1 \input texinfo @c -*-texinfo-*-
3 @setfilename automake.info
10 @dircategory GNU admin
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 (C) 1995, 96 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}
53 @vskip 0pt plus 1filll
54 Copyright @copyright{} 1995, 96 Free Software Foundation, Inc.
56 This is the first edition of the GNU Automake documentation,@*
57 and is consistent with GNU Automake @value{VERSION}.@*
59 Published by the Free Software Foundation @*
60 59 Temple Place - Suite 330, @*
61 Boston, MA 02111-1307 USA @*
63 Permission is granted to make and distribute verbatim copies of
64 this manual provided the copyright notice and this permission notice
65 are preserved on all copies.
67 Permission is granted to copy and distribute modified versions of this
68 manual under the conditions for verbatim copying, provided that the entire
69 resulting derived work is distributed under the terms of a permission
70 notice identical to this one.
72 Permission is granted to copy and distribute translations of this manual
73 into another language, under the above conditions for modified versions,
74 except that this permission notice may be stated in a translation
75 approved by the Free Software Foundation.
78 @c Define an index of configure variables.
80 @c Define an index of options.
82 @c Define an index of targets.
86 @node Top, Introduction, (dir), (dir)
87 @comment node-name, next, previous, up
90 This file documents the GNU Automake package for creating GNU
91 Standards-compliant Makefiles from template files. This edition
92 documents version @value{VERSION}.
95 * Introduction:: Automake's purpose
96 * Invoking Automake:: Creating a Makefile.in
97 * Generalities:: General ideas
98 * configure:: Scanning configure.in
99 * Top level:: The top-level Makefile.am
100 * Programs:: Building programs and libraries
101 * Other objects:: Other derived objects
102 * Other GNU Tools:: Other GNU Tools
103 * Documentation:: Building documentation
104 * Install:: What gets installed
105 * Clean:: What gets cleaned
106 * Dist:: What goes in a distribution
107 * Tests:: Support for test suites
108 * Options:: Changing Automake's behavior
109 * Miscellaneous:: Miscellaneous rules
110 * Gnits:: The effect of --gnu and --gnits
111 * Extending:: Extending Automake
112 * Distributing:: Distributing the Makefile.in
113 * Examples:: Some example packages
114 * Future:: Some ideas for the future
115 * Variables:: Index of variables
116 * Configure variables:: Index of configure variables and macros
117 * Targets:: Index of targets
123 @chapter Introduction
125 Automake is a tool for automatically generating
126 @file{Makefile.in}s from files called @file{Makefile.am}. The
127 @file{Makefile.am} is basically a series of @code{make} macro
128 definitions (with rules being thrown in occasionally). The generated
129 @file{Makefile.in}s are compliant with the GNU Makefile standards.
131 The GNU Makefile Standards Document
132 (@pxref{Makefile Conventions, , , standards.info, The GNU Coding Standards})
133 is long, complicated, and subject to change. The goal of Automake is to
134 remove the burden of Makefile maintenance from the back of the
135 individual GNU maintainer (and put it on the back of the Automake
138 The typical Automake input files is simply a series of macro
139 definitions. Each such file is processed to create a
140 @file{Makefile.in}. There should generally be one @file{Makefile.am}
141 per directory of a project.
143 Automake does constrain a project in certain ways; for instance it
144 assumes that the project uses Autoconf
145 (@pxref{Top, , The Autoconf Manual, autoconf.info, The Autoconf Manual}),
146 and enforces certain restrictions on the @file{configure.in} contents.
148 @code{Automake} requires @code{perl} in order to generate the
149 @file{Makefile.in}s. However, the distributions created by Automake are
150 fully GNU standards-compliant, and do not require @code{perl} in order
153 Mail suggestions and bug reports for Automake to
154 @email{bug-gnu-utils@@prep.ai.mit.edu}.
157 @node Invoking Automake
158 @chapter Creating a @file{Makefile.in}
160 To create all the @file{Makefile.in}s for a package, run the
161 @code{automake} program in the top level directory, with no arguments.
162 @code{automake} will automatically find each appropriate
163 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
164 and generate the corresponding @file{Makefile.in}.
166 You can optionally give @code{automake} an argument; @samp{.am} is
167 appended to the argument and the result is used as the name of the input
168 file. This feature is generally only used to automatically rebuild an
169 out-of-date @file{Makefile.in}. Note that @code{automake} must always
170 be run from the topmost directory of a project, even if being used to
171 regenerate the @file{Makefile.in} in some subdirectory. This is
172 necessary because @code{automake} must scan @file{configure.in}, and
173 because @code{automake} uses the knowledge that a @file{Makefile.in} is
174 in a subdirectory to change its behavior in some cases.
176 @code{automake} accepts the following options:
181 Automake requires certain common files to exist in certain situations;
182 for instance @file{config.guess} is required if @file{configure.in} runs
183 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
184 files; this option will cause the missing ones to be automatically added
185 to the package, whenever possible. In general if Automake tells you a
186 file is missing, try using this option.
188 @item --amdir=@var{dir}
189 Look for Automake data files in directory @var{dir} instead of in the
190 installation directory. This is typically used for debugging.
192 @item --build-dir=@var{dir}
193 Tell Automake where the build directory is. This option is used when
194 including dependencies into a @file{Makefile.in} generated by @code{make
195 dist}; it should not be used otherwise.
198 An alias for @samp{--strictness=foreign}.
201 An alias for @samp{--strictness=gnits}.
204 An alias for @samp{--strictness=gnu}.
207 Print a summary of the command line options and exit.
211 Include all automatically generated dependency information
212 (@pxref{Dependencies}) in the generated
213 @file{Makefile.in}. This is generally done when making a distribution;
217 @item --output-dir=@var{dir}
218 Put the generated @file{Makefile.in} in the directory @var{dir}.
219 Ordinarily each @file{Makefile.in} is created in the directory of the
220 corresponding @file{Makefile.am}. This option is used when making
223 @item --srcdir-name=@var{dir}
224 Tell Automake the name of the source directory used in the current
225 build. This option is used when including dependencies into a
226 @file{Makefile.in} generated by @code{make dist}; it should not be used
230 @item --strictness=@var{level}
231 Set the global strictness to @var{level}; this can be overridden in each
232 @file{Makefile.am} if required. @xref{Generalities} for more
237 Cause Automake to print information about which files are being read or
241 Print the version number of Automake and exit.
246 @chapter General ideas
248 There are a few basic ideas that will help understand how Automake
252 * General Operation:: General operation of Automake
253 * Depth:: The kinds of packages
254 * Strictness:: Standards conformance checking
255 * Uniform:: The Uniform Naming Scheme
256 * Canonicalization:: How derived variables are named
259 @node General Operation
260 @section General Operation
262 Automake works by reading a @file{Makefile.am} and generating a
263 @file{Makefile.in}. Certain macros and targets defined in the
264 @file{Makefile.am} instruct automake to generate more specialized code;
265 for instances a @samp{bin_PROGRAMS} macro definition will cause targets
266 for compiling and linking to be generated.
268 The macro definitions and targets in the @file{Makefile.am} are copied
269 into the generated file. This allows you to add arbitrary code into the
270 generated @file{Makefile.in}. For instance the Automake distribution
271 includes a non-standard @code{cvs-dist} target, which the Automake
272 maintainer uses to make distributions from his source control system.
274 Note that GNU make extensions are not recognized by Automake. Using
275 such extensions in a @file{Makefile.am} will lead to errors or confusing
278 Automake tries to group comments with adjoining targets (or variable
279 definitions) in an intelligent way.
281 A target defined in @file{Makefile.am} generally overrides any such
282 target of a similar name that would be automatically generated by
283 @code{automake}. Although this is a supported feature, it is generally
284 best to avoid making use of it, as sometimes the generated rules are
287 Similarly, a variable defined in @file{Makefile.am} will override any
288 definition of the variable that @code{automake} would ordinarily create.
289 This feature is more often useful than the ability to override a target
290 definition. Be warned that many of the variables generated by
291 @code{automake} are considered to be for internal use only, and their
292 names might change in future releases.
294 When examining a variable definition, Automake will recursively examine
295 variables referenced in the definition. Eg if Automake is looking at
296 the content of @samp{foo_SOURCES} in this snippet
300 foo_SOURCES = c.c $(xs)
303 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
304 contents of @samp{foo_SOURCES}.
306 Automake also allows a form of comment which is @emph{not} copied into
307 the output; all lines beginning with @samp{##} are completely ignored by
310 It is customary to make the first line of @file{Makefile.am} read:
313 ## Process this file with automake to produce Makefile.in
316 @c FIXME discuss putting a copyright into Makefile.am here? I would but
317 @c I don't know quite what to say.
319 @c FIXME document customary ordering of Makefile.am here!
325 @code{automake} supports three kinds of directory hierarchy: ``flat'',
326 ``shallow'', and ``deep''.
328 A @dfn{flat} package is one in which all the files are in a single
329 directory. The @file{Makefile.am} for such a package by definition
330 lacks a @code{SUBDIRS} macro. An example of such a package is
334 A @dfn{deep} package is one in which all the source lies in
335 subdirectories; the top level directory contains mainly configuration
336 information. GNU cpio is a good example of such a package, as is GNU
337 @code{tar}. The top level @file{Makefile.am} for a deep package will
338 contain a @code{SUBDIRS} macro, but no other macros to define objects
341 A @dfn{shallow} package is one in which the primary source resides in
342 the top-level directory, while various parts (typically libraries)
343 reside in subdirectories. @code{automake} is one such package (as is
344 GNU @code{make}, which does not currently use @code{automake}).
349 While Automake is intended to be used by maintainers of GNU packages, it
350 does make some effort to accommodate those who wish to use it, but do
351 not want to use all the GNU conventions.
353 To this end, Automake supports three levels of @dfn{strictness} -- the
354 strictness indicating how stringently Automake should check standards
357 The valid strictness levels are:
361 Automake will check for only those things which are absolutely
362 required for proper operations. For instance, whereas GNU standards
363 dictate the existence of a @file{NEWS} file, it will not be required in
364 this mode. The name comes from the fact that Automake is intended to be
365 used for GNU programs; these relaxed rules are not the standard mode of
369 Automake will check -- as much as possible -- for compliance to the GNU
370 standards for packages. This is the default.
373 Automake will check for compliance to the as-yet-unwritten GNITS
374 standards. These are based on the GNU standards, but are even more
375 detailed. Unless you are a GNITS standards contributor, it is
376 recommended that you avoid this option until such time as the GNITS
377 standard is actually published.
380 For more information on the precise implications of the strictness
381 level, see @xref{Gnits}.
385 @section The Uniform Naming Scheme
386 Automake variables generally follow a uniform naming scheme that makes
387 it easy to decide how programs (and other derived objects) are built,
388 and how they are installed. This scheme also supports @code{configure}
389 time determination of what should be built.
391 At @code{make} time, certain variables are used to determine which
392 objects are to be built. These variables are called @dfn{primary}
393 variables. For instance, the primary variable @code{PROGRAMS} holds a
394 list of programs which are to be compiled and linked.
397 A different set of variables is used to decide where the built objects
398 should be installed. These variables are named after the primary
399 variables, but have a prefix indicating which standard directory should
400 be used as the installation directory. The standard directory names are
401 given in the GNU standards
402 (@pxref{Directory Variables, , , standards.info, The GNU Coding
404 @code{automake} extends this list with @code{pkglibdir},
405 @code{pkgincludedir}, and @code{pkgdatadir}; these are the same as the
406 non-@samp{pkg} versions, but with @samp{@@PACKAGE@@} appended.
409 For each primary, there is one additional variable named by prepending
410 @samp{EXTRA_} to the primary name. This variable is used to list
411 objects which may or may not be built, depending on what
412 @code{configure} decides. This variable is required because Automake
413 must know the entire list of objects to be built in order to generate a
414 @file{Makefile.in} that will work in all cases.
416 For instance, @code{cpio} decides at configure time which programs are
417 built. Some of the programs are installed in @code{bindir}, and some
418 are installed in @code{sbindir}:
421 EXTRA_PROGRAMS = mt rmt
422 bin_PROGRAMS = cpio pax
423 sbin_PROGRAMS = @@PROGRAMS@@
426 Defining a primary variable is an error.
428 Note that the common @samp{dir} suffix is left off when constructing the
429 variable names; thus one writes @samp{bin_PROGRAMS} and not
430 @samp{bindir_PROGRAMS}.
432 Not every sort of object can be installed in every directory. Automake
433 will flag those attempts it finds in error. Automake will also diagnose
434 obvious misspellings in directory names.
436 Sometimes the standard directories -- even as augmented by Automake --
437 are not enough. In particular it is sometimes useful, for clarity, to
438 install objects in a subdirectory of some predefined directory. To this
439 end, Automake allows you to extend the list of possible installation
440 directories. A given prefix (eg @samp{zar}) is valid if a variable of
441 the same name with @samp{dir} appended is defined (eg @samp{zardir}).
443 For instance, until HTML support is part of Automake, you could use this
444 to install raw HTML documentation:
447 htmldir = $(prefix)/html
448 html_DATA = automake.html
451 The special prefix @samp{noinst} indicates that the objects in question
452 should not be installed at all.
454 The special prefix @samp{check} indicates that the objects in question
455 should not be built until the @code{make check} command is run.
457 Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
458 @samp{LISP}, @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS},
470 @node Canonicalization
471 @section How derived variables are named
473 Sometimes a Makefile variable name is derived from some text the user
474 supplies. For instance program names are rewritten into Makefile macro
475 names. Automake canonicalizes this text, so that it does not have to
476 follow Makefile variable naming rules. All characters in the name
477 except for letters, numbers, and the underscore are turned into
478 underscores when making macro references. Eg, if your program is named
479 @code{sniff-glue}, the derived variable name would be
480 @code{sniff_glue_SOURCES}, not @code{sniff-glue_SOURCES}.
484 @chapter Scanning @file{configure.in}
486 Automake scans the package's @file{configure.in} to determine certain
487 information about the package. Some @code{autoconf} macros are required
488 and some variables must be defined in @file{configure.in}. Automake
489 will also use information from @file{configure.in} to further tailor its
493 * Requirements:: Configuration requirements
494 * Optional:: Other things Automake recognizes
495 * Invoking aclocal:: Auto-generating aclocal.m4
496 * Macros:: Autoconf macros supplied with Automake
497 * Extending aclocal:: Writing your own aclocal macros
502 @section Configuration requirements
504 The simplest way to meet the basic Automake requirements is to use the
505 macro @code{AM_INIT_AUTOMAKE} (FIXME: xref). But if you prefer, you can
506 do the required steps by hand:
507 @cvindex AM_INIT_AUTOMAKE
511 Define the variables @code{PACKAGE} and @code{VERSION} with
515 @code{PACKAGE} should be the name of the package as it appears when
516 bundled for distribution. For instance, Automake defines @code{PACKAGE}
517 to be @samp{automake}. @code{VERSION} should be the version number of
518 the release that is being developed. We recommend that you make
519 @file{configure.in} the only place in your package where the version
520 number is defined; this makes releases simpler.
522 Automake doesn't do any interpretation of @code{PACKAGE} or
523 @code{VERSION}, except in @samp{Gnits} mode (FIXME xref).
526 Use the macro @code{AC_ARG_PROGRAM} if a program or script is installed.
527 @cvindex AC_ARG_PROGRAM
530 Use @code{AC_PROG_MAKE_SET} if the package is not flat.
531 @cvindex AC_PROG_MAKE_SET
534 Use @code{AM_PROG_INSTALL} if any scripts (@pxref{Scripts}) are
535 installed by the package. Otherwise, use @code{AC_PROG_INSTALL}.
536 @cvindex AC_PROG_INSTALL
537 @cvindex AM_PROG_INSTALL
541 Here are the other macros which Automake requires but which are not run
542 by @code{AM_INIT_AUTOMAKE}:
546 Automake uses this to determine which files to create. Listed files
547 named @code{Makefile} are treated as @file{Makefile}s. Other listed
548 files are treated differently. Currently the only difference is that a
549 @file{Makefile} is removed by @code{make distclean}, while other files
550 are removed by @code{make clean}.
551 @c FIXME: this is in violation of standards!
556 @section Other things Automake recognizes
558 Automake will also recognize the use of certain macros and tailor the
559 generated @file{Makefile.in} appropriately. Currently recognized macros
560 and their effects are:
563 @item AC_CONFIG_HEADER
564 Automake will generate rules to automatically regenerate the config
565 header. If you do use this macro, you must create the file
566 @file{stamp-h.in} in your source directory. It can be empty. Also, the
567 @code{AC_OUTPUT} command in @file{configure.in} must create
571 [test -z "$CONFIG_HEADERS" || echo timestamp > stamp-h])
573 @cvindex AC_CONFIG_HEADER
574 Note that Automake does not currently currently check to make sure the
575 @code{AC_OUTPUT} command is correct. Hopefully a future version of
576 @code{autoconf} will let Automake handle this automatically.
578 @item AC_CONFIG_AUX_DIR
579 Automake will look for various helper scripts, such as
580 @file{mkinstalldirs}, in the directory named in this macro invocation.
581 If not seen, the scripts are looked for in their ``standard'' locations
582 (either the top source directory, or in the source directory
583 corresponding to the current @file{Makefile.am}, whichever is
585 @cvindex AC_CONFIG_AUX_DIR
586 FIXME: give complete list of things looked for in this directory
589 Automake will insert definitions for the variables defined by
590 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
592 @cvindex AC_PATH_XTRA
594 @item AC_CANONICAL_HOST
596 Automake will ensure that @file{config.guess} and @file{config.sub}
597 exist. Also, the @file{Makefile} variables @samp{host_alias} and
598 @samp{host_triplet} are introduced.
599 @c fixme xref autoconf docs.
600 @cvindex AC_CANONICAL_HOST
601 @cvindex AC_CHECK_TOOL
605 @item AC_CANONICAL_SYSTEM
606 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
607 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
608 @cvindex AC_CANONICAL_SYSTEM
613 @item AC_FUNC_GETLOADAVG
615 @item AC_STRUCT_ST_BLOCKS
616 @item AM_FUNC_FNMATCH
618 @item AC_REPLACE_FUNCS
619 @item AC_REPLACE_GNU_GETOPT
621 Automake will ensure that the appropriate source files are part of the
622 distribution, and will ensure that the appropriate dependencies are
623 generated for these objects. @xref{A Library} for more
625 @cvindex AC_FUNC_ALLOCA
626 @cvindex AC_FUNC_GETLOADAVG
627 @cvindex AC_FUNC_MEMCMP
628 @cvindex AC_STRUCT_ST_BLOCKS
629 @cvindex AM_FUNC_FNMATCH
630 @cvindex AC_FUNC_FNMATCH
631 @cvindex AC_REPLACE_FUNCS
632 @cvindex AC_REPLACE_GNU_GETOPT
633 @cvindex AM_FUNC_STRTOD
634 @cvindex AM_WITH_REGEX
637 Automake will detect statements which put @samp{.o} files into
638 @code{LIBOBJS}, and will treat these additional files as if they were
639 discovered via @code{AC_REPLACE_FUNCS}.
643 This is required if any libraries are built in the package.
644 @cvindex AC_PROG_RANLIB
647 This is required if any C++ source is included.
650 @item AM_PROG_LIBTOOL
651 Automake will turn on processing for @code{libtool} (@pxref{Top, , The
652 Libtool Manual, libtool.info, The Libtool Manual}).
653 @cvindex AM_PROG_LIBTOOL
656 If a Yacc source file is seen, then you must either use this macro or
657 define the variable @samp{YACC} in @file{configure.in}. The former is
659 @cvindex AC_PROG_YACC
663 This macro is required if there is Lex source in the package.
664 @cvindex AC_DECL_YYTEXT
667 If a Lex source file is seen, then this macro must be used.
671 If Automake sees that this variable is set in @file{configure.in}, it
672 will check the @file{po} directory to ensure that all the named
673 @samp{.po} files exist, and that all the @samp{.po} files that exist are
677 @item AM_C_PROTOTYPES
678 This is required when using automatic de-ANSI-fication, see @ref{ANSI}.
679 @cvindex AM_C_PROTOTYPES
682 This macro is required for packages which use GNU gettext
683 (@pxref{gettext}). It is distributed with gettext. If Automake sees
684 this macro it ensures that the package meets some of gettext's
686 @cvindex ud_GNU_GETTEXT
688 @item AM_MAINTAINER_MODE
689 This macro adds a @samp{--enable-maintainer-mode} option to
690 @code{configure}. If this is used, @code{automake} will cause
691 ``maintainer-only'' rules to be turned off by default in the generated
692 @file{Makefile.in}s. This macro is disallowed in @samp{Gnits} mode.
694 @cvindex AM_MAINTAINER_MODE
702 For each of these macros, the first argument is automatically defined as
703 a variable in each generated @file{Makefile.in}.
705 @cvindex AC_CHECK_TOOL
706 @cvindex AC_CHECK_PROG
707 @cvindex AC_CHECK_PROGS
708 @cvindex AC_PATH_PROG
709 @cvindex AC_PATH_PROGS
714 @node Invoking aclocal
715 @section Auto-generating aclocal.m4
717 The @code{aclocal} program will automatically generate @file{aclocal.m4}
718 files based on the contents of @file{configure.in}.
720 ... explain why on earth you'd want to do this
722 @code{aclocal} accepts the following options:
725 @item --acdir=@var{dir}
726 Look for the macro files in @var{dir} instead of the installation
727 directory. This is typically used for debugging.
730 Print a summary of the command line options and exit.
732 @item --output=@var{file}
733 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
736 Print the names of the files it examines.
739 Print the version number of Automake and exit.
744 @section Autoconf macros supplied with Automake
746 @c consider generating this node automatically from m4 files.
749 @item AC_FUNC_FNMATCH
750 If the @code{fnmatch} function is not available, or does not work
751 correctly (like the one on SunOS 5.4), add @samp{fnmatch.o} to output
752 variable @code{LIBOBJS}.
755 If the @code{strtod} function is not available, or does not work
756 correctly (like the one on SunOS 5.4), add @samp{strtod.o} to output
757 variable @code{LIBOBJS}.
759 @item AM_FUNC_ERROR_AT_LINE
761 @item AM_FUNC_OBSTACK
763 @item AM_C_PROTOTYPES
764 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
765 @item AM_INIT_AUTOMAKE
766 @item AM_MAINTAINER_MODE
767 @item AM_PATH_LISPDIR
768 @item AM_PROG_CC_STDC
769 @item AM_PROG_INSTALL
770 @item AM_SANITY_CHECK_CC
771 @item AM_SYS_POSIX_TERMIOS
772 @item AM_TYPE_PTRDIFF_T
773 @item AM_WITH_DMALLOC
778 @node Extending aclocal
779 @section Writing your own aclocal macros
781 ... explain format of macro files
782 ... explain how to get your own macros installed (using acinstall)
783 ... explain situations where this is actually useful (eg gettext)
787 @chapter The top-level @file{Makefile.am}
789 In non-flat packages, the top level @file{Makefile.am} must tell
790 Automake which subdirectories are to be built. This is done via the
791 @code{SUBDIRS} variable.
794 The @code{SUBDIRS} macro holds a list of subdirectories in which
795 building of various sorts can occur. Many targets (eg @code{all}) in
796 the generated @file{Makefile} will run both locally and in all specified
797 subdirectories. Note that the directories listed in @code{SUBDIRS} are
798 not required to contain @file{Makefile.am}s; only @file{Makefile}s
799 (after configuration). This allows inclusion of libraries from packages
800 which do not use Automake (such as @code{gettext}).
802 In a deep package, the top-level @file{Makefile.am} is often very short.
803 For instance, here is the @file{Makefile.am} from the textutils
807 SUBDIRS = lib src doc man
810 @code{SUBDIRS} can contain configure substitutions (eg @samp{@@DIRS@@});
811 Automake itself does not actually examine the contents of this variable.
813 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
814 @code{AC_PROG_MAKE_SET}.
816 The use of @code{SUBDIRS} is not restricted to just the top-level
817 @file{Makefile.am}. Automake can be used to construct packages of
822 @chapter Building Programs and Libraries
824 A large part of Automake's functionality is dedicated to making it easy
825 to build C programs and libraries.
828 * A Program:: Building a program
829 * A Library:: Building a library
830 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
831 * Program variables:: Variables used when building a program
832 * Yacc and Lex:: Yacc and Lex support
833 * C++:: C++ and other languages
834 * ANSI:: Automatic de-ANSI-fication
835 * Dependencies:: Automatic dependency tracking
840 @section Building a program
842 In a directory containing source that gets built into a program (as
843 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
844 can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
845 @code{pkglibdir}, or not at all.
853 In this simple case, the resulting @file{Makefile.in} will contain code
854 to generate a program named @code{hello}. The variable
855 @code{hello_SOURCES} is used to specify which source files get built
859 hello_SOURCES = hello.c
862 This causes @file{hello.c} to be compiled into @file{hello.o}, and then
863 linked to produce @file{hello}.
865 If @samp{prog_SOURCES} is needed, but not specified, then it defaults to
866 the single file @file{prog.c}. In the example above, the definition of
867 @code{hello_SOURCES} is actually redundant.
871 Multiple programs can be built in a single directory. Multiple programs
872 can share a single source file. The source file must be listed in each
873 @samp{_SOURCES} definition.
875 Header files listed in a @samp{_SOURCES} definition will be included in
876 the distribution but otherwise ignored. In case it isn't obvious, you
877 should not include the header file generated by @file{configure} in an
878 @samp{_SOURCES} variable; this file should not be distributed. Lex
879 (@samp{.l}) and yacc (@samp{.y}) files can also be listed; see @ref{Yacc
882 Sometimes it is useful to determine the programs that are to be built at
883 configure time. For instance, GNU @code{cpio} only builds @code{mt} and
884 @code{rmt} under special circumstances.
886 In this case, you must notify @code{Automake} of all the programs that
887 can possibly be built, but at the same time cause the generated
888 @file{Makefile.in} to use the programs specified by @code{configure}.
889 This is done by having @code{configure} substitute values into each
890 @samp{_PROGRAMS} definition, while listing all optionally built programs in
891 @code{EXTRA_PROGRAMS}.
892 @vindex EXTRA_PROGRAMS
894 If you need to link against libraries that are not found by
895 @code{configure}, you can use @code{LDADD} to do so. This variable
896 actually can be used to add any options to the linker command line.
899 Sometimes, multiple programs are built in one directory but do not share
900 the same link-time requirements. In this case, you can use the
901 @samp{@var{prog}_LDADD} variable (where @var{PROG} is the name of the
902 program as it appears in some @samp{_PROGRAMS} variable, and usually
903 written in lowercase) to override the global @code{LDADD}. (If this
904 variable exists for a given program, then that program is not linked
908 For instance, in GNU cpio, @code{pax}, @code{cpio}, and @code{mt} are
909 linked against the library @file{libcpio.a}. However, @code{rmt} is
910 built in the same directory, and has no such link requirement. Also,
911 @code{mt} and @code{rmt} are only built on certain architectures. Here
912 is what cpio's @file{src/Makefile.am} looks like (abridged):
915 bin_PROGRAMS = cpio pax @@MT@@
916 libexec_PROGRAMS = @@RMT@@
917 EXTRA_PROGRAMS = mt rmt
919 LDADD = ../lib/libcpio.a @@INTLLIBS@@
922 cpio_SOURCES = @dots{}
923 pax_SOURCES = @dots{}
925 rmt_SOURCES = @dots{}
928 @samp{prog_LDADD} is inappropriate for passing program-specific linker
929 flags (except for @samp{-l} and @samp{-L}). So, use the
930 @samp{prog_LDFLAGS} variable for this purpose.
933 It is also occasionally useful to have a program depend on some other
934 target which is not actually part of that program. This can be done
935 using the @samp{prog_DEPENDENCIES} variable. Each program depends on
936 the contents of such a variable, but no further interpretation is done.
938 If @samp{prog_DEPENDENCIES} is not supplied, it is computed by Automake.
939 The automatically-assigned value is the contents of @samp{prog_LDADD}.
940 Be warned that @file{configure} substitutions are preserved; this can
941 lead to bad dependencies if you are not careful.
945 @section Building a library
947 Building a library is much like building a program. In this case, the
948 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
949 @code{libdir} or @code{pkglibdir}.
951 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
952 For instance to create a library named @file{libcpio.a}, but not install
956 noinst_LIBRARIES = libcpio.a
959 The sources that go into a library are determined exactly as they are
960 for programs, via the @samp{_SOURCES} variables. Note that the library
961 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
962 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
963 not @samp{liblob.a_SOURCES}.
965 Extra objects can be added to a library using the @samp{library_LIBADD}
966 variable. This should be used for objects determined by
967 @code{configure}. Again from cpio:
972 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
975 @unnumberedsubsec Building Libraries with @code{libtool}
977 The innovation used by GNU Libtool (@pxref{Top, , The Libtool Manual,
978 libtool.info, The Libtool Manual}) is that libraries are programs.
980 So, if you have GNU Libtool and want to use it to build your libraries,
981 you should use the @samp{lib_PROGRAMS} variable (@pxref{Using Automake,
982 , Using Automake with Libtool, libtool.info, The Libtool Manual}).
985 @section Special handling for LIBOBJS and ALLOCA
987 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
988 @code{@@ALLOCA@@}, and uses this information, plus the list of
989 @code{LIBOBJS} files derived from @file{configure.in} to automatically
990 include the appropriate source files in the distribution (@pxref{Dist}).
991 These source files are also automatically handled in the
992 dependency-tracking scheme, see @xref{Dependencies}.
994 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
995 @samp{_LDADD} or @samp{_LIBADD} variable.
998 @node Program variables
999 @section Variables used when building a program
1001 Occasionally it is useful to know which @file{Makefile} variables
1002 Automake uses for compilations; for instance you might need to do your
1003 own compilation in some special cases.
1005 Some variables are inherited from Autoconf; these are @code{CC},
1006 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
1010 There are some additional variables which Automake itself defines:
1014 A list of @samp{-I} options. This can be set in your @file{Makefile.am}
1015 if you have special directories you want to look in.
1018 This is the command used to actually compile a C source file. The
1019 filename is appended to form the complete command line.
1022 This is the command used to actually link a C program.
1027 @section Yacc and Lex support
1029 Automake has somewhat idiosyncratic support for Yacc and Lex.
1031 Automake assumes that the @samp{.c} file generated by yacc (or lex)
1032 should be named using the basename of the input file. That is, for a
1033 yacc source file @file{foo.y}, automake will cause the intermediate file
1034 to be named @file{foo.c} (as opposed to @file{y.tab.c}, which is more
1037 Yacc source files must end with the extension @samp{.y}. Lex source
1038 files must have the extension @samp{.l}. You should never explicitly
1039 mention the intermediate @samp{.c} file in any @samp{SOURCES} variable;
1040 only list the source file.
1042 The intermediate files generated by yacc (or lex) will be included in
1043 any distribution that is made. That way the user doesn't need to have
1046 If a yacc source file is seen, then your @file{configure.in} must define
1047 the variable @samp{YACC}. This is most easily done by invoking the
1048 macro @samp{AC_PROG_YACC}.
1050 Similarly, if a lex source file is seen, then your @file{configure.in}
1051 must define the variable @samp{LEX}. You can use @samp{AC_PROG_LEX} to
1052 do this. Automake's lex support also requires that you use the
1053 @samp{AC_DECL_YYTEXT} macro -- automake needs to know the value of
1054 @samp{LEX_OUTPUT_ROOT}.
1056 Any program including a lex source file must be linked against
1057 @samp{@@LEXLIB@@}. You can do this by putting @samp{@@LEXLIB@@} into
1058 the appropriate @samp{LDADD} variable.
1060 Automake makes it possible to include multiple yacc (or lex) source
1061 files in a single program. Automake uses a small program called
1062 @code{interlock} to manage locks between multiple yacc invocations.
1063 This is necessary because yacc's output filename is fixed, and a
1064 parallel make could conceivably invoke more than one instance of
1065 @code{yacc} simultaneously. @code{interlock} is distributed with
1066 automake. It should appear in the directory specified by
1067 @samp{AC_CONFIG_AUX_DIR}, or the current directory if that macro is not
1068 used in @file{configure.in}.
1070 For @code{yacc}, simply managing locking is insufficient. @code{yacc}
1071 output also always uses the same symbol names internally, so it isn't
1072 possible to link two @code{yacc} parsers into the same executable.
1074 We recommend using the following renaming hack used in @code{gdb}:
1076 #define yymaxdepth c_maxdepth
1077 #define yyparse c_parse
1079 #define yyerror c_error
1080 #define yylval c_lval
1081 #define yychar c_char
1082 #define yydebug c_debug
1083 #define yypact c_pact
1090 #define yyexca c_exca
1091 #define yyerrflag c_errflag
1092 #define yynerrs c_nerrs
1096 #define yy_yys c_yys
1097 #define yystate c_state
1100 #define yy_yyv c_yyv
1102 #define yylloc c_lloc
1103 #define yyreds c_reds
1104 #define yytoks c_toks
1105 #define yylhs c_yylhs
1106 #define yylen c_yylen
1107 #define yydefred c_yydefred
1108 #define yydgoto c_yydgoto
1109 #define yysindex c_yysindex
1110 #define yyrindex c_yyrindex
1111 #define yygindex c_yygindex
1112 #define yytable c_yytable
1113 #define yycheck c_yycheck
1116 For each define, replace the @samp{c_} prefix with whatever you like.
1117 These defines work for @code{bison}, @code{byacc}, and traditional
1118 @code{yacc}s. If you find a parser generator that uses a symbol not
1119 covered here, please report the new name so it can be added to the list.
1123 @section C++ and other languages
1125 Automake includes full support for C++, and rudimentary support for
1126 other languages. Support for other languages will be improved based on
1129 Any package including C++ code must define the output variable
1130 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
1131 the @code{AC_PROG_CXX} macro.
1133 A few additional variables are defined when a C++ source file is seen:
1137 The name of the C++ compiler.
1141 Any flags to pass to the C++ compiler.
1145 The command used to actually compile a C++ source file. The file name
1146 is appended to form the complete command line.
1150 The command used to actually link a C++ program.
1156 @section Automatic de-ANSI-fication
1158 Although the GNU standards prohibit it, some GNU programs are written in
1159 ANSI C. This is possible because each source file can be
1160 ``de-ANSI-fied'' before the actual compilation takes place.
1161 @c NOTE that the standards no longer prohibit this!
1162 @c What does that imply for this feature?
1164 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
1165 @vindex AUTOMAKE_OPTIONS
1166 (@ref{Options}) contains the option @code{ansi2knr}
1168 then code to handle de-ANSI-fication is inserted into the generated
1171 This causes each C source file in the directory to be treated as ANSI C.
1172 If an ANSI C compiler is available, it is used. If no ANSI C compiler
1173 is available, the @code{ansi2knr} program is used to convert the source
1174 files into K&R C, which is then compiled.
1176 The @code{ansi2knr} program is simple-minded. It assumes the source
1177 code will be formatted in a particular way; see the @code{ansi2knr} man
1178 page for details. Running @code{ansi2knr} on K&R C source will result
1179 in compilation errors.
1181 De-ANSI-fication support requires the source files @file{ansi2knr.c} and
1182 @file{ansi2knr.1} to be in the same package as the ANSI C source; these
1183 files are distributed with Automake. Also, the package
1184 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}.
1185 @cvindex AM_C_PROTOTYPES
1187 Automake also handles finding the @code{ansi2knr} support files in some
1188 other directory in the current package. This is done by prepending the
1189 relative path to the appropriate directory to the @code{ansi2knr}
1190 option. For instance, suppose the package has ANSI C code in the
1191 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
1192 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
1193 @file{src/Makefile.am}:
1196 AUTOMAKE_OPTIONS = ../lib/ansi2knr
1199 If no directory prefix is given, the files are assumed to be in the
1202 Note that the directory holding the @code{ansi2knr} support files must
1203 be built before all other directories using these files. Automake does
1204 not currently check that this is the case.
1208 @section Automatic dependency tracking
1210 As a developer it is often painful to continually update the
1211 @file{Makefile.in} whenever the include-file dependencies change in a
1212 project. @code{automake} supplies a way to automatically track
1213 dependency changes, and distribute the dependencies in the generated
1216 Currently this support requires the use of GNU @code{make} and
1217 @code{gcc}. It might become possible in the future to supply a
1218 different dependency generating program, if there is enough demand.
1220 This mode is enabled by default if any C program or library is defined
1221 in the current directory.
1223 When you decide to make a distribution, the @code{dist} target will
1225 re-run @code{automake} with the @samp{--include-deps} option. This
1227 causes the previously generated dependencies to be inserted into the
1228 generated @file{Makefile.in}, and thus into the distribution.
1229 @samp{--include-deps} also turns off inclusion of the dependency
1232 This mode can be suppressed by putting @code{no-dependencies} in the
1233 variable @code{AUTOMAKE_OPTIONS}.
1234 @vindex AUTOMAKE_OPTIONS
1235 @opindex no-dependencies
1237 If you unpack a distribution made by @code{make dist}, and you want to
1238 turn on the dependency-tracking code again, simply run @code{automake}
1243 @chapter Other Derived Objects
1245 Automake can handle derived objects which are not C programs. Sometimes
1246 the support for actually building such objects must be explicitly
1247 supplied, but Automake will still automatically handle installation and
1251 * Scripts:: Executable scripts
1252 * Headers:: Header files
1253 * Data:: Architecture-independent data files
1254 * Sources:: Derived sources
1259 @section Executable Scripts
1261 It is possible to define and install programs which are scripts. Such
1262 programs are listed using the @samp{SCRIPTS} primary name.
1263 @code{automake} doesn't define any dependencies for scripts; the
1264 @file{Makefile.am} should include the appropriate rules.
1267 @code{automake} does not assume that scripts are derived objects; such
1268 objects must be deleted by hand; see @ref{Clean} for more information.
1270 @code{automake} itself is a script that is generated at configure time
1271 from @file{automake.in}. Here is how this is handled:
1274 bin_SCRIPTS = automake
1277 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
1278 for it is automatically generated.
1280 Script objects can be installed in @code{bindir}, @code{sbindir},
1281 @code{libexecdir}, or @code{pkgdatadir}.
1285 @section Header files
1287 Header files are specified by the @samp{HEADERS} family of variables.
1288 Generally header files are not installed, so the @code{noinst_HEADERS}
1289 variable will be the most used.
1292 All header files must be listed somewhere; missing ones will not appear
1293 in the distribution. Often it is clearest to list uninstalled headers
1294 with the rest of the sources for a program. @xref{A Program}. Headers
1295 listed in a @samp{_SOURCES} variable need not be listed in any
1296 @samp{_HEADERS} variable.
1298 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
1299 @code{pkgincludedir}.
1303 @section Architecture-independent data files
1305 Automake supports the installation of miscellaneous data files using the
1306 @samp{DATA} family of variables.
1309 Such data can be installed in the directories @code{datadir},
1310 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
1313 By default, data files are not included in a distribution.
1315 Here is how @code{automake} installs its auxiliary data files:
1318 pkgdata_DATA = clean-kr.am clean.am compile-kr.am compile-vars.am \
1319 compile.am data.am depend.am dist-subd-top.am dist-subd-vars.am \
1320 dist-subd.am dist-vars.am dist.am footer.am header-vars.am header.am \
1321 libscripts.am libprograms.am libraries-vars.am libraries.am library.am \
1322 mans-vars.am mans.am packagedata.am program.am programs.am remake-hdr.am \
1323 remake-subd.am remake.am scripts.am subdirs.am tags.am tags-subd.am \
1324 texinfos-vars.am texinfos.am hack-make.sed nl-remove.sed
1329 @section Built sources
1331 Occasionally a file which would otherwise be called ``source'' (eg a C
1332 @samp{.h} file) is actually derived from some other file. Such files
1333 should be listed in the @code{BUILT_SOURCES} variable.
1334 @vindex BUILT_SOURCES
1336 Files listed in @code{BUILT_SOURCES} are built before any automatic
1337 dependency tracking is done. By default, built sources are not included
1341 @node Other GNU Tools
1342 @chapter Other GNU Tools
1344 Since Automake is primarily intended to generate @file{Makefile.in}s for
1345 use in GNU programs, it tries hard to interoperatoe with other GNU
1349 * Emacs Lisp:: Emacs Lisp
1357 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
1358 is used to hold a list of @samp{.el} files. Possible prefixes for this
1359 primary are @samp{lisp_} and @samp{noinst_}. Note that if
1360 @code{lisp_LISP} is defined, then @file{configure.in} must run
1361 @code{AM_PATH_LISPDIR} (fixme xref).
1366 By default Automake will byte-compile all Emacs Lisp source files using
1367 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
1368 byte-compiling, simply define the variable @samp{ELCFILES} to be empty.
1374 If @code{ud_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
1375 turns on support for GNU gettext, a message catalog system for
1376 internationalization
1377 (@pxref{GNU Gettext, , , gettext.info, GNU gettext utilities}).
1379 The @code{gettext} support in Automake requires the addition of two
1380 subdirectories to the package, @file{intl} and @file{po}. Automake
1381 ensure that these directories exist and are mentioned in @code{SUBDIRS}.
1383 Furthermore, Automake checks that the definition of @samp{ALL_LINGUAS}
1384 in @file{configure.in} corresponds to all the valid @samp{.po} files,
1391 Automake provides some automatic support for writing Guile modules.
1392 Automake will turn on Guile support if the @code{AM_INIT_GUILE_MODULE}
1393 macro is used in @file{configure.in}.
1395 Right now Guile support just means that the @code{AM_INIT_GUILE_MODULE}
1396 macro is understood to mean:
1399 @code{AM_INIT_AUTOMAKE} is run.
1402 @code{AC_CONFIG_AUX_DIR} is run, with a path of @file{..}.
1405 As the Guile module code matures, no doubt the Automake support will
1410 @chapter Building documentation
1412 Currently Automake provides support for Texinfo and man pages.
1416 * Man pages:: Man pages
1423 If the current directory contains Texinfo source, you must declare it
1424 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
1425 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
1426 here. Note that any Texinfo source file must end in the @samp{.texi} or
1427 @samp{.texinfo} extension.
1429 @vindex info_TEXINFOS
1431 If the @samp{.texi} file @code{@@include}s @file{version.texi}, then that
1432 file will be automatically generated. @file{version.texi} defines three
1433 Texinfo macros you can reference: @code{EDITION}, @code{VERSION}, and
1434 @code{UPDATED}. The first two hold the version number of your package
1435 (but are kept separate for clarity); the last is the date the primary
1436 file was last modified. The @file{version.texi} support requires the
1437 @code{mdate-sh} program; this program is supplied with Automake.
1439 Sometimes an info file actually depends on more than one @samp{.texi}
1440 file. For instance, in the @code{xdvik} distribution,
1441 @file{kpathsea.texi} includes the files @file{install.texi},
1442 @file{copying.texi}, and @file{freedom.texi}. You can tell Automake
1443 about these dependencies using the @samp{texi_TEXINFOS} variable. Here
1444 is how @code{xdvik} could do it:
1449 info_TEXINFOS = kpathsea.texi
1450 kpathsea_TEXINFOS = install.texi copying.texi freedom.texi
1453 By default, Automake requires the file @file{texinfo.tex} to appear in
1454 the same directory as the Texinfo source. However, if you used
1455 @code{AC_CONFIG_AUX_DIR} in @file{configure.in}, then @file{texinfo.tex}
1456 is looked for there. Automake supplies @file{texinfo.tex}.
1458 Automake generates an @code{install-info} target; some people apparently
1459 use this. By default, info pages are installed by @samp{make install}.
1460 This can be prevented via the @code{no-installinfo} option.
1466 A package can also include man pages. (Though see the GNU standards on
1467 this matter, @ref{Man Pages, , , standards.info, The GNU Coding
1468 Standards}.) Man pages are declared using the @samp{MANS} primary.
1469 Generally the @code{man_MANS} macro is used. Man pages are
1470 automatically installed in the correct subdirectory of @code{mandir},
1471 based on the file extension.
1475 @c Use @samp{make install} per documentation: (texi.info)code.
1476 By default, man pages are installed by @samp{make install}. However,
1477 since the GNU project does not require man pages, many maintainers do
1478 not expend effort to keep the man pages up to date. In these cases, the
1479 @code{no-installman} option will prevent the man pages from being
1480 installed by default. The user can still explicitly install them via
1481 @samp{make install-man}.
1482 @opindex no-installman
1483 @trindex install-man
1485 Here is how the documentation is handled in GNU @code{cpio} (which
1486 includes both Texinfo documentation and man pages):
1489 info_TEXINFOS = cpio.texi
1490 man_MANS = cpio.1 mt.1
1493 Texinfo source, info pages and man pages are all considered to be source
1494 for the purposes of making a distribution.
1498 @chapter What Gets Installed
1500 Naturally, Automake handles the details of actually installing your
1501 program once it has been built. All @code{PROGRAMS}, @code{SCRIPTS},
1502 @code{LIBRARIES}, @code{LISP}, @code{DATA} and @code{HEADERS} are
1503 automatically installed in the appropriate places.
1505 Automake also handles installing any specified info and man pages.
1507 Automake generates separate @code{install-data} and @code{install-exec}
1508 targets, in case the installer is installing on multiple machines which
1509 share directory structure -- these targets allow the machine-independent
1510 parts to be installed only once. The @code{install} target depends on
1511 both of these targets.
1512 @trindex install-data
1513 @trindex install-exec
1516 Automake also generates an @code{uninstall} target, and an
1517 @code{installdirs} target.
1519 @trindex installdirs
1521 It is possible to extend this mechanism by defining an
1522 @code{install-exec-local} or @code{install-data-local} target. If these
1523 targets exist, they will be run at @samp{make install} time.
1524 @trindex install-exec-local
1525 @trindex install-data-local
1529 @chapter What Gets Cleaned
1531 The GNU Makefile Standards specify a number of different clean rules.
1533 Generally the files that can cleaned are determined automatically by
1534 Automake. Of course, Automake also recognizes some variables that can
1535 be defined to specify additional files to clean. These variables are
1536 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
1537 @code{MAINTAINERCLEANFILES}.
1538 @vindex MOSTLYCLEANFILES
1540 @vindex DISTCLEANFILES
1541 @vindex MAINTAINERCLEANFILES
1545 @chapter What Goes in a Distribution
1547 The @code{dist} target in the generated @file{Makefile.in} can be used
1548 to generate a gzip'd @code{tar} file for distribution. The tar file is
1549 named based on the @var{PACKAGE} and @var{VERSION} variables; more
1550 precisely it is named @samp{@var{PACKAGE}-@var{VERSION}.tar.gz}.
1555 For the most part, the files to distribute are automatically found by
1556 Automake: all source files are automatically included in a distribution,
1557 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
1558 has a built-in list of commonly used files which, if present in the
1559 current directory, are automatically included. This list is printed by
1560 @samp{automake --help}. Also, files which are read by @code{configure}
1561 (ie, the source files corresponding to the files specified in the
1562 @code{AC_OUTPUT} invocation) are automatically distributed.
1564 Still, sometimes there are files which must be distributed, but which
1565 are not covered in the automatic rules. These files should be listed in
1566 the @code{EXTRA_DIST} variable. Note that @code{EXTRA_DIST} can only
1567 handle files in the current directory; files in other directories will
1568 cause @code{make dist} runtime failures.
1571 Occasionally it is useful to be able to change the distribution before
1572 it is packaged up. If the @code{dist-hook} target exists, it is run
1573 after the distribution directory is filled, but before the actual tar
1574 (or shar) file is created. One way to use this is for distributing file
1575 in subdirectories for which a new @file{Makefile.am} is overkill:
1579 mkdir $(distdir)/random
1580 cp -p random/a1 random/a2 $(distdir)/random
1583 Automake also generates a @code{distcheck} target which can be help to
1584 ensure that a given distribution will actually work. @code{distcheck}
1585 makes a distribution, and then tries to do a @code{VPATH} build.
1587 @c FIXME: document distcheck-hook here
1590 @chapter Support for test suites
1592 Automake supports a two forms of test suite.
1594 If the variable @code{TESTS} is defined, its value is taken to be a list
1595 of programs to run in order to do the testing. The programs can either
1596 be derived objects or source objects; the generated rule will look both
1597 in @var{srcdir} and @file{.}. The number of failures will be printed at
1598 the end of the run. The variable @code{TESTS_ENVIRONMENT} can be used
1599 to set environment variables for the test run; the environment variable
1600 @code{srcdir} is set in the rule.
1602 @vindex TESTS_ENVIRONMENT
1604 If @samp{dejagnu} appears in @code{AUTOMAKE_OPTIONS}, then the a
1605 @code{dejagnu}-based test suite is assumed. The value of the variable
1606 @code{DEJATOOL} is passed as the @code{--tool} argument to
1607 @code{runtest}; it defaults to the name of the package. The variables
1608 @code{EXPECT}, @code{RUNTEST} and @code{RUNTESTFLAGS} can also be
1609 overridden to provide project-specific values. For instance, you will
1610 need to do this if you are testing a compiler toolchain, because the
1611 default values do not take into account host and target names.
1616 @vindex RUNTESTFLAGS
1617 @c FIXME xref dejagnu
1619 In either case, the testing is done via @samp{make check}.
1623 @chapter Changing Automake's Behavior
1625 Various features of Automake can be controlled by options in the
1626 @file{Makefile.am}. Such options are listed in a special variable named
1627 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
1628 @vindex AUTOMAKE_OPTIONS
1633 @itemx @code{foreign}
1634 The same as the corresponding @samp{--strictness} option.
1636 @item @code{no-installman}
1637 The generated @file{Makefile.in} will not cause man pages to be
1638 installed by default. However, an @code{install-man} target will still
1639 be available for optional installation. This option is disallowed at
1640 @samp{GNU} strictness and above.
1641 @trindex install-man
1643 @item @code{no-installinfo}
1644 The generated @file{Makefile.in} will not cause info pages to be built
1645 or installed by default. However, @code{info} and @code{install-info}
1646 targets will still be available. This option is disallowed at
1647 @samp{GNU} strictness and above.
1649 @trindex install-info
1651 @item @code{ansi2knr}
1652 @item @code{path/ansi2knr}
1653 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceeded by a
1654 path, the generated @file{Makefile.in} will look in the specified
1655 directory to find the @file{ansi2knr} program. Generally the path
1656 should be a relative path to another directory in the same distribution
1657 (though Automake currently does not check this). It is up to you to
1658 make sure that the specified directory is built before the current
1659 directory; if @file{ansi2knr} does not exist then the build will fail.
1661 @item @code{dejagnu}
1662 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
1664 @item @code{dist-shar}
1665 Generate a @code{dist-shar} target as well as the ordinary @code{dist}
1666 target. This new target will create a shar archive of the
1670 @item @code{dist-zip}
1671 Generate a @code{dist-zip} target as well as the ordinary @code{dist}
1672 target. This new target will create a zip archive of the distribution.
1675 @item @code{dist-tarZ}
1676 Generate a @code{dist-tarZ} target as well as the ordinary @code{dist}
1677 target. This new target will create a compressed tar archive of the
1678 distribution; a traditional @code{tar} and @code{compress} will be
1679 assumed. Warning: if you are actually using @code{GNU tar}, then the
1680 generated archive might contain nonportable constructs.
1683 @item @code{no-dependencies}
1684 This is similar to using @samp{--include-deps} on the command line, but
1685 is useful for those situations where you don't have the necessary bits
1686 to make automatic dependency tracking work @xref{Dependencies}. In this
1687 case the effect is to effectively disable automatic dependency tracking.
1690 A version number (eg @samp{0.30}) can be specified. If Automake is not
1691 newer than the version specified, creation of the @file{Makefile.in}
1695 Unrecognized options are diagnosed by @code{automake}.
1699 @chapter Miscellaneous Rules
1701 There are a few rules and variables that didn't fit anywhere else.
1704 * Tags:: Interfacing to etags and mkid
1705 * Suffixes:: Handling new file extensions
1706 * Built:: Built sources
1711 @section Interfacing to @code{etags}
1713 @code{automake} will generate rules to generate @file{TAGS} files for
1714 use with GNU Emacs under some circumstances.
1716 If any C source code or headers are present, then a @code{tags} target
1717 will be generated for the directory.
1720 At the topmost directory of a multi-directory package, a @code{tags}
1721 target file will be generated which, when run, will generate a
1722 @file{TAGS} file that includes by reference all @file{TAGS} files from
1725 Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
1726 will be generated. This variable is intended for use in directories
1727 which contain taggable source that @code{etags} does not understand.
1730 Here is how Automake generates tags for its source, and for nodes in its
1734 ETAGS_ARGS = automake.in --lang=none \
1735 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
1738 If you add filenames to @var{ETAGS_ARGS}, you will probably also
1739 want to set @var{TAGS_DEPENDENCIES}. The contents of this variable
1740 are added directly to the dependencies for the @code{tags} target.
1741 @vindex TAGS_DEPENDENCIES
1743 Automake will also generate an @code{ID} target which will run
1744 @code{mkid} on the source. This is only supported on a
1745 directory-by-directory basis.
1750 @section Handling new file extensions
1752 It is sometimes useful to introduce a new implicit rule to handle a file
1753 type that Automake does not know about. If this is done, you must
1754 notify GNU Make of the new suffixes. This can be done by putting a list
1755 of new suffixes in the @code{SUFFIXES} variable.
1758 For instance, currently automake does not provide any Java support. If
1759 you wrote a macro to generate @samp{.class} files from @samp{.java}
1760 source files, you would also need to add these suffixes to the list:
1763 SUFFIXES = .java .class
1767 @section Built sources
1773 @chapter The effect of --gnu and --gnits
1775 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
1776 variable) causes @code{automake} to check the following:
1780 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
1781 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
1782 directory of the package.
1785 The options @samp{no-installman} and @samp{no-installinfo} are
1789 Note that this option will be extended in the future to do even more
1790 checking; it is advisable to be familiar with the precise requirements
1791 of the GNU standards. Also, @samp{--gnu} can require certain
1792 non-standard GNU programs to exist for use by various maintainer-only
1793 targets; for instance in the future @code{pathchk} might be required for
1796 The @samp{--gnits} option does everything that @samp{--gnu} does, and
1797 checks the following as well:
1801 @samp{make dist} will check to make sure the @file{NEWS} file has been
1802 updated to the current version.
1805 The file @file{COPYING.LIB} is prohibited.
1808 @samp{VERSION} is checked to make sure its format complies with Gnits
1810 @c FIXME xref when standards are finished
1813 If @samp{VERSION} indicates that this is an alpha release, and the file
1814 @file{README-alpha} appears in the topmost directory of a package, then
1815 it is included in the distribution.
1818 The file @file{THANKS} is required.
1823 @chapter When Automake Isn't Enough
1825 Sometimes @code{automake} isn't enough. Then you just lose.
1827 Actually, @code{automake}s implicit copying semantics means that many
1828 problems can be worked around by simply adding some @code{make} targets
1829 and rules to @file{Makefile.in}. @code{automake} will ignore these
1832 There are some caveats to doing this. Although you can overload a
1833 target already used by @code{automake}, it is often inadvisable,
1834 particularly in the topmost directory of a non-flat package. However,
1835 various useful targets have a @samp{-local} version you can specify in your
1836 @file{Makefile.in}. Automake will supplement the standard target with
1837 these user-supplied targets.
1839 The targets that support a local version are @code{all}, @code{info},
1840 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec}, and
1841 @code{uninstall}. Note that there are no @code{uninstall-exec-local} or
1842 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
1843 It doesn't make sense to uninstall just data or just executables.
1848 @trindex install-data
1849 @trindex install-exec
1852 For instance, here is how to install a file in @file{/etc}:
1856 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
1859 Some targets also have a way to run another target, called a @dfn{hook},
1860 after their work is done. The hook is named after the principal target,
1861 with @samp{-hook} appended. The targets allowing hooks are
1862 @code{install-data}, @code{install-exec}, @code{dist}, and
1864 @trindex install-data-hook
1865 @trindex install-exec-hook
1868 For instance, here is how to create a hard link to an installed program:
1872 ln $(bindir)/program $(bindir)/proglink
1875 @c FIXME should include discussion of variables you can use in these
1880 @chapter Distributing @file{Makefile.in}s
1882 Automake places no restrictions on the distribution of the resulting
1883 @file{Makefile.in}s. We still encourage software authors to distribute
1884 their work under terms like those of the GPL, but doing so is not
1885 required to use Automake.
1887 Some of the files that can be automatically installed via the
1888 @samp{--add-missing} switch do fall under the GPL; examine each file
1893 @chapter Some example packages
1895 Here are some examples of how Automake can be used.
1898 * Hello:: The simplest GNU program
1899 * Tricky:: A trickier example
1900 * Automake:: Automake's own use
1901 * Textutils:: A deep hierarchy
1905 @section The simplest GNU program
1907 @code{hello} is renowned for its classic simplicity and versatility.
1908 What better place to begin a tour? The below shows what could be used
1909 as the Hello distribution's @file{Makefile.am}.
1912 bin_PROGRAMS = hello
1913 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h
1914 hello_LDADD = @@ALLOCA@@
1915 info_TEXINFOS = hello.texi
1916 hello_TEXINFOS = gpl.texi
1918 EXTRA_DIST = testdata
1921 @@echo expect no output from diff
1923 diff -c $(srcdir)/testdata test.out
1927 Of course, Automake also requires some minor changes to
1928 @file{configure.in}. The new @file{configure.in} would read:
1931 dnl Process this file with autoconf to produce a configure script.
1933 AM_INIT_AUTOMAKE(hello, 1.3)
1938 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h)
1943 If Hello were really going to use Automake, the @file{version.c} file
1944 would probably be deleted, or changed so as to be automatically
1949 @section A tricker example
1951 Here is another, trickier example. It shows how to generate two
1952 programs (@code{ctags} and @code{etags}) from the same source file
1953 (@file{etags.c}). The difficult part is that each compilation of
1954 @file{etags.c} requires different @code{cpp} flags.
1957 bin_PROGRAMS = etags ctags
1959 ctags_LDADD = ctags.o
1960 ctags_DEPENDENCIES = ctags.o
1963 $(COMPILE) -DETAGS_REGEXPS etags.c
1966 $(COMPILE) -DCTAGS -o ctags.o etags.c
1969 Note that @code{ctags_SOURCES} is defined to be empty -- that way no
1970 implicit value is substituted. The implicit value, however, is used to
1971 generate @code{etags} from @file{etags.o}.
1973 @code{ctags_LDADD} is used to get @file{ctags.o} into the link line,
1974 while @code{ctags_DEPENDENCIES} exists to make sure that @file{ctags.o}
1975 gets built in the first place.
1977 This is a somewhat pathological example.
1981 @section Automake uses itself
1983 Automake, of course, uses itself to generate its @file{Makefile.in}.
1984 Since Automake is a shallow package, it has more than one
1985 @file{Makefile.am}. Here is the top-level @file{Makefile.am}:
1988 ## Process this file with automake to create Makefile.in
1990 AUTOMAKE_OPTIONS = gnits
1991 MAINT_CHARSET = latin1
1996 bin_SCRIPTS = automake
1997 info_TEXINFOS = automake.texi
1999 pkgdata_DATA = clean-kr.am clean.am compile-kr.am compile-vars.am \
2000 compile.am data.am depend.am \
2001 dist-vars.am footer.am header.am header-vars.am \
2002 kr-vars.am libraries-vars.am \
2003 libraries.am library.am mans-vars.am \
2004 program.am programs.am remake-hdr.am \
2005 remake-subd.am remake.am scripts.am subdirs.am tags.am tags-subd.am \
2007 texi-version.am texinfos-vars.am texinfos.am \
2008 libraries-clean.am programs-clean.am data-clean.am \
2009 COPYING INSTALL texinfo.tex \
2010 ansi2knr.c ansi2knr.1 \
2013 ## These must all be executable when installed.
2014 pkgdata_SCRIPTS = config.guess config.sub install-sh mdate-sh mkinstalldirs
2016 # The following requires a fixed version of the Emacs 19.30 etags.
2017 ETAGS_ARGS = automake.in --lang=none \
2018 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
2020 ## `test -x' is not portable. So we use Perl instead. If Perl
2021 ## doesn't exist, then this test is meaningless anyway.
2022 # Check to make sure some installed files are executable.
2024 $(PERL) -e "exit ! -x '$(pkgdatadir)/config.guess';"
2025 $(PERL) -e "exit ! -x '$(pkgdatadir)/config.sub';"
2026 $(PERL) -e "exit ! -x '$(pkgdatadir)/install-sh';"
2027 $(PERL) -e "exit ! -x '$(pkgdatadir)/mdate-sh';"
2028 $(PERL) -e "exit ! -x '$(pkgdatadir)/mkinstalldirs';"
2030 # Some simple checks:
2031 # * syntax check with perl4 and perl5.
2032 # * make sure the scripts don't use 'true'
2033 # * expect no instances of '$@{...@}'
2034 # These are only really guaranteed to work on my machine.
2035 maintainer-check: automake check
2036 $(PERL) -c -w automake
2037 @@if grep '^[^#].*true' $(srcdir)/[a-z]*.am; then \
2038 echo "can't use 'true' in GNU Makefile" 1>&2; \
2041 @@if test `fgrep '$$@{' $(srcdir)/[a-z]*.am | wc -l` -ne 0; then \
2042 echo "found too many uses of '\$$@{'" 1>&2; \
2045 if $(SHELL) -c 'perl4.036 -v' >/dev/null 2>&1; then \
2046 perl4.036 -c -w automake; \
2049 # Tag before making distribution. Also, don't make a distribution if
2050 # checks fail. Also, make sure the NEWS file is up-to-date.
2051 cvs-dist: maintainer-check
2052 @@if sed 1q NEWS | grep -e "$(VERSION)" > /dev/null; then :; else \
2053 echo "NEWS not updated; not releasing" 1>&2; \
2056 cvs tag `echo "Release-$(VERSION)" | sed 's/\./-/g'`
2060 As you can see, Automake defines many of its own rules, to make the
2061 maintainer's job easier. For instance the @code{cvs-dist} rule
2062 automatically tags the current version in the CVS repository, and then
2063 makes a standard distribution.
2065 Automake consists primarily of one program, @code{automake}, and a
2066 number of auxiliary scripts. Automake also installs a number of
2067 programs which are possibly installed via the @samp{--add-missing}
2068 option; these scripts are listed in the @code{pkgdata_SCRIPTS} variable.
2070 Automake also has a @file{tests} subdirectory, as indicated in the
2071 @code{SUBDIRS} variable above. Here is @file{tests/Makefile.am}:
2074 ## Process this file with automake to create Makefile.in
2076 AUTOMAKE_OPTIONS = gnits
2078 TESTS = mdate.test vtexi.test acoutput.test instexec.test checkall.test \
2079 acoutnoq.test acouttbs.test libobj.test proginst.test acoutqnl.test \
2080 confincl.test spelling.test prefix.test badprog.test depend.test
2085 This is where all the tests are really run. @file{defs} is an
2086 initialization file used by each test script; it is explicitly mentioned
2087 because @code{automake} has no way of automatically finding it.
2091 @section A deep hierarchy
2093 The GNU textutils are a collection of programs for manipulating text
2094 files. They are distributed as a deep package. The textutils have only
2095 recently been modified to use Automake; the examples come from a
2098 Here is the top-level @file{Makefile.am}:
2101 SUBDIRS = lib src doc man
2104 In the @file{lib} directory, a library is built which is used by each
2105 textutil. Here is @file{lib/Makefile.am}:
2108 noinst_LIBRARIES = tu
2110 EXTRA_DIST = rx.c regex.c
2112 tu_SOURCES = error.h getline.h getopt.h linebuffer.h \
2113 long-options.h md5.h regex.h rx.h xstrtod.h xstrtol.h xstrtoul.h \
2114 error.c full-write.c getline.c getopt.c getopt1.c \
2115 linebuffer.c long-options.c md5.c memchr.c safe-read.c \
2116 xmalloc.c xstrtod.c xstrtol.c xstrtoul.c
2118 tu_LIBADD = @@REGEXOBJ@@ @@LIBOBJS@@ @@ALLOCA@@
2121 The @file{src} directory contains the source for all the textutils -- 23
2122 programs in all. The @file{Makefile.am} for this directory also
2123 includes some simple checking code, and constructs a @file{version.c}
2127 bin_PROGRAMS = cat cksum comm csplit cut expand fmt fold head join md5sum \
2128 nl od paste pr sort split sum tac tail tr unexpand uniq wc
2130 noinst_HEADERS = system.h version.h
2131 DISTCLEANFILES = stamp-v version.c
2133 INCLUDES = -I$(top_srcdir)/lib
2135 LDADD = version.o ../lib/libtu.a
2137 $(PROGRAMS): version.o ../lib/libtu.a
2139 AUTOMAKE_OPTIONS = ansi2knr
2144 echo '#include <config.h>' > t-version.c
2145 echo '#include "version.h"' >> t-version.c
2146 echo 'const char *version_string = "'GNU @@PACKAGE@@ @@VERSION@@'";' \
2148 if cmp -s version.c t-version.c; then \
2151 mv t-version.c version.c; \
2153 echo timestamp > $@@
2160 --string="message digest" \
2161 --string="abcdefghijklmnopqrstuvwxyz" \
2162 --string="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" \
2163 --string="12345678901234567890123456789012345678901234567890123456789012345678901234567890" \
2164 | diff -c $(srcdir)/md5-test.rfc -
2167 The @file{doc} directory builds the info documentation for the
2171 info_TEXINFOS = textutils.texi
2174 And, last, the @file{man} directory installs the man pages for all the
2178 man_MANS = cat.1 cksum.1 comm.1 csplit.1 cut.1 expand.1 fmt.1 fold.1 head.1 \
2179 join.1 md5sum.1 nl.1 od.1 paste.1 pr.1 sort.1 split.1 sum.1 tac.1 tail.1 \
2180 tr.1 unexpand.1 uniq.1 wc.1
2183 You can now see how easy it is to handle even a largish project using
2188 @chapter Some ideas for the future
2190 Here are some things that might happen in the future:
2197 The output will be cleaned up. For instance, only variables which are
2198 actually used will appear in the generated @file{Makefile.in}.
2201 There will be support for automatically recoding a distribution. The
2202 intent is to allow a maintainer to use whatever character set is most
2203 convenient locally, but for all distributions to be Unicode or
2204 @w{ISO 10646} with the UTF-8 encoding.
2207 Support for automatically generating packages (eg Solaris packages, or
2212 @unnumbered Index of Variables
2217 @node Configure variables
2218 @unnumbered Index of Configure Variables and Macros
2224 @unnumbered Index of Targets