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
1195 If Automake sees that this variable is set in @file{configure.in}, it
1196 will check the @file{po} directory to ensure that all the named
1197 @samp{.po} files exist, and that all the @samp{.po} files that exist are
1199 @cvindex ALL_LINGUAS
1201 @item AM_C_PROTOTYPES
1202 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
1203 @cvindex AM_C_PROTOTYPES
1205 @item AM_GNU_GETTEXT
1206 This macro is required for packages which use GNU gettext
1207 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1208 this macro it ensures that the package meets some of gettext's
1210 @cvindex AM_GNU_GETTEXT
1212 @item AM_MAINTAINER_MODE
1213 @opindex --enable-maintainer-mode
1214 This macro adds a @samp{--enable-maintainer-mode} option to
1215 @code{configure}. If this is used, @code{automake} will cause
1216 @samp{maintainer-only} rules to be turned off by default in the
1217 generated @file{Makefile.in}s. This macro is disallowed in @samp{Gnits}
1218 mode (@pxref{Gnits}). This macro defines the @samp{MAINTAINER_MODE}
1219 conditional, which you can use in your own @file{Makefile.am}.
1220 @cvindex AM_MAINTAINER_MODE
1223 @itemx AC_CHECK_TOOL
1224 @itemx AC_CHECK_PROG
1225 @itemx AC_CHECK_PROGS
1227 @itemx AC_PATH_PROGS
1228 For each of these macros, the first argument is automatically defined as
1229 a variable in each generated @file{Makefile.in}. @xref{Setting Output
1230 Variables, , Setting Output Variables, autoconf, The Autoconf Manual},
1231 and @ref{Generic Programs, , Generic Program Checks, autoconf, The
1234 @cvindex AC_CHECK_TOOL
1235 @cvindex AC_CHECK_PROG
1236 @cvindex AC_CHECK_PROGS
1237 @cvindex AC_PATH_PROG
1238 @cvindex AC_PATH_PROGS
1243 @node Invoking aclocal, Macros, Optional, configure
1244 @section Auto-generating aclocal.m4
1246 @cindex Invoking aclocal
1247 @cindex aclocal, Invoking
1249 Automake includes a number of Autoconf macros which can be used in your
1250 package; some of them are actually required by Automake in certain
1251 situations. These macros must be defined in your @file{aclocal.m4};
1252 otherwise they will not be seen by @code{autoconf}.
1254 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1255 files based on the contents of @file{configure.in}. This provides a
1256 convenient way to get Automake-provided macros, without having to
1257 search around. Also, the @code{aclocal} mechanism is extensible for use
1260 At startup, @code{aclocal} scans all the @file{.m4} files it can find,
1261 looking for macro definitions. Then it scans @file{configure.in}. Any
1262 mention of one of the macros found in the first step causes that macro,
1263 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1265 The contents of @file{acinclude.m4}, if it exists, are also
1266 automatically included in @file{aclocal.m4}. This is useful for
1267 incorporating local macros into @file{configure}.
1269 @code{aclocal} tries to be smart about looking for new @code{AC_DEFUN}s
1270 in the files it scans. It will warn if it finds duplicates. It also
1271 tries to copy the full text of the scanned file into @file{aclocal.m4},
1272 including both @samp{#} and @samp{dnl} comments. If you want to make a
1273 comment which will be completely ignored by @code{aclocal}, use
1274 @samp{##} as the comment leader.
1276 @code{aclocal} accepts the following options:
1279 @item --acdir=@var{dir}
1281 Look for the macro files in @var{dir} instead of the installation
1282 directory. This is typically used for debugging.
1286 Print a summary of the command line options and exit.
1290 Add the directory @var{dir} to the list of directories searched for
1293 @item --output=@var{file}
1295 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1297 @item --print-ac-dir
1298 @opindex --print-ac-dir
1299 Prints the name of the directory which @code{aclocal} will search to
1300 find the @file{.m4} files. When this option is given, normal processing
1301 is suppressed. This option can be used by a package to determine where
1302 to install a macro file.
1306 Print the names of the files it examines.
1310 Print the version number of Automake and exit.
1314 @node Macros, Extending aclocal, Invoking aclocal, configure
1315 @section Autoconf macros supplied with Automake
1317 @c consider generating this node automatically from m4 files.
1320 @item AM_CONFIG_HEADER
1321 Automake will generate rules to automatically regenerate the config
1322 header. If you do use this macro, you must create the file
1323 @file{stamp-h.in} in your source directory. It can be empty.
1324 @cvindex AM_CONFIG_HEADER
1326 @item AM_ENABLE_MULTILIB
1327 This is used when a ``multilib'' library is being built. The first
1328 optional argument is the name of the @file{Makefile} being generated; it
1329 defaults to @samp{Makefile}. The second option argument is used to find
1330 the top source directory; it defaults to the empty string (generally
1331 this should not be used unless you are familiar with the internals).
1334 @item _AM_DEPENDENCIES
1335 @itemx AM_SET_DEPDIR
1337 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
1338 These macros are used to implement automake's automatic dependency
1339 tracking scheme. They are called automatically by automake when
1340 required, and there should be no need to invoke them manually.
1342 @item AM_FUNC_STRTOD
1343 If the @code{strtod} function is not available, or does not work
1344 correctly (like the one on SunOS 5.4), add @file{strtod.o} to output
1345 variable @code{LIBOBJS}.
1346 @cvindex AM_FUNC_STRTOD
1348 @item AM_FUNC_ERROR_AT_LINE
1349 If the function @code{error_at_line} is not found, then add
1350 @file{error.o} to @code{LIBOBJS}.
1351 @cvindex AM_FUNC_ERROR_AT_LINE
1353 @item AM_FUNC_OBSTACK
1354 Check for the GNU obstacks code; if not found, add @file{obstack.o} to
1356 @cvindex AM_FUNC_OBSTACK
1358 @item AM_C_PROTOTYPES
1359 Check to see if function prototypes are understood by the compiler. If
1360 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1361 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1362 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1363 values to implement automatic de-ANSI-fication.
1364 @cvindex AM_C_PROTOTYPES
1366 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1367 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1368 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1369 found in @file{<termios.h>}.
1370 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1372 @item AM_INIT_AUTOMAKE
1373 Runs many macros that most @file{configure.in}'s need. This macro has
1374 two required arguments, the package and the version number. By default
1375 this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}. This
1376 can be avoided by passing in a non-empty third argument.
1378 @item AM_MAKE_INCLUDE
1379 This macro is used to discover how the user's @code{make} handles
1380 @code{include} statements. This macro is automatically invoked when
1381 needed; there should be no need to invoke it manually.
1383 @item AM_PATH_LISPDIR
1384 Searches for the program @code{emacs}, and, if found, sets the output
1385 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1386 @cvindex AM_PATH_LISPDIR
1389 Use this macro when you have assembly code in your project. This will
1390 choose the assembler for you (by default the C compiler), and will set
1391 @code{ASFLAGS} if required.
1393 @item AM_PROG_CC_C_O
1394 This is like @code{AC_PROG_CC_C_O}, but it generates its results in the
1395 manner required by automake. You must use this instead of
1396 @code{AC_PROG_CC_C_O} when you need this functionality.
1398 @item AM_PROG_CC_STDC
1399 If the C compiler in not in ANSI C mode by default, try to add an option
1400 to output variable @code{CC} to make it so. This macro tries various
1401 options that select ANSI C on some system or another. It considers the
1402 compiler to be in ANSI C mode if it handles function prototypes correctly.
1404 If you use this macro, you should check after calling it whether the C
1405 compiler has been set to accept ANSI C; if not, the shell variable
1406 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1407 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1408 @code{ansi2knr} option (@pxref{ANSI}).
1411 @cindex HP-UX 10, lex problems
1412 @cindex lex problems with HP-UX 10
1413 Like @code{AC_PROG_LEX} with @code{AC_DECL_YYTEXT} (@pxref{Particular
1414 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}),
1415 but uses the @code{missing} script on systems that do not have
1416 @code{lex}. @samp{HP-UX 10} is one such system.
1418 Autoconf 2.50 and higher, in order to simplify the interface, includes
1419 the body of @code{AC_DECL_YYTEXT} in @code{AC_PROG_LEX}. To ensure
1420 backward compatibility, @code{AC_DECL_YYTEXT} is nevertheless defined as
1421 an invocation of @code{AC_PROG_LEX}. Since @code{AM_PROG_LEX} invokes
1422 both, it causes an annoying but benign warning (@code{AC_PROG_LEX}
1423 invoked multiple times) which you should just ignore. In the future,
1424 once Automake requires Autoconf 2.50, this issue will be fixed, but the
1425 current compatibility with Autoconf 2.13 prevents this.
1428 This macro finds the @code{gcj} program or causes an error. It sets
1429 @samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
1430 GNU Compiler Collection.
1431 @cvindex AM_PROG_GCJ
1433 @item AM_PROG_INSTALL_STRIP
1434 This is used to find a version of @code{install} which can be used to
1435 @code{strip} a program at installation time. This macro is
1436 automatically included when required.
1438 @item AM_SANITY_CHECK
1439 This checks to make sure that a file created in the build directory is
1440 newer than a file in the source directory. This can fail on systems
1441 where the clock is set incorrectly. This macro is automatically run
1442 from @code{AM_INIT_AUTOMAKE}.
1444 @item AM_SYS_POSIX_TERMIOS
1445 @cvindex am_cv_sys_posix_termios
1446 @cindex POSIX termios headers
1447 @cindex termios POSIX headers
1448 Check to see if POSIX termios headers and functions are available on the
1449 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1450 @samp{yes}. If not, set the variable to @samp{no}.
1452 @item AM_TYPE_PTRDIFF_T
1453 @cvindex HAVE_PTRDIFF_T
1455 Define @samp{HAVE_PTRDIFF_T} if the type @samp{ptrdiff_t} is defined in
1458 @item AM_WITH_DMALLOC
1459 @cvindex WITH_DMALLOC
1460 @cindex dmalloc, support for
1461 @opindex --with-dmalloc
1463 @uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
1464 package. If the user configures with @samp{--with-dmalloc}, then define
1465 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
1469 @opindex --with-regex
1470 @cindex regex package
1472 Adds @samp{--with-regex} to the @code{configure} command line. If
1473 specified (the default), then the @samp{regex} regular expression
1474 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1475 @samp{WITH_REGEX} is defined.. If @samp{--without-regex} is given, then
1476 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1477 into @samp{LIBOBJS}.
1482 @node Extending aclocal, , Macros, configure
1483 @section Writing your own aclocal macros
1485 @cindex aclocal, extending
1486 @cindex Extending aclocal
1488 The @code{aclocal} program doesn't have any built-in knowledge of any
1489 macros, so it is easy to extend it with your own macros.
1491 This is mostly used for libraries which want to supply their own
1492 Autoconf macros for use by other programs. For instance the
1493 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1494 should be used by any package using @code{gettext}. When the library is
1495 installed, it installs this macro so that @code{aclocal} will find it.
1497 A file of macros should be a series of @code{AC_DEFUN}'s. The
1498 @code{aclocal} programs also understands @code{AC_REQUIRE}, so it is
1499 safe to put each macro in a separate file. @xref{Prerequisite Macros, ,
1500 , autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
1501 autoconf, The Autoconf Manual}.
1503 A macro file's name should end in @file{.m4}. Such files should be
1504 installed in @file{$(datadir)/aclocal}.
1507 @node Top level, Alternative, configure, Top
1508 @chapter The top-level @file{Makefile.am}
1510 @cindex SUBDIRS, explained
1512 In packages with subdirectories, the top level @file{Makefile.am} must
1513 tell Automake which subdirectories are to be built. This is done via
1514 the @code{SUBDIRS} variable.
1517 The @code{SUBDIRS} macro holds a list of subdirectories in which
1518 building of various sorts can occur. Many targets (e.g. @code{all}) in
1519 the generated @file{Makefile} will run both locally and in all specified
1520 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1521 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1522 (after configuration). This allows inclusion of libraries from packages
1523 which do not use Automake (such as @code{gettext}). The directories
1524 mentioned in @code{SUBDIRS} must be direct children of the current
1525 directory. For instance, you cannot put @samp{src/subdir} into
1528 In packages that use subdirectories, the top-level @file{Makefile.am} is
1529 often very short. For instance, here is the @file{Makefile.am} from the
1530 GNU Hello distribution:
1533 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1534 SUBDIRS = doc intl po src tests
1537 @cindex SUBDIRS, overriding
1538 @cindex Overriding SUBDIRS
1540 It is possible to override the @code{SUBDIRS} variable if, like in the
1541 case of GNU @code{Inetutils}, you want to only build a subset of the
1542 entire package. In your @file{Makefile.am} include:
1545 SUBDIRS = @@MY_SUBDIRS@@
1548 Then in your @file{configure.in} you can specify:
1551 MY_SUBDIRS="src doc lib po"
1552 AC_SUBST(MY_SUBDIRS)
1555 (Note that we don't use the variable name @code{SUBDIRS} in our
1556 @file{configure.in}; that would cause Automake to believe that every
1557 @file{Makefile.in} should recurse into the listed subdirectories.)
1559 The upshot of this is that Automake is tricked into building the package
1560 to take the subdirs, but doesn't actually bind that list until
1561 @code{configure} is run.
1563 Although the @code{SUBDIRS} macro can contain configure substitutions
1564 (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
1565 contents of this variable.
1567 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1568 @code{AC_PROG_MAKE_SET}. When Automake invokes @code{make} in a
1569 subdirectory, it uses the value of the @code{MAKE} variable. It passes
1570 the value of the variable @code{AM_MAKEFLAGS} to the @code{make}
1571 invocation; this can be set in @file{Makefile.am} if there are flags you
1572 must always pass to @code{make}.
1576 The use of @code{SUBDIRS} is not restricted to just the top-level
1577 @file{Makefile.am}. Automake can be used to construct packages of
1580 By default, Automake generates @file{Makefiles} which work depth-first
1581 (@samp{postfix}). However, it is possible to change this ordering. You
1582 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
1583 putting @samp{.} first will cause a @samp{prefix} ordering of
1584 directories. All @samp{clean} targets are run in reverse order of build
1587 Sometimes, such as when running @code{make dist}, you want all possible
1588 subdirectories to be examined. In this case Automake will use
1589 @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to
1590 recurse. This variable will also be used when the user runs
1591 @code{distclean} or @code{maintainer-clean}. It should be set to the
1592 full list of subdirectories in the project. If this macro is not set,
1593 Automake will attempt to set it for you.
1596 @node Alternative, Rebuilding, Top level, Top
1597 @chapter An Alternative Approach to Subdirectories
1599 If you've ever read Peter Miller's excellent paper,
1600 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
1601 Recursive Make Considered Harmful}, the preceding section on the use of
1602 subdirectories will probably come as unwelcome advice. For those who
1603 haven't read the paper, Miller's main thesis is that recursive
1604 @code{make} invocations are both slow and error-prone.
1606 Automake provides sufficient cross-directory support @footnote{We
1607 believe. This work is new and there are probably warts.
1608 @xref{Introduction}, for information on reporting bugs.} to enable you
1609 to write a single @file{Makefile.am} for a complex multi-directory
1613 By default an installable file specified in a subdirectory will have its
1614 directory name stripped before installation. For instance, in this
1615 example, the header file will be installed as
1616 @file{$(includedir)/stdio.h}:
1619 include_HEADERS = inc/stdio.h
1623 @cindex Path stripping, avoiding
1624 @cindex Avoiding path stripping
1626 However, the @samp{nobase_} prefix can be used to circumvent this path
1627 stripping. In this example, the header file will be installed as
1628 @file{$(includedir)/sys/types.h}:
1631 nobase_include_HEADERS = sys/types.h
1635 @node Rebuilding, Programs, Alternative, Top
1636 @chapter Rebuilding Makefiles
1638 Automake generates rules to automatically rebuild @file{Makefile}s,
1639 @file{configure}, and other derived files like @file{Makefile.in}.
1641 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.in}, then
1642 these automatic rebuilding rules are only enabled in maintainer mode.
1644 Sometimes you need to run @code{aclocal} with an argument like @code{-I}
1645 to tell it where to find @file{.m4} files. Since sometimes @code{make}
1646 will automatically run @code{aclocal}, you need a way to specify these
1647 arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this
1648 holds arguments which are passed verbatim to @code{aclocal}. This macro
1649 is only useful in the top-level @file{Makefile.am}.
1650 @cindex ACLOCAL_AMFLAGS
1653 @node Programs, Other objects, Rebuilding, Top
1654 @chapter Building Programs and Libraries
1656 A large part of Automake's functionality is dedicated to making it easy
1657 to build programs and libraries.
1660 * A Program:: Building a program
1661 * A Library:: Building a library
1662 * Program and Library Variables::
1663 Variables controlling program and
1665 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1666 * A Shared Library:: Building a Libtool library
1667 * Program variables:: Variables used when building a program
1668 * Yacc and Lex:: Yacc and Lex support
1670 * Assembly Support::
1671 * Fortran 77 Support::
1673 * Support for Other Languages::
1674 * ANSI:: Automatic de-ANSI-fication
1675 * Dependencies:: Automatic dependency tracking
1679 @node A Program, A Library, Programs, Programs
1680 @section Building a program
1682 @cindex PROGRAMS, bindir
1683 @vindex bin_PROGRAMS
1684 @vindex sbin_PROGRAMS
1685 @vindex libexec_PROGRAMS
1686 @vindex pkglib_PROGRAMS
1687 @vindex noinst_PROGRAMS
1689 In a directory containing source that gets built into a program (as
1690 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
1691 can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
1692 @code{pkglibdir}, or not at all (@samp{noinst}). They can also be built
1693 only for @code{make check}, in which case the prefix is @samp{check}.
1698 bin_PROGRAMS = hello
1701 In this simple case, the resulting @file{Makefile.in} will contain code
1702 to generate a program named @code{hello}.
1704 Associated with each program are several assisting variables which are
1705 named after the program. These variables are all optional, and have
1706 reasonable defaults. Each variable, its use, and default is spelled out
1707 below; we use the ``hello'' example throughout.
1709 The variable @code{hello_SOURCES} is used to specify which source files
1710 get built into an executable:
1713 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1716 This causes each mentioned @samp{.c} file to be compiled into the
1717 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1719 @cindex _SOURCES primary, defined
1720 @cindex SOURCES primary, defined
1721 @cindex Primary variable, SOURCES
1723 If @samp{hello_SOURCES} is not specified, then it defaults to the single
1724 file @file{hello.c}; that is, the default is to compile a single C file
1725 whose base name is the name of the program itself. (This is a terrible
1726 default but we are stuck with it for historical reasons.)
1730 Multiple programs can be built in a single directory. Multiple programs
1731 can share a single source file, which must be listed in each
1732 @samp{_SOURCES} definition.
1734 @cindex Header files in _SOURCES
1735 @cindex _SOURCES and header files
1737 Header files listed in a @samp{_SOURCES} definition will be included in
1738 the distribution but otherwise ignored. In case it isn't obvious, you
1739 should not include the header file generated by @file{configure} in an
1740 @samp{_SOURCES} variable; this file should not be distributed. Lex
1741 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1744 You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
1745 @samp{_SOURCES} variable. The reason for this is a bit hard to explain,
1746 but suffice to say that it simply won't work. Automake will give an
1747 error if you try to do this.
1749 @cindex EXTRA_prog_SOURCES, defined
1751 Automake must know all the source files that could possibly go into a
1752 program, even if not all the files are built in every circumstance.
1753 Any files which are only conditionally built should be listed in the
1754 appropriate @samp{EXTRA_} variable. For instance, if
1755 @file{hello-linux.c} were conditionally included in @code{hello}, the
1756 @file{Makefile.am} would contain:
1759 EXTRA_hello_SOURCES = hello-linux.c
1762 Similarly, sometimes it is useful to determine the programs that are to
1763 be built at configure time. For instance, GNU @code{cpio} only builds
1764 @code{mt} and @code{rmt} under special circumstances.
1766 @cindex EXTRA_PROGRAMS, defined
1768 In this case, you must notify Automake of all the programs that can
1769 possibly be built, but at the same time cause the generated
1770 @file{Makefile.in} to use the programs specified by @code{configure}.
1771 This is done by having @code{configure} substitute values into each
1772 @samp{_PROGRAMS} definition, while listing all optionally built programs
1773 in @code{EXTRA_PROGRAMS}.
1774 @vindex EXTRA_PROGRAMS
1776 If you need to link against libraries that are not found by
1777 @code{configure}, you can use @code{LDADD} to do so. This variable
1778 actually can be used to add any options to the linker command line.
1781 @cindex prog_LDADD, defined
1783 Sometimes, multiple programs are built in one directory but do not share
1784 the same link-time requirements. In this case, you can use the
1785 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1786 program as it appears in some @samp{_PROGRAMS} variable, and usually
1787 written in lowercase) to override the global @code{LDADD}. If this
1788 variable exists for a given program, then that program is not linked
1792 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
1793 linked against the library @file{libcpio.a}. However, @code{rmt} is
1794 built in the same directory, and has no such link requirement. Also,
1795 @code{mt} and @code{rmt} are only built on certain architectures. Here
1796 is what cpio's @file{src/Makefile.am} looks like (abridged):
1799 bin_PROGRAMS = cpio pax @@MT@@
1800 libexec_PROGRAMS = @@RMT@@
1801 EXTRA_PROGRAMS = mt rmt
1803 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1806 cpio_SOURCES = @dots{}
1807 pax_SOURCES = @dots{}
1808 mt_SOURCES = @dots{}
1809 rmt_SOURCES = @dots{}
1812 @cindex _LDFLAGS, defined
1814 @samp{@var{prog}_LDADD} is inappropriate for passing program-specific
1815 linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
1816 @samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
1820 @cindex _DEPENDENCIES, defined
1822 It is also occasionally useful to have a program depend on some other
1823 target which is not actually part of that program. This can be done
1824 using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
1825 on the contents of such a variable, but no further interpretation is
1828 If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
1829 Automake. The automatically-assigned value is the contents of
1830 @samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
1831 @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
1832 configure substitutions that are left in are only @samp{@@LIBOBJS@@} and
1833 @samp{@@ALLOCA@@}; these are left because it is known that they will not
1834 cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
1838 @node A Library, Program and Library Variables, A Program, Programs
1839 @section Building a library
1841 @cindex _LIBRARIES primary, defined
1842 @cindex LIBRARIES primary, defined
1843 @cindex Primary variable, LIBRARIES
1845 @vindex lib_LIBRARIES
1846 @vindex pkglib_LIBRARIES
1847 @vindex noinst_LIBRARIES
1849 Building a library is much like building a program. In this case, the
1850 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
1851 @code{libdir} or @code{pkglibdir}.
1853 @xref{A Shared Library}, for information on how to build shared
1854 libraries using Libtool and the @samp{LTLIBRARIES} primary.
1856 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
1857 For instance to create a library named @file{libcpio.a}, but not install
1858 it, you would write:
1861 noinst_LIBRARIES = libcpio.a
1864 The sources that go into a library are determined exactly as they are
1865 for programs, via the @samp{_SOURCES} variables. Note that the library
1866 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
1867 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
1868 not @samp{liblob.a_SOURCES}.
1870 @cindex _LIBADD primary, defined
1871 @cindex LIBADD primary, defined
1872 @cindex Primary variable, LIBADD
1874 Extra objects can be added to a library using the
1875 @samp{@var{library}_LIBADD} variable. This should be used for objects
1876 determined by @code{configure}. Again from @code{cpio}:
1881 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
1884 In addition, sources for extra objects that will not exist until
1885 configure-time must be added to the @code{BUILT_SOURCES} variable
1889 @node Program and Library Variables, LIBOBJS, A Library, Programs
1890 @section Program and Library Variables
1892 Associated with each program are a collection of variables which can be
1893 used to modify how that program is built. There is a similar list of
1894 such variables for each library. The canonical name of the program (or
1895 library) is used as a base for naming these variables.
1897 In the list below, we use the name ``maude'' to refer to the program or
1898 library. In your @file{Makefile.am} you would replace this with the
1899 canonical name of your program. This list also refers to ``maude'' as a
1900 program, but in general the same rules apply for both static and dynamic
1901 libraries; the documentation below notes situations where programs and
1906 This variable, if it exists, lists all the source files which are
1907 compiled to build the program. These files are added to the
1908 distribution by default. When building the program, Automake will cause
1909 each source file to be compiled to a single @file{.o} file (or
1910 @file{.lo} when using libtool). Normally these object files are named
1911 after the source file, but other factors can change this. If a file in
1912 the @samp{_SOURCES} variable has an unrecognized extension, Automake
1913 will do one of two things with it. If a suffix rule exists for turning
1914 files with the unrecognized extension into @file{.o} files, then
1915 automake will treat this file as it will any other source file
1916 (@pxref{Support for Other Languages}). Otherwise, the file will be
1917 ignored as though it were a header file.
1919 The prefixes @samp{dist_} and @samp{nodist_} can be used to control
1920 whether files listed in a @samp{_SOURCES} variable are distributed.
1921 @samp{dist_} is redundant, as sources are distributed by default, but it
1922 can be specified for clarity if desired.
1924 It is possible to have both @samp{dist_} and @samp{nodist_} variants of
1925 a given @samp{_SOURCES} variable at once; this lets you easily
1926 distribute some files and not others, for instance:
1929 nodist_maude_SOURCES = nodist.c
1930 dist_maude_SOURCES = dist-me.c
1933 By default the output file (on Unix systems, the @file{.o} file) will be
1934 put into the current build directory. However, if the option
1935 @code{subdir-objects} is in effect in the current directory then the
1936 @file{.o} file will be put into the subdirectory named after the source
1937 file. For instance, with @code{subdir-objects} enabled,
1938 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
1939 people prefer this mode of operation. You can specify
1940 @code{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
1941 @cindex Subdirectory, objects in
1942 @cindex Objects in subdirectory
1945 @item EXTRA_maude_SOURCES
1946 Automake needs to know the list of files you intend to compile
1947 @emph{statically}. For one thing, this is the only way Automake has of
1948 knowing what sort of language support a given @file{Makefile.in}
1949 requires. @footnote{There are other, more obscure reasons reasons for
1950 this limitation as well.} This means that, for example, you can't put a
1951 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
1952 variable. If you intend to conditionally compile source files and use
1953 @file{configure} to substitute the appropriate object names into, e.g.,
1954 @samp{_LDADD} (see below), then you should list the corresponding source
1955 files in the @samp{EXTRA_} variable.
1957 This variable also supports @samp{dist_} and @samp{nodist_} prefixes,
1958 e.g., @samp{nodist_EXTRA_maude_SOURCES}.
1961 A static library is created by default by invoking @code{$(AR) cru}
1962 followed by the name of the library and then the objects being put into
1963 the library. You can override this by setting the @samp{_AR} variable.
1964 This is usually used with C++; some C++ compilers require a special
1965 invocation in order to instantiate all the templates which should go
1966 into a library. For instance, the SGI C++ compiler likes this macro set
1969 libmaude_a_AR = $(CXX) -ar -o
1973 Extra objects can be added to a static library using the @samp{_LIBADD}
1974 variable. This should be used for objects determined by
1975 @code{configure}. Note that @samp{_LIBADD} is not used for shared
1976 libraries; there you must use @samp{_LDADD}.
1979 Extra objects can be added to a shared library or a program by listing
1980 them in the @samp{_LDADD} variable. This should be used for objects
1981 determined by @code{configure}.
1983 @samp{_LDADD} is inappropriate for passing program-specific linker flags
1984 (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen}).
1985 Use the @samp{_LDFLAGS} variable for this purpose.
1987 For instance, if your @file{configure.in} uses @code{AC_PATH_XTRA}, you
1988 could link your program against the X libraries like so:
1991 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
1995 This variable is used to pass extra flags to the link step of a program
1996 or a shared library.
1999 You can override the linker on a per-program basis. By default the
2000 linker is chosen according to the languages used by the program. For
2001 instance, a program that includes C++ source code would use the C++
2002 compiler to link. The @samp{_LINK} variable must hold the name of a
2003 command which can be passed all the @file{.o} file names as arguments.
2004 Note that the name of the underlying program is @emph{not} passed to
2005 @samp{_LINK}; typically one uses @samp{$@@}:
2008 maude_LINK = $(CCLD) -magic -o $@
2012 Automake allows you to set compilation flags on a per-program (or
2013 per-library) basis. A single source file can be included in several
2014 programs, and it will potentially be compiled with different flags for
2015 each program. This works for any language directly supported by
2016 Automake. The flags are @samp{_CFLAGS}, @samp{_CXXFLAGS},
2017 @samp{_OBJCFLAGS}, @samp{_YFLAGS}, @samp{_ASFLAGS}, @samp{_FFLAGS},
2018 @samp{_RFLAGS}, and @samp{_GCJFLAGS}.
2020 When using a per-program compilation flag, Automake will choose a
2021 different name for the intermediate object files. Ordinarily a file
2022 like @file{sample.c} will be compiled to produce @file{sample.o}.
2023 However, if the program's @samp{_CFLAGS} variable is set, then the
2024 object file will be named, for instance, @file{maude-sample.o}.
2026 In compilations with per-program flags, the ordinary @samp{AM_} form of
2027 the flags variable is @emph{not} automatically included in the
2028 compilation (however, the user form of the variable @emph{is} included).
2029 So for instance, if you want the hypothetical @file{maude} compilations
2030 to also use the value of @samp{AM_CFLAGS}, you would need to write:
2033 maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
2036 @item maude_DEPENDENCIES
2037 It is also occasionally useful to have a program depend on some other
2038 target which is not actually part of that program. This can be done
2039 using the @samp{_DEPENDENCIES} variable. Each program depends on the
2040 contents of such a variable, but no further interpretation is done.
2042 If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake.
2043 The automatically-assigned value is the contents of @samp{_LDADD}, with
2044 most configure substitutions, @samp{-l}, @samp{-L}, @samp{-dlopen} and
2045 @samp{-dlpreopen} options removed. The configure substitutions that are
2046 left in are only @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are
2047 left because it is known that they will not cause an invalid value for
2048 @samp{_DEPENDENCIES} to be generated.
2050 @item maude_SHORTNAME
2051 On some platforms the allowable file names are very short. In order to
2052 support these systems and per-program compilation flags at the same
2053 time, Automake allows you to set a ``short name'' which will influence
2054 how intermediate object files are named. For instance, if you set
2055 @samp{maude_SHORTNAME} to @samp{m}, then in the above per-program
2056 compilation flag example the object file would be named
2057 @file{m-sample.o} rather than @file{maude-sample.o}. This facility is
2058 rarely needed in practice, and we recommend avoiding it until you find
2063 @node LIBOBJS, A Shared Library, Program and Library Variables, Programs
2064 @section Special handling for LIBOBJS and ALLOCA
2066 @cindex @@LIBOBJS@@, special handling
2067 @cindex @@ALLOCA@@, special handling
2069 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
2070 @code{@@ALLOCA@@}, and uses this information, plus the list of
2071 @code{LIBOBJS} files derived from @file{configure.in} to automatically
2072 include the appropriate source files in the distribution (@pxref{Dist}).
2073 These source files are also automatically handled in the
2074 dependency-tracking scheme; see @xref{Dependencies}.
2076 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
2077 @samp{_LDADD} or @samp{_LIBADD} variable.
2080 @node A Shared Library, Program variables, LIBOBJS, Programs
2081 @section Building a Shared Library
2083 @cindex Shared libraries, support for
2085 Building shared libraries is a relatively complex matter. For this
2086 reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
2087 Libtool Manual}) was created to help build shared libraries in a
2088 platform-independent way.
2090 @cindex _LTLIBRARIES primary, defined
2091 @cindex LTLIBRARIES primary, defined
2092 @cindex Primary variable, LTLIBRARIES
2093 @cindex Example of shared libraries
2095 @cindex suffix .la, defined
2097 Automake uses Libtool to build libraries declared with the
2098 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
2099 of shared libraries to build. For instance, to create a library named
2100 @file{libgettext.a} and its corresponding shared libraries, and install
2101 them in @samp{libdir}, write:
2104 lib_LTLIBRARIES = libgettext.la
2107 @vindex lib_LTLIBRARIES
2108 @vindex pkglib_LTLIBRARIES
2109 @vindex noinst_LTLIBRARIES
2110 @vindex check_LTLIBRARIES
2112 @cindex check_LTLIBRARIES, not allowed
2114 Note that shared libraries @emph{must} be installed, so
2115 @code{check_LTLIBRARIES} is not allowed. However,
2116 @code{noinst_LTLIBRARIES} is allowed. This feature should be used for
2117 libtool ``convenience libraries''.
2119 @cindex suffix .lo, defined
2121 For each library, the @samp{@var{library}_LIBADD} variable contains the
2122 names of extra libtool objects (@file{.lo} files) to add to the shared
2123 library. The @samp{@var{library}_LDFLAGS} variable contains any
2124 additional libtool flags, such as @samp{-version-info} or
2127 @cindex @@LTLIBOBJS@@, special handling
2129 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
2130 library must use @code{@@LTLIBOBJS@@}. This is required because the
2131 object files that libtool operates on do not necessarily end in
2132 @file{.o}. The libtool manual contains more details on this topic.
2134 For libraries installed in some directory, Automake will automatically
2135 supply the appropriate @samp{-rpath} option. However, for libraries
2136 determined at configure time (and thus mentioned in
2137 @code{EXTRA_LTLIBRARIES}), Automake does not know the eventual
2138 installation directory; for such libraries you must add the
2139 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
2142 Ordinarily, Automake requires that a shared library's name start with
2143 @samp{lib}. However, if you are building a dynamically loadable module
2144 then you might wish to use a "nonstandard" name. In this case, put
2145 @code{-module} into the @samp{_LDFLAGS} variable.
2147 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
2148 libtool, The Libtool Manual}, for more information.
2151 @node Program variables, Yacc and Lex, A Shared Library, Programs
2152 @section Variables used when building a program
2154 Occasionally it is useful to know which @file{Makefile} variables
2155 Automake uses for compilations; for instance you might need to do your
2156 own compilation in some special cases.
2158 Some variables are inherited from Autoconf; these are @code{CC},
2159 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
2163 There are some additional variables which Automake itself defines:
2167 The contents of this macro are passed to every compilation which invokes
2168 the C preprocessor; it is a list of arguments to the preprocessor. For
2169 instance, @samp{-I} and @samp{-D} options should be listed here.
2171 Automake already provides some @samp{-I} options automatically. In
2172 particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I}
2173 pointing to the directory holding @file{config.h} (if you've used
2174 @code{AC_CONFIG_HEADER} or @code{AM_CONFIG_HEADER}). You can disable
2175 the default @samp{-I} options using the @samp{nostdinc} option.
2178 This does the same job as @samp{AM_CPPFLAGS}. It is an older name for
2179 the same functionality. This macro is deprecated; we suggest using
2180 @samp{AM_CPPFLAGS} instead.
2183 This is the command used to actually compile a C source file. The
2184 filename is appended to form the complete command line.
2187 This is the command used to actually link a C program.
2191 @node Yacc and Lex, C++ Support, Program variables, Programs
2192 @section Yacc and Lex support
2194 Automake has somewhat idiosyncratic support for Yacc and Lex.
2196 Automake assumes that the @file{.c} file generated by @code{yacc} (or
2197 @code{lex}) should be named using the basename of the input file. That
2198 is, for a yacc source file @file{foo.y}, Automake will cause the
2199 intermediate file to be named @file{foo.c} (as opposed to
2200 @file{y.tab.c}, which is more traditional).
2202 The extension of a yacc source file is used to determine the extension
2203 of the resulting @samp{C} or @samp{C++} file. Files with the extension
2204 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
2205 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
2208 Likewise, lex source files can be used to generate @samp{C} or
2209 @samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
2210 @samp{.lxx} are recognized.
2212 You should never explicitly mention the intermediate (@samp{C} or
2213 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
2216 The intermediate files generated by @code{yacc} (or @code{lex}) will be
2217 included in any distribution that is made. That way the user doesn't
2218 need to have @code{yacc} or @code{lex}.
2220 If a @code{yacc} source file is seen, then your @file{configure.in} must
2221 define the variable @samp{YACC}. This is most easily done by invoking
2222 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
2223 Program Checks, autoconf, The Autoconf Manual}).
2225 When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
2226 @samp{AM_YFLAGS}. The former is a user variable and the latter is
2227 intended for the @file{Makefile.am} author.
2229 Similarly, if a @code{lex} source file is seen, then your
2230 @file{configure.in} must define the variable @samp{LEX}. You can use
2231 @samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
2232 Program Checks, autoconf, The Autoconf Manual}). Automake's @code{lex}
2233 support also requires that you use the @samp{AC_DECL_YYTEXT}
2234 macro---automake needs to know the value of @samp{LEX_OUTPUT_ROOT}.
2235 This is all handled for you if you use the @code{AM_PROG_LEX} macro
2238 When @code{yacc} is invoked, it is passed @samp{LFLAGS} and
2239 @samp{AM_LFLAGS}. The former is a user variable and the latter is
2240 intended for the @file{Makefile.am} author.
2245 @cindex yacc, multiple parsers
2246 @cindex Multiple yacc parsers
2247 @cindex Multiple lex lexers
2248 @cindex lex, multiple lexers
2251 Automake makes it possible to include multiple @code{yacc} (or
2252 @code{lex}) source files in a single program. Automake uses a small
2253 program called @code{ylwrap} to run @code{yacc} (or @code{lex}) in a
2254 subdirectory. This is necessary because yacc's output filename is
2255 fixed, and a parallel make could conceivably invoke more than one
2256 instance of @code{yacc} simultaneously. The @code{ylwrap} program is
2257 distributed with Automake. It should appear in the directory specified
2258 by @samp{AC_CONFIG_AUX_DIR} (@pxref{Input, , Finding `configure' Input,
2259 autoconf, The Autoconf Manual}), or the current directory if that macro
2260 is not used in @file{configure.in}.
2262 For @code{yacc}, simply managing locking is insufficient. The output of
2263 @code{yacc} always uses the same symbol names internally, so it isn't
2264 possible to link two @code{yacc} parsers into the same executable.
2266 We recommend using the following renaming hack used in @code{gdb}:
2268 #define yymaxdepth c_maxdepth
2269 #define yyparse c_parse
2271 #define yyerror c_error
2272 #define yylval c_lval
2273 #define yychar c_char
2274 #define yydebug c_debug
2275 #define yypact c_pact
2282 #define yyexca c_exca
2283 #define yyerrflag c_errflag
2284 #define yynerrs c_nerrs
2288 #define yy_yys c_yys
2289 #define yystate c_state
2292 #define yy_yyv c_yyv
2294 #define yylloc c_lloc
2295 #define yyreds c_reds
2296 #define yytoks c_toks
2297 #define yylhs c_yylhs
2298 #define yylen c_yylen
2299 #define yydefred c_yydefred
2300 #define yydgoto c_yydgoto
2301 #define yysindex c_yysindex
2302 #define yyrindex c_yyrindex
2303 #define yygindex c_yygindex
2304 #define yytable c_yytable
2305 #define yycheck c_yycheck
2306 #define yyname c_yyname
2307 #define yyrule c_yyrule
2310 For each define, replace the @samp{c_} prefix with whatever you like.
2311 These defines work for @code{bison}, @code{byacc}, and traditional
2312 @code{yacc}s. If you find a parser generator that uses a symbol not
2313 covered here, please report the new name so it can be added to the list.
2316 @node C++ Support, Assembly Support, Yacc and Lex, Programs
2317 @section C++ Support
2320 @cindex Support for C++
2322 Automake includes full support for C++.
2324 Any package including C++ code must define the output variable
2325 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
2326 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
2327 Program Checks, autoconf, The Autoconf Manual}).
2329 A few additional variables are defined when a C++ source file is seen:
2333 The name of the C++ compiler.
2336 Any flags to pass to the C++ compiler.
2339 The command used to actually compile a C++ source file. The file name
2340 is appended to form the complete command line.
2343 The command used to actually link a C++ program.
2347 @node Assembly Support, Fortran 77 Support, C++ Support, Programs
2348 @section Assembly Support
2350 Automake includes some support for assembly code.
2352 The variable @code{AS} holds the name of the compiler used to build
2353 assembly code. This compiler must work a bit like a C compiler; in
2354 particular it must accept @samp{-c} and @samp{-o}. The value of
2355 @code{ASFLAGS} is passed to the compilation.
2359 You are required to set @code{AS} and @code{ASFLAGS} via
2360 @file{configure.in}. The autoconf macro @code{AM_PROG_AS} will do this
2361 for you. Unless they are already set, it simply sets @code{AS} to the C
2362 compiler and @code{ASFLAGS} to the C compiler flags.
2365 @node Fortran 77 Support, Java Support, Assembly Support, Programs
2366 @comment node-name, next, previous, up
2367 @section Fortran 77 Support
2369 @cindex Fortran 77 support
2370 @cindex Support for Fortran 77
2372 Automake includes full support for Fortran 77.
2374 Any package including Fortran 77 code must define the output variable
2375 @samp{F77} in @file{configure.in}; the simplest way to do this is to use
2376 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
2377 Program Checks, autoconf, The Autoconf Manual}). @xref{Fortran 77 and
2380 A few additional variables are defined when a Fortran 77 source file is
2386 The name of the Fortran 77 compiler.
2389 Any flags to pass to the Fortran 77 compiler.
2392 Any flags to pass to the Ratfor compiler.
2395 The command used to actually compile a Fortran 77 source file. The file
2396 name is appended to form the complete command line.
2399 The command used to actually link a pure Fortran 77 program or shared
2404 Automake can handle preprocessing Fortran 77 and Ratfor source files in
2405 addition to compiling them@footnote{Much, if not most, of the
2406 information in the following sections pertaining to preprocessing
2407 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
2408 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
2409 also contains some support for creating programs and shared libraries
2410 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
2411 Fortran 77 With C and C++}).
2413 These issues are covered in the following sections.
2416 * Preprocessing Fortran 77::
2417 * Compiling Fortran 77 Files::
2418 * Mixing Fortran 77 With C and C++::
2419 * Fortran 77 and Autoconf::
2423 @node Preprocessing Fortran 77, Compiling Fortran 77 Files, Fortran 77 Support, Fortran 77 Support
2424 @comment node-name, next, previous, up
2425 @subsection Preprocessing Fortran 77
2427 @cindex Preprocessing Fortran 77
2428 @cindex Fortran 77, Preprocessing
2429 @cindex Ratfor programs
2431 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
2432 rule runs just the preprocessor to convert a preprocessable Fortran 77
2433 or Ratfor source file into a strict Fortran 77 source file. The precise
2434 command used is as follows:
2439 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2442 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2447 @node Compiling Fortran 77 Files, Mixing Fortran 77 With C and C++, Preprocessing Fortran 77, Fortran 77 Support
2448 @comment node-name, next, previous, up
2449 @subsection Compiling Fortran 77 Files
2451 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
2452 @file{N.r} by running the Fortran 77 compiler. The precise command used
2458 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
2461 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2464 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2469 @node Mixing Fortran 77 With C and C++, Fortran 77 and Autoconf, Compiling Fortran 77 Files, Fortran 77 Support
2470 @comment node-name, next, previous, up
2471 @subsection Mixing Fortran 77 With C and C++
2473 @cindex Fortran 77, mixing with C and C++
2474 @cindex Mixing Fortran 77 with C and C++
2475 @cindex Linking Fortran 77 with C and C++
2477 @cindex Mixing Fortran 77 with C and/or C++
2479 Automake currently provides @emph{limited} support for creating programs
2480 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
2481 However, there are many other issues related to mixing Fortran 77 with
2482 other languages that are @emph{not} (currently) handled by Automake, but
2483 that are handled by other packages@footnote{For example,
2484 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
2485 addresses all of these inter-language issues, and runs under nearly all
2486 Fortran 77, C and C++ compilers on nearly all platforms. However,
2487 @code{cfortran} is not yet Free Software, but it will be in the next
2491 Automake can help in two ways:
2495 Automatic selection of the linker depending on which combinations of
2499 Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
2500 @samp{-l}) to pass to the automatically selected linker in order to link
2501 in the appropriate Fortran 77 intrinsic and run-time libraries.
2503 @cindex FLIBS, defined
2504 These extra Fortran 77 linker flags are supplied in the output variable
2505 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
2506 supplied with newer versions of Autoconf (Autoconf version 2.13 and
2507 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
2511 If Automake detects that a program or shared library (as mentioned in
2512 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
2513 code that is a mixture of Fortran 77 and C and/or C++, then it requires
2514 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
2515 @file{configure.in}, and that either @code{$(FLIBS)} or @code{@@FLIBS@@}
2516 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
2517 (for shared libraries) variables. It is the responsibility of the
2518 person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
2519 or @code{@@FLIBS@@} appears in the appropriate @code{_LDADD} or
2520 @code{_LIBADD} variable.
2522 @cindex Mixed language example
2523 @cindex Example, mixed language
2525 For example, consider the following @file{Makefile.am}:
2529 foo_SOURCES = main.cc foo.f
2530 foo_LDADD = libfoo.la @@FLIBS@@
2532 pkglib_LTLIBRARIES = libfoo.la
2533 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
2534 libfoo_la_LIBADD = $(FLIBS)
2537 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
2538 is mentioned in @file{configure.in}. Also, if @code{@@FLIBS@@} hadn't
2539 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
2540 Automake would have issued a warning.
2545 * How the Linker is Chosen::
2548 @node How the Linker is Chosen, , Mixing Fortran 77 With C and C++, Mixing Fortran 77 With C and C++
2549 @comment node-name, next, previous, up
2550 @subsubsection How the Linker is Chosen
2552 @cindex Automatic linker selection
2553 @cindex Selecting the linker automatically
2555 The following diagram demonstrates under what conditions a particular
2556 linker is chosen by Automake.
2558 For example, if Fortran 77, C and C++ source code were to be compiled
2559 into a program, then the C++ linker will be used. In this case, if the
2560 C or Fortran 77 linkers required any special libraries that weren't
2561 included by the C++ linker, then they must be manually added to an
2562 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
2568 code \ C C++ Fortran
2569 ----------------- +---------+---------+---------+
2573 +---------+---------+---------+
2577 +---------+---------+---------+
2581 +---------+---------+---------+
2585 +---------+---------+---------+
2587 C + Fortran | | | x |
2589 +---------+---------+---------+
2591 C++ + Fortran | | x | |
2593 +---------+---------+---------+
2595 C + C++ + Fortran | | x | |
2597 +---------+---------+---------+
2601 @node Fortran 77 and Autoconf, , Mixing Fortran 77 With C and C++, Fortran 77 Support
2602 @comment node-name, next, previous, up
2603 @subsection Fortran 77 and Autoconf
2605 The current Automake support for Fortran 77 requires a recent enough
2606 version Autoconf that also includes support for Fortran 77. Full
2607 Fortran 77 support was added to Autoconf 2.13, so you will want to use
2608 that version of Autoconf or later.
2611 @node Java Support, Support for Other Languages, Fortran 77 Support, Programs
2612 @comment node-name, next, previous, up
2613 @section Java Support
2615 @cindex Java support
2616 @cindex Support for Java
2618 Automake includes support for compiled Java, using @code{gcj}, the Java
2619 front end to the GNU Compiler Collection.
2621 Any package including Java code to be compiled must define the output
2622 variable @samp{GCJ} in @file{configure.in}; the variable @samp{GCJFLAGS}
2623 must also be defined somehow (either in @file{configure.in} or
2624 @file{Makefile.am}). The simplest way to do this is to use the
2625 @code{AM_PROG_GCJ} macro.
2629 By default, programs including Java source files are linked with
2632 As always, the contents of @samp{AM_GCJFLAGS} are passed to every
2633 compilation invoking @code{gcj} (in its role as an ahead-of-time
2634 compiler -- when invoking it to create @file{.class} files,
2635 @samp{AM_JAVACFLAGS} is used instead). If it is necessary to pass
2636 options to @code{gcj} from @file{Makefile.am}, this macro, and not the
2637 user macro @samp{GCJFLAGS}, should be used.
2641 @code{gcj} can be used to compile @file{.java}, @file{.class},
2642 @file{.zip}, or @file{.jar} files.
2645 @node Support for Other Languages, ANSI, Java Support, Programs
2646 @comment node-name, next, previous, up
2647 @section Support for Other Languages
2649 Automake currently only includes full support for C, C++ (@pxref{C++
2650 Support}), Fortran 77 (@pxref{Fortran 77 Support}), and Java
2651 (@pxref{Java Support}). There is only rudimentary support for other
2652 languages, support for which will be improved based on user demand.
2654 Some limited support for adding your own languages is available via the
2655 suffix rule handling; see @ref{Suffixes}.
2658 @node ANSI, Dependencies, Support for Other Languages, Programs
2659 @section Automatic de-ANSI-fication
2661 @cindex de-ANSI-fication, defined
2663 Although the GNU standards allow the use of ANSI C, this can have the
2664 effect of limiting portability of a package to some older compilers
2665 (notably the SunOS C compiler).
2667 Automake allows you to work around this problem on such machines by
2668 @dfn{de-ANSI-fying} each source file before the actual compilation takes
2671 @vindex AUTOMAKE_OPTIONS
2674 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
2675 (@pxref{Options}) contains the option @code{ansi2knr} then code to
2676 handle de-ANSI-fication is inserted into the generated
2679 This causes each C source file in the directory to be treated as ANSI C.
2680 If an ANSI C compiler is available, it is used. If no ANSI C compiler
2681 is available, the @code{ansi2knr} program is used to convert the source
2682 files into K&R C, which is then compiled.
2684 The @code{ansi2knr} program is simple-minded. It assumes the source
2685 code will be formatted in a particular way; see the @code{ansi2knr} man
2688 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
2689 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
2690 these files are distributed with Automake. Also, the package
2691 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}
2693 @cvindex AM_C_PROTOTYPES
2695 Automake also handles finding the @code{ansi2knr} support files in some
2696 other directory in the current package. This is done by prepending the
2697 relative path to the appropriate directory to the @code{ansi2knr}
2698 option. For instance, suppose the package has ANSI C code in the
2699 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
2700 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
2701 @file{src/Makefile.am}:
2704 AUTOMAKE_OPTIONS = ../lib/ansi2knr
2707 If no directory prefix is given, the files are assumed to be in the
2710 Files mentioned in @code{LIBOBJS} which need de-ANSI-fication will not
2711 be automatically handled. That's because @code{configure} will generate
2712 an object name like @file{regex.o}, while @code{make} will be looking
2713 for @file{regex_.o} (when de-ANSI-fying). Eventually this problem will
2714 be fixed via @code{autoconf} magic, but for now you must put this code
2715 into your @file{configure.in}, just before the @code{AC_OUTPUT} call:
2718 # This is necessary so that .o files in LIBOBJS are also built via
2719 # the ANSI2KNR-filtering rules.
2720 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
2723 Note that automatic de-ANSI-fication will not work when the package is
2724 being built for a different host architecture. That is because automake
2725 currently has no way to build @code{ansi2knr} for the build machine.
2728 @node Dependencies, , ANSI, Programs
2729 @section Automatic dependency tracking
2731 As a developer it is often painful to continually update the
2732 @file{Makefile.in} whenever the include-file dependencies change in a
2733 project. Automake supplies a way to automatically track dependency
2736 @cindex Dependency tracking
2737 @cindex Automatic dependency tracking
2739 Automake always uses complete dependencies for a compilation, including
2740 system headers. Automake's model is that dependency computation should
2741 be a side effect of the build. To this end, dependencies are computed
2742 by running all compilations through a special wrapper program called
2743 @code{depcomp}. @code{depcomp} understands how to coax many different C
2744 and C++ compilers into generating dependency information in the format
2745 it requires. @code{automake -a} will install @code{depcomp} into your
2746 source tree for you. If @code{depcomp} can't figure out how to properly
2747 invoke your compiler, dependency tracking will simply be disabled for
2752 Experience with earlier versions of Automake @footnote{See
2753 @uref{http://sources.redhat.com/automake/dependencies.html} for more
2754 information on the history and experiences with automatic dependency
2755 tracking in Automake} taught us that it is not reliable to generate
2756 dependencies only on the maintainer's system, as configurations vary too
2757 much. So instead Automake implements dependency tracking at build time.
2759 Automatic dependency tracking can be suppressed by putting
2760 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}. Or, you
2761 can invoke @code{automake} with the @code{-i} option. Dependency
2762 tracking is enabled by default.
2764 @vindex AUTOMAKE_OPTIONS
2765 @opindex no-dependencies
2767 The person building your package also can choose to disable dependency
2768 tracking by configuring with @code{--disable-dependency-tracking}.
2770 @cindex Disabling dependency tracking
2771 @cindex Dependency tracking, disabling
2774 @node Other objects, Other GNU Tools, Programs, Top
2775 @chapter Other Derived Objects
2777 Automake can handle derived objects which are not C programs. Sometimes
2778 the support for actually building such objects must be explicitly
2779 supplied, but Automake will still automatically handle installation and
2783 * Scripts:: Executable scripts
2784 * Headers:: Header files
2785 * Data:: Architecture-independent data files
2786 * Sources:: Derived sources
2790 @node Scripts, Headers, Other objects, Other objects
2791 @section Executable Scripts
2793 @cindex _SCRIPTS primary, defined
2794 @cindex SCRIPTS primary, defined
2795 @cindex Primary variable, SCRIPTS
2797 It is possible to define and install programs which are scripts. Such
2798 programs are listed using the @samp{SCRIPTS} primary name. Automake
2799 doesn't define any dependencies for scripts; the @file{Makefile.am}
2800 should include the appropriate rules.
2803 Automake does not assume that scripts are derived objects; such objects
2804 must be deleted by hand (@pxref{Clean}).
2806 The @code{automake} program itself is a Perl script that is generated at
2807 configure time from @file{automake.in}. Here is how this is handled:
2810 bin_SCRIPTS = automake
2813 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
2814 for it is automatically generated.
2816 @cindex SCRIPTS, installation directories
2817 @cindex Installing scripts
2820 @vindex sbin_SCRIPTS
2821 @vindex libexec_SCRIPTS
2822 @vindex pkgdata_SCRIPTS
2823 @vindex noinst_SCRIPTS
2825 Script objects can be installed in @code{bindir}, @code{sbindir},
2826 @code{libexecdir}, or @code{pkgdatadir}.
2829 @node Headers, Data, Scripts, Other objects
2830 @section Header files
2832 @cindex _HEADERS primary, defined
2833 @cindex HEADERS primary, defined
2834 @cindex Primary variable, HEADERS
2836 @vindex noinst_HEADERS
2838 Header files are specified by the @samp{HEADERS} family of variables.
2839 Generally header files are not installed, so the @code{noinst_HEADERS}
2840 variable will be the most used. @footnote{However, for the case of a
2841 non-installed header file that is actually used by a particular program,
2842 we recommend listing it in the program's @samp{_SOURCES} variable
2843 instead of in @code{noinst_HEADERS}. We believe this is more clear.}
2846 All header files must be listed somewhere; missing ones will not appear
2847 in the distribution. Often it is clearest to list uninstalled headers
2848 with the rest of the sources for a program. @xref{A Program}. Headers
2849 listed in a @samp{_SOURCES} variable need not be listed in any
2850 @samp{_HEADERS} variable.
2852 @cindex HEADERS, installation directories
2853 @cindex Installing headers
2855 @vindex include_HEADERS
2856 @vindex oldinclude_HEADERS
2857 @vindex pkginclude_HEADERS
2859 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
2860 @code{pkgincludedir}.
2863 @node Data, Sources, Headers, Other objects
2864 @section Architecture-independent data files
2866 @cindex _DATA primary, defined
2867 @cindex DATA primary, defined
2868 @cindex Primary variable, DATA
2870 Automake supports the installation of miscellaneous data files using the
2871 @samp{DATA} family of variables.
2875 @vindex sysconf_DATA
2876 @vindex sharedstate_DATA
2877 @vindex localstate_DATA
2878 @vindex pkgdata_DATA
2880 Such data can be installed in the directories @code{datadir},
2881 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
2884 By default, data files are @emph{not} included in a distribution. Of
2885 course, you can use the @samp{dist_} prefix to change this on a
2888 Here is how Automake installs its auxiliary data files:
2891 pkgdata_DATA = clean-kr.am clean.am @dots{}
2895 @node Sources, , Data, Other objects
2896 @section Built sources
2898 @cindex BUILT_SOURCES, defined
2900 Occasionally a file which would otherwise be called @samp{source}
2901 (e.g. a C @samp{.h} file) is actually derived from some other file.
2902 Such files should be listed in the @code{BUILT_SOURCES} variable.
2903 @vindex BUILT_SOURCES
2905 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
2906 must be created early in the build process can be listed in this
2909 A source file listed in @code{BUILT_SOURCES} is created before the other
2910 @code{all} targets are made. However, such a source file is not
2911 compiled unless explicitly requested by mentioning it in some other
2912 @samp{_SOURCES} variable.
2914 So, for instance, if you had header files which were created by a script
2915 run at build time, then you would list these headers in
2916 @code{BUILT_SOURCES}, to ensure that they would be built before any
2917 other compilations (perhaps ones using these headers) were started.
2920 @node Other GNU Tools, Documentation, Other objects, Top
2921 @chapter Other GNU Tools
2923 Since Automake is primarily intended to generate @file{Makefile.in}s for
2924 use in GNU programs, it tries hard to interoperate with other GNU tools.
2927 * Emacs Lisp:: Emacs Lisp
2935 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
2938 @cindex _LISP primary, defined
2939 @cindex LISP primary, defined
2940 @cindex Primary variable, LISP
2946 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
2947 is used to hold a list of @file{.el} files. Possible prefixes for this
2948 primary are @samp{lisp_} and @samp{noinst_}. Note that if
2949 @code{lisp_LISP} is defined, then @file{configure.in} must run
2950 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
2954 By default Automake will byte-compile all Emacs Lisp source files using
2955 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
2956 byte-compiling, simply define the variable @code{ELCFILES} to be empty.
2957 Byte-compiled Emacs Lisp files are not portable among all versions of
2958 Emacs, so it makes sense to turn this off if you expect sites to have
2959 more than one version of Emacs installed. Furthermore, many packages
2960 don't actually benefit from byte-compilation. Still, we recommend that
2961 you leave it enabled by default. It is probably better for sites with
2962 strange setups to cope for themselves than to make the installation less
2963 nice for everybody else.
2966 @node gettext, Libtool, Emacs Lisp, Other GNU Tools
2969 @cindex GNU Gettext support
2970 @cindex Gettext support
2971 @cindex Support for GNU Gettext
2973 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
2974 turns on support for GNU gettext, a message catalog system for
2975 internationalization
2976 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
2978 The @code{gettext} support in Automake requires the addition of two
2979 subdirectories to the package, @file{intl} and @file{po}. Automake
2980 insures that these directories exist and are mentioned in
2983 Furthermore, Automake checks that the definition of @code{ALL_LINGUAS}
2984 in @file{configure.in} corresponds to all the valid @file{.po} files,
2988 @node Libtool, Java, gettext, Other GNU Tools
2991 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
2992 libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
2993 @xref{A Shared Library}.
2996 @node Java, Python, Libtool, Other GNU Tools
2999 @cindex _JAVA primary, defined
3000 @cindex JAVA primary, defined
3001 @cindex Primary variable, JAVA
3003 Automake provides some minimal support for Java compilation with the
3004 @samp{JAVA} primary.
3006 Any @file{.java} files listed in a @samp{_JAVA} variable will be
3007 compiled with @code{JAVAC} at build time. By default, @file{.class}
3008 files are not included in the distribution.
3010 @cindex JAVA restrictions
3011 @cindex Restrictions for JAVA
3013 Currently Automake enforces the restriction that only one @samp{_JAVA}
3014 primary can be used in a given @file{Makefile.am}. The reason for this
3015 restriction is that, in general, it isn't possible to know which
3016 @file{.class} files were generated from which @file{.java} files -- so
3017 it would be impossible to know which files to install where. For
3018 instance, a @file{.java} file can define multiple classes; the resulting
3019 @file{.class} file names cannot be predicted without parsing the
3022 There are a few variables which are used when compiling Java sources:
3026 The name of the Java compiler. This defaults to @samp{javac}.
3029 The flags to pass to the compiler. This is considered to be a user
3030 variable (@pxref{User Variables}).
3033 More flags to pass to the Java compiler. This, and not
3034 @code{JAVACFLAGS}, should be used when it is necessary to put Java
3035 compiler flags into @file{Makefile.am}.
3038 The value of this variable is passed to the @samp{-d} option to
3039 @code{javac}. It defaults to @samp{$(top_builddir)}.
3042 This variable is an @code{sh} expression which is used to set the
3043 @code{CLASSPATH} environment variable on the @code{javac} command line.
3044 (In the future we will probably handle class path setting differently.)
3048 @node Python, , Java, Other GNU Tools
3051 @cindex _PYTHON primary, defined
3052 @cindex PYTHON primary, defined
3053 @cindex Primary variable, PYTHON
3056 Automake provides support for Python modules. Automake will turn on
3057 Python support if the @code{AM_PATH_PYTHON} macro is used in
3058 @file{configure.in}. The @samp{PYTHON} primary is used to hold a list
3059 of @file{.py} files. Possible prefixes for this primary are
3060 @samp{python_} and @samp{noinst_}. Note that if @code{python_PYTHON} is
3061 defined, then @file{configure.in} must run @code{AM_PATH_PYTHON}.
3062 Python source files are included in the distribution by default.
3064 @code{AM_PATH_PYTHON} takes a single optional argument. This argument,
3065 if present, is the minimum version of Python which can be used for this
3066 package. If the version of Python found on the system is older than the
3067 required version, then @code{AM_PATH_PYTHON} will cause an error.
3069 @code{AM_PATH_PYTHON} creates several output variables based on the
3070 Python installation found during configuration.
3074 The name of the Python executable.
3076 @item PYTHON_VERSION
3077 The Python version number, in the form @var{major}.@var{minor}
3078 (e.g. @samp{1.5}). This is currently the value of
3079 @code{sys.version[:3]}.
3082 The string @code{$prefix}. This term may be used in future work
3083 which needs the contents of Python's @code{sys.prefix}, but general
3084 consensus is to always use the value from configure.
3086 @item PYTHON_EXEC_PREFIX
3087 The string @code{$exec_prefix}. This term may be used in future work
3088 which needs the contents of Python's @code{sys.exec_prefix}, but general
3089 consensus is to always use the value from configure.
3091 @item PYTHON_PLATFORM
3092 The canonical name used by Python to describe the operating system, as
3093 given by @code{sys.platform}. This value is sometimes needed when
3094 building Python extensions.
3097 The directory name for the @file{site-packages} subdirectory of the
3098 standard Python install tree.
3101 This is is the directory under @code{pythondir} which is named after the
3102 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
3106 This is the directory where Python extension modules (shared libraries)
3107 should be installed.
3110 This is a convenience variable which is defined as
3111 @samp{$(pyexecdir)/$(PACKAGE)}.
3117 By default Automake will byte-compile all Python source files to both
3118 @file{.pyc} and @file{.pyo} forms. If you wish to avoid generating the
3119 optimized byte-code files, simply define the variable @code{PYOFILES} to
3120 be empty. Similarly, if you don't wish to generate the standard
3121 byte-compiled files, define the variable @code{PYCFILES} to be empty.
3124 @node Documentation, Install, Other GNU Tools, Top
3125 @chapter Building documentation
3127 Currently Automake provides support for Texinfo and man pages.
3131 * Man pages:: Man pages
3135 @node Texinfo, Man pages, Documentation, Documentation
3138 @cindex _TEXINFOS primary, defined
3139 @cindex TEXINFOS primary, defined
3140 @cindex Primary variable, TEXINFOS
3142 If the current directory contains Texinfo source, you must declare it
3143 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
3144 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
3145 here. Any Texinfo source file must end in the @file{.texi},
3146 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
3149 @vindex info_TEXINFOS
3151 @cindex Texinfo macro, VERSION
3152 @cindex Texinfo macro, UPDATED
3153 @cindex Texinfo macro, EDITION
3154 @cindex Texinfo macro, UPDATED-MONTH
3156 @cindex VERSION Texinfo macro
3157 @cindex UPDATED Texinfo macro
3158 @cindex EDITION Texinfo macro
3159 @cindex UPDATED-MONTH Texinfo macro
3163 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
3164 that file will be automatically generated. The file @file{version.texi}
3165 defines four Texinfo macros you can reference:
3170 Both of these macros hold the version number of your program. They are
3171 kept separate for clarity.
3174 This holds the date the primary @file{.texi} file was last modified.
3177 This holds the name of the month in which the primary @file{.texi} file
3181 The @file{version.texi} support requires the @code{mdate-sh} program;
3182 this program is supplied with Automake and automatically included when
3183 @code{automake} is invoked with the @code{--add-missing} option.
3185 If you have multiple Texinfo files, and you want to use the
3186 @file{version.texi} feature, then you have to have a separate version
3187 file for each Texinfo file. Automake will treat any include in a
3188 Texinfo file that matches @samp{vers*.texi} just as an automatically
3189 generated version file.
3191 When an info file is rebuilt, the program named by the @code{MAKEINFO}
3192 variable is used to invoke it. If the @code{makeinfo} program is found
3193 on the system then it will be used by default; otherwise @code{missing}
3194 will be used instead. The flags in the variables @code{MAKEINFOFLAGS}
3195 and @code{AM_MAKEINFOFLAGS} will be passed to the @code{makeinfo}
3196 invocation; the first of these is intended for use by the user
3197 (@pxref{User Variables}) and the second by the @file{Makefile.am}
3200 @vindex MAKEINFOFLAGS
3201 @vindex AM_MAKEINFOFLAGS
3203 Sometimes an info file actually depends on more than one @file{.texi}
3204 file. For instance, in GNU Hello, @file{hello.texi} includes the file
3205 @file{gpl.texi}. You can tell Automake about these dependencies using
3206 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
3211 info_TEXINFOS = hello.texi
3212 hello_TEXINFOS = gpl.texi
3217 By default, Automake requires the file @file{texinfo.tex} to appear in
3218 the same directory as the Texinfo source. However, if you used
3219 @code{AC_CONFIG_AUX_DIR} in @file{configure.in} (@pxref{Input, , Finding
3220 `configure' Input, autoconf, The Autoconf Manual}), then
3221 @file{texinfo.tex} is looked for there. Automake supplies
3222 @file{texinfo.tex} if @samp{--add-missing} is given.
3226 If your package has Texinfo files in many directories, you can use the
3227 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
3228 @file{texinfo.tex} for your package. The value of this variable should
3229 be the relative path from the current @file{Makefile.am} to
3233 TEXINFO_TEX = ../doc/texinfo.tex
3236 @opindex no-texinfo.tex
3238 The option @samp{no-texinfo.tex} can be used to eliminate the
3239 requirement for @file{texinfo.tex}. Use of the variable
3240 @code{TEXINFO_TEX} is preferable, however, because that allows the
3241 @code{dvi} target to still work.
3243 @cindex Target, install-info
3244 @cindex Target, noinstall-info
3245 @cindex install-info target
3246 @cindex noinstall-info target
3248 @opindex no-installinfo
3249 @trindex install-info
3251 Automake generates an @code{install-info} target; some people apparently
3252 use this. By default, info pages are installed by @samp{make install}.
3253 This can be prevented via the @code{no-installinfo} option.
3256 @node Man pages, , Texinfo, Documentation
3259 @cindex _MANS primary, defined
3260 @cindex MANS primary, defined
3261 @cindex Primary variable, MANS
3263 A package can also include man pages (but see the GNU standards on this
3264 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
3265 pages are declared using the @samp{MANS} primary. Generally the
3266 @code{man_MANS} macro is used. Man pages are automatically installed in
3267 the correct subdirectory of @code{mandir}, based on the file extension.
3271 File extensions such as @samp{.1c} are handled by looking for the valid
3272 part of the extension and using that to determine the correct
3273 subdirectory of @code{mandir}. Valid section names are the digits
3274 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
3276 Sometimes developers prefer to name a man page something like
3277 @file{foo.man} in the source, and then rename it to have the correct
3278 suffix, e.g. @file{foo.1}, when installing the file. Automake also
3279 supports this mode. For a valid section named @var{SECTION}, there is a
3280 corresponding directory named @samp{man@var{SECTION}dir}, and a
3281 corresponding @samp{_MANS} variable. Files listed in such a variable
3282 are installed in the indicated section. If the file already has a
3283 valid suffix, then it is installed as-is; otherwise the file suffix is
3284 changed to match the section.
3286 For instance, consider this example:
3288 man1_MANS = rename.man thesame.1 alsothesame.1c
3291 In this case, @file{rename.man} will be renamed to @file{rename.1} when
3292 installed, but the other files will keep their names.
3294 @cindex Target, install-man
3295 @cindex Target, noinstall-man
3296 @cindex install-man target
3297 @cindex noinstall-man target
3299 @c Use @samp{make install} per documentation: (texi)code.
3300 By default, man pages are installed by @samp{make install}. However,
3301 since the GNU project does not require man pages, many maintainers do
3302 not expend effort to keep the man pages up to date. In these cases, the
3303 @code{no-installman} option will prevent the man pages from being
3304 installed by default. The user can still explicitly install them via
3305 @samp{make install-man}.
3306 @opindex no-installman
3307 @trindex install-man
3309 Here is how the man pages are handled in GNU @code{cpio} (which includes
3310 both Texinfo documentation and man pages):
3313 man_MANS = cpio.1 mt.1
3314 EXTRA_DIST = $(man_MANS)
3317 Man pages are not currently considered to be source, because it is not
3318 uncommon for man pages to be automatically generated. Therefore they
3319 are not automatically included in the distribution. However, this can
3320 be changed by use of the @samp{dist_} prefix.
3322 The @samp{nobase_} prefix is meaningless for man pages and is
3326 @node Install, Clean, Documentation, Top
3327 @chapter What Gets Installed
3329 @cindex Installation support
3330 @cindex make install support
3332 Naturally, Automake handles the details of actually installing your
3333 program once it has been built. All files named by the various
3334 primaries are automatically installed in the appropriate places when the
3335 user runs @code{make install}.
3337 A file named in a primary is installed by copying the built file into
3338 the appropriate directory. The base name of the file is used when
3342 bin_PROGRAMS = hello subdir/goodbye
3345 In this example, both @samp{hello} and @samp{goodbye} will be installed
3346 in @code{$(bindir)}.
3348 Sometimes it is useful to avoid the basename step at install time. For
3349 instance, you might have a number of header files in subdirectories of
3350 the source tree which are laid out precisely how you want to install
3351 them. In this situation you can use the @samp{nobase_} prefix to
3352 suppress the base name step. For example:
3355 include_HEADERS = stdio.h sys/types.h
3358 Will include @file{stdio.h} in @code{$(includedir)} and @file{types.h}
3359 in @code{$(includedir)/sys}.
3361 Automake generates separate @code{install-data} and @code{install-exec}
3362 targets, in case the installer is installing on multiple machines which
3363 share directory structure---these targets allow the machine-independent
3364 parts to be installed only once. The @code{install} target depends on
3365 both of these targets.
3366 @trindex install-data
3367 @trindex install-exec
3370 Automake also generates an @code{uninstall} target, an
3371 @code{installdirs} target, and an @code{install-strip} target.
3373 @trindex installdirs
3374 @trindex install-strip
3376 It is possible to extend this mechanism by defining an
3377 @code{install-exec-local} or @code{install-data-local} target. If these
3378 targets exist, they will be run at @samp{make install} time.
3379 @trindex install-exec-local
3380 @trindex install-data-local
3382 Variables using the standard directory prefixes @samp{data},
3383 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
3384 @samp{pkgdata}, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
3385 installed by @samp{install-data}.
3387 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
3388 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
3389 @samp{pkglib} (e.g. @samp{bin_PROGRAMS}) are installed by
3390 @samp{install-exec}.
3392 Any variable using a user-defined directory prefix with @samp{exec} in
3393 the name (e.g. @samp{myexecbin_PROGRAMS} is installed by
3394 @samp{install-exec}. All other user-defined prefixes are installed by
3395 @samp{install-data}.
3398 Automake generates support for the @samp{DESTDIR} variable in all
3399 install rules. @samp{DESTDIR} is used during the @samp{make install}
3400 step to relocate install objects into a staging area. Each object and
3401 path is prefixed with the value of @samp{DESTDIR} before being copied
3402 into the install area. Here is an example of typical DESTDIR usage:
3405 make DESTDIR=/tmp/staging install
3408 This places install objects in a directory tree built under
3409 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
3410 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
3411 would install @file{/tmp/staging/gnu/bin/foo} and
3412 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
3414 This feature is commonly used to build install images and packages. For
3415 more information, see @ref{Makefile Conventions, , , standards, The GNU
3419 @node Clean, Dist, Install, Top
3420 @chapter What Gets Cleaned
3422 @cindex make clean support
3424 The GNU Makefile Standards specify a number of different clean rules.
3426 Generally the files that can be cleaned are determined automatically by
3427 Automake. Of course, Automake also recognizes some variables that can
3428 be defined to specify additional files to clean. These variables are
3429 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
3430 @code{MAINTAINERCLEANFILES}.
3431 @vindex MOSTLYCLEANFILES
3433 @vindex DISTCLEANFILES
3434 @vindex MAINTAINERCLEANFILES
3436 As the GNU Standards aren't always explicit as to which files should be
3437 removed by which target, we've adopted a heuristic which we believe were
3438 first formulated by Fran@,{c}ois Pinard:
3442 If @code{make} built it, and it is commonly something that one would
3443 want to rebuild (for instance, a @file{.o} file), then
3444 @code{mostlyclean} should delete it.
3447 Otherwise, if @code{make} built it, then @code{clean} should delete it.
3450 If @code{configure} built it, then @code{distclean} should delete it
3453 If the maintainer built it, then @code{maintainer-clean} should
3457 We recommend that you follow this same set of heuristics in your
3461 @node Dist, Tests, Clean, Top
3462 @chapter What Goes in a Distribution
3465 @cindex make distcheck
3467 The @code{dist} target in the generated @file{Makefile.in} can be used
3468 to generate a gzip'd @code{tar} file for distribution. The tar file is
3469 named based on the @samp{PACKAGE} and @samp{VERSION} variables; more
3470 precisely it is named @samp{@var{package}-@var{version}.tar.gz}.
3474 You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
3475 is run. The default setting is @samp{--best}.
3477 For the most part, the files to distribute are automatically found by
3478 Automake: all source files are automatically included in a distribution,
3479 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
3480 has a built-in list of commonly used files which, if present in the
3481 current directory, are automatically included. This list is printed by
3482 @samp{automake --help}. Also, files which are read by @code{configure}
3483 (i.e. the source files corresponding to the files specified in the
3484 @code{AC_OUTPUT} invocation) are automatically distributed.
3486 Still, sometimes there are files which must be distributed, but which
3487 are not covered in the automatic rules. These files should be listed in
3488 the @code{EXTRA_DIST} variable. You can mention files from
3489 subdirectories in @code{EXTRA_DIST}. You can also mention a directory
3490 there; in this case the entire directory will be recursively copied into
3491 the distribution. Please note that this will also copy
3492 @emph{everything} in the directory, including CVS/RCS version control
3497 Sometimes you need tighter control over what does @emph{not} go into the
3498 distribution; for instance you might have source files which are
3499 generated and which you do not want to distribute. In this case
3500 Automake gives fine-grained control using the @samp{dist} and
3501 @samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
3502 prefixed with @samp{dist_} to add the listed files to the distribution.
3503 Similarly, @samp{nodist_} can be used to omit the files from the
3508 As an example, here is how you would cause some data to be distributed
3509 while leaving some source code out of the distribution:
3512 dist_data_DATA = distribute-this
3514 nodist_foo_SOURCES = do-not-distribute.c
3517 Another way to to use this is for removing unnecessary files that get
3518 recursively included by specifying a directory in EXTRA_DIST:
3524 rm -rf `find $(distdir)/doc -name CVS`
3527 If you define @code{SUBDIRS}, Automake will recursively include the
3528 subdirectories in the distribution. If @code{SUBDIRS} is defined
3529 conditionally (@pxref{Conditionals}), Automake will normally include all
3530 directories that could possibly appear in @code{SUBDIRS} in the
3531 distribution. If you need to specify the set of directories
3532 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
3533 list of subdirectories to include in the distribution.
3534 @vindex DIST_SUBDIRS
3538 Occasionally it is useful to be able to change the distribution before
3539 it is packaged up. If the @code{dist-hook} target exists, it is run
3540 after the distribution directory is filled, but before the actual tar
3541 (or shar) file is created. One way to use this is for distributing
3542 files in subdirectories for which a new @file{Makefile.am} is overkill:
3546 mkdir $(distdir)/random
3547 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
3550 Automake also generates a @code{distcheck} target which can be of help
3551 to ensure that a given distribution will actually work.
3552 @code{distcheck} makes a distribution, and then tries to do a
3556 If the target @code{distcheck-hook} is defined in your
3557 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
3558 the new distribution has been unpacked, but before the unpacked copy is
3559 configured and built. Your @code{distcheck-hook} can do almost
3560 anything, though as always caution is advised. Generally this hook is
3561 used to check for potential distribution errors not caught by the
3565 @node Tests, Options, Dist, Top
3566 @chapter Support for test suites
3571 Automake supports two forms of test suites.
3573 @section Simple Tests
3575 If the variable @code{TESTS} is defined, its value is taken to be a list
3576 of programs to run in order to do the testing. The programs can either
3577 be derived objects or source objects; the generated rule will look both
3578 in @code{srcdir} and @file{.}. Programs needing data files should look
3579 for them in @code{srcdir} (which is both an environment variable and a
3580 make variable) so they work when building in a separate directory
3581 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
3582 Manual}), and in particular for the @code{distcheck} target
3585 @cindex Exit status 77, special interpretation
3587 The number of failures will be printed at the end of the run. If a
3588 given test program exits with a status of 77, then its result is ignored
3589 in the final count. This feature allows non-portable tests to be
3590 ignored in environments where they don't make sense.
3592 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
3593 variables for the test run; the environment variable @code{srcdir} is
3594 set in the rule. If all your test programs are scripts, you can also
3595 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
3596 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
3598 @vindex TESTS_ENVIRONMENT
3600 @cindex Tests, expected failure
3601 @cindex Expected test failure
3603 You may define the variable @code{XFAIL_TESTS} to a list of tests
3604 (usually a subset of @code{TESTS}) that are expected to fail. This will
3605 reverse the result of those tests.
3608 Automake ensures that each program listed in @code{TESTS} is built
3609 before any tests are run; you can list both source and derived programs
3610 in @code{TESTS}. For instance, you might want to run a C program as a
3611 test. To do this you would list its name in @code{TESTS} and also in
3612 @code{check_PROGRAMS}, and then specify it as you would any other
3615 @section DejaGNU Tests
3617 If @uref{ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz,
3618 @samp{dejagnu}} appears in @code{AUTOMAKE_OPTIONS}, then a
3619 @code{dejagnu}-based test suite is assumed. The variable
3620 @code{DEJATOOL} is a list of names which are passed, one at a time, as
3621 the @code{--tool} argument to @code{runtest} invocations; it defaults to
3622 the name of the package.
3624 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
3625 @code{--srcdir} flags that are passed to dejagnu by default; this can be
3626 overridden if necessary.
3627 @vindex RUNTESTDEFAULTFLAGS
3629 The variables @code{EXPECT} and @code{RUNTEST} can
3630 also be overridden to provide project-specific values. For instance,
3631 you will need to do this if you are testing a compiler toolchain,
3632 because the default values do not take into account host and target
3639 The contents of the variable @code{RUNTESTFLAGS} are passed to the
3640 @code{runtest} invocation. This is considered a ``user variable''
3641 (@pxref{User Variables}). If you need to set @code{runtest} flags in
3642 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
3643 @vindex RUNTESTFLAGS
3644 @vindex AM_RUNTESTFLAGS
3645 @c FIXME xref dejagnu
3647 In either case, the testing is done via @samp{make check}.
3650 @node Options, Miscellaneous, Tests, Top
3651 @chapter Changing Automake's Behavior
3653 Various features of Automake can be controlled by options in the
3654 @file{Makefile.am}. Such options are listed in a special variable named
3655 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
3656 @vindex AUTOMAKE_OPTIONS
3661 @itemx @code{foreign}
3663 @cindex Option, gnits
3665 @cindex Option, foreign
3666 @cindex Option, cygnus
3668 Set the strictness as appropriate. The @code{gnits} option also implies
3669 @code{readme-alpha} and @code{check-news}.
3671 @item @code{ansi2knr}
3672 @itemx @code{path/ansi2knr}
3673 @cindex Option, ansi2knr
3674 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
3675 path, the generated @file{Makefile.in} will look in the specified
3676 directory to find the @file{ansi2knr} program. Generally the path
3677 should be a relative path to another directory in the same distribution
3678 (though Automake currently does not check this).
3680 @item @code{check-news}
3681 @cindex Option, check-news
3682 Cause @code{make dist} to fail unless the current version number appears
3683 in the first few lines of the @file{NEWS} file.
3685 @item @code{dejagnu}
3686 @cindex Option, dejagnu
3687 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
3689 @item @code{dist-bzip2}
3690 @cindex Option, dist-bzip2
3691 Generate a @code{dist-bzip2} target as well as the ordinary @code{dist}
3692 target. This new target will create a bzip2 tar archive of the
3693 distribution. bzip2 archives are frequently smaller than even gzipped
3697 @item @code{dist-shar}
3698 @cindex Option, dist-shar
3699 Generate a @code{dist-shar} target as well as the ordinary @code{dist}
3700 target. This new target will create a shar archive of the
3704 @item @code{dist-zip}
3705 @cindex Option, dist-zip
3706 Generate a @code{dist-zip} target as well as the ordinary @code{dist}
3707 target. This new target will create a zip archive of the distribution.
3710 @item @code{dist-tarZ}
3711 @cindex Option, dist-tarZ
3712 Generate a @code{dist-tarZ} target as well as the ordinary @code{dist}
3713 target. This new target will create a compressed tar archive of the
3717 @item @code{no-dependencies}
3718 @cindex Option, no-dependencies
3719 This is similar to using @samp{--include-deps} on the command line, but
3720 is useful for those situations where you don't have the necessary bits
3721 to make automatic dependency tracking work @xref{Dependencies}. In this
3722 case the effect is to effectively disable automatic dependency tracking.
3724 @item @code{no-installinfo}
3725 @cindex Option, no-installinfo
3726 The generated @file{Makefile.in} will not cause info pages to be built
3727 or installed by default. However, @code{info} and @code{install-info}
3728 targets will still be available. This option is disallowed at
3729 @samp{GNU} strictness and above.
3731 @trindex install-info
3733 @item @code{no-installman}
3734 @cindex Option, no-installman
3735 The generated @file{Makefile.in} will not cause man pages to be
3736 installed by default. However, an @code{install-man} target will still
3737 be available for optional installation. This option is disallowed at
3738 @samp{GNU} strictness and above.
3739 @trindex install-man
3741 @item @code{nostdinc}
3742 @cindex Option, nostdinc
3743 This option can be used to disable the standard @samp{-I} options which
3744 are ordinarily automatically provided by Automake.
3746 @item @code{no-texinfo.tex}
3747 @cindex Option, no-texinfo
3748 Don't require @file{texinfo.tex}, even if there are texinfo files in
3751 @item @code{readme-alpha}
3752 @cindex Option, readme-alpha
3753 If this release is an alpha release, and the file @file{README-alpha}
3754 exists, then it will be added to the distribution. If this option is
3755 given, version numbers are expected to follow one of two forms. The
3756 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
3757 element is a number; the final period and number should be left off for
3758 non-alpha releases. The second form is
3759 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
3760 letter; it should be omitted for non-alpha releases.
3762 @item @code{subdir-objects}
3763 If this option is specified, then objects are placed into the
3764 subdirectory of the build directory corresponding to the subdirectory of
3765 the source file. For instance if the source file is
3766 @file{subdir/file.cxx}, then the output file would be
3767 @file{subdir/file.o}.
3770 @cindex Option, version
3771 A version number (e.g. @samp{0.30}) can be specified. If Automake is not
3772 newer than the version specified, creation of the @file{Makefile.in}
3776 Unrecognized options are diagnosed by @code{automake}.
3779 @node Miscellaneous, Include, Options, Top
3780 @chapter Miscellaneous Rules
3782 There are a few rules and variables that didn't fit anywhere else.
3785 * Tags:: Interfacing to etags and mkid
3786 * Suffixes:: Handling new file extensions
3787 * Multilibs:: Support for multilibbing.
3791 @node Tags, Suffixes, Miscellaneous, Miscellaneous
3792 @section Interfacing to @code{etags}
3794 @cindex TAGS support
3796 Automake will generate rules to generate @file{TAGS} files for use with
3797 GNU Emacs under some circumstances.
3799 If any C, C++ or Fortran 77 source code or headers are present, then
3800 @code{tags} and @code{TAGS} targets will be generated for the directory.
3803 At the topmost directory of a multi-directory package, a @code{tags}
3804 target file will be generated which, when run, will generate a
3805 @file{TAGS} file that includes by reference all @file{TAGS} files from
3808 Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
3809 will be generated. This variable is intended for use in directories
3810 which contain taggable source that @code{etags} does not understand.
3813 Here is how Automake generates tags for its source, and for nodes in its
3817 ETAGS_ARGS = automake.in --lang=none \
3818 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
3821 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
3822 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
3823 are added directly to the dependencies for the @code{tags} target.
3824 @vindex TAGS_DEPENDENCIES
3826 Automake will also generate an @code{ID} target which will run
3827 @code{mkid} on the source. This is only supported on a
3828 directory-by-directory basis.
3831 Automake also supports the @uref{http://www.gnu.org/software/global/,
3832 GNU Global Tags program}. The @code{GTAGS} target runs Global Tags
3833 automatically and puts the result in the top build directory. The
3834 variable @code{GTAGS_ARGS} holds arguments which are passed to
3839 @node Suffixes, Multilibs, Tags, Miscellaneous
3840 @section Handling new file extensions
3842 @cindex Adding new SUFFIXES
3843 @cindex SUFFIXES, adding
3845 It is sometimes useful to introduce a new implicit rule to handle a file
3846 type that Automake does not know about. If this is done, you must
3847 notify GNU Make of the new suffixes. This can be done by putting a list
3848 of new suffixes in the @code{SUFFIXES} variable.
3851 For instance, suppose you had a compiler which could compile @samp{.foo}
3852 files to @samp{.o} files. Then you would add @samp{.foo} to your suffix
3859 Then you could directly use a @samp{.foo} file in a @samp{_SOURCES}
3860 variable and expect the correct results:
3864 doit_SOURCES = doit.foo
3867 Any given @code{SUFFIXES} go at the start of the generated suffixes
3868 list, followed by automake generated suffixes not already in the list.
3871 @node Multilibs, , Suffixes, Miscellaneous
3872 @section Support for Multilibs
3874 Automake has support for an obscure feature called multilibs. A
3875 @dfn{multilib} is a library which is built for multiple different ABIs
3876 at a single time; each time the library is built with a different target
3877 flag combination. This is only useful when the library is intended to
3878 be cross-compiled, and it is almost exclusively used for compiler
3881 The multilib support is still experimental. Only use it if you are
3882 familiar with multilibs and can debug problems you might encounter.
3885 @node Include, Conditionals, Miscellaneous, Top
3889 @cindex Including Makefile fragment
3890 @cindex Makefile fragment, including
3892 Automake supports an @code{include} directive which can be used to
3893 include other @file{Makefile} fragments when @code{automake} is run.
3894 Note that these fragments are read and interpreted by @code{automake},
3895 not by @code{make}. As with conditionals, @code{make} has no idea that
3896 @code{include} is in use.
3898 There are two forms of @code{include}:
3901 @item include $(srcdir)/file
3902 Include a fragment which is found relative to the current source
3905 @item include $(top_srcdir)/file
3906 Include a fragment which is found relative to the top source directory.
3909 Note that if a fragment is included inside a conditional, then the
3910 condition applies to the entire contents of that fragment.
3913 @node Conditionals, Gnits, Include, Top
3914 @chapter Conditionals
3916 @cindex Conditionals
3918 Automake supports a simple type of conditionals.
3920 @cvindex AM_CONDITIONAL
3921 Before using a conditional, you must define it by using
3922 @code{AM_CONDITIONAL} in the @code{configure.in} file (@pxref{Macros}).
3924 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
3925 The conditional name, @var{conditional}, should be a simple string
3926 starting with a letter and containing only letters, digits, and
3927 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
3928 which are reserved by Automake.
3930 The shell @var{condition} (suitable for use in a shell @code{if}
3931 statement) is evaluated when @code{configure} is run.
3934 @cindex --enable-debug, example
3935 @cindex Example conditional --enable-debug
3936 @cindex Conditional example, --enable-debug
3938 Conditionals typically depend upon options which the user provides to
3939 the @code{configure} script. Here is an example of how to write a
3940 conditional which is true if the user uses the @samp{--enable-debug}
3944 AC_ARG_ENABLE(debug,
3945 [ --enable-debug Turn on debugging],
3946 [case "$@{enableval@}" in
3949 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
3950 esac],[debug=false])
3951 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
3954 Here is an example of how to use that conditional in @file{Makefile.am}:
3966 noinst_PROGRAMS = $(DBG)
3969 This trivial example could also be handled using EXTRA_PROGRAMS
3970 (@pxref{A Program}).
3972 You may only test a single variable in an @code{if} statement, possibly
3973 negated using @samp{!}. The @code{else} statement may be omitted.
3974 Conditionals may be nested to any depth. You may specify an argument to
3975 @code{else} in which case it must be the negation of the condition used
3976 for the current @code{if}. Similarly you may specify the condition
3977 which is closed by an @code{end}:
3988 Unbalanced conditions are errors.
3990 Note that conditionals in Automake are not the same as conditionals in
3991 GNU Make. Automake conditionals are checked at configure time by the
3992 @file{configure} script, and affect the translation from
3993 @file{Makefile.in} to @file{Makefile}. They are based on options passed
3994 to @file{configure} and on results that @file{configure} has discovered
3995 about the host system. GNU Make conditionals are checked at @code{make}
3996 time, and are based on variables passed to the make program or defined
3997 in the @file{Makefile}.
3999 Automake conditionals will work with any make program.
4002 @node Gnits, Cygnus, Conditionals, Top
4003 @chapter The effect of @code{--gnu} and @code{--gnits}
4005 @cindex --gnu, required files
4006 @cindex --gnu, complete description
4008 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
4009 variable) causes @code{automake} to check the following:
4013 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
4014 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
4015 directory of the package.
4018 The options @samp{no-installman} and @samp{no-installinfo} are
4022 Note that this option will be extended in the future to do even more
4023 checking; it is advisable to be familiar with the precise requirements
4024 of the GNU standards. Also, @samp{--gnu} can require certain
4025 non-standard GNU programs to exist for use by various maintainer-only
4026 targets; for instance in the future @code{pathchk} might be required for
4029 @cindex --gnits, complete description
4031 The @samp{--gnits} option does everything that @samp{--gnu} does, and
4032 checks the following as well:
4036 @samp{make dist} will check to make sure the @file{NEWS} file has been
4037 updated to the current version.
4040 @samp{VERSION} is checked to make sure its format complies with Gnits
4042 @c FIXME xref when standards are finished
4045 @cindex README-alpha
4046 If @samp{VERSION} indicates that this is an alpha release, and the file
4047 @file{README-alpha} appears in the topmost directory of a package, then
4048 it is included in the distribution. This is done in @samp{--gnits}
4049 mode, and no other, because this mode is the only one where version
4050 number formats are constrained, and hence the only mode where Automake
4051 can automatically determine whether @file{README-alpha} should be
4055 The file @file{THANKS} is required.
4059 @node Cygnus, Extending, Gnits, Top
4060 @chapter The effect of @code{--cygnus}
4062 @cindex Cygnus strictness
4064 Cygnus Solutions has slightly different rules for how a
4065 @file{Makefile.in} is to be constructed. Passing @samp{--cygnus} to
4066 @code{automake} will cause any generated @file{Makefile.in} to comply
4069 Here are the precise effects of @samp{--cygnus}:
4073 Info files are always created in the build directory, and not in the
4077 @file{texinfo.tex} is not required if a Texinfo source file is
4078 specified. The assumption is that the file will be supplied, but in a
4079 place that Automake cannot find. This assumption is an artifact of how
4080 Cygnus packages are typically bundled.
4083 @samp{make dist} will look for files in the build directory as well as
4084 the source directory. This is required to support putting info files
4085 into the build directory.
4088 Certain tools will be searched for in the build tree as well as in the
4089 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
4090 @code{makeinfo} and @code{texi2dvi}.
4093 @code{--foreign} is implied.
4096 The options @samp{no-installinfo} and @samp{no-dependencies} are
4100 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
4104 The @code{check} target doesn't depend on @code{all}.
4107 GNU maintainers are advised to use @samp{gnu} strictness in preference
4108 to the special Cygnus mode.
4111 @node Extending, Distributing, Cygnus, Top
4112 @chapter When Automake Isn't Enough
4114 Automake's implicit copying semantics means that many problems can be
4115 worked around by simply adding some @code{make} targets and rules to
4116 @file{Makefile.in}. Automake will ignore these additions.
4118 @cindex -local targets
4119 @cindex local targets
4121 There are some caveats to doing this. Although you can overload a
4122 target already used by Automake, it is often inadvisable, particularly
4123 in the topmost directory of a package with subdirectories. However,
4124 various useful targets have a @samp{-local} version you can specify in
4125 your @file{Makefile.in}. Automake will supplement the standard target
4126 with these user-supplied targets.
4131 @trindex check-local
4132 @trindex install-data-local
4133 @trindex install-exec-local
4134 @trindex uninstall-local
4135 @trindex mostlyclean-local
4136 @trindex clean-local
4137 @trindex distclean-local
4139 The targets that support a local version are @code{all}, @code{info},
4140 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
4141 @code{uninstall}, and the various @code{clean} targets
4142 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
4143 @code{maintainer-clean}). Note that there are no
4144 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
4145 use @code{uninstall-local}. It doesn't make sense to uninstall just
4146 data or just executables.
4151 @trindex install-data
4152 @trindex install-exec
4155 For instance, here is one way to install a file in @file{/etc}:
4159 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
4162 @cindex -hook targets
4163 @cindex hook targets
4165 Some targets also have a way to run another target, called a @dfn{hook},
4166 after their work is done. The hook is named after the principal target,
4167 with @samp{-hook} appended. The targets allowing hooks are
4168 @code{install-data}, @code{install-exec}, @code{dist}, and
4170 @trindex install-data-hook
4171 @trindex install-exec-hook
4174 For instance, here is how to create a hard link to an installed program:
4178 ln $(bindir)/program $(bindir)/proglink
4181 @c FIXME should include discussion of variables you can use in these
4185 @node Distributing, Macro and Variable Index, Extending, Top
4186 @chapter Distributing @file{Makefile.in}s
4188 Automake places no restrictions on the distribution of the resulting
4189 @file{Makefile.in}s. We still encourage software authors to distribute
4190 their work under terms like those of the GPL, but doing so is not
4191 required to use Automake.
4193 Some of the files that can be automatically installed via the
4194 @code{--add-missing} switch do fall under the GPL. However, these also
4195 have a special exception allowing you to distribute them with your
4196 package, regardless of the licensing you choose.
4200 @node Macro and Variable Index, General Index, Distributing, Top
4201 @unnumbered Macro and Variable Index
4207 @node General Index, , Macro and Variable Index, Top
4208 @unnumbered General Index