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
21 * automake: (automake). Making Makefile.in's
27 This file documents GNU automake @value{VERSION}
29 Copyright (C) 1995 Free Software Foundation, Inc.
31 Permission is granted to make and distribute verbatim copies of
32 this manual provided the copyright notice and this permission notice
33 are preserved on all copies.
36 Permission is granted to process this file through TeX and print the
37 results, provided the printed document carries copying permission
38 notice identical to this one except for the removal of this paragraph
42 Permission is granted to copy and distribute modified versions of this
43 manual under the conditions for verbatim copying, provided that the entire
44 resulting derived work is distributed under the terms of a permission
45 notice identical to this one.
47 Permission is granted to copy and distribute translations of this manual
48 into another language, under the above conditions for modified versions,
49 except that this permission notice may be stated in a translation approved
56 @subtitle For version @value{VERSION}, @value{UPDATED}
59 @vskip 0pt plus 1filll
60 Copyright @copyright{} 1995 Free Software Foundation, Inc.
62 This is the first edition of the GNU Automake documentation,@*
63 and is consistent with GNU Automake @value{VERSION}.@*
65 Published by the Free Software Foundation @*
66 675 Massachusetts Avenue, @*
67 Cambridge, MA 02139 USA @*
69 Permission is granted to make and distribute verbatim copies of
70 this manual provided the copyright notice and this permission notice
71 are preserved on all copies.
73 Permission is granted to copy and distribute modified versions of this
74 manual under the conditions for verbatim copying, provided that the entire
75 resulting derived work is distributed under the terms of a permission
76 notice identical to this one.
78 Permission is granted to copy and distribute translations of this manual
79 into another language, under the above conditions for modified versions,
80 except that this permission notice may be stated in a translation
81 approved by the Free Software Foundation.
84 @c Define an index of configure variables.
86 @c Define an index of options.
88 @c Define an index of targets.
92 @node Top, Introduction, (dir), (dir)
93 @comment node-name, next, previous, up
96 This file documents the GNU Automake package for creating GNU
97 Standards-compliant Makefiles from template files. This edition
98 documents version @value{VERSION}.
101 * Introduction:: Automake's purpose
102 * Invoking Automake:: Creating a Makefile.in
103 * Generalities:: General ideas
104 * configure:: Scanning configure.in
105 * Top level:: The top-level Makefile.am
106 * Programs:: Building programs and libraries
107 * Other objects:: Other derived objects
108 * Documentation:: Building documentation
109 * Install:: What gets installed
110 * Clean:: What gets cleaned
111 * Dist:: What goes in a distribution
112 * Tests:: Support for test suites
113 * Options:: Changing Automake's behavior
114 * Miscellaneous:: Miscellaneous rules
115 * Extending:: Extending Automake
116 * Distributing:: Distributing the Makefile.in
117 * Examples:: Some example packages
118 * Future:: Some ideas for the future
119 * Variables:: Index of variables
120 * Configure variables:: Index of configure variables and macros
121 * Targets:: Index of targets
127 @chapter Introduction
129 Automake is a tool for automatically generating
130 @file{Makefile.in}s from files called @file{Makefile.am}. The
131 @file{Makefile.am} is basically a series of @code{make} macro
132 definitions (with rules being thrown in occasionally). The generated
133 @file{Makefile.in}s are compliant with the GNU Makefile standards.
135 The GNU Makefile Standards Document
136 (@pxref{Makefile Conventions, , , standards.info, The GNU Coding Standards})
137 is long, complicated, and subject to change. The goal of Automake is to
138 remove the burden of Makefile maintenance from the back of the
139 individual GNU maintainer (and put it on the back of the Automake
142 The typical Automake input files is simply a series of macro
143 definitions. Each such file is processed to create a
144 @file{Makefile.in}. There should generally be one @file{Makefile.am}
145 per directory of a project.
147 Automake does constrain a project in certain ways; for instance it
148 assumes that the project uses Autoconf
149 (@pxref{Top, , The Autoconf Manual, autoconf.info, The Autoconf Manual}),
150 and enforces certain restrictions on the @file{configure.in} contents.
152 @code{Automake} requires @code{perl} in order to generate the
153 @file{Makefile.in}s. However, the distributions created by Automake are
154 fully GNU standards-compliant, and do not require @code{perl} in order
157 Mail suggestions and bug reports for Automake to tromey@@cygnus.com.
160 @node Invoking Automake
161 @chapter Creating a @file{Makefile.in}
163 To create all the @file{Makefile.in}s for a package, run the
164 @code{automake} program in the top level directory, with no arguments.
165 @code{automake} will automatically find each appropriate
166 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
167 and generate the corresponding @file{Makefile.in}.
169 You can optionally give @code{automake} an argument; @samp{.am} is
170 appended to the argument and the result is used as the name of the input
171 file. This feature is generally only used to automatically rebuild an
172 out-of-date @file{Makefile.in}. Note that @code{automake} must always
173 be run from the topmost directory of a project, even if being used to
174 regenerate the @file{Makefile.in} in some subdirectory. This is
175 necessary because @code{automake} must scan @file{configure.in}, and
176 because @code{automake} uses the knowledge that a @file{Makefile.in} is
177 in a subdirectory to change its behavior in some cases.
179 @code{automake} accepts the following options:
182 @item --amdir=@var{dir}
183 Look for Automake data files in directory @var{dir} instead of in the
184 installation directory. This is typically used for debugging.
187 An alias for @samp{--strictness=foreign}.
190 An alias for @samp{--strictness=gnits}.
193 An alias for @samp{--strictness=gnu}.
196 Print a summary of the command line options and exit.
199 Include all automatically generated dependency information
200 (@pxref{Dependencies}) in the generated
201 @file{Makefile.in}. This is generally done when making a distribution;
205 Automake requires certain common files to exist in certain situations;
206 for instance @file{config.guess} is required if @file{configure.in} runs
207 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
208 files; this option will cause the missing ones to be automatically added
209 to the package, whenever possible.
211 @item --output-dir=@var{dir}
212 Put the generated @file{Makefile.in} in the directory @var{dir}.
213 Ordinarily each @file{Makefile.in} is created in the directory of the
214 corresponding @file{Makefile.am}. This option is used when making
217 @item --strictness=@var{level}
218 Set the global strictness to @var{level}; this can be overridden in each
219 @file{Makefile.am} if required. @xref{Generalities} for more
223 Cause Automake to print information about which files are being read or
227 Print the version number of Automake and exit.
232 @chapter General ideas
235 @code{automake} supports three kinds of directory hierarchy: ``flat'',
236 ``shallow'', and ``deep''.
238 A @dfn{flat} package is one in which all the files are in a single
239 directory. The @file{Makefile.am} for such a package by definition
240 lacks a @code{SUBDIRS} macro. An example of such a package is
244 A @dfn{deep} package is one in which all the source lies in
245 subdirectories; the top level directory contains mainly configuration
246 information. GNU cpio is a good example of such a package, as is GNU
247 @code{tar}. The top level @file{Makefile.am} for a deep package will
248 contain a @code{SUBDIRS} macro, but no other macros to define objects
251 A @dfn{shallow} package is one in which the primary source resides in
252 the top-level directory, while various parts (typically libraries)
253 reside in subdirectories. @code{automake} is one such package (as is
254 GNU @code{make}, which does not currently use @code{automake}).
258 While Automake is intended to be used by maintainers of GNU packages, it
259 does make some effort to accomodate those who wish to use it, but do not
260 want to use all the GNU conventions.
262 To this end, Automake supports three levels of @dfn{strictness} -- the
263 strictness indicating how stringently Automake should check standards
266 The valid strictness levels are:
270 Automake will check for only those things which are absolutely
271 required for proper operations. For instance, whereas GNU standards
272 dictate the existence of a @file{NEWS} file, it will not be required in
273 this mode. The name comes from the fact that Automake is intended to be
274 used for GNU programs; these relaxed rules are not the standard mode of
278 Automake will check -- as much as possible -- for compliance to the GNU
279 standards for packages. This is the default.
282 Automake will check for compliance to the as-yet-unwritten GNITS
283 standards. These are based on the GNU standards, but are even more
284 detailed. Unless you are a GNITS standards contributor, it is
285 recommended that you avoid this option until such time as the GNITS
286 standard is actually published.
290 @section The Uniform Naming Scheme
291 Automake variables generally follow a uniform naming scheme that makes
292 it easy to decide how programs (and other derived objects) are built,
293 and how they are installed. This scheme also supports @code{configure}
294 time determination of what should be built.
296 At @code{make} time, certain variables are used to determine which
297 objects are to be built. These variables are called @dfn{primary}
298 variables. For instance, the primary variable @code{PROGRAMS} holds a
299 list of programs which are to be compiled and linked.
302 A different set of variables is used to decide where the built objects
303 should be installed. These variables are named after the primary
304 variables, but have a prefix indicating which standard directory should
305 be used as the installation directory. The standard directory names are
306 given in the GNU standards
307 (@pxref{Directory Variables, , , standards.info, The GNU Coding
309 @code{automake} extends this list with @code{pkglibdir},
310 @code{pkgincludedir}, and @code{pkgdatadir}; these are the same as the
311 non-@samp{pkg} versions, but with @samp{@@PACKAGE@@} appended.
314 For each primary, there is one additional variable named by prepending
315 @samp{EXTRA_} to the primary name. This variable is used to list
316 objects which may or may not be built, depending on what
317 @code{configure} decides. This variable is required because Automake
318 must know the entire list of objects to be built in order to generate a
319 @file{Makefile.in} that will work in all cases.
321 For instance, @code{cpio} decides at configure time which programs are
322 built. Some of the programs are installed in @code{bindir}, and some
323 are installed in @code{sbindir}:
326 EXTRA_PROGRAMS = mt rmt
327 bin_PROGRAMS = cpio pax
328 sbin_PROGRAMS = @@PROGRAMS@@
331 Defining a primary variable is an error.
333 Note that the common @samp{dir} suffix is left off when constructing the
334 variable names; thus one writes @samp{bin_PROGRAMS} and not
335 @samp{bindir_PROGRAMS}.
337 Not every sort of object can be installed in every directory. Automake
338 will flag those attempts it finds in error. Automake will also diagnose
339 obvious misspellings in directory names.
341 Sometimes the standard directories -- even as augmented by Automake --
342 are not enough. In particular it is sometimes useful, for clarity, to
343 install objects in a subdirectory of some predefined directory. To this
344 end, Automake allows you to extend the list of possible installation
345 directories. A given prefix (eg @samp{zar}) is valid if a variable of
346 the same name with @samp{dir} appended is defined (eg @samp{zardir}).
348 For instance, until HTML support is part of Automake, you could use this
349 to install raw HTML documentation:
352 htmldir = $(prefix)/html
353 html_DATA = automake.html
356 The special prefix @samp{noinst} indicates that the objects in question
357 should not be installed at all.
359 Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
360 @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
370 @section General Operation
371 Automake essentially works by reading a @file{Makefile.am} and
372 generating a @file{Makefile.in}. The macro definitions and targets in
373 the @file{Makefile.am} are copied into the generated file.
375 Automake tries to group comments with adjoining targets (or variable
376 definitions) in an intelligent way.
378 A target defined in @file{Makefile.am} generally overrides any such
379 target of a similar name that would be automatically generated by
380 @code{automake}. Although this is a supported feature, it is generally
381 best to avoid making use of it, as sometimes the generated rules are
384 Automake also allows a form of comment which is @emph{not} copied into
385 the output; all lines beginning with @samp{##} are completely ignored by
388 It is customary to make the first line of @file{Makefile.am} read:
391 ## Process this file with automake to produce Makefile.in
394 @c FIXME discuss putting a copyright into Makefile.am here? I would but
395 @c I don't know quite what to say.
397 @c FIXME document customary ordering of Makefile.am here!
401 @chapter Scanning @file{configure.in}
403 Automake requires certain variables to be defined and certain macros to
404 be used in the package @file{configure.in}.
406 One such requirement is that @file{configure.in} must define the
407 variables @code{PACKAGE} and @code{VERSION} with @code{AC_SUBST}.
410 @code{PACKAGE} should be the name of the package as it appears when
411 bundled for distribution. For instance, Automake definees
412 @code{PACKAGE} to be @samp{automake}. @code{VERSION} should be the
413 version number of the release that is being developed. We recommend
414 that you make @file{configure.in} the only place in your package where
415 the version number is defined; this makes releases simpler.
417 Automake also requires the use of the macros @code{AC_ARG_PROGRAM}
418 @cvindex AC_ARG_PROGRAM
420 If your package is not a flat distribution, Automake requires the use of
421 @code{AC_PROG_MAKE_SET}.
422 @cvindex AC_PROG_MAKE_SET
424 Automake will also recognize the use of certain macros and tailor the
425 generated @file{Makefile.in} appropriately. Currently recognized macros
426 and their effects are:
429 @item AC_CONFIG_HEADER
430 Automake will generate rules to automatically regenerate the config
432 @cvindex AC_CONFIG_HEADER
435 Automake uses this to determine which files to create.
439 Automake will insert definitions for the variables defined by
440 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
442 @cvindex AC_PATH_XTRA
444 @item AC_CANONICAL_HOST
445 @item AC_CANONICAL_SYSTEM
446 Automake will ensure that @file{config.guess} and @file{config.sub}
448 @cvindex AC_CANONICAL_HOST
449 @cvindex AC_CANONICAL_SYSTEM
452 @item AC_FUNC_GETLOADAVG
454 @item AC_STRUCT_ST_BLOCKS
455 @item fp_FUNC_FNMATCH
456 @item AC_REPLACE_FUNCS
457 Automake will ensure that the appropriate source files are part of the
458 distribution, and will ensure that the appropriate dependencies are
459 generated for these objects. @xref{A Library} for more
461 @cvindex AC_FUNC_ALLOCA
462 @cvindex AC_FUNC_GETLOADAVG
463 @cvindex AC_FUNC_MEMCMP
464 @cvindex AC_STRUCT_ST_BLOCKS
465 @cvindex fp_FUNC_FNMATCH
466 @cvindex AC_REPLACE_FUNCS
468 Automake will also detect statements which put @samp{.o} files into
469 @code{LIBOBJS}, and will treat these additional files in a similar way.
473 This is required if any libraries are built in the package.
474 @cvindex AC_PROG_RANLIB
476 @item AC_PROG_INSTALL
477 @item fp_PROG_INSTALL
478 @code{fp_PROG_INSTALL} is required if any scripts (@pxref{Scripts}) are
479 installed by the package. Otherwise, @code{AC_PROG_INSTALL} is
481 @cvindex AC_PROG_INSTALL
482 @cvindex fp_PROG_INSTALL
484 @item fp_C_PROTOTYPES
485 This is required when using automatic de-ANSI-fication, see @ref{ANSI}.
486 @cvindex fp_C_PROTOTYPES
489 This macro is required for packages which use GNU gettext (FIXME xref).
490 It is distributed with gettext. Automake uses this macro to ensure that
491 the package meets some of gettext's requirements.
492 @cvindex ud_GNU_GETTEXT
495 The @samp{fp_} macros are from @value{Francois} Pinard, and are included
496 with Automake. @code{automake} will tell where the macros can be found
501 @chapter The top-level @file{Makefile.am}
503 In non-flat packages, the top level @file{Makefile.am} must tell
504 Automake which subdirectories are to be built. This is done via the
505 @code{SUBDIRS} variable.
508 The @code{SUBDIRS} macro holds a list of subdirectories in which
509 building of various sorts can occur. Many targets (eg @code{all}) in
510 the generated @file{Makefile} will run both locally and in all specified
511 subdirectories. Note that the directories listed in @code{SUBDIRS} are
512 not required to contain @file{Makefile.am}s; only @file{Makefile}s
513 (after configuration). This allows inclusion of libraries from packages
514 which do not use Automake (such as @code{gettext}).
516 In a deep package, the top-level @file{Makefile.am} is often very short.
517 For instance, here is the @file{Makefile.am} from the textutils
521 SUBDIRS = lib src doc man
522 EXTRA_DIST = @@README_ALPHA@@
525 @code{SUBDIRS} can contain configure substitutions (eg @samp{@@DIRS@@});
526 Automake itself does not actually examine the contents of this variable.
528 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
529 @code{AC_PROG_MAKE_SET}.
533 @chapter Building Programs and Libraries
535 A large part of Automake's functionality is dedicated to making it easy
536 to build C programs and libraries.
539 * A Program:: Building a program
540 * A Library:: Building a library
541 * ANSI:: Automatic de-ANSI-fication
542 * Dependencies:: Automatic dependency tracking
547 @section Building a program
549 In a directory containing source that gets built into a program (as
550 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
551 can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
552 @code{pkglibdir}, or not at all.
560 In this simple case, the resulting @file{Makefile.in} will contain code
561 to generate a program named @code{hello}. The variable
562 @code{hello_SOURCES} is used to specify which source files get built
566 hello_SOURCES = hello.c
569 This causes @file{hello.c} to be compiled into @file{hello.o}, and then
570 linked to produce @file{hello}.
572 If @samp{prog_SOURCES} is needed, but not specified, then it defaults to
573 the single file @file{prog.c}. Id est in the example above, the
574 definition of @code{hello_SOURCES} is actually redundant.
578 Multiple programs can be built in a single directory. Multiple programs
579 can share a single source file. The source file must be listed in each
580 @samp{_SOURCES} definition.
582 Header files listed in a @samp{_SOURCES} definition will be ignored.
583 Lex (@samp{.l}) and yacc (@samp{.y}) files can also be listed; support
584 for these should work but is still preliminary.
585 @c lex & yacc should have a separate section
587 Sometimes it is useful to determine the programs that are to be built at
588 configure time. For instance, GNU @code{cpio} only builts @code{mt} and
589 @code{rmt} under special circumstances.
591 In this case, you must notify @code{Automake} of all the programs that
592 can possibly be built, but at the same time cause the generated
593 @file{Makefile.in} to use the programs specified by @code{configure}.
594 This is done by having @code{configure} substitute values into each
595 @samp{_PROGRAMS} definition, while listing all optionally built programs in
596 @code{EXTRA_PROGRAMS}.
597 @vindex EXTRA_PROGRAMS
599 If you need to link against libraries that are not found by
600 @code{configure}, you can use @code{LDADD} to do so. This variable
601 actually can be used to add any options to the linker command line.
604 Sometimes, multiple programs are built in one directory but do not share
605 the same link-time requirements. In this case, you can use the
606 @samp{@var{prog}_LDADD} variable (where @var{PROG} is the name of the
607 program as it appears in some @samp{_PROGRAMS} variable, and usually
608 written in lowercase) to override the global @code{LDADD}. (If this
609 variable exists for a given program, then that program is not linked
613 For instance, in GNU cpio, @code{pax}, @code{cpio}, and @code{mt} are
614 linked against the library @file{libcpio.a}. However, @code{rmt} is
615 built in the same directory, and has no such link requirement. Also,
616 @code{mt} and @code{rmt} are only built on certain architectures. Here
617 is what cpio's @file{src/Makefile.am} looks like (abridged):
620 bin_PROGRAMS = cpio pax @@MT@@
621 libexec_PROGRAMS = @@RMT@@
622 EXTRA_PROGRAMS = mt rmt
624 LDADD = ../lib/libcpio.a @@INTLLIBS@@
627 cpio_SOURCES = @dots{}
628 pax_SOURCES = @dots{}
630 rmt_SOURCES = @dots{}
635 @section Building a library
637 Building a library is much like building a program. In this case, the
638 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
639 @code{libdir} or @code{pkglibdir}.
641 Each @samp{_LIBRARIES} variable is a list of the base names of
642 libraries to be built. For instance to create a library named
643 @file{libcpio.a}, but not install it, you would write:
646 noinst_LIBRARIES = cpio
649 The sources that go into a library are determined exactly as they are
650 for programs, via the @samp{_SOURCES} variables. Note that programs and
651 libraries share a namespace, so one cannot have a program (@file{lob}) and
652 a library (@file{liblob.a}) with the same name in one directory.
654 Extra objects can be added to a library using the @samp{library_LIBADD}
655 variable. This should be used for objects determined by
656 @code{configure}. Again from cpio:
661 cpio_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
664 Note that Automake explicitly recognizes the use of @code{@@LIBOBJS@@}
665 and @code{@@ALLOCA@@} in the above example, and uses this information,
666 plus the list of @code{LIBOBJS} files derived from @file{configure.in}
667 to automatically include the appropriate source files in the
668 distribution (@pxref{Dist}). These source files are also automatically
669 handled in the dependency-tracking scheme, see @xref{Dependencies}.
673 @section Automatic de-ANSI-fication
675 Although the GNU standards prohibit it, some GNU programs are written in
676 ANSI C; see FIXME. This is possible because each source file can be
677 ``de-ANSI-fied'' before the actual compilation takes place.
679 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
680 @vindex AUTOMAKE_OPTIONS
681 (@ref{Options}) contains the option @code{ansi2knr}
683 then code to handle de-ANSI-fication is inserted into the generated
686 This causes each source file to be treated as ANSI C. If an ANSI C
687 compiler is available, it is used.
689 This support requires the source files @file{ansi2knr.c} and
690 @file{ansi2knr.1} to be in the same directory as the ANSI C source;
691 these files are distributed with Automake.
692 Also, the package @file{configure.in} must call the macro
693 @code{fp_C_PROTOTYPES}.
694 @cvindex fp_C_PROTOTYPES
698 @section Automatic dependency tracking
700 As a developer it is often painful to continually update the
701 @file{Makefile.in} whenever the include-file dependencies change in a
702 project. @code{automake} supplies a way to automatically track
703 dependency changes, and distribute the dependencies in the generated
706 Currently this support requires the use of GNU @code{make} and
707 @code{gcc}. It might become possible in the future to supply a
708 different dependency generating program, if there is enough demand.
710 This mode is enabled by default if any C program or library is defined
711 in the current directory.
713 When you decide to make a distribution, the @code{dist} target will
715 re-run @code{automake} with the @samp{--include-deps} option. This
717 causes the previously generated dependencies to be inserted into the
718 generated @file{Makefile.in}, and thus into the distribution.
719 @samp{--include-deps} also turns off inclusion of the dependency
722 This mode can be suppressed by putting @code{no-dependencies} in the
723 variable @code{AUTOMAKE_OPTIONS}.
724 @vindex AUTOMAKE_OPTIONS
725 @opindex no-dependencies
729 @chapter Other Derived Objects
731 Automake can handle derived objects which are not C programs. Sometimes
732 the support for actually building such objects must be explicitly
733 supplied, but Automake will still automatically handle installation and
737 * Scripts:: Executable scripts
738 * Headers:: Header files
739 * Data:: Architecture-independent data files
744 @section Executable Scripts
746 It is possible to define and install programs which are scripts. Such
747 programs are listed using the @samp{SCRIPTS} primary name.
748 @code{automake} doesn't define any dependencies for scripts; the
749 @file{Makefile.am} should include the appropriate rules.
752 @code{automake} does not assume that scripts are derived objects; such
753 objects are must be deleted by hand; see @ref{Clean} for more
756 @code{automake} itself is a script that is generated at configure time
757 from @file{automake.in}. Here is how this is handled:
760 bin_SCRIPTS = automake
763 Since @code{automake} appears in the @code{AC_OUTPUT} macro,
764 dependencies for it are automatically generated.
766 Script objects can be installed in @code{bindir}, @code{sbindir},
767 @code{libexecdir}, or @code{pkgdatadir}.
771 @section Header files
773 Header files are specified by the @samp{HEADERS} family of variables.
774 Generally header files are not installed, so the @code{noinst_HEADERS}
775 variable will be the most used.
778 All header files must be listed somewhere; missing ones will not appear
779 in the distribution. Often it is most convenient to list uninstalled
780 headers with the rest of the sources for a program. @xref{A Program}.
782 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
783 @code{pkgincludedir}.
787 @section Architecture-independent data files
789 Automake supports the installation of miscellaneous data files using the
790 @samp{DATA} family of variables.
793 Such data can be installed in the directories @code{datadir},
794 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
797 All such data files are included in the distribution.
799 Here is how @code{autoconf} installs its auxiliary data files:
802 pkgdata_DATA = clean-kr.am clean.am compile-kr.am compile-vars.am \
803 compile.am data.am depend.am dist-subd-top.am dist-subd-vars.am \
804 dist-subd.am dist-vars.am dist.am footer.am header-vars.am header.am \
805 libscripts.am libprograms.am libraries-vars.am libraries.am library.am \
806 mans-vars.am mans.am packagedata.am program.am programs.am remake-hdr.am \
807 remake-subd.am remake.am scripts.am subdirs.am tags.am tags-subd.am \
808 texinfos-vars.am texinfos.am hack-make.sed nl-remove.sed
813 @chapter Building documentation
815 Currently Automake provides support for Texinfo and man pages.
819 * Man pages:: Man pages
826 If the current directory contains Texinfo source, you must declare it
827 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
828 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
829 here. Note that any Texinfo source file must end in the @samp{.texi}
830 extension (@samp{.texinfo} won't work).
832 @vindex info_TEXINFOS
834 If the @samp{.texi} file @code{@@include}s @file{version.texi}, then that
835 file will be automatically generated. @file{version.texi} defines three
836 Texinfo macros you can reference: @code{EDITION}, @code{VERSION}, and
837 @code{UPDATED}. The first two hold the version number of your package
838 (but are kept separate for clarity); the last is the date the primary
839 file was last modified. The @file{version.texi} support requires the
840 @code{mdate-sh} program; this program is supplied with Automake.
842 Sometimes an info file actually depends on more than one @samp{.texi}
843 file. For instance, in the @code{xdvik} distribution,
844 @file{kpathsea.texi} includes the files @file{install.texi},
845 @file{copying.texi}, and @file{freedom.texi}. You can tell Automake
846 about these dependencies using the @samp{texi_TEXINFOS} variable. Here
847 is how @code{xdvik} could do it:
852 info_TEXINFOS = kpathsea.texi
853 kpathsea_TEXINFOS = install.texi copying.texi freedom.texi
856 Automake will warn if a directory containing Texinfo source does not
857 also contain the file @file{texinfo.tex}. This file is supplied with
860 Automake generates an @code{install-info} target; some people apparently
867 A package can also include man pages. (Though see the GNU standards on
868 this matter, @ref{Man Pages, , , standards.info, The GNU Coding
869 Standards}.) Man pages are declared using the @samp{MANS} primary.
870 Generally the @code{man_MANS} macro is used. Man pages are
871 automatically installed in the correct subdirectory of @code{mandir},
872 based on the file extension.
876 @c Use @samp{make install} per documentation: (texi.info)code.
877 By default, man pages are installed by @samp{make install}. However,
878 since the GNU project does not require man pages, many maintainers do
879 not expend effort to keep the man pages up to date. In these cases, the
880 @code{no-installman} option will prevent the man pages from being
881 installed by default. The user can still explicitly install them via
882 @samp{make install-man}.
883 @opindex no-installman
886 Here is how the documentation is handled in GNU @code{cpio} (which
887 includes both Texinfo documentation and man pages):
890 info_TEXINFOS = cpio.texi
891 man_MANS = cpio.1 mt.1
894 Texinfo source, info pages and man pages are all considered to be source
895 for the purposes of making a distribution.
899 @chapter What Gets Installed
901 Naturally, Automake handles the details of actually installing your
902 program once it has been built. All @code{PROGRAMS}, @code{SCRIPTS},
903 @code{LIBRARIES}, @code{DATA} and @code{HEADERS} are automatically
904 installed in the appropriate places.
906 Automake also handles installing any specified info and man pages.
908 Automake generates separate @code{install-data} and @code{install-exec}
909 targets, in case the installer is installing on multiple machines which
910 share directory structure -- these targets allow the machine-independent
911 parts to be installed only once. The @code{install} target depends on
912 both of these targets.
913 @trindex install-data
914 @trindex install-exec
917 Automake also generates an @code{uninstall} target, and an
918 @code{installdirs} target.
922 It is possible to extend this mechanism by defining an
923 @code{install-exec-local} or @code{install-data-local} target. If these
924 targets exist, they will be run at @samp{make install} time.
925 @trindex install-exec-local
926 @trindex install-data-local
930 @chapter What Gets Cleaned
932 The GNU Makefile Standards specify a number of different clean rules.
934 Generally the files that can cleaned are determined automatically by
935 Automake. Of course, Automake also recognizes some variables that can
936 be defined to specify additional files to clean. These variables are
937 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
938 @code{MAINTAINERCLEANFILES}.
939 @vindex MOSTLYCLEANFILES
941 @vindex DISTCLEANFILES
942 @vindex MAINTAINERCLEANFILES
944 In Automake, the @code{automake} program is not automatically removed,
945 because it is an executable script. So this code in @file{Makefile.am}
946 causes it to be removed by @samp{make clean}:
949 CLEANFILES = automake
954 @chapter What Goes in a Distribution
956 The @code{dist} target in the generated @file{Makefile.in} can be used
957 to generate a gzip'd @code{tar} file for distribution. The tar file is
958 named based on the @var{PACKAGE} and @var{VERSION} variables.
963 For the most part, the files to distribute are automatically found by
964 Automake: all source files are automatically included in a distribution,
965 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
966 has a built-in list of commonly used files which, if present in the
967 current directory, are automatically included. This list is printed by
968 @samp{automake --help}. Also, files which are read by @code{configure}
969 (ie, the source files corresponding to the files specified in the
970 @code{AC_OUTPUT} invocation) are automatically distributed.
972 Still, sometimes there are files which must be distributed, but which
973 are not covered in the automatic rules. These files should be listed in
974 the @code{EXTRA_DIST} variable.
979 @chapter Support for test suites
981 Automake supports a simple form of test suite. If the variable
982 @code{TESTS} is defined, its value is taken to be a list of programs to
983 run in order to do the testing. The programs can either be derived
984 objects or source objects; the generated rule will look both in
985 @var{srcdir} and @file{.}.
987 The testing is done via @samp{make check}. The number of failures will
988 be printed at the end of the run.
990 In the future there will be some support for test suites which use
995 @chapter Changing Automake's Behavior
997 Various features of Automake can be controlled by options in the
998 @file{Makefile.am}. Such options are listed in a special variable named
999 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
1000 @vindex AUTOMAKE_OPTIONS
1005 @itemx @code{foreign}
1006 The same as the corresponding @samp{--strictness} option.
1008 @item @code{no-installman}
1009 The generated @file{Makefile.in} will not cause man pages to be
1010 installed by default. However, an @code{install-man} target will still
1011 be available for optional installation.
1013 @item @code{ansi2knr}
1014 Turn on automatic de-ANSI-fication.
1016 @item @code{dist-shar}
1017 Generate a @code{dist-shar} target as well as the ordinary @code{dist}
1020 @item @code{no-dependencies}
1021 This is similar to using @samp{--include-deps} on the command line, but
1022 is useful for those situations where you don't have the necessary bits
1023 to make automatic dependency tracking work @xref{Dependencies}. In this
1024 case the effect is to effectively disable automatic dependency tracking.
1027 A version number (eg @samp{0.30}) can be specified. If Automake is not
1028 newer than the version specified, creation of the @file{Makefile.in}
1032 Unrecognized options are diagnosed by @code{automake}.
1036 @chapter Miscellaneous Rules
1038 There are a few rules and variables that didn't fit anywhere else.
1041 * Tags:: Interfacing to etags and mkid
1042 * Suffixes:: Handling new file extensions
1043 * Built:: Built sources
1048 @section Interfacing to @code{etags}
1050 @code{automake} will generate rules to generate @file{TAGS} files for
1051 use with GNU Emacs under some circumstances.
1053 If any C source code or headers are present, then a @code{tags} target
1054 will be generated for the directory.
1057 At the topmost directory of a multi-directory package, a @code{tags}
1058 target file will be generated which, when run, will generate a
1059 @file{TAGS} file that includes by reference all @file{TAGS} files from
1062 Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
1063 will be generated. This variable is intended for use in directories
1064 which contain taggable source that @code{etags} does not understand.
1066 Here is how Automake generates tags for its source, and for nodes in its
1070 ETAGS_ARGS = automake.in --lang=none \
1071 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
1074 Automake will also generate an @code{ID} target which will run
1075 @code{mkid} on the source. This is only supported on a
1076 directory-by-directory basis.
1081 @section Handling new file extensions
1083 It is sometimes useful to introduce a new implicit rule to handle a file
1084 type that Automake does not know about. If this is done, you must
1085 notify GNU Make of the new suffixes. This can be done by putting a list
1086 of new suffixes in the @code{SUFFIXES} variable.
1091 @section Built sources
1097 @chapter When Automake Isn't Enough
1099 Sometimes @code{automake} isn't enough. Then you just lose.
1101 Actually, @code{automake}s implicit copying semantics means that many
1102 problems can be worked around by simply adding some @code{make} targets
1103 and rules to @file{Makefile.in}. @code{automake} will ignore these
1106 There are some caveats to doing this. Although you can overload a
1107 target already used by @code{automake}, it is often inadvisable,
1108 particularly in the topmost directory of a non-flat package. However,
1109 various useful targets have a @samp{-local} version you can specify in your
1110 @file{Makefile.in}. Automake will supplement the standard target with
1111 these user-supplied targets.
1113 The targets that support a local version are @code{all}, @code{info},
1114 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec}, and
1120 @trindex install-data
1121 @trindex install-exec
1124 For instance, here is how to install a file in @file{/etc}:
1128 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
1131 @c FIXME should include discussion of variables you can use in these
1136 @chapter Distributing @file{Makefile.in}s
1138 Automake places no restrictions on the distribution of the resulting
1139 @file{Makefile.in}s. We still encourage software authors to distribute
1140 their work under terms like those of the GPL, but doing so is not
1141 required to use Automake.
1143 Some of the files that can be automatically installed via the
1144 @samp{--add-missing} switch do fall under the GPL; examine each file
1149 @chapter Some example packages
1151 Here are some examples of how Automake can be used.
1154 * Hello:: The simplest GNU program
1155 * Tricky:: A trickier example
1156 * Automake:: Automake's own use
1157 * Textutils:: A deep hierarchy
1161 @section The simplest GNU program
1163 @code{hello} is renowned for its classic simplicity and versatility.
1164 What better place to begin a tour? The below shows what could be used
1165 as the Hello distribution's @file{Makefile.am}.
1168 bin_PROGRAMS = hello
1169 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h
1170 hello_LDADD = @@ALLOCA@@
1171 info_TEXINFOS = hello.texi
1172 hello_TEXINFOS = gpl.texi
1174 EXTRA_DIST = testdata
1177 @@echo expect no output from diff
1179 diff -c $(srcdir)/testdata test.out
1183 Of course, Automake also requires some minor changes to
1184 @file{configure.in}. The new @file{configure.in} would read:
1187 dnl Process this file with autoconf to produce a configure script.
1197 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h)
1202 If Hello were really going to use Automake, the @file{version.c} file
1203 would probably be deleted, or changed so as to be automatically
1208 @section A tricker example
1210 Here is another, trickier example. It shows how to generate two
1211 programs (@code{ctags} and @code{etags}) from the same source file
1212 (@file{etags.c}). The difficult part is that each compilation of
1213 @file{etags.c} requires different @code{cpp} flags.
1216 bin_PROGRAMS = etags ctags
1218 ctags_LDADD = ctags.o
1221 $(COMPILE) -DETAGS_REGEXPS etags.c
1224 $(COMPILE) -DCTAGS -o ctags.o etags.c
1227 Note that @code{ctags_SOURCES} is defined to be empty -- that way no
1228 implicit value is substituted. The implicit value, however, is used to
1229 generate @code{etags} from @file{etags.o}.
1233 @section Automake uses itself
1235 Automake, of course, uses itself to generate its @file{Makefile.in}.
1236 Since Automake is a shallow package, it has more than one
1237 @file{Makefile.am}. Here is the top-level @file{Makefile.am}:
1240 ## Process this file with automake to create Makefile.in
1242 AUTOMAKE_OPTIONS = gnits
1243 MAINT_CHARSET = latin1
1248 bin_SCRIPTS = automake
1249 info_TEXINFOS = automake.texi
1251 pkgdata_DATA = clean-kr.am clean.am compile-kr.am compile-vars.am \
1252 compile.am data.am depend.am \
1253 dist-vars.am footer.am header.am header-vars.am \
1254 kr-vars.am libraries-vars.am \
1255 libraries.am library.am mans-vars.am \
1256 program.am programs.am remake-hdr.am \
1257 remake-subd.am remake.am scripts.am subdirs.am tags.am tags-subd.am \
1259 texi-version.am texinfos-vars.am texinfos.am \
1260 libraries-clean.am programs-clean.am data-clean.am \
1261 COPYING INSTALL texinfo.tex \
1262 ansi2knr.c ansi2knr.1 \
1265 ## These must all be executable when installed.
1266 pkgdata_SCRIPTS = config.guess config.sub install-sh mdate-sh mkinstalldirs
1268 CLEANFILES = automake
1270 # The following requires a fixed version of the Emacs 19.30 etags.
1271 ETAGS_ARGS = automake.in --lang=none \
1272 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
1274 ## `test -x' is not portable. So we use Perl instead. If Perl
1275 ## doesn't exist, then this test is meaningless anyway.
1276 # Check to make sure some installed files are executable.
1278 $(PERL) -e "exit ! -x '$(pkgdatadir)/config.guess';"
1279 $(PERL) -e "exit ! -x '$(pkgdatadir)/config.sub';"
1280 $(PERL) -e "exit ! -x '$(pkgdatadir)/install-sh';"
1281 $(PERL) -e "exit ! -x '$(pkgdatadir)/mdate-sh';"
1282 $(PERL) -e "exit ! -x '$(pkgdatadir)/mkinstalldirs';"
1284 # Some simple checks:
1285 # * syntax check with perl4 and perl5.
1286 # * make sure the scripts don't use 'true'
1287 # * expect no instances of '$@{...@}'
1288 # These are only really guaranteed to work on my machine.
1289 maintainer-check: automake check
1290 $(PERL) -c -w automake
1291 @@if grep '^[^#].*true' $(srcdir)/[a-z]*.am; then \
1292 echo "can't use 'true' in GNU Makefile" 1>&2; \
1295 @@if test `fgrep '$$@{' $(srcdir)/[a-z]*.am | wc -l` -ne 0; then \
1296 echo "found too many uses of '\$$@{'" 1>&2; \
1299 if $(SHELL) -c 'perl4.036 -v' >/dev/null 2>&1; then \
1300 perl4.036 -c -w automake; \
1303 # Tag before making distribution. Also, don't make a distribution if
1304 # checks fail. Also, make sure the NEWS file is up-to-date.
1305 cvs-dist: maintainer-check
1306 @@if sed 1q NEWS | grep -e "$(VERSION)" > /dev/null; then :; else \
1307 echo "NEWS not updated; not releasing" 1>&2; \
1310 cvs tag `echo "Release-$(VERSION)" | sed 's/\./-/g'`
1314 As you can see, Automake defines many of its own rules, to make the
1315 maintainer's job easier. For instance the @code{cvs-dist} rule
1316 automatically tags the current version in the CVS repository, and then
1317 makes a standard distribution.
1319 Automake consists primarily of one program, @code{automake}, and a
1320 number of auxiliary scripts. Automake also installs a number of
1321 programs which are possibly installed via the @samp{--add-missing}
1322 option; these scripts are listed in the @code{pkgdata_SCRIPTS} variable.
1324 Automake also has a @file{tests} subdirectory, as indicated in the
1325 @code{SUBDIRS} variable above. Here is @file{tests/Makefile.am}:
1328 ## Process this file with automake to create Makefile.in
1330 AUTOMAKE_OPTIONS = gnits
1332 TESTS = mdate.test vtexi.test acoutput.test instexec.test checkall.test \
1333 acoutnoq.test acouttbs.test libobj.test proginst.test acoutqnl.test \
1334 confincl.test spelling.test prefix.test badprog.test depend.test
1339 This is where all the tests are really run. @file{defs} is an
1340 initialization file used by each test script; it is explicitly mentioned
1341 because @code{automake} has no way of automatically finding it.
1345 @section A deep hierarchy
1347 The GNU textutils are a collection of programs for manipulating text
1348 files. They are distributed as a deep package. The textutils have only
1349 recently been modified to use Automake; the examples come from a
1352 Here is the top-level @file{Makefile.am}:
1355 SUBDIRS = lib src doc man
1358 In the @file{lib} directory, a library is built which is used by each
1359 textutil. Here is @file{lib/Makefile.am}:
1362 noinst_LIBRARIES = tu
1364 EXTRA_DIST = rx.c regex.c
1366 tu_SOURCES = error.h getline.h getopt.h linebuffer.h \
1367 long-options.h md5.h regex.h rx.h xstrtod.h xstrtol.h xstrtoul.h \
1368 error.c full-write.c getline.c getopt.c getopt1.c \
1369 linebuffer.c long-options.c md5.c memchr.c safe-read.c \
1370 xmalloc.c xstrtod.c xstrtol.c xstrtoul.c
1372 tu_LIBADD = @@REGEXOBJ@@ @@LIBOBJS@@ @@ALLOCA@@
1375 The @file{src} directory contains the source for all the textutils -- 23
1376 programs in all. The @file{Makefile.am} for this directory also
1377 includes some simple checking code, and constructs a @file{version.c}
1381 bin_PROGRAMS = cat cksum comm csplit cut expand fmt fold head join md5sum \
1382 nl od paste pr sort split sum tac tail tr unexpand uniq wc
1384 noinst_HEADERS = system.h version.h
1385 DISTCLEANFILES = stamp-v version.c
1387 INCLUDES = -I$(top_srcdir)/lib
1389 LDADD = version.o ../lib/libtu.a
1391 $(PROGRAMS): version.o ../lib/libtu.a
1393 AUTOMAKE_OPTIONS = ansi2knr
1398 echo '#include <config.h>' > t-version.c
1399 echo '#include "version.h"' >> t-version.c
1400 echo 'const char *version_string = "'GNU @@PACKAGE@@ @@VERSION@@'";' \
1402 if cmp -s version.c t-version.c; then \
1405 mv t-version.c version.c; \
1407 echo timestamp > $@@
1414 --string="message digest" \
1415 --string="abcdefghijklmnopqrstuvwxyz" \
1416 --string="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" \
1417 --string="12345678901234567890123456789012345678901234567890123456789012345678901234567890" \
1418 | diff -c $(srcdir)/md5-test.rfc -
1421 The @file{doc} directory builds the info documentation for the
1425 info_TEXINFOS = textutils.texi
1428 And, last, the @file{man} directory installs the man pages for all the
1432 man_MANS = cat.1 cksum.1 comm.1 csplit.1 cut.1 expand.1 fmt.1 fold.1 head.1 \
1433 join.1 md5sum.1 nl.1 od.1 paste.1 pr.1 sort.1 split.1 sum.1 tac.1 tail.1 \
1434 tr.1 unexpand.1 uniq.1 wc.1
1437 You can now see how easy it is to handle even a largish project using
1442 @chapter Some ideas for the future
1444 Here are some things that might happen in the future:
1451 The output will be cleaned up. For instance, only variables which are
1452 actually used will appear in the generated @file{Makefile.in}.
1455 There will be support for automatically recoding a distribution. The
1456 intent is to allow a maintainer to use whatever character set is most
1457 convenient locally, but for all distributions to be Unicode or
1458 @w{ISO 10646} with the UTF-8 encoding.
1463 @unnumbered Index of Variables
1468 @node Configure variables
1469 @unnumbered Index of Configure Variables and Macros
1475 @unnumbered Index of Targets