1 \input texinfo @c -*-texinfo-*-
3 @setfilename automake.info
10 @dircategory GNU programming tools
12 * automake: (automake). Making Makefile.in's
15 @dircategory Individual utilities
17 * aclocal: (automake)Invoking aclocal. Generating aclocal.m4
21 This file documents GNU automake @value{VERSION}
23 Copyright 1995, 1996, 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
25 Permission is granted to make and distribute verbatim copies of
26 this manual provided the copyright notice and this permission notice
27 are preserved on all copies.
30 Permission is granted to process this file through TeX and print the
31 results, provided the printed document carries copying permission
32 notice identical to this one except for the removal of this paragraph
36 Permission is granted to copy and distribute modified versions of this
37 manual under the conditions for verbatim copying, provided that the entire
38 resulting derived work is distributed under the terms of a permission
39 notice identical to this one.
41 Permission is granted to copy and distribute translations of this manual
42 into another language, under the above conditions for modified versions,
43 except that this permission notice may be stated in a translation approved
50 @subtitle For version @value{VERSION}, @value{UPDATED}
51 @author David MacKenzie and Tom Tromey
54 @vskip 0pt plus 1filll
55 Copyright @copyright{} 1995, 1996, 2000, 2001 Free Software Foundation, Inc.
57 This is the first edition of the GNU Automake documentation,@*
58 and is consistent with GNU Automake @value{VERSION}.@*
60 Published by the Free Software Foundation @*
61 59 Temple Place - Suite 330, @*
62 Boston, MA 02111-1307 USA @*
64 Permission is granted to make and distribute verbatim copies of
65 this manual provided the copyright notice and this permission notice
66 are preserved on all copies.
68 Permission is granted to copy and distribute modified versions of this
69 manual under the conditions for verbatim copying, provided that the entire
70 resulting derived work is distributed under the terms of a permission
71 notice identical to this one.
73 Permission is granted to copy and distribute translations of this manual
74 into another language, under the above conditions for modified versions,
75 except that this permission notice may be stated in a translation
76 approved by the Free Software Foundation.
79 @c Define an index of configure output variables.
81 @c Define an index of configure variables.
83 @c Define an index of options.
85 @c Define an index of targets.
87 @c Define an index of commands.
90 @c Put the macros and variables into their own index.
91 @c @syncodeindex fn cp
96 @c Put everything else into one index (arbitrarily chosen to be the concept index).
102 @node Top, Introduction, (dir), (dir)
103 @comment node-name, next, previous, up
106 This file documents the GNU Automake package. Automake is a program
107 which creates GNU standards-compliant Makefiles from template files.
108 This edition documents version @value{VERSION}.
111 * Introduction:: Automake's purpose
112 * Generalities:: General ideas
113 * Examples:: Some example packages
114 * Invoking Automake:: Creating a Makefile.in
115 * configure:: Scanning configure.ac or configure.in
116 * Top level:: The top-level Makefile.am
117 * Alternative:: An alternative approach to subdirectories
118 * Rebuilding:: Automatic rebuilding of Makefile
119 * Programs:: Building programs and libraries
120 * Other objects:: Other derived objects
121 * Other GNU Tools:: Other GNU Tools
122 * Documentation:: Building documentation
123 * Install:: What gets installed
124 * Clean:: What gets cleaned
125 * Dist:: What goes in a distribution
126 * Tests:: Support for test suites
127 * Options:: Changing Automake's behavior
128 * Miscellaneous:: Miscellaneous rules
129 * Include:: Including extra files in an Automake template.
130 * Conditionals:: Conditionals
131 * Gnits:: The effect of @code{--gnu} and @code{--gnits}
132 * Cygnus:: The effect of @code{--cygnus}
133 * Extending:: Extending Automake
134 * Distributing:: Distributing the Makefile.in
135 * Macro and Variable Index::
142 @node Introduction, Generalities, Top, Top
143 @chapter Introduction
145 Automake is a tool for automatically generating @file{Makefile.in}s from
146 files called @file{Makefile.am}. Each @file{Makefile.am} is basically a
147 series of @code{make} macro definitions (with rules being thrown in
148 occasionally). The generated @file{Makefile.in}s are compliant with the
149 GNU Makefile standards.
151 @cindex GNU Makefile standards
153 The GNU Makefile Standards Document
154 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
155 is long, complicated, and subject to change. The goal of Automake is to
156 remove the burden of Makefile maintenance from the back of the
157 individual GNU maintainer (and put it on the back of the Automake
160 The typical Automake input file is simply a series of macro definitions.
161 Each such file is processed to create a @file{Makefile.in}. There
162 should generally be one @file{Makefile.am} per directory of a project.
164 @cindex Constraints of Automake
165 @cindex Automake constraints
167 Automake does constrain a project in certain ways; for instance it
168 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
169 autoconf, The Autoconf Manual}), and enforces certain restrictions on
170 the @file{configure.in} contents@footnote{Autoconf 2.50 promotes
171 @file{configure.ac} over @file{configure.in}. The rest of this
172 documentation will refer to @file{configure.in} as this use is not yet
173 spread, but Automake supports @file{configure.ac} too.}.
175 @cindex Automake requirements
176 @cindex Requirements, Automake
178 Automake requires @code{perl} in order to generate the
179 @file{Makefile.in}s. However, the distributions created by Automake are
180 fully GNU standards-compliant, and do not require @code{perl} in order
183 @cindex BUGS, reporting
184 @cindex Reporting BUGS
185 @cindex E-mail, bug reports
187 Mail suggestions and bug reports for Automake to
188 @email{bug-automake@@gnu.org}.
191 @node Generalities, Examples, Introduction, Top
192 @chapter General ideas
194 The following sections cover a few basic ideas that will help you
195 understand how Automake works.
198 * General Operation:: General operation of Automake
199 * Strictness:: Standards conformance checking
200 * Uniform:: The Uniform Naming Scheme
201 * Canonicalization:: How derived variables are named
202 * User Variables:: Variables reserved for the user
203 * Auxiliary Programs:: Programs automake might require
207 @node General Operation, Strictness, Generalities, Generalities
208 @section General Operation
210 Automake works by reading a @file{Makefile.am} and generating a
211 @file{Makefile.in}. Certain macros and targets defined in the
212 @file{Makefile.am} instruct Automake to generate more specialized code;
213 for instance, a @samp{bin_PROGRAMS} macro definition will cause targets
214 for compiling and linking programs to be generated.
216 @cindex Non-standard targets
217 @cindex cvs-dist, non-standard example
220 The macro definitions and targets in the @file{Makefile.am} are copied
221 verbatim into the generated file. This allows you to add arbitrary code
222 into the generated @file{Makefile.in}. For instance the Automake
223 distribution includes a non-standard @code{cvs-dist} target, which the
224 Automake maintainer uses to make distributions from his source control
227 @cindex GNU make extensions
229 Note that GNU make extensions are not recognized by Automake. Using
230 such extensions in a @file{Makefile.am} will lead to errors or confusing
233 Automake tries to group comments with adjoining targets and macro
234 definitions in an intelligent way.
236 @cindex Make targets, overriding
237 @cindex Overriding make targets
239 A target defined in @file{Makefile.am} generally overrides any such
240 target of a similar name that would be automatically generated by
241 @code{automake}. Although this is a supported feature, it is generally
242 best to avoid making use of it, as sometimes the generated rules are
245 @cindex Macros, overriding
246 @cindex Overriding make macros
248 Similarly, a macro defined in @file{Makefile.am} will override any
249 definition of the macro that @code{automake} would ordinarily create.
250 This feature is more often useful than the ability to override a target
251 definition. Be warned that many of the macros generated by
252 @code{automake} are considered to be for internal use only, and their
253 names might change in future releases.
255 @cindex Recursive operation of Automake
256 @cindex Automake, recursive operation
257 @cindex Example of recursive operation
259 When examining a macro definition, Automake will recursively examine
260 macros referenced in the definition. For example, if Automake is
261 looking at the content of @code{foo_SOURCES} in this snippet
265 foo_SOURCES = c.c $(xs)
268 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
269 contents of @code{foo_SOURCES}.
271 @cindex ## (special Automake comment)
272 @cindex Special Automake comment
273 @cindex Comment, special to Automake
275 Automake also allows a form of comment which is @emph{not} copied into
276 the output; all lines beginning with @samp{##} (leading spaces allowed)
277 are completely ignored by Automake.
279 It is customary to make the first line of @file{Makefile.am} read:
281 @cindex Makefile.am, first line
282 @cindex First line of Makefile.am
285 ## Process this file with automake to produce Makefile.in
288 @c FIXME discuss putting a copyright into Makefile.am here? I would but
289 @c I don't know quite what to say.
291 @c FIXME document customary ordering of Makefile.am here!
294 @node Strictness, Uniform, General Operation, Generalities
297 @cindex Non-GNU packages
299 While Automake is intended to be used by maintainers of GNU packages, it
300 does make some effort to accommodate those who wish to use it, but do
301 not want to use all the GNU conventions.
303 @cindex Strictness, defined
304 @cindex Strictness, foreign
305 @cindex foreign strictness
306 @cindex Strictness, gnu
307 @cindex gnits strictness
308 @cindex Strictness, gnits
309 @cindex gnits strictness
311 To this end, Automake supports three levels of @dfn{strictness}---the
312 strictness indicating how stringently Automake should check standards
315 The valid strictness levels are:
319 Automake will check for only those things which are absolutely
320 required for proper operations. For instance, whereas GNU standards
321 dictate the existence of a @file{NEWS} file, it will not be required in
322 this mode. The name comes from the fact that Automake is intended to be
323 used for GNU programs; these relaxed rules are not the standard mode of
327 Automake will check---as much as possible---for compliance to the GNU
328 standards for packages. This is the default.
331 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
332 standards}. These are based on the GNU standards, but are even more
333 detailed. Unless you are a Gnits standards contributor, it is
334 recommended that you avoid this option until such time as the Gnits
335 standard is actually published (which may never happen).
338 For more information on the precise implications of the strictness
339 level, see @ref{Gnits}.
342 @node Uniform, Canonicalization, Strictness, Generalities
343 @section The Uniform Naming Scheme
345 @cindex Uniform naming scheme
347 Automake macros (from here on referred to as @emph{variables}) generally
348 follow a @dfn{uniform naming scheme} that makes it easy to decide how
349 programs (and other derived objects) are built, and how they are
350 installed. This scheme also supports @code{configure} time
351 determination of what should be built.
353 @cindex _PROGRAMS primary variable
354 @cindex PROGRAMS primary variable
355 @cindex Primary variable, PROGRAMS
357 @cindex Primary variable, defined
359 At @code{make} time, certain variables are used to determine which
360 objects are to be built. These variables are called @dfn{primary
361 variables}. For instance, the primary variable @code{PROGRAMS} holds a
362 list of programs which are to be compiled and linked.
365 @cindex pkglibdir, defined
366 @cindex pkgincludedir, defined
367 @cindex pkgdatadir, defined
370 @vindex pkgincludedir
373 A different set of variables is used to decide where the built objects
374 should be installed. These variables are named after the primary
375 variables, but have a prefix indicating which standard directory should
376 be used as the installation directory. The standard directory names are
377 given in the GNU standards (@pxref{Directory Variables, , , standards,
378 The GNU Coding Standards}). Automake extends this list with
379 @code{pkglibdir}, @code{pkgincludedir}, and @code{pkgdatadir}; these are
380 the same as the non-@samp{pkg} versions, but with @samp{@@PACKAGE@@}
381 appended. For instance, @code{pkglibdir} is defined as
382 @code{$(libdir)/@@PACKAGE@@}.
385 @cindex EXTRA_, prepending
387 For each primary, there is one additional variable named by prepending
388 @samp{EXTRA_} to the primary name. This variable is used to list
389 objects which may or may not be built, depending on what
390 @code{configure} decides. This variable is required because Automake
391 must statically know the entire list of objects that may be built in
392 order to generate a @file{Makefile.in} that will work in all cases.
394 @cindex EXTRA_PROGRAMS, defined
395 @cindex Example, EXTRA_PROGRAMS
398 For instance, @code{cpio} decides at configure time which programs are
399 built. Some of the programs are installed in @code{bindir}, and some
400 are installed in @code{sbindir}:
403 EXTRA_PROGRAMS = mt rmt
404 bin_PROGRAMS = cpio pax
405 sbin_PROGRAMS = @@MORE_PROGRAMS@@
408 Defining a primary variable without a prefix (e.g. @code{PROGRAMS}) is
411 Note that the common @samp{dir} suffix is left off when constructing the
412 variable names; thus one writes @samp{bin_PROGRAMS} and not
413 @samp{bindir_PROGRAMS}.
415 Not every sort of object can be installed in every directory. Automake
416 will flag those attempts it finds in error. Automake will also diagnose
417 obvious misspellings in directory names.
419 @cindex Extending list of installation directories
420 @cindex Installation directories, extending list
422 Sometimes the standard directories---even as augmented by Automake---
423 are not enough. In particular it is sometimes useful, for clarity, to
424 install objects in a subdirectory of some predefined directory. To this
425 end, Automake allows you to extend the list of possible installation
426 directories. A given prefix (e.g. @samp{zar}) is valid if a variable of
427 the same name with @samp{dir} appended is defined (e.g. @code{zardir}).
429 @cindex HTML support, example
431 For instance, until HTML support is part of Automake, you could use this
432 to install raw HTML documentation:
435 htmldir = $(prefix)/html
436 html_DATA = automake.html
439 @cindex noinst primary prefix, definition
441 The special prefix @samp{noinst} indicates that the objects in question
442 should not be installed at all.
444 @cindex check primary prefix, definition
446 The special prefix @samp{check} indicates that the objects in question
447 should not be built until the @code{make check} command is run.
449 Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
450 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
451 @samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
463 Some primaries also allow additional prefixes which control other
464 aspects of @code{automake}'s behavior. The currently defined prefixes
465 are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes
469 @node Canonicalization, User Variables, Uniform, Generalities
470 @section How derived variables are named
472 @cindex canonicalizing Automake macros
474 Sometimes a Makefile variable name is derived from some text the user
475 supplies. For instance, program names are rewritten into Makefile macro
476 names. Automake canonicalizes this text, so that it does not have to
477 follow Makefile macro naming rules. All characters in the name except
478 for letters, numbers, the strudel (@@), and the underscore are turned into
479 underscores when making macro references. For example, if your program
480 is named @code{sniff-glue}, the derived variable name would be
481 @code{sniff_glue_SOURCES}, not @code{sniff-glue_SOURCES}. The strudel
482 is an addition since Automake 1.4c, to make the use of Autoconf
483 substitutions in macro names less obfuscating.
486 @node User Variables, Auxiliary Programs, Canonicalization, Generalities
487 @section Variables reserved for the user
489 @cindex variables, reserved for the user
490 @cindex user variables
492 Some @code{Makefile} variables are reserved by the GNU Coding Standards
493 for the use of the ``user'' -- the person building the package. For
494 instance, @code{CFLAGS} is one such variable.
496 Sometimes package developers are tempted to set user variables such as
497 @code{CFLAGS} because it appears to make their job easier -- they don't
498 have to introduce a second variable into every target.
500 However, the package itself should never set a user variable,
501 particularly not to include switches which are required for proper
502 compilation of the package. Since these variables are documented as
503 being for the package builder, that person rightfully expects to be able
504 to override any of these variables at build time.
506 To get around this problem, automake introduces an automake-specific
507 shadow variable for each user flag variable. (Shadow variables are not
508 introduced for variables like @code{CC}, where they would make no
509 sense.) The shadow variable is named by prepending @samp{AM_} to the
510 user variable's name. For instance, the shadow variable for
511 @code{YFLAGS} is @code{AM_YFLAGS}.
514 @node Auxiliary Programs, , User Variables, Generalities
515 @section Programs automake might require
517 @cindex Programs, auxiliary
518 @cindex Auxiliary programs
520 Automake sometimes requires helper programs so that the generated
521 @file{Makefile} can do its work properly. There are a fairly large
522 number of them, and we list them here.
527 These two files are used by the automatic de-ANSI-fication support
531 This is a wrapper for compilers which don't accept both @samp{-c} and
532 @samp{-o} at the same time. It is only used when absolutely required.
533 Such compilers are rare.
537 These programs compute the canonical triplets for the given build, host,
538 or target architecture.
541 This program understands how to run a compiler so that it will generate
542 not only the desired output but also dependency information which is
543 then used by the automatic dependency tracking feature.
546 This program is used to byte-compile Emacs Lisp code.
549 This is a replacement for the @code{install} program which works on
550 platforms where @code{install} is unavailable or unusable.
553 This script is used to generate a @file{version.texi} file. It examines
554 a file and prints some date information about it.
557 This wraps a number of programs which are typically only required by
558 maintainers. If the program in question doesn't exist, @code{missing}
559 prints an informative warning and attempts to fix things so that the
563 This works around the fact that @code{mkdir -p} is not portable.
566 This is used to byte-compile Python scripts.
569 Not a program, this file is required for @code{make dvi} to work when
570 Texinfo sources are in the package.
573 This program wraps @code{lex} and @code{yacc} and ensures that, for
574 instance, multiple @code{yacc} instances can be invoked in a single
575 directory in parallel.
580 @node Examples, Invoking Automake, Generalities, Top
581 @chapter Some example packages
584 * Complete:: A simple example, start to finish
585 * Hello:: A classic program
586 * etags:: Building etags and ctags
590 @node Complete, Hello, Examples, Examples
591 @section A simple example, start to finish
593 @cindex Complete example
595 Let's suppose you just finished writing @code{zardoz}, a program to make
596 your head float from vortex to vortex. You've been using Autoconf to
597 provide a portability framework, but your @file{Makefile.in}s have been
598 ad-hoc. You want to make them bulletproof, so you turn to Automake.
600 @cindex AM_INIT_AUTOMAKE, example use
602 The first step is to update your @file{configure.in} to include the
603 commands that @code{automake} needs. The way to do this is to add an
604 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
607 AM_INIT_AUTOMAKE(zardoz, 1.0)
610 Since your program doesn't have any complicating factors (e.g., it
611 doesn't use @code{gettext}, it doesn't want to build a shared library),
612 you're done with this part. That was easy!
614 @cindex aclocal program, introduction
615 @cindex aclocal.m4, preexisting
616 @cindex acinclude.m4, defined
618 Now you must regenerate @file{configure}. But to do that, you'll need
619 to tell @code{autoconf} how to find the new macro you've used. The
620 easiest way to do this is to use the @code{aclocal} program to generate
621 your @file{aclocal.m4} for you. But wait... you already have an
622 @file{aclocal.m4}, because you had to write some hairy macros for your
623 program. The @code{aclocal} program lets you put your own macros into
624 @file{acinclude.m4}, so simply rename and then run:
627 mv aclocal.m4 acinclude.m4
632 @cindex zardoz example
634 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
635 Since @code{zardoz} is a user program, you want to install it where the
636 rest of the user programs go. Additionally, @code{zardoz} has some
637 Texinfo documentation. Your @file{configure.in} script uses
638 @code{AC_REPLACE_FUNCS}, so you need to link against @samp{@@LIBOBJS@@}.
639 So here's what you'd write:
642 bin_PROGRAMS = zardoz
643 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
644 zardoz_LDADD = @@LIBOBJS@@
646 info_TEXINFOS = zardoz.texi
649 Now you can run @code{automake --add-missing} to generate your
650 @file{Makefile.in} and grab any auxiliary files you might need, and
654 @node Hello, etags, Complete, Examples
655 @section A classic program
657 @cindex Example, GNU Hello
658 @cindex Hello example
659 @cindex GNU Hello, example
661 @uref{ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz, GNU hello} is
662 renowned for its classic simplicity and versatility. This section shows
663 how Automake could be used with the GNU Hello package. The examples
664 below are from the latest beta version of GNU Hello, but with all of the
665 maintainer-only code stripped out, as well as all copyright comments.
667 Of course, GNU Hello is somewhat more featureful than your traditional
668 two-liner. GNU Hello is internationalized, does option processing, and
669 has a manual and a test suite.
671 @cindex configure.in, from GNU Hello
672 @cindex GNU Hello, configure.in
673 @cindex Hello, configure.in
675 Here is the @file{configure.in} from GNU Hello:
678 dnl Process this file with autoconf to produce a configure script.
680 AM_INIT_AUTOMAKE(hello, 1.3.11)
681 AM_CONFIG_HEADER(config.h)
683 dnl Set of available languages.
684 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
686 dnl Checks for programs.
690 dnl Checks for libraries.
692 dnl Checks for header files.
694 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
696 dnl Checks for library functions.
699 dnl Check for st_blksize in struct stat
702 dnl internationalization macros
704 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
705 src/Makefile tests/Makefile tests/hello],
706 [chmod +x tests/hello])
709 The @samp{AM_} macros are provided by Automake (or the Gettext library);
710 the rest are standard Autoconf macros.
713 The top-level @file{Makefile.am}:
716 EXTRA_DIST = BUGS ChangeLog.O
717 SUBDIRS = doc intl po src tests
720 As you can see, all the work here is really done in subdirectories.
722 The @file{po} and @file{intl} directories are automatically generated
723 using @code{gettextize}; they will not be discussed here.
725 @cindex Texinfo file handling example
726 @cindex Example, handling Texinfo files
728 In @file{doc/Makefile.am} we see:
731 info_TEXINFOS = hello.texi
732 hello_TEXINFOS = gpl.texi
735 This is sufficient to build, install, and distribute the GNU Hello
738 @cindex Regression test example
739 @cindex Example, regression test
741 Here is @file{tests/Makefile.am}:
745 EXTRA_DIST = hello.in testdata
748 The script @file{hello} is generated by @code{configure}, and is the
749 only test case. @code{make check} will run this test.
751 @cindex INCLUDES, example usage
753 Last we have @file{src/Makefile.am}, where all the real work is done:
757 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
758 hello_LDADD = @@INTLLIBS@@ @@ALLOCA@@
759 localedir = $(datadir)/locale
760 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
764 @node etags, , Hello, Examples
765 @section Building etags and ctags
767 @cindex Example, ctags and etags
768 @cindex ctags Example
769 @cindex etags Example
771 Here is another, trickier example. It shows how to generate two
772 programs (@code{ctags} and @code{etags}) from the same source file
773 (@file{etags.c}). The difficult part is that each compilation of
774 @file{etags.c} requires different @code{cpp} flags.
777 bin_PROGRAMS = etags ctags
779 ctags_LDADD = ctags.o
782 $(COMPILE) -DETAGS_REGEXPS -c etags.c
785 $(COMPILE) -DCTAGS -o ctags.o -c etags.c
788 Note that @code{ctags_SOURCES} is defined to be empty---that way no
789 implicit value is substituted. The implicit value, however, is used to
790 generate @code{etags} from @file{etags.o}.
792 @code{ctags_LDADD} is used to get @file{ctags.o} into the link line.
793 @code{ctags_DEPENDENCIES} is generated by Automake.
795 The above rules won't work if your compiler doesn't accept both
796 @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
797 bogus dependency (to avoid problems with a parallel @code{make}):
800 etags.o: etags.c ctags.o
801 $(COMPILE) -DETAGS_REGEXPS -c etags.c
804 $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
807 Also, these explicit rules do not work if the de-ANSI-fication feature
808 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
812 etags._o: etags._c ctags.o
813 $(COMPILE) -DETAGS_REGEXPS -c etags.c
816 $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
819 As it turns out, there is also a much easier way to do this same task.
820 Some of the above techniques are useful enough that we've kept the
821 example in the manual. However if you were to build @code{etags} and
822 @code{ctags} in real life, you would probably use per-program
823 compilation flags, like so:
826 bin_PROGRAMS = ctags etags
828 ctags_SOURCES = etags.c
829 ctags_CFLAGS = -DCTAGS
831 etags_SOURCES = etags.c
832 etags_CFLAGS = -DETAGS_REGEXPS
835 In this case Automake will cause @file{etags.c} to be compiled twice,
836 with different flags. De-ANSI-fication will work automatically. In
837 this instance, the names of the object files would be chosen by
838 automake; they would be @file{ctags-etags.c} and @file{etags-etags.o}.
839 (The name of the object files rarely matters.)
842 @node Invoking Automake, configure, Examples, Top
843 @chapter Creating a @file{Makefile.in}
845 @cindex Multiple configure.in files
846 @cindex Invoking Automake
847 @cindex Automake, invoking
849 To create all the @file{Makefile.in}s for a package, run the
850 @code{automake} program in the top level directory, with no arguments.
851 @code{automake} will automatically find each appropriate
852 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
853 and generate the corresponding @file{Makefile.in}. Note that
854 @code{automake} has a rather simplistic view of what constitutes a
855 package; it assumes that a package has only one @file{configure.in}, at
856 the top. If your package has multiple @file{configure.in}s, then you
857 must run @code{automake} in each directory holding a
860 You can optionally give @code{automake} an argument; @file{.am} is
861 appended to the argument and the result is used as the name of the input
862 file. This feature is generally only used to automatically rebuild an
863 out-of-date @file{Makefile.in}. Note that @code{automake} must always
864 be run from the topmost directory of a project, even if being used to
865 regenerate the @file{Makefile.in} in some subdirectory. This is
866 necessary because @code{automake} must scan @file{configure.in}, and
867 because @code{automake} uses the knowledge that a @file{Makefile.in} is
868 in a subdirectory to change its behavior in some cases.
870 @cindex Automake options
871 @cindex Options, Automake
873 @code{automake} accepts the following options:
875 @cindex Extra files distributed with Automake
876 @cindex Files distributed with Automake
883 @opindex --add-missing
884 Automake requires certain common files to exist in certain situations;
885 for instance @file{config.guess} is required if @file{configure.in} runs
886 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
887 files; this option will cause the missing ones to be automatically added
888 to the package, whenever possible. In general if Automake tells you a
889 file is missing, try using this option. By default Automake tries to
890 make a symbolic link pointing to its own copy of the missing file; this
891 can be changed with @code{--copy}.
893 @item --libdir=@var{dir}
895 Look for Automake data files in directory @var{dir} instead of in the
896 installation directory. This is typically used for debugging.
902 When used with @code{--add-missing}, causes installed files to be
903 copied. The default is to make a symbolic link.
907 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
908 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
912 @itemx --force-missing
913 @opindex --force-missing
914 When used with @code{--add-missing}, causes standard files to be rebuilt
915 even if they already exist in the source tree. This involves removing
916 the file from the source tree before creating the new symlink (or, with
917 @code{--copy}, copying the new file).
921 Set the global strictness to @samp{foreign}. For more information, see
926 Set the global strictness to @samp{gnits}. For more information, see
931 Set the global strictness to @samp{gnu}. For more information, see
932 @ref{Gnits}. This is the default strictness.
936 Print a summary of the command line options and exit.
941 This disables the dependency tracking feature; see @ref{Dependencies}.
944 @opindex --include-deps
945 This enables the dependency tracking feature. This feature is enabled
946 by default. This option is provided for historical reasons only and
947 probably should not be used.
951 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
952 @file{configure.in}. This option causes it to only update those
953 @file{Makefile.in}s which are out of date with respect to one of their
957 @itemx --output-dir=@var{dir}
959 @opindex --output-dir
960 Put the generated @file{Makefile.in} in the directory @var{dir}.
961 Ordinarily each @file{Makefile.in} is created in the directory of the
962 corresponding @file{Makefile.am}. This option is used when making
969 Cause Automake to print information about which files are being read or
974 Print the version number of Automake and exit.
978 @node configure, Top level, Invoking Automake, Top
979 @chapter Scanning @file{configure.in}
981 @cindex configure.in, scanning
982 @cindex Scanning configure.in
984 Automake scans the package's @file{configure.in} to determine certain
985 information about the package. Some @code{autoconf} macros are required
986 and some variables must be defined in @file{configure.in}. Automake
987 will also use information from @file{configure.in} to further tailor its
990 Automake also supplies some Autoconf macros to make the maintenance
991 easier. These macros can automatically be put into your
992 @file{aclocal.m4} using the @code{aclocal} program.
995 * Requirements:: Configuration requirements
996 * Optional:: Other things Automake recognizes
997 * Invoking aclocal:: Auto-generating aclocal.m4
998 * Macros:: Autoconf macros supplied with Automake
999 * Extending aclocal:: Writing your own aclocal macros
1003 @node Requirements, Optional, configure, configure
1004 @section Configuration requirements
1006 @cindex Automake requirements
1007 @cindex Requirements of Automake
1009 The one real requirement of Automake is that your @file{configure.in}
1010 call @code{AM_INIT_AUTOMAKE}. This macro does several things which are
1011 required for proper Automake operation.
1012 @cvindex AM_INIT_AUTOMAKE
1014 Here are the other macros which Automake requires but which are not run
1015 by @code{AM_INIT_AUTOMAKE}:
1017 @cindex AC_OUTPUT, scanning
1021 Automake uses this to determine which files to create (@pxref{Output, ,
1022 Creating Output Files, autoconf, The Autoconf Manual}). Listed files
1023 named @code{Makefile} are treated as @file{Makefile}s. Other listed
1024 files are treated differently. Currently the only difference is that a
1025 @file{Makefile} is removed by @code{make distclean}, while other files
1026 are removed by @code{make clean}.
1027 @c FIXME: this is in violation of standards!
1031 You may need the following macros in some conditions, even though they
1035 @item AC_CHECK_TOOL([STRIP],[strip])
1036 @cindex STRIP, how to setup
1037 @cindex install-strip and STRIP
1038 @cvindex AC_CHECK_TOOL([STRIP],[strip])
1039 Installed binaries are usually stripped using @code{strip} when you run
1040 @code{make install-strip}. However @code{strip} might not be the
1041 right tool to use in cross-compilation environments, therefore
1042 Automake will honor the @code{STRIP} environment variable to overrule
1043 the program used to perform stripping. Automake will not set @code{STRIP}
1044 itself. If your package is not setup for cross-compilation you do not
1045 have to care (@code{strip} is ok), otherwise you can set @code{STRIP}
1046 automatically by calling @code{AC_CHECK_TOOL([STRIP],[strip])} from
1047 your @file{configure.in}.
1051 @node Optional, Invoking aclocal, Requirements, configure
1052 @section Other things Automake recognizes
1054 @cindex Macros Automake recognizes
1055 @cindex Recognized macros by Automake
1057 Automake will also recognize the use of certain macros and tailor the
1058 generated @file{Makefile.in} appropriately. Currently recognized macros
1059 and their effects are:
1062 @item AC_CONFIG_HEADER
1063 Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar
1064 to @code{AC_CONFIG_HEADER} (@pxref{Configuration Headers, ,
1065 Configuration Header Files, autoconf, The Autoconf Manual}), but does
1066 some useful Automake-specific work.
1067 @cvindex AC_CONFIG_HEADER
1069 @item AC_CONFIG_AUX_DIR
1070 Automake will look for various helper scripts, such as
1071 @file{mkinstalldirs}, in the directory named in this macro invocation.
1072 If not seen, the scripts are looked for in their @samp{standard}
1073 locations (either the top source directory, or in the source directory
1074 corresponding to the current @file{Makefile.am}, whichever is
1075 appropriate). @xref{Input, , Finding `configure' Input, autoconf, The
1077 @cvindex AC_CONFIG_AUX_DIR
1078 FIXME: give complete list of things looked for in this directory
1081 Automake will insert definitions for the variables defined by
1082 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
1083 or library. @xref{System Services, , System Services, autoconf, The
1085 @cvindex AC_PATH_XTRA
1087 @item AC_CANONICAL_HOST
1088 @itemx AC_CHECK_TOOL
1089 Automake will ensure that @file{config.guess} and @file{config.sub}
1090 exist. Also, the @file{Makefile} variables @samp{host_alias} and
1091 @samp{host_triplet} are introduced. See both @ref{Canonicalizing, ,
1092 Getting the Canonical System Type, autoconf, The Autoconf Manual}, and
1093 @ref{Generic Programs, , Generic Program Checks, autoconf, The Autoconf
1095 @c fixme xref autoconf docs.
1096 @cvindex AC_CANONICAL_HOST
1097 @cvindex AC_CHECK_TOOL
1099 @vindex host_triplet
1101 @item AC_CANONICAL_SYSTEM
1102 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
1103 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
1104 @xref{Canonicalizing, , Getting the Canonical System Type, autoconf, The
1106 @cvindex AC_CANONICAL_SYSTEM
1108 @vindex target_alias
1110 @item AC_FUNC_ALLOCA
1111 @itemx AC_FUNC_GETLOADAVG
1112 @itemx AC_FUNC_MEMCMP
1113 @itemx AC_STRUCT_ST_BLOCKS
1114 @itemx AC_FUNC_FNMATCH
1115 @itemx AC_FUNC_MKTIME
1116 @itemx AM_FUNC_STRTOD
1117 @itemx AC_REPLACE_FUNCS
1118 @itemx AC_REPLACE_GNU_GETOPT
1119 @itemx AM_WITH_REGEX
1120 Automake will ensure that the appropriate dependencies are generated for
1121 the objects corresponding to these macros. Also, Automake will verify
1122 that the appropriate source files are part of the distribution. Note
1123 that Automake does not come with any of the C sources required to use
1124 these macros, so @code{automake -a} will not install the sources.
1125 @xref{A Library}, for more information. Also, see @ref{Particular
1126 Functions, , Particular Function Checks, autoconf, The Autoconf Manual}.
1127 @cvindex AC_FUNC_ALLOCA
1128 @cvindex AC_FUNC_GETLOADAVG
1129 @cvindex AC_FUNC_MEMCMP
1130 @cvindex AC_STRUCT_ST_BLOCKS
1131 @cvindex AC_FUNC_FNMATCH
1132 @cvindex AC_FUNC_FNMATCH
1133 @cvindex AC_REPLACE_FUNCS
1134 @cvindex AC_REPLACE_GNU_GETOPT
1135 @cvindex AM_FUNC_STRTOD
1136 @cvindex AM_WITH_REGEX
1137 @cvindex AC_FUNC_MKTIME
1140 Automake will detect statements which put @file{.o} files into
1141 @code{LIBOBJS}, and will treat these additional files as if they were
1142 discovered via @code{AC_REPLACE_FUNCS}. @xref{Generic Functions, ,
1143 Generic Function Checks, autoconf, The Autoconf Manual}.
1146 @item AC_PROG_RANLIB
1147 This is required if any libraries are built in the package.
1148 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1150 @cvindex AC_PROG_RANLIB
1153 This is required if any C++ source is included. @xref{Particular
1154 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1155 @cvindex AC_PROG_CXX
1158 This is required if any Fortran 77 source is included. This macro is
1159 distributed with Autoconf version 2.13 and later. @xref{Particular
1160 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1161 @cvindex AC_PROG_F77
1163 @item AC_F77_LIBRARY_LDFLAGS
1164 This is required for programs and shared libraries that are a mixture of
1165 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
1166 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
1167 @cvindex AC_F77_LIBRARY_LDFLAGS
1169 @item AC_PROG_LIBTOOL
1170 Automake will turn on processing for @code{libtool} (@pxref{Top, ,
1171 Introduction, libtool, The Libtool Manual}).
1172 @cvindex AC_PROG_LIBTOOL
1175 If a Yacc source file is seen, then you must either use this macro or
1176 define the variable @samp{YACC} in @file{configure.in}. The former is
1177 preferred (@pxref{Particular Programs, , Particular Program Checks,
1178 autoconf, The Autoconf Manual}).
1179 @cvindex AC_PROG_YACC
1182 @item AC_DECL_YYTEXT
1183 This macro is required if there is Lex source in the package.
1184 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1186 @cvindex AC_DECL_YYTEXT
1189 If a Lex source file is seen, then this macro must be used.
1190 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1192 @cvindex AC_PROG_LEX
1194 @item AM_C_PROTOTYPES
1195 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
1196 @cvindex AM_C_PROTOTYPES
1198 @item AM_GNU_GETTEXT
1199 This macro is required for packages which use GNU gettext
1200 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1201 this macro it ensures that the package meets some of gettext's
1203 @cvindex AM_GNU_GETTEXT
1205 @item AM_MAINTAINER_MODE
1206 @opindex --enable-maintainer-mode
1207 This macro adds a @samp{--enable-maintainer-mode} option to
1208 @code{configure}. If this is used, @code{automake} will cause
1209 @samp{maintainer-only} rules to be turned off by default in the
1210 generated @file{Makefile.in}s. This macro is disallowed in @samp{Gnits}
1211 mode (@pxref{Gnits}). This macro defines the @samp{MAINTAINER_MODE}
1212 conditional, which you can use in your own @file{Makefile.am}.
1213 @cvindex AM_MAINTAINER_MODE
1216 @itemx AC_CHECK_TOOL
1217 @itemx AC_CHECK_PROG
1218 @itemx AC_CHECK_PROGS
1220 @itemx AC_PATH_PROGS
1221 For each of these macros, the first argument is automatically defined as
1222 a variable in each generated @file{Makefile.in}. @xref{Setting Output
1223 Variables, , Setting Output Variables, autoconf, The Autoconf Manual},
1224 and @ref{Generic Programs, , Generic Program Checks, autoconf, The
1227 @cvindex AC_CHECK_TOOL
1228 @cvindex AC_CHECK_PROG
1229 @cvindex AC_CHECK_PROGS
1230 @cvindex AC_PATH_PROG
1231 @cvindex AC_PATH_PROGS
1236 @node Invoking aclocal, Macros, Optional, configure
1237 @section Auto-generating aclocal.m4
1239 @cindex Invoking aclocal
1240 @cindex aclocal, Invoking
1242 Automake includes a number of Autoconf macros which can be used in your
1243 package; some of them are actually required by Automake in certain
1244 situations. These macros must be defined in your @file{aclocal.m4};
1245 otherwise they will not be seen by @code{autoconf}.
1247 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1248 files based on the contents of @file{configure.in}. This provides a
1249 convenient way to get Automake-provided macros, without having to
1250 search around. Also, the @code{aclocal} mechanism is extensible for use
1253 At startup, @code{aclocal} scans all the @file{.m4} files it can find,
1254 looking for macro definitions. Then it scans @file{configure.in}. Any
1255 mention of one of the macros found in the first step causes that macro,
1256 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1258 The contents of @file{acinclude.m4}, if it exists, are also
1259 automatically included in @file{aclocal.m4}. This is useful for
1260 incorporating local macros into @file{configure}.
1262 @code{aclocal} tries to be smart about looking for new @code{AC_DEFUN}s
1263 in the files it scans. It will warn if it finds duplicates. It also
1264 tries to copy the full text of the scanned file into @file{aclocal.m4},
1265 including both @samp{#} and @samp{dnl} comments. If you want to make a
1266 comment which will be completely ignored by @code{aclocal}, use
1267 @samp{##} as the comment leader.
1269 @code{aclocal} accepts the following options:
1272 @item --acdir=@var{dir}
1274 Look for the macro files in @var{dir} instead of the installation
1275 directory. This is typically used for debugging.
1279 Print a summary of the command line options and exit.
1283 Add the directory @var{dir} to the list of directories searched for
1286 @item --output=@var{file}
1288 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1290 @item --print-ac-dir
1291 @opindex --print-ac-dir
1292 Prints the name of the directory which @code{aclocal} will search to
1293 find the @file{.m4} files. When this option is given, normal processing
1294 is suppressed. This option can be used by a package to determine where
1295 to install a macro file.
1299 Print the names of the files it examines.
1303 Print the version number of Automake and exit.
1307 @node Macros, Extending aclocal, Invoking aclocal, configure
1308 @section Autoconf macros supplied with Automake
1310 @c consider generating this node automatically from m4 files.
1313 @item AM_CONFIG_HEADER
1314 Automake will generate rules to automatically regenerate the config
1315 header. If you do use this macro, you must create the file
1316 @file{stamp-h.in} in your source directory. It can be empty.
1317 @cvindex AM_CONFIG_HEADER
1319 @item AM_ENABLE_MULTILIB
1320 This is used when a ``multilib'' library is being built. The first
1321 optional argument is the name of the @file{Makefile} being generated; it
1322 defaults to @samp{Makefile}. The second option argument is used to find
1323 the top source directory; it defaults to the empty string (generally
1324 this should not be used unless you are familiar with the internals).
1327 @item _AM_DEPENDENCIES
1328 @itemx AM_SET_DEPDIR
1330 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
1331 These macros are used to implement automake's automatic dependency
1332 tracking scheme. They are called automatically by automake when
1333 required, and there should be no need to invoke them manually.
1335 @item AM_FUNC_STRTOD
1336 If the @code{strtod} function is not available, or does not work
1337 correctly (like the one on SunOS 5.4), add @file{strtod.o} to output
1338 variable @code{LIBOBJS}.
1339 @cvindex AM_FUNC_STRTOD
1341 @item AM_FUNC_ERROR_AT_LINE
1342 If the function @code{error_at_line} is not found, then add
1343 @file{error.o} to @code{LIBOBJS}.
1344 @cvindex AM_FUNC_ERROR_AT_LINE
1346 @item AM_FUNC_OBSTACK
1347 Check for the GNU obstacks code; if not found, add @file{obstack.o} to
1349 @cvindex AM_FUNC_OBSTACK
1351 @item AM_C_PROTOTYPES
1352 Check to see if function prototypes are understood by the compiler. If
1353 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1354 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1355 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1356 values to implement automatic de-ANSI-fication.
1357 @cvindex AM_C_PROTOTYPES
1359 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1360 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1361 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1362 found in @file{<termios.h>}.
1363 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1365 @item AM_INIT_AUTOMAKE
1366 Runs many macros that most @file{configure.in}'s need. This macro has
1367 two required arguments, the package and the version number. By default
1368 this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}. This
1369 can be avoided by passing in a non-empty third argument.
1371 @item AM_MAKE_INCLUDE
1372 This macro is used to discover how the user's @code{make} handles
1373 @code{include} statements. This macro is automatically invoked when
1374 needed; there should be no need to invoke it manually.
1376 @item AM_PATH_LISPDIR
1377 Searches for the program @code{emacs}, and, if found, sets the output
1378 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1379 @cvindex AM_PATH_LISPDIR
1382 Use this macro when you have assembly code in your project. This will
1383 choose the assembler for you (by default the C compiler), and will set
1384 @code{ASFLAGS} if required.
1386 @item AM_PROG_CC_C_O
1387 This is like @code{AC_PROG_CC_C_O}, but it generates its results in the
1388 manner required by automake. You must use this instead of
1389 @code{AC_PROG_CC_C_O} when you need this functionality.
1391 @item AM_PROG_CC_STDC
1392 If the C compiler in not in ANSI C mode by default, try to add an option
1393 to output variable @code{CC} to make it so. This macro tries various
1394 options that select ANSI C on some system or another. It considers the
1395 compiler to be in ANSI C mode if it handles function prototypes correctly.
1397 If you use this macro, you should check after calling it whether the C
1398 compiler has been set to accept ANSI C; if not, the shell variable
1399 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1400 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1401 @code{ansi2knr} option (@pxref{ANSI}).
1404 @cindex HP-UX 10, lex problems
1405 @cindex lex problems with HP-UX 10
1406 Like @code{AC_PROG_LEX} with @code{AC_DECL_YYTEXT} (@pxref{Particular
1407 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}),
1408 but uses the @code{missing} script on systems that do not have
1409 @code{lex}. @samp{HP-UX 10} is one such system.
1411 Autoconf 2.50 and higher, in order to simplify the interface, includes
1412 the body of @code{AC_DECL_YYTEXT} in @code{AC_PROG_LEX}. To ensure
1413 backward compatibility, @code{AC_DECL_YYTEXT} is nevertheless defined as
1414 an invocation of @code{AC_PROG_LEX}. Since @code{AM_PROG_LEX} invokes
1415 both, it causes an annoying but benign warning (@code{AC_PROG_LEX}
1416 invoked multiple times) which you should just ignore. In the future,
1417 once Automake requires Autoconf 2.50, this issue will be fixed, but the
1418 current compatibility with Autoconf 2.13 prevents this.
1421 This macro finds the @code{gcj} program or causes an error. It sets
1422 @samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
1423 GNU Compiler Collection.
1424 @cvindex AM_PROG_GCJ
1426 @item AM_PROG_INSTALL_STRIP
1427 This is used to find a version of @code{install} which can be used to
1428 @code{strip} a program at installation time. This macro is
1429 automatically included when required.
1431 @item AM_SANITY_CHECK
1432 This checks to make sure that a file created in the build directory is
1433 newer than a file in the source directory. This can fail on systems
1434 where the clock is set incorrectly. This macro is automatically run
1435 from @code{AM_INIT_AUTOMAKE}.
1437 @item AM_SYS_POSIX_TERMIOS
1438 @cvindex am_cv_sys_posix_termios
1439 @cindex POSIX termios headers
1440 @cindex termios POSIX headers
1441 Check to see if POSIX termios headers and functions are available on the
1442 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1443 @samp{yes}. If not, set the variable to @samp{no}.
1445 @item AM_TYPE_PTRDIFF_T
1446 @cvindex HAVE_PTRDIFF_T
1448 Define @samp{HAVE_PTRDIFF_T} if the type @samp{ptrdiff_t} is defined in
1451 @item AM_WITH_DMALLOC
1452 @cvindex WITH_DMALLOC
1453 @cindex dmalloc, support for
1454 @opindex --with-dmalloc
1456 @uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
1457 package. If the user configures with @samp{--with-dmalloc}, then define
1458 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
1462 @opindex --with-regex
1463 @cindex regex package
1465 Adds @samp{--with-regex} to the @code{configure} command line. If
1466 specified (the default), then the @samp{regex} regular expression
1467 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1468 @samp{WITH_REGEX} is defined.. If @samp{--without-regex} is given, then
1469 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1470 into @samp{LIBOBJS}.
1475 @node Extending aclocal, , Macros, configure
1476 @section Writing your own aclocal macros
1478 @cindex aclocal, extending
1479 @cindex Extending aclocal
1481 The @code{aclocal} program doesn't have any built-in knowledge of any
1482 macros, so it is easy to extend it with your own macros.
1484 This is mostly used for libraries which want to supply their own
1485 Autoconf macros for use by other programs. For instance the
1486 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1487 should be used by any package using @code{gettext}. When the library is
1488 installed, it installs this macro so that @code{aclocal} will find it.
1490 A file of macros should be a series of @code{AC_DEFUN}'s. The
1491 @code{aclocal} programs also understands @code{AC_REQUIRE}, so it is
1492 safe to put each macro in a separate file. @xref{Prerequisite Macros, ,
1493 , autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
1494 autoconf, The Autoconf Manual}.
1496 A macro file's name should end in @file{.m4}. Such files should be
1497 installed in @file{$(datadir)/aclocal}.
1500 @node Top level, Alternative, configure, Top
1501 @chapter The top-level @file{Makefile.am}
1503 @cindex SUBDIRS, explained
1505 In packages with subdirectories, the top level @file{Makefile.am} must
1506 tell Automake which subdirectories are to be built. This is done via
1507 the @code{SUBDIRS} variable.
1510 The @code{SUBDIRS} macro holds a list of subdirectories in which
1511 building of various sorts can occur. Many targets (e.g. @code{all}) in
1512 the generated @file{Makefile} will run both locally and in all specified
1513 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1514 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1515 (after configuration). This allows inclusion of libraries from packages
1516 which do not use Automake (such as @code{gettext}). The directories
1517 mentioned in @code{SUBDIRS} must be direct children of the current
1518 directory. For instance, you cannot put @samp{src/subdir} into
1521 In packages that use subdirectories, the top-level @file{Makefile.am} is
1522 often very short. For instance, here is the @file{Makefile.am} from the
1523 GNU Hello distribution:
1526 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1527 SUBDIRS = doc intl po src tests
1530 @cindex SUBDIRS, overriding
1531 @cindex Overriding SUBDIRS
1533 It is possible to override the @code{SUBDIRS} variable if, like in the
1534 case of GNU @code{Inetutils}, you want to only build a subset of the
1535 entire package. In your @file{Makefile.am} include:
1538 SUBDIRS = @@MY_SUBDIRS@@
1541 Then in your @file{configure.in} you can specify:
1544 MY_SUBDIRS="src doc lib po"
1545 AC_SUBST(MY_SUBDIRS)
1548 (Note that we don't use the variable name @code{SUBDIRS} in our
1549 @file{configure.in}; that would cause Automake to believe that every
1550 @file{Makefile.in} should recurse into the listed subdirectories.)
1552 The upshot of this is that Automake is tricked into building the package
1553 to take the subdirs, but doesn't actually bind that list until
1554 @code{configure} is run.
1556 Although the @code{SUBDIRS} macro can contain configure substitutions
1557 (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
1558 contents of this variable.
1560 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1561 @code{AC_PROG_MAKE_SET}. When Automake invokes @code{make} in a
1562 subdirectory, it uses the value of the @code{MAKE} variable. It passes
1563 the value of the variable @code{AM_MAKEFLAGS} to the @code{make}
1564 invocation; this can be set in @file{Makefile.am} if there are flags you
1565 must always pass to @code{make}.
1569 The use of @code{SUBDIRS} is not restricted to just the top-level
1570 @file{Makefile.am}. Automake can be used to construct packages of
1573 By default, Automake generates @file{Makefiles} which work depth-first
1574 (@samp{postfix}). However, it is possible to change this ordering. You
1575 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
1576 putting @samp{.} first will cause a @samp{prefix} ordering of
1577 directories. All @samp{clean} targets are run in reverse order of build
1580 Sometimes, such as when running @code{make dist}, you want all possible
1581 subdirectories to be examined. In this case Automake will use
1582 @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to
1583 recurse. This variable will also be used when the user runs
1584 @code{distclean} or @code{maintainer-clean}. It should be set to the
1585 full list of subdirectories in the project. If this macro is not set,
1586 Automake will attempt to set it for you.
1589 @node Alternative, Rebuilding, Top level, Top
1590 @chapter An Alternative Approach to Subdirectories
1592 If you've ever read Peter Miller's excellent paper,
1593 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
1594 Recursive Make Considered Harmful}, the preceding section on the use of
1595 subdirectories will probably come as unwelcome advice. For those who
1596 haven't read the paper, Miller's main thesis is that recursive
1597 @code{make} invocations are both slow and error-prone.
1599 Automake provides sufficient cross-directory support @footnote{We
1600 believe. This work is new and there are probably warts.
1601 @xref{Introduction}, for information on reporting bugs.} to enable you
1602 to write a single @file{Makefile.am} for a complex multi-directory
1606 By default an installable file specified in a subdirectory will have its
1607 directory name stripped before installation. For instance, in this
1608 example, the header file will be installed as
1609 @file{$(includedir)/stdio.h}:
1612 include_HEADERS = inc/stdio.h
1616 @cindex Path stripping, avoiding
1617 @cindex Avoiding path stripping
1619 However, the @samp{nobase_} prefix can be used to circumvent this path
1620 stripping. In this example, the header file will be installed as
1621 @file{$(includedir)/sys/types.h}:
1624 nobase_include_HEADERS = sys/types.h
1628 @node Rebuilding, Programs, Alternative, Top
1629 @chapter Rebuilding Makefiles
1631 Automake generates rules to automatically rebuild @file{Makefile}s,
1632 @file{configure}, and other derived files like @file{Makefile.in}.
1634 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.in}, then
1635 these automatic rebuilding rules are only enabled in maintainer mode.
1637 Sometimes you need to run @code{aclocal} with an argument like @code{-I}
1638 to tell it where to find @file{.m4} files. Since sometimes @code{make}
1639 will automatically run @code{aclocal}, you need a way to specify these
1640 arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this
1641 holds arguments which are passed verbatim to @code{aclocal}. This macro
1642 is only useful in the top-level @file{Makefile.am}.
1643 @cindex ACLOCAL_AMFLAGS
1646 @node Programs, Other objects, Rebuilding, Top
1647 @chapter Building Programs and Libraries
1649 A large part of Automake's functionality is dedicated to making it easy
1650 to build programs and libraries.
1653 * A Program:: Building a program
1654 * A Library:: Building a library
1655 * Program and Library Variables::
1656 Variables controlling program and
1658 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1659 * A Shared Library:: Building a Libtool library
1660 * Program variables:: Variables used when building a program
1661 * Yacc and Lex:: Yacc and Lex support
1663 * Assembly Support::
1664 * Fortran 77 Support::
1666 * Support for Other Languages::
1667 * ANSI:: Automatic de-ANSI-fication
1668 * Dependencies:: Automatic dependency tracking
1672 @node A Program, A Library, Programs, Programs
1673 @section Building a program
1675 @cindex PROGRAMS, bindir
1676 @vindex bin_PROGRAMS
1677 @vindex sbin_PROGRAMS
1678 @vindex libexec_PROGRAMS
1679 @vindex pkglib_PROGRAMS
1680 @vindex noinst_PROGRAMS
1682 In a directory containing source that gets built into a program (as
1683 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
1684 can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
1685 @code{pkglibdir}, or not at all (@samp{noinst}). They can also be built
1686 only for @code{make check}, in which case the prefix is @samp{check}.
1691 bin_PROGRAMS = hello
1694 In this simple case, the resulting @file{Makefile.in} will contain code
1695 to generate a program named @code{hello}.
1697 Associated with each program are several assisting variables which are
1698 named after the program. These variables are all optional, and have
1699 reasonable defaults. Each variable, its use, and default is spelled out
1700 below; we use the ``hello'' example throughout.
1702 The variable @code{hello_SOURCES} is used to specify which source files
1703 get built into an executable:
1706 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1709 This causes each mentioned @samp{.c} file to be compiled into the
1710 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1712 @cindex _SOURCES primary, defined
1713 @cindex SOURCES primary, defined
1714 @cindex Primary variable, SOURCES
1716 If @samp{hello_SOURCES} is not specified, then it defaults to the single
1717 file @file{hello.c}; that is, the default is to compile a single C file
1718 whose base name is the name of the program itself. (This is a terrible
1719 default but we are stuck with it for historical reasons.)
1723 Multiple programs can be built in a single directory. Multiple programs
1724 can share a single source file, which must be listed in each
1725 @samp{_SOURCES} definition.
1727 @cindex Header files in _SOURCES
1728 @cindex _SOURCES and header files
1730 Header files listed in a @samp{_SOURCES} definition will be included in
1731 the distribution but otherwise ignored. In case it isn't obvious, you
1732 should not include the header file generated by @file{configure} in an
1733 @samp{_SOURCES} variable; this file should not be distributed. Lex
1734 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1737 You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
1738 @samp{_SOURCES} variable. The reason for this is a bit hard to explain,
1739 but suffice to say that it simply won't work. Automake will give an
1740 error if you try to do this.
1742 @cindex EXTRA_prog_SOURCES, defined
1744 Automake must know all the source files that could possibly go into a
1745 program, even if not all the files are built in every circumstance.
1746 Any files which are only conditionally built should be listed in the
1747 appropriate @samp{EXTRA_} variable. For instance, if
1748 @file{hello-linux.c} were conditionally included in @code{hello}, the
1749 @file{Makefile.am} would contain:
1752 EXTRA_hello_SOURCES = hello-linux.c
1755 Similarly, sometimes it is useful to determine the programs that are to
1756 be built at configure time. For instance, GNU @code{cpio} only builds
1757 @code{mt} and @code{rmt} under special circumstances.
1759 @cindex EXTRA_PROGRAMS, defined
1761 In this case, you must notify Automake of all the programs that can
1762 possibly be built, but at the same time cause the generated
1763 @file{Makefile.in} to use the programs specified by @code{configure}.
1764 This is done by having @code{configure} substitute values into each
1765 @samp{_PROGRAMS} definition, while listing all optionally built programs
1766 in @code{EXTRA_PROGRAMS}.
1767 @vindex EXTRA_PROGRAMS
1769 If you need to link against libraries that are not found by
1770 @code{configure}, you can use @code{LDADD} to do so. This variable
1771 actually can be used to add any options to the linker command line.
1774 @cindex prog_LDADD, defined
1776 Sometimes, multiple programs are built in one directory but do not share
1777 the same link-time requirements. In this case, you can use the
1778 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1779 program as it appears in some @samp{_PROGRAMS} variable, and usually
1780 written in lowercase) to override the global @code{LDADD}. If this
1781 variable exists for a given program, then that program is not linked
1785 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
1786 linked against the library @file{libcpio.a}. However, @code{rmt} is
1787 built in the same directory, and has no such link requirement. Also,
1788 @code{mt} and @code{rmt} are only built on certain architectures. Here
1789 is what cpio's @file{src/Makefile.am} looks like (abridged):
1792 bin_PROGRAMS = cpio pax @@MT@@
1793 libexec_PROGRAMS = @@RMT@@
1794 EXTRA_PROGRAMS = mt rmt
1796 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1799 cpio_SOURCES = @dots{}
1800 pax_SOURCES = @dots{}
1801 mt_SOURCES = @dots{}
1802 rmt_SOURCES = @dots{}
1805 @cindex _LDFLAGS, defined
1807 @samp{@var{prog}_LDADD} is inappropriate for passing program-specific
1808 linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
1809 @samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
1813 @cindex _DEPENDENCIES, defined
1815 It is also occasionally useful to have a program depend on some other
1816 target which is not actually part of that program. This can be done
1817 using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
1818 on the contents of such a variable, but no further interpretation is
1821 If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
1822 Automake. The automatically-assigned value is the contents of
1823 @samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
1824 @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
1825 configure substitutions that are left in are only @samp{@@LIBOBJS@@} and
1826 @samp{@@ALLOCA@@}; these are left because it is known that they will not
1827 cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
1831 @node A Library, Program and Library Variables, A Program, Programs
1832 @section Building a library
1834 @cindex _LIBRARIES primary, defined
1835 @cindex LIBRARIES primary, defined
1836 @cindex Primary variable, LIBRARIES
1838 @vindex lib_LIBRARIES
1839 @vindex pkglib_LIBRARIES
1840 @vindex noinst_LIBRARIES
1842 Building a library is much like building a program. In this case, the
1843 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
1844 @code{libdir} or @code{pkglibdir}.
1846 @xref{A Shared Library}, for information on how to build shared
1847 libraries using Libtool and the @samp{LTLIBRARIES} primary.
1849 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
1850 For instance to create a library named @file{libcpio.a}, but not install
1851 it, you would write:
1854 noinst_LIBRARIES = libcpio.a
1857 The sources that go into a library are determined exactly as they are
1858 for programs, via the @samp{_SOURCES} variables. Note that the library
1859 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
1860 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
1861 not @samp{liblob.a_SOURCES}.
1863 @cindex _LIBADD primary, defined
1864 @cindex LIBADD primary, defined
1865 @cindex Primary variable, LIBADD
1867 Extra objects can be added to a library using the
1868 @samp{@var{library}_LIBADD} variable. This should be used for objects
1869 determined by @code{configure}. Again from @code{cpio}:
1874 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
1877 In addition, sources for extra objects that will not exist until
1878 configure-time must be added to the @code{BUILT_SOURCES} variable
1882 @node Program and Library Variables, LIBOBJS, A Library, Programs
1883 @section Program and Library Variables
1885 Associated with each program are a collection of variables which can be
1886 used to modify how that program is built. There is a similar list of
1887 such variables for each library. The canonical name of the program (or
1888 library) is used as a base for naming these variables.
1890 In the list below, we use the name ``maude'' to refer to the program or
1891 library. In your @file{Makefile.am} you would replace this with the
1892 canonical name of your program. This list also refers to ``maude'' as a
1893 program, but in general the same rules apply for both static and dynamic
1894 libraries; the documentation below notes situations where programs and
1899 This variable, if it exists, lists all the source files which are
1900 compiled to build the program. These files are added to the
1901 distribution by default. When building the program, Automake will cause
1902 each source file to be compiled to a single @file{.o} file (or
1903 @file{.lo} when using libtool). Normally these object files are named
1904 after the source file, but other factors can change this. If a file in
1905 the @samp{_SOURCES} variable has an unrecognized extension, Automake
1906 will do one of two things with it. If a suffix rule exists for turning
1907 files with the unrecognized extension into @file{.o} files, then
1908 automake will treat this file as it will any other source file
1909 (@pxref{Support for Other Languages}). Otherwise, the file will be
1910 ignored as though it were a header file.
1912 The prefixes @samp{dist_} and @samp{nodist_} can be used to control
1913 whether files listed in a @samp{_SOURCES} variable are distributed.
1914 @samp{dist_} is redundant, as sources are distributed by default, but it
1915 can be specified for clarity if desired.
1917 It is possible to have both @samp{dist_} and @samp{nodist_} variants of
1918 a given @samp{_SOURCES} variable at once; this lets you easily
1919 distribute some files and not others, for instance:
1922 nodist_maude_SOURCES = nodist.c
1923 dist_maude_SOURCES = dist-me.c
1926 By default the output file (on Unix systems, the @file{.o} file) will be
1927 put into the current build directory. However, if the option
1928 @code{subdir-objects} is in effect in the current directory then the
1929 @file{.o} file will be put into the subdirectory named after the source
1930 file. For instance, with @code{subdir-objects} enabled,
1931 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
1932 people prefer this mode of operation. You can specify
1933 @code{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
1934 @cindex Subdirectory, objects in
1935 @cindex Objects in subdirectory
1938 @item EXTRA_maude_SOURCES
1939 Automake needs to know the list of files you intend to compile
1940 @emph{statically}. For one thing, this is the only way Automake has of
1941 knowing what sort of language support a given @file{Makefile.in}
1942 requires. @footnote{There are other, more obscure reasons reasons for
1943 this limitation as well.} This means that, for example, you can't put a
1944 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
1945 variable. If you intend to conditionally compile source files and use
1946 @file{configure} to substitute the appropriate object names into, e.g.,
1947 @samp{_LDADD} (see below), then you should list the corresponding source
1948 files in the @samp{EXTRA_} variable.
1950 This variable also supports @samp{dist_} and @samp{nodist_} prefixes,
1951 e.g., @samp{nodist_EXTRA_maude_SOURCES}.
1954 A static library is created by default by invoking @code{$(AR) cru}
1955 followed by the name of the library and then the objects being put into
1956 the library. You can override this by setting the @samp{_AR} variable.
1957 This is usually used with C++; some C++ compilers require a special
1958 invocation in order to instantiate all the templates which should go
1959 into a library. For instance, the SGI C++ compiler likes this macro set
1962 libmaude_a_AR = $(CXX) -ar -o
1966 Extra objects can be added to a static library using the @samp{_LIBADD}
1967 variable. This should be used for objects determined by
1968 @code{configure}. Note that @samp{_LIBADD} is not used for shared
1969 libraries; there you must use @samp{_LDADD}.
1972 Extra objects can be added to a shared library or a program by listing
1973 them in the @samp{_LDADD} variable. This should be used for objects
1974 determined by @code{configure}.
1976 @samp{_LDADD} is inappropriate for passing program-specific linker flags
1977 (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen}).
1978 Use the @samp{_LDFLAGS} variable for this purpose.
1980 For instance, if your @file{configure.in} uses @code{AC_PATH_XTRA}, you
1981 could link your program against the X libraries like so:
1984 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
1988 This variable is used to pass extra flags to the link step of a program
1989 or a shared library.
1992 You can override the linker on a per-program basis. By default the
1993 linker is chosen according to the languages used by the program. For
1994 instance, a program that includes C++ source code would use the C++
1995 compiler to link. The @samp{_LINK} variable must hold the name of a
1996 command which can be passed all the @file{.o} file names as arguments.
1997 Note that the name of the underlying program is @emph{not} passed to
1998 @samp{_LINK}; typically one uses @samp{$@@}:
2001 maude_LINK = $(CCLD) -magic -o $@
2005 Automake allows you to set compilation flags on a per-program (or
2006 per-library) basis. A single source file can be included in several
2007 programs, and it will potentially be compiled with different flags for
2008 each program. This works for any language directly supported by
2009 Automake. The flags are @samp{_CFLAGS}, @samp{_CXXFLAGS},
2010 @samp{_OBJCFLAGS}, @samp{_YFLAGS}, @samp{_ASFLAGS}, @samp{_FFLAGS},
2011 @samp{_RFLAGS}, and @samp{_GCJFLAGS}.
2013 When using a per-program compilation flag, Automake will choose a
2014 different name for the intermediate object files. Ordinarily a file
2015 like @file{sample.c} will be compiled to produce @file{sample.o}.
2016 However, if the program's @samp{_CFLAGS} variable is set, then the
2017 object file will be named, for instance, @file{maude-sample.o}.
2019 In compilations with per-program flags, the ordinary @samp{AM_} form of
2020 the flags variable is @emph{not} automatically included in the
2021 compilation (however, the user form of the variable @emph{is} included).
2022 So for instance, if you want the hypothetical @file{maude} compilations
2023 to also use the value of @samp{AM_CFLAGS}, you would need to write:
2026 maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
2029 @item maude_DEPENDENCIES
2030 It is also occasionally useful to have a program depend on some other
2031 target which is not actually part of that program. This can be done
2032 using the @samp{_DEPENDENCIES} variable. Each program depends on the
2033 contents of such a variable, but no further interpretation is done.
2035 If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake.
2036 The automatically-assigned value is the contents of @samp{_LDADD}, with
2037 most configure substitutions, @samp{-l}, @samp{-L}, @samp{-dlopen} and
2038 @samp{-dlpreopen} options removed. The configure substitutions that are
2039 left in are only @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are
2040 left because it is known that they will not cause an invalid value for
2041 @samp{_DEPENDENCIES} to be generated.
2043 @item maude_SHORTNAME
2044 On some platforms the allowable file names are very short. In order to
2045 support these systems and per-program compilation flags at the same
2046 time, Automake allows you to set a ``short name'' which will influence
2047 how intermediate object files are named. For instance, if you set
2048 @samp{maude_SHORTNAME} to @samp{m}, then in the above per-program
2049 compilation flag example the object file would be named
2050 @file{m-sample.o} rather than @file{maude-sample.o}. This facility is
2051 rarely needed in practice, and we recommend avoiding it until you find
2056 @node LIBOBJS, A Shared Library, Program and Library Variables, Programs
2057 @section Special handling for LIBOBJS and ALLOCA
2059 @cindex @@LIBOBJS@@, special handling
2060 @cindex @@ALLOCA@@, special handling
2062 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
2063 @code{@@ALLOCA@@}, and uses this information, plus the list of
2064 @code{LIBOBJS} files derived from @file{configure.in} to automatically
2065 include the appropriate source files in the distribution (@pxref{Dist}).
2066 These source files are also automatically handled in the
2067 dependency-tracking scheme; see @xref{Dependencies}.
2069 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
2070 @samp{_LDADD} or @samp{_LIBADD} variable.
2073 @node A Shared Library, Program variables, LIBOBJS, Programs
2074 @section Building a Shared Library
2076 @cindex Shared libraries, support for
2078 Building shared libraries is a relatively complex matter. For this
2079 reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
2080 Libtool Manual}) was created to help build shared libraries in a
2081 platform-independent way.
2083 @cindex _LTLIBRARIES primary, defined
2084 @cindex LTLIBRARIES primary, defined
2085 @cindex Primary variable, LTLIBRARIES
2086 @cindex Example of shared libraries
2088 @cindex suffix .la, defined
2090 Automake uses Libtool to build libraries declared with the
2091 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
2092 of shared libraries to build. For instance, to create a library named
2093 @file{libgettext.a} and its corresponding shared libraries, and install
2094 them in @samp{libdir}, write:
2097 lib_LTLIBRARIES = libgettext.la
2100 @vindex lib_LTLIBRARIES
2101 @vindex pkglib_LTLIBRARIES
2102 @vindex noinst_LTLIBRARIES
2103 @vindex check_LTLIBRARIES
2105 @cindex check_LTLIBRARIES, not allowed
2107 Note that shared libraries @emph{must} be installed, so
2108 @code{check_LTLIBRARIES} is not allowed. However,
2109 @code{noinst_LTLIBRARIES} is allowed. This feature should be used for
2110 libtool ``convenience libraries''.
2112 @cindex suffix .lo, defined
2114 For each library, the @samp{@var{library}_LIBADD} variable contains the
2115 names of extra libtool objects (@file{.lo} files) to add to the shared
2116 library. The @samp{@var{library}_LDFLAGS} variable contains any
2117 additional libtool flags, such as @samp{-version-info} or
2120 @cindex @@LTLIBOBJS@@, special handling
2122 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
2123 library must use @code{@@LTLIBOBJS@@}. This is required because the
2124 object files that libtool operates on do not necessarily end in
2125 @file{.o}. The libtool manual contains more details on this topic.
2127 For libraries installed in some directory, Automake will automatically
2128 supply the appropriate @samp{-rpath} option. However, for libraries
2129 determined at configure time (and thus mentioned in
2130 @code{EXTRA_LTLIBRARIES}), Automake does not know the eventual
2131 installation directory; for such libraries you must add the
2132 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
2135 Ordinarily, Automake requires that a shared library's name start with
2136 @samp{lib}. However, if you are building a dynamically loadable module
2137 then you might wish to use a "nonstandard" name. In this case, put
2138 @code{-module} into the @samp{_LDFLAGS} variable.
2140 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
2141 libtool, The Libtool Manual}, for more information.
2144 @node Program variables, Yacc and Lex, A Shared Library, Programs
2145 @section Variables used when building a program
2147 Occasionally it is useful to know which @file{Makefile} variables
2148 Automake uses for compilations; for instance you might need to do your
2149 own compilation in some special cases.
2151 Some variables are inherited from Autoconf; these are @code{CC},
2152 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
2156 There are some additional variables which Automake itself defines:
2160 The contents of this macro are passed to every compilation which invokes
2161 the C preprocessor; it is a list of arguments to the preprocessor. For
2162 instance, @samp{-I} and @samp{-D} options should be listed here.
2164 Automake already provides some @samp{-I} options automatically. In
2165 particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I}
2166 pointing to the directory holding @file{config.h} (if you've used
2167 @code{AC_CONFIG_HEADER} or @code{AM_CONFIG_HEADER}). You can disable
2168 the default @samp{-I} options using the @samp{nostdinc} option.
2171 This does the same job as @samp{AM_CPPFLAGS}. It is an older name for
2172 the same functionality. This macro is deprecated; we suggest using
2173 @samp{AM_CPPFLAGS} instead.
2176 This is the command used to actually compile a C source file. The
2177 filename is appended to form the complete command line.
2180 This is the command used to actually link a C program.
2184 @node Yacc and Lex, C++ Support, Program variables, Programs
2185 @section Yacc and Lex support
2187 Automake has somewhat idiosyncratic support for Yacc and Lex.
2189 Automake assumes that the @file{.c} file generated by @code{yacc} (or
2190 @code{lex}) should be named using the basename of the input file. That
2191 is, for a yacc source file @file{foo.y}, Automake will cause the
2192 intermediate file to be named @file{foo.c} (as opposed to
2193 @file{y.tab.c}, which is more traditional).
2195 The extension of a yacc source file is used to determine the extension
2196 of the resulting @samp{C} or @samp{C++} file. Files with the extension
2197 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
2198 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
2201 Likewise, lex source files can be used to generate @samp{C} or
2202 @samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
2203 @samp{.lxx} are recognized.
2205 You should never explicitly mention the intermediate (@samp{C} or
2206 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
2209 The intermediate files generated by @code{yacc} (or @code{lex}) will be
2210 included in any distribution that is made. That way the user doesn't
2211 need to have @code{yacc} or @code{lex}.
2213 If a @code{yacc} source file is seen, then your @file{configure.in} must
2214 define the variable @samp{YACC}. This is most easily done by invoking
2215 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
2216 Program Checks, autoconf, The Autoconf Manual}).
2218 When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
2219 @samp{AM_YFLAGS}. The former is a user variable and the latter is
2220 intended for the @file{Makefile.am} author.
2222 Similarly, if a @code{lex} source file is seen, then your
2223 @file{configure.in} must define the variable @samp{LEX}. You can use
2224 @samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
2225 Program Checks, autoconf, The Autoconf Manual}). Automake's @code{lex}
2226 support also requires that you use the @samp{AC_DECL_YYTEXT}
2227 macro---automake needs to know the value of @samp{LEX_OUTPUT_ROOT}.
2228 This is all handled for you if you use the @code{AM_PROG_LEX} macro
2231 When @code{yacc} is invoked, it is passed @samp{LFLAGS} and
2232 @samp{AM_LFLAGS}. The former is a user variable and the latter is
2233 intended for the @file{Makefile.am} author.
2238 @cindex yacc, multiple parsers
2239 @cindex Multiple yacc parsers
2240 @cindex Multiple lex lexers
2241 @cindex lex, multiple lexers
2244 Automake makes it possible to include multiple @code{yacc} (or
2245 @code{lex}) source files in a single program. Automake uses a small
2246 program called @code{ylwrap} to run @code{yacc} (or @code{lex}) in a
2247 subdirectory. This is necessary because yacc's output filename is
2248 fixed, and a parallel make could conceivably invoke more than one
2249 instance of @code{yacc} simultaneously. The @code{ylwrap} program is
2250 distributed with Automake. It should appear in the directory specified
2251 by @samp{AC_CONFIG_AUX_DIR} (@pxref{Input, , Finding `configure' Input,
2252 autoconf, The Autoconf Manual}), or the current directory if that macro
2253 is not used in @file{configure.in}.
2255 For @code{yacc}, simply managing locking is insufficient. The output of
2256 @code{yacc} always uses the same symbol names internally, so it isn't
2257 possible to link two @code{yacc} parsers into the same executable.
2259 We recommend using the following renaming hack used in @code{gdb}:
2261 #define yymaxdepth c_maxdepth
2262 #define yyparse c_parse
2264 #define yyerror c_error
2265 #define yylval c_lval
2266 #define yychar c_char
2267 #define yydebug c_debug
2268 #define yypact c_pact
2275 #define yyexca c_exca
2276 #define yyerrflag c_errflag
2277 #define yynerrs c_nerrs
2281 #define yy_yys c_yys
2282 #define yystate c_state
2285 #define yy_yyv c_yyv
2287 #define yylloc c_lloc
2288 #define yyreds c_reds
2289 #define yytoks c_toks
2290 #define yylhs c_yylhs
2291 #define yylen c_yylen
2292 #define yydefred c_yydefred
2293 #define yydgoto c_yydgoto
2294 #define yysindex c_yysindex
2295 #define yyrindex c_yyrindex
2296 #define yygindex c_yygindex
2297 #define yytable c_yytable
2298 #define yycheck c_yycheck
2299 #define yyname c_yyname
2300 #define yyrule c_yyrule
2303 For each define, replace the @samp{c_} prefix with whatever you like.
2304 These defines work for @code{bison}, @code{byacc}, and traditional
2305 @code{yacc}s. If you find a parser generator that uses a symbol not
2306 covered here, please report the new name so it can be added to the list.
2309 @node C++ Support, Assembly Support, Yacc and Lex, Programs
2310 @section C++ Support
2313 @cindex Support for C++
2315 Automake includes full support for C++.
2317 Any package including C++ code must define the output variable
2318 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
2319 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
2320 Program Checks, autoconf, The Autoconf Manual}).
2322 A few additional variables are defined when a C++ source file is seen:
2326 The name of the C++ compiler.
2329 Any flags to pass to the C++ compiler.
2332 The command used to actually compile a C++ source file. The file name
2333 is appended to form the complete command line.
2336 The command used to actually link a C++ program.
2340 @node Assembly Support, Fortran 77 Support, C++ Support, Programs
2341 @section Assembly Support
2343 Automake includes some support for assembly code.
2345 The variable @code{AS} holds the name of the compiler used to build
2346 assembly code. This compiler must work a bit like a C compiler; in
2347 particular it must accept @samp{-c} and @samp{-o}. The value of
2348 @code{ASFLAGS} is passed to the compilation.
2352 You are required to set @code{AS} and @code{ASFLAGS} via
2353 @file{configure.in}. The autoconf macro @code{AM_PROG_AS} will do this
2354 for you. Unless they are already set, it simply sets @code{AS} to the C
2355 compiler and @code{ASFLAGS} to the C compiler flags.
2358 @node Fortran 77 Support, Java Support, Assembly Support, Programs
2359 @comment node-name, next, previous, up
2360 @section Fortran 77 Support
2362 @cindex Fortran 77 support
2363 @cindex Support for Fortran 77
2365 Automake includes full support for Fortran 77.
2367 Any package including Fortran 77 code must define the output variable
2368 @samp{F77} in @file{configure.in}; the simplest way to do this is to use
2369 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
2370 Program Checks, autoconf, The Autoconf Manual}). @xref{Fortran 77 and
2373 A few additional variables are defined when a Fortran 77 source file is
2379 The name of the Fortran 77 compiler.
2382 Any flags to pass to the Fortran 77 compiler.
2385 Any flags to pass to the Ratfor compiler.
2388 The command used to actually compile a Fortran 77 source file. The file
2389 name is appended to form the complete command line.
2392 The command used to actually link a pure Fortran 77 program or shared
2397 Automake can handle preprocessing Fortran 77 and Ratfor source files in
2398 addition to compiling them@footnote{Much, if not most, of the
2399 information in the following sections pertaining to preprocessing
2400 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
2401 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
2402 also contains some support for creating programs and shared libraries
2403 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
2404 Fortran 77 With C and C++}).
2406 These issues are covered in the following sections.
2409 * Preprocessing Fortran 77::
2410 * Compiling Fortran 77 Files::
2411 * Mixing Fortran 77 With C and C++::
2412 * Fortran 77 and Autoconf::
2416 @node Preprocessing Fortran 77, Compiling Fortran 77 Files, Fortran 77 Support, Fortran 77 Support
2417 @comment node-name, next, previous, up
2418 @subsection Preprocessing Fortran 77
2420 @cindex Preprocessing Fortran 77
2421 @cindex Fortran 77, Preprocessing
2422 @cindex Ratfor programs
2424 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
2425 rule runs just the preprocessor to convert a preprocessable Fortran 77
2426 or Ratfor source file into a strict Fortran 77 source file. The precise
2427 command used is as follows:
2432 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2435 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2440 @node Compiling Fortran 77 Files, Mixing Fortran 77 With C and C++, Preprocessing Fortran 77, Fortran 77 Support
2441 @comment node-name, next, previous, up
2442 @subsection Compiling Fortran 77 Files
2444 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
2445 @file{N.r} by running the Fortran 77 compiler. The precise command used
2451 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
2454 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2457 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2462 @node Mixing Fortran 77 With C and C++, Fortran 77 and Autoconf, Compiling Fortran 77 Files, Fortran 77 Support
2463 @comment node-name, next, previous, up
2464 @subsection Mixing Fortran 77 With C and C++
2466 @cindex Fortran 77, mixing with C and C++
2467 @cindex Mixing Fortran 77 with C and C++
2468 @cindex Linking Fortran 77 with C and C++
2470 @cindex Mixing Fortran 77 with C and/or C++
2472 Automake currently provides @emph{limited} support for creating programs
2473 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
2474 However, there are many other issues related to mixing Fortran 77 with
2475 other languages that are @emph{not} (currently) handled by Automake, but
2476 that are handled by other packages@footnote{For example,
2477 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
2478 addresses all of these inter-language issues, and runs under nearly all
2479 Fortran 77, C and C++ compilers on nearly all platforms. However,
2480 @code{cfortran} is not yet Free Software, but it will be in the next
2484 Automake can help in two ways:
2488 Automatic selection of the linker depending on which combinations of
2492 Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
2493 @samp{-l}) to pass to the automatically selected linker in order to link
2494 in the appropriate Fortran 77 intrinsic and run-time libraries.
2496 @cindex FLIBS, defined
2497 These extra Fortran 77 linker flags are supplied in the output variable
2498 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
2499 supplied with newer versions of Autoconf (Autoconf version 2.13 and
2500 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
2504 If Automake detects that a program or shared library (as mentioned in
2505 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
2506 code that is a mixture of Fortran 77 and C and/or C++, then it requires
2507 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
2508 @file{configure.in}, and that either @code{$(FLIBS)} or @code{@@FLIBS@@}
2509 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
2510 (for shared libraries) variables. It is the responsibility of the
2511 person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
2512 or @code{@@FLIBS@@} appears in the appropriate @code{_LDADD} or
2513 @code{_LIBADD} variable.
2515 @cindex Mixed language example
2516 @cindex Example, mixed language
2518 For example, consider the following @file{Makefile.am}:
2522 foo_SOURCES = main.cc foo.f
2523 foo_LDADD = libfoo.la @@FLIBS@@
2525 pkglib_LTLIBRARIES = libfoo.la
2526 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
2527 libfoo_la_LIBADD = $(FLIBS)
2530 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
2531 is mentioned in @file{configure.in}. Also, if @code{@@FLIBS@@} hadn't
2532 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
2533 Automake would have issued a warning.
2538 * How the Linker is Chosen::
2541 @node How the Linker is Chosen, , Mixing Fortran 77 With C and C++, Mixing Fortran 77 With C and C++
2542 @comment node-name, next, previous, up
2543 @subsubsection How the Linker is Chosen
2545 @cindex Automatic linker selection
2546 @cindex Selecting the linker automatically
2548 The following diagram demonstrates under what conditions a particular
2549 linker is chosen by Automake.
2551 For example, if Fortran 77, C and C++ source code were to be compiled
2552 into a program, then the C++ linker will be used. In this case, if the
2553 C or Fortran 77 linkers required any special libraries that weren't
2554 included by the C++ linker, then they must be manually added to an
2555 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
2561 code \ C C++ Fortran
2562 ----------------- +---------+---------+---------+
2566 +---------+---------+---------+
2570 +---------+---------+---------+
2574 +---------+---------+---------+
2578 +---------+---------+---------+
2580 C + Fortran | | | x |
2582 +---------+---------+---------+
2584 C++ + Fortran | | x | |
2586 +---------+---------+---------+
2588 C + C++ + Fortran | | x | |
2590 +---------+---------+---------+
2594 @node Fortran 77 and Autoconf, , Mixing Fortran 77 With C and C++, Fortran 77 Support
2595 @comment node-name, next, previous, up
2596 @subsection Fortran 77 and Autoconf
2598 The current Automake support for Fortran 77 requires a recent enough
2599 version Autoconf that also includes support for Fortran 77. Full
2600 Fortran 77 support was added to Autoconf 2.13, so you will want to use
2601 that version of Autoconf or later.
2604 @node Java Support, Support for Other Languages, Fortran 77 Support, Programs
2605 @comment node-name, next, previous, up
2606 @section Java Support
2608 @cindex Java support
2609 @cindex Support for Java
2611 Automake includes support for compiled Java, using @code{gcj}, the Java
2612 front end to the GNU Compiler Collection.
2614 Any package including Java code to be compiled must define the output
2615 variable @samp{GCJ} in @file{configure.in}; the variable @samp{GCJFLAGS}
2616 must also be defined somehow (either in @file{configure.in} or
2617 @file{Makefile.am}). The simplest way to do this is to use the
2618 @code{AM_PROG_GCJ} macro.
2622 By default, programs including Java source files are linked with
2625 As always, the contents of @samp{AM_GCJFLAGS} are passed to every
2626 compilation invoking @code{gcj} (in its role as an ahead-of-time
2627 compiler -- when invoking it to create @file{.class} files,
2628 @samp{AM_JAVACFLAGS} is used instead). If it is necessary to pass
2629 options to @code{gcj} from @file{Makefile.am}, this macro, and not the
2630 user macro @samp{GCJFLAGS}, should be used.
2634 @code{gcj} can be used to compile @file{.java}, @file{.class},
2635 @file{.zip}, or @file{.jar} files.
2638 @node Support for Other Languages, ANSI, Java Support, Programs
2639 @comment node-name, next, previous, up
2640 @section Support for Other Languages
2642 Automake currently only includes full support for C, C++ (@pxref{C++
2643 Support}), Fortran 77 (@pxref{Fortran 77 Support}), and Java
2644 (@pxref{Java Support}). There is only rudimentary support for other
2645 languages, support for which will be improved based on user demand.
2647 Some limited support for adding your own languages is available via the
2648 suffix rule handling; see @ref{Suffixes}.
2651 @node ANSI, Dependencies, Support for Other Languages, Programs
2652 @section Automatic de-ANSI-fication
2654 @cindex de-ANSI-fication, defined
2656 Although the GNU standards allow the use of ANSI C, this can have the
2657 effect of limiting portability of a package to some older compilers
2658 (notably the SunOS C compiler).
2660 Automake allows you to work around this problem on such machines by
2661 @dfn{de-ANSI-fying} each source file before the actual compilation takes
2664 @vindex AUTOMAKE_OPTIONS
2667 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
2668 (@pxref{Options}) contains the option @code{ansi2knr} then code to
2669 handle de-ANSI-fication is inserted into the generated
2672 This causes each C source file in the directory to be treated as ANSI C.
2673 If an ANSI C compiler is available, it is used. If no ANSI C compiler
2674 is available, the @code{ansi2knr} program is used to convert the source
2675 files into K&R C, which is then compiled.
2677 The @code{ansi2knr} program is simple-minded. It assumes the source
2678 code will be formatted in a particular way; see the @code{ansi2knr} man
2681 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
2682 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
2683 these files are distributed with Automake. Also, the package
2684 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}
2686 @cvindex AM_C_PROTOTYPES
2688 Automake also handles finding the @code{ansi2knr} support files in some
2689 other directory in the current package. This is done by prepending the
2690 relative path to the appropriate directory to the @code{ansi2knr}
2691 option. For instance, suppose the package has ANSI C code in the
2692 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
2693 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
2694 @file{src/Makefile.am}:
2697 AUTOMAKE_OPTIONS = ../lib/ansi2knr
2700 If no directory prefix is given, the files are assumed to be in the
2703 Files mentioned in @code{LIBOBJS} which need de-ANSI-fication will not
2704 be automatically handled. That's because @code{configure} will generate
2705 an object name like @file{regex.o}, while @code{make} will be looking
2706 for @file{regex_.o} (when de-ANSI-fying). Eventually this problem will
2707 be fixed via @code{autoconf} magic, but for now you must put this code
2708 into your @file{configure.in}, just before the @code{AC_OUTPUT} call:
2711 # This is necessary so that .o files in LIBOBJS are also built via
2712 # the ANSI2KNR-filtering rules.
2713 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
2716 Note that automatic de-ANSI-fication will not work when the package is
2717 being built for a different host architecture. That is because automake
2718 currently has no way to build @code{ansi2knr} for the build machine.
2721 @node Dependencies, , ANSI, Programs
2722 @section Automatic dependency tracking
2724 As a developer it is often painful to continually update the
2725 @file{Makefile.in} whenever the include-file dependencies change in a
2726 project. Automake supplies a way to automatically track dependency
2729 @cindex Dependency tracking
2730 @cindex Automatic dependency tracking
2732 Automake always uses complete dependencies for a compilation, including
2733 system headers. Automake's model is that dependency computation should
2734 be a side effect of the build. To this end, dependencies are computed
2735 by running all compilations through a special wrapper program called
2736 @code{depcomp}. @code{depcomp} understands how to coax many different C
2737 and C++ compilers into generating dependency information in the format
2738 it requires. @code{automake -a} will install @code{depcomp} into your
2739 source tree for you. If @code{depcomp} can't figure out how to properly
2740 invoke your compiler, dependency tracking will simply be disabled for
2745 Experience with earlier versions of Automake @footnote{See
2746 @uref{http://sources.redhat.com/automake/dependencies.html} for more
2747 information on the history and experiences with automatic dependency
2748 tracking in Automake} taught us that it is not reliable to generate
2749 dependencies only on the maintainer's system, as configurations vary too
2750 much. So instead Automake implements dependency tracking at build time.
2752 Automatic dependency tracking can be suppressed by putting
2753 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}. Or, you
2754 can invoke @code{automake} with the @code{-i} option. Dependency
2755 tracking is enabled by default.
2757 @vindex AUTOMAKE_OPTIONS
2758 @opindex no-dependencies
2760 The person building your package also can choose to disable dependency
2761 tracking by configuring with @code{--disable-dependency-tracking}.
2763 @cindex Disabling dependency tracking
2764 @cindex Dependency tracking, disabling
2767 @node Other objects, Other GNU Tools, Programs, Top
2768 @chapter Other Derived Objects
2770 Automake can handle derived objects which are not C programs. Sometimes
2771 the support for actually building such objects must be explicitly
2772 supplied, but Automake will still automatically handle installation and
2776 * Scripts:: Executable scripts
2777 * Headers:: Header files
2778 * Data:: Architecture-independent data files
2779 * Sources:: Derived sources
2783 @node Scripts, Headers, Other objects, Other objects
2784 @section Executable Scripts
2786 @cindex _SCRIPTS primary, defined
2787 @cindex SCRIPTS primary, defined
2788 @cindex Primary variable, SCRIPTS
2790 It is possible to define and install programs which are scripts. Such
2791 programs are listed using the @samp{SCRIPTS} primary name. Automake
2792 doesn't define any dependencies for scripts; the @file{Makefile.am}
2793 should include the appropriate rules.
2796 Automake does not assume that scripts are derived objects; such objects
2797 must be deleted by hand (@pxref{Clean}).
2799 The @code{automake} program itself is a Perl script that is generated at
2800 configure time from @file{automake.in}. Here is how this is handled:
2803 bin_SCRIPTS = automake
2806 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
2807 for it is automatically generated.
2809 @cindex SCRIPTS, installation directories
2810 @cindex Installing scripts
2813 @vindex sbin_SCRIPTS
2814 @vindex libexec_SCRIPTS
2815 @vindex pkgdata_SCRIPTS
2816 @vindex noinst_SCRIPTS
2818 Script objects can be installed in @code{bindir}, @code{sbindir},
2819 @code{libexecdir}, or @code{pkgdatadir}.
2822 @node Headers, Data, Scripts, Other objects
2823 @section Header files
2825 @cindex _HEADERS primary, defined
2826 @cindex HEADERS primary, defined
2827 @cindex Primary variable, HEADERS
2829 @vindex noinst_HEADERS
2831 Header files are specified by the @samp{HEADERS} family of variables.
2832 Generally header files are not installed, so the @code{noinst_HEADERS}
2833 variable will be the most used. @footnote{However, for the case of a
2834 non-installed header file that is actually used by a particular program,
2835 we recommend listing it in the program's @samp{_SOURCES} variable
2836 instead of in @code{noinst_HEADERS}. We believe this is more clear.}
2839 All header files must be listed somewhere; missing ones will not appear
2840 in the distribution. Often it is clearest to list uninstalled headers
2841 with the rest of the sources for a program. @xref{A Program}. Headers
2842 listed in a @samp{_SOURCES} variable need not be listed in any
2843 @samp{_HEADERS} variable.
2845 @cindex HEADERS, installation directories
2846 @cindex Installing headers
2848 @vindex include_HEADERS
2849 @vindex oldinclude_HEADERS
2850 @vindex pkginclude_HEADERS
2852 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
2853 @code{pkgincludedir}.
2856 @node Data, Sources, Headers, Other objects
2857 @section Architecture-independent data files
2859 @cindex _DATA primary, defined
2860 @cindex DATA primary, defined
2861 @cindex Primary variable, DATA
2863 Automake supports the installation of miscellaneous data files using the
2864 @samp{DATA} family of variables.
2868 @vindex sysconf_DATA
2869 @vindex sharedstate_DATA
2870 @vindex localstate_DATA
2871 @vindex pkgdata_DATA
2873 Such data can be installed in the directories @code{datadir},
2874 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
2877 By default, data files are @emph{not} included in a distribution. Of
2878 course, you can use the @samp{dist_} prefix to change this on a
2881 Here is how Automake installs its auxiliary data files:
2884 pkgdata_DATA = clean-kr.am clean.am @dots{}
2888 @node Sources, , Data, Other objects
2889 @section Built sources
2891 @cindex BUILT_SOURCES, defined
2893 Occasionally a file which would otherwise be called @samp{source}
2894 (e.g. a C @samp{.h} file) is actually derived from some other file.
2895 Such files should be listed in the @code{BUILT_SOURCES} variable.
2896 @vindex BUILT_SOURCES
2898 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
2899 must be created early in the build process can be listed in this
2902 A source file listed in @code{BUILT_SOURCES} is created before the other
2903 @code{all} targets are made. However, such a source file is not
2904 compiled unless explicitly requested by mentioning it in some other
2905 @samp{_SOURCES} variable.
2907 So, for instance, if you had header files which were created by a script
2908 run at build time, then you would list these headers in
2909 @code{BUILT_SOURCES}, to ensure that they would be built before any
2910 other compilations (perhaps ones using these headers) were started.
2913 @node Other GNU Tools, Documentation, Other objects, Top
2914 @chapter Other GNU Tools
2916 Since Automake is primarily intended to generate @file{Makefile.in}s for
2917 use in GNU programs, it tries hard to interoperate with other GNU tools.
2920 * Emacs Lisp:: Emacs Lisp
2928 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
2931 @cindex _LISP primary, defined
2932 @cindex LISP primary, defined
2933 @cindex Primary variable, LISP
2939 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
2940 is used to hold a list of @file{.el} files. Possible prefixes for this
2941 primary are @samp{lisp_} and @samp{noinst_}. Note that if
2942 @code{lisp_LISP} is defined, then @file{configure.in} must run
2943 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
2947 By default Automake will byte-compile all Emacs Lisp source files using
2948 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
2949 byte-compiling, simply define the variable @code{ELCFILES} to be empty.
2950 Byte-compiled Emacs Lisp files are not portable among all versions of
2951 Emacs, so it makes sense to turn this off if you expect sites to have
2952 more than one version of Emacs installed. Furthermore, many packages
2953 don't actually benefit from byte-compilation. Still, we recommend that
2954 you leave it enabled by default. It is probably better for sites with
2955 strange setups to cope for themselves than to make the installation less
2956 nice for everybody else.
2959 @node gettext, Libtool, Emacs Lisp, Other GNU Tools
2962 @cindex GNU Gettext support
2963 @cindex Gettext support
2964 @cindex Support for GNU Gettext
2966 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
2967 turns on support for GNU gettext, a message catalog system for
2968 internationalization
2969 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
2971 The @code{gettext} support in Automake requires the addition of two
2972 subdirectories to the package, @file{intl} and @file{po}. Automake
2973 insures that these directories exist and are mentioned in
2977 @node Libtool, Java, gettext, Other GNU Tools
2980 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
2981 libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
2982 @xref{A Shared Library}.
2985 @node Java, Python, Libtool, Other GNU Tools
2988 @cindex _JAVA primary, defined
2989 @cindex JAVA primary, defined
2990 @cindex Primary variable, JAVA
2992 Automake provides some minimal support for Java compilation with the
2993 @samp{JAVA} primary.
2995 Any @file{.java} files listed in a @samp{_JAVA} variable will be
2996 compiled with @code{JAVAC} at build time. By default, @file{.class}
2997 files are not included in the distribution.
2999 @cindex JAVA restrictions
3000 @cindex Restrictions for JAVA
3002 Currently Automake enforces the restriction that only one @samp{_JAVA}
3003 primary can be used in a given @file{Makefile.am}. The reason for this
3004 restriction is that, in general, it isn't possible to know which
3005 @file{.class} files were generated from which @file{.java} files -- so
3006 it would be impossible to know which files to install where. For
3007 instance, a @file{.java} file can define multiple classes; the resulting
3008 @file{.class} file names cannot be predicted without parsing the
3011 There are a few variables which are used when compiling Java sources:
3015 The name of the Java compiler. This defaults to @samp{javac}.
3018 The flags to pass to the compiler. This is considered to be a user
3019 variable (@pxref{User Variables}).
3022 More flags to pass to the Java compiler. This, and not
3023 @code{JAVACFLAGS}, should be used when it is necessary to put Java
3024 compiler flags into @file{Makefile.am}.
3027 The value of this variable is passed to the @samp{-d} option to
3028 @code{javac}. It defaults to @samp{$(top_builddir)}.
3031 This variable is an @code{sh} expression which is used to set the
3032 @code{CLASSPATH} environment variable on the @code{javac} command line.
3033 (In the future we will probably handle class path setting differently.)
3037 @node Python, , Java, Other GNU Tools
3040 @cindex _PYTHON primary, defined
3041 @cindex PYTHON primary, defined
3042 @cindex Primary variable, PYTHON
3045 Automake provides support for Python modules. Automake will turn on
3046 Python support if the @code{AM_PATH_PYTHON} macro is used in
3047 @file{configure.in}. The @samp{PYTHON} primary is used to hold a list
3048 of @file{.py} files. Possible prefixes for this primary are
3049 @samp{python_} and @samp{noinst_}. Note that if @code{python_PYTHON} is
3050 defined, then @file{configure.in} must run @code{AM_PATH_PYTHON}.
3051 Python source files are included in the distribution by default.
3053 @code{AM_PATH_PYTHON} takes a single optional argument. This argument,
3054 if present, is the minimum version of Python which can be used for this
3055 package. If the version of Python found on the system is older than the
3056 required version, then @code{AM_PATH_PYTHON} will cause an error.
3058 @code{AM_PATH_PYTHON} creates several output variables based on the
3059 Python installation found during configuration.
3063 The name of the Python executable.
3065 @item PYTHON_VERSION
3066 The Python version number, in the form @var{major}.@var{minor}
3067 (e.g. @samp{1.5}). This is currently the value of
3068 @code{sys.version[:3]}.
3071 The string @code{$prefix}. This term may be used in future work
3072 which needs the contents of Python's @code{sys.prefix}, but general
3073 consensus is to always use the value from configure.
3075 @item PYTHON_EXEC_PREFIX
3076 The string @code{$exec_prefix}. This term may be used in future work
3077 which needs the contents of Python's @code{sys.exec_prefix}, but general
3078 consensus is to always use the value from configure.
3080 @item PYTHON_PLATFORM
3081 The canonical name used by Python to describe the operating system, as
3082 given by @code{sys.platform}. This value is sometimes needed when
3083 building Python extensions.
3086 The directory name for the @file{site-packages} subdirectory of the
3087 standard Python install tree.
3090 This is is the directory under @code{pythondir} which is named after the
3091 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
3095 This is the directory where Python extension modules (shared libraries)
3096 should be installed.
3099 This is a convenience variable which is defined as
3100 @samp{$(pyexecdir)/$(PACKAGE)}.
3106 By default Automake will byte-compile all Python source files to both
3107 @file{.pyc} and @file{.pyo} forms. If you wish to avoid generating the
3108 optimized byte-code files, simply define the variable @code{PYOFILES} to
3109 be empty. Similarly, if you don't wish to generate the standard
3110 byte-compiled files, define the variable @code{PYCFILES} to be empty.
3113 @node Documentation, Install, Other GNU Tools, Top
3114 @chapter Building documentation
3116 Currently Automake provides support for Texinfo and man pages.
3120 * Man pages:: Man pages
3124 @node Texinfo, Man pages, Documentation, Documentation
3127 @cindex _TEXINFOS primary, defined
3128 @cindex TEXINFOS primary, defined
3129 @cindex Primary variable, TEXINFOS
3131 If the current directory contains Texinfo source, you must declare it
3132 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
3133 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
3134 here. Any Texinfo source file must end in the @file{.texi},
3135 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
3138 @vindex info_TEXINFOS
3140 @cindex Texinfo macro, VERSION
3141 @cindex Texinfo macro, UPDATED
3142 @cindex Texinfo macro, EDITION
3143 @cindex Texinfo macro, UPDATED-MONTH
3145 @cindex VERSION Texinfo macro
3146 @cindex UPDATED Texinfo macro
3147 @cindex EDITION Texinfo macro
3148 @cindex UPDATED-MONTH Texinfo macro
3152 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
3153 that file will be automatically generated. The file @file{version.texi}
3154 defines four Texinfo macros you can reference:
3159 Both of these macros hold the version number of your program. They are
3160 kept separate for clarity.
3163 This holds the date the primary @file{.texi} file was last modified.
3166 This holds the name of the month in which the primary @file{.texi} file
3170 The @file{version.texi} support requires the @code{mdate-sh} program;
3171 this program is supplied with Automake and automatically included when
3172 @code{automake} is invoked with the @code{--add-missing} option.
3174 If you have multiple Texinfo files, and you want to use the
3175 @file{version.texi} feature, then you have to have a separate version
3176 file for each Texinfo file. Automake will treat any include in a
3177 Texinfo file that matches @samp{vers*.texi} just as an automatically
3178 generated version file.
3180 When an info file is rebuilt, the program named by the @code{MAKEINFO}
3181 variable is used to invoke it. If the @code{makeinfo} program is found
3182 on the system then it will be used by default; otherwise @code{missing}
3183 will be used instead. The flags in the variables @code{MAKEINFOFLAGS}
3184 and @code{AM_MAKEINFOFLAGS} will be passed to the @code{makeinfo}
3185 invocation; the first of these is intended for use by the user
3186 (@pxref{User Variables}) and the second by the @file{Makefile.am}
3189 @vindex MAKEINFOFLAGS
3190 @vindex AM_MAKEINFOFLAGS
3192 Sometimes an info file actually depends on more than one @file{.texi}
3193 file. For instance, in GNU Hello, @file{hello.texi} includes the file
3194 @file{gpl.texi}. You can tell Automake about these dependencies using
3195 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
3200 info_TEXINFOS = hello.texi
3201 hello_TEXINFOS = gpl.texi
3206 By default, Automake requires the file @file{texinfo.tex} to appear in
3207 the same directory as the Texinfo source. However, if you used
3208 @code{AC_CONFIG_AUX_DIR} in @file{configure.in} (@pxref{Input, , Finding
3209 `configure' Input, autoconf, The Autoconf Manual}), then
3210 @file{texinfo.tex} is looked for there. Automake supplies
3211 @file{texinfo.tex} if @samp{--add-missing} is given.
3215 If your package has Texinfo files in many directories, you can use the
3216 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
3217 @file{texinfo.tex} for your package. The value of this variable should
3218 be the relative path from the current @file{Makefile.am} to
3222 TEXINFO_TEX = ../doc/texinfo.tex
3225 @opindex no-texinfo.tex
3227 The option @samp{no-texinfo.tex} can be used to eliminate the
3228 requirement for @file{texinfo.tex}. Use of the variable
3229 @code{TEXINFO_TEX} is preferable, however, because that allows the
3230 @code{dvi} target to still work.
3232 @cindex Target, install-info
3233 @cindex Target, noinstall-info
3234 @cindex install-info target
3235 @cindex noinstall-info target
3237 @opindex no-installinfo
3238 @trindex install-info
3240 Automake generates an @code{install-info} target; some people apparently
3241 use this. By default, info pages are installed by @samp{make install}.
3242 This can be prevented via the @code{no-installinfo} option.
3245 @node Man pages, , Texinfo, Documentation
3248 @cindex _MANS primary, defined
3249 @cindex MANS primary, defined
3250 @cindex Primary variable, MANS
3252 A package can also include man pages (but see the GNU standards on this
3253 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
3254 pages are declared using the @samp{MANS} primary. Generally the
3255 @code{man_MANS} macro is used. Man pages are automatically installed in
3256 the correct subdirectory of @code{mandir}, based on the file extension.
3260 File extensions such as @samp{.1c} are handled by looking for the valid
3261 part of the extension and using that to determine the correct
3262 subdirectory of @code{mandir}. Valid section names are the digits
3263 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
3265 Sometimes developers prefer to name a man page something like
3266 @file{foo.man} in the source, and then rename it to have the correct
3267 suffix, e.g. @file{foo.1}, when installing the file. Automake also
3268 supports this mode. For a valid section named @var{SECTION}, there is a
3269 corresponding directory named @samp{man@var{SECTION}dir}, and a
3270 corresponding @samp{_MANS} variable. Files listed in such a variable
3271 are installed in the indicated section. If the file already has a
3272 valid suffix, then it is installed as-is; otherwise the file suffix is
3273 changed to match the section.
3275 For instance, consider this example:
3277 man1_MANS = rename.man thesame.1 alsothesame.1c
3280 In this case, @file{rename.man} will be renamed to @file{rename.1} when
3281 installed, but the other files will keep their names.
3283 @cindex Target, install-man
3284 @cindex Target, noinstall-man
3285 @cindex install-man target
3286 @cindex noinstall-man target
3288 @c Use @samp{make install} per documentation: (texi)code.
3289 By default, man pages are installed by @samp{make install}. However,
3290 since the GNU project does not require man pages, many maintainers do
3291 not expend effort to keep the man pages up to date. In these cases, the
3292 @code{no-installman} option will prevent the man pages from being
3293 installed by default. The user can still explicitly install them via
3294 @samp{make install-man}.
3295 @opindex no-installman
3296 @trindex install-man
3298 Here is how the man pages are handled in GNU @code{cpio} (which includes
3299 both Texinfo documentation and man pages):
3302 man_MANS = cpio.1 mt.1
3303 EXTRA_DIST = $(man_MANS)
3306 Man pages are not currently considered to be source, because it is not
3307 uncommon for man pages to be automatically generated. Therefore they
3308 are not automatically included in the distribution. However, this can
3309 be changed by use of the @samp{dist_} prefix.
3311 The @samp{nobase_} prefix is meaningless for man pages and is
3315 @node Install, Clean, Documentation, Top
3316 @chapter What Gets Installed
3318 @cindex Installation support
3319 @cindex make install support
3321 Naturally, Automake handles the details of actually installing your
3322 program once it has been built. All files named by the various
3323 primaries are automatically installed in the appropriate places when the
3324 user runs @code{make install}.
3326 A file named in a primary is installed by copying the built file into
3327 the appropriate directory. The base name of the file is used when
3331 bin_PROGRAMS = hello subdir/goodbye
3334 In this example, both @samp{hello} and @samp{goodbye} will be installed
3335 in @code{$(bindir)}.
3337 Sometimes it is useful to avoid the basename step at install time. For
3338 instance, you might have a number of header files in subdirectories of
3339 the source tree which are laid out precisely how you want to install
3340 them. In this situation you can use the @samp{nobase_} prefix to
3341 suppress the base name step. For example:
3344 include_HEADERS = stdio.h sys/types.h
3347 Will include @file{stdio.h} in @code{$(includedir)} and @file{types.h}
3348 in @code{$(includedir)/sys}.
3350 Automake generates separate @code{install-data} and @code{install-exec}
3351 targets, in case the installer is installing on multiple machines which
3352 share directory structure---these targets allow the machine-independent
3353 parts to be installed only once. The @code{install} target depends on
3354 both of these targets.
3355 @trindex install-data
3356 @trindex install-exec
3359 Automake also generates an @code{uninstall} target, an
3360 @code{installdirs} target, and an @code{install-strip} target.
3362 @trindex installdirs
3363 @trindex install-strip
3365 It is possible to extend this mechanism by defining an
3366 @code{install-exec-local} or @code{install-data-local} target. If these
3367 targets exist, they will be run at @samp{make install} time.
3368 @trindex install-exec-local
3369 @trindex install-data-local
3371 Variables using the standard directory prefixes @samp{data},
3372 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
3373 @samp{pkgdata}, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
3374 installed by @samp{install-data}.
3376 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
3377 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
3378 @samp{pkglib} (e.g. @samp{bin_PROGRAMS}) are installed by
3379 @samp{install-exec}.
3381 Any variable using a user-defined directory prefix with @samp{exec} in
3382 the name (e.g. @samp{myexecbin_PROGRAMS} is installed by
3383 @samp{install-exec}. All other user-defined prefixes are installed by
3384 @samp{install-data}.
3387 Automake generates support for the @samp{DESTDIR} variable in all
3388 install rules. @samp{DESTDIR} is used during the @samp{make install}
3389 step to relocate install objects into a staging area. Each object and
3390 path is prefixed with the value of @samp{DESTDIR} before being copied
3391 into the install area. Here is an example of typical DESTDIR usage:
3394 make DESTDIR=/tmp/staging install
3397 This places install objects in a directory tree built under
3398 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
3399 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
3400 would install @file{/tmp/staging/gnu/bin/foo} and
3401 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
3403 This feature is commonly used to build install images and packages. For
3404 more information, see @ref{Makefile Conventions, , , standards, The GNU
3408 @node Clean, Dist, Install, Top
3409 @chapter What Gets Cleaned
3411 @cindex make clean support
3413 The GNU Makefile Standards specify a number of different clean rules.
3415 Generally the files that can be cleaned are determined automatically by
3416 Automake. Of course, Automake also recognizes some variables that can
3417 be defined to specify additional files to clean. These variables are
3418 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
3419 @code{MAINTAINERCLEANFILES}.
3420 @vindex MOSTLYCLEANFILES
3422 @vindex DISTCLEANFILES
3423 @vindex MAINTAINERCLEANFILES
3425 As the GNU Standards aren't always explicit as to which files should be
3426 removed by which target, we've adopted a heuristic which we believe were
3427 first formulated by Fran@,{c}ois Pinard:
3431 If @code{make} built it, and it is commonly something that one would
3432 want to rebuild (for instance, a @file{.o} file), then
3433 @code{mostlyclean} should delete it.
3436 Otherwise, if @code{make} built it, then @code{clean} should delete it.
3439 If @code{configure} built it, then @code{distclean} should delete it
3442 If the maintainer built it, then @code{maintainer-clean} should
3446 We recommend that you follow this same set of heuristics in your
3450 @node Dist, Tests, Clean, Top
3451 @chapter What Goes in a Distribution
3454 @cindex make distcheck
3456 The @code{dist} target in the generated @file{Makefile.in} can be used
3457 to generate a gzip'd @code{tar} file for distribution. The tar file is
3458 named based on the @samp{PACKAGE} and @samp{VERSION} variables; more
3459 precisely it is named @samp{@var{package}-@var{version}.tar.gz}.
3463 You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
3464 is run. The default setting is @samp{--best}.
3466 For the most part, the files to distribute are automatically found by
3467 Automake: all source files are automatically included in a distribution,
3468 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
3469 has a built-in list of commonly used files which, if present in the
3470 current directory, are automatically included. This list is printed by
3471 @samp{automake --help}. Also, files which are read by @code{configure}
3472 (i.e. the source files corresponding to the files specified in the
3473 @code{AC_OUTPUT} invocation) are automatically distributed.
3475 Still, sometimes there are files which must be distributed, but which
3476 are not covered in the automatic rules. These files should be listed in
3477 the @code{EXTRA_DIST} variable. You can mention files from
3478 subdirectories in @code{EXTRA_DIST}. You can also mention a directory
3479 there; in this case the entire directory will be recursively copied into
3480 the distribution. Please note that this will also copy
3481 @emph{everything} in the directory, including CVS/RCS version control
3486 Sometimes you need tighter control over what does @emph{not} go into the
3487 distribution; for instance you might have source files which are
3488 generated and which you do not want to distribute. In this case
3489 Automake gives fine-grained control using the @samp{dist} and
3490 @samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
3491 prefixed with @samp{dist_} to add the listed files to the distribution.
3492 Similarly, @samp{nodist_} can be used to omit the files from the
3497 As an example, here is how you would cause some data to be distributed
3498 while leaving some source code out of the distribution:
3501 dist_data_DATA = distribute-this
3503 nodist_foo_SOURCES = do-not-distribute.c
3506 Another way to to use this is for removing unnecessary files that get
3507 recursively included by specifying a directory in EXTRA_DIST:
3513 rm -rf `find $(distdir)/doc -name CVS`
3516 If you define @code{SUBDIRS}, Automake will recursively include the
3517 subdirectories in the distribution. If @code{SUBDIRS} is defined
3518 conditionally (@pxref{Conditionals}), Automake will normally include all
3519 directories that could possibly appear in @code{SUBDIRS} in the
3520 distribution. If you need to specify the set of directories
3521 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
3522 list of subdirectories to include in the distribution.
3523 @vindex DIST_SUBDIRS
3527 Occasionally it is useful to be able to change the distribution before
3528 it is packaged up. If the @code{dist-hook} target exists, it is run
3529 after the distribution directory is filled, but before the actual tar
3530 (or shar) file is created. One way to use this is for distributing
3531 files in subdirectories for which a new @file{Makefile.am} is overkill:
3535 mkdir $(distdir)/random
3536 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
3539 Automake also generates a @code{distcheck} target which can be of help
3540 to ensure that a given distribution will actually work.
3541 @code{distcheck} makes a distribution, and then tries to do a
3545 If the target @code{distcheck-hook} is defined in your
3546 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
3547 the new distribution has been unpacked, but before the unpacked copy is
3548 configured and built. Your @code{distcheck-hook} can do almost
3549 anything, though as always caution is advised. Generally this hook is
3550 used to check for potential distribution errors not caught by the
3554 @node Tests, Options, Dist, Top
3555 @chapter Support for test suites
3560 Automake supports two forms of test suites.
3562 @section Simple Tests
3564 If the variable @code{TESTS} is defined, its value is taken to be a list
3565 of programs to run in order to do the testing. The programs can either
3566 be derived objects or source objects; the generated rule will look both
3567 in @code{srcdir} and @file{.}. Programs needing data files should look
3568 for them in @code{srcdir} (which is both an environment variable and a
3569 make variable) so they work when building in a separate directory
3570 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
3571 Manual}), and in particular for the @code{distcheck} target
3574 @cindex Exit status 77, special interpretation
3576 The number of failures will be printed at the end of the run. If a
3577 given test program exits with a status of 77, then its result is ignored
3578 in the final count. This feature allows non-portable tests to be
3579 ignored in environments where they don't make sense.
3581 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
3582 variables for the test run; the environment variable @code{srcdir} is
3583 set in the rule. If all your test programs are scripts, you can also
3584 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
3585 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
3587 @vindex TESTS_ENVIRONMENT
3589 @cindex Tests, expected failure
3590 @cindex Expected test failure
3592 You may define the variable @code{XFAIL_TESTS} to a list of tests
3593 (usually a subset of @code{TESTS}) that are expected to fail. This will
3594 reverse the result of those tests.
3597 Automake ensures that each program listed in @code{TESTS} is built
3598 before any tests are run; you can list both source and derived programs
3599 in @code{TESTS}. For instance, you might want to run a C program as a
3600 test. To do this you would list its name in @code{TESTS} and also in
3601 @code{check_PROGRAMS}, and then specify it as you would any other
3604 @section DejaGNU Tests
3606 If @uref{ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz,
3607 @samp{dejagnu}} appears in @code{AUTOMAKE_OPTIONS}, then a
3608 @code{dejagnu}-based test suite is assumed. The variable
3609 @code{DEJATOOL} is a list of names which are passed, one at a time, as
3610 the @code{--tool} argument to @code{runtest} invocations; it defaults to
3611 the name of the package.
3613 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
3614 @code{--srcdir} flags that are passed to dejagnu by default; this can be
3615 overridden if necessary.
3616 @vindex RUNTESTDEFAULTFLAGS
3618 The variables @code{EXPECT} and @code{RUNTEST} can
3619 also be overridden to provide project-specific values. For instance,
3620 you will need to do this if you are testing a compiler toolchain,
3621 because the default values do not take into account host and target
3628 The contents of the variable @code{RUNTESTFLAGS} are passed to the
3629 @code{runtest} invocation. This is considered a ``user variable''
3630 (@pxref{User Variables}). If you need to set @code{runtest} flags in
3631 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
3632 @vindex RUNTESTFLAGS
3633 @vindex AM_RUNTESTFLAGS
3634 @c FIXME xref dejagnu
3636 In either case, the testing is done via @samp{make check}.
3639 @node Options, Miscellaneous, Tests, Top
3640 @chapter Changing Automake's Behavior
3642 Various features of Automake can be controlled by options in the
3643 @file{Makefile.am}. Such options are listed in a special variable named
3644 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
3645 @vindex AUTOMAKE_OPTIONS
3650 @itemx @code{foreign}
3652 @cindex Option, gnits
3654 @cindex Option, foreign
3655 @cindex Option, cygnus
3657 Set the strictness as appropriate. The @code{gnits} option also implies
3658 @code{readme-alpha} and @code{check-news}.
3660 @item @code{ansi2knr}
3661 @itemx @code{path/ansi2knr}
3662 @cindex Option, ansi2knr
3663 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
3664 path, the generated @file{Makefile.in} will look in the specified
3665 directory to find the @file{ansi2knr} program. Generally the path
3666 should be a relative path to another directory in the same distribution
3667 (though Automake currently does not check this).
3669 @item @code{check-news}
3670 @cindex Option, check-news
3671 Cause @code{make dist} to fail unless the current version number appears
3672 in the first few lines of the @file{NEWS} file.
3674 @item @code{dejagnu}
3675 @cindex Option, dejagnu
3676 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
3678 @item @code{dist-bzip2}
3679 @cindex Option, dist-bzip2
3680 Generate a @code{dist-bzip2} target as well as the ordinary @code{dist}
3681 target. This new target will create a bzip2 tar archive of the
3682 distribution. bzip2 archives are frequently smaller than even gzipped
3686 @item @code{dist-shar}
3687 @cindex Option, dist-shar
3688 Generate a @code{dist-shar} target as well as the ordinary @code{dist}
3689 target. This new target will create a shar archive of the
3693 @item @code{dist-zip}
3694 @cindex Option, dist-zip
3695 Generate a @code{dist-zip} target as well as the ordinary @code{dist}
3696 target. This new target will create a zip archive of the distribution.
3699 @item @code{dist-tarZ}
3700 @cindex Option, dist-tarZ
3701 Generate a @code{dist-tarZ} target as well as the ordinary @code{dist}
3702 target. This new target will create a compressed tar archive of the
3706 @item @code{no-dependencies}
3707 @cindex Option, no-dependencies
3708 This is similar to using @samp{--include-deps} on the command line, but
3709 is useful for those situations where you don't have the necessary bits
3710 to make automatic dependency tracking work @xref{Dependencies}. In this
3711 case the effect is to effectively disable automatic dependency tracking.
3713 @item @code{no-exeext}
3714 @cindex Option, no-exeext
3715 If your @file{Makefile.am} defines a target @samp{foo}, it will override
3716 a target named @samp{foo$(EXEEXT)}. This is necessary when
3717 @code{EXEEXT} is found to be empty. However, by default automake will
3718 generate an error for this use. The @code{no-exeext} option will
3719 disable this error. This is intended for use only where it is known in
3720 advance that the package will not be ported to Windows, or any other
3721 operating system using extensions on executables.
3723 @item @code{no-installinfo}
3724 @cindex Option, no-installinfo
3725 The generated @file{Makefile.in} will not cause info pages to be built
3726 or installed by default. However, @code{info} and @code{install-info}
3727 targets will still be available. This option is disallowed at
3728 @samp{GNU} strictness and above.
3730 @trindex install-info
3732 @item @code{no-installman}
3733 @cindex Option, no-installman
3734 The generated @file{Makefile.in} will not cause man pages to be
3735 installed by default. However, an @code{install-man} target will still
3736 be available for optional installation. This option is disallowed at
3737 @samp{GNU} strictness and above.
3738 @trindex install-man
3740 @item @code{nostdinc}
3741 @cindex Option, nostdinc
3742 This option can be used to disable the standard @samp{-I} options which
3743 are ordinarily automatically provided by Automake.
3745 @item @code{no-texinfo.tex}
3746 @cindex Option, no-texinfo
3747 Don't require @file{texinfo.tex}, even if there are texinfo files in
3750 @item @code{readme-alpha}
3751 @cindex Option, readme-alpha
3752 If this release is an alpha release, and the file @file{README-alpha}
3753 exists, then it will be added to the distribution. If this option is
3754 given, version numbers are expected to follow one of two forms. The
3755 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
3756 element is a number; the final period and number should be left off for
3757 non-alpha releases. The second form is
3758 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
3759 letter; it should be omitted for non-alpha releases.
3761 @item @code{subdir-objects}
3762 If this option is specified, then objects are placed into the
3763 subdirectory of the build directory corresponding to the subdirectory of
3764 the source file. For instance if the source file is
3765 @file{subdir/file.cxx}, then the output file would be
3766 @file{subdir/file.o}.
3769 @cindex Option, version
3770 A version number (e.g. @samp{0.30}) can be specified. If Automake is not
3771 newer than the version specified, creation of the @file{Makefile.in}
3775 Unrecognized options are diagnosed by @code{automake}.
3778 @node Miscellaneous, Include, Options, Top
3779 @chapter Miscellaneous Rules
3781 There are a few rules and variables that didn't fit anywhere else.
3784 * Tags:: Interfacing to etags and mkid
3785 * Suffixes:: Handling new file extensions
3786 * Multilibs:: Support for multilibbing.
3790 @node Tags, Suffixes, Miscellaneous, Miscellaneous
3791 @section Interfacing to @code{etags}
3793 @cindex TAGS support
3795 Automake will generate rules to generate @file{TAGS} files for use with
3796 GNU Emacs under some circumstances.
3798 If any C, C++ or Fortran 77 source code or headers are present, then
3799 @code{tags} and @code{TAGS} targets will be generated for the directory.
3802 At the topmost directory of a multi-directory package, a @code{tags}
3803 target file will be generated which, when run, will generate a
3804 @file{TAGS} file that includes by reference all @file{TAGS} files from
3807 Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
3808 will be generated. This variable is intended for use in directories
3809 which contain taggable source that @code{etags} does not understand.
3812 Here is how Automake generates tags for its source, and for nodes in its
3816 ETAGS_ARGS = automake.in --lang=none \
3817 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
3820 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
3821 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
3822 are added directly to the dependencies for the @code{tags} target.
3823 @vindex TAGS_DEPENDENCIES
3825 Automake will also generate an @code{ID} target which will run
3826 @code{mkid} on the source. This is only supported on a
3827 directory-by-directory basis.
3830 Automake also supports the @uref{http://www.gnu.org/software/global/,
3831 GNU Global Tags program}. The @code{GTAGS} target runs Global Tags
3832 automatically and puts the result in the top build directory. The
3833 variable @code{GTAGS_ARGS} holds arguments which are passed to
3838 @node Suffixes, Multilibs, Tags, Miscellaneous
3839 @section Handling new file extensions
3841 @cindex Adding new SUFFIXES
3842 @cindex SUFFIXES, adding
3844 It is sometimes useful to introduce a new implicit rule to handle a file
3845 type that Automake does not know about. If this is done, you must
3846 notify GNU Make of the new suffixes. This can be done by putting a list
3847 of new suffixes in the @code{SUFFIXES} variable.
3850 For instance, suppose you had a compiler which could compile @samp{.foo}
3851 files to @samp{.o} files. Then you would add @samp{.foo} to your suffix
3858 Then you could directly use a @samp{.foo} file in a @samp{_SOURCES}
3859 variable and expect the correct results:
3863 doit_SOURCES = doit.foo
3866 Any given @code{SUFFIXES} go at the start of the generated suffixes
3867 list, followed by automake generated suffixes not already in the list.
3870 @node Multilibs, , Suffixes, Miscellaneous
3871 @section Support for Multilibs
3873 Automake has support for an obscure feature called multilibs. A
3874 @dfn{multilib} is a library which is built for multiple different ABIs
3875 at a single time; each time the library is built with a different target
3876 flag combination. This is only useful when the library is intended to
3877 be cross-compiled, and it is almost exclusively used for compiler
3880 The multilib support is still experimental. Only use it if you are
3881 familiar with multilibs and can debug problems you might encounter.
3884 @node Include, Conditionals, Miscellaneous, Top
3888 @cindex Including Makefile fragment
3889 @cindex Makefile fragment, including
3891 Automake supports an @code{include} directive which can be used to
3892 include other @file{Makefile} fragments when @code{automake} is run.
3893 Note that these fragments are read and interpreted by @code{automake},
3894 not by @code{make}. As with conditionals, @code{make} has no idea that
3895 @code{include} is in use.
3897 There are two forms of @code{include}:
3900 @item include $(srcdir)/file
3901 Include a fragment which is found relative to the current source
3904 @item include $(top_srcdir)/file
3905 Include a fragment which is found relative to the top source directory.
3908 Note that if a fragment is included inside a conditional, then the
3909 condition applies to the entire contents of that fragment.
3912 @node Conditionals, Gnits, Include, Top
3913 @chapter Conditionals
3915 @cindex Conditionals
3917 Automake supports a simple type of conditionals.
3919 @cvindex AM_CONDITIONAL
3920 Before using a conditional, you must define it by using
3921 @code{AM_CONDITIONAL} in the @code{configure.in} file (@pxref{Macros}).
3923 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
3924 The conditional name, @var{conditional}, should be a simple string
3925 starting with a letter and containing only letters, digits, and
3926 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
3927 which are reserved by Automake.
3929 The shell @var{condition} (suitable for use in a shell @code{if}
3930 statement) is evaluated when @code{configure} is run.
3933 @cindex --enable-debug, example
3934 @cindex Example conditional --enable-debug
3935 @cindex Conditional example, --enable-debug
3937 Conditionals typically depend upon options which the user provides to
3938 the @code{configure} script. Here is an example of how to write a
3939 conditional which is true if the user uses the @samp{--enable-debug}
3943 AC_ARG_ENABLE(debug,
3944 [ --enable-debug Turn on debugging],
3945 [case "$@{enableval@}" in
3948 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
3949 esac],[debug=false])
3950 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
3953 Here is an example of how to use that conditional in @file{Makefile.am}:
3965 noinst_PROGRAMS = $(DBG)
3968 This trivial example could also be handled using EXTRA_PROGRAMS
3969 (@pxref{A Program}).
3971 You may only test a single variable in an @code{if} statement, possibly
3972 negated using @samp{!}. The @code{else} statement may be omitted.
3973 Conditionals may be nested to any depth. You may specify an argument to
3974 @code{else} in which case it must be the negation of the condition used
3975 for the current @code{if}. Similarly you may specify the condition
3976 which is closed by an @code{end}:
3987 Unbalanced conditions are errors.
3989 Note that conditionals in Automake are not the same as conditionals in
3990 GNU Make. Automake conditionals are checked at configure time by the
3991 @file{configure} script, and affect the translation from
3992 @file{Makefile.in} to @file{Makefile}. They are based on options passed
3993 to @file{configure} and on results that @file{configure} has discovered
3994 about the host system. GNU Make conditionals are checked at @code{make}
3995 time, and are based on variables passed to the make program or defined
3996 in the @file{Makefile}.
3998 Automake conditionals will work with any make program.
4001 @node Gnits, Cygnus, Conditionals, Top
4002 @chapter The effect of @code{--gnu} and @code{--gnits}
4004 @cindex --gnu, required files
4005 @cindex --gnu, complete description
4007 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
4008 variable) causes @code{automake} to check the following:
4012 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
4013 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
4014 directory of the package.
4017 The options @samp{no-installman} and @samp{no-installinfo} are
4021 Note that this option will be extended in the future to do even more
4022 checking; it is advisable to be familiar with the precise requirements
4023 of the GNU standards. Also, @samp{--gnu} can require certain
4024 non-standard GNU programs to exist for use by various maintainer-only
4025 targets; for instance in the future @code{pathchk} might be required for
4028 @cindex --gnits, complete description
4030 The @samp{--gnits} option does everything that @samp{--gnu} does, and
4031 checks the following as well:
4035 @samp{make dist} will check to make sure the @file{NEWS} file has been
4036 updated to the current version.
4039 @samp{VERSION} is checked to make sure its format complies with Gnits
4041 @c FIXME xref when standards are finished
4044 @cindex README-alpha
4045 If @samp{VERSION} indicates that this is an alpha release, and the file
4046 @file{README-alpha} appears in the topmost directory of a package, then
4047 it is included in the distribution. This is done in @samp{--gnits}
4048 mode, and no other, because this mode is the only one where version
4049 number formats are constrained, and hence the only mode where Automake
4050 can automatically determine whether @file{README-alpha} should be
4054 The file @file{THANKS} is required.
4058 @node Cygnus, Extending, Gnits, Top
4059 @chapter The effect of @code{--cygnus}
4061 @cindex Cygnus strictness
4063 Cygnus Solutions has slightly different rules for how a
4064 @file{Makefile.in} is to be constructed. Passing @samp{--cygnus} to
4065 @code{automake} will cause any generated @file{Makefile.in} to comply
4068 Here are the precise effects of @samp{--cygnus}:
4072 Info files are always created in the build directory, and not in the
4076 @file{texinfo.tex} is not required if a Texinfo source file is
4077 specified. The assumption is that the file will be supplied, but in a
4078 place that Automake cannot find. This assumption is an artifact of how
4079 Cygnus packages are typically bundled.
4082 @samp{make dist} will look for files in the build directory as well as
4083 the source directory. This is required to support putting info files
4084 into the build directory.
4087 Certain tools will be searched for in the build tree as well as in the
4088 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
4089 @code{makeinfo} and @code{texi2dvi}.
4092 @code{--foreign} is implied.
4095 The options @samp{no-installinfo} and @samp{no-dependencies} are
4099 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
4103 The @code{check} target doesn't depend on @code{all}.
4106 GNU maintainers are advised to use @samp{gnu} strictness in preference
4107 to the special Cygnus mode.
4110 @node Extending, Distributing, Cygnus, Top
4111 @chapter When Automake Isn't Enough
4113 Automake's implicit copying semantics means that many problems can be
4114 worked around by simply adding some @code{make} targets and rules to
4115 @file{Makefile.in}. Automake will ignore these additions.
4117 @cindex -local targets
4118 @cindex local targets
4120 There are some caveats to doing this. Although you can overload a
4121 target already used by Automake, it is often inadvisable, particularly
4122 in the topmost directory of a package with subdirectories. However,
4123 various useful targets have a @samp{-local} version you can specify in
4124 your @file{Makefile.in}. Automake will supplement the standard target
4125 with these user-supplied targets.
4130 @trindex check-local
4131 @trindex install-data-local
4132 @trindex install-exec-local
4133 @trindex uninstall-local
4134 @trindex mostlyclean-local
4135 @trindex clean-local
4136 @trindex distclean-local
4138 The targets that support a local version are @code{all}, @code{info},
4139 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
4140 @code{uninstall}, and the various @code{clean} targets
4141 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
4142 @code{maintainer-clean}). Note that there are no
4143 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
4144 use @code{uninstall-local}. It doesn't make sense to uninstall just
4145 data or just executables.
4150 @trindex install-data
4151 @trindex install-exec
4154 For instance, here is one way to install a file in @file{/etc}:
4158 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
4161 @cindex -hook targets
4162 @cindex hook targets
4164 Some targets also have a way to run another target, called a @dfn{hook},
4165 after their work is done. The hook is named after the principal target,
4166 with @samp{-hook} appended. The targets allowing hooks are
4167 @code{install-data}, @code{install-exec}, @code{dist}, and
4169 @trindex install-data-hook
4170 @trindex install-exec-hook
4173 For instance, here is how to create a hard link to an installed program:
4177 ln $(bindir)/program $(bindir)/proglink
4180 @c FIXME should include discussion of variables you can use in these
4184 @node Distributing, Macro and Variable Index, Extending, Top
4185 @chapter Distributing @file{Makefile.in}s
4187 Automake places no restrictions on the distribution of the resulting
4188 @file{Makefile.in}s. We still encourage software authors to distribute
4189 their work under terms like those of the GPL, but doing so is not
4190 required to use Automake.
4192 Some of the files that can be automatically installed via the
4193 @code{--add-missing} switch do fall under the GPL. However, these also
4194 have a special exception allowing you to distribute them with your
4195 package, regardless of the licensing you choose.
4199 @node Macro and Variable Index, General Index, Distributing, Top
4200 @unnumbered Macro and Variable Index
4206 @node General Index, , Macro and Variable Index, Top
4207 @unnumbered General Index