1 \input texinfo @c -*-texinfo-*-
3 @setfilename automake.info
10 @c Yes, this appears in many Texinfo files. He's just a likeable guy.
12 @set Francois Franc,ois
15 @set Francois Fran\noexpand\ptexc cois
18 @dircategory GNU admin
20 * automake: (automake). Making Makefile.in's
23 @dircategory Individual utilities
25 * aclocal: (automake)Invoking aclocal Generating aclocal.m4
29 This file documents GNU automake @value{VERSION}
31 Copyright (C) 1995 Free Software Foundation, Inc.
33 Permission is granted to make and distribute verbatim copies of
34 this manual provided the copyright notice and this permission notice
35 are preserved on all copies.
38 Permission is granted to process this file through TeX and print the
39 results, provided the printed document carries copying permission
40 notice identical to this one except for the removal of this paragraph
44 Permission is granted to copy and distribute modified versions of this
45 manual under the conditions for verbatim copying, provided that the entire
46 resulting derived work is distributed under the terms of a permission
47 notice identical to this one.
49 Permission is granted to copy and distribute translations of this manual
50 into another language, under the above conditions for modified versions,
51 except that this permission notice may be stated in a translation approved
58 @subtitle For version @value{VERSION}, @value{UPDATED}
61 @vskip 0pt plus 1filll
62 Copyright @copyright{} 1995 Free Software Foundation, Inc.
64 This is the first edition of the GNU Automake documentation,@*
65 and is consistent with GNU Automake @value{VERSION}.@*
67 Published by the Free Software Foundation @*
68 59 Template Place - Suite 330, @*
69 Boston, MA 02111-1307 USA @*
71 Permission is granted to make and distribute verbatim copies of
72 this manual provided the copyright notice and this permission notice
73 are preserved on all copies.
75 Permission is granted to copy and distribute modified versions of this
76 manual under the conditions for verbatim copying, provided that the entire
77 resulting derived work is distributed under the terms of a permission
78 notice identical to this one.
80 Permission is granted to copy and distribute translations of this manual
81 into another language, under the above conditions for modified versions,
82 except that this permission notice may be stated in a translation
83 approved by the Free Software Foundation.
86 @c Define an index of configure variables.
88 @c Define an index of options.
90 @c Define an index of targets.
94 @node Top, Introduction, (dir), (dir)
95 @comment node-name, next, previous, up
98 This file documents the GNU Automake package for creating GNU
99 Standards-compliant Makefiles from template files. This edition
100 documents version @value{VERSION}.
103 * Introduction:: Automake's purpose
104 * Invoking Automake:: Creating a Makefile.in
105 * Generalities:: General ideas
106 * configure:: Scanning configure.in
107 * Top level:: The top-level Makefile.am
108 * Programs:: Building programs and libraries
109 * Other objects:: Other derived objects
110 * Other GNU Tools:: Other GNU Tools
111 * Documentation:: Building documentation
112 * Install:: What gets installed
113 * Clean:: What gets cleaned
114 * Dist:: What goes in a distribution
115 * Tests:: Support for test suites
116 * Options:: Changing Automake's behavior
117 * Miscellaneous:: Miscellaneous rules
118 * Gnits:: The effect of --gnu and --gnits
119 * Extending:: Extending Automake
120 * Distributing:: Distributing the Makefile.in
121 * Examples:: Some example packages
122 * Future:: Some ideas for the future
123 * Variables:: Index of variables
124 * Configure variables:: Index of configure variables and macros
125 * Targets:: Index of targets
131 @chapter Introduction
133 Automake is a tool for automatically generating
134 @file{Makefile.in}s from files called @file{Makefile.am}. The
135 @file{Makefile.am} is basically a series of @code{make} macro
136 definitions (with rules being thrown in occasionally). The generated
137 @file{Makefile.in}s are compliant with the GNU Makefile standards.
139 The GNU Makefile Standards Document
140 (@pxref{Makefile Conventions, , , standards.info, The GNU Coding Standards})
141 is long, complicated, and subject to change. The goal of Automake is to
142 remove the burden of Makefile maintenance from the back of the
143 individual GNU maintainer (and put it on the back of the Automake
146 The typical Automake input files is simply a series of macro
147 definitions. Each such file is processed to create a
148 @file{Makefile.in}. There should generally be one @file{Makefile.am}
149 per directory of a project.
151 Automake does constrain a project in certain ways; for instance it
152 assumes that the project uses Autoconf
153 (@pxref{Top, , The Autoconf Manual, autoconf.info, The Autoconf Manual}),
154 and enforces certain restrictions on the @file{configure.in} contents.
156 @code{Automake} requires @code{perl} in order to generate the
157 @file{Makefile.in}s. However, the distributions created by Automake are
158 fully GNU standards-compliant, and do not require @code{perl} in order
161 Mail suggestions and bug reports for Automake to
162 @email{bug-gnu-utils@@prep.ai.mit.edu}.
165 @node Invoking Automake
166 @chapter Creating a @file{Makefile.in}
168 To create all the @file{Makefile.in}s for a package, run the
169 @code{automake} program in the top level directory, with no arguments.
170 @code{automake} will automatically find each appropriate
171 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
172 and generate the corresponding @file{Makefile.in}.
174 You can optionally give @code{automake} an argument; @samp{.am} is
175 appended to the argument and the result is used as the name of the input
176 file. This feature is generally only used to automatically rebuild an
177 out-of-date @file{Makefile.in}. Note that @code{automake} must always
178 be run from the topmost directory of a project, even if being used to
179 regenerate the @file{Makefile.in} in some subdirectory. This is
180 necessary because @code{automake} must scan @file{configure.in}, and
181 because @code{automake} uses the knowledge that a @file{Makefile.in} is
182 in a subdirectory to change its behavior in some cases.
184 @code{automake} accepts the following options:
189 Automake requires certain common files to exist in certain situations;
190 for instance @file{config.guess} is required if @file{configure.in} runs
191 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
192 files; this option will cause the missing ones to be automatically added
193 to the package, whenever possible. In general if Automake tells you a
194 file is missing, try using this option.
196 @item --amdir=@var{dir}
197 Look for Automake data files in directory @var{dir} instead of in the
198 installation directory. This is typically used for debugging.
200 @item --build-dir=@var{dir}
201 Tell Automake where the build directory is. This option is used when
202 including dependencies into a @file{Makefile.in} generated by @code{make
203 dist}; it should not be used otherwise.
206 An alias for @samp{--strictness=foreign}.
209 An alias for @samp{--strictness=gnits}.
212 An alias for @samp{--strictness=gnu}.
215 Print a summary of the command line options and exit.
219 Include all automatically generated dependency information
220 (@pxref{Dependencies}) in the generated
221 @file{Makefile.in}. This is generally done when making a distribution;
225 @item --output-dir=@var{dir}
226 Put the generated @file{Makefile.in} in the directory @var{dir}.
227 Ordinarily each @file{Makefile.in} is created in the directory of the
228 corresponding @file{Makefile.am}. This option is used when making
231 @item --srcdir-name=@var{dir}
232 Tell Automake the name of the source directory used in the current
233 build. This option is used when including dependencies into a
234 @file{Makefile.in} generated by @code{make dist}; it should not be used
238 @item --strictness=@var{level}
239 Set the global strictness to @var{level}; this can be overridden in each
240 @file{Makefile.am} if required. @xref{Generalities} for more
245 Cause Automake to print information about which files are being read or
249 Print the version number of Automake and exit.
254 @chapter General ideas
256 There are a few basic ideas that will help understand how Automake
260 * General Operation:: General operation of Automake
261 * Depth:: The kinds of packages
262 * Strictness:: Standards conformance checking
263 * Uniform:: The Uniform Naming Scheme
264 * Canonicalization:: How derived variables are named
267 @node General Operation
268 @section General Operation
270 Automake works by reading a @file{Makefile.am} and generating a
271 @file{Makefile.in}. Certain macros and targets defined in the
272 @file{Makefile.am} instruct automake to generate more specialized code;
273 for instances a @samp{bin_PROGRAMS} macro definition will cause targets
274 for compiling and linking to be generated.
276 The macro definitions and targets in the @file{Makefile.am} are copied
277 into the generated file. This allows you to add arbitrary code into the
278 generated @file{Makefile.in}. For instance the Automake distribution
279 includes a non-standard @code{cvs-dist} target, which the Automake
280 maintainer uses to make distributions from his source control system.
282 Note that GNU make extensions are not recognized by Automake. Using
283 such extensions in a @file{Makefile.am} will lead to errors or confusing
286 Automake tries to group comments with adjoining targets (or variable
287 definitions) in an intelligent way.
289 A target defined in @file{Makefile.am} generally overrides any such
290 target of a similar name that would be automatically generated by
291 @code{automake}. Although this is a supported feature, it is generally
292 best to avoid making use of it, as sometimes the generated rules are
295 When examining a variable definition, Automake will recursively examine
296 variables referenced in the definition. Eg if Automake is looking at
297 the content of @samp{foo_SOURCES} in this snippet
301 foo_SOURCES = c.c $(xs)
304 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
305 contents of @samp{foo_SOURCES}.
307 Automake also allows a form of comment which is @emph{not} copied into
308 the output; all lines beginning with @samp{##} are completely ignored by
311 It is customary to make the first line of @file{Makefile.am} read:
314 ## Process this file with automake to produce Makefile.in
317 @c FIXME discuss putting a copyright into Makefile.am here? I would but
318 @c I don't know quite what to say.
320 @c FIXME document customary ordering of Makefile.am here!
326 @code{automake} supports three kinds of directory hierarchy: ``flat'',
327 ``shallow'', and ``deep''.
329 A @dfn{flat} package is one in which all the files are in a single
330 directory. The @file{Makefile.am} for such a package by definition
331 lacks a @code{SUBDIRS} macro. An example of such a package is
335 A @dfn{deep} package is one in which all the source lies in
336 subdirectories; the top level directory contains mainly configuration
337 information. GNU cpio is a good example of such a package, as is GNU
338 @code{tar}. The top level @file{Makefile.am} for a deep package will
339 contain a @code{SUBDIRS} macro, but no other macros to define objects
342 A @dfn{shallow} package is one in which the primary source resides in
343 the top-level directory, while various parts (typically libraries)
344 reside in subdirectories. @code{automake} is one such package (as is
345 GNU @code{make}, which does not currently use @code{automake}).
350 While Automake is intended to be used by maintainers of GNU packages, it
351 does make some effort to accommodate those who wish to use it, but do
352 not want to use all the GNU conventions.
354 To this end, Automake supports three levels of @dfn{strictness} -- the
355 strictness indicating how stringently Automake should check standards
358 The valid strictness levels are:
362 Automake will check for only those things which are absolutely
363 required for proper operations. For instance, whereas GNU standards
364 dictate the existence of a @file{NEWS} file, it will not be required in
365 this mode. The name comes from the fact that Automake is intended to be
366 used for GNU programs; these relaxed rules are not the standard mode of
370 Automake will check -- as much as possible -- for compliance to the GNU
371 standards for packages. This is the default.
374 Automake will check for compliance to the as-yet-unwritten GNITS
375 standards. These are based on the GNU standards, but are even more
376 detailed. Unless you are a GNITS standards contributor, it is
377 recommended that you avoid this option until such time as the GNITS
378 standard is actually published.
381 For more information on the precise implications of the strictness
382 level, see @xref{Gnits}.
386 @section The Uniform Naming Scheme
387 Automake variables generally follow a uniform naming scheme that makes
388 it easy to decide how programs (and other derived objects) are built,
389 and how they are installed. This scheme also supports @code{configure}
390 time determination of what should be built.
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 A different set of variables is used to decide where the built objects
399 should be installed. These variables are named after the primary
400 variables, but have a prefix indicating which standard directory should
401 be used as the installation directory. The standard directory names are
402 given in the GNU standards
403 (@pxref{Directory Variables, , , standards.info, The GNU Coding
405 @code{automake} extends this list with @code{pkglibdir},
406 @code{pkgincludedir}, and @code{pkgdatadir}; these are the same as the
407 non-@samp{pkg} versions, but with @samp{@@PACKAGE@@} appended.
410 For each primary, there is one additional variable named by prepending
411 @samp{EXTRA_} to the primary name. This variable is used to list
412 objects which may or may not be built, depending on what
413 @code{configure} decides. This variable is required because Automake
414 must know the entire list of objects to be built in order to generate a
415 @file{Makefile.in} that will work in all cases.
417 For instance, @code{cpio} decides at configure time which programs are
418 built. Some of the programs are installed in @code{bindir}, and some
419 are installed in @code{sbindir}:
422 EXTRA_PROGRAMS = mt rmt
423 bin_PROGRAMS = cpio pax
424 sbin_PROGRAMS = @@PROGRAMS@@
427 Defining a primary variable is an error.
429 Note that the common @samp{dir} suffix is left off when constructing the
430 variable names; thus one writes @samp{bin_PROGRAMS} and not
431 @samp{bindir_PROGRAMS}.
433 Not every sort of object can be installed in every directory. Automake
434 will flag those attempts it finds in error. Automake will also diagnose
435 obvious misspellings in directory names.
437 Sometimes the standard directories -- even as augmented by Automake --
438 are not enough. In particular it is sometimes useful, for clarity, to
439 install objects in a subdirectory of some predefined directory. To this
440 end, Automake allows you to extend the list of possible installation
441 directories. A given prefix (eg @samp{zar}) is valid if a variable of
442 the same name with @samp{dir} appended is defined (eg @samp{zardir}).
444 For instance, until HTML support is part of Automake, you could use this
445 to install raw HTML documentation:
448 htmldir = $(prefix)/html
449 html_DATA = automake.html
452 The special prefix @samp{noinst} indicates that the objects in question
453 should not be installed at all.
455 The special prefix @samp{check} indicates that the objects in question
456 should not be built until the @code{make check} command is run.
458 Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
459 @samp{LISP}, @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS},
471 @node Canonicalization
472 @section How derived variables are named
474 Sometimes a Makefile variable name is derived from some text the user
475 supplies. For instance program names are rewritten into Makefile macro
476 names. Automake canonicalizes this text, so that it does not have to
477 follow Makefile variable naming rules. All characters in the name
478 except for letters, numbers, and the underscore are turned into
479 underscores when making macro references. Eg, if your program is named
480 @code{sniff-glue}, the derived variable name would be
481 @code{sniff_glue_SOURCES}, not @code{sniff-glue_SOURCES}.
485 @chapter Scanning @file{configure.in}
487 Automake scans the package's @file{configure.in} to determine certain
488 information about the package. Some @code{autoconf} macros are required
489 and some variables must be defined in @file{configure.in}. Automake
490 will also use information from @file{configure.in} to further tailor its
494 * Requirements:: Configuration requirements
495 * Optional:: Other things Automake recognizes
496 * Invoking aclocal:: Auto-generating aclocal.m4
497 * Macros:: Autoconf macros supplied with Automake
498 * Extending aclocal:: Writing your own aclocal macros
503 @section Configuration requirements
505 The simplest way to meet the basic Automake requirements is to use the
506 macro @code{AM_INIT_AUTOMAKE} (FIXME: xref). But if you prefer, you can
507 do the required steps by hand:
508 @cvindex AM_INIT_AUTOMAKE
512 Define the variables @code{PACKAGE} and @code{VERSION} with
516 @code{PACKAGE} should be the name of the package as it appears when
517 bundled for distribution. For instance, Automake defines @code{PACKAGE}
518 to be @samp{automake}. @code{VERSION} should be the version number of
519 the release that is being developed. We recommend that you make
520 @file{configure.in} the only place in your package where the version
521 number is defined; this makes releases simpler.
523 Automake doesn't do any interpretation of @code{PACKAGE} or
524 @code{VERSION}, except in @samp{Gnits} mode (FIXME xref).
527 Use the macro @code{AC_ARG_PROGRAM} if a program or script is installed.
528 @cvindex AC_ARG_PROGRAM
531 Use @code{AC_PROG_MAKE_SET} if the package is not flat.
532 @cvindex AC_PROG_MAKE_SET
535 Use @code{AM_PROG_INSTALL} if any scripts (@pxref{Scripts}) are
536 installed by the package. Otherwise, use @code{AC_PROG_INSTALL}.
537 @cvindex AC_PROG_INSTALL
538 @cvindex AM_PROG_INSTALL
542 Here are the other macros which Automake requires but which are not run
543 by @code{AM_INIT_AUTOMAKE}:
547 Automake uses this to determine which files to create. Listed files
548 named @code{Makefile} are treated as @file{Makefile}s. Other listed
549 files are treated differently. Currently the only difference is that a
550 @file{Makefile} is removed by @code{make distclean}, while other files
551 are removed by @code{make clean}.
552 @c FIXME: this is in violation of standards!
557 @section Other things Automake recognizes
559 Automake will also recognize the use of certain macros and tailor the
560 generated @file{Makefile.in} appropriately. Currently recognized macros
561 and their effects are:
564 @item AC_CONFIG_HEADER
565 Automake will generate rules to automatically regenerate the config
566 header. If you do use this macro, you must create the file
567 @file{stamp-h.in} in your source directory. It can be empty. Also, the
568 @code{AC_OUTPUT} command in @file{configure.in} must create
572 [test -z "$CONFIG_HEADERS" || echo timestamp > stamp-h])
574 @cvindex AC_CONFIG_HEADER
575 Note that Automake does not currently currently check to make sure the
576 @code{AC_OUTPUT} command is correct. Hopefully a future version of
577 @code{autoconf} will let Automake handle this automatically.
579 @item AC_CONFIG_AUX_DIR
580 Automake will look for various helper scripts, such as
581 @file{mkinstalldirs}, in the directory named in this macro invocation.
582 If not seen, the scripts are looked for in their ``standard'' locations
583 (either the top source directory, or in the source directory
584 corresponding to the current @file{Makefile.am}, whichever is
586 @cvindex AC_CONFIG_AUX_DIR
587 FIXME: give complete list of things looked for in this directory
590 Automake will insert definitions for the variables defined by
591 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
593 @cvindex AC_PATH_XTRA
595 @item AC_CANONICAL_HOST
597 Automake will ensure that @file{config.guess} and @file{config.sub}
598 exist. Also, the @file{Makefile} variables @samp{host_alias} and
599 @samp{host_triplet} are introduced.
600 @c fixme xref autoconf docs.
601 @cvindex AC_CANONICAL_HOST
602 @cvindex AC_CHECK_TOOL
606 @item AC_CANONICAL_SYSTEM
607 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
608 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
609 @cvindex AC_CANONICAL_SYSTEM
614 @item AC_FUNC_GETLOADAVG
616 @item AC_STRUCT_ST_BLOCKS
617 @item AM_FUNC_FNMATCH
619 @item AC_REPLACE_FUNCS
620 @item AC_REPLACE_GNU_GETOPT
622 Automake will ensure that the appropriate source files are part of the
623 distribution, and will ensure that the appropriate dependencies are
624 generated for these objects. @xref{A Library} for more
626 @cvindex AC_FUNC_ALLOCA
627 @cvindex AC_FUNC_GETLOADAVG
628 @cvindex AC_FUNC_MEMCMP
629 @cvindex AC_STRUCT_ST_BLOCKS
630 @cvindex AM_FUNC_FNMATCH
631 @cvindex AC_FUNC_FNMATCH
632 @cvindex AC_REPLACE_FUNCS
633 @cvindex AC_REPLACE_GNU_GETOPT
634 @cvindex AM_FUNC_STRTOD
635 @cvindex AM_WITH_REGEX
638 Automake will detect statements which put @samp{.o} files into
639 @code{LIBOBJS}, and will treat these additional files as if they were
640 discovered via @code{AC_REPLACE_FUNCS}.
644 This is required if any libraries are built in the package.
645 @cvindex AC_PROG_RANLIB
648 This is required if any C++ source is included.
651 @c @item AM_PROG_LIBTOOL
652 @c Automake will turn on processing for @code{libtool} (@pxref{Top, , The
653 @c Libtool Manual, libtool.info, The Libtool Manual}). This work is
654 @c still preliminary.
655 @c @cvindex AM_PROG_LIBTOOL
658 If a Yacc source file is seen, then you must either use this macro or
659 declare the variable @samp{YACC} in @file{configure.in}. The former is
661 @cvindex AC_PROG_YACC
665 This macro is required if there is Yacc source in the package.
666 @cvindex AC_DECL_YYTEXT
669 If a Lex source file is seen, then this macro must be used.
673 If Automake sees that this variable is set in @file{configure.in}, it
674 will check the @file{po} directory to ensure that all the named
675 @samp{.po} files exist, and that all the @samp{.po} files that exist are
679 @item AM_C_PROTOTYPES
680 This is required when using automatic de-ANSI-fication, see @ref{ANSI}.
681 @cvindex AM_C_PROTOTYPES
684 This macro is required for packages which use GNU gettext
685 (@pxref{gettext}). It is distributed with gettext. If Automake sees
686 this macro it ensures that the package meets some of gettext's
688 @cvindex ud_GNU_GETTEXT
690 @item AM_MAINTAINER_MODE
691 This macro adds a @samp{--enable-maintainer-mode} option to
692 @code{configure}. If this is used, @code{automake} will cause
693 ``maintainer-only'' rules to be turned off by default in the generated
694 @file{Makefile.in}s. This macro is disallowed in @samp{Gnits} mode.
696 @cvindex jm_MAINTAINER_MODE
700 @node Invoking aclocal
701 @section Auto-generating aclocal.m4
703 The @code{aclocal} program will automatically generate @file{aclocal.m4}
704 files based on the contents of @file{configure.in}.
706 ... explain why on earth you'd want to do this
708 @code{aclocal} accepts the following options:
711 @item --acdir=@var{dir}
712 Look for the macro files in @var{dir} instead of the installation
713 directory. This is typically used for debugging.
716 Print a summary of the command line options and exit.
718 @item --output=@var{file}
719 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
722 Print the names of the files it examines.
725 Print the version number of Automake and exit.
730 @section Autoconf macros supplied with Automake
732 @c consider generating this node automatically from m4 files.
735 @item AM_FUNC_FNMATCH
736 If the @code{fnmatch} function is not available, or does not work
737 correctly (like the one on SunOS 5.4), add @samp{fnmatch.o} to output
738 variable @code{LIBOBJS}.
741 If the @code{strtod} function is not available, or does not work
742 correctly (like the one on SunOS 5.4), add @samp{strtod.o} to output
743 variable @code{LIBOBJS}.
745 @item AM_FUNC_ERROR_AT_LINE
747 @item AM_FUNC_OBSTACK
749 @item AM_C_PROTOTYPES
750 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
751 @item AM_INIT_AUTOMAKE
752 @item AM_MAINTAINER_MODE
753 @item AM_PATH_LISPDIR
754 @item AM_PROG_CC_STDC
755 @item AM_PROG_INSTALL
756 @item AM_SANITY_CHECK_CC
757 @item AM_SYS_POSIX_TERMIOS
758 @item AM_TYPE_PTRDIFF_T
759 @item AM_WITH_DMALLOC
764 @node Extending aclocal
765 @section Writing your own aclocal macros
767 ... explain format of macro files
768 ... explain how to get your own macros installed (using acinstall)
769 ... explain situations where this is actually useful (eg gettext)
773 @chapter The top-level @file{Makefile.am}
775 In non-flat packages, the top level @file{Makefile.am} must tell
776 Automake which subdirectories are to be built. This is done via the
777 @code{SUBDIRS} variable.
780 The @code{SUBDIRS} macro holds a list of subdirectories in which
781 building of various sorts can occur. Many targets (eg @code{all}) in
782 the generated @file{Makefile} will run both locally and in all specified
783 subdirectories. Note that the directories listed in @code{SUBDIRS} are
784 not required to contain @file{Makefile.am}s; only @file{Makefile}s
785 (after configuration). This allows inclusion of libraries from packages
786 which do not use Automake (such as @code{gettext}).
788 In a deep package, the top-level @file{Makefile.am} is often very short.
789 For instance, here is the @file{Makefile.am} from the textutils
793 SUBDIRS = lib src doc man
796 @code{SUBDIRS} can contain configure substitutions (eg @samp{@@DIRS@@});
797 Automake itself does not actually examine the contents of this variable.
799 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
800 @code{AC_PROG_MAKE_SET}.
802 The use of @code{SUBDIRS} is not restricted to just the top-level
803 @file{Makefile.am}. Automake can be used to construct packages of
808 @chapter Building Programs and Libraries
810 A large part of Automake's functionality is dedicated to making it easy
811 to build C programs and libraries.
814 * A Program:: Building a program
815 * A Library:: Building a library
816 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
817 * Program variables:: Variables used when building a program
818 * Yacc and Lex:: Yacc and Lex support
819 * C++:: C++ and other languages
820 * ANSI:: Automatic de-ANSI-fication
821 * Dependencies:: Automatic dependency tracking
826 @section Building a program
828 In a directory containing source that gets built into a program (as
829 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
830 can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
831 @code{pkglibdir}, or not at all.
839 In this simple case, the resulting @file{Makefile.in} will contain code
840 to generate a program named @code{hello}. The variable
841 @code{hello_SOURCES} is used to specify which source files get built
845 hello_SOURCES = hello.c
848 This causes @file{hello.c} to be compiled into @file{hello.o}, and then
849 linked to produce @file{hello}.
851 If @samp{prog_SOURCES} is needed, but not specified, then it defaults to
852 the single file @file{prog.c}. In the example above, the definition of
853 @code{hello_SOURCES} is actually redundant.
857 Multiple programs can be built in a single directory. Multiple programs
858 can share a single source file. The source file must be listed in each
859 @samp{_SOURCES} definition.
861 Header files listed in a @samp{_SOURCES} definition will be included in
862 the distribution but otherwise ignored. In case it isn't obvious, you
863 should not include the header file generated by @file{configure} in an
864 @samp{_SOURCES} variable; this file should not be distributed.
865 Lex (@samp{.l}) and yacc (@samp{.y}) files can also be listed; support
866 for these should work but is still preliminary.
867 @c lex & yacc should have a separate section
869 Sometimes it is useful to determine the programs that are to be built at
870 configure time. For instance, GNU @code{cpio} only builds @code{mt} and
871 @code{rmt} under special circumstances.
873 In this case, you must notify @code{Automake} of all the programs that
874 can possibly be built, but at the same time cause the generated
875 @file{Makefile.in} to use the programs specified by @code{configure}.
876 This is done by having @code{configure} substitute values into each
877 @samp{_PROGRAMS} definition, while listing all optionally built programs in
878 @code{EXTRA_PROGRAMS}.
879 @vindex EXTRA_PROGRAMS
881 If you need to link against libraries that are not found by
882 @code{configure}, you can use @code{LDADD} to do so. This variable
883 actually can be used to add any options to the linker command line.
886 Sometimes, multiple programs are built in one directory but do not share
887 the same link-time requirements. In this case, you can use the
888 @samp{@var{prog}_LDADD} variable (where @var{PROG} is the name of the
889 program as it appears in some @samp{_PROGRAMS} variable, and usually
890 written in lowercase) to override the global @code{LDADD}. (If this
891 variable exists for a given program, then that program is not linked
895 For instance, in GNU cpio, @code{pax}, @code{cpio}, and @code{mt} are
896 linked against the library @file{libcpio.a}. However, @code{rmt} is
897 built in the same directory, and has no such link requirement. Also,
898 @code{mt} and @code{rmt} are only built on certain architectures. Here
899 is what cpio's @file{src/Makefile.am} looks like (abridged):
902 bin_PROGRAMS = cpio pax @@MT@@
903 libexec_PROGRAMS = @@RMT@@
904 EXTRA_PROGRAMS = mt rmt
906 LDADD = ../lib/libcpio.a @@INTLLIBS@@
909 cpio_SOURCES = @dots{}
910 pax_SOURCES = @dots{}
912 rmt_SOURCES = @dots{}
915 It is also occasionally useful to have a program depend on some other
916 target which is not actually part of that program. This can be done
917 using the @samp{prog_DEPENDENCIES} variable. Each program depends on
918 the contents of such a variable, but no further interpretation is done.
920 If @samp{prog_DEPENDENCIES} is not supplied, it is computed by Automake.
921 The automatically-assigned value is the contents of @samp{prog_LDADD}
922 with all the @samp{-l} and @samp{-L} options removed. Be warned that
923 @file{configure} substitutions are preserved; this can lead to bad
924 dependencies if you are not careful.
928 @section Building a library
930 Building a library is much like building a program. In this case, the
931 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
932 @code{libdir} or @code{pkglibdir}.
934 Each @samp{_LIBRARIES} variable is a list of the base names of
935 libraries to be built. For instance to create a library named
936 @file{libcpio.a}, but not install it, you would write:
939 noinst_LIBRARIES = cpio
942 The sources that go into a library are determined exactly as they are
943 for programs, via the @samp{_SOURCES} variables. Note that programs and
944 libraries share a namespace, so one cannot have a program (@file{lob}) and
945 a library (@file{liblob.a}) with the same name in one directory.
947 Extra objects can be added to a library using the @samp{library_LIBADD}
948 variable. This should be used for objects determined by
949 @code{configure}. Again from cpio:
954 cpio_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
959 @section Special handling for LIBOBJS and ALLOCA
961 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
962 @code{@@ALLOCA@@}, and uses this information, plus the list of
963 @code{LIBOBJS} files derived from @file{configure.in} to automatically
964 include the appropriate source files in the distribution (@pxref{Dist}).
965 These source files are also automatically handled in the
966 dependency-tracking scheme, see @xref{Dependencies}.
968 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
969 @samp{_LDADD} or @samp{_LIBADD} variable.
972 @node Program variables
973 @section Variables used when building a program
975 Occasionally it is useful to know which @file{Makefile} variables
976 Automake uses for compilations; for instance you might need to do your
977 own compilation in some special cases.
979 Some variables are inherited from Autoconf; these are @code{CC},
980 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
984 There are some additional variables which Automake itself defines:
988 A list of @samp{-I} options. This can be set in your @file{Makefile.am}
989 if you have special directories you want to look in.
992 This is the command used to actually compile a C source file. The
993 filename is appended to form the complete command line.
996 This is the command used to actually link a C program.
1001 @section Yacc and Lex support
1003 Automake has somewhat idiosyncratic support for Yacc and Lex.
1004 FIXME: describe it here.
1008 @section C++ and other languages
1010 Automake includes full support for C++, and rudimentary support for
1011 other languages. Support for other languages will be improved based on
1014 Any package including C++ code must use @code{AC_PROG_CXX} in its
1015 @file{configure.in}.
1017 A few additional variables are defined when a C++ source file is seen:
1021 The name of the C++ compiler.
1024 Any flags to pass to the C++ compiler.
1027 The command used to actually compile a C++ source file. The file name
1028 is appended to form the complete command line.
1031 The command used to actually link a C++ program.
1036 @section Automatic de-ANSI-fication
1038 Although the GNU standards prohibit it, some GNU programs are written in
1039 ANSI C; see FIXME. This is possible because each source file can be
1040 ``de-ANSI-fied'' before the actual compilation takes place.
1042 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
1043 @vindex AUTOMAKE_OPTIONS
1044 (@ref{Options}) contains the option @code{ansi2knr}
1046 then code to handle de-ANSI-fication is inserted into the generated
1049 This causes each source file to be treated as ANSI C. If an ANSI C
1050 compiler is available, it is used.
1052 This support requires the source files @file{ansi2knr.c} and
1053 @file{ansi2knr.1} to be in the same directory as the ANSI C source;
1054 these files are distributed with Automake.
1055 Also, the package @file{configure.in} must call the macro
1056 @code{AM_C_PROTOTYPES}.
1057 @cvindex AM_C_PROTOTYPES
1059 Automake also handles finding the @code{ansi2knr} support files in some
1060 other directory in the current package. This is done by prepending the
1061 relative path to the appropriate directory to the @code{ansi2knr}
1062 option. For instance, suppose the package has ANSI C code in the
1063 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
1064 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
1065 @file{src/Makefile.am}:
1068 AUTOMAKE_OPTIONS = ../lib/ansi2knr
1071 Note that the directory holding the @code{ansi2knr} support files must
1072 be built before all other directories using these files. Automake does
1073 not currently check that this is the case.
1075 Note also that @code{ansi2knr} assumes the source code will be formatted
1076 in a particular way. See the @code{ansi2knr} man page for details.
1080 @section Automatic dependency tracking
1082 As a developer it is often painful to continually update the
1083 @file{Makefile.in} whenever the include-file dependencies change in a
1084 project. @code{automake} supplies a way to automatically track
1085 dependency changes, and distribute the dependencies in the generated
1088 Currently this support requires the use of GNU @code{make} and
1089 @code{gcc}. It might become possible in the future to supply a
1090 different dependency generating program, if there is enough demand.
1092 This mode is enabled by default if any C program or library is defined
1093 in the current directory.
1095 When you decide to make a distribution, the @code{dist} target will
1097 re-run @code{automake} with the @samp{--include-deps} option. This
1099 causes the previously generated dependencies to be inserted into the
1100 generated @file{Makefile.in}, and thus into the distribution.
1101 @samp{--include-deps} also turns off inclusion of the dependency
1104 This mode can be suppressed by putting @code{no-dependencies} in the
1105 variable @code{AUTOMAKE_OPTIONS}.
1106 @vindex AUTOMAKE_OPTIONS
1107 @opindex no-dependencies
1109 If you unpack a distribution made by @code{make dist}, and you want to
1110 turn on the dependency-tracking code again, simply run @code{automake}
1115 @chapter Other Derived Objects
1117 Automake can handle derived objects which are not C programs. Sometimes
1118 the support for actually building such objects must be explicitly
1119 supplied, but Automake will still automatically handle installation and
1123 * Scripts:: Executable scripts
1124 * Headers:: Header files
1125 * Data:: Architecture-independent data files
1126 * Sources:: Derived sources
1131 @section Executable Scripts
1133 It is possible to define and install programs which are scripts. Such
1134 programs are listed using the @samp{SCRIPTS} primary name.
1135 @code{automake} doesn't define any dependencies for scripts; the
1136 @file{Makefile.am} should include the appropriate rules.
1139 @code{automake} does not assume that scripts are derived objects; such
1140 objects must be deleted by hand; see @ref{Clean} for more information.
1142 @code{automake} itself is a script that is generated at configure time
1143 from @file{automake.in}. Here is how this is handled:
1146 bin_SCRIPTS = automake
1149 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
1150 for it is automatically generated.
1152 Script objects can be installed in @code{bindir}, @code{sbindir},
1153 @code{libexecdir}, or @code{pkgdatadir}.
1157 @section Header files
1159 Header files are specified by the @samp{HEADERS} family of variables.
1160 Generally header files are not installed, so the @code{noinst_HEADERS}
1161 variable will be the most used.
1164 All header files must be listed somewhere; missing ones will not appear
1165 in the distribution. Often it is clearest to list uninstalled headers
1166 with the rest of the sources for a program. @xref{A Program}. Headers
1167 listed in a @samp{_SOURCES} variable need not be listed in any
1168 @samp{_HEADERS} variable.
1170 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
1171 @code{pkgincludedir}.
1175 @section Architecture-independent data files
1177 Automake supports the installation of miscellaneous data files using the
1178 @samp{DATA} family of variables.
1181 Such data can be installed in the directories @code{datadir},
1182 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
1185 By default, data files are not included in a distribution.
1187 Here is how @code{automake} installs its auxiliary data files:
1190 pkgdata_DATA = clean-kr.am clean.am compile-kr.am compile-vars.am \
1191 compile.am data.am depend.am dist-subd-top.am dist-subd-vars.am \
1192 dist-subd.am dist-vars.am dist.am footer.am header-vars.am header.am \
1193 libscripts.am libprograms.am libraries-vars.am libraries.am library.am \
1194 mans-vars.am mans.am packagedata.am program.am programs.am remake-hdr.am \
1195 remake-subd.am remake.am scripts.am subdirs.am tags.am tags-subd.am \
1196 texinfos-vars.am texinfos.am hack-make.sed nl-remove.sed
1201 @section Built sources
1203 Occasionally a file which would otherwise be called ``source'' (eg a C
1204 @samp{.h} file) is actually derived from some other file. Such files
1205 should be listed in the @code{BUILT_SOURCES} variable.
1206 @vindex BUILT_SOURCES
1208 Files listed in @code{BUILT_SOURCES} are built before any automatic
1209 dependency tracking is done. By default, built sources are not included
1213 @node Other GNU Tools
1214 @chapter Other GNU Tools
1216 Since Automake is primarily intended to generate @file{Makefile.in}s for
1217 use in GNU programs, it tries hard to interoperatoe with other GNU
1221 * Emacs Lisp:: Emacs Lisp
1228 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
1229 is used to hold a list of @samp{.el} files. Possible prefixes for this
1230 primary are @samp{lisp_} and @samp{noinst_}. Note that if
1231 @code{lisp_LISP} is defined, then @file{configure.in} must run
1232 @code{AM_PATH_LISPDIR} (fixme xref).
1237 By default Automake will byte-compile all Emacs Lisp source files using
1238 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
1239 byte-compiling, simply define the variable @samp{ELCFILES} to be empty.
1245 If @code{ud_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
1246 turns on support for GNU gettext, a message catalog system for
1247 internationalization
1248 (@pxref{GNU Gettext, , , gettext.info, GNU gettext utilities}).
1250 The @code{gettext} support in Automake requires the addition of two
1251 subdirectories to the package, @file{intl} and @file{po}. Automake
1252 ensure that these directories exist and are mentioned in @code{SUBDIRS}.
1254 Furthermore, Automake checks that the definition of @samp{ALL_LINGUAS}
1255 in @file{configure.in} corresponds to all the valid @samp{.po} files,
1260 @chapter Building documentation
1262 Currently Automake provides support for Texinfo and man pages.
1266 * Man pages:: Man pages
1273 If the current directory contains Texinfo source, you must declare it
1274 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
1275 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
1276 here. Note that any Texinfo source file must end in the @samp{.texi} or
1277 @samp{.texinfo} extension.
1279 @vindex info_TEXINFOS
1281 If the @samp{.texi} file @code{@@include}s @file{version.texi}, then that
1282 file will be automatically generated. @file{version.texi} defines three
1283 Texinfo macros you can reference: @code{EDITION}, @code{VERSION}, and
1284 @code{UPDATED}. The first two hold the version number of your package
1285 (but are kept separate for clarity); the last is the date the primary
1286 file was last modified. The @file{version.texi} support requires the
1287 @code{mdate-sh} program; this program is supplied with Automake.
1289 Sometimes an info file actually depends on more than one @samp{.texi}
1290 file. For instance, in the @code{xdvik} distribution,
1291 @file{kpathsea.texi} includes the files @file{install.texi},
1292 @file{copying.texi}, and @file{freedom.texi}. You can tell Automake
1293 about these dependencies using the @samp{texi_TEXINFOS} variable. Here
1294 is how @code{xdvik} could do it:
1299 info_TEXINFOS = kpathsea.texi
1300 kpathsea_TEXINFOS = install.texi copying.texi freedom.texi
1303 By default, Automake requires the file @file{texinfo.tex} to appear in
1304 the same directory as the Texinfo source. However, if you used
1305 @code{AC_CONFIG_AUX_DIR} in @file{configure.in}, then @file{texinfo.tex}
1306 is looked for there. Automake supplies @file{texinfo.tex}.
1308 Automake generates an @code{install-info} target; some people apparently
1309 use this. By default, info pages are installed by @samp{make install}.
1310 This can be prevented via the @code{no-installinfo} option.
1316 A package can also include man pages. (Though see the GNU standards on
1317 this matter, @ref{Man Pages, , , standards.info, The GNU Coding
1318 Standards}.) Man pages are declared using the @samp{MANS} primary.
1319 Generally the @code{man_MANS} macro is used. Man pages are
1320 automatically installed in the correct subdirectory of @code{mandir},
1321 based on the file extension.
1325 @c Use @samp{make install} per documentation: (texi.info)code.
1326 By default, man pages are installed by @samp{make install}. However,
1327 since the GNU project does not require man pages, many maintainers do
1328 not expend effort to keep the man pages up to date. In these cases, the
1329 @code{no-installman} option will prevent the man pages from being
1330 installed by default. The user can still explicitly install them via
1331 @samp{make install-man}.
1332 @opindex no-installman
1333 @trindex install-man
1335 Here is how the documentation is handled in GNU @code{cpio} (which
1336 includes both Texinfo documentation and man pages):
1339 info_TEXINFOS = cpio.texi
1340 man_MANS = cpio.1 mt.1
1343 Texinfo source, info pages and man pages are all considered to be source
1344 for the purposes of making a distribution.
1348 @chapter What Gets Installed
1350 Naturally, Automake handles the details of actually installing your
1351 program once it has been built. All @code{PROGRAMS}, @code{SCRIPTS},
1352 @code{LIBRARIES}, @code{LISP}, @code{DATA} and @code{HEADERS} are
1353 automatically installed in the appropriate places.
1355 Automake also handles installing any specified info and man pages.
1357 Automake generates separate @code{install-data} and @code{install-exec}
1358 targets, in case the installer is installing on multiple machines which
1359 share directory structure -- these targets allow the machine-independent
1360 parts to be installed only once. The @code{install} target depends on
1361 both of these targets.
1362 @trindex install-data
1363 @trindex install-exec
1366 Automake also generates an @code{uninstall} target, and an
1367 @code{installdirs} target.
1369 @trindex installdirs
1371 It is possible to extend this mechanism by defining an
1372 @code{install-exec-local} or @code{install-data-local} target. If these
1373 targets exist, they will be run at @samp{make install} time.
1374 @trindex install-exec-local
1375 @trindex install-data-local
1379 @chapter What Gets Cleaned
1381 The GNU Makefile Standards specify a number of different clean rules.
1383 Generally the files that can cleaned are determined automatically by
1384 Automake. Of course, Automake also recognizes some variables that can
1385 be defined to specify additional files to clean. These variables are
1386 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
1387 @code{MAINTAINERCLEANFILES}.
1388 @vindex MOSTLYCLEANFILES
1390 @vindex DISTCLEANFILES
1391 @vindex MAINTAINERCLEANFILES
1395 @chapter What Goes in a Distribution
1397 The @code{dist} target in the generated @file{Makefile.in} can be used
1398 to generate a gzip'd @code{tar} file for distribution. The tar file is
1399 named based on the @var{PACKAGE} and @var{VERSION} variables; more
1400 precisely it is named @samp{@var{PACKAGE}-@var{VERSION}.tar.gz}.
1405 For the most part, the files to distribute are automatically found by
1406 Automake: all source files are automatically included in a distribution,
1407 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
1408 has a built-in list of commonly used files which, if present in the
1409 current directory, are automatically included. This list is printed by
1410 @samp{automake --help}. Also, files which are read by @code{configure}
1411 (ie, the source files corresponding to the files specified in the
1412 @code{AC_OUTPUT} invocation) are automatically distributed.
1414 Still, sometimes there are files which must be distributed, but which
1415 are not covered in the automatic rules. These files should be listed in
1416 the @code{EXTRA_DIST} variable. Note that @code{EXTRA_DIST} can only
1417 handle files in the current directory; files in other directories will
1418 cause @code{make dist} runtime failures.
1421 Occasionally it is useful to be able to change the distribution before
1422 it is packaged up. If the @code{dist-hook} target exists, it is run
1423 after the distribution directory is filled, but before the actual tar
1424 (or shar) file is created. One way to use this is for distributing file
1425 in subdirectories for which a new @file{Makefile.am} is overkill:
1429 mkdir $(distdir)/random
1430 cp -p random/a1 random/a2 $(distdir)/random
1433 Automake also generates a @code{distcheck} target which can be help to
1434 ensure that a given distribution will actually work. @code{distcheck}
1435 makes a distribution, and then tries to do a @code{VPATH} build.
1437 @c FIXME: document distcheck-hook here
1440 @chapter Support for test suites
1442 Automake supports a two forms of test suite.
1444 If the variable @code{TESTS} is defined, its value is taken to be a list
1445 of programs to run in order to do the testing. The programs can either
1446 be derived objects or source objects; the generated rule will look both
1447 in @var{srcdir} and @file{.}. The number of failures will be printed at
1448 the end of the run. The variable @code{TESTS_ENVIRONMENT} can be used
1449 to set environment variables for the test run; the environment variable
1450 @code{srcdir} is set in the rule.
1452 @vindex TESTS_ENVIRONMENT
1454 If @samp{dejagnu} appears in @code{AUTOMAKE_OPTIONS}, then the a
1455 @code{dejagnu}-based test suite is assumed. The value of the variable
1456 @code{DEJATOOL} is passed as the @code{--tool} argument to
1457 @code{runtest}; it defaults to the name of the package. The variables
1458 @code{EXPECT}, @code{RUNTEST} and @code{RUNTESTFLAGS} can also be
1459 overridden to provide project-specific values. For instance, you will
1460 need to do this if you are testing a compiler toolchain, because the
1461 default values do not take into account host and target names.
1466 @vindex RUNTESTFLAGS
1467 @c FIXME xref dejagnu
1469 In either case, the testing is done via @samp{make check}.
1473 @chapter Changing Automake's Behavior
1475 Various features of Automake can be controlled by options in the
1476 @file{Makefile.am}. Such options are listed in a special variable named
1477 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
1478 @vindex AUTOMAKE_OPTIONS
1483 @itemx @code{foreign}
1484 The same as the corresponding @samp{--strictness} option.
1486 @item @code{no-installman}
1487 The generated @file{Makefile.in} will not cause man pages to be
1488 installed by default. However, an @code{install-man} target will still
1489 be available for optional installation. This option is disallowed at
1490 @samp{GNU} strictness and above.
1491 @trindex install-man
1493 @item @code{no-installinfo}
1494 The generated @file{Makefile.in} will not cause info pages to be built
1495 or installed by default. However, @code{info} and @code{install-info}
1496 targets will still be available. This option is disallowed at
1497 @samp{GNU} strictness and above.
1499 @trindex install-info
1501 @item @code{ansi2knr}
1502 @item @code{path/ansi2knr}
1503 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceeded by a
1504 path, the generated @file{Makefile.in} will look in the specified
1505 directory to find the @file{ansi2knr} program. Generally the path
1506 should be a relative path to another directory in the same distribution
1507 (though Automake currently does not check this). It is up to you to
1508 make sure that the specified directory is built before the current
1509 directory; if @file{ansi2knr} does not exist then the build will fail.
1511 @item @code{dejagnu}
1512 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
1514 @item @code{dist-shar}
1515 Generate a @code{dist-shar} target as well as the ordinary @code{dist}
1516 target. This new target will create a shar archive of the
1520 @item @code{dist-zip}
1521 Generate a @code{dist-zip} target as well as the ordinary @code{dist}
1522 target. This new target will create a zip archive of the distribution.
1525 @item @code{dist-tarZ}
1526 Generate a @code{dist-tarZ} target as well as the ordinary @code{dist}
1527 target. This new target will create a compressed tar archive of the
1528 distribution; a traditional @code{tar} and @code{compress} will be
1529 assumed. Warning: if you are actually using @code{GNU tar}, then the
1530 generated archive might contain nonportable constructs.
1533 @item @code{no-dependencies}
1534 This is similar to using @samp{--include-deps} on the command line, but
1535 is useful for those situations where you don't have the necessary bits
1536 to make automatic dependency tracking work @xref{Dependencies}. In this
1537 case the effect is to effectively disable automatic dependency tracking.
1540 A version number (eg @samp{0.30}) can be specified. If Automake is not
1541 newer than the version specified, creation of the @file{Makefile.in}
1545 Unrecognized options are diagnosed by @code{automake}.
1549 @chapter Miscellaneous Rules
1551 There are a few rules and variables that didn't fit anywhere else.
1554 * Tags:: Interfacing to etags and mkid
1555 * Suffixes:: Handling new file extensions
1556 * Built:: Built sources
1561 @section Interfacing to @code{etags}
1563 @code{automake} will generate rules to generate @file{TAGS} files for
1564 use with GNU Emacs under some circumstances.
1566 If any C source code or headers are present, then a @code{tags} target
1567 will be generated for the directory.
1570 At the topmost directory of a multi-directory package, a @code{tags}
1571 target file will be generated which, when run, will generate a
1572 @file{TAGS} file that includes by reference all @file{TAGS} files from
1575 Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
1576 will be generated. This variable is intended for use in directories
1577 which contain taggable source that @code{etags} does not understand.
1580 Here is how Automake generates tags for its source, and for nodes in its
1584 ETAGS_ARGS = automake.in --lang=none \
1585 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
1588 If you add filenames to @var{ETAGS_ARGS}, you will probably also
1589 want to set @var{TAGS_DEPENDENCIES}. The contents of this variable
1590 are added directly to the dependencies for the @code{tags} target.
1591 @vindex TAGS_DEPENDENCIES
1593 Automake will also generate an @code{ID} target which will run
1594 @code{mkid} on the source. This is only supported on a
1595 directory-by-directory basis.
1600 @section Handling new file extensions
1602 It is sometimes useful to introduce a new implicit rule to handle a file
1603 type that Automake does not know about. If this is done, you must
1604 notify GNU Make of the new suffixes. This can be done by putting a list
1605 of new suffixes in the @code{SUFFIXES} variable.
1608 For instance, currently automake does not provide any Java support. If
1609 you wrote a macro to generate @samp{.class} files from @samp{.java}
1610 source files, you would also need to add these suffixes to the list:
1613 SUFFIXES = .java .class
1617 @section Built sources
1623 @chapter The effect of --gnu and --gnits
1625 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
1626 variable) causes @code{automake} to check the following:
1630 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
1631 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
1632 directory of the package.
1635 The options @samp{no-installman} and @samp{no-installinfo} are
1639 Note that this option will be extended in the future to do even more
1640 checking; it is advisable to be familiar with the precise requirements
1641 of the GNU standards. Also, @samp{--gnu} can require certain
1642 non-standard GNU programs to exist for use by various maintainer-only
1643 targets; for instance in the future @code{pathchk} might be required for
1646 The @samp{--gnits} option does everything that @samp{--gnu} does, and
1647 checks the following as well:
1651 @samp{make dist} will check to make sure the @file{NEWS} file has been
1652 updated to the current version.
1655 The file @file{COPYING.LIB} is prohibited.
1658 @samp{VERSION} is checked to make sure its format complies with Gnits
1660 @c FIXME xref when standards are finished
1663 If @samp{VERSION} indicates that this is an alpha release, and the file
1664 @file{README-alpha} appears in the topmost directory of a package, then
1665 it is included in the distribution.
1668 The file @file{THANKS} is required.
1673 @chapter When Automake Isn't Enough
1675 Sometimes @code{automake} isn't enough. Then you just lose.
1677 Actually, @code{automake}s implicit copying semantics means that many
1678 problems can be worked around by simply adding some @code{make} targets
1679 and rules to @file{Makefile.in}. @code{automake} will ignore these
1682 There are some caveats to doing this. Although you can overload a
1683 target already used by @code{automake}, it is often inadvisable,
1684 particularly in the topmost directory of a non-flat package. However,
1685 various useful targets have a @samp{-local} version you can specify in your
1686 @file{Makefile.in}. Automake will supplement the standard target with
1687 these user-supplied targets.
1689 The targets that support a local version are @code{all}, @code{info},
1690 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec}, and
1691 @code{uninstall}. Note that there are no @code{uninstall-exec-local} or
1692 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
1693 It doesn't make sense to uninstall just data or just executables.
1698 @trindex install-data
1699 @trindex install-exec
1702 For instance, here is how to install a file in @file{/etc}:
1706 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
1709 Some targets also have a way to run another target, called a @dfn{hook},
1710 after their work is done. The hook is named after the principal target,
1711 with @samp{-hook} appended. The targets allowing hooks are
1712 @code{install-data}, @code{install-exec}, @code{dist}, and
1714 @trindex install-data-hook
1715 @trindex install-exec-hook
1718 For instance, here is how to create a hard link to an installed program:
1722 ln $(bindir)/program $(bindir)/proglink
1725 @c FIXME should include discussion of variables you can use in these
1730 @chapter Distributing @file{Makefile.in}s
1732 Automake places no restrictions on the distribution of the resulting
1733 @file{Makefile.in}s. We still encourage software authors to distribute
1734 their work under terms like those of the GPL, but doing so is not
1735 required to use Automake.
1737 Some of the files that can be automatically installed via the
1738 @samp{--add-missing} switch do fall under the GPL; examine each file
1743 @chapter Some example packages
1745 Here are some examples of how Automake can be used.
1748 * Hello:: The simplest GNU program
1749 * Tricky:: A trickier example
1750 * Automake:: Automake's own use
1751 * Textutils:: A deep hierarchy
1755 @section The simplest GNU program
1757 @code{hello} is renowned for its classic simplicity and versatility.
1758 What better place to begin a tour? The below shows what could be used
1759 as the Hello distribution's @file{Makefile.am}.
1762 bin_PROGRAMS = hello
1763 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h
1764 hello_LDADD = @@ALLOCA@@
1765 info_TEXINFOS = hello.texi
1766 hello_TEXINFOS = gpl.texi
1768 EXTRA_DIST = testdata
1771 @@echo expect no output from diff
1773 diff -c $(srcdir)/testdata test.out
1777 Of course, Automake also requires some minor changes to
1778 @file{configure.in}. The new @file{configure.in} would read:
1781 dnl Process this file with autoconf to produce a configure script.
1783 AM_INIT_AUTOMAKE(hello, 1.3)
1788 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h)
1793 If Hello were really going to use Automake, the @file{version.c} file
1794 would probably be deleted, or changed so as to be automatically
1799 @section A tricker example
1801 Here is another, trickier example. It shows how to generate two
1802 programs (@code{ctags} and @code{etags}) from the same source file
1803 (@file{etags.c}). The difficult part is that each compilation of
1804 @file{etags.c} requires different @code{cpp} flags.
1807 bin_PROGRAMS = etags ctags
1809 ctags_LDADD = ctags.o
1810 ctags_DEPENDENCIES = ctags.o
1813 $(COMPILE) -DETAGS_REGEXPS etags.c
1816 $(COMPILE) -DCTAGS -o ctags.o etags.c
1819 Note that @code{ctags_SOURCES} is defined to be empty -- that way no
1820 implicit value is substituted. The implicit value, however, is used to
1821 generate @code{etags} from @file{etags.o}.
1823 @code{ctags_LDADD} is used to get @file{ctags.o} into the link line,
1824 while @code{ctags_DEPENDENCIES} exists to make sure that @file{ctags.o}
1825 gets built in the first place.
1827 This is a somewhat pathological example.
1831 @section Automake uses itself
1833 Automake, of course, uses itself to generate its @file{Makefile.in}.
1834 Since Automake is a shallow package, it has more than one
1835 @file{Makefile.am}. Here is the top-level @file{Makefile.am}:
1838 ## Process this file with automake to create Makefile.in
1840 AUTOMAKE_OPTIONS = gnits
1841 MAINT_CHARSET = latin1
1846 bin_SCRIPTS = automake
1847 info_TEXINFOS = automake.texi
1849 pkgdata_DATA = clean-kr.am clean.am compile-kr.am compile-vars.am \
1850 compile.am data.am depend.am \
1851 dist-vars.am footer.am header.am header-vars.am \
1852 kr-vars.am libraries-vars.am \
1853 libraries.am library.am mans-vars.am \
1854 program.am programs.am remake-hdr.am \
1855 remake-subd.am remake.am scripts.am subdirs.am tags.am tags-subd.am \
1857 texi-version.am texinfos-vars.am texinfos.am \
1858 libraries-clean.am programs-clean.am data-clean.am \
1859 COPYING INSTALL texinfo.tex \
1860 ansi2knr.c ansi2knr.1 \
1863 ## These must all be executable when installed.
1864 pkgdata_SCRIPTS = config.guess config.sub install-sh mdate-sh mkinstalldirs
1866 # The following requires a fixed version of the Emacs 19.30 etags.
1867 ETAGS_ARGS = automake.in --lang=none \
1868 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
1870 ## `test -x' is not portable. So we use Perl instead. If Perl
1871 ## doesn't exist, then this test is meaningless anyway.
1872 # Check to make sure some installed files are executable.
1874 $(PERL) -e "exit ! -x '$(pkgdatadir)/config.guess';"
1875 $(PERL) -e "exit ! -x '$(pkgdatadir)/config.sub';"
1876 $(PERL) -e "exit ! -x '$(pkgdatadir)/install-sh';"
1877 $(PERL) -e "exit ! -x '$(pkgdatadir)/mdate-sh';"
1878 $(PERL) -e "exit ! -x '$(pkgdatadir)/mkinstalldirs';"
1880 # Some simple checks:
1881 # * syntax check with perl4 and perl5.
1882 # * make sure the scripts don't use 'true'
1883 # * expect no instances of '$@{...@}'
1884 # These are only really guaranteed to work on my machine.
1885 maintainer-check: automake check
1886 $(PERL) -c -w automake
1887 @@if grep '^[^#].*true' $(srcdir)/[a-z]*.am; then \
1888 echo "can't use 'true' in GNU Makefile" 1>&2; \
1891 @@if test `fgrep '$$@{' $(srcdir)/[a-z]*.am | wc -l` -ne 0; then \
1892 echo "found too many uses of '\$$@{'" 1>&2; \
1895 if $(SHELL) -c 'perl4.036 -v' >/dev/null 2>&1; then \
1896 perl4.036 -c -w automake; \
1899 # Tag before making distribution. Also, don't make a distribution if
1900 # checks fail. Also, make sure the NEWS file is up-to-date.
1901 cvs-dist: maintainer-check
1902 @@if sed 1q NEWS | grep -e "$(VERSION)" > /dev/null; then :; else \
1903 echo "NEWS not updated; not releasing" 1>&2; \
1906 cvs tag `echo "Release-$(VERSION)" | sed 's/\./-/g'`
1910 As you can see, Automake defines many of its own rules, to make the
1911 maintainer's job easier. For instance the @code{cvs-dist} rule
1912 automatically tags the current version in the CVS repository, and then
1913 makes a standard distribution.
1915 Automake consists primarily of one program, @code{automake}, and a
1916 number of auxiliary scripts. Automake also installs a number of
1917 programs which are possibly installed via the @samp{--add-missing}
1918 option; these scripts are listed in the @code{pkgdata_SCRIPTS} variable.
1920 Automake also has a @file{tests} subdirectory, as indicated in the
1921 @code{SUBDIRS} variable above. Here is @file{tests/Makefile.am}:
1924 ## Process this file with automake to create Makefile.in
1926 AUTOMAKE_OPTIONS = gnits
1928 TESTS = mdate.test vtexi.test acoutput.test instexec.test checkall.test \
1929 acoutnoq.test acouttbs.test libobj.test proginst.test acoutqnl.test \
1930 confincl.test spelling.test prefix.test badprog.test depend.test
1935 This is where all the tests are really run. @file{defs} is an
1936 initialization file used by each test script; it is explicitly mentioned
1937 because @code{automake} has no way of automatically finding it.
1941 @section A deep hierarchy
1943 The GNU textutils are a collection of programs for manipulating text
1944 files. They are distributed as a deep package. The textutils have only
1945 recently been modified to use Automake; the examples come from a
1948 Here is the top-level @file{Makefile.am}:
1951 SUBDIRS = lib src doc man
1954 In the @file{lib} directory, a library is built which is used by each
1955 textutil. Here is @file{lib/Makefile.am}:
1958 noinst_LIBRARIES = tu
1960 EXTRA_DIST = rx.c regex.c
1962 tu_SOURCES = error.h getline.h getopt.h linebuffer.h \
1963 long-options.h md5.h regex.h rx.h xstrtod.h xstrtol.h xstrtoul.h \
1964 error.c full-write.c getline.c getopt.c getopt1.c \
1965 linebuffer.c long-options.c md5.c memchr.c safe-read.c \
1966 xmalloc.c xstrtod.c xstrtol.c xstrtoul.c
1968 tu_LIBADD = @@REGEXOBJ@@ @@LIBOBJS@@ @@ALLOCA@@
1971 The @file{src} directory contains the source for all the textutils -- 23
1972 programs in all. The @file{Makefile.am} for this directory also
1973 includes some simple checking code, and constructs a @file{version.c}
1977 bin_PROGRAMS = cat cksum comm csplit cut expand fmt fold head join md5sum \
1978 nl od paste pr sort split sum tac tail tr unexpand uniq wc
1980 noinst_HEADERS = system.h version.h
1981 DISTCLEANFILES = stamp-v version.c
1983 INCLUDES = -I$(top_srcdir)/lib
1985 LDADD = version.o ../lib/libtu.a
1987 $(PROGRAMS): version.o ../lib/libtu.a
1989 AUTOMAKE_OPTIONS = ansi2knr
1994 echo '#include <config.h>' > t-version.c
1995 echo '#include "version.h"' >> t-version.c
1996 echo 'const char *version_string = "'GNU @@PACKAGE@@ @@VERSION@@'";' \
1998 if cmp -s version.c t-version.c; then \
2001 mv t-version.c version.c; \
2003 echo timestamp > $@@
2010 --string="message digest" \
2011 --string="abcdefghijklmnopqrstuvwxyz" \
2012 --string="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" \
2013 --string="12345678901234567890123456789012345678901234567890123456789012345678901234567890" \
2014 | diff -c $(srcdir)/md5-test.rfc -
2017 The @file{doc} directory builds the info documentation for the
2021 info_TEXINFOS = textutils.texi
2024 And, last, the @file{man} directory installs the man pages for all the
2028 man_MANS = cat.1 cksum.1 comm.1 csplit.1 cut.1 expand.1 fmt.1 fold.1 head.1 \
2029 join.1 md5sum.1 nl.1 od.1 paste.1 pr.1 sort.1 split.1 sum.1 tac.1 tail.1 \
2030 tr.1 unexpand.1 uniq.1 wc.1
2033 You can now see how easy it is to handle even a largish project using
2038 @chapter Some ideas for the future
2040 Here are some things that might happen in the future:
2047 The output will be cleaned up. For instance, only variables which are
2048 actually used will appear in the generated @file{Makefile.in}.
2051 There will be support for automatically recoding a distribution. The
2052 intent is to allow a maintainer to use whatever character set is most
2053 convenient locally, but for all distributions to be Unicode or
2054 @w{ISO 10646} with the UTF-8 encoding.
2059 @unnumbered Index of Variables
2064 @node Configure variables
2065 @unnumbered Index of Configure Variables and Macros
2071 @unnumbered Index of Targets