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 * Rebuilding:: Automatic rebuilding of Makefile
118 * Programs:: Building programs and libraries
119 * Other objects:: Other derived objects
120 * Other GNU Tools:: Other GNU Tools
121 * Documentation:: Building documentation
122 * Install:: What gets installed
123 * Clean:: What gets cleaned
124 * Dist:: What goes in a distribution
125 * Tests:: Support for test suites
126 * Options:: Changing Automake's behavior
127 * Miscellaneous:: Miscellaneous rules
128 * Include:: Including extra files in an Automake template.
129 * Conditionals:: Conditionals
130 * Gnits:: The effect of @code{--gnu} and @code{--gnits}
131 * Cygnus:: The effect of @code{--cygnus}
132 * Extending:: Extending Automake
133 * Distributing:: Distributing the Makefile.in
134 * Future:: Some ideas for the future
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 * Depth:: The kinds of packages
200 * Strictness:: Standards conformance checking
201 * Uniform:: The Uniform Naming Scheme
202 * Canonicalization:: How derived variables are named
206 @node General Operation, Depth, Generalities, Generalities
207 @section General Operation
209 Automake works by reading a @file{Makefile.am} and generating a
210 @file{Makefile.in}. Certain macros and targets defined in the
211 @file{Makefile.am} instruct Automake to generate more specialized code;
212 for instance, a @samp{bin_PROGRAMS} macro definition will cause targets
213 for compiling and linking programs to be generated.
215 @cindex Non-standard targets
216 @cindex cvs-dist, non-standard example
219 The macro definitions and targets in the @file{Makefile.am} are copied
220 verbatim into the generated file. This allows you to add arbitrary code
221 into the generated @file{Makefile.in}. For instance the Automake
222 distribution includes a non-standard @code{cvs-dist} target, which the
223 Automake maintainer uses to make distributions from his source control
226 @cindex GNU make extensions
228 Note that GNU make extensions are not recognized by Automake. Using
229 such extensions in a @file{Makefile.am} will lead to errors or confusing
232 Automake tries to group comments with adjoining targets and macro
233 definitions in an intelligent way.
235 @cindex Make targets, overriding
236 @cindex Overriding make targets
238 A target defined in @file{Makefile.am} generally overrides any such
239 target of a similar name that would be automatically generated by
240 @code{automake}. Although this is a supported feature, it is generally
241 best to avoid making use of it, as sometimes the generated rules are
244 @cindex Macros, overriding
245 @cindex Overriding make macros
247 Similarly, a macro defined in @file{Makefile.am} will override any
248 definition of the macro that @code{automake} would ordinarily create.
249 This feature is more often useful than the ability to override a target
250 definition. Be warned that many of the macros generated by
251 @code{automake} are considered to be for internal use only, and their
252 names might change in future releases.
254 @cindex Recursive operation of Automake
255 @cindex Automake, recursive operation
256 @cindex Example of recursive operation
258 When examining a macro definition, Automake will recursively examine
259 macros referenced in the definition. For example, if Automake is
260 looking at the content of @code{foo_SOURCES} in this snippet
264 foo_SOURCES = c.c $(xs)
267 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
268 contents of @code{foo_SOURCES}.
270 @cindex ## (special Automake comment)
271 @cindex Special Automake comment
272 @cindex Comment, special to Automake
274 Automake also allows a form of comment which is @emph{not} copied into
275 the output; all lines beginning with @samp{##} are completely ignored by
278 It is customary to make the first line of @file{Makefile.am} read:
280 @cindex Makefile.am, first line
281 @cindex First line of Makefile.am
284 ## Process this file with automake to produce Makefile.in
287 @c FIXME discuss putting a copyright into Makefile.am here? I would but
288 @c I don't know quite what to say.
290 @c FIXME document customary ordering of Makefile.am here!
293 @node Depth, Strictness, General Operation, Generalities
297 @cindex Package, Flat
298 @cindex Shallow package
299 @cindex Package, shallow
301 @cindex Package, deep
303 @code{automake} supports three kinds of directory hierarchy:
304 @samp{flat}, @samp{shallow}, and @samp{deep}.
306 A @dfn{flat} package is one in which all the files are in a single
307 directory. The @file{Makefile.am} for such a package by definition
308 lacks a @code{SUBDIRS} macro. An example of such a package is
312 @cindex SUBDIRS, deep package
314 A @dfn{deep} package is one in which all the source lies in
315 subdirectories; the top level directory contains mainly configuration
316 information. GNU @code{cpio} is a good example of such a package, as is
317 GNU @code{tar}. The top level @file{Makefile.am} for a deep package
318 will contain a @code{SUBDIRS} macro, but no other macros to define
319 objects which are built.
321 A @dfn{shallow} package is one in which the primary source resides in
322 the top-level directory, while various parts (typically libraries)
323 reside in subdirectories. Automake is one such package (as is GNU
324 @code{make}, which does not currently use @code{automake}).
327 @node Strictness, Uniform, Depth, Generalities
330 @cindex Non-GNU packages
332 While Automake is intended to be used by maintainers of GNU packages, it
333 does make some effort to accommodate those who wish to use it, but do
334 not want to use all the GNU conventions.
336 @cindex Strictness, defined
337 @cindex Strictness, foreign
338 @cindex foreign strictness
339 @cindex Strictness, gnu
340 @cindex gnits strictness
341 @cindex Strictness, gnits
342 @cindex gnits strictness
344 To this end, Automake supports three levels of @dfn{strictness}---the
345 strictness indicating how stringently Automake should check standards
348 The valid strictness levels are:
352 Automake will check for only those things which are absolutely
353 required for proper operations. For instance, whereas GNU standards
354 dictate the existence of a @file{NEWS} file, it will not be required in
355 this mode. The name comes from the fact that Automake is intended to be
356 used for GNU programs; these relaxed rules are not the standard mode of
360 Automake will check---as much as possible---for compliance to the GNU
361 standards for packages. This is the default.
364 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
365 standards}. These are based on the GNU standards, but are even more
366 detailed. Unless you are a Gnits standards contributor, it is
367 recommended that you avoid this option until such time as the Gnits
368 standard is actually published.
371 For more information on the precise implications of the strictness
372 level, see @ref{Gnits}.
375 @node Uniform, Canonicalization, Strictness, Generalities
376 @section The Uniform Naming Scheme
378 @cindex Uniform naming scheme
380 Automake macros (from here on referred to as @emph{variables}) generally
381 follow a @dfn{uniform naming scheme} that makes it easy to decide how
382 programs (and other derived objects) are built, and how they are
383 installed. This scheme also supports @code{configure} time
384 determination of what should be built.
386 @cindex _PROGRAMS primary variable
387 @cindex PROGRAMS primary variable
388 @cindex Primary variable, PROGRAMS
390 @cindex Primary variable, defined
392 At @code{make} time, certain variables are used to determine which
393 objects are to be built. These variables are called @dfn{primary
394 variables}. For instance, the primary variable @code{PROGRAMS} holds a
395 list of programs which are to be compiled and linked.
398 @cindex pkglibdir, defined
399 @cindex pkgincludedir, defined
400 @cindex pkgdatadir, defined
403 @vindex pkgincludedir
406 A different set of variables is used to decide where the built objects
407 should be installed. These variables are named after the primary
408 variables, but have a prefix indicating which standard directory should
409 be used as the installation directory. The standard directory names are
410 given in the GNU standards (@pxref{Directory Variables, , , standards,
411 The GNU Coding Standards}). Automake extends this list with
412 @code{pkglibdir}, @code{pkgincludedir}, and @code{pkgdatadir}; these are
413 the same as the non-@samp{pkg} versions, but with @samp{@@PACKAGE@@}
414 appended. For instance, @code{pkglibdir} is defined as
415 @code{$(libdir)/@@PACKAGE@@}.
418 @cindex EXTRA_, prepending
420 For each primary, there is one additional variable named by prepending
421 @samp{EXTRA_} to the primary name. This variable is used to list
422 objects which may or may not be built, depending on what
423 @code{configure} decides. This variable is required because Automake
424 must statically know the entire list of objects that may be built in
425 order to generate a @file{Makefile.in} that will work in all cases.
427 @cindex EXTRA_PROGRAMS, defined
428 @cindex Example, EXTRA_PROGRAMS
431 For instance, @code{cpio} decides at configure time which programs are
432 built. Some of the programs are installed in @code{bindir}, and some
433 are installed in @code{sbindir}:
436 EXTRA_PROGRAMS = mt rmt
437 bin_PROGRAMS = cpio pax
438 sbin_PROGRAMS = @@PROGRAMS@@
441 Defining a primary variable without a prefix (e.g. @code{PROGRAMS}) is
444 Note that the common @samp{dir} suffix is left off when constructing the
445 variable names; thus one writes @samp{bin_PROGRAMS} and not
446 @samp{bindir_PROGRAMS}.
448 Not every sort of object can be installed in every directory. Automake
449 will flag those attempts it finds in error. Automake will also diagnose
450 obvious misspellings in directory names.
452 @cindex Extending list of installation directories
453 @cindex Installation directories, extending list
455 Sometimes the standard directories---even as augmented by Automake---
456 are not enough. In particular it is sometimes useful, for clarity, to
457 install objects in a subdirectory of some predefined directory. To this
458 end, Automake allows you to extend the list of possible installation
459 directories. A given prefix (e.g. @samp{zar}) is valid if a variable of
460 the same name with @samp{dir} appended is defined (e.g. @code{zardir}).
462 @cindex HTML support, example
464 For instance, until HTML support is part of Automake, you could use this
465 to install raw HTML documentation:
468 htmldir = $(prefix)/html
469 html_DATA = automake.html
472 @cindex noinst primary prefix, definition
474 The special prefix @samp{noinst} indicates that the objects in question
475 should not be installed at all.
477 @cindex check primary prefix, definition
479 The special prefix @samp{check} indicates that the objects in question
480 should not be built until the @code{make check} command is run.
482 Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
483 @samp{LISP}, @samp{PYTHON}, @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS},
484 @samp{MANS}, and @samp{TEXINFOS}.
496 @node Canonicalization, , Uniform, Generalities
497 @section How derived variables are named
499 @cindex canonicalizing Automake macros
501 Sometimes a Makefile variable name is derived from some text the user
502 supplies. For instance, program names are rewritten into Makefile macro
503 names. Automake canonicalizes this text, so that it does not have to
504 follow Makefile macro naming rules. All characters in the name except
505 for letters, numbers, and the underscore are turned into underscores
506 when making macro references. For example, if your program is named
507 @code{sniff-glue}, the derived variable name would be
508 @code{sniff_glue_SOURCES}, not @code{sniff-glue_SOURCES}.
510 @node Examples, Invoking Automake, Generalities, Top
511 @chapter Some example packages
514 * Complete:: A simple example, start to finish
515 * Hello:: A classic program
516 * etags:: Building etags and ctags
520 @node Complete, Hello, Examples, Examples
521 @section A simple example, start to finish
523 @cindex Complete example
525 Let's suppose you just finished writing @code{zardoz}, a program to make
526 your head float from vortex to vortex. You've been using Autoconf to
527 provide a portability framework, but your @file{Makefile.in}s have been
528 ad-hoc. You want to make them bulletproof, so you turn to Automake.
530 @cindex AM_INIT_AUTOMAKE, example use
532 The first step is to update your @file{configure.in} to include the
533 commands that @code{automake} needs. The way to do this is to add an
534 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
537 AM_INIT_AUTOMAKE(zardoz, 1.0)
540 Since your program doesn't have any complicating factors (e.g., it
541 doesn't use @code{gettext}, it doesn't want to build a shared library),
542 you're done with this part. That was easy!
544 @cindex aclocal program, introduction
545 @cindex aclocal.m4, preexisting
546 @cindex acinclude.m4, defined
548 Now you must regenerate @file{configure}. But to do that, you'll need
549 to tell @code{autoconf} how to find the new macro you've used. The
550 easiest way to do this is to use the @code{aclocal} program to generate
551 your @file{aclocal.m4} for you. But wait... you already have an
552 @file{aclocal.m4}, because you had to write some hairy macros for your
553 program. The @code{aclocal} program lets you put your own macros into
554 @file{acinclude.m4}, so simply rename and then run:
557 mv aclocal.m4 acinclude.m4
562 @cindex zardoz example
564 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
565 Since @code{zardoz} is a user program, you want to install it where the
566 rest of the user programs go. Additionally, @code{zardoz} has some
567 Texinfo documentation. Your @file{configure.in} script uses
568 @code{AC_REPLACE_FUNCS}, so you need to link against @samp{@@LIBOBJS@@}.
569 So here's what you'd write:
572 bin_PROGRAMS = zardoz
573 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
574 zardoz_LDADD = @@LIBOBJS@@
576 info_TEXINFOS = zardoz.texi
579 Now you can run @code{automake --add-missing} to generate your
580 @file{Makefile.in} and grab any auxiliary files you might need, and
584 @node Hello, etags, Complete, Examples
585 @section A classic program
587 @cindex Example, GNU Hello
588 @cindex Hello example
589 @cindex GNU Hello, example
591 @uref{ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz, GNU hello} is
592 renowned for its classic simplicity and versatility. This section shows
593 how Automake could be used with the GNU Hello package. The examples
594 below are from the latest beta version of GNU Hello, but with all of the
595 maintainer-only code stripped out, as well as all copyright comments.
597 Of course, GNU Hello is somewhat more featureful than your traditional
598 two-liner. GNU Hello is internationalized, does option processing, and
599 has a manual and a test suite. GNU Hello is a deep package.
601 @cindex configure.in, from GNU Hello
602 @cindex GNU Hello, configure.in
603 @cindex Hello, configure.in
605 Here is the @file{configure.in} from GNU Hello:
608 dnl Process this file with autoconf to produce a configure script.
610 AM_INIT_AUTOMAKE(hello, 1.3.11)
611 AM_CONFIG_HEADER(config.h)
613 dnl Set of available languages.
614 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
616 dnl Checks for programs.
620 dnl Checks for libraries.
622 dnl Checks for header files.
624 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
626 dnl Checks for library functions.
629 dnl Check for st_blksize in struct stat
632 dnl internationalization macros
634 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
635 src/Makefile tests/Makefile tests/hello],
636 [chmod +x tests/hello])
639 The @samp{AM_} macros are provided by Automake (or the Gettext library);
640 the rest are standard Autoconf macros.
643 The top-level @file{Makefile.am}:
646 EXTRA_DIST = BUGS ChangeLog.O
647 SUBDIRS = doc intl po src tests
650 As you can see, all the work here is really done in subdirectories.
652 The @file{po} and @file{intl} directories are automatically generated
653 using @code{gettextize}; they will not be discussed here.
655 @cindex Texinfo file handling example
656 @cindex Example, handling Texinfo files
658 In @file{doc/Makefile.am} we see:
661 info_TEXINFOS = hello.texi
662 hello_TEXINFOS = gpl.texi
665 This is sufficient to build, install, and distribute the GNU Hello
668 @cindex Regression test example
669 @cindex Example, regression test
671 Here is @file{tests/Makefile.am}:
675 EXTRA_DIST = hello.in testdata
678 The script @file{hello} is generated by @code{configure}, and is the
679 only test case. @code{make check} will run this test.
681 @cindex INCLUDES, example usage
683 Last we have @file{src/Makefile.am}, where all the real work is done:
687 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
688 hello_LDADD = @@INTLLIBS@@ @@ALLOCA@@
689 localedir = $(datadir)/locale
690 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
694 @node etags, , Hello, Examples
695 @section Building etags and ctags
697 @cindex Example, ctags and etags
698 @cindex ctags Example
699 @cindex etags Example
701 Here is another, trickier example. It shows how to generate two
702 programs (@code{ctags} and @code{etags}) from the same source file
703 (@file{etags.c}). The difficult part is that each compilation of
704 @file{etags.c} requires different @code{cpp} flags.
707 bin_PROGRAMS = etags ctags
709 ctags_LDADD = ctags.o
712 $(COMPILE) -DETAGS_REGEXPS -c etags.c
715 $(COMPILE) -DCTAGS -o ctags.o -c etags.c
718 Note that @code{ctags_SOURCES} is defined to be empty---that way no
719 implicit value is substituted. The implicit value, however, is used to
720 generate @code{etags} from @file{etags.o}.
722 @code{ctags_LDADD} is used to get @file{ctags.o} into the link line.
723 @code{ctags_DEPENDENCIES} is generated by Automake.
725 The above rules won't work if your compiler doesn't accept both
726 @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
727 bogus dependency (to avoid problems with a parallel @code{make}):
730 etags.o: etags.c ctags.o
731 $(COMPILE) -DETAGS_REGEXPS -c etags.c
734 $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
737 Also, these explicit rules do not work if the de-ANSI-fication feature
738 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
742 etags._o: etags._c ctags.o
743 $(COMPILE) -DETAGS_REGEXPS -c etags.c
746 $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
750 @node Invoking Automake, configure, Examples, Top
751 @chapter Creating a @file{Makefile.in}
753 @cindex Multiple configure.in files
754 @cindex Invoking Automake
755 @cindex Automake, invoking
757 To create all the @file{Makefile.in}s for a package, run the
758 @code{automake} program in the top level directory, with no arguments.
759 @code{automake} will automatically find each appropriate
760 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
761 and generate the corresponding @file{Makefile.in}. Note that
762 @code{automake} has a rather simplistic view of what constitutes a
763 package; it assumes that a package has only one @file{configure.in}, at
764 the top. If your package has multiple @file{configure.in}s, then you
765 must run @code{automake} in each directory holding a
768 You can optionally give @code{automake} an argument; @file{.am} is
769 appended to the argument and the result is used as the name of the input
770 file. This feature is generally only used to automatically rebuild an
771 out-of-date @file{Makefile.in}. Note that @code{automake} must always
772 be run from the topmost directory of a project, even if being used to
773 regenerate the @file{Makefile.in} in some subdirectory. This is
774 necessary because @code{automake} must scan @file{configure.in}, and
775 because @code{automake} uses the knowledge that a @file{Makefile.in} is
776 in a subdirectory to change its behavior in some cases.
778 @cindex Automake options
779 @cindex Options, Automake
781 @code{automake} accepts the following options:
783 @cindex Extra files distributed with Automake
784 @cindex Files distributed with Automake
791 @opindex --add-missing
792 Automake requires certain common files to exist in certain situations;
793 for instance @file{config.guess} is required if @file{configure.in} runs
794 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
795 files; this option will cause the missing ones to be automatically added
796 to the package, whenever possible. In general if Automake tells you a
797 file is missing, try using this option. By default Automake tries to
798 make a symbolic link pointing to its own copy of the missing file; this
799 can be changed with @code{--copy}.
801 @item --amdir=@var{dir}
803 Look for Automake data files in directory @var{dir} instead of in the
804 installation directory. This is typically used for debugging.
806 @item --build-dir=@var{dir}
808 Tell Automake where the build directory is. This option is used when
809 including dependencies into a @file{Makefile.in} generated by @code{make
810 dist}; it should not be used otherwise.
814 When used with @code{--add-missing}, causes installed files to be
815 copied. The default is to make a symbolic link.
819 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
820 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
822 @item --force-missing
823 @opindex --force-missing
824 When used with @code{--add-missing}, causes standard files to be rebuilt
825 even if they already exist in the source tree. This involves removing
826 the file from the source tree before creating the new symlink (or, with
827 @code{--copy}, copying the new file).
831 Set the global strictness to @samp{foreign}. For more information, see
836 Set the global strictness to @samp{gnits}. For more information, see
841 Set the global strictness to @samp{gnu}. For more information, see
842 @ref{Gnits}. This is the default strictness.
846 Print a summary of the command line options and exit.
849 @itemx --include-deps
851 @opindex --include-deps
852 Include all automatically generated dependency information
853 (@pxref{Dependencies}) in the generated
854 @file{Makefile.in}. This is generally done when making a distribution;
857 @item --generate-deps
858 @opindex --generate-deps
859 Generate a file concatenating all automatically generated dependency
860 information (@pxref{Dependencies}) into one file, @file{.dep_segment}.
861 This is generally done when making a distribution; see @ref{Dist}. It
862 is useful when maintaining a @file{SMakefile} or makefiles for other
863 platforms (@file{Makefile.DOS}, etc.) It can only be used in
864 conjunction with @samp{--include-deps}, @samp{--srcdir-name}, and
865 @samp{--build-dir}. Note that if this option is given, no other
870 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
871 @file{configure.in}. This option causes it to only update those
872 @file{Makefile.in}s which are out of date with respect to one of their
876 @itemx --output-dir=@var{dir}
878 @opindex --output-dir
879 Put the generated @file{Makefile.in} in the directory @var{dir}.
880 Ordinarily each @file{Makefile.in} is created in the directory of the
881 corresponding @file{Makefile.am}. This option is used when making
884 @item --srcdir-name=@var{dir}
885 @opindex --srcdir-name
886 Tell Automake the name of the source directory associated with the
887 current build. This option is used when including dependencies into a
888 @file{Makefile.in} generated by @code{make dist}; it should not be used
895 Cause Automake to print information about which files are being read or
900 Print the version number of Automake and exit.
904 @node configure, Top level, Invoking Automake, Top
905 @chapter Scanning @file{configure.in}
907 @cindex configure.in, scanning
908 @cindex Scanning configure.in
910 Automake scans the package's @file{configure.in} to determine certain
911 information about the package. Some @code{autoconf} macros are required
912 and some variables must be defined in @file{configure.in}. Automake
913 will also use information from @file{configure.in} to further tailor its
916 Automake also supplies some Autoconf macros to make the maintenance
917 easier. These macros can automatically be put into your
918 @file{aclocal.m4} using the @code{aclocal} program.
921 * Requirements:: Configuration requirements
922 * Optional:: Other things Automake recognizes
923 * Invoking aclocal:: Auto-generating aclocal.m4
924 * Macros:: Autoconf macros supplied with Automake
925 * Extending aclocal:: Writing your own aclocal macros
929 @node Requirements, Optional, configure, configure
930 @section Configuration requirements
932 @cindex Automake requirements
933 @cindex Requirements of Automake
935 The one real requirement of Automake is that your @file{configure.in}
936 call @code{AM_INIT_AUTOMAKE}. This macro does several things which are
937 required for proper Automake operation.
938 @cvindex AM_INIT_AUTOMAKE
940 Here are the other macros which Automake requires but which are not run
941 by @code{AM_INIT_AUTOMAKE}:
943 @cindex AC_OUTPUT, scanning
947 Automake uses this to determine which files to create (@pxref{Output, ,
948 Creating Output Files, autoconf, The Autoconf Manual}). Listed files
949 named @code{Makefile} are treated as @file{Makefile}s. Other listed
950 files are treated differently. Currently the only difference is that a
951 @file{Makefile} is removed by @code{make distclean}, while other files
952 are removed by @code{make clean}.
953 @c FIXME: this is in violation of standards!
958 @node Optional, Invoking aclocal, Requirements, configure
959 @section Other things Automake recognizes
961 @cindex Macros Automake recognizes
962 @cindex Recognized macros by Automake
964 Automake will also recognize the use of certain macros and tailor the
965 generated @file{Makefile.in} appropriately. Currently recognized macros
966 and their effects are:
969 @item AC_CONFIG_HEADER
970 Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar
971 to @code{AC_CONFIG_HEADER} (@pxref{Configuration Headers, ,
972 Configuration Header Files, autoconf, The Autoconf Manual}), but does
973 some useful Automake-specific work.
974 @cvindex AC_CONFIG_HEADER
976 @item AC_CONFIG_AUX_DIR
977 Automake will look for various helper scripts, such as
978 @file{mkinstalldirs}, in the directory named in this macro invocation.
979 If not seen, the scripts are looked for in their @samp{standard}
980 locations (either the top source directory, or in the source directory
981 corresponding to the current @file{Makefile.am}, whichever is
982 appropriate). @xref{Input, , Finding `configure' Input, autoconf, The
984 @cvindex AC_CONFIG_AUX_DIR
985 FIXME: give complete list of things looked for in this directory
988 Automake will insert definitions for the variables defined by
989 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
990 or library. @xref{System Services, , System Services, autoconf, The
992 @cvindex AC_PATH_XTRA
994 @item AC_CANONICAL_HOST
996 Automake will ensure that @file{config.guess} and @file{config.sub}
997 exist. Also, the @file{Makefile} variables @samp{host_alias} and
998 @samp{host_triplet} are introduced. See both @ref{Canonicalizing, ,
999 Getting the Canonical System Type, autoconf, The Autoconf Manual}, and
1000 @ref{Generic Programs, , Generic Program Checks, autoconf, The Autoconf
1002 @c fixme xref autoconf docs.
1003 @cvindex AC_CANONICAL_HOST
1004 @cvindex AC_CHECK_TOOL
1006 @vindex host_triplet
1008 @item AC_CANONICAL_SYSTEM
1009 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
1010 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
1011 @xref{Canonicalizing, , Getting the Canonical System Type, autoconf, The
1013 @cvindex AC_CANONICAL_SYSTEM
1015 @vindex target_alias
1017 @item AC_FUNC_ALLOCA
1018 @itemx AC_FUNC_GETLOADAVG
1019 @itemx AC_FUNC_MEMCMP
1020 @itemx AC_STRUCT_ST_BLOCKS
1021 @itemx AC_FUNC_FNMATCH
1022 @itemx AC_FUNC_MKTIME
1023 @itemx AM_FUNC_STRTOD
1024 @itemx AC_REPLACE_FUNCS
1025 @itemx AC_REPLACE_GNU_GETOPT
1026 @itemx AM_WITH_REGEX
1027 Automake will ensure that the appropriate dependencies are generated for
1028 the objects corresponding to these macros. Also, Automake will verify
1029 that the appropriate source files are part of the distribution. Note
1030 that Automake does not come with any of the C sources required to use
1031 these macros, so @code{automake -a} will not install the sources.
1032 @xref{A Library}, for more information. Also, see @ref{Particular
1033 Functions, , Particular Function Checks, autoconf, The Autoconf Manual}.
1034 @cvindex AC_FUNC_ALLOCA
1035 @cvindex AC_FUNC_GETLOADAVG
1036 @cvindex AC_FUNC_MEMCMP
1037 @cvindex AC_STRUCT_ST_BLOCKS
1038 @cvindex AC_FUNC_FNMATCH
1039 @cvindex AC_FUNC_FNMATCH
1040 @cvindex AC_REPLACE_FUNCS
1041 @cvindex AC_REPLACE_GNU_GETOPT
1042 @cvindex AM_FUNC_STRTOD
1043 @cvindex AM_WITH_REGEX
1044 @cvindex AC_FUNC_MKTIME
1047 Automake will detect statements which put @file{.o} files into
1048 @code{LIBOBJS}, and will treat these additional files as if they were
1049 discovered via @code{AC_REPLACE_FUNCS}. @xref{Generic Functions, ,
1050 Generic Function Checks, autoconf, The Autoconf Manual}.
1053 @item AC_PROG_RANLIB
1054 This is required if any libraries are built in the package.
1055 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1057 @cvindex AC_PROG_RANLIB
1060 This is required if any C++ source is included. @xref{Particular
1061 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1062 @cvindex AC_PROG_CXX
1065 This is required if any Fortran 77 source is included. This macro is
1066 distributed with Autoconf version 2.13 and later. @xref{Particular
1067 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1068 @cvindex AC_PROG_F77
1070 @item AC_F77_LIBRARY_LDFLAGS
1071 This is required for programs and shared libraries that are a mixture of
1072 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
1073 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
1074 @cvindex AC_F77_LIBRARY_LDFLAGS
1076 @item AC_PROG_LIBTOOL
1077 Automake will turn on processing for @code{libtool} (@pxref{Top, ,
1078 Introduction, libtool, The Libtool Manual}).
1079 @cvindex AC_PROG_LIBTOOL
1082 If a Yacc source file is seen, then you must either use this macro or
1083 define the variable @samp{YACC} in @file{configure.in}. The former is
1084 preferred (@pxref{Particular Programs, , Particular Program Checks,
1085 autoconf, The Autoconf Manual}).
1086 @cvindex AC_PROG_YACC
1089 @item AC_DECL_YYTEXT
1090 This macro is required if there is Lex source in the package.
1091 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1093 @cvindex AC_DECL_YYTEXT
1096 If a Lex source file is seen, then this macro must be used.
1097 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1099 @cvindex AC_PROG_LEX
1102 If Automake sees that this variable is set in @file{configure.in}, it
1103 will check the @file{po} directory to ensure that all the named
1104 @samp{.po} files exist, and that all the @samp{.po} files that exist are
1106 @cvindex ALL_LINGUAS
1108 @item AM_C_PROTOTYPES
1109 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
1110 @cvindex AM_C_PROTOTYPES
1112 @item AM_GNU_GETTEXT
1113 This macro is required for packages which use GNU gettext
1114 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1115 this macro it ensures that the package meets some of gettext's
1117 @cvindex AM_GNU_GETTEXT
1119 @item AM_MAINTAINER_MODE
1120 @opindex --enable-maintainer-mode
1121 This macro adds a @samp{--enable-maintainer-mode} option to
1122 @code{configure}. If this is used, @code{automake} will cause
1123 @samp{maintainer-only} rules to be turned off by default in the
1124 generated @file{Makefile.in}s. This macro is disallowed in @samp{Gnits}
1125 mode (@pxref{Gnits}). This macro defines the @samp{MAINTAINER_MODE}
1126 conditional, which you can use in your own @file{Makefile.am}.
1127 @cvindex AM_MAINTAINER_MODE
1130 @itemx AC_CHECK_TOOL
1131 @itemx AC_CHECK_PROG
1132 @itemx AC_CHECK_PROGS
1134 @itemx AC_PATH_PROGS
1135 For each of these macros, the first argument is automatically defined as
1136 a variable in each generated @file{Makefile.in}. @xref{Setting Output
1137 Variables, , Setting Output Variables, autoconf, The Autoconf Manual},
1138 and @ref{Generic Programs, , Generic Program Checks, autoconf, The
1141 @cvindex AC_CHECK_TOOL
1142 @cvindex AC_CHECK_PROG
1143 @cvindex AC_CHECK_PROGS
1144 @cvindex AC_PATH_PROG
1145 @cvindex AC_PATH_PROGS
1150 @node Invoking aclocal, Macros, Optional, configure
1151 @section Auto-generating aclocal.m4
1153 @cindex Invoking aclocal
1154 @cindex aclocal, Invoking
1156 Automake includes a number of Autoconf macros which can be used in your
1157 package; some of them are actually required by Automake in certain
1158 situations. These macros must be defined in your @file{aclocal.m4};
1159 otherwise they will not be seen by @code{autoconf}.
1161 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1162 files based on the contents of @file{configure.in}. This provides a
1163 convenient way to get Automake-provided macros, without having to
1164 search around. Also, the @code{aclocal} mechanism is extensible for use
1167 At startup, @code{aclocal} scans all the @file{.m4} files it can find,
1168 looking for macro definitions. Then it scans @file{configure.in}. Any
1169 mention of one of the macros found in the first step causes that macro,
1170 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1172 The contents of @file{acinclude.m4}, if it exists, are also
1173 automatically included in @file{aclocal.m4}. This is useful for
1174 incorporating local macros into @file{configure}.
1176 @code{aclocal} tries to be smart about looking for new @code{AC_DEFUN}s
1177 in the files it scans. It will warn if it finds duplicates. It also
1178 tries to copy the full text of the scanned file into @file{aclocal.m4},
1179 including both @samp{#} and @samp{dnl} comments. If you want to make a
1180 comment which will be completely ignored by @code{aclocal}, use
1181 @samp{##} as the comment leader.
1183 @code{aclocal} accepts the following options:
1186 @item --acdir=@var{dir}
1188 Look for the macro files in @var{dir} instead of the installation
1189 directory. This is typically used for debugging.
1193 Print a summary of the command line options and exit.
1197 Add the directory @var{dir} to the list of directories searched for
1200 @item --output=@var{file}
1202 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1204 @item --print-ac-dir
1205 @opindex --print-ac-dir
1206 Prints the name of the directory which @code{aclocal} will search to
1207 find the @file{.m4} files. When this option is given, normal processing
1208 is suppressed. This option can be used by a package to determine where
1209 to install a macro file.
1213 Print the names of the files it examines.
1217 Print the version number of Automake and exit.
1221 @node Macros, Extending aclocal, Invoking aclocal, configure
1222 @section Autoconf macros supplied with Automake
1224 @c consider generating this node automatically from m4 files.
1227 @item AM_CONFIG_HEADER
1228 Automake will generate rules to automatically regenerate the config
1229 header. If you do use this macro, you must create the file
1230 @file{stamp-h.in} in your source directory. It can be empty.
1231 @cvindex AM_CONFIG_HEADER
1233 @item AM_ENABLE_MULTILIB
1234 This is used when a ``multilib'' library is being built. A
1235 @dfn{multilib} library is one that is built multiple times, once per
1236 target flag combination. This is only useful when the library is
1237 intended to be cross-compiled. The first optional argument is the name
1238 of the @file{Makefile} being generated; it defaults to @samp{Makefile}.
1239 The second option argument is used to find the top source directory; it
1240 defaults to the empty string (generally this should not be used unless
1241 you are familiar with the internals).
1243 @item AM_FUNC_STRTOD
1244 If the @code{strtod} function is not available, or does not work
1245 correctly (like the one on SunOS 5.4), add @file{strtod.o} to output
1246 variable @code{LIBOBJS}.
1247 @cvindex AM_FUNC_STRTOD
1249 @item AM_FUNC_ERROR_AT_LINE
1250 If the function @code{error_at_line} is not found, then add
1251 @file{error.o} to @code{LIBOBJS}.
1252 @cvindex AM_FUNC_ERROR_AT_LINE
1254 @item AM_FUNC_OBSTACK
1255 Check for the GNU obstacks code; if not found, add @file{obstack.o} to
1257 @cvindex AM_FUNC_OBSTACK
1259 @item AM_C_PROTOTYPES
1260 Check to see if function prototypes are understood by the compiler. If
1261 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1262 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1263 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1264 values to implement automatic de-ANSI-fication.
1265 @cvindex AM_C_PROTOTYPES
1267 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1268 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1269 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1270 found in @file{<termios.h>}.
1271 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1273 @item AM_INIT_AUTOMAKE
1274 Runs many macros that most @file{configure.in}'s need. This macro has
1275 two required arguments, the package and the version number. By default
1276 this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}. This
1277 can be avoided by passing in a non-empty third argument.
1279 @item AM_PATH_LISPDIR
1280 Searches for the program @code{emacs}, and, if found, sets the output
1281 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1282 @cvindex AM_PATH_LISPDIR
1284 @item AM_PROG_CC_STDC
1285 If the C compiler in not in ANSI C mode by default, try to add an option
1286 to output variable @code{CC} to make it so. This macro tries various
1287 options that select ANSI C on some system or another. It considers the
1288 compiler to be in ANSI C mode if it handles function prototypes correctly.
1290 If you use this macro, you should check after calling it whether the C
1291 compiler has been set to accept ANSI C; if not, the shell variable
1292 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1293 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1294 @code{ansi2knr} option (@pxref{ANSI}).
1297 @cindex HP-UX 10, lex problems
1298 @cindex lex problems with HP-UX 10
1299 Like @code{AC_PROG_LEX} with @code{AC_DECL_YYTEXT} (@pxref{Particular
1300 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}),
1301 but uses the @code{missing} script on systems that do not have
1302 @code{lex}. @samp{HP-UX 10} is one such system.
1305 This macro finds the @code{gcj} program or causes an error. It sets
1306 @samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
1308 @cvindex AM_PROG_GCJ
1310 @item AM_SANITY_CHECK
1311 This checks to make sure that a file created in the build directory is
1312 newer than a file in the source directory. This can fail on systems
1313 where the clock is set incorrectly. This macro is automatically run
1314 from @code{AM_INIT_AUTOMAKE}.
1316 @item AM_SYS_POSIX_TERMIOS
1317 @cvindex am_cv_sys_posix_termios
1318 @cindex POSIX termios headers
1319 @cindex termios POSIX headers
1320 Check to see if POSIX termios headers and functions are available on the
1321 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1322 @samp{yes}. If not, set the variable to @samp{no}.
1324 @item AM_TYPE_PTRDIFF_T
1325 @cvindex HAVE_PTRDIFF_T
1327 Define @samp{HAVE_PTRDIFF_T} if the type @samp{ptrdiff_t} is defined in
1330 @item AM_WITH_DMALLOC
1331 @cvindex WITH_DMALLOC
1332 @cindex dmalloc, support for
1333 @opindex --with-dmalloc
1335 @uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
1336 package. If the user configures with @samp{--with-dmalloc}, then define
1337 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
1341 @opindex --with-regex
1342 @cindex regex package
1344 Adds @samp{--with-regex} to the @code{configure} command line. If
1345 specified (the default), then the @samp{regex} regular expression
1346 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1347 @samp{WITH_REGEX} is defined.. If @samp{--without-regex} is given, then
1348 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1349 into @samp{LIBOBJS}.
1354 @node Extending aclocal, , Macros, configure
1355 @section Writing your own aclocal macros
1357 @cindex aclocal, extending
1358 @cindex Extending aclocal
1360 The @code{aclocal} program doesn't have any built-in knowledge of any
1361 macros, so it is easy to extend it with your own macros.
1363 This is mostly used for libraries which want to supply their own
1364 Autoconf macros for use by other programs. For instance the
1365 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1366 should be used by any package using @code{gettext}. When the library is
1367 installed, it installs this macro so that @code{aclocal} will find it.
1369 A file of macros should be a series of @code{AC_DEFUN}'s. The
1370 @code{aclocal} programs also understands @code{AC_REQUIRE}, so it is
1371 safe to put each macro in a separate file. @xref{Prerequisite Macros, ,
1372 , autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
1373 autoconf, The Autoconf Manual}.
1375 A macro file's name should end in @file{.m4}. Such files should be
1376 installed in @file{$(datadir)/aclocal}.
1379 @node Top level, Rebuilding, configure, Top
1380 @chapter The top-level @file{Makefile.am}
1382 @cindex SUBDIRS, explained
1384 In non-flat packages, the top level @file{Makefile.am} must tell
1385 Automake which subdirectories are to be built. This is done via the
1386 @code{SUBDIRS} variable.
1389 The @code{SUBDIRS} macro holds a list of subdirectories in which
1390 building of various sorts can occur. Many targets (e.g. @code{all}) in
1391 the generated @file{Makefile} will run both locally and in all specified
1392 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1393 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1394 (after configuration). This allows inclusion of libraries from packages
1395 which do not use Automake (such as @code{gettext}). The directories
1396 mentioned in @code{SUBDIRS} must be direct children of the current
1397 directory. For instance, you cannot put @samp{src/subdir} into
1400 In a deep package, the top-level @file{Makefile.am} is often very short.
1401 For instance, here is the @file{Makefile.am} from the GNU Hello
1405 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1406 SUBDIRS = doc intl po src tests
1409 @cindex SUBDIRS, overriding
1410 @cindex Overriding SUBDIRS
1412 It is possible to override the @code{SUBDIRS} variable if, like in the
1413 case of GNU @code{Inetutils}, you want to only build a subset of the
1414 entire package. In your @file{Makefile.am} include:
1417 SUBDIRS = @@MY_SUBDIRS@@
1420 Then in your @file{configure.in} you can specify:
1423 MY_SUBDIRS = "src doc lib po"
1424 AC_SUBST(MY_SUBDIRS)
1427 (Note that we don't use the variable name @code{SUBDIRS} in our
1428 @file{configure.in}; that would cause Automake to believe that every
1429 @file{Makefile.in} should recurse into the listed subdirectories.)
1431 The upshot of this is that Automake is tricked into building the package
1432 to take the subdirs, but doesn't actually bind that list until
1433 @code{configure} is run.
1435 Although the @code{SUBDIRS} macro can contain configure substitutions
1436 (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
1437 contents of this variable.
1439 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1440 @code{AC_PROG_MAKE_SET}.
1442 The use of @code{SUBDIRS} is not restricted to just the top-level
1443 @file{Makefile.am}. Automake can be used to construct packages of
1446 By default, Automake generates @file{Makefiles} which work depth-first
1447 (@samp{postfix}). However, it is possible to change this ordering. You
1448 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
1449 putting @samp{.} first will cause a @samp{prefix} ordering of
1452 Sometimes, such as when running @code{make dist}, you want all possible
1453 subdirectories to be examined. In this case Automake will use
1454 @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to
1455 recurse. This variable will also be used when the user runs
1456 @code{distclean} or @code{maintainer-clean}. It should be set to the
1457 full list of subdirectories in the project. If this macro is not set,
1458 Automake will attempt to set it for you.
1461 @node Rebuilding, Programs, Top level, Top
1462 @chapter Rebuilding Makefiles
1464 Automake generates rules to automatically rebuild @file{Makefile}s,
1465 @file{configure}, and other derived files like @file{Makefile.in}.
1467 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.in}, then
1468 these automatic rebuilding rules are only enabled in maintainer mode.
1470 Sometimes you need to run @code{aclocal} with an argument like @code{-I}
1471 to tell it where to find @file{.m4} files. Since sometimes @code{make}
1472 will automatically run @code{aclocal}, you need a way to specify these
1473 arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this
1474 holds arguments which are passed verbatim to @code{aclocal}. This macro
1475 is only useful in the top-level @file{Makefile.am}.
1476 @cindex ACLOCAL_AMFLAGS
1479 @node Programs, Other objects, Rebuilding, Top
1480 @chapter Building Programs and Libraries
1482 A large part of Automake's functionality is dedicated to making it easy
1483 to build programs and libraries.
1486 * A Program:: Building a program
1487 * A Library:: Building a library
1488 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1489 * A Shared Library:: Building a Libtool library
1490 * Program variables:: Variables used when building a program
1491 * Yacc and Lex:: Yacc and Lex support
1493 * Fortran 77 Support::
1495 * Support for Other Languages::
1496 * ANSI:: Automatic de-ANSI-fication
1497 * Dependencies:: Automatic dependency tracking
1501 @node A Program, A Library, Programs, Programs
1502 @section Building a program
1504 @cindex PROGRAMS, bindir
1505 @vindex bin_PROGRAMS
1506 @vindex sbin_PROGRAMS
1507 @vindex libexec_PROGRAMS
1508 @vindex pkglib_PROGRAMS
1509 @vindex noinst_PROGRAMS
1511 In a directory containing source that gets built into a program (as
1512 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
1513 can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
1514 @code{pkglibdir}, or not at all (@samp{noinst}).
1519 bin_PROGRAMS = hello
1522 In this simple case, the resulting @file{Makefile.in} will contain code
1523 to generate a program named @code{hello}. The variable
1524 @code{hello_SOURCES} is used to specify which source files get built
1528 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1531 This causes each mentioned @samp{.c} file to be compiled into the
1532 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1534 @cindex _SOURCES primary, defined
1535 @cindex SOURCES primary, defined
1536 @cindex Primary variable, SOURCES
1538 If @samp{@var{prog}_SOURCES} is needed, but not specified, then it
1539 defaults to the single file @file{prog.c}.
1543 Multiple programs can be built in a single directory. Multiple programs
1544 can share a single source file, which must be listed in each
1545 @samp{_SOURCES} definition.
1547 @cindex Header files in _SOURCES
1548 @cindex _SOURCES and header files
1550 Header files listed in a @samp{_SOURCES} definition will be included in
1551 the distribution but otherwise ignored. In case it isn't obvious, you
1552 should not include the header file generated by @file{configure} in an
1553 @samp{_SOURCES} variable; this file should not be distributed. Lex
1554 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1557 @cindex EXTRA_prog_SOURCES, defined
1559 Automake must know all the source files that could possibly go into a
1560 program, even if not all the files are built in every circumstance.
1561 Any files which are only conditionally built should be listed in the
1562 appropriate @samp{EXTRA_} variable. For instance, if
1563 @file{hello-linux.c} were conditionally included in @code{hello}, the
1564 @file{Makefile.am} would contain:
1567 EXTRA_hello_SOURCES = hello-linux.c
1570 Similarly, sometimes it is useful to determine the programs that are to
1571 be built at configure time. For instance, GNU @code{cpio} only builds
1572 @code{mt} and @code{rmt} under special circumstances.
1574 @cindex EXTRA_PROGRAMS, defined
1576 In this case, you must notify Automake of all the programs that can
1577 possibly be built, but at the same time cause the generated
1578 @file{Makefile.in} to use the programs specified by @code{configure}.
1579 This is done by having @code{configure} substitute values into each
1580 @samp{_PROGRAMS} definition, while listing all optionally built programs
1581 in @code{EXTRA_PROGRAMS}.
1582 @vindex EXTRA_PROGRAMS
1584 If you need to link against libraries that are not found by
1585 @code{configure}, you can use @code{LDADD} to do so. This variable
1586 actually can be used to add any options to the linker command line.
1589 @cindex prog_LDADD, defined
1591 Sometimes, multiple programs are built in one directory but do not share
1592 the same link-time requirements. In this case, you can use the
1593 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1594 program as it appears in some @samp{_PROGRAMS} variable, and usually
1595 written in lowercase) to override the global @code{LDADD}. If this
1596 variable exists for a given program, then that program is not linked
1600 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
1601 linked against the library @file{libcpio.a}. However, @code{rmt} is
1602 built in the same directory, and has no such link requirement. Also,
1603 @code{mt} and @code{rmt} are only built on certain architectures. Here
1604 is what cpio's @file{src/Makefile.am} looks like (abridged):
1607 bin_PROGRAMS = cpio pax @@MT@@
1608 libexec_PROGRAMS = @@RMT@@
1609 EXTRA_PROGRAMS = mt rmt
1611 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1614 cpio_SOURCES = @dots{}
1615 pax_SOURCES = @dots{}
1616 mt_SOURCES = @dots{}
1617 rmt_SOURCES = @dots{}
1620 @cindex _LDFLAGS, defined
1622 @samp{@var{prog}_LDADD} is inappropriate for passing program-specific
1623 linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
1624 @samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
1628 @cindex _DEPENDENCIES, defined
1630 It is also occasionally useful to have a program depend on some other
1631 target which is not actually part of that program. This can be done
1632 using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
1633 on the contents of such a variable, but no further interpretation is
1636 If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
1637 Automake. The automatically-assigned value is the contents of
1638 @samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
1639 @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
1640 configure substitutions that are left in are only @samp{@@LIBOBJS@@} and
1641 @samp{@@ALLOCA@@}; these are left because it is known that they will not
1642 cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
1646 @node A Library, LIBOBJS, A Program, Programs
1647 @section Building a library
1649 @cindex _LIBRARIES primary, defined
1650 @cindex LIBRARIES primary, defined
1651 @cindex Primary variable, LIBRARIES
1653 @vindex lib_LIBRARIES
1654 @vindex pkglib_LIBRARIES
1655 @vindex noinst_LIBRARIES
1657 Building a library is much like building a program. In this case, the
1658 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
1659 @code{libdir} or @code{pkglibdir}.
1661 @xref{A Shared Library}, for information on how to build shared
1662 libraries using Libtool and the @samp{LTLIBRARIES} primary.
1664 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
1665 For instance to create a library named @file{libcpio.a}, but not install
1666 it, you would write:
1669 noinst_LIBRARIES = libcpio.a
1672 The sources that go into a library are determined exactly as they are
1673 for programs, via the @samp{_SOURCES} variables. Note that the library
1674 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
1675 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
1676 not @samp{liblob.a_SOURCES}.
1678 @cindex _LIBADD primary, defined
1679 @cindex LIBADD primary, defined
1680 @cindex Primary variable, LIBADD
1682 Extra objects can be added to a library using the
1683 @samp{@var{library}_LIBADD} variable. This should be used for objects
1684 determined by @code{configure}. Again from @code{cpio}:
1689 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
1692 In addition, sources for extra objects that will not exist until
1693 configure-time must be added to the @code{BUILT_SOURCES} variable
1697 @node LIBOBJS, A Shared Library, A Library, Programs
1698 @section Special handling for LIBOBJS and ALLOCA
1700 @cindex @@LIBOBJS@@, special handling
1701 @cindex @@ALLOCA@@, special handling
1703 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
1704 @code{@@ALLOCA@@}, and uses this information, plus the list of
1705 @code{LIBOBJS} files derived from @file{configure.in} to automatically
1706 include the appropriate source files in the distribution (@pxref{Dist}).
1707 These source files are also automatically handled in the
1708 dependency-tracking scheme; see @xref{Dependencies}.
1710 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
1711 @samp{_LDADD} or @samp{_LIBADD} variable.
1714 @node A Shared Library, Program variables, LIBOBJS, Programs
1715 @section Building a Shared Library
1717 @cindex Shared libraries, support for
1719 Building shared libraries is a relatively complex matter. For this
1720 reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
1721 Libtool Manual}) was created to help build shared libraries in a
1722 platform-independent way.
1724 @cindex _LTLIBRARIES primary, defined
1725 @cindex LTLIBRARIES primary, defined
1726 @cindex Primary variable, LTLIBRARIES
1727 @cindex Example of shared libraries
1729 @cindex suffix .la, defined
1731 Automake uses Libtool to build libraries declared with the
1732 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
1733 of shared libraries to build. For instance, to create a library named
1734 @file{libgettext.a} and its corresponding shared libraries, and install
1735 them in @samp{libdir}, write:
1738 lib_LTLIBRARIES = libgettext.la
1741 @vindex lib_LTLIBRARIES
1742 @vindex pkglib_LTLIBRARIES
1743 @vindex noinst_LTLIBRARIES
1744 @vindex check_LTLIBRARIES
1746 @cindex check_LTLIBRARIES, not allowed
1748 Note that shared libraries @emph{must} be installed, so
1749 @code{check_LTLIBRARIES} is not allowed. However,
1750 @code{noinst_LTLIBRARIES} is allowed. This feature should be used for
1751 libtool ``convenience libraries''.
1753 @cindex suffix .lo, defined
1755 For each library, the @samp{@var{library}_LIBADD} variable contains the
1756 names of extra libtool objects (@file{.lo} files) to add to the shared
1757 library. The @samp{@var{library}_LDFLAGS} variable contains any
1758 additional libtool flags, such as @samp{-version-info} or
1761 @cindex @@LTLIBOBJS@@, special handling
1763 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
1764 library must use @code{@@LTLIBOBJS@@}. This is required because the
1765 object files that libtool operates on do not necessarily end in
1766 @file{.o}. The libtool manual contains more details on this topic.
1768 For libraries installed in some directory, Automake will automatically
1769 supply the appropriate @samp{-rpath} option. However, for libraries
1770 determined at configure time (and thus mentioned in
1771 @code{EXTRA_LTLIBRARIES}), Automake does not know the eventual
1772 installation directory; for such libraries you must add the
1773 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
1776 Ordinarily, Automake requires that a shared library's name start with
1777 @samp{lib}. However, if you are building a dynamically loadable module
1778 then you might wish to use a "nonstandard" name. In this case, put
1779 @code{-module} into the @samp{_LDFLAGS} variable.
1781 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
1782 libtool, The Libtool Manual}, for more information.
1785 @node Program variables, Yacc and Lex, A Shared Library, Programs
1786 @section Variables used when building a program
1788 Occasionally it is useful to know which @file{Makefile} variables
1789 Automake uses for compilations; for instance you might need to do your
1790 own compilation in some special cases.
1792 Some variables are inherited from Autoconf; these are @code{CC},
1793 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
1797 There are some additional variables which Automake itself defines:
1801 A list of @samp{-I} options. This can be set in your @file{Makefile.am}
1802 if you have special directories you want to look in. Automake already
1803 provides some @samp{-I} options automatically. In particular it
1804 generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I} pointing to
1805 the directory holding @file{config.h} (if you've used
1806 @code{AC_CONFIG_HEADER} or @code{AM_CONFIG_HEADER}). You can disable
1807 the default @samp{-I} options using the @samp{nostdinc} option.
1809 @code{INCLUDES} can actually be used for other @code{cpp} options
1810 besides @samp{-I}. For instance, it is sometimes used to pass arbitrary
1811 @samp{-D} options to the compiler.
1814 This is the command used to actually compile a C source file. The
1815 filename is appended to form the complete command line.
1818 This is the command used to actually link a C program.
1822 @node Yacc and Lex, C++ Support, Program variables, Programs
1823 @section Yacc and Lex support
1825 Automake has somewhat idiosyncratic support for Yacc and Lex.
1827 Automake assumes that the @file{.c} file generated by @code{yacc} (or
1828 @code{lex}) should be named using the basename of the input file. That
1829 is, for a yacc source file @file{foo.y}, Automake will cause the
1830 intermediate file to be named @file{foo.c} (as opposed to
1831 @file{y.tab.c}, which is more traditional).
1833 The extension of a yacc source file is used to determine the extension
1834 of the resulting @samp{C} or @samp{C++} file. Files with the extension
1835 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
1836 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
1839 Likewise, lex source files can be used to generate @samp{C} or
1840 @samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
1841 @samp{.lxx} are recognized.
1843 You should never explicitly mention the intermediate (@samp{C} or
1844 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
1847 The intermediate files generated by @code{yacc} (or @code{lex}) will be
1848 included in any distribution that is made. That way the user doesn't
1849 need to have @code{yacc} or @code{lex}.
1851 If a @code{yacc} source file is seen, then your @file{configure.in} must
1852 define the variable @samp{YACC}. This is most easily done by invoking
1853 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
1854 Program Checks, autoconf, The Autoconf Manual}).
1856 Similarly, if a @code{lex} source file is seen, then your
1857 @file{configure.in} must define the variable @samp{LEX}. You can use
1858 @samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
1859 Program Checks, autoconf, The Autoconf Manual}). Automake's @code{lex}
1860 support also requires that you use the @samp{AC_DECL_YYTEXT}
1861 macro---automake needs to know the value of @samp{LEX_OUTPUT_ROOT}.
1862 This is all handled for you if you use the @code{AM_PROG_LEX} macro
1866 @cindex yacc, multiple parsers
1867 @cindex Multiple yacc parsers
1868 @cindex Multiple lex lexers
1869 @cindex lex, multiple lexers
1872 Automake makes it possible to include multiple @code{yacc} (or
1873 @code{lex}) source files in a single program. Automake uses a small
1874 program called @code{ylwrap} to run @code{yacc} (or @code{lex}) in a
1875 subdirectory. This is necessary because yacc's output filename is
1876 fixed, and a parallel make could conceivably invoke more than one
1877 instance of @code{yacc} simultaneously. The @code{ylwrap} program is
1878 distributed with Automake. It should appear in the directory specified
1879 by @samp{AC_CONFIG_AUX_DIR} (@pxref{Input, , Finding `configure' Input,
1880 autoconf, The Autoconf Manual}), or the current directory if that macro
1881 is not used in @file{configure.in}.
1883 For @code{yacc}, simply managing locking is insufficient. The output of
1884 @code{yacc} always uses the same symbol names internally, so it isn't
1885 possible to link two @code{yacc} parsers into the same executable.
1887 We recommend using the following renaming hack used in @code{gdb}:
1889 #define yymaxdepth c_maxdepth
1890 #define yyparse c_parse
1892 #define yyerror c_error
1893 #define yylval c_lval
1894 #define yychar c_char
1895 #define yydebug c_debug
1896 #define yypact c_pact
1903 #define yyexca c_exca
1904 #define yyerrflag c_errflag
1905 #define yynerrs c_nerrs
1909 #define yy_yys c_yys
1910 #define yystate c_state
1913 #define yy_yyv c_yyv
1915 #define yylloc c_lloc
1916 #define yyreds c_reds
1917 #define yytoks c_toks
1918 #define yylhs c_yylhs
1919 #define yylen c_yylen
1920 #define yydefred c_yydefred
1921 #define yydgoto c_yydgoto
1922 #define yysindex c_yysindex
1923 #define yyrindex c_yyrindex
1924 #define yygindex c_yygindex
1925 #define yytable c_yytable
1926 #define yycheck c_yycheck
1927 #define yyname c_yyname
1928 #define yyrule c_yyrule
1931 For each define, replace the @samp{c_} prefix with whatever you like.
1932 These defines work for @code{bison}, @code{byacc}, and traditional
1933 @code{yacc}s. If you find a parser generator that uses a symbol not
1934 covered here, please report the new name so it can be added to the list.
1937 @node C++ Support, Fortran 77 Support, Yacc and Lex, Programs
1938 @section C++ Support
1941 @cindex Support for C++
1943 Automake includes full support for C++.
1945 Any package including C++ code must define the output variable
1946 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
1947 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
1948 Program Checks, autoconf, The Autoconf Manual}).
1950 A few additional variables are defined when a C++ source file is seen:
1954 The name of the C++ compiler.
1957 Any flags to pass to the C++ compiler.
1960 The command used to actually compile a C++ source file. The file name
1961 is appended to form the complete command line.
1964 The command used to actually link a C++ program.
1968 @node Fortran 77 Support, Java Support, C++ Support, Programs
1969 @comment node-name, next, previous, up
1970 @section Fortran 77 Support
1972 @cindex Fortran 77 support
1973 @cindex Support for Fortran 77
1975 Automake includes full support for Fortran 77.
1977 Any package including Fortran 77 code must define the output variable
1978 @samp{F77} in @file{configure.in}; the simplest way to do this is to use
1979 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
1980 Program Checks, autoconf, The Autoconf Manual}). @xref{Fortran 77 and
1983 A few additional variables are defined when a Fortran 77 source file is
1989 The name of the Fortran 77 compiler.
1992 Any flags to pass to the Fortran 77 compiler.
1995 Any flags to pass to the Ratfor compiler.
1998 The command used to actually compile a Fortran 77 source file. The file
1999 name is appended to form the complete command line.
2002 The command used to actually link a pure Fortran 77 program or shared
2007 Automake can handle preprocessing Fortran 77 and Ratfor source files in
2008 addition to compiling them@footnote{Much, if not most, of the
2009 information in the following sections pertaining to preprocessing
2010 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
2011 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
2012 also contains some support for creating programs and shared libraries
2013 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
2014 Fortran 77 With C and C++}).
2016 These issues are covered in the following sections.
2019 * Preprocessing Fortran 77::
2020 * Compiling Fortran 77 Files::
2021 * Mixing Fortran 77 With C and C++::
2022 * Fortran 77 and Autoconf::
2026 @node Preprocessing Fortran 77, Compiling Fortran 77 Files, Fortran 77 Support, Fortran 77 Support
2027 @comment node-name, next, previous, up
2028 @subsection Preprocessing Fortran 77
2030 @cindex Preprocessing Fortran 77
2031 @cindex Fortran 77, Preprocessing
2032 @cindex Ratfor programs
2034 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
2035 rule runs just the preprocessor to convert a preprocessable Fortran 77
2036 or Ratfor source file into a strict Fortran 77 source file. The precise
2037 command used is as follows:
2042 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2045 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2050 @node Compiling Fortran 77 Files, Mixing Fortran 77 With C and C++, Preprocessing Fortran 77, Fortran 77 Support
2051 @comment node-name, next, previous, up
2052 @subsection Compiling Fortran 77 Files
2054 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
2055 @file{N.r} by running the Fortran 77 compiler. The precise command used
2061 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
2064 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2067 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2072 @node Mixing Fortran 77 With C and C++, Fortran 77 and Autoconf, Compiling Fortran 77 Files, Fortran 77 Support
2073 @comment node-name, next, previous, up
2074 @subsection Mixing Fortran 77 With C and C++
2076 @cindex Fortran 77, mixing with C and C++
2077 @cindex Mixing Fortran 77 with C and C++
2078 @cindex Linking Fortran 77 with C and C++
2080 @cindex Mixing Fortran 77 with C and/or C++
2082 Automake currently provides @emph{limited} support for creating programs
2083 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
2084 However, there are many other issues related to mixing Fortran 77 with
2085 other languages that are @emph{not} (currently) handled by Automake, but
2086 that are handled by other packages@footnote{For example,
2087 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
2088 addresses all of these inter-language issues, and runs under nearly all
2089 Fortran 77, C and C++ compilers on nearly all platforms. However,
2090 @code{cfortran} is not yet Free Software, but it will be in the next
2094 Automake can help in two ways:
2098 Automatic selection of the linker depending on which combinations of
2102 Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
2103 @samp{-l}) to pass to the automatically selected linker in order to link
2104 in the appropriate Fortran 77 intrinsic and run-time libraries.
2106 @cindex FLIBS, defined
2107 These extra Fortran 77 linker flags are supplied in the output variable
2108 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
2109 supplied with newer versions of Autoconf (Autoconf version 2.13 and
2110 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
2114 If Automake detects that a program or shared library (as mentioned in
2115 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
2116 code that is a mixture of Fortran 77 and C and/or C++, then it requires
2117 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
2118 @file{configure.in}, and that either @code{$(FLIBS)} or @code{@@FLIBS@@}
2119 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
2120 (for shared libraries) variables. It is the responsibility of the
2121 person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
2122 or @code{@@FLIBS@@} appears in the appropriate @code{_LDADD} or
2123 @code{_LIBADD} variable.
2125 @cindex Mixed language example
2126 @cindex Example, mixed language
2128 For example, consider the following @file{Makefile.am}:
2132 foo_SOURCES = main.cc foo.f
2133 foo_LDADD = libfoo.la @@FLIBS@@
2135 pkglib_LTLIBRARIES = libfoo.la
2136 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
2137 libfoo_la_LIBADD = $(FLIBS)
2140 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
2141 is mentioned in @file{configure.in}. Also, if @code{@@FLIBS@@} hadn't
2142 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
2143 Automake would have issued a warning.
2148 * How the Linker is Chosen::
2151 @node How the Linker is Chosen, , Mixing Fortran 77 With C and C++, Mixing Fortran 77 With C and C++
2152 @comment node-name, next, previous, up
2153 @subsubsection How the Linker is Chosen
2155 @cindex Automatic linker selection
2156 @cindex Selecting the linker automatically
2158 The following diagram demonstrates under what conditions a particular
2159 linker is chosen by Automake.
2161 For example, if Fortran 77, C and C++ source code were to be compiled
2162 into a program, then the C++ linker will be used. In this case, if the
2163 C or Fortran 77 linkers required any special libraries that weren't
2164 included by the C++ linker, then they must be manually added to an
2165 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
2171 code \ C C++ Fortran
2172 ----------------- +---------+---------+---------+
2176 +---------+---------+---------+
2180 +---------+---------+---------+
2184 +---------+---------+---------+
2188 +---------+---------+---------+
2190 C + Fortran | | | x |
2192 +---------+---------+---------+
2194 C++ + Fortran | | x | |
2196 +---------+---------+---------+
2198 C + C++ + Fortran | | x | |
2200 +---------+---------+---------+
2204 @node Fortran 77 and Autoconf, , Mixing Fortran 77 With C and C++, Fortran 77 Support
2205 @comment node-name, next, previous, up
2206 @subsection Fortran 77 and Autoconf
2208 The current Automake support for Fortran 77 requires a recent enough
2209 version Autoconf that also includes support for Fortran 77. Full
2210 Fortran 77 support was added to Autoconf 2.13, so you will want to use
2211 that version of Autoconf or later.
2214 @node Java Support, Support for Other Languages, Fortran 77 Support, Programs
2215 @comment node-name, next, previous, up
2216 @section Java Support
2218 @cindex Java support
2219 @cindex Support for Java
2221 Automake includes support for compiled Java, using @code{gcj}, the Java
2222 front end to the GNU C compiler.
2224 Any package including Java code to be compiled must define the output
2225 variable @samp{GCJ} in @file{configure.in}; the variable @samp{GCJFLAGS}
2226 must also be defined somehow (either in @file{configure.in} or
2227 @file{Makefile.am}). The simplest way to do this is to use the
2228 @code{AM_PROG_GCJ} macro.
2230 By default, programs including Java source files are linked with
2234 @node Support for Other Languages, ANSI, Java Support, Programs
2235 @comment node-name, next, previous, up
2236 @section Support for Other Languages
2238 Automake currently only includes full support for C, C++ (@pxref{C++
2239 Support}), Fortran 77 (@pxref{Fortran 77 Support}), and Java
2240 (@pxref{Java Support}). There is only rudimentary support for other
2241 languages, support for which will be improved based on user demand.
2243 @c FIXME: mention suffix rule processing here.
2246 @node ANSI, Dependencies, Support for Other Languages, Programs
2247 @section Automatic de-ANSI-fication
2249 @cindex de-ANSI-fication, defined
2251 Although the GNU standards allow the use of ANSI C, this can have the
2252 effect of limiting portability of a package to some older compilers
2255 Automake allows you to work around this problem on such machines by
2256 @dfn{de-ANSI-fying} each source file before the actual compilation takes
2259 @vindex AUTOMAKE_OPTIONS
2262 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
2263 (@pxref{Options}) contains the option @code{ansi2knr} then code to
2264 handle de-ANSI-fication is inserted into the generated
2267 This causes each C source file in the directory to be treated as ANSI C.
2268 If an ANSI C compiler is available, it is used. If no ANSI C compiler
2269 is available, the @code{ansi2knr} program is used to convert the source
2270 files into K&R C, which is then compiled.
2272 The @code{ansi2knr} program is simple-minded. It assumes the source
2273 code will be formatted in a particular way; see the @code{ansi2knr} man
2276 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
2277 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
2278 these files are distributed with Automake. Also, the package
2279 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}
2281 @cvindex AM_C_PROTOTYPES
2283 Automake also handles finding the @code{ansi2knr} support files in some
2284 other directory in the current package. This is done by prepending the
2285 relative path to the appropriate directory to the @code{ansi2knr}
2286 option. For instance, suppose the package has ANSI C code in the
2287 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
2288 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
2289 @file{src/Makefile.am}:
2292 AUTOMAKE_OPTIONS = ../lib/ansi2knr
2295 If no directory prefix is given, the files are assumed to be in the
2298 Files mentioned in @code{LIBOBJS} which need de-ANSI-fication will not
2299 be automatically handled. That's because @code{configure} will generate
2300 an object name like @file{regex.o}, while @code{make} will be looking
2301 for @file{regex_.o} (when de-ANSI-fying). Eventually this problem will
2302 be fixed via @code{autoconf} magic, but for now you must put this code
2303 into your @file{configure.in}, just before the @code{AC_OUTPUT} call:
2306 # This is necessary so that .o files in LIBOBJS are also built via
2307 # the ANSI2KNR-filtering rules.
2308 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
2312 @node Dependencies, , ANSI, Programs
2313 @section Automatic dependency tracking
2315 As a developer it is often painful to continually update the
2316 @file{Makefile.in} whenever the include-file dependencies change in a
2317 project. Automake supplies a way to automatically track dependency
2318 changes, and distribute the dependencies in the generated
2321 Currently this support requires the use of GNU @code{make} and
2322 @code{gcc}. It might become possible in the future to supply a
2323 different dependency generating program, if there is enough demand. In
2324 the meantime, this mode is enabled by default if any C program or
2325 library is defined in the current directory, so you may get a @samp{Must
2326 be a separator} error from non-GNU make.
2330 When you decide to make a distribution, the @code{dist} target will
2331 re-run @code{automake} with @samp{--include-deps} and other options.
2332 @xref{Invoking Automake}, and @ref{Options}. This will cause the
2333 previously generated dependencies to be inserted into the generated
2334 @file{Makefile.in}, and thus into the distribution. This step also
2335 turns off inclusion of the dependency generation code, so that those who
2336 download your distribution but don't use GNU @code{make} and @code{gcc}
2337 will not get errors.
2339 @vindex OMIT_DEPENDENCIES
2341 When added to the @file{Makefile.in}, the dependencies have all
2342 system-specific dependencies automatically removed. This can be done by
2343 listing the files in @samp{OMIT_DEPENDENCIES}. For instance all
2344 references to system header files are removed by Automake. Sometimes it
2345 is useful to specify that a certain header file should be removed. For
2346 instance if your @file{configure.in} uses @samp{AM_WITH_REGEX}, then any
2347 dependency on @file{rx.h} or @file{regex.h} should be removed, because
2348 the correct one cannot be known until the user configures the package.
2350 As it turns out, Automake is actually smart enough to handle the
2351 particular case of the regular expression header. It will also
2352 automatically omit @file{libintl.h} if @samp{AM_GNU_GETTEXT} is used.
2354 @vindex AUTOMAKE_OPTIONS
2355 @opindex no-dependencies
2357 Automatic dependency tracking can be suppressed by putting
2358 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}.
2360 If you unpack a distribution made by @code{make dist}, and you want to
2361 turn on the dependency-tracking code again, simply re-run
2364 The actual dependency files are put under the build directory, in a
2365 subdirectory named @file{.deps}. These dependencies are machine
2366 specific. It is safe to delete them if you like; they will be
2367 automatically recreated during the next build.
2370 @node Other objects, Other GNU Tools, Programs, Top
2371 @chapter Other Derived Objects
2373 Automake can handle derived objects which are not C programs. Sometimes
2374 the support for actually building such objects must be explicitly
2375 supplied, but Automake will still automatically handle installation and
2379 * Scripts:: Executable scripts
2380 * Headers:: Header files
2381 * Data:: Architecture-independent data files
2382 * Sources:: Derived sources
2386 @node Scripts, Headers, Other objects, Other objects
2387 @section Executable Scripts
2389 @cindex _SCRIPTS primary, defined
2390 @cindex SCRIPTS primary, defined
2391 @cindex Primary variable, SCRIPTS
2393 It is possible to define and install programs which are scripts. Such
2394 programs are listed using the @samp{SCRIPTS} primary name. Automake
2395 doesn't define any dependencies for scripts; the @file{Makefile.am}
2396 should include the appropriate rules.
2399 Automake does not assume that scripts are derived objects; such objects
2400 must be deleted by hand (@pxref{Clean}).
2402 The @code{automake} program itself is a Perl script that is generated at
2403 configure time from @file{automake.in}. Here is how this is handled:
2406 bin_SCRIPTS = automake
2409 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
2410 for it is automatically generated.
2412 @cindex SCRIPTS, installation directories
2413 @cindex Installing scripts
2416 @vindex sbin_SCRIPTS
2417 @vindex libexec_SCRIPTS
2418 @vindex pkgdata_SCRIPTS
2419 @vindex noinst_SCRIPTS
2421 Script objects can be installed in @code{bindir}, @code{sbindir},
2422 @code{libexecdir}, or @code{pkgdatadir}.
2425 @node Headers, Data, Scripts, Other objects
2426 @section Header files
2428 @cindex _HEADERS primary, defined
2429 @cindex HEADERS primary, defined
2430 @cindex Primary variable, HEADERS
2432 @vindex noinst_HEADERS
2434 Header files are specified by the @samp{HEADERS} family of variables.
2435 Generally header files are not installed, so the @code{noinst_HEADERS}
2436 variable will be the most used.
2439 All header files must be listed somewhere; missing ones will not appear
2440 in the distribution. Often it is clearest to list uninstalled headers
2441 with the rest of the sources for a program. @xref{A Program}. Headers
2442 listed in a @samp{_SOURCES} variable need not be listed in any
2443 @samp{_HEADERS} variable.
2445 @cindex HEADERS, installation directories
2446 @cindex Installing headers
2448 @vindex include_HEADERS
2449 @vindex oldinclude_HEADERS
2450 @vindex pkginclude_HEADERS
2452 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
2453 @code{pkgincludedir}.
2456 @node Data, Sources, Headers, Other objects
2457 @section Architecture-independent data files
2459 @cindex _DATA primary, defined
2460 @cindex DATA primary, defined
2461 @cindex Primary variable, DATA
2463 Automake supports the installation of miscellaneous data files using the
2464 @samp{DATA} family of variables.
2468 @vindex sysconf_DATA
2469 @vindex sharedstate_DATA
2470 @vindex localstate_DATA
2471 @vindex pkgdata_DATA
2473 Such data can be installed in the directories @code{datadir},
2474 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
2477 By default, data files are @emph{not} included in a distribution.
2479 Here is how Automake installs its auxiliary data files:
2482 pkgdata_DATA = clean-kr.am clean.am @dots{}
2486 @node Sources, , Data, Other objects
2487 @section Built sources
2489 @cindex BUILT_SOURCES, defined
2491 Occasionally a file which would otherwise be called @samp{source}
2492 (e.g. a C @samp{.h} file) is actually derived from some other file.
2493 Such files should be listed in the @code{BUILT_SOURCES} variable.
2494 @vindex BUILT_SOURCES
2496 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
2497 must be created early in the build process can be listed in this
2500 A source file listed in @code{BUILT_SOURCES} is created before the other
2501 @code{all} targets are made. However, such a source file is not
2502 compiled unless explicitly requested by mentioning it in some other
2503 @samp{_SOURCES} variable.
2506 @node Other GNU Tools, Documentation, Other objects, Top
2507 @chapter Other GNU Tools
2509 Since Automake is primarily intended to generate @file{Makefile.in}s for
2510 use in GNU programs, it tries hard to interoperate with other GNU tools.
2513 * Emacs Lisp:: Emacs Lisp
2522 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
2525 @cindex _LISP primary, defined
2526 @cindex LISP primary, defined
2527 @cindex Primary variable, LISP
2533 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
2534 is used to hold a list of @file{.el} files. Possible prefixes for this
2535 primary are @samp{lisp_} and @samp{noinst_}. Note that if
2536 @code{lisp_LISP} is defined, then @file{configure.in} must run
2537 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
2541 By default Automake will byte-compile all Emacs Lisp source files using
2542 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
2543 byte-compiling, simply define the variable @code{ELCFILES} to be empty.
2544 Byte-compiled Emacs Lisp files are not portable among all versions of
2545 Emacs, so it makes sense to turn this off if you expect sites to have
2546 more than one version of Emacs installed. Furthermore, many packages
2547 don't actually benefit from byte-compilation. Still, we recommend that
2548 you leave it enabled by default. It is probably better for sites with
2549 strange setups to cope for themselves than to make the installation less
2550 nice for everybody else.
2553 @node gettext, Guile, Emacs Lisp, Other GNU Tools
2556 @cindex GNU Gettext support
2557 @cindex Gettext support
2558 @cindex Support for GNU Gettext
2560 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
2561 turns on support for GNU gettext, a message catalog system for
2562 internationalization
2563 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
2565 The @code{gettext} support in Automake requires the addition of two
2566 subdirectories to the package, @file{intl} and @file{po}. Automake
2567 insures that these directories exist and are mentioned in
2570 Furthermore, Automake checks that the definition of @code{ALL_LINGUAS}
2571 in @file{configure.in} corresponds to all the valid @file{.po} files,
2575 @node Guile, Libtool, gettext, Other GNU Tools
2578 Automake provides some automatic support for writing Guile modules.
2579 Automake will turn on Guile support if the @code{AM_INIT_GUILE_MODULE}
2580 macro is used in @file{configure.in}.
2582 Right now Guile support just means that the @code{AM_INIT_GUILE_MODULE}
2583 macro is understood to mean:
2586 @code{AM_INIT_AUTOMAKE} is run.
2589 @code{AC_CONFIG_AUX_DIR} is run, with a path of @file{..}.
2592 As the Guile module code matures, no doubt the Automake support will
2596 @node Libtool, Java, Guile, Other GNU Tools
2599 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
2600 libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
2601 @xref{A Shared Library}.
2604 @node Java, Python, Libtool, Other GNU Tools
2607 @cindex _JAVA primary, defined
2608 @cindex JAVA primary, defined
2609 @cindex Primary variable, JAVA
2611 Automake provides some minimal support for Java compilation with the
2612 @samp{JAVA} primary.
2614 Any @file{.java} files listed in a @samp{_JAVA} variable will be
2615 compiled with @code{JAVAC} at build time. By default, @file{.class}
2616 files are not included in the distribution.
2618 @cindex JAVA restrictions
2619 @cindex Restrictions for JAVA
2621 Currently Automake enforces the restriction that only one @samp{_JAVA}
2622 primary can be used in a given @file{Makefile.am}. The reason for this
2623 restriction is that, in general, it isn't possible to know which
2624 @file{.class} files were generated from which @file{.java} files -- so
2625 it would be impossible to know which files to install where.
2627 @node Python, , Java, Other GNU Tools
2630 @cindex _PYTHON primary, defined
2631 @cindex PYTHON primary, defined
2632 @cindex Primary variable, PYTHON
2635 Automake provides support for Python modules. Automake will turn on
2636 Python support if the @code{AM_CHECK_PYTHON} macro is used in
2637 @file{configure.in}. The @samp{PYTHON} primary is used to hold a list
2638 of @file{.py} files. Possible prefixes for this primary are
2639 @samp{python_} and @samp{noinst_}. Note that if @code{python_PYTHON} is
2640 defined, then @file{configure.in} must run @code{AM_CHECK_PYTHON}.
2642 @code{AM_CHECK_PYTHON} takes a single argument --- either the word
2643 @samp{module} or @samp{package}. The first installs files directly into
2644 the @file{site-packages} directory and is used when the @file{.py[co]}
2645 files must be on the @code{PYTHONPATH}. The second is used for modules
2646 distributed as a package, which should be installed in a subdirectory
2647 of @file{site-packages} and contain the @file{__init__.py} file. The
2648 subdirectory name is the same as the name given by @samp{PACKAGE}.
2651 @code{AM_CHECK_PYTHON} creates several output variables based on the
2652 Python installation found during configuration.
2656 The name of the Python executable.
2658 @item PYTHON_VERSION
2659 The Python version number, in the form @var{major}.@var{minor}
2660 (e.g. @samp{1.5}). This is currently the value of
2661 @code{sys.version[:3]}.
2664 The string @code{$prefix}. This term may be used in future work
2665 which needs the contents of Python's @code{sys.prefix}, but general
2666 consensus is to always use the value from configure.
2668 @item PYTHON_EXEC_PREFIX
2669 The string @code{$exec_prefix}. This term may be used in future work
2670 which needs the contents of Python's @code{sys.exec_prefix}, but general
2671 consensus is to always use the value from configure.
2673 @item PYTHON_PLATFORM
2674 The canonical name used by Python to describe the operating system, as
2675 given by @code{sys.platform}. This value is sometimes needed when
2676 building Python extensions.
2679 The directory name for the top of the standard Python library.
2682 The location of the platform-independent @file{site-packages} directory,
2683 where `module' files are installed. Note that older versions of Python
2684 (pre-1.5) used @file{$prefix/lib/site-python} so future versions of
2685 Automake's Python support may provide backwards compatibility.
2687 @item PYTHON_SITE_PACKAGE
2688 The string @code{$PYTHON_SITE/$PACKAGE}. This is the default
2689 installation directory for a Python `package.'
2691 @item PYTHON_SITE_INSTALL
2692 The top-level directory in which the Python files will be installed. It
2693 will be the value of either @samp{PYTHON_SITE} or @samp{PYTHON_PACKAGE}
2694 depending on the argument given to @code{AM_CHECK_PYTHON}.
2696 @item PYTHON_SITE_EXEC
2697 The location of the platform-dependent @file{site-packages} directory,
2698 where shared library extensions should be placed. Note that older
2699 versions of Python (pre-1.5) used @file{sharedmodules} so future version
2700 of Automake's Python support may provide backwards compatibility.
2707 By default Automake will byte-compile all Python source files to both
2708 @file{.pyc} and @file{.pyo} forms. If you wish to avoid generating the
2709 optimized byte-code files, simply define the variable @code{PYOFILES} to
2710 be empty. Similarly, if you don't wish to generate the standard
2711 byte-compiled files, define the variable @code{PYCFILES} to be empty.
2714 @node Documentation, Install, Other GNU Tools, Top
2715 @chapter Building documentation
2717 Currently Automake provides support for Texinfo and man pages.
2721 * Man pages:: Man pages
2725 @node Texinfo, Man pages, Documentation, Documentation
2728 @cindex _TEXINFOS primary, defined
2729 @cindex TEXINFOS primary, defined
2730 @cindex Primary variable, TEXINFOS
2732 If the current directory contains Texinfo source, you must declare it
2733 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
2734 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
2735 here. Note that any Texinfo source file must end in the @file{.texi} or
2736 @file{.texinfo} extension.
2738 @vindex info_TEXINFOS
2740 @cindex Texinfo macro, VERSION
2741 @cindex Texinfo macro, UPDATED
2742 @cindex Texinfo macro, EDITION
2744 @cindex VERSION Texinfo macro
2745 @cindex UPDATED Texinfo macro
2746 @cindex EDITION Texinfo macro
2750 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
2751 that file will be automatically generated. The file @file{version.texi}
2752 defines three Texinfo macros you can reference: @code{EDITION},
2753 @code{VERSION}, and @code{UPDATED}. The first two hold the version
2754 number of your package (but are kept separate for clarity); the last is
2755 the date the primary file was last modified. The @file{version.texi}
2756 support requires the @code{mdate-sh} program; this program is supplied
2757 with Automake and automatically included when @code{automake} is invoked
2758 with the @code{--add-missing} option.
2760 If you have multiple Texinfo files, and you want to use the
2761 @file{version.texi} feature, then you have to have a separate version
2762 file for each Texinfo file. Automake will treat any include in a
2763 Texinfo file that matches @samp{vers*.texi} just as an automatically
2764 generated version file.
2766 Sometimes an info file actually depends on more than one @file{.texi}
2767 file. For instance, in GNU Hello, @file{hello.texi} includes the file
2768 @file{gpl.texi}. You can tell Automake about these dependencies using
2769 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
2774 info_TEXINFOS = hello.texi
2775 hello_TEXINFOS = gpl.texi
2780 By default, Automake requires the file @file{texinfo.tex} to appear in
2781 the same directory as the Texinfo source. However, if you used
2782 @code{AC_CONFIG_AUX_DIR} in @file{configure.in} (@pxref{Input, , Finding
2783 `configure' Input, autoconf, The Autoconf Manual}), then
2784 @file{texinfo.tex} is looked for there. Automake supplies
2785 @file{texinfo.tex} if @samp{--add-missing} is given.
2789 If your package has Texinfo files in many directories, you can use the
2790 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
2791 @file{texinfo.tex} for your package. The value of this variable should
2792 be the relative path from the current @file{Makefile.am} to
2796 TEXINFO_TEX = ../doc/texinfo.tex
2799 @opindex no-texinfo.tex
2801 The option @samp{no-texinfo.tex} can be used to eliminate the
2802 requirement for @file{texinfo.tex}. Use of the variable
2803 @code{TEXINFO_TEX} is preferable, however, because that allows the
2804 @code{dvi} target to still work.
2806 @cindex Target, install-info
2807 @cindex Target, noinstall-info
2808 @cindex install-info target
2809 @cindex noinstall-info target
2811 @opindex no-installinfo
2812 @trindex install-info
2814 Automake generates an @code{install-info} target; some people apparently
2815 use this. By default, info pages are installed by @samp{make install}.
2816 This can be prevented via the @code{no-installinfo} option.
2819 @node Man pages, , Texinfo, Documentation
2822 @cindex _MANS primary, defined
2823 @cindex MANS primary, defined
2824 @cindex Primary variable, MANS
2826 A package can also include man pages (but see the GNU standards on this
2827 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
2828 pages are declared using the @samp{MANS} primary. Generally the
2829 @code{man_MANS} macro is used. Man pages are automatically installed in
2830 the correct subdirectory of @code{mandir}, based on the file extension.
2834 File extensions such as @samp{.1c} are handled by looking for the valid
2835 part of the extension and using that to determine the correct
2836 subdirectory of @code{mandir}. Valid section names are the digits
2837 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
2839 Sometimes developers prefer to name a man page something like
2840 @file{foo.man} in the source, and then rename it to have the correct
2841 suffix, e.g. @file{foo.1}, when installing the file. Automake also
2842 supports this mode. For a valid section named @var{SECTION}, there is a
2843 corresponding directory named @samp{man@var{SECTION}dir}, and a
2844 corresponding @samp{_MANS} variable. Files listed in such a variable
2845 are installed in the indicated section. If the file already has a
2846 valid suffix, then it is installed as-is; otherwise the file suffix is
2847 changed to match the section.
2849 For instance, consider this example:
2851 man1_MANS = rename.man thesame.1 alsothesame.1c
2854 In this case, @file{rename.man} will be renamed to @file{rename.1} when
2855 installed, but the other files will keep their names.
2857 @cindex Target, install-man
2858 @cindex Target, noinstall-man
2859 @cindex install-man target
2860 @cindex noinstall-man target
2862 @c Use @samp{make install} per documentation: (texi)code.
2863 By default, man pages are installed by @samp{make install}. However,
2864 since the GNU project does not require man pages, many maintainers do
2865 not expend effort to keep the man pages up to date. In these cases, the
2866 @code{no-installman} option will prevent the man pages from being
2867 installed by default. The user can still explicitly install them via
2868 @samp{make install-man}.
2869 @opindex no-installman
2870 @trindex install-man
2872 Here is how the documentation is handled in GNU @code{cpio} (which
2873 includes both Texinfo documentation and man pages):
2876 info_TEXINFOS = cpio.texi
2877 man_MANS = cpio.1 mt.1
2878 EXTRA_DIST = $(man_MANS)
2881 Texinfo source and info pages are all considered to be source for the
2882 purposes of making a distribution.
2884 Man pages are not currently considered to be source, because it is not
2885 uncommon for man pages to be automatically generated. For the same
2886 reason, they are not automatically included in the distribution.
2889 @node Install, Clean, Documentation, Top
2890 @chapter What Gets Installed
2892 @cindex Installation support
2893 @cindex make install support
2895 Naturally, Automake handles the details of actually installing your
2896 program once it has been built. All @code{PROGRAMS}, @code{SCRIPTS},
2897 @code{LIBRARIES}, @code{LISP}, @code{DATA} and @code{HEADERS} are
2898 automatically installed in the appropriate places.
2900 Automake also handles installing any specified info and man pages.
2902 Automake generates separate @code{install-data} and @code{install-exec}
2903 targets, in case the installer is installing on multiple machines which
2904 share directory structure---these targets allow the machine-independent
2905 parts to be installed only once. The @code{install} target depends on
2906 both of these targets.
2907 @trindex install-data
2908 @trindex install-exec
2911 Automake also generates an @code{uninstall} target, an
2912 @code{installdirs} target, and an @code{install-strip} target.
2914 @trindex installdirs
2915 @trindex install-strip
2917 It is possible to extend this mechanism by defining an
2918 @code{install-exec-local} or @code{install-data-local} target. If these
2919 targets exist, they will be run at @samp{make install} time.
2920 @trindex install-exec-local
2921 @trindex install-data-local
2923 Variables using the standard directory prefixes @samp{data},
2924 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
2925 @samp{pkgdata}, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
2926 installed by @samp{install-data}.
2928 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
2929 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
2930 @samp{pkglib} (e.g. @samp{bin_PROGRAMS}) are installed by
2931 @samp{install-exec}.
2933 Any variable using a user-defined directory prefix with @samp{exec} in
2934 the name (e.g. @samp{myexecbin_PROGRAMS} is installed by
2935 @samp{install-exec}. All other user-defined prefixes are installed by
2936 @samp{install-data}.
2939 Automake generates support for the @samp{DESTDIR} variable in all
2940 install rules. @samp{DESTDIR} is used during the @samp{make install}
2941 step to relocate install objects into a staging area. Each object and
2942 path is prefixed with the value of @samp{DESTDIR} before being copied
2943 into the install area. Here is an example of typical DESTDIR usage:
2946 make DESTDIR=/tmp/staging install
2949 This places install objects in a directory tree built under
2950 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
2951 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
2952 would install @file{/tmp/staging/gnu/bin/foo} and
2953 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
2955 This feature is commonly used to build install images and packages. For
2956 more information, see @ref{Makefile Conventions, , , standards, The GNU
2960 @node Clean, Dist, Install, Top
2961 @chapter What Gets Cleaned
2963 @cindex make clean support
2965 The GNU Makefile Standards specify a number of different clean rules.
2967 Generally the files that can be cleaned are determined automatically by
2968 Automake. Of course, Automake also recognizes some variables that can
2969 be defined to specify additional files to clean. These variables are
2970 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
2971 @code{MAINTAINERCLEANFILES}.
2972 @vindex MOSTLYCLEANFILES
2974 @vindex DISTCLEANFILES
2975 @vindex MAINTAINERCLEANFILES
2978 @node Dist, Tests, Clean, Top
2979 @chapter What Goes in a Distribution
2982 @cindex make distcheck
2984 The @code{dist} target in the generated @file{Makefile.in} can be used
2985 to generate a gzip'd @code{tar} file for distribution. The tar file is
2986 named based on the @samp{PACKAGE} and @samp{VERSION} variables; more
2987 precisely it is named @samp{@var{package}-@var{version}.tar.gz}.
2991 You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
2992 is run. The default setting is @samp{--best}.
2994 For the most part, the files to distribute are automatically found by
2995 Automake: all source files are automatically included in a distribution,
2996 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
2997 has a built-in list of commonly used files which, if present in the
2998 current directory, are automatically included. This list is printed by
2999 @samp{automake --help}. Also, files which are read by @code{configure}
3000 (i.e. the source files corresponding to the files specified in the
3001 @code{AC_OUTPUT} invocation) are automatically distributed.
3003 Still, sometimes there are files which must be distributed, but which
3004 are not covered in the automatic rules. These files should be listed in
3005 the @code{EXTRA_DIST} variable. You can mention files from
3006 subdirectories in @code{EXTRA_DIST}. You can also mention a directory
3007 there; in this case the entire directory will be recursively copied into
3008 the distribution. Please note that this will also copy
3009 @emph{everything} in the directory, including CVS/RCS version control
3014 Sometimes you need tighter control over what does @emph{not} go into the
3015 distribution; for instance you might have source files which are
3016 generated and which you do not want to distribute. In this case
3017 Automake gives fine-grained control using the @samp{dist} and
3018 @samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
3019 prefixed with @samp{dist_} to add the listed files to the distribution.
3020 Similarly, @samp{nodist_} can be used to omit the files from the
3025 As an example, here is how you would cause some data to be distributed
3026 while leaving some source code out of the distribution:
3029 dist_data_DATA = distribute-this
3031 nodist_foo_SOURCES = do-not-distribute.c
3034 Another way to to use this is for removing unnecessary files that get
3035 recursively included by specifying a directory in EXTRA_DIST:
3041 rm -rf `find $(distdir)/doc -name CVS`
3044 If you define @code{SUBDIRS}, Automake will recursively include the
3045 subdirectories in the distribution. If @code{SUBDIRS} is defined
3046 conditionally (@pxref{Conditionals}), Automake will normally include all
3047 directories that could possibly appear in @code{SUBDIRS} in the
3048 distribution. If you need to specify the set of directories
3049 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
3050 list of subdirectories to include in the distribution.
3051 @vindex DIST_SUBDIRS
3055 Occasionally it is useful to be able to change the distribution before
3056 it is packaged up. If the @code{dist-hook} target exists, it is run
3057 after the distribution directory is filled, but before the actual tar
3058 (or shar) file is created. One way to use this is for distributing
3059 files in subdirectories for which a new @file{Makefile.am} is overkill:
3063 mkdir $(distdir)/random
3064 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
3067 Automake also generates a @code{distcheck} target which can be of help
3068 to ensure that a given distribution will actually work.
3069 @code{distcheck} makes a distribution, and then tries to do a
3072 @c FIXME: document distcheck-hook here
3075 @node Tests, Options, Dist, Top
3076 @chapter Support for test suites
3081 Automake supports two forms of test suites.
3083 If the variable @code{TESTS} is defined, its value is taken to be a list
3084 of programs to run in order to do the testing. The programs can either
3085 be derived objects or source objects; the generated rule will look both
3086 in @code{srcdir} and @file{.}. Programs needing data files should look
3087 for them in @code{srcdir} (which is both an environment variable and a
3088 make variable) so they work when building in a separate directory
3089 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
3090 Manual}), and in particular for the @code{distcheck} target
3093 @cindex Exit status 77, special interpretation
3095 The number of failures will be printed at the end of the run. If a
3096 given test program exits with a status of 77, then its result is ignored
3097 in the final count. This feature allows non-portable tests to be
3098 ignored in environments where they don't make sense.
3100 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
3101 variables for the test run; the environment variable @code{srcdir} is
3102 set in the rule. If all your test programs are scripts, you can also
3103 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
3104 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
3106 @vindex TESTS_ENVIRONMENT
3108 If @uref{ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz,
3109 @samp{dejagnu}} appears in @code{AUTOMAKE_OPTIONS}, then a
3110 @code{dejagnu}-based test suite is assumed. The variable
3111 @code{DEJATOOL} is a list of names which are passed, one at a time, as
3112 the @code{--tool} argument to @code{runtest} invocations; it defaults to
3113 the name of the package.
3115 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
3116 @code{--srcdir} flags that are passed to dejagnu by default; this can be
3117 overridden if necessary.
3118 @vindex RUNTESTDEFAULTFLAGS
3120 The variables @code{EXPECT}, @code{RUNTEST} and @code{RUNTESTFLAGS} can
3121 also be overridden to provide project-specific values. For instance,
3122 you will need to do this if you are testing a compiler toolchain,
3123 because the default values do not take into account host and target
3129 @vindex RUNTESTFLAGS
3130 @c FIXME xref dejagnu
3132 If you're not using dejagnu, you may define the variable
3133 @samp{XFAIL_TESTS} to a list of tests (usually a subset of @samp{TESTS})
3134 that are expected to fail. This will reverse the result of those tests.
3136 In either case, the testing is done via @samp{make check}.
3139 @node Options, Miscellaneous, Tests, Top
3140 @chapter Changing Automake's Behavior
3142 Various features of Automake can be controlled by options in the
3143 @file{Makefile.am}. Such options are listed in a special variable named
3144 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
3145 @vindex AUTOMAKE_OPTIONS
3150 @itemx @code{foreign}
3152 @cindex Option, gnits
3154 @cindex Option, foreign
3155 @cindex Option, cygnus
3157 Set the strictness as appropriate. The @code{gnits} option also implies
3158 @code{readme-alpha} and @code{check-news}.
3160 @item @code{ansi2knr}
3161 @itemx @code{path/ansi2knr}
3162 @cindex Option, ansi2knr
3163 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
3164 path, the generated @file{Makefile.in} will look in the specified
3165 directory to find the @file{ansi2knr} program. Generally the path
3166 should be a relative path to another directory in the same distribution
3167 (though Automake currently does not check this).
3169 @item @code{check-news}
3170 @cindex Option, check-news
3171 Cause @code{make dist} to fail unless the current version number appears
3172 in the first few lines of the @file{NEWS} file.
3174 @item @code{dejagnu}
3175 @cindex Option, dejagnu
3176 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
3178 @item @code{dist-bzip2}
3179 @cindex Option, dist-bzip2
3180 Generate a @code{dist-bzip2} target as well as the ordinary @code{dist}
3181 target. This new target will create a bzip2 tar archive of the
3182 distribution. bzip2 archives are frequently smaller than even gzipped
3186 @item @code{dist-shar}
3187 @cindex Option, dist-shar
3188 Generate a @code{dist-shar} target as well as the ordinary @code{dist}
3189 target. This new target will create a shar archive of the
3193 @item @code{dist-zip}
3194 @cindex Option, dist-zip
3195 Generate a @code{dist-zip} target as well as the ordinary @code{dist}
3196 target. This new target will create a zip archive of the distribution.
3199 @item @code{dist-tarZ}
3200 @cindex Option, dist-tarZ
3201 Generate a @code{dist-tarZ} target as well as the ordinary @code{dist}
3202 target. This new target will create a compressed tar archive of the
3206 @item @code{no-dependencies}
3207 @cindex Option, no-dependencies
3208 This is similar to using @samp{--include-deps} on the command line, but
3209 is useful for those situations where you don't have the necessary bits
3210 to make automatic dependency tracking work @xref{Dependencies}. In this
3211 case the effect is to effectively disable automatic dependency tracking.
3213 @item @code{no-installinfo}
3214 @cindex Option, no-installinfo
3215 The generated @file{Makefile.in} will not cause info pages to be built
3216 or installed by default. However, @code{info} and @code{install-info}
3217 targets will still be available. This option is disallowed at
3218 @samp{GNU} strictness and above.
3220 @trindex install-info
3222 @item @code{no-installman}
3223 @cindex Option, no-installman
3224 The generated @file{Makefile.in} will not cause man pages to be
3225 installed by default. However, an @code{install-man} target will still
3226 be available for optional installation. This option is disallowed at
3227 @samp{GNU} strictness and above.
3228 @trindex install-man
3230 @item @code{nostdinc}
3231 @cindex Option, nostdinc
3232 This option can be used to disable the standard @samp{-I} options which
3233 are ordinarily automatically provided by Automake.
3235 @item @code{no-texinfo.tex}
3236 @cindex Option, no-texinfo
3237 Don't require @file{texinfo.tex}, even if there are texinfo files in
3240 @item @code{readme-alpha}
3241 @cindex Option, readme-alpha
3242 If this release is an alpha release, and the file @file{README-alpha}
3243 exists, then it will be added to the distribution. If this option is
3244 given, version numbers are expected to follow one of two forms. The
3245 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
3246 element is a number; the final period and number should be left off for
3247 non-alpha releases. The second form is
3248 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
3249 letter; it should be omitted for non-alpha releases.
3252 @cindex Option, version
3253 A version number (e.g. @samp{0.30}) can be specified. If Automake is not
3254 newer than the version specified, creation of the @file{Makefile.in}
3258 Unrecognized options are diagnosed by @code{automake}.
3261 @node Miscellaneous, Include, Options, Top
3262 @chapter Miscellaneous Rules
3264 There are a few rules and variables that didn't fit anywhere else.
3267 * Tags:: Interfacing to etags and mkid
3268 * Suffixes:: Handling new file extensions
3272 @node Tags, Suffixes, Miscellaneous, Miscellaneous
3273 @section Interfacing to @code{etags}
3275 @cindex TAGS support
3277 Automake will generate rules to generate @file{TAGS} files for use with
3278 GNU Emacs under some circumstances.
3280 If any C, C++ or Fortran 77 source code or headers are present, then
3281 @code{tags} and @code{TAGS} targets will be generated for the directory.
3284 At the topmost directory of a multi-directory package, a @code{tags}
3285 target file will be generated which, when run, will generate a
3286 @file{TAGS} file that includes by reference all @file{TAGS} files from
3289 Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
3290 will be generated. This variable is intended for use in directories
3291 which contain taggable source that @code{etags} does not understand.
3294 Here is how Automake generates tags for its source, and for nodes in its
3298 ETAGS_ARGS = automake.in --lang=none \
3299 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
3302 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
3303 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
3304 are added directly to the dependencies for the @code{tags} target.
3305 @vindex TAGS_DEPENDENCIES
3307 Automake will also generate an @code{ID} target which will run
3308 @code{mkid} on the source. This is only supported on a
3309 directory-by-directory basis.
3312 Automake also supports the GNU Global Tags program. The @code{GTAGS}
3313 target runs Global Tags automatically and puts the result in the top
3317 @node Suffixes, , Tags, Miscellaneous
3318 @section Handling new file extensions
3320 @cindex Adding new SUFFIXES
3321 @cindex SUFFIXES, adding
3323 It is sometimes useful to introduce a new implicit rule to handle a file
3324 type that Automake does not know about. If this is done, you must
3325 notify GNU Make of the new suffixes. This can be done by putting a list
3326 of new suffixes in the @code{SUFFIXES} variable.
3329 For instance, currently Automake does not provide any Java support. If
3330 you wrote a macro to generate @samp{.class} files from @samp{.java}
3331 source files, you would also need to add these suffixes to the list:
3334 SUFFIXES = .java .class
3337 Any given @code{SUFFIXES} go at the start of the generated suffixes
3338 list, followed by automake generated suffixes not already in the list.
3341 @node Include, Conditionals, Miscellaneous, Top
3345 To include another file (perhaps for common rules),
3346 the following syntax is supported:
3348 include ($(srcdir)|$(top_srcdir))/filename
3350 Using files in the current directory:
3352 include $(srcdir)/Makefile.extra
3356 include Makefile.generated
3359 Using a file in the top level directory:
3361 include $(top_srcdir)/filename
3365 @node Conditionals, Gnits, Include, Top
3366 @chapter Conditionals
3368 @cindex Conditionals
3370 Automake supports a simple type of conditionals.
3372 @cvindex AM_CONDITIONAL
3373 Before using a conditional, you must define it by using
3374 @code{AM_CONDITIONAL} in the @code{configure.in} file (@pxref{Macros}).
3375 The @code{AM_CONDITIONAL} macro takes two arguments.
3377 The first argument to @code{AM_CONDITIONAL} is the name of the
3378 conditional. This should be a simple string starting with a letter and
3379 containing only letters, digits, and underscores.
3381 The second argument to @code{AM_CONDITIONAL} is a shell condition,
3382 suitable for use in a shell @code{if} statement. The condition is
3383 evaluated when @code{configure} is run.
3385 @cindex --enable-debug, example
3386 @cindex Example conditional --enable-debug
3387 @cindex Conditional example, --enable-debug
3389 Conditionals typically depend upon options which the user provides to
3390 the @code{configure} script. Here is an example of how to write a
3391 conditional which is true if the user uses the @samp{--enable-debug}
3395 AC_ARG_ENABLE(debug,
3396 [ --enable-debug Turn on debugging],
3397 [case "$@{enableval@}" in
3400 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
3401 esac],[debug=false])
3402 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
3405 Here is an example of how to use that conditional in @file{Makefile.am}:
3417 noinst_PROGRAMS = $(DBG)
3420 This trivial example could also be handled using EXTRA_PROGRAMS
3421 (@pxref{A Program}).
3423 You may only test a single variable in an @code{if} statement. The
3424 @code{else} statement may be omitted. Conditionals may be nested to any
3427 Note that conditionals in Automake are not the same as conditionals in
3428 GNU Make. Automake conditionals are checked at configure time by the
3429 @file{configure} script, and affect the translation from
3430 @file{Makefile.in} to @file{Makefile}. They are based on options passed
3431 to @file{configure} and on results that @file{configure} has discovered
3432 about the host system. GNU Make conditionals are checked at @code{make}
3433 time, and are based on variables passed to the make program or defined
3434 in the @file{Makefile}.
3436 Automake conditionals will work with any make program.
3439 @node Gnits, Cygnus, Conditionals, Top
3440 @chapter The effect of @code{--gnu} and @code{--gnits}
3442 @cindex --gnu, required files
3443 @cindex --gnu, complete description
3445 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
3446 variable) causes @code{automake} to check the following:
3450 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
3451 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
3452 directory of the package.
3455 The options @samp{no-installman} and @samp{no-installinfo} are
3459 Note that this option will be extended in the future to do even more
3460 checking; it is advisable to be familiar with the precise requirements
3461 of the GNU standards. Also, @samp{--gnu} can require certain
3462 non-standard GNU programs to exist for use by various maintainer-only
3463 targets; for instance in the future @code{pathchk} might be required for
3466 @cindex --gnits, complete description
3468 The @samp{--gnits} option does everything that @samp{--gnu} does, and
3469 checks the following as well:
3473 @samp{make dist} will check to make sure the @file{NEWS} file has been
3474 updated to the current version.
3477 @samp{VERSION} is checked to make sure its format complies with Gnits
3479 @c FIXME xref when standards are finished
3482 @cindex README-alpha
3483 If @samp{VERSION} indicates that this is an alpha release, and the file
3484 @file{README-alpha} appears in the topmost directory of a package, then
3485 it is included in the distribution. This is done in @samp{--gnits}
3486 mode, and no other, because this mode is the only one where version
3487 number formats are constrained, and hence the only mode where Automake
3488 can automatically determine whether @file{README-alpha} should be
3492 The file @file{THANKS} is required.
3496 @node Cygnus, Extending, Gnits, Top
3497 @chapter The effect of @code{--cygnus}
3499 @cindex Cygnus strictness
3501 Cygnus Solutions has slightly different rules for how a
3502 @file{Makefile.in} is to be constructed. Passing @samp{--cygnus} to
3503 @code{automake} will cause any generated @file{Makefile.in} to comply
3506 Here are the precise effects of @samp{--cygnus}:
3510 Info files are always created in the build directory, and not in the
3514 @file{texinfo.tex} is not required if a Texinfo source file is
3515 specified. The assumption is that the file will be supplied, but in a
3516 place that Automake cannot find. This assumption is an artifact of how
3517 Cygnus packages are typically bundled.
3520 @samp{make dist} will look for files in the build directory as well as
3521 the source directory. This is required to support putting info files
3522 into the build directory.
3525 Certain tools will be searched for in the build tree as well as in the
3526 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
3527 @code{makeinfo} and @code{texi2dvi}.
3530 @code{--foreign} is implied.
3533 The options @samp{no-installinfo} and @samp{no-dependencies} are
3537 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
3541 The @code{check} target doesn't depend on @code{all}.
3544 GNU maintainers are advised to use @samp{gnu} strictness in preference
3545 to the special Cygnus mode.
3548 @node Extending, Distributing, Cygnus, Top
3549 @chapter When Automake Isn't Enough
3551 Automake's implicit copying semantics means that many problems can be
3552 worked around by simply adding some @code{make} targets and rules to
3553 @file{Makefile.in}. Automake will ignore these additions.
3555 @cindex -local targets
3556 @cindex local targets
3558 There are some caveats to doing this. Although you can overload a
3559 target already used by Automake, it is often inadvisable, particularly
3560 in the topmost directory of a non-flat package. However, various useful
3561 targets have a @samp{-local} version you can specify in your
3562 @file{Makefile.in}. Automake will supplement the standard target with
3563 these user-supplied targets.
3568 @trindex check-local
3569 @trindex install-data-local
3570 @trindex install-exec-local
3571 @trindex uninstall-local
3572 @trindex mostlyclean-local
3573 @trindex clean-local
3574 @trindex distclean-local
3576 The targets that support a local version are @code{all}, @code{info},
3577 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
3578 @code{uninstall}, and the various @code{clean} targets
3579 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
3580 @code{maintainer-clean}). Note that there are no
3581 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
3582 use @code{uninstall-local}. It doesn't make sense to uninstall just
3583 data or just executables.
3588 @trindex install-data
3589 @trindex install-exec
3592 For instance, here is one way to install a file in @file{/etc}:
3596 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
3599 @cindex -hook targets
3600 @cindex hook targets
3602 Some targets also have a way to run another target, called a @dfn{hook},
3603 after their work is done. The hook is named after the principal target,
3604 with @samp{-hook} appended. The targets allowing hooks are
3605 @code{install-data}, @code{install-exec}, @code{dist}, and
3607 @trindex install-data-hook
3608 @trindex install-exec-hook
3611 For instance, here is how to create a hard link to an installed program:
3615 ln $(bindir)/program $(bindir)/proglink
3618 @c FIXME should include discussion of variables you can use in these
3622 @node Distributing, Future, Extending, Top
3623 @chapter Distributing @file{Makefile.in}s
3625 Automake places no restrictions on the distribution of the resulting
3626 @file{Makefile.in}s. We still encourage software authors to distribute
3627 their work under terms like those of the GPL, but doing so is not
3628 required to use Automake.
3630 Some of the files that can be automatically installed via the
3631 @code{--add-missing} switch do fall under the GPL; examine each file
3635 @node Future, Macro and Variable Index, Distributing, Top
3636 @chapter Some ideas for the future
3638 @cindex Future directions
3640 Here are some things that might happen in the future:
3647 The output will be cleaned up. For instance, only variables which are
3648 actually used will appear in the generated @file{Makefile.in}.
3651 There will be support for automatically recoding a distribution. The
3652 intent is to allow a maintainer to use whatever character set is most
3653 convenient locally, but for all distributions to be Unicode or
3654 @w{ISO 10646} with the UTF-8 encoding.
3656 @cindex Guile rewrite
3659 Rewrite in Guile. This won't happen in the near future, but it will
3665 @node Macro and Variable Index, General Index, Future, Top
3666 @unnumbered Macro and Variable Index
3672 @node General Index, , Macro and Variable Index, Top
3673 @unnumbered General Index