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.
810 When used with @code{--add-missing}, causes installed files to be
811 copied. The default is to make a symbolic link.
815 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
816 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
820 @itemx --force-missing
821 @opindex --force-missing
822 When used with @code{--add-missing}, causes standard files to be rebuilt
823 even if they already exist in the source tree. This involves removing
824 the file from the source tree before creating the new symlink (or, with
825 @code{--copy}, copying the new file).
829 Set the global strictness to @samp{foreign}. For more information, see
834 Set the global strictness to @samp{gnits}. For more information, see
839 Set the global strictness to @samp{gnu}. For more information, see
840 @ref{Gnits}. This is the default strictness.
844 Print a summary of the command line options and exit.
847 @itemx --include-deps
849 @opindex --include-deps
850 Include all automatically generated dependency information
851 (@pxref{Dependencies}) in the generated
852 @file{Makefile.in}. This is generally done when making a distribution;
857 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
858 @file{configure.in}. This option causes it to only update those
859 @file{Makefile.in}s which are out of date with respect to one of their
863 @itemx --output-dir=@var{dir}
865 @opindex --output-dir
866 Put the generated @file{Makefile.in} in the directory @var{dir}.
867 Ordinarily each @file{Makefile.in} is created in the directory of the
868 corresponding @file{Makefile.am}. This option is used when making
875 Cause Automake to print information about which files are being read or
880 Print the version number of Automake and exit.
884 @node configure, Top level, Invoking Automake, Top
885 @chapter Scanning @file{configure.in}
887 @cindex configure.in, scanning
888 @cindex Scanning configure.in
890 Automake scans the package's @file{configure.in} to determine certain
891 information about the package. Some @code{autoconf} macros are required
892 and some variables must be defined in @file{configure.in}. Automake
893 will also use information from @file{configure.in} to further tailor its
896 Automake also supplies some Autoconf macros to make the maintenance
897 easier. These macros can automatically be put into your
898 @file{aclocal.m4} using the @code{aclocal} program.
901 * Requirements:: Configuration requirements
902 * Optional:: Other things Automake recognizes
903 * Invoking aclocal:: Auto-generating aclocal.m4
904 * Macros:: Autoconf macros supplied with Automake
905 * Extending aclocal:: Writing your own aclocal macros
909 @node Requirements, Optional, configure, configure
910 @section Configuration requirements
912 @cindex Automake requirements
913 @cindex Requirements of Automake
915 The one real requirement of Automake is that your @file{configure.in}
916 call @code{AM_INIT_AUTOMAKE}. This macro does several things which are
917 required for proper Automake operation.
918 @cvindex AM_INIT_AUTOMAKE
920 Here are the other macros which Automake requires but which are not run
921 by @code{AM_INIT_AUTOMAKE}:
923 @cindex AC_OUTPUT, scanning
927 Automake uses this to determine which files to create (@pxref{Output, ,
928 Creating Output Files, autoconf, The Autoconf Manual}). Listed files
929 named @code{Makefile} are treated as @file{Makefile}s. Other listed
930 files are treated differently. Currently the only difference is that a
931 @file{Makefile} is removed by @code{make distclean}, while other files
932 are removed by @code{make clean}.
933 @c FIXME: this is in violation of standards!
938 @node Optional, Invoking aclocal, Requirements, configure
939 @section Other things Automake recognizes
941 @cindex Macros Automake recognizes
942 @cindex Recognized macros by Automake
944 Automake will also recognize the use of certain macros and tailor the
945 generated @file{Makefile.in} appropriately. Currently recognized macros
946 and their effects are:
949 @item AC_CONFIG_HEADER
950 Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar
951 to @code{AC_CONFIG_HEADER} (@pxref{Configuration Headers, ,
952 Configuration Header Files, autoconf, The Autoconf Manual}), but does
953 some useful Automake-specific work.
954 @cvindex AC_CONFIG_HEADER
956 @item AC_CONFIG_AUX_DIR
957 Automake will look for various helper scripts, such as
958 @file{mkinstalldirs}, in the directory named in this macro invocation.
959 If not seen, the scripts are looked for in their @samp{standard}
960 locations (either the top source directory, or in the source directory
961 corresponding to the current @file{Makefile.am}, whichever is
962 appropriate). @xref{Input, , Finding `configure' Input, autoconf, The
964 @cvindex AC_CONFIG_AUX_DIR
965 FIXME: give complete list of things looked for in this directory
968 Automake will insert definitions for the variables defined by
969 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
970 or library. @xref{System Services, , System Services, autoconf, The
972 @cvindex AC_PATH_XTRA
974 @item AC_CANONICAL_HOST
976 Automake will ensure that @file{config.guess} and @file{config.sub}
977 exist. Also, the @file{Makefile} variables @samp{host_alias} and
978 @samp{host_triplet} are introduced. See both @ref{Canonicalizing, ,
979 Getting the Canonical System Type, autoconf, The Autoconf Manual}, and
980 @ref{Generic Programs, , Generic Program Checks, autoconf, The Autoconf
982 @c fixme xref autoconf docs.
983 @cvindex AC_CANONICAL_HOST
984 @cvindex AC_CHECK_TOOL
988 @item AC_CANONICAL_SYSTEM
989 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
990 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
991 @xref{Canonicalizing, , Getting the Canonical System Type, autoconf, The
993 @cvindex AC_CANONICAL_SYSTEM
998 @itemx AC_FUNC_GETLOADAVG
999 @itemx AC_FUNC_MEMCMP
1000 @itemx AC_STRUCT_ST_BLOCKS
1001 @itemx AC_FUNC_FNMATCH
1002 @itemx AC_FUNC_MKTIME
1003 @itemx AM_FUNC_STRTOD
1004 @itemx AC_REPLACE_FUNCS
1005 @itemx AC_REPLACE_GNU_GETOPT
1006 @itemx AM_WITH_REGEX
1007 Automake will ensure that the appropriate dependencies are generated for
1008 the objects corresponding to these macros. Also, Automake will verify
1009 that the appropriate source files are part of the distribution. Note
1010 that Automake does not come with any of the C sources required to use
1011 these macros, so @code{automake -a} will not install the sources.
1012 @xref{A Library}, for more information. Also, see @ref{Particular
1013 Functions, , Particular Function Checks, autoconf, The Autoconf Manual}.
1014 @cvindex AC_FUNC_ALLOCA
1015 @cvindex AC_FUNC_GETLOADAVG
1016 @cvindex AC_FUNC_MEMCMP
1017 @cvindex AC_STRUCT_ST_BLOCKS
1018 @cvindex AC_FUNC_FNMATCH
1019 @cvindex AC_FUNC_FNMATCH
1020 @cvindex AC_REPLACE_FUNCS
1021 @cvindex AC_REPLACE_GNU_GETOPT
1022 @cvindex AM_FUNC_STRTOD
1023 @cvindex AM_WITH_REGEX
1024 @cvindex AC_FUNC_MKTIME
1027 Automake will detect statements which put @file{.o} files into
1028 @code{LIBOBJS}, and will treat these additional files as if they were
1029 discovered via @code{AC_REPLACE_FUNCS}. @xref{Generic Functions, ,
1030 Generic Function Checks, autoconf, The Autoconf Manual}.
1033 @item AC_PROG_RANLIB
1034 This is required if any libraries are built in the package.
1035 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1037 @cvindex AC_PROG_RANLIB
1040 This is required if any C++ source is included. @xref{Particular
1041 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1042 @cvindex AC_PROG_CXX
1045 This is required if any Fortran 77 source is included. This macro is
1046 distributed with Autoconf version 2.13 and later. @xref{Particular
1047 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1048 @cvindex AC_PROG_F77
1050 @item AC_F77_LIBRARY_LDFLAGS
1051 This is required for programs and shared libraries that are a mixture of
1052 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
1053 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
1054 @cvindex AC_F77_LIBRARY_LDFLAGS
1056 @item AC_PROG_LIBTOOL
1057 Automake will turn on processing for @code{libtool} (@pxref{Top, ,
1058 Introduction, libtool, The Libtool Manual}).
1059 @cvindex AC_PROG_LIBTOOL
1062 If a Yacc source file is seen, then you must either use this macro or
1063 define the variable @samp{YACC} in @file{configure.in}. The former is
1064 preferred (@pxref{Particular Programs, , Particular Program Checks,
1065 autoconf, The Autoconf Manual}).
1066 @cvindex AC_PROG_YACC
1069 @item AC_DECL_YYTEXT
1070 This macro is required if there is Lex source in the package.
1071 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1073 @cvindex AC_DECL_YYTEXT
1076 If a Lex source file is seen, then this macro must be used.
1077 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1079 @cvindex AC_PROG_LEX
1082 If Automake sees that this variable is set in @file{configure.in}, it
1083 will check the @file{po} directory to ensure that all the named
1084 @samp{.po} files exist, and that all the @samp{.po} files that exist are
1086 @cvindex ALL_LINGUAS
1088 @item AM_C_PROTOTYPES
1089 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
1090 @cvindex AM_C_PROTOTYPES
1092 @item AM_GNU_GETTEXT
1093 This macro is required for packages which use GNU gettext
1094 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1095 this macro it ensures that the package meets some of gettext's
1097 @cvindex AM_GNU_GETTEXT
1099 @item AM_MAINTAINER_MODE
1100 @opindex --enable-maintainer-mode
1101 This macro adds a @samp{--enable-maintainer-mode} option to
1102 @code{configure}. If this is used, @code{automake} will cause
1103 @samp{maintainer-only} rules to be turned off by default in the
1104 generated @file{Makefile.in}s. This macro is disallowed in @samp{Gnits}
1105 mode (@pxref{Gnits}). This macro defines the @samp{MAINTAINER_MODE}
1106 conditional, which you can use in your own @file{Makefile.am}.
1107 @cvindex AM_MAINTAINER_MODE
1110 @itemx AC_CHECK_TOOL
1111 @itemx AC_CHECK_PROG
1112 @itemx AC_CHECK_PROGS
1114 @itemx AC_PATH_PROGS
1115 For each of these macros, the first argument is automatically defined as
1116 a variable in each generated @file{Makefile.in}. @xref{Setting Output
1117 Variables, , Setting Output Variables, autoconf, The Autoconf Manual},
1118 and @ref{Generic Programs, , Generic Program Checks, autoconf, The
1121 @cvindex AC_CHECK_TOOL
1122 @cvindex AC_CHECK_PROG
1123 @cvindex AC_CHECK_PROGS
1124 @cvindex AC_PATH_PROG
1125 @cvindex AC_PATH_PROGS
1130 @node Invoking aclocal, Macros, Optional, configure
1131 @section Auto-generating aclocal.m4
1133 @cindex Invoking aclocal
1134 @cindex aclocal, Invoking
1136 Automake includes a number of Autoconf macros which can be used in your
1137 package; some of them are actually required by Automake in certain
1138 situations. These macros must be defined in your @file{aclocal.m4};
1139 otherwise they will not be seen by @code{autoconf}.
1141 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1142 files based on the contents of @file{configure.in}. This provides a
1143 convenient way to get Automake-provided macros, without having to
1144 search around. Also, the @code{aclocal} mechanism is extensible for use
1147 At startup, @code{aclocal} scans all the @file{.m4} files it can find,
1148 looking for macro definitions. Then it scans @file{configure.in}. Any
1149 mention of one of the macros found in the first step causes that macro,
1150 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1152 The contents of @file{acinclude.m4}, if it exists, are also
1153 automatically included in @file{aclocal.m4}. This is useful for
1154 incorporating local macros into @file{configure}.
1156 @code{aclocal} tries to be smart about looking for new @code{AC_DEFUN}s
1157 in the files it scans. It will warn if it finds duplicates. It also
1158 tries to copy the full text of the scanned file into @file{aclocal.m4},
1159 including both @samp{#} and @samp{dnl} comments. If you want to make a
1160 comment which will be completely ignored by @code{aclocal}, use
1161 @samp{##} as the comment leader.
1163 @code{aclocal} accepts the following options:
1166 @item --acdir=@var{dir}
1168 Look for the macro files in @var{dir} instead of the installation
1169 directory. This is typically used for debugging.
1173 Print a summary of the command line options and exit.
1177 Add the directory @var{dir} to the list of directories searched for
1180 @item --output=@var{file}
1182 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1184 @item --print-ac-dir
1185 @opindex --print-ac-dir
1186 Prints the name of the directory which @code{aclocal} will search to
1187 find the @file{.m4} files. When this option is given, normal processing
1188 is suppressed. This option can be used by a package to determine where
1189 to install a macro file.
1193 Print the names of the files it examines.
1197 Print the version number of Automake and exit.
1201 @node Macros, Extending aclocal, Invoking aclocal, configure
1202 @section Autoconf macros supplied with Automake
1204 @c consider generating this node automatically from m4 files.
1207 @item AM_CONFIG_HEADER
1208 Automake will generate rules to automatically regenerate the config
1209 header. If you do use this macro, you must create the file
1210 @file{stamp-h.in} in your source directory. It can be empty.
1211 @cvindex AM_CONFIG_HEADER
1213 @item AM_ENABLE_MULTILIB
1214 This is used when a ``multilib'' library is being built. A
1215 @dfn{multilib} library is one that is built multiple times, once per
1216 target flag combination. This is only useful when the library is
1217 intended to be cross-compiled. The first optional argument is the name
1218 of the @file{Makefile} being generated; it defaults to @samp{Makefile}.
1219 The second option argument is used to find the top source directory; it
1220 defaults to the empty string (generally this should not be used unless
1221 you are familiar with the internals).
1223 @item AM_FUNC_STRTOD
1224 If the @code{strtod} function is not available, or does not work
1225 correctly (like the one on SunOS 5.4), add @file{strtod.o} to output
1226 variable @code{LIBOBJS}.
1227 @cvindex AM_FUNC_STRTOD
1229 @item AM_FUNC_ERROR_AT_LINE
1230 If the function @code{error_at_line} is not found, then add
1231 @file{error.o} to @code{LIBOBJS}.
1232 @cvindex AM_FUNC_ERROR_AT_LINE
1234 @item AM_FUNC_OBSTACK
1235 Check for the GNU obstacks code; if not found, add @file{obstack.o} to
1237 @cvindex AM_FUNC_OBSTACK
1239 @item AM_C_PROTOTYPES
1240 Check to see if function prototypes are understood by the compiler. If
1241 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1242 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1243 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1244 values to implement automatic de-ANSI-fication.
1245 @cvindex AM_C_PROTOTYPES
1247 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1248 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1249 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1250 found in @file{<termios.h>}.
1251 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1253 @item AM_INIT_AUTOMAKE
1254 Runs many macros that most @file{configure.in}'s need. This macro has
1255 two required arguments, the package and the version number. By default
1256 this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}. This
1257 can be avoided by passing in a non-empty third argument.
1259 @item AM_PATH_LISPDIR
1260 Searches for the program @code{emacs}, and, if found, sets the output
1261 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1262 @cvindex AM_PATH_LISPDIR
1264 @item AM_PROG_CC_STDC
1265 If the C compiler in not in ANSI C mode by default, try to add an option
1266 to output variable @code{CC} to make it so. This macro tries various
1267 options that select ANSI C on some system or another. It considers the
1268 compiler to be in ANSI C mode if it handles function prototypes correctly.
1270 If you use this macro, you should check after calling it whether the C
1271 compiler has been set to accept ANSI C; if not, the shell variable
1272 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1273 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1274 @code{ansi2knr} option (@pxref{ANSI}).
1277 @cindex HP-UX 10, lex problems
1278 @cindex lex problems with HP-UX 10
1279 Like @code{AC_PROG_LEX} with @code{AC_DECL_YYTEXT} (@pxref{Particular
1280 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}),
1281 but uses the @code{missing} script on systems that do not have
1282 @code{lex}. @samp{HP-UX 10} is one such system.
1285 This macro finds the @code{gcj} program or causes an error. It sets
1286 @samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
1288 @cvindex AM_PROG_GCJ
1290 @item AM_SANITY_CHECK
1291 This checks to make sure that a file created in the build directory is
1292 newer than a file in the source directory. This can fail on systems
1293 where the clock is set incorrectly. This macro is automatically run
1294 from @code{AM_INIT_AUTOMAKE}.
1296 @item AM_SYS_POSIX_TERMIOS
1297 @cvindex am_cv_sys_posix_termios
1298 @cindex POSIX termios headers
1299 @cindex termios POSIX headers
1300 Check to see if POSIX termios headers and functions are available on the
1301 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1302 @samp{yes}. If not, set the variable to @samp{no}.
1304 @item AM_TYPE_PTRDIFF_T
1305 @cvindex HAVE_PTRDIFF_T
1307 Define @samp{HAVE_PTRDIFF_T} if the type @samp{ptrdiff_t} is defined in
1310 @item AM_WITH_DMALLOC
1311 @cvindex WITH_DMALLOC
1312 @cindex dmalloc, support for
1313 @opindex --with-dmalloc
1315 @uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
1316 package. If the user configures with @samp{--with-dmalloc}, then define
1317 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
1321 @opindex --with-regex
1322 @cindex regex package
1324 Adds @samp{--with-regex} to the @code{configure} command line. If
1325 specified (the default), then the @samp{regex} regular expression
1326 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1327 @samp{WITH_REGEX} is defined.. If @samp{--without-regex} is given, then
1328 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1329 into @samp{LIBOBJS}.
1334 @node Extending aclocal, , Macros, configure
1335 @section Writing your own aclocal macros
1337 @cindex aclocal, extending
1338 @cindex Extending aclocal
1340 The @code{aclocal} program doesn't have any built-in knowledge of any
1341 macros, so it is easy to extend it with your own macros.
1343 This is mostly used for libraries which want to supply their own
1344 Autoconf macros for use by other programs. For instance the
1345 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1346 should be used by any package using @code{gettext}. When the library is
1347 installed, it installs this macro so that @code{aclocal} will find it.
1349 A file of macros should be a series of @code{AC_DEFUN}'s. The
1350 @code{aclocal} programs also understands @code{AC_REQUIRE}, so it is
1351 safe to put each macro in a separate file. @xref{Prerequisite Macros, ,
1352 , autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
1353 autoconf, The Autoconf Manual}.
1355 A macro file's name should end in @file{.m4}. Such files should be
1356 installed in @file{$(datadir)/aclocal}.
1359 @node Top level, Rebuilding, configure, Top
1360 @chapter The top-level @file{Makefile.am}
1362 @cindex SUBDIRS, explained
1364 In non-flat packages, the top level @file{Makefile.am} must tell
1365 Automake which subdirectories are to be built. This is done via the
1366 @code{SUBDIRS} variable.
1369 The @code{SUBDIRS} macro holds a list of subdirectories in which
1370 building of various sorts can occur. Many targets (e.g. @code{all}) in
1371 the generated @file{Makefile} will run both locally and in all specified
1372 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1373 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1374 (after configuration). This allows inclusion of libraries from packages
1375 which do not use Automake (such as @code{gettext}). The directories
1376 mentioned in @code{SUBDIRS} must be direct children of the current
1377 directory. For instance, you cannot put @samp{src/subdir} into
1380 In a deep package, the top-level @file{Makefile.am} is often very short.
1381 For instance, here is the @file{Makefile.am} from the GNU Hello
1385 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1386 SUBDIRS = doc intl po src tests
1389 @cindex SUBDIRS, overriding
1390 @cindex Overriding SUBDIRS
1392 It is possible to override the @code{SUBDIRS} variable if, like in the
1393 case of GNU @code{Inetutils}, you want to only build a subset of the
1394 entire package. In your @file{Makefile.am} include:
1397 SUBDIRS = @@MY_SUBDIRS@@
1400 Then in your @file{configure.in} you can specify:
1403 MY_SUBDIRS = "src doc lib po"
1404 AC_SUBST(MY_SUBDIRS)
1407 (Note that we don't use the variable name @code{SUBDIRS} in our
1408 @file{configure.in}; that would cause Automake to believe that every
1409 @file{Makefile.in} should recurse into the listed subdirectories.)
1411 The upshot of this is that Automake is tricked into building the package
1412 to take the subdirs, but doesn't actually bind that list until
1413 @code{configure} is run.
1415 Although the @code{SUBDIRS} macro can contain configure substitutions
1416 (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
1417 contents of this variable.
1419 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1420 @code{AC_PROG_MAKE_SET}.
1422 The use of @code{SUBDIRS} is not restricted to just the top-level
1423 @file{Makefile.am}. Automake can be used to construct packages of
1426 By default, Automake generates @file{Makefiles} which work depth-first
1427 (@samp{postfix}). However, it is possible to change this ordering. You
1428 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
1429 putting @samp{.} first will cause a @samp{prefix} ordering of
1432 Sometimes, such as when running @code{make dist}, you want all possible
1433 subdirectories to be examined. In this case Automake will use
1434 @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to
1435 recurse. This variable will also be used when the user runs
1436 @code{distclean} or @code{maintainer-clean}. It should be set to the
1437 full list of subdirectories in the project. If this macro is not set,
1438 Automake will attempt to set it for you.
1441 @node Rebuilding, Programs, Top level, Top
1442 @chapter Rebuilding Makefiles
1444 Automake generates rules to automatically rebuild @file{Makefile}s,
1445 @file{configure}, and other derived files like @file{Makefile.in}.
1447 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.in}, then
1448 these automatic rebuilding rules are only enabled in maintainer mode.
1450 Sometimes you need to run @code{aclocal} with an argument like @code{-I}
1451 to tell it where to find @file{.m4} files. Since sometimes @code{make}
1452 will automatically run @code{aclocal}, you need a way to specify these
1453 arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this
1454 holds arguments which are passed verbatim to @code{aclocal}. This macro
1455 is only useful in the top-level @file{Makefile.am}.
1456 @cindex ACLOCAL_AMFLAGS
1459 @node Programs, Other objects, Rebuilding, Top
1460 @chapter Building Programs and Libraries
1462 A large part of Automake's functionality is dedicated to making it easy
1463 to build programs and libraries.
1466 * A Program:: Building a program
1467 * A Library:: Building a library
1468 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1469 * A Shared Library:: Building a Libtool library
1470 * Program variables:: Variables used when building a program
1471 * Yacc and Lex:: Yacc and Lex support
1473 * Fortran 77 Support::
1475 * Support for Other Languages::
1476 * ANSI:: Automatic de-ANSI-fication
1477 * Dependencies:: Automatic dependency tracking
1481 @node A Program, A Library, Programs, Programs
1482 @section Building a program
1484 @cindex PROGRAMS, bindir
1485 @vindex bin_PROGRAMS
1486 @vindex sbin_PROGRAMS
1487 @vindex libexec_PROGRAMS
1488 @vindex pkglib_PROGRAMS
1489 @vindex noinst_PROGRAMS
1491 In a directory containing source that gets built into a program (as
1492 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
1493 can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
1494 @code{pkglibdir}, or not at all (@samp{noinst}).
1499 bin_PROGRAMS = hello
1502 In this simple case, the resulting @file{Makefile.in} will contain code
1503 to generate a program named @code{hello}. The variable
1504 @code{hello_SOURCES} is used to specify which source files get built
1508 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1511 This causes each mentioned @samp{.c} file to be compiled into the
1512 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1514 @cindex _SOURCES primary, defined
1515 @cindex SOURCES primary, defined
1516 @cindex Primary variable, SOURCES
1518 If @samp{@var{prog}_SOURCES} is needed, but not specified, then it
1519 defaults to the single file @file{prog.c}.
1523 Multiple programs can be built in a single directory. Multiple programs
1524 can share a single source file, which must be listed in each
1525 @samp{_SOURCES} definition.
1527 @cindex Header files in _SOURCES
1528 @cindex _SOURCES and header files
1530 Header files listed in a @samp{_SOURCES} definition will be included in
1531 the distribution but otherwise ignored. In case it isn't obvious, you
1532 should not include the header file generated by @file{configure} in an
1533 @samp{_SOURCES} variable; this file should not be distributed. Lex
1534 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1537 @cindex EXTRA_prog_SOURCES, defined
1539 Automake must know all the source files that could possibly go into a
1540 program, even if not all the files are built in every circumstance.
1541 Any files which are only conditionally built should be listed in the
1542 appropriate @samp{EXTRA_} variable. For instance, if
1543 @file{hello-linux.c} were conditionally included in @code{hello}, the
1544 @file{Makefile.am} would contain:
1547 EXTRA_hello_SOURCES = hello-linux.c
1550 Similarly, sometimes it is useful to determine the programs that are to
1551 be built at configure time. For instance, GNU @code{cpio} only builds
1552 @code{mt} and @code{rmt} under special circumstances.
1554 @cindex EXTRA_PROGRAMS, defined
1556 In this case, you must notify Automake of all the programs that can
1557 possibly be built, but at the same time cause the generated
1558 @file{Makefile.in} to use the programs specified by @code{configure}.
1559 This is done by having @code{configure} substitute values into each
1560 @samp{_PROGRAMS} definition, while listing all optionally built programs
1561 in @code{EXTRA_PROGRAMS}.
1562 @vindex EXTRA_PROGRAMS
1564 If you need to link against libraries that are not found by
1565 @code{configure}, you can use @code{LDADD} to do so. This variable
1566 actually can be used to add any options to the linker command line.
1569 @cindex prog_LDADD, defined
1571 Sometimes, multiple programs are built in one directory but do not share
1572 the same link-time requirements. In this case, you can use the
1573 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1574 program as it appears in some @samp{_PROGRAMS} variable, and usually
1575 written in lowercase) to override the global @code{LDADD}. If this
1576 variable exists for a given program, then that program is not linked
1580 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
1581 linked against the library @file{libcpio.a}. However, @code{rmt} is
1582 built in the same directory, and has no such link requirement. Also,
1583 @code{mt} and @code{rmt} are only built on certain architectures. Here
1584 is what cpio's @file{src/Makefile.am} looks like (abridged):
1587 bin_PROGRAMS = cpio pax @@MT@@
1588 libexec_PROGRAMS = @@RMT@@
1589 EXTRA_PROGRAMS = mt rmt
1591 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1594 cpio_SOURCES = @dots{}
1595 pax_SOURCES = @dots{}
1596 mt_SOURCES = @dots{}
1597 rmt_SOURCES = @dots{}
1600 @cindex _LDFLAGS, defined
1602 @samp{@var{prog}_LDADD} is inappropriate for passing program-specific
1603 linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
1604 @samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
1608 @cindex _DEPENDENCIES, defined
1610 It is also occasionally useful to have a program depend on some other
1611 target which is not actually part of that program. This can be done
1612 using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
1613 on the contents of such a variable, but no further interpretation is
1616 If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
1617 Automake. The automatically-assigned value is the contents of
1618 @samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
1619 @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
1620 configure substitutions that are left in are only @samp{@@LIBOBJS@@} and
1621 @samp{@@ALLOCA@@}; these are left because it is known that they will not
1622 cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
1626 @node A Library, LIBOBJS, A Program, Programs
1627 @section Building a library
1629 @cindex _LIBRARIES primary, defined
1630 @cindex LIBRARIES primary, defined
1631 @cindex Primary variable, LIBRARIES
1633 @vindex lib_LIBRARIES
1634 @vindex pkglib_LIBRARIES
1635 @vindex noinst_LIBRARIES
1637 Building a library is much like building a program. In this case, the
1638 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
1639 @code{libdir} or @code{pkglibdir}.
1641 @xref{A Shared Library}, for information on how to build shared
1642 libraries using Libtool and the @samp{LTLIBRARIES} primary.
1644 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
1645 For instance to create a library named @file{libcpio.a}, but not install
1646 it, you would write:
1649 noinst_LIBRARIES = libcpio.a
1652 The sources that go into a library are determined exactly as they are
1653 for programs, via the @samp{_SOURCES} variables. Note that the library
1654 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
1655 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
1656 not @samp{liblob.a_SOURCES}.
1658 @cindex _LIBADD primary, defined
1659 @cindex LIBADD primary, defined
1660 @cindex Primary variable, LIBADD
1662 Extra objects can be added to a library using the
1663 @samp{@var{library}_LIBADD} variable. This should be used for objects
1664 determined by @code{configure}. Again from @code{cpio}:
1669 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
1672 In addition, sources for extra objects that will not exist until
1673 configure-time must be added to the @code{BUILT_SOURCES} variable
1677 @node LIBOBJS, A Shared Library, A Library, Programs
1678 @section Special handling for LIBOBJS and ALLOCA
1680 @cindex @@LIBOBJS@@, special handling
1681 @cindex @@ALLOCA@@, special handling
1683 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
1684 @code{@@ALLOCA@@}, and uses this information, plus the list of
1685 @code{LIBOBJS} files derived from @file{configure.in} to automatically
1686 include the appropriate source files in the distribution (@pxref{Dist}).
1687 These source files are also automatically handled in the
1688 dependency-tracking scheme; see @xref{Dependencies}.
1690 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
1691 @samp{_LDADD} or @samp{_LIBADD} variable.
1694 @node A Shared Library, Program variables, LIBOBJS, Programs
1695 @section Building a Shared Library
1697 @cindex Shared libraries, support for
1699 Building shared libraries is a relatively complex matter. For this
1700 reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
1701 Libtool Manual}) was created to help build shared libraries in a
1702 platform-independent way.
1704 @cindex _LTLIBRARIES primary, defined
1705 @cindex LTLIBRARIES primary, defined
1706 @cindex Primary variable, LTLIBRARIES
1707 @cindex Example of shared libraries
1709 @cindex suffix .la, defined
1711 Automake uses Libtool to build libraries declared with the
1712 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
1713 of shared libraries to build. For instance, to create a library named
1714 @file{libgettext.a} and its corresponding shared libraries, and install
1715 them in @samp{libdir}, write:
1718 lib_LTLIBRARIES = libgettext.la
1721 @vindex lib_LTLIBRARIES
1722 @vindex pkglib_LTLIBRARIES
1723 @vindex noinst_LTLIBRARIES
1724 @vindex check_LTLIBRARIES
1726 @cindex check_LTLIBRARIES, not allowed
1728 Note that shared libraries @emph{must} be installed, so
1729 @code{check_LTLIBRARIES} is not allowed. However,
1730 @code{noinst_LTLIBRARIES} is allowed. This feature should be used for
1731 libtool ``convenience libraries''.
1733 @cindex suffix .lo, defined
1735 For each library, the @samp{@var{library}_LIBADD} variable contains the
1736 names of extra libtool objects (@file{.lo} files) to add to the shared
1737 library. The @samp{@var{library}_LDFLAGS} variable contains any
1738 additional libtool flags, such as @samp{-version-info} or
1741 @cindex @@LTLIBOBJS@@, special handling
1743 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
1744 library must use @code{@@LTLIBOBJS@@}. This is required because the
1745 object files that libtool operates on do not necessarily end in
1746 @file{.o}. The libtool manual contains more details on this topic.
1748 For libraries installed in some directory, Automake will automatically
1749 supply the appropriate @samp{-rpath} option. However, for libraries
1750 determined at configure time (and thus mentioned in
1751 @code{EXTRA_LTLIBRARIES}), Automake does not know the eventual
1752 installation directory; for such libraries you must add the
1753 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
1756 Ordinarily, Automake requires that a shared library's name start with
1757 @samp{lib}. However, if you are building a dynamically loadable module
1758 then you might wish to use a "nonstandard" name. In this case, put
1759 @code{-module} into the @samp{_LDFLAGS} variable.
1761 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
1762 libtool, The Libtool Manual}, for more information.
1765 @node Program variables, Yacc and Lex, A Shared Library, Programs
1766 @section Variables used when building a program
1768 Occasionally it is useful to know which @file{Makefile} variables
1769 Automake uses for compilations; for instance you might need to do your
1770 own compilation in some special cases.
1772 Some variables are inherited from Autoconf; these are @code{CC},
1773 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
1777 There are some additional variables which Automake itself defines:
1781 A list of @samp{-I} options. This can be set in your @file{Makefile.am}
1782 if you have special directories you want to look in. Automake already
1783 provides some @samp{-I} options automatically. In particular it
1784 generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I} pointing to
1785 the directory holding @file{config.h} (if you've used
1786 @code{AC_CONFIG_HEADER} or @code{AM_CONFIG_HEADER}). You can disable
1787 the default @samp{-I} options using the @samp{nostdinc} option.
1789 @code{INCLUDES} can actually be used for other @code{cpp} options
1790 besides @samp{-I}. For instance, it is sometimes used to pass arbitrary
1791 @samp{-D} options to the compiler.
1794 This is the command used to actually compile a C source file. The
1795 filename is appended to form the complete command line.
1798 This is the command used to actually link a C program.
1802 @node Yacc and Lex, C++ Support, Program variables, Programs
1803 @section Yacc and Lex support
1805 Automake has somewhat idiosyncratic support for Yacc and Lex.
1807 Automake assumes that the @file{.c} file generated by @code{yacc} (or
1808 @code{lex}) should be named using the basename of the input file. That
1809 is, for a yacc source file @file{foo.y}, Automake will cause the
1810 intermediate file to be named @file{foo.c} (as opposed to
1811 @file{y.tab.c}, which is more traditional).
1813 The extension of a yacc source file is used to determine the extension
1814 of the resulting @samp{C} or @samp{C++} file. Files with the extension
1815 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
1816 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
1819 Likewise, lex source files can be used to generate @samp{C} or
1820 @samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
1821 @samp{.lxx} are recognized.
1823 You should never explicitly mention the intermediate (@samp{C} or
1824 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
1827 The intermediate files generated by @code{yacc} (or @code{lex}) will be
1828 included in any distribution that is made. That way the user doesn't
1829 need to have @code{yacc} or @code{lex}.
1831 If a @code{yacc} source file is seen, then your @file{configure.in} must
1832 define the variable @samp{YACC}. This is most easily done by invoking
1833 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
1834 Program Checks, autoconf, The Autoconf Manual}).
1836 Similarly, if a @code{lex} source file is seen, then your
1837 @file{configure.in} must define the variable @samp{LEX}. You can use
1838 @samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
1839 Program Checks, autoconf, The Autoconf Manual}). Automake's @code{lex}
1840 support also requires that you use the @samp{AC_DECL_YYTEXT}
1841 macro---automake needs to know the value of @samp{LEX_OUTPUT_ROOT}.
1842 This is all handled for you if you use the @code{AM_PROG_LEX} macro
1846 @cindex yacc, multiple parsers
1847 @cindex Multiple yacc parsers
1848 @cindex Multiple lex lexers
1849 @cindex lex, multiple lexers
1852 Automake makes it possible to include multiple @code{yacc} (or
1853 @code{lex}) source files in a single program. Automake uses a small
1854 program called @code{ylwrap} to run @code{yacc} (or @code{lex}) in a
1855 subdirectory. This is necessary because yacc's output filename is
1856 fixed, and a parallel make could conceivably invoke more than one
1857 instance of @code{yacc} simultaneously. The @code{ylwrap} program is
1858 distributed with Automake. It should appear in the directory specified
1859 by @samp{AC_CONFIG_AUX_DIR} (@pxref{Input, , Finding `configure' Input,
1860 autoconf, The Autoconf Manual}), or the current directory if that macro
1861 is not used in @file{configure.in}.
1863 For @code{yacc}, simply managing locking is insufficient. The output of
1864 @code{yacc} always uses the same symbol names internally, so it isn't
1865 possible to link two @code{yacc} parsers into the same executable.
1867 We recommend using the following renaming hack used in @code{gdb}:
1869 #define yymaxdepth c_maxdepth
1870 #define yyparse c_parse
1872 #define yyerror c_error
1873 #define yylval c_lval
1874 #define yychar c_char
1875 #define yydebug c_debug
1876 #define yypact c_pact
1883 #define yyexca c_exca
1884 #define yyerrflag c_errflag
1885 #define yynerrs c_nerrs
1889 #define yy_yys c_yys
1890 #define yystate c_state
1893 #define yy_yyv c_yyv
1895 #define yylloc c_lloc
1896 #define yyreds c_reds
1897 #define yytoks c_toks
1898 #define yylhs c_yylhs
1899 #define yylen c_yylen
1900 #define yydefred c_yydefred
1901 #define yydgoto c_yydgoto
1902 #define yysindex c_yysindex
1903 #define yyrindex c_yyrindex
1904 #define yygindex c_yygindex
1905 #define yytable c_yytable
1906 #define yycheck c_yycheck
1907 #define yyname c_yyname
1908 #define yyrule c_yyrule
1911 For each define, replace the @samp{c_} prefix with whatever you like.
1912 These defines work for @code{bison}, @code{byacc}, and traditional
1913 @code{yacc}s. If you find a parser generator that uses a symbol not
1914 covered here, please report the new name so it can be added to the list.
1917 @node C++ Support, Fortran 77 Support, Yacc and Lex, Programs
1918 @section C++ Support
1921 @cindex Support for C++
1923 Automake includes full support for C++.
1925 Any package including C++ code must define the output variable
1926 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
1927 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
1928 Program Checks, autoconf, The Autoconf Manual}).
1930 A few additional variables are defined when a C++ source file is seen:
1934 The name of the C++ compiler.
1937 Any flags to pass to the C++ compiler.
1940 The command used to actually compile a C++ source file. The file name
1941 is appended to form the complete command line.
1944 The command used to actually link a C++ program.
1948 @node Fortran 77 Support, Java Support, C++ Support, Programs
1949 @comment node-name, next, previous, up
1950 @section Fortran 77 Support
1952 @cindex Fortran 77 support
1953 @cindex Support for Fortran 77
1955 Automake includes full support for Fortran 77.
1957 Any package including Fortran 77 code must define the output variable
1958 @samp{F77} in @file{configure.in}; the simplest way to do this is to use
1959 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
1960 Program Checks, autoconf, The Autoconf Manual}). @xref{Fortran 77 and
1963 A few additional variables are defined when a Fortran 77 source file is
1969 The name of the Fortran 77 compiler.
1972 Any flags to pass to the Fortran 77 compiler.
1975 Any flags to pass to the Ratfor compiler.
1978 The command used to actually compile a Fortran 77 source file. The file
1979 name is appended to form the complete command line.
1982 The command used to actually link a pure Fortran 77 program or shared
1987 Automake can handle preprocessing Fortran 77 and Ratfor source files in
1988 addition to compiling them@footnote{Much, if not most, of the
1989 information in the following sections pertaining to preprocessing
1990 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
1991 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
1992 also contains some support for creating programs and shared libraries
1993 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
1994 Fortran 77 With C and C++}).
1996 These issues are covered in the following sections.
1999 * Preprocessing Fortran 77::
2000 * Compiling Fortran 77 Files::
2001 * Mixing Fortran 77 With C and C++::
2002 * Fortran 77 and Autoconf::
2006 @node Preprocessing Fortran 77, Compiling Fortran 77 Files, Fortran 77 Support, Fortran 77 Support
2007 @comment node-name, next, previous, up
2008 @subsection Preprocessing Fortran 77
2010 @cindex Preprocessing Fortran 77
2011 @cindex Fortran 77, Preprocessing
2012 @cindex Ratfor programs
2014 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
2015 rule runs just the preprocessor to convert a preprocessable Fortran 77
2016 or Ratfor source file into a strict Fortran 77 source file. The precise
2017 command used is as follows:
2022 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2025 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2030 @node Compiling Fortran 77 Files, Mixing Fortran 77 With C and C++, Preprocessing Fortran 77, Fortran 77 Support
2031 @comment node-name, next, previous, up
2032 @subsection Compiling Fortran 77 Files
2034 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
2035 @file{N.r} by running the Fortran 77 compiler. The precise command used
2041 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
2044 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2047 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2052 @node Mixing Fortran 77 With C and C++, Fortran 77 and Autoconf, Compiling Fortran 77 Files, Fortran 77 Support
2053 @comment node-name, next, previous, up
2054 @subsection Mixing Fortran 77 With C and C++
2056 @cindex Fortran 77, mixing with C and C++
2057 @cindex Mixing Fortran 77 with C and C++
2058 @cindex Linking Fortran 77 with C and C++
2060 @cindex Mixing Fortran 77 with C and/or C++
2062 Automake currently provides @emph{limited} support for creating programs
2063 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
2064 However, there are many other issues related to mixing Fortran 77 with
2065 other languages that are @emph{not} (currently) handled by Automake, but
2066 that are handled by other packages@footnote{For example,
2067 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
2068 addresses all of these inter-language issues, and runs under nearly all
2069 Fortran 77, C and C++ compilers on nearly all platforms. However,
2070 @code{cfortran} is not yet Free Software, but it will be in the next
2074 Automake can help in two ways:
2078 Automatic selection of the linker depending on which combinations of
2082 Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
2083 @samp{-l}) to pass to the automatically selected linker in order to link
2084 in the appropriate Fortran 77 intrinsic and run-time libraries.
2086 @cindex FLIBS, defined
2087 These extra Fortran 77 linker flags are supplied in the output variable
2088 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
2089 supplied with newer versions of Autoconf (Autoconf version 2.13 and
2090 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
2094 If Automake detects that a program or shared library (as mentioned in
2095 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
2096 code that is a mixture of Fortran 77 and C and/or C++, then it requires
2097 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
2098 @file{configure.in}, and that either @code{$(FLIBS)} or @code{@@FLIBS@@}
2099 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
2100 (for shared libraries) variables. It is the responsibility of the
2101 person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
2102 or @code{@@FLIBS@@} appears in the appropriate @code{_LDADD} or
2103 @code{_LIBADD} variable.
2105 @cindex Mixed language example
2106 @cindex Example, mixed language
2108 For example, consider the following @file{Makefile.am}:
2112 foo_SOURCES = main.cc foo.f
2113 foo_LDADD = libfoo.la @@FLIBS@@
2115 pkglib_LTLIBRARIES = libfoo.la
2116 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
2117 libfoo_la_LIBADD = $(FLIBS)
2120 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
2121 is mentioned in @file{configure.in}. Also, if @code{@@FLIBS@@} hadn't
2122 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
2123 Automake would have issued a warning.
2128 * How the Linker is Chosen::
2131 @node How the Linker is Chosen, , Mixing Fortran 77 With C and C++, Mixing Fortran 77 With C and C++
2132 @comment node-name, next, previous, up
2133 @subsubsection How the Linker is Chosen
2135 @cindex Automatic linker selection
2136 @cindex Selecting the linker automatically
2138 The following diagram demonstrates under what conditions a particular
2139 linker is chosen by Automake.
2141 For example, if Fortran 77, C and C++ source code were to be compiled
2142 into a program, then the C++ linker will be used. In this case, if the
2143 C or Fortran 77 linkers required any special libraries that weren't
2144 included by the C++ linker, then they must be manually added to an
2145 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
2151 code \ C C++ Fortran
2152 ----------------- +---------+---------+---------+
2156 +---------+---------+---------+
2160 +---------+---------+---------+
2164 +---------+---------+---------+
2168 +---------+---------+---------+
2170 C + Fortran | | | x |
2172 +---------+---------+---------+
2174 C++ + Fortran | | x | |
2176 +---------+---------+---------+
2178 C + C++ + Fortran | | x | |
2180 +---------+---------+---------+
2184 @node Fortran 77 and Autoconf, , Mixing Fortran 77 With C and C++, Fortran 77 Support
2185 @comment node-name, next, previous, up
2186 @subsection Fortran 77 and Autoconf
2188 The current Automake support for Fortran 77 requires a recent enough
2189 version Autoconf that also includes support for Fortran 77. Full
2190 Fortran 77 support was added to Autoconf 2.13, so you will want to use
2191 that version of Autoconf or later.
2194 @node Java Support, Support for Other Languages, Fortran 77 Support, Programs
2195 @comment node-name, next, previous, up
2196 @section Java Support
2198 @cindex Java support
2199 @cindex Support for Java
2201 Automake includes support for compiled Java, using @code{gcj}, the Java
2202 front end to the GNU C compiler.
2204 Any package including Java code to be compiled must define the output
2205 variable @samp{GCJ} in @file{configure.in}; the variable @samp{GCJFLAGS}
2206 must also be defined somehow (either in @file{configure.in} or
2207 @file{Makefile.am}). The simplest way to do this is to use the
2208 @code{AM_PROG_GCJ} macro.
2210 By default, programs including Java source files are linked with
2214 @node Support for Other Languages, ANSI, Java Support, Programs
2215 @comment node-name, next, previous, up
2216 @section Support for Other Languages
2218 Automake currently only includes full support for C, C++ (@pxref{C++
2219 Support}), Fortran 77 (@pxref{Fortran 77 Support}), and Java
2220 (@pxref{Java Support}). There is only rudimentary support for other
2221 languages, support for which will be improved based on user demand.
2223 @c FIXME: mention suffix rule processing here.
2226 @node ANSI, Dependencies, Support for Other Languages, Programs
2227 @section Automatic de-ANSI-fication
2229 @cindex de-ANSI-fication, defined
2231 Although the GNU standards allow the use of ANSI C, this can have the
2232 effect of limiting portability of a package to some older compilers
2235 Automake allows you to work around this problem on such machines by
2236 @dfn{de-ANSI-fying} each source file before the actual compilation takes
2239 @vindex AUTOMAKE_OPTIONS
2242 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
2243 (@pxref{Options}) contains the option @code{ansi2knr} then code to
2244 handle de-ANSI-fication is inserted into the generated
2247 This causes each C source file in the directory to be treated as ANSI C.
2248 If an ANSI C compiler is available, it is used. If no ANSI C compiler
2249 is available, the @code{ansi2knr} program is used to convert the source
2250 files into K&R C, which is then compiled.
2252 The @code{ansi2knr} program is simple-minded. It assumes the source
2253 code will be formatted in a particular way; see the @code{ansi2knr} man
2256 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
2257 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
2258 these files are distributed with Automake. Also, the package
2259 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}
2261 @cvindex AM_C_PROTOTYPES
2263 Automake also handles finding the @code{ansi2knr} support files in some
2264 other directory in the current package. This is done by prepending the
2265 relative path to the appropriate directory to the @code{ansi2knr}
2266 option. For instance, suppose the package has ANSI C code in the
2267 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
2268 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
2269 @file{src/Makefile.am}:
2272 AUTOMAKE_OPTIONS = ../lib/ansi2knr
2275 If no directory prefix is given, the files are assumed to be in the
2278 Files mentioned in @code{LIBOBJS} which need de-ANSI-fication will not
2279 be automatically handled. That's because @code{configure} will generate
2280 an object name like @file{regex.o}, while @code{make} will be looking
2281 for @file{regex_.o} (when de-ANSI-fying). Eventually this problem will
2282 be fixed via @code{autoconf} magic, but for now you must put this code
2283 into your @file{configure.in}, just before the @code{AC_OUTPUT} call:
2286 # This is necessary so that .o files in LIBOBJS are also built via
2287 # the ANSI2KNR-filtering rules.
2288 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
2292 @node Dependencies, , ANSI, Programs
2293 @section Automatic dependency tracking
2295 As a developer it is often painful to continually update the
2296 @file{Makefile.in} whenever the include-file dependencies change in a
2297 project. Automake supplies a way to automatically track dependency
2298 changes, and distribute the dependencies in the generated
2301 Currently this support requires the use of GNU @code{make} and
2302 @code{gcc}. It might become possible in the future to supply a
2303 different dependency generating program, if there is enough demand. In
2304 the meantime, this mode is enabled by default if any C program or
2305 library is defined in the current directory, so you may get a @samp{Must
2306 be a separator} error from non-GNU make.
2310 When you decide to make a distribution, the @code{dist} target will
2311 re-run @code{automake} with @samp{--include-deps} and other options.
2312 @xref{Invoking Automake}, and @ref{Options}. This will cause the
2313 previously generated dependencies to be inserted into the generated
2314 @file{Makefile.in}, and thus into the distribution. This step also
2315 turns off inclusion of the dependency generation code, so that those who
2316 download your distribution but don't use GNU @code{make} and @code{gcc}
2317 will not get errors.
2319 @vindex OMIT_DEPENDENCIES
2321 When added to the @file{Makefile.in}, the dependencies have all
2322 system-specific dependencies automatically removed. This can be done by
2323 listing the files in @samp{OMIT_DEPENDENCIES}. For instance all
2324 references to system header files are removed by Automake. Sometimes it
2325 is useful to specify that a certain header file should be removed. For
2326 instance if your @file{configure.in} uses @samp{AM_WITH_REGEX}, then any
2327 dependency on @file{rx.h} or @file{regex.h} should be removed, because
2328 the correct one cannot be known until the user configures the package.
2330 As it turns out, Automake is actually smart enough to handle the
2331 particular case of the regular expression header. It will also
2332 automatically omit @file{libintl.h} if @samp{AM_GNU_GETTEXT} is used.
2334 @vindex AUTOMAKE_OPTIONS
2335 @opindex no-dependencies
2337 Automatic dependency tracking can be suppressed by putting
2338 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}.
2340 If you unpack a distribution made by @code{make dist}, and you want to
2341 turn on the dependency-tracking code again, simply re-run
2344 The actual dependency files are put under the build directory, in a
2345 subdirectory named @file{.deps}. These dependencies are machine
2346 specific. It is safe to delete them if you like; they will be
2347 automatically recreated during the next build.
2350 @node Other objects, Other GNU Tools, Programs, Top
2351 @chapter Other Derived Objects
2353 Automake can handle derived objects which are not C programs. Sometimes
2354 the support for actually building such objects must be explicitly
2355 supplied, but Automake will still automatically handle installation and
2359 * Scripts:: Executable scripts
2360 * Headers:: Header files
2361 * Data:: Architecture-independent data files
2362 * Sources:: Derived sources
2366 @node Scripts, Headers, Other objects, Other objects
2367 @section Executable Scripts
2369 @cindex _SCRIPTS primary, defined
2370 @cindex SCRIPTS primary, defined
2371 @cindex Primary variable, SCRIPTS
2373 It is possible to define and install programs which are scripts. Such
2374 programs are listed using the @samp{SCRIPTS} primary name. Automake
2375 doesn't define any dependencies for scripts; the @file{Makefile.am}
2376 should include the appropriate rules.
2379 Automake does not assume that scripts are derived objects; such objects
2380 must be deleted by hand (@pxref{Clean}).
2382 The @code{automake} program itself is a Perl script that is generated at
2383 configure time from @file{automake.in}. Here is how this is handled:
2386 bin_SCRIPTS = automake
2389 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
2390 for it is automatically generated.
2392 @cindex SCRIPTS, installation directories
2393 @cindex Installing scripts
2396 @vindex sbin_SCRIPTS
2397 @vindex libexec_SCRIPTS
2398 @vindex pkgdata_SCRIPTS
2399 @vindex noinst_SCRIPTS
2401 Script objects can be installed in @code{bindir}, @code{sbindir},
2402 @code{libexecdir}, or @code{pkgdatadir}.
2405 @node Headers, Data, Scripts, Other objects
2406 @section Header files
2408 @cindex _HEADERS primary, defined
2409 @cindex HEADERS primary, defined
2410 @cindex Primary variable, HEADERS
2412 @vindex noinst_HEADERS
2414 Header files are specified by the @samp{HEADERS} family of variables.
2415 Generally header files are not installed, so the @code{noinst_HEADERS}
2416 variable will be the most used.
2419 All header files must be listed somewhere; missing ones will not appear
2420 in the distribution. Often it is clearest to list uninstalled headers
2421 with the rest of the sources for a program. @xref{A Program}. Headers
2422 listed in a @samp{_SOURCES} variable need not be listed in any
2423 @samp{_HEADERS} variable.
2425 @cindex HEADERS, installation directories
2426 @cindex Installing headers
2428 @vindex include_HEADERS
2429 @vindex oldinclude_HEADERS
2430 @vindex pkginclude_HEADERS
2432 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
2433 @code{pkgincludedir}.
2436 @node Data, Sources, Headers, Other objects
2437 @section Architecture-independent data files
2439 @cindex _DATA primary, defined
2440 @cindex DATA primary, defined
2441 @cindex Primary variable, DATA
2443 Automake supports the installation of miscellaneous data files using the
2444 @samp{DATA} family of variables.
2448 @vindex sysconf_DATA
2449 @vindex sharedstate_DATA
2450 @vindex localstate_DATA
2451 @vindex pkgdata_DATA
2453 Such data can be installed in the directories @code{datadir},
2454 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
2457 By default, data files are @emph{not} included in a distribution.
2459 Here is how Automake installs its auxiliary data files:
2462 pkgdata_DATA = clean-kr.am clean.am @dots{}
2466 @node Sources, , Data, Other objects
2467 @section Built sources
2469 @cindex BUILT_SOURCES, defined
2471 Occasionally a file which would otherwise be called @samp{source}
2472 (e.g. a C @samp{.h} file) is actually derived from some other file.
2473 Such files should be listed in the @code{BUILT_SOURCES} variable.
2474 @vindex BUILT_SOURCES
2476 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
2477 must be created early in the build process can be listed in this
2480 A source file listed in @code{BUILT_SOURCES} is created before the other
2481 @code{all} targets are made. However, such a source file is not
2482 compiled unless explicitly requested by mentioning it in some other
2483 @samp{_SOURCES} variable.
2486 @node Other GNU Tools, Documentation, Other objects, Top
2487 @chapter Other GNU Tools
2489 Since Automake is primarily intended to generate @file{Makefile.in}s for
2490 use in GNU programs, it tries hard to interoperate with other GNU tools.
2493 * Emacs Lisp:: Emacs Lisp
2502 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
2505 @cindex _LISP primary, defined
2506 @cindex LISP primary, defined
2507 @cindex Primary variable, LISP
2513 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
2514 is used to hold a list of @file{.el} files. Possible prefixes for this
2515 primary are @samp{lisp_} and @samp{noinst_}. Note that if
2516 @code{lisp_LISP} is defined, then @file{configure.in} must run
2517 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
2521 By default Automake will byte-compile all Emacs Lisp source files using
2522 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
2523 byte-compiling, simply define the variable @code{ELCFILES} to be empty.
2524 Byte-compiled Emacs Lisp files are not portable among all versions of
2525 Emacs, so it makes sense to turn this off if you expect sites to have
2526 more than one version of Emacs installed. Furthermore, many packages
2527 don't actually benefit from byte-compilation. Still, we recommend that
2528 you leave it enabled by default. It is probably better for sites with
2529 strange setups to cope for themselves than to make the installation less
2530 nice for everybody else.
2533 @node gettext, Guile, Emacs Lisp, Other GNU Tools
2536 @cindex GNU Gettext support
2537 @cindex Gettext support
2538 @cindex Support for GNU Gettext
2540 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
2541 turns on support for GNU gettext, a message catalog system for
2542 internationalization
2543 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
2545 The @code{gettext} support in Automake requires the addition of two
2546 subdirectories to the package, @file{intl} and @file{po}. Automake
2547 insures that these directories exist and are mentioned in
2550 Furthermore, Automake checks that the definition of @code{ALL_LINGUAS}
2551 in @file{configure.in} corresponds to all the valid @file{.po} files,
2555 @node Guile, Libtool, gettext, Other GNU Tools
2558 Automake provides some automatic support for writing Guile modules.
2559 Automake will turn on Guile support if the @code{AM_INIT_GUILE_MODULE}
2560 macro is used in @file{configure.in}.
2562 Right now Guile support just means that the @code{AM_INIT_GUILE_MODULE}
2563 macro is understood to mean:
2566 @code{AM_INIT_AUTOMAKE} is run.
2569 @code{AC_CONFIG_AUX_DIR} is run, with a path of @file{..}.
2572 As the Guile module code matures, no doubt the Automake support will
2576 @node Libtool, Java, Guile, Other GNU Tools
2579 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
2580 libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
2581 @xref{A Shared Library}.
2584 @node Java, Python, Libtool, Other GNU Tools
2587 @cindex _JAVA primary, defined
2588 @cindex JAVA primary, defined
2589 @cindex Primary variable, JAVA
2591 Automake provides some minimal support for Java compilation with the
2592 @samp{JAVA} primary.
2594 Any @file{.java} files listed in a @samp{_JAVA} variable will be
2595 compiled with @code{JAVAC} at build time. By default, @file{.class}
2596 files are not included in the distribution.
2598 @cindex JAVA restrictions
2599 @cindex Restrictions for JAVA
2601 Currently Automake enforces the restriction that only one @samp{_JAVA}
2602 primary can be used in a given @file{Makefile.am}. The reason for this
2603 restriction is that, in general, it isn't possible to know which
2604 @file{.class} files were generated from which @file{.java} files -- so
2605 it would be impossible to know which files to install where.
2607 @node Python, , Java, Other GNU Tools
2610 @cindex _PYTHON primary, defined
2611 @cindex PYTHON primary, defined
2612 @cindex Primary variable, PYTHON
2615 Automake provides support for Python modules. Automake will turn on
2616 Python support if the @code{AM_CHECK_PYTHON} macro is used in
2617 @file{configure.in}. The @samp{PYTHON} primary is used to hold a list
2618 of @file{.py} files. Possible prefixes for this primary are
2619 @samp{python_} and @samp{noinst_}. Note that if @code{python_PYTHON} is
2620 defined, then @file{configure.in} must run @code{AM_CHECK_PYTHON}.
2622 @code{AM_CHECK_PYTHON} takes a single argument --- either the word
2623 @samp{module} or @samp{package}. The first installs files directly into
2624 the @file{site-packages} directory and is used when the @file{.py[co]}
2625 files must be on the @code{PYTHONPATH}. The second is used for modules
2626 distributed as a package, which should be installed in a subdirectory
2627 of @file{site-packages} and contain the @file{__init__.py} file. The
2628 subdirectory name is the same as the name given by @samp{PACKAGE}.
2631 @code{AM_CHECK_PYTHON} creates several output variables based on the
2632 Python installation found during configuration.
2636 The name of the Python executable.
2638 @item PYTHON_VERSION
2639 The Python version number, in the form @var{major}.@var{minor}
2640 (e.g. @samp{1.5}). This is currently the value of
2641 @code{sys.version[:3]}.
2644 The string @code{$prefix}. This term may be used in future work
2645 which needs the contents of Python's @code{sys.prefix}, but general
2646 consensus is to always use the value from configure.
2648 @item PYTHON_EXEC_PREFIX
2649 The string @code{$exec_prefix}. This term may be used in future work
2650 which needs the contents of Python's @code{sys.exec_prefix}, but general
2651 consensus is to always use the value from configure.
2653 @item PYTHON_PLATFORM
2654 The canonical name used by Python to describe the operating system, as
2655 given by @code{sys.platform}. This value is sometimes needed when
2656 building Python extensions.
2659 The directory name for the top of the standard Python library.
2662 The location of the platform-independent @file{site-packages} directory,
2663 where `module' files are installed. Note that older versions of Python
2664 (pre-1.5) used @file{$prefix/lib/site-python} so future versions of
2665 Automake's Python support may provide backwards compatibility.
2667 @item PYTHON_SITE_PACKAGE
2668 The string @code{$PYTHON_SITE/$PACKAGE}. This is the default
2669 installation directory for a Python `package.'
2671 @item PYTHON_SITE_INSTALL
2672 The top-level directory in which the Python files will be installed. It
2673 will be the value of either @samp{PYTHON_SITE} or @samp{PYTHON_PACKAGE}
2674 depending on the argument given to @code{AM_CHECK_PYTHON}.
2676 @item PYTHON_SITE_EXEC
2677 The location of the platform-dependent @file{site-packages} directory,
2678 where shared library extensions should be placed. Note that older
2679 versions of Python (pre-1.5) used @file{sharedmodules} so future version
2680 of Automake's Python support may provide backwards compatibility.
2687 By default Automake will byte-compile all Python source files to both
2688 @file{.pyc} and @file{.pyo} forms. If you wish to avoid generating the
2689 optimized byte-code files, simply define the variable @code{PYOFILES} to
2690 be empty. Similarly, if you don't wish to generate the standard
2691 byte-compiled files, define the variable @code{PYCFILES} to be empty.
2694 @node Documentation, Install, Other GNU Tools, Top
2695 @chapter Building documentation
2697 Currently Automake provides support for Texinfo and man pages.
2701 * Man pages:: Man pages
2705 @node Texinfo, Man pages, Documentation, Documentation
2708 @cindex _TEXINFOS primary, defined
2709 @cindex TEXINFOS primary, defined
2710 @cindex Primary variable, TEXINFOS
2712 If the current directory contains Texinfo source, you must declare it
2713 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
2714 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
2715 here. Note that any Texinfo source file must end in the @file{.texi} or
2716 @file{.texinfo} extension.
2718 @vindex info_TEXINFOS
2720 @cindex Texinfo macro, VERSION
2721 @cindex Texinfo macro, UPDATED
2722 @cindex Texinfo macro, EDITION
2724 @cindex VERSION Texinfo macro
2725 @cindex UPDATED Texinfo macro
2726 @cindex EDITION Texinfo macro
2730 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
2731 that file will be automatically generated. The file @file{version.texi}
2732 defines three Texinfo macros you can reference: @code{EDITION},
2733 @code{VERSION}, and @code{UPDATED}. The first two hold the version
2734 number of your package (but are kept separate for clarity); the last is
2735 the date the primary file was last modified. The @file{version.texi}
2736 support requires the @code{mdate-sh} program; this program is supplied
2737 with Automake and automatically included when @code{automake} is invoked
2738 with the @code{--add-missing} option.
2740 If you have multiple Texinfo files, and you want to use the
2741 @file{version.texi} feature, then you have to have a separate version
2742 file for each Texinfo file. Automake will treat any include in a
2743 Texinfo file that matches @samp{vers*.texi} just as an automatically
2744 generated version file.
2746 Sometimes an info file actually depends on more than one @file{.texi}
2747 file. For instance, in GNU Hello, @file{hello.texi} includes the file
2748 @file{gpl.texi}. You can tell Automake about these dependencies using
2749 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
2754 info_TEXINFOS = hello.texi
2755 hello_TEXINFOS = gpl.texi
2760 By default, Automake requires the file @file{texinfo.tex} to appear in
2761 the same directory as the Texinfo source. However, if you used
2762 @code{AC_CONFIG_AUX_DIR} in @file{configure.in} (@pxref{Input, , Finding
2763 `configure' Input, autoconf, The Autoconf Manual}), then
2764 @file{texinfo.tex} is looked for there. Automake supplies
2765 @file{texinfo.tex} if @samp{--add-missing} is given.
2769 If your package has Texinfo files in many directories, you can use the
2770 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
2771 @file{texinfo.tex} for your package. The value of this variable should
2772 be the relative path from the current @file{Makefile.am} to
2776 TEXINFO_TEX = ../doc/texinfo.tex
2779 @opindex no-texinfo.tex
2781 The option @samp{no-texinfo.tex} can be used to eliminate the
2782 requirement for @file{texinfo.tex}. Use of the variable
2783 @code{TEXINFO_TEX} is preferable, however, because that allows the
2784 @code{dvi} target to still work.
2786 @cindex Target, install-info
2787 @cindex Target, noinstall-info
2788 @cindex install-info target
2789 @cindex noinstall-info target
2791 @opindex no-installinfo
2792 @trindex install-info
2794 Automake generates an @code{install-info} target; some people apparently
2795 use this. By default, info pages are installed by @samp{make install}.
2796 This can be prevented via the @code{no-installinfo} option.
2799 @node Man pages, , Texinfo, Documentation
2802 @cindex _MANS primary, defined
2803 @cindex MANS primary, defined
2804 @cindex Primary variable, MANS
2806 A package can also include man pages (but see the GNU standards on this
2807 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
2808 pages are declared using the @samp{MANS} primary. Generally the
2809 @code{man_MANS} macro is used. Man pages are automatically installed in
2810 the correct subdirectory of @code{mandir}, based on the file extension.
2814 File extensions such as @samp{.1c} are handled by looking for the valid
2815 part of the extension and using that to determine the correct
2816 subdirectory of @code{mandir}. Valid section names are the digits
2817 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
2819 Sometimes developers prefer to name a man page something like
2820 @file{foo.man} in the source, and then rename it to have the correct
2821 suffix, e.g. @file{foo.1}, when installing the file. Automake also
2822 supports this mode. For a valid section named @var{SECTION}, there is a
2823 corresponding directory named @samp{man@var{SECTION}dir}, and a
2824 corresponding @samp{_MANS} variable. Files listed in such a variable
2825 are installed in the indicated section. If the file already has a
2826 valid suffix, then it is installed as-is; otherwise the file suffix is
2827 changed to match the section.
2829 For instance, consider this example:
2831 man1_MANS = rename.man thesame.1 alsothesame.1c
2834 In this case, @file{rename.man} will be renamed to @file{rename.1} when
2835 installed, but the other files will keep their names.
2837 @cindex Target, install-man
2838 @cindex Target, noinstall-man
2839 @cindex install-man target
2840 @cindex noinstall-man target
2842 @c Use @samp{make install} per documentation: (texi)code.
2843 By default, man pages are installed by @samp{make install}. However,
2844 since the GNU project does not require man pages, many maintainers do
2845 not expend effort to keep the man pages up to date. In these cases, the
2846 @code{no-installman} option will prevent the man pages from being
2847 installed by default. The user can still explicitly install them via
2848 @samp{make install-man}.
2849 @opindex no-installman
2850 @trindex install-man
2852 Here is how the documentation is handled in GNU @code{cpio} (which
2853 includes both Texinfo documentation and man pages):
2856 info_TEXINFOS = cpio.texi
2857 man_MANS = cpio.1 mt.1
2858 EXTRA_DIST = $(man_MANS)
2861 Texinfo source and info pages are all considered to be source for the
2862 purposes of making a distribution.
2864 Man pages are not currently considered to be source, because it is not
2865 uncommon for man pages to be automatically generated. For the same
2866 reason, they are not automatically included in the distribution.
2869 @node Install, Clean, Documentation, Top
2870 @chapter What Gets Installed
2872 @cindex Installation support
2873 @cindex make install support
2875 Naturally, Automake handles the details of actually installing your
2876 program once it has been built. All @code{PROGRAMS}, @code{SCRIPTS},
2877 @code{LIBRARIES}, @code{LISP}, @code{DATA} and @code{HEADERS} are
2878 automatically installed in the appropriate places.
2880 Automake also handles installing any specified info and man pages.
2882 Automake generates separate @code{install-data} and @code{install-exec}
2883 targets, in case the installer is installing on multiple machines which
2884 share directory structure---these targets allow the machine-independent
2885 parts to be installed only once. The @code{install} target depends on
2886 both of these targets.
2887 @trindex install-data
2888 @trindex install-exec
2891 Automake also generates an @code{uninstall} target, an
2892 @code{installdirs} target, and an @code{install-strip} target.
2894 @trindex installdirs
2895 @trindex install-strip
2897 It is possible to extend this mechanism by defining an
2898 @code{install-exec-local} or @code{install-data-local} target. If these
2899 targets exist, they will be run at @samp{make install} time.
2900 @trindex install-exec-local
2901 @trindex install-data-local
2903 Variables using the standard directory prefixes @samp{data},
2904 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
2905 @samp{pkgdata}, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
2906 installed by @samp{install-data}.
2908 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
2909 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
2910 @samp{pkglib} (e.g. @samp{bin_PROGRAMS}) are installed by
2911 @samp{install-exec}.
2913 Any variable using a user-defined directory prefix with @samp{exec} in
2914 the name (e.g. @samp{myexecbin_PROGRAMS} is installed by
2915 @samp{install-exec}. All other user-defined prefixes are installed by
2916 @samp{install-data}.
2919 Automake generates support for the @samp{DESTDIR} variable in all
2920 install rules. @samp{DESTDIR} is used during the @samp{make install}
2921 step to relocate install objects into a staging area. Each object and
2922 path is prefixed with the value of @samp{DESTDIR} before being copied
2923 into the install area. Here is an example of typical DESTDIR usage:
2926 make DESTDIR=/tmp/staging install
2929 This places install objects in a directory tree built under
2930 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
2931 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
2932 would install @file{/tmp/staging/gnu/bin/foo} and
2933 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
2935 This feature is commonly used to build install images and packages. For
2936 more information, see @ref{Makefile Conventions, , , standards, The GNU
2940 @node Clean, Dist, Install, Top
2941 @chapter What Gets Cleaned
2943 @cindex make clean support
2945 The GNU Makefile Standards specify a number of different clean rules.
2947 Generally the files that can be cleaned are determined automatically by
2948 Automake. Of course, Automake also recognizes some variables that can
2949 be defined to specify additional files to clean. These variables are
2950 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
2951 @code{MAINTAINERCLEANFILES}.
2952 @vindex MOSTLYCLEANFILES
2954 @vindex DISTCLEANFILES
2955 @vindex MAINTAINERCLEANFILES
2958 @node Dist, Tests, Clean, Top
2959 @chapter What Goes in a Distribution
2962 @cindex make distcheck
2964 The @code{dist} target in the generated @file{Makefile.in} can be used
2965 to generate a gzip'd @code{tar} file for distribution. The tar file is
2966 named based on the @samp{PACKAGE} and @samp{VERSION} variables; more
2967 precisely it is named @samp{@var{package}-@var{version}.tar.gz}.
2971 You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
2972 is run. The default setting is @samp{--best}.
2974 For the most part, the files to distribute are automatically found by
2975 Automake: all source files are automatically included in a distribution,
2976 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
2977 has a built-in list of commonly used files which, if present in the
2978 current directory, are automatically included. This list is printed by
2979 @samp{automake --help}. Also, files which are read by @code{configure}
2980 (i.e. the source files corresponding to the files specified in the
2981 @code{AC_OUTPUT} invocation) are automatically distributed.
2983 Still, sometimes there are files which must be distributed, but which
2984 are not covered in the automatic rules. These files should be listed in
2985 the @code{EXTRA_DIST} variable. You can mention files from
2986 subdirectories in @code{EXTRA_DIST}. You can also mention a directory
2987 there; in this case the entire directory will be recursively copied into
2988 the distribution. Please note that this will also copy
2989 @emph{everything} in the directory, including CVS/RCS version control
2994 Sometimes you need tighter control over what does @emph{not} go into the
2995 distribution; for instance you might have source files which are
2996 generated and which you do not want to distribute. In this case
2997 Automake gives fine-grained control using the @samp{dist} and
2998 @samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
2999 prefixed with @samp{dist_} to add the listed files to the distribution.
3000 Similarly, @samp{nodist_} can be used to omit the files from the
3005 As an example, here is how you would cause some data to be distributed
3006 while leaving some source code out of the distribution:
3009 dist_data_DATA = distribute-this
3011 nodist_foo_SOURCES = do-not-distribute.c
3014 Another way to to use this is for removing unnecessary files that get
3015 recursively included by specifying a directory in EXTRA_DIST:
3021 rm -rf `find $(distdir)/doc -name CVS`
3024 If you define @code{SUBDIRS}, Automake will recursively include the
3025 subdirectories in the distribution. If @code{SUBDIRS} is defined
3026 conditionally (@pxref{Conditionals}), Automake will normally include all
3027 directories that could possibly appear in @code{SUBDIRS} in the
3028 distribution. If you need to specify the set of directories
3029 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
3030 list of subdirectories to include in the distribution.
3031 @vindex DIST_SUBDIRS
3035 Occasionally it is useful to be able to change the distribution before
3036 it is packaged up. If the @code{dist-hook} target exists, it is run
3037 after the distribution directory is filled, but before the actual tar
3038 (or shar) file is created. One way to use this is for distributing
3039 files in subdirectories for which a new @file{Makefile.am} is overkill:
3043 mkdir $(distdir)/random
3044 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
3047 Automake also generates a @code{distcheck} target which can be of help
3048 to ensure that a given distribution will actually work.
3049 @code{distcheck} makes a distribution, and then tries to do a
3052 @c FIXME: document distcheck-hook here
3055 @node Tests, Options, Dist, Top
3056 @chapter Support for test suites
3061 Automake supports two forms of test suites.
3063 If the variable @code{TESTS} is defined, its value is taken to be a list
3064 of programs to run in order to do the testing. The programs can either
3065 be derived objects or source objects; the generated rule will look both
3066 in @code{srcdir} and @file{.}. Programs needing data files should look
3067 for them in @code{srcdir} (which is both an environment variable and a
3068 make variable) so they work when building in a separate directory
3069 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
3070 Manual}), and in particular for the @code{distcheck} target
3073 @cindex Exit status 77, special interpretation
3075 The number of failures will be printed at the end of the run. If a
3076 given test program exits with a status of 77, then its result is ignored
3077 in the final count. This feature allows non-portable tests to be
3078 ignored in environments where they don't make sense.
3080 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
3081 variables for the test run; the environment variable @code{srcdir} is
3082 set in the rule. If all your test programs are scripts, you can also
3083 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
3084 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
3086 @vindex TESTS_ENVIRONMENT
3088 If @uref{ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz,
3089 @samp{dejagnu}} appears in @code{AUTOMAKE_OPTIONS}, then a
3090 @code{dejagnu}-based test suite is assumed. The variable
3091 @code{DEJATOOL} is a list of names which are passed, one at a time, as
3092 the @code{--tool} argument to @code{runtest} invocations; it defaults to
3093 the name of the package.
3095 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
3096 @code{--srcdir} flags that are passed to dejagnu by default; this can be
3097 overridden if necessary.
3098 @vindex RUNTESTDEFAULTFLAGS
3100 The variables @code{EXPECT}, @code{RUNTEST} and @code{RUNTESTFLAGS} can
3101 also be overridden to provide project-specific values. For instance,
3102 you will need to do this if you are testing a compiler toolchain,
3103 because the default values do not take into account host and target
3109 @vindex RUNTESTFLAGS
3110 @c FIXME xref dejagnu
3112 If you're not using dejagnu, you may define the variable
3113 @samp{XFAIL_TESTS} to a list of tests (usually a subset of @samp{TESTS})
3114 that are expected to fail. This will reverse the result of those tests.
3116 In either case, the testing is done via @samp{make check}.
3119 @node Options, Miscellaneous, Tests, Top
3120 @chapter Changing Automake's Behavior
3122 Various features of Automake can be controlled by options in the
3123 @file{Makefile.am}. Such options are listed in a special variable named
3124 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
3125 @vindex AUTOMAKE_OPTIONS
3130 @itemx @code{foreign}
3132 @cindex Option, gnits
3134 @cindex Option, foreign
3135 @cindex Option, cygnus
3137 Set the strictness as appropriate. The @code{gnits} option also implies
3138 @code{readme-alpha} and @code{check-news}.
3140 @item @code{ansi2knr}
3141 @itemx @code{path/ansi2knr}
3142 @cindex Option, ansi2knr
3143 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
3144 path, the generated @file{Makefile.in} will look in the specified
3145 directory to find the @file{ansi2knr} program. Generally the path
3146 should be a relative path to another directory in the same distribution
3147 (though Automake currently does not check this).
3149 @item @code{check-news}
3150 @cindex Option, check-news
3151 Cause @code{make dist} to fail unless the current version number appears
3152 in the first few lines of the @file{NEWS} file.
3154 @item @code{dejagnu}
3155 @cindex Option, dejagnu
3156 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
3158 @item @code{dist-bzip2}
3159 @cindex Option, dist-bzip2
3160 Generate a @code{dist-bzip2} target as well as the ordinary @code{dist}
3161 target. This new target will create a bzip2 tar archive of the
3162 distribution. bzip2 archives are frequently smaller than even gzipped
3166 @item @code{dist-shar}
3167 @cindex Option, dist-shar
3168 Generate a @code{dist-shar} target as well as the ordinary @code{dist}
3169 target. This new target will create a shar archive of the
3173 @item @code{dist-zip}
3174 @cindex Option, dist-zip
3175 Generate a @code{dist-zip} target as well as the ordinary @code{dist}
3176 target. This new target will create a zip archive of the distribution.
3179 @item @code{dist-tarZ}
3180 @cindex Option, dist-tarZ
3181 Generate a @code{dist-tarZ} target as well as the ordinary @code{dist}
3182 target. This new target will create a compressed tar archive of the
3186 @item @code{no-dependencies}
3187 @cindex Option, no-dependencies
3188 This is similar to using @samp{--include-deps} on the command line, but
3189 is useful for those situations where you don't have the necessary bits
3190 to make automatic dependency tracking work @xref{Dependencies}. In this
3191 case the effect is to effectively disable automatic dependency tracking.
3193 @item @code{no-installinfo}
3194 @cindex Option, no-installinfo
3195 The generated @file{Makefile.in} will not cause info pages to be built
3196 or installed by default. However, @code{info} and @code{install-info}
3197 targets will still be available. This option is disallowed at
3198 @samp{GNU} strictness and above.
3200 @trindex install-info
3202 @item @code{no-installman}
3203 @cindex Option, no-installman
3204 The generated @file{Makefile.in} will not cause man pages to be
3205 installed by default. However, an @code{install-man} target will still
3206 be available for optional installation. This option is disallowed at
3207 @samp{GNU} strictness and above.
3208 @trindex install-man
3210 @item @code{nostdinc}
3211 @cindex Option, nostdinc
3212 This option can be used to disable the standard @samp{-I} options which
3213 are ordinarily automatically provided by Automake.
3215 @item @code{no-texinfo.tex}
3216 @cindex Option, no-texinfo
3217 Don't require @file{texinfo.tex}, even if there are texinfo files in
3220 @item @code{readme-alpha}
3221 @cindex Option, readme-alpha
3222 If this release is an alpha release, and the file @file{README-alpha}
3223 exists, then it will be added to the distribution. If this option is
3224 given, version numbers are expected to follow one of two forms. The
3225 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
3226 element is a number; the final period and number should be left off for
3227 non-alpha releases. The second form is
3228 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
3229 letter; it should be omitted for non-alpha releases.
3232 @cindex Option, version
3233 A version number (e.g. @samp{0.30}) can be specified. If Automake is not
3234 newer than the version specified, creation of the @file{Makefile.in}
3238 Unrecognized options are diagnosed by @code{automake}.
3241 @node Miscellaneous, Include, Options, Top
3242 @chapter Miscellaneous Rules
3244 There are a few rules and variables that didn't fit anywhere else.
3247 * Tags:: Interfacing to etags and mkid
3248 * Suffixes:: Handling new file extensions
3252 @node Tags, Suffixes, Miscellaneous, Miscellaneous
3253 @section Interfacing to @code{etags}
3255 @cindex TAGS support
3257 Automake will generate rules to generate @file{TAGS} files for use with
3258 GNU Emacs under some circumstances.
3260 If any C, C++ or Fortran 77 source code or headers are present, then
3261 @code{tags} and @code{TAGS} targets will be generated for the directory.
3264 At the topmost directory of a multi-directory package, a @code{tags}
3265 target file will be generated which, when run, will generate a
3266 @file{TAGS} file that includes by reference all @file{TAGS} files from
3269 Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
3270 will be generated. This variable is intended for use in directories
3271 which contain taggable source that @code{etags} does not understand.
3274 Here is how Automake generates tags for its source, and for nodes in its
3278 ETAGS_ARGS = automake.in --lang=none \
3279 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
3282 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
3283 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
3284 are added directly to the dependencies for the @code{tags} target.
3285 @vindex TAGS_DEPENDENCIES
3287 Automake will also generate an @code{ID} target which will run
3288 @code{mkid} on the source. This is only supported on a
3289 directory-by-directory basis.
3292 Automake also supports the GNU Global Tags program. The @code{GTAGS}
3293 target runs Global Tags automatically and puts the result in the top
3297 @node Suffixes, , Tags, Miscellaneous
3298 @section Handling new file extensions
3300 @cindex Adding new SUFFIXES
3301 @cindex SUFFIXES, adding
3303 It is sometimes useful to introduce a new implicit rule to handle a file
3304 type that Automake does not know about. If this is done, you must
3305 notify GNU Make of the new suffixes. This can be done by putting a list
3306 of new suffixes in the @code{SUFFIXES} variable.
3309 For instance, currently Automake does not provide any Java support. If
3310 you wrote a macro to generate @samp{.class} files from @samp{.java}
3311 source files, you would also need to add these suffixes to the list:
3314 SUFFIXES = .java .class
3317 Any given @code{SUFFIXES} go at the start of the generated suffixes
3318 list, followed by automake generated suffixes not already in the list.
3321 @node Include, Conditionals, Miscellaneous, Top
3325 To include another file (perhaps for common rules),
3326 the following syntax is supported:
3328 include ($(srcdir)|$(top_srcdir))/filename
3330 Using files in the current directory:
3332 include $(srcdir)/Makefile.extra
3336 include Makefile.generated
3339 Using a file in the top level directory:
3341 include $(top_srcdir)/filename
3345 @node Conditionals, Gnits, Include, Top
3346 @chapter Conditionals
3348 @cindex Conditionals
3350 Automake supports a simple type of conditionals.
3352 @cvindex AM_CONDITIONAL
3353 Before using a conditional, you must define it by using
3354 @code{AM_CONDITIONAL} in the @code{configure.in} file (@pxref{Macros}).
3355 The @code{AM_CONDITIONAL} macro takes two arguments.
3357 The first argument to @code{AM_CONDITIONAL} is the name of the
3358 conditional. This should be a simple string starting with a letter and
3359 containing only letters, digits, and underscores.
3361 The second argument to @code{AM_CONDITIONAL} is a shell condition,
3362 suitable for use in a shell @code{if} statement. The condition is
3363 evaluated when @code{configure} is run.
3365 @cindex --enable-debug, example
3366 @cindex Example conditional --enable-debug
3367 @cindex Conditional example, --enable-debug
3369 Conditionals typically depend upon options which the user provides to
3370 the @code{configure} script. Here is an example of how to write a
3371 conditional which is true if the user uses the @samp{--enable-debug}
3375 AC_ARG_ENABLE(debug,
3376 [ --enable-debug Turn on debugging],
3377 [case "$@{enableval@}" in
3380 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
3381 esac],[debug=false])
3382 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
3385 Here is an example of how to use that conditional in @file{Makefile.am}:
3397 noinst_PROGRAMS = $(DBG)
3400 This trivial example could also be handled using EXTRA_PROGRAMS
3401 (@pxref{A Program}).
3403 You may only test a single variable in an @code{if} statement. The
3404 @code{else} statement may be omitted. Conditionals may be nested to any
3407 Note that conditionals in Automake are not the same as conditionals in
3408 GNU Make. Automake conditionals are checked at configure time by the
3409 @file{configure} script, and affect the translation from
3410 @file{Makefile.in} to @file{Makefile}. They are based on options passed
3411 to @file{configure} and on results that @file{configure} has discovered
3412 about the host system. GNU Make conditionals are checked at @code{make}
3413 time, and are based on variables passed to the make program or defined
3414 in the @file{Makefile}.
3416 Automake conditionals will work with any make program.
3419 @node Gnits, Cygnus, Conditionals, Top
3420 @chapter The effect of @code{--gnu} and @code{--gnits}
3422 @cindex --gnu, required files
3423 @cindex --gnu, complete description
3425 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
3426 variable) causes @code{automake} to check the following:
3430 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
3431 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
3432 directory of the package.
3435 The options @samp{no-installman} and @samp{no-installinfo} are
3439 Note that this option will be extended in the future to do even more
3440 checking; it is advisable to be familiar with the precise requirements
3441 of the GNU standards. Also, @samp{--gnu} can require certain
3442 non-standard GNU programs to exist for use by various maintainer-only
3443 targets; for instance in the future @code{pathchk} might be required for
3446 @cindex --gnits, complete description
3448 The @samp{--gnits} option does everything that @samp{--gnu} does, and
3449 checks the following as well:
3453 @samp{make dist} will check to make sure the @file{NEWS} file has been
3454 updated to the current version.
3457 @samp{VERSION} is checked to make sure its format complies with Gnits
3459 @c FIXME xref when standards are finished
3462 @cindex README-alpha
3463 If @samp{VERSION} indicates that this is an alpha release, and the file
3464 @file{README-alpha} appears in the topmost directory of a package, then
3465 it is included in the distribution. This is done in @samp{--gnits}
3466 mode, and no other, because this mode is the only one where version
3467 number formats are constrained, and hence the only mode where Automake
3468 can automatically determine whether @file{README-alpha} should be
3472 The file @file{THANKS} is required.
3476 @node Cygnus, Extending, Gnits, Top
3477 @chapter The effect of @code{--cygnus}
3479 @cindex Cygnus strictness
3481 Cygnus Solutions has slightly different rules for how a
3482 @file{Makefile.in} is to be constructed. Passing @samp{--cygnus} to
3483 @code{automake} will cause any generated @file{Makefile.in} to comply
3486 Here are the precise effects of @samp{--cygnus}:
3490 Info files are always created in the build directory, and not in the
3494 @file{texinfo.tex} is not required if a Texinfo source file is
3495 specified. The assumption is that the file will be supplied, but in a
3496 place that Automake cannot find. This assumption is an artifact of how
3497 Cygnus packages are typically bundled.
3500 @samp{make dist} will look for files in the build directory as well as
3501 the source directory. This is required to support putting info files
3502 into the build directory.
3505 Certain tools will be searched for in the build tree as well as in the
3506 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
3507 @code{makeinfo} and @code{texi2dvi}.
3510 @code{--foreign} is implied.
3513 The options @samp{no-installinfo} and @samp{no-dependencies} are
3517 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
3521 The @code{check} target doesn't depend on @code{all}.
3524 GNU maintainers are advised to use @samp{gnu} strictness in preference
3525 to the special Cygnus mode.
3528 @node Extending, Distributing, Cygnus, Top
3529 @chapter When Automake Isn't Enough
3531 Automake's implicit copying semantics means that many problems can be
3532 worked around by simply adding some @code{make} targets and rules to
3533 @file{Makefile.in}. Automake will ignore these additions.
3535 @cindex -local targets
3536 @cindex local targets
3538 There are some caveats to doing this. Although you can overload a
3539 target already used by Automake, it is often inadvisable, particularly
3540 in the topmost directory of a non-flat package. However, various useful
3541 targets have a @samp{-local} version you can specify in your
3542 @file{Makefile.in}. Automake will supplement the standard target with
3543 these user-supplied targets.
3548 @trindex check-local
3549 @trindex install-data-local
3550 @trindex install-exec-local
3551 @trindex uninstall-local
3552 @trindex mostlyclean-local
3553 @trindex clean-local
3554 @trindex distclean-local
3556 The targets that support a local version are @code{all}, @code{info},
3557 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
3558 @code{uninstall}, and the various @code{clean} targets
3559 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
3560 @code{maintainer-clean}). Note that there are no
3561 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
3562 use @code{uninstall-local}. It doesn't make sense to uninstall just
3563 data or just executables.
3568 @trindex install-data
3569 @trindex install-exec
3572 For instance, here is one way to install a file in @file{/etc}:
3576 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
3579 @cindex -hook targets
3580 @cindex hook targets
3582 Some targets also have a way to run another target, called a @dfn{hook},
3583 after their work is done. The hook is named after the principal target,
3584 with @samp{-hook} appended. The targets allowing hooks are
3585 @code{install-data}, @code{install-exec}, @code{dist}, and
3587 @trindex install-data-hook
3588 @trindex install-exec-hook
3591 For instance, here is how to create a hard link to an installed program:
3595 ln $(bindir)/program $(bindir)/proglink
3598 @c FIXME should include discussion of variables you can use in these
3602 @node Distributing, Future, Extending, Top
3603 @chapter Distributing @file{Makefile.in}s
3605 Automake places no restrictions on the distribution of the resulting
3606 @file{Makefile.in}s. We still encourage software authors to distribute
3607 their work under terms like those of the GPL, but doing so is not
3608 required to use Automake.
3610 Some of the files that can be automatically installed via the
3611 @code{--add-missing} switch do fall under the GPL; examine each file
3615 @node Future, Macro and Variable Index, Distributing, Top
3616 @chapter Some ideas for the future
3618 @cindex Future directions
3620 Here are some things that might happen in the future:
3627 The output will be cleaned up. For instance, only variables which are
3628 actually used will appear in the generated @file{Makefile.in}.
3631 There will be support for automatically recoding a distribution. The
3632 intent is to allow a maintainer to use whatever character set is most
3633 convenient locally, but for all distributions to be Unicode or
3634 @w{ISO 10646} with the UTF-8 encoding.
3636 @cindex Guile rewrite
3639 Rewrite in Guile. This won't happen in the near future, but it will
3645 @node Macro and Variable Index, General Index, Future, Top
3646 @unnumbered Macro and Variable Index
3652 @node General Index, , Macro and Variable Index, Top
3653 @unnumbered General Index