1 \input texinfo @c -*-texinfo-*-
3 @setfilename automake.info
10 @dircategory GNU admin
12 * automake: (automake). Making Makefile.in's
15 @dircategory Individual utilities
17 * aclocal: (automake)Invoking aclocal. Generating aclocal.m4
21 This file documents GNU automake @value{VERSION}
23 Copyright (C) 1995, 96, 97 Free Software Foundation, Inc.
25 Permission is granted to make and distribute verbatim copies of
26 this manual provided the copyright notice and this permission notice
27 are preserved on all copies.
30 Permission is granted to process this file through TeX and print the
31 results, provided the printed document carries copying permission
32 notice identical to this one except for the removal of this paragraph
36 Permission is granted to copy and distribute modified versions of this
37 manual under the conditions for verbatim copying, provided that the entire
38 resulting derived work is distributed under the terms of a permission
39 notice identical to this one.
41 Permission is granted to copy and distribute translations of this manual
42 into another language, under the above conditions for modified versions,
43 except that this permission notice may be stated in a translation approved
50 @subtitle For version @value{VERSION}, @value{UPDATED}
51 @author David MacKenzie and Tom Tromey
54 @vskip 0pt plus 1filll
55 Copyright @copyright{} 1995, 96 Free Software Foundation, Inc.
57 This is the first edition of the GNU Automake documentation,@*
58 and is consistent with GNU Automake @value{VERSION}.@*
60 Published by the Free Software Foundation @*
61 59 Temple Place - Suite 330, @*
62 Boston, MA 02111-1307 USA @*
64 Permission is granted to make and distribute verbatim copies of
65 this manual provided the copyright notice and this permission notice
66 are preserved on all copies.
68 Permission is granted to copy and distribute modified versions of this
69 manual under the conditions for verbatim copying, provided that the entire
70 resulting derived work is distributed under the terms of a permission
71 notice identical to this one.
73 Permission is granted to copy and distribute translations of this manual
74 into another language, under the above conditions for modified versions,
75 except that this permission notice may be stated in a translation
76 approved by the Free Software Foundation.
79 @c Define an index of configure variables.
81 @c Define an index of options.
83 @c Define an index of targets.
86 @c Put everything in one index (arbitrarily chosen to be the concept index).
93 @node Top, Introduction, (dir), (dir)
94 @comment node-name, next, previous, up
97 This file documents the GNU Automake package for creating GNU
98 Standards-compliant Makefiles from template files. This edition
99 documents version @value{VERSION}.
102 * Introduction:: Automake's purpose
103 * Generalities:: General ideas
104 * Examples:: Some example packages
105 * Invoking Automake:: Creating a Makefile.in
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 * Conditionals:: Conditionals
119 * Gnits:: The effect of @code{--gnu} and @code{--gnits}
120 * Cygnus:: The effect of @code{--cygnus}
121 * Extending:: Extending Automake
122 * Distributing:: Distributing the Makefile.in
123 * Future:: Some ideas for the future
124 * Index:: General index
126 --- The Detailed Node Listing ---
130 * General Operation:: General operation of Automake
131 * Depth:: The kinds of packages
132 * Strictness:: Standards conformance checking
133 * Uniform:: The Uniform Naming Scheme
134 * Canonicalization:: How derived variables are named
136 Some example packages
138 * Complete:: A simple example, start to finish
139 * Hello:: A classic program
140 * etags:: Building etags and ctags
142 Scanning @file{configure.in}
144 * Requirements:: Configuration requirements
145 * Optional:: Other things Automake recognizes
146 * Invoking aclocal:: Auto-generating aclocal.m4
147 * Macros:: Autoconf macros supplied with Automake
148 * Extending aclocal:: Writing your own aclocal macros
150 Building Programs and Libraries
152 * A Program:: Building a program
153 * A Library:: Building a library
154 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
155 * A Shared Library:: Building a Libtool library
156 * Program variables:: Variables used when building a program
157 * Yacc and Lex:: Yacc and Lex support
159 * ANSI:: Automatic de-ANSI-fication
160 * Dependencies:: Automatic dependency tracking
162 Other Derived Objects
164 * Scripts:: Executable scripts
165 * Headers:: Header files
166 * Data:: Architecture-independent data files
167 * Sources:: Derived sources
171 * Emacs Lisp:: Emacs Lisp
176 Building documentation
179 * Man pages:: Man pages
183 * Tags:: Interfacing to etags and mkid
184 * Suffixes:: Handling new file extensions
189 @node Introduction, Generalities, Top, Top
190 @chapter Introduction
192 Automake is a tool for automatically generating @file{Makefile.in}s from
193 files called @file{Makefile.am}. Each @file{Makefile.am} is basically a
194 series of @code{make} macro definitions (with rules being thrown in
195 occasionally). The generated @file{Makefile.in}s are compliant with the
196 GNU Makefile standards.
198 The GNU Makefile Standards Document
199 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
200 is long, complicated, and subject to change. The goal of Automake is to
201 remove the burden of Makefile maintenance from the back of the
202 individual GNU maintainer (and put it on the back of the Automake
205 The typical Automake input files is simply a series of macro
206 definitions. Each such file is processed to create a
207 @file{Makefile.in}. There should generally be one @file{Makefile.am}
208 per directory of a project.
210 Automake does constrain a project in certain ways; for instance it
211 assumes that the project uses Autoconf
212 (@pxref{Top, , The Autoconf Manual, autoconf, The Autoconf Manual}),
213 and enforces certain restrictions on the @file{configure.in} contents.
215 Automake requires @code{perl} in order to generate the
216 @file{Makefile.in}s. However, the distributions created by Automake are
217 fully GNU standards-compliant, and do not require @code{perl} in order
220 Mail suggestions and bug reports for Automake to
221 @email{automake-bugs@@gnu.ai.mit.edu}.
224 @node Generalities, Examples, Introduction, Top
225 @chapter General ideas
227 There are a few basic ideas that will help understand how Automake
231 * General Operation:: General operation of Automake
232 * Depth:: The kinds of packages
233 * Strictness:: Standards conformance checking
234 * Uniform:: The Uniform Naming Scheme
235 * Canonicalization:: How derived variables are named
238 @node General Operation, Depth, Generalities, Generalities
239 @section General Operation
241 Automake works by reading a @file{Makefile.am} and generating a
242 @file{Makefile.in}. Certain macros and targets defined in the
243 @file{Makefile.am} instruct automake to generate more specialized code;
244 for instances a @samp{bin_PROGRAMS} macro definition will cause targets
245 for compiling and linking to be generated.
247 The macro definitions and targets in the @file{Makefile.am} are copied
248 into the generated file. This allows you to add arbitrary code into the
249 generated @file{Makefile.in}. For instance the Automake distribution
250 includes a non-standard @code{cvs-dist} target, which the Automake
251 maintainer uses to make distributions from his source control system.
253 Note that GNU make extensions are not recognized by Automake. Using
254 such extensions in a @file{Makefile.am} will lead to errors or confusing
257 Automake tries to group comments with adjoining targets (or variable
258 definitions) in an intelligent way.
260 A target defined in @file{Makefile.am} generally overrides any such
261 target of a similar name that would be automatically generated by
262 @code{automake}. Although this is a supported feature, it is generally
263 best to avoid making use of it, as sometimes the generated rules are
266 Similarly, a variable defined in @file{Makefile.am} will override any
267 definition of the variable that @code{automake} would ordinarily create.
268 This feature is more often useful than the ability to override a target
269 definition. Be warned that many of the variables generated by
270 @code{automake} are considered to be for internal use only, and their
271 names might change in future releases.
273 When examining a variable definition, Automake will recursively examine
274 variables referenced in the definition. E.g., if Automake is looking at
275 the content of @samp{foo_SOURCES} in this snippet
279 foo_SOURCES = c.c $(xs)
282 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
283 contents of @samp{foo_SOURCES}.
285 Automake also allows a form of comment which is @emph{not} copied into
286 the output; all lines beginning with @samp{##} are completely ignored by
289 It is customary to make the first line of @file{Makefile.am} read:
292 ## Process this file with automake to produce Makefile.in
295 @c FIXME discuss putting a copyright into Makefile.am here? I would but
296 @c I don't know quite what to say.
298 @c FIXME document customary ordering of Makefile.am here!
302 @node Depth, Strictness, General Operation, Generalities
304 @code{automake} supports three kinds of directory hierarchy: ``flat'',
305 ``shallow'', and ``deep''.
307 A @dfn{flat} package is one in which all the files are in a single
308 directory. The @file{Makefile.am} for such a package by definition
309 lacks a @code{SUBDIRS} macro. An example of such a package is
313 A @dfn{deep} package is one in which all the source lies in
314 subdirectories; the top level directory contains mainly configuration
315 information. GNU cpio is a good example of such a package, as is GNU
316 @code{tar}. The top level @file{Makefile.am} for a deep package will
317 contain a @code{SUBDIRS} macro, but no other macros to define objects
320 A @dfn{shallow} package is one in which the primary source resides in
321 the top-level directory, while various parts (typically libraries)
322 reside in subdirectories. Automake is one such package (as is GNU
323 @code{make}, which does not currently use @code{automake}).
326 @node Strictness, Uniform, Depth, Generalities
328 While Automake is intended to be used by maintainers of GNU packages, it
329 does make some effort to accommodate those who wish to use it, but do
330 not want to use all the GNU conventions.
332 To this end, Automake supports three levels of @dfn{strictness}---the
333 strictness indicating how stringently Automake should check standards
336 The valid strictness levels are:
340 Automake will check for only those things which are absolutely
341 required for proper operations. For instance, whereas GNU standards
342 dictate the existence of a @file{NEWS} file, it will not be required in
343 this mode. The name comes from the fact that Automake is intended to be
344 used for GNU programs; these relaxed rules are not the standard mode of
348 Automake will check---as much as possible---for compliance to the GNU
349 standards for packages. This is the default.
352 Automake will check for compliance to the as-yet-unwritten Gnits
353 standards. These are based on the GNU standards, but are even more
354 detailed. Unless you are a Gnits standards contributor, it is
355 recommended that you avoid this option until such time as the Gnits
356 standard is actually published.
359 For more information on the precise implications of the strictness
360 level, see @xref{Gnits}.
363 @node Uniform, Canonicalization, Strictness, Generalities
364 @section The Uniform Naming Scheme
365 Automake variables generally follow a uniform naming scheme that makes
366 it easy to decide how programs (and other derived objects) are built,
367 and how they are installed. This scheme also supports @code{configure}
368 time determination of what should be built.
370 At @code{make} time, certain variables are used to determine which
371 objects are to be built. These variables are called @dfn{primary}
372 variables. For instance, the primary variable @code{PROGRAMS} holds a
373 list of programs which are to be compiled and linked.
376 A different set of variables is used to decide where the built objects
377 should be installed. These variables are named after the primary
378 variables, but have a prefix indicating which standard directory should
379 be used as the installation directory. The standard directory names are
380 given in the GNU standards
381 (@pxref{Directory Variables, , , standards, The GNU Coding
383 Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
384 and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
385 versions, but with @samp{@@PACKAGE@@} appended. For instance,
386 @code{pkglibdir} is defined as @code{$(datadir)/@@PACKAGE@@}.
389 For each primary, there is one additional variable named by prepending
390 @samp{EXTRA_} to the primary name. This variable is used to list
391 objects which may or may not be built, depending on what
392 @code{configure} decides. This variable is required because Automake
393 must statically know the entire list of objects to be built in order to
394 generate a @file{Makefile.in} that will work in all cases.
396 For instance, @code{cpio} decides at configure time which programs are
397 built. Some of the programs are installed in @code{bindir}, and some
398 are installed in @code{sbindir}:
401 EXTRA_PROGRAMS = mt rmt
402 bin_PROGRAMS = cpio pax
403 sbin_PROGRAMS = @@PROGRAMS@@
406 Defining a primary variable without a prefix (eg @code{PROGRAMS}) is an
409 Note that the common @samp{dir} suffix is left off when constructing the
410 variable names; thus one writes @samp{bin_PROGRAMS} and not
411 @samp{bindir_PROGRAMS}.
413 Not every sort of object can be installed in every directory. Automake
414 will flag those attempts it finds in error. Automake will also diagnose
415 obvious misspellings in directory names.
417 Sometimes the standard directories---even as augmented by Automake---
418 are not enough. In particular it is sometimes useful, for clarity, to
419 install objects in a subdirectory of some predefined directory. To this
420 end, Automake allows you to extend the list of possible installation
421 directories. A given prefix (eg @samp{zar}) is valid if a variable of
422 the same name with @samp{dir} appended is defined (eg @samp{zardir}).
424 For instance, until HTML support is part of Automake, you could use this
425 to install raw HTML documentation:
428 htmldir = $(prefix)/html
429 html_DATA = automake.html
432 The special prefix @samp{noinst} indicates that the objects in question
433 should not be installed at all.
435 The special prefix @samp{check} indicates that the objects in question
436 should not be built until the @code{make check} command is run.
438 Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
439 @samp{LISP}, @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS},
451 @node Canonicalization, , Uniform, Generalities
452 @section How derived variables are named
454 Sometimes a Makefile variable name is derived from some text the user
455 supplies. For instance program names are rewritten into Makefile macro
456 names. Automake canonicalizes this text, so that it does not have to
457 follow Makefile variable naming rules. All characters in the name
458 except for letters, numbers, and the underscore are turned into
459 underscores when making macro references. E.g., if your program is named
460 @code{sniff-glue}, the derived variable name would be
461 @code{sniff_glue_SOURCES}, not @code{sniff-glue_SOURCES}.
464 @node Examples, Invoking Automake, Generalities, Top
465 @chapter Some example packages
468 * Complete:: A simple example, start to finish
469 * Hello:: A classic program
470 * etags:: Building etags and ctags
473 @node Complete, Hello, Examples, Examples
474 @section A simple example, start to finish
476 Let's suppose you just finished writing @code{zardoz}, a program to make
477 your head float from vortex to vortex. You've been using
478 @code{autoconf} to provide a portability framework, but your
479 @file{Makefile.in}s have been ad-hoc. You want to make them
480 bulletproof, so you turn to @code{automake}.
482 The first step is to update your @file{configure.in} to include the
483 commands that @code{automake} needs. The simplest way to do this is to
484 add an @code{AM_INIT_AUTOMAKE} call near the beginning:
487 AM_INIT_AUTOMAKE(zardoz, 1.0)
490 Since your program doesn't have any complicating factors (e.g., it
491 doesn't use @code{gettext}, it doesn't want to build a shared library),
492 you're done with this part. That was easy!
494 Now you must regenerate @file{configure}. But to do that, you'll need
495 to tell @code{autoconf} how to find the new macro you've used. The
496 easiest way to do this is to use the @code{aclocal} program to generate
497 your @file{aclocal.m4} for you. But wait... you already have an
498 @file{aclocal.m4}, because you had to write some hairy macros for your
499 program. @code{aclocal} lets you put your own macros into
500 @file{acinclude.m4}, so simply rename and then run:
503 mv aclocal.m4 acinclude.m4
508 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
509 @code{zardoz} is a user program, so you want to install it where the
510 rest of the user programs go. @code{zardoz} also has some Texinfo
511 documentation. Your @file{configure.in} script uses
512 @code{AC_REPLACE_FUNCS}, so you need to link against @samp{@@LIBOBJS@@}.
513 So here's what you'd write:
516 bin_PROGRAMS = zardoz
517 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
518 zardoz_LDADD = @@LIBOBJS@@
520 info_TEXINFOS = zardoz.texi
523 Now you can run @code{automake --add-missing} to generate your
524 @file{Makefile.in} and grab any auxiliary files you might need, and
528 @node Hello, etags, Complete, Examples
529 @section A classic program
531 @code{hello} is renowned for its classic simplicity and versatility.
532 This section shows how Automake could be used with the Hello package.
533 The examples below are from the latest GNU Hello, but all the
534 maintainer-only code has been stripped out, as well as all copyright
537 Of course, GNU Hello is somewhat more featureful than your traditional
538 two-liner. GNU Hello is internationalized, does option processing, and
539 has a manual and a test suite. GNU Hello is a deep package.
541 Here is the @file{configure.in} from GNU Hello:
544 dnl Process this file with autoconf to produce a configure script.
546 AM_INIT_AUTOMAKE(hello, 1.3.11)
547 AM_CONFIG_HEADER(config.h)
549 dnl Set of available languages.
550 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
552 dnl Checks for programs.
556 dnl Checks for libraries.
558 dnl Checks for header files.
560 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
562 dnl Checks for library functions.
565 dnl Check for st_blksize in struct stat
568 dnl internationalization macros
570 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
571 src/Makefile tests/Makefile tests/hello],
572 [chmod +x tests/hello])
575 The @samp{AM_} macros are provided by Automake (or the Gettext library);
576 the rest are standard Autoconf macros.
579 The top-level @file{Makefile.am}:
582 EXTRA_DIST = BUGS ChangeLog.O
583 SUBDIRS = doc intl po src tests
586 As you can see, all the work here is really done in subdirectories.
588 The @file{po} and @file{intl} directories are automatically generated
589 using @code{gettextize}; they will not be discussed here.
591 In @file{doc/Makefile.am} we see:
594 info_TEXINFOS = hello.texi
595 hello_TEXINFOS = gpl.texi
598 This is sufficient to build, install, and distribute the Hello manual.
601 Here is @file{tests/Makefile.am}:
605 EXTRA_DIST = hello.in testdata
608 The script @file{hello} is generated by @code{configure}, and is the
609 only test case. @code{make check} will run this test.
611 Last we have @file{src/Makefile.am}, where all the real work is done:
615 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
616 hello_LDADD = @@INTLLIBS@@ @@ALLOCA@@
617 localedir = $(datadir)/locale
618 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
622 @node etags, , Hello, Examples
623 @section Building etags and ctags
625 Here is another, trickier example. It shows how to generate two
626 programs (@code{ctags} and @code{etags}) from the same source file
627 (@file{etags.c}). The difficult part is that each compilation of
628 @file{etags.c} requires different @code{cpp} flags.
631 bin_PROGRAMS = etags ctags
633 ctags_LDADD = ctags.o
636 $(COMPILE) -DETAGS_REGEXPS -c etags.c
639 $(COMPILE) -DCTAGS -o ctags.o -c etags.c
642 Note that @code{ctags_SOURCES} is defined to be empty---that way no
643 implicit value is substituted. The implicit value, however, is used to
644 generate @code{etags} from @file{etags.o}.
646 @code{ctags_LDADD} is used to get @file{ctags.o} into the link line.
647 @code{ctags_DEPENDENCIES} is generated by Automake.
649 The above rules won't work if your compiler doesn't accept both
650 @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
651 bogus dependency (to avoid problems with a parallel @code{make}):
654 etags.o: etags.c ctags.o
655 $(COMPILE) -DETAGS_REGEXPS -c etags.c
658 $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
661 Also, these explicit rules do not work if the de-ANSI-fication feature
662 is used; supporting that requires a little more work:
665 etags._o: etags._c ctags.o
666 $(COMPILE) -DETAGS_REGEXPS -c etags.c
669 $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
673 @node Invoking Automake, configure, Examples, Top
674 @chapter Creating a @file{Makefile.in}
676 To create all the @file{Makefile.in}s for a package, run the
677 @code{automake} program in the top level directory, with no arguments.
678 @code{automake} will automatically find each appropriate
679 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
680 and generate the corresponding @file{Makefile.in}. Note that
681 @code{automake} has a rather simplistic view of what constitutes a
682 package; it assumes that a package has only one @file{configure.in}, at
683 the top. If your package has multiple @file{configure.in}s, then you
684 must run @code{automake} in each directory holding a
687 You can optionally give @code{automake} an argument; @samp{.am} is
688 appended to the argument and the result is used as the name of the input
689 file. This feature is generally only used to automatically rebuild an
690 out-of-date @file{Makefile.in}. Note that @code{automake} must always
691 be run from the topmost directory of a project, even if being used to
692 regenerate the @file{Makefile.in} in some subdirectory. This is
693 necessary because @code{automake} must scan @file{configure.in}, and
694 because @code{automake} uses the knowledge that a @file{Makefile.in} is
695 in a subdirectory to change its behavior in some cases.
697 @code{automake} accepts the following options:
702 Automake requires certain common files to exist in certain situations;
703 for instance @file{config.guess} is required if @file{configure.in} runs
704 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
705 files; this option will cause the missing ones to be automatically added
706 to the package, whenever possible. In general if Automake tells you a
707 file is missing, try using this option.
709 @item --amdir=@var{dir}
710 Look for Automake data files in directory @var{dir} instead of in the
711 installation directory. This is typically used for debugging.
713 @item --build-dir=@var{dir}
714 Tell Automake where the build directory is. This option is used when
715 including dependencies into a @file{Makefile.in} generated by @code{make
716 dist}; it should not be used otherwise.
719 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
720 of GNU or Gnits rules. @xref{Cygnus} for more information.
723 Set the global strictness to @samp{foreign}. @xref{Strictness} for more
727 Set the global strictness to @samp{gnits}. @xref{Gnits} for more
731 Set the global strictness to @samp{gnu}. @xref{Gnits} for more
732 information. This is the default strictness.
735 Print a summary of the command line options and exit.
738 @itemx --include-deps
739 Include all automatically generated dependency information
740 (@pxref{Dependencies}) in the generated
741 @file{Makefile.in}. This is generally done when making a distribution;
745 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
746 @file{configure.in}. This option causes it to only update those
747 @file{Makefile.in}s which are out of date with respect to one of their
751 @itemx --output-dir=@var{dir}
752 Put the generated @file{Makefile.in} in the directory @var{dir}.
753 Ordinarily each @file{Makefile.in} is created in the directory of the
754 corresponding @file{Makefile.am}. This option is used when making
757 @item --srcdir-name=@var{dir}
758 Tell Automake the name of the source directory associated with the
759 current build. This option is used when including dependencies into a
760 @file{Makefile.in} generated by @code{make dist}; it should not be used
765 Cause Automake to print information about which files are being read or
769 Print the version number of Automake and exit.
773 @node configure, Top level, Invoking Automake, Top
774 @chapter Scanning @file{configure.in}
776 Automake scans the package's @file{configure.in} to determine certain
777 information about the package. Some @code{autoconf} macros are required
778 and some variables must be defined in @file{configure.in}. Automake
779 will also use information from @file{configure.in} to further tailor its
782 Automake also supplies some @code{autoconf} macros to make the
783 maintenance easier. These macros can automatically be put into your
784 @file{aclocal.m4} using the @code{aclocal} program.
787 * Requirements:: Configuration requirements
788 * Optional:: Other things Automake recognizes
789 * Invoking aclocal:: Auto-generating aclocal.m4
790 * Macros:: Autoconf macros supplied with Automake
791 * Extending aclocal:: Writing your own aclocal macros
795 @node Requirements, Optional, configure, configure
796 @section Configuration requirements
798 The simplest way to meet the basic Automake requirements is to use the
799 macro @code{AM_INIT_AUTOMAKE} (@pxref{Macros}). But if you prefer, you
800 can do the required steps by hand:
801 @cvindex AM_INIT_AUTOMAKE
805 Define the variables @code{PACKAGE} and @code{VERSION} with
809 @code{PACKAGE} should be the name of the package as it appears when
810 bundled for distribution. For instance, Automake defines @code{PACKAGE}
811 to be @samp{automake}. @code{VERSION} should be the version number of
812 the release that is being developed. We recommend that you make
813 @file{configure.in} the only place in your package where the version
814 number is defined; this makes releases simpler.
816 Automake doesn't do any interpretation of @code{PACKAGE} or
817 @code{VERSION}, except in @samp{Gnits} mode (@pxref{Gnits}).
820 Use the macro @code{AC_ARG_PROGRAM} if a program or script is installed.
821 @cvindex AC_ARG_PROGRAM
824 Use @code{AC_PROG_MAKE_SET} if the package is not flat.
825 @cvindex AC_PROG_MAKE_SET
828 Use @code{AM_SANITY_CHECK} to make sure the build environment is sane.
831 Use @code{AM_PROG_INSTALL} if any scripts (@pxref{Scripts}) are
832 installed by the package. Otherwise, use @code{AC_PROG_INSTALL}.
833 @cvindex AC_PROG_INSTALL
834 @cvindex AM_PROG_INSTALL
837 Use @code{AM_MISSING_PROG} to see whether the programs @code{aclocal},
838 @code{autoconf}, @code{automake}, @code{autoheader}, and @code{makeinfo}
839 are in the build environment. Here is how this is done:
841 missing_dir=`cd $ac_aux_dir && pwd`
842 AM_MISSING_PROG(ACLOCAL, aclocal, $missing_dir)
843 AM_MISSING_PROG(AUTOCONF, autoconf, $missing_dir)
844 AM_MISSING_PROG(AUTOMAKE, automake, $missing_dir)
845 AM_MISSING_PROG(AUTOHEADER, autoheader, $missing_dir)
846 AM_MISSING_PROG(MAKEINFO, makeinfo, $missing_dir)
851 Here are the other macros which Automake requires but which are not run
852 by @code{AM_INIT_AUTOMAKE}:
856 Automake uses this to determine which files to create. Listed files
857 named @code{Makefile} are treated as @file{Makefile}s. Other listed
858 files are treated differently. Currently the only difference is that a
859 @file{Makefile} is removed by @code{make distclean}, while other files
860 are removed by @code{make clean}.
861 @c FIXME: this is in violation of standards!
865 @node Optional, Invoking aclocal, Requirements, configure
866 @section Other things Automake recognizes
868 Automake will also recognize the use of certain macros and tailor the
869 generated @file{Makefile.in} appropriately. Currently recognized macros
870 and their effects are:
873 @item AC_CONFIG_HEADER
874 Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar
875 to @code{AC_CONFIG_HEADER} but does some useful Automake-specific work.
876 @cvindex AC_CONFIG_HEADER
878 @item AC_CONFIG_AUX_DIR
879 Automake will look for various helper scripts, such as
880 @file{mkinstalldirs}, in the directory named in this macro invocation.
881 If not seen, the scripts are looked for in their ``standard'' locations
882 (either the top source directory, or in the source directory
883 corresponding to the current @file{Makefile.am}, whichever is
885 @cvindex AC_CONFIG_AUX_DIR
886 FIXME: give complete list of things looked for in this directory
889 Automake will insert definitions for the variables defined by
890 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
892 @cvindex AC_PATH_XTRA
894 @item AC_CANONICAL_HOST
896 Automake will ensure that @file{config.guess} and @file{config.sub}
897 exist. Also, the @file{Makefile} variables @samp{host_alias} and
898 @samp{host_triplet} are introduced.
899 @c fixme xref autoconf docs.
900 @cvindex AC_CANONICAL_HOST
901 @cvindex AC_CHECK_TOOL
905 @item AC_CANONICAL_SYSTEM
906 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
907 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
908 @cvindex AC_CANONICAL_SYSTEM
913 @itemx AC_FUNC_GETLOADAVG
914 @itemx AC_FUNC_MEMCMP
915 @itemx AC_STRUCT_ST_BLOCKS
916 @itemx AC_FUNC_FNMATCH
917 @itemx AM_FUNC_STRTOD
918 @itemx AC_REPLACE_FUNCS
919 @itemx AC_REPLACE_GNU_GETOPT
921 Automake will ensure that the appropriate dependencies are generated for
922 the objects corresponding to these macros. Also, Automake will verify
923 that the appropriate source files are part of the distribution. Note
924 that Automake does not come with any of the C sources required to use
925 these macros, so @code{automake -a} will not install the sources.
926 @xref{A Library} for more information.
927 @cvindex AC_FUNC_ALLOCA
928 @cvindex AC_FUNC_GETLOADAVG
929 @cvindex AC_FUNC_MEMCMP
930 @cvindex AC_STRUCT_ST_BLOCKS
931 @cvindex AC_FUNC_FNMATCH
932 @cvindex AC_FUNC_FNMATCH
933 @cvindex AC_REPLACE_FUNCS
934 @cvindex AC_REPLACE_GNU_GETOPT
935 @cvindex AM_FUNC_STRTOD
936 @cvindex AM_WITH_REGEX
939 Automake will detect statements which put @samp{.o} files into
940 @code{LIBOBJS}, and will treat these additional files as if they were
941 discovered via @code{AC_REPLACE_FUNCS}.
945 This is required if any libraries are built in the package.
946 @cvindex AC_PROG_RANLIB
949 This is required if any C++ source is included.
952 @item AM_PROG_LIBTOOL
953 Automake will turn on processing for @code{libtool} (@pxref{Top, , The
954 Libtool Manual, libtool, The Libtool Manual}).
955 @cvindex AM_PROG_LIBTOOL
958 If a Yacc source file is seen, then you must either use this macro or
959 define the variable @samp{YACC} in @file{configure.in}. The former is
961 @cvindex AC_PROG_YACC
965 This macro is required if there is Lex source in the package.
966 @cvindex AC_DECL_YYTEXT
969 If a Lex source file is seen, then this macro must be used.
973 If Automake sees that this variable is set in @file{configure.in}, it
974 will check the @file{po} directory to ensure that all the named
975 @samp{.po} files exist, and that all the @samp{.po} files that exist are
979 @item AM_C_PROTOTYPES
980 This is required when using automatic de-ANSI-fication, see @ref{ANSI}.
981 @cvindex AM_C_PROTOTYPES
984 This macro is required for packages which use GNU gettext
985 (@pxref{gettext}). It is distributed with gettext. If Automake sees
986 this macro it ensures that the package meets some of gettext's
988 @cvindex AM_GNU_GETTEXT
990 @item AM_MAINTAINER_MODE
991 This macro adds a @samp{--enable-maintainer-mode} option to
992 @code{configure}. If this is used, @code{automake} will cause
993 ``maintainer-only'' rules to be turned off by default in the generated
994 @file{Makefile.in}s. This macro is disallowed in @samp{Gnits} mode
996 @cvindex AM_MAINTAINER_MODE
1000 @itemx AC_CHECK_PROG
1001 @itemx AC_CHECK_PROGS
1003 @itemx AC_PATH_PROGS
1004 For each of these macros, the first argument is automatically defined as
1005 a variable in each generated @file{Makefile.in}.
1007 @cvindex AC_CHECK_TOOL
1008 @cvindex AC_CHECK_PROG
1009 @cvindex AC_CHECK_PROGS
1010 @cvindex AC_PATH_PROG
1011 @cvindex AC_PATH_PROGS
1016 @node Invoking aclocal, Macros, Optional, configure
1017 @section Auto-generating aclocal.m4
1019 Automake includes a number of Autoconf macros which can be used in your
1020 package; some of them are actually required by Automake in certain
1021 situations. These macros must be defined in your @file{aclocal.m4};
1022 otherwise they will not be seen by @code{autoconf}.
1024 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1025 files based on the contents of @file{configure.in}. This provides a
1026 convenient way to get Automake-provided macros, without having to
1027 search around. Also, the @code{aclocal} mechanism is extensible for use
1030 At startup, @code{aclocal} scans all the @samp{.m4} files it can find,
1031 looking for macro definitions. Then it scans @file{configure.in}. Any
1032 mention of one of the macros found in the first step causes that macro,
1033 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1035 The contents of @file{acinclude.m4}, if it exists, are also
1036 automatically included in @file{aclocal.m4}. This is useful for
1037 incorporating local macros into @file{configure}.
1039 @code{aclocal} accepts the following options:
1042 @item --acdir=@var{dir}
1043 Look for the macro files in @var{dir} instead of the installation
1044 directory. This is typically used for debugging.
1047 Print a summary of the command line options and exit.
1050 Add the directory @var{dir} to the list of directories searched for
1053 @item --output=@var{file}
1054 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1057 Print the names of the files it examines.
1060 Print the version number of Automake and exit.
1064 @node Macros, Extending aclocal, Invoking aclocal, configure
1065 @section Autoconf macros supplied with Automake
1067 @c consider generating this node automatically from m4 files.
1070 @item AM_CONFIG_HEADER
1071 Automake will generate rules to automatically regenerate the config
1072 header. If you do use this macro, you must create the file
1073 @file{stamp-h.in} in your source directory. It can be empty.
1074 @cvindex AM_CONFIG_HEADER
1077 Check to see if this @code{configure} is being run in the
1078 @samp{Cygwin32} environment. (FIXME xref). If so, define output
1079 variable @code{EXEEXT} to @samp{.exe}; otherwise define it to the empty
1080 string. Automake recognizes this macro and uses it to generate
1081 @file{Makefile.in}s which will automatically work under @samp{Cygwin32}.
1082 In the @samp{Cygwin32} environment, @code{gcc} generates executables
1083 whose names end in @samp{.exe}, even if this was not specified on the
1084 command line. Automake adds special code to @file{Makefile.in} to
1085 gracefully deal with this.
1087 @item AM_FUNC_STRTOD
1088 If the @code{strtod} function is not available, or does not work
1089 correctly (like the one on SunOS 5.4), add @file{strtod.o} to output
1090 variable @code{LIBOBJS}.
1091 @cvindex AM_FUNC_STRTOD
1093 @item AM_FUNC_ERROR_AT_LINE
1094 If the function @code{error_at_line} is not found, then add
1095 @file{error.o} to @code{LIBOBJS}.
1096 @cvindex AM_FUNC_ERROR_AT_LINE
1098 @item AM_FUNC_MKTIME
1099 Check for a working @code{mktime} function. If not found, add
1100 @file{mktime.o} to @samp{LIBOBJS}.
1101 @cvindex AM_FUNC_MKTIME
1103 @item AM_FUNC_OBSTACK
1104 Check for the GNU obstacks code; if not found, add @file{obstack.o} to
1106 @cvindex AM_FUNC_OBSTACK
1108 @item AM_C_PROTOTYPES
1109 Check to see if function prototypes are understood by the compiler. If
1110 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1111 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1112 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1113 values to implement automatic de-ANSI-fication.
1114 @cvindex AM_C_PROTOTYPES
1116 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1117 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1118 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1119 found in @file{<termios.h>}.
1120 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1122 @item AM_INIT_AUTOMAKE
1123 Runs many macros that most @file{configure.in}'s need. This macro has
1124 two required arguments, the package and the version number. By default
1125 this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}. This
1126 can be avoided by passing in a non-empty third argument.
1128 @item AM_PATH_LISPDIR
1129 Searches for the program @code{emacs}, and, if found, sets the output
1130 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1131 @cvindex AM_PATH_LISPDIR
1133 @item AM_PROG_CC_STDC
1134 If the C compiler in not in ANSI C mode by default, try to add an option
1135 to output variable @code{CC} to make it so. This macro tries various
1136 options that select ANSI C on some system or another. It considers the
1137 compiler to be in ANSI C mode if it handles function prototypes correctly.
1139 If you use this macro, you should check after calling it whether the C
1140 compiler has been set to accept ANSI C; if not, the shell variable
1141 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1142 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1143 @code{ansi2knr} option.
1144 @cvindex AM_PROG_CC_STDC
1146 @item AM_PROG_INSTALL
1147 Like @code{AC_PROG_INSTALL}, but also defines @code{INSTALL_SCRIPT}.
1148 @cvindex AM_PROG_INSTALL
1150 @item AM_SANITY_CHECK
1151 This checks to make sure that a file created in the build directory is
1152 newer than a file in the source directory. This can fail on systems
1153 where the clock is set incorrectly. This macro is automatically run
1154 from @code{AM_INIT_AUTOMAKE}.
1155 @cvindex AM_SANITY_CHECK
1157 @item AM_SYS_POSIX_TERMIOS
1158 Check to see if POSIX termios headers and functions are available on the
1159 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1160 @samp{yes}. If not, set the variable to @samp{no}.
1161 @cvindex AM_SYS_POSIX_TERMIOS
1163 @item AM_TYPE_PTRDIFF_T
1164 Define @samp{HAVE_PTRDIFF_T} if the type @samp{ptrdiff_t} is defined in
1166 @cvindex AM_TYPE_PTRDIFF_T
1168 @item AM_WITH_DMALLOC
1169 Add support for the @code{dmalloc} package. If the user configures with
1170 @samp{--with-dmalloc}, then define @code{WITH_DMALLOC} and add
1171 @samp{-ldmalloc} to @code{LIBS}. The @code{dmalloc} package can be
1172 found at @url{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz}
1173 @cvindex AM_WITH_DMALLOC
1176 Adds @samp{--with-regex} to the @code{configure} command line. If
1177 specified (the default), then the @samp{regex} regular expression
1178 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1179 @samp{WITH_REGEX} is defined.. If @samp{--without-regex} is given, then
1180 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1181 into @samp{LIBOBJS}.
1182 @cvindex AM_WITH_REGEX
1186 @node Extending aclocal, , Macros, configure
1187 @section Writing your own aclocal macros
1189 Aclocal doesn't have any built-in knowledge of any macros, so it is easy
1190 to extend it with your own macros.
1192 This is mostly used for libraries which want to supply their own
1193 Autoconf macros for use by other programs. For instance the
1194 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1195 should be used by any package using @code{gettext}. When the library is
1196 installed, it installs this macro so that @code{aclocal} will find it.
1198 A file of macros should be a series of @code{AC_DEFUN}'s. Aclocal also
1199 understands @code{AC_REQUIRE}, so it is safe to put each macro in a
1202 A macro file's name should end in @samp{.m4}. Such files should be
1203 installed in @file{$(datadir)/aclocal}.
1205 @node Top level, Programs, configure, Top
1206 @chapter The top-level @file{Makefile.am}
1208 In non-flat packages, the top level @file{Makefile.am} must tell
1209 Automake which subdirectories are to be built. This is done via the
1210 @code{SUBDIRS} variable.
1213 The @code{SUBDIRS} macro holds a list of subdirectories in which
1214 building of various sorts can occur. Many targets (eg @code{all}) in
1215 the generated @file{Makefile} will run both locally and in all specified
1216 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1217 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1218 (after configuration). This allows inclusion of libraries from packages
1219 which do not use Automake (such as @code{gettext}). The directories
1220 mentioned in @code{SUBDIRS} must be direct children of the current
1221 directory. For instance, you cannot put @samp{src/subdir} into
1224 In a deep package, the top-level @file{Makefile.am} is often very short.
1225 For instance, here is the @file{Makefile.am} from the Hello
1229 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1230 SUBDIRS = doc intl po src tests
1233 @code{SUBDIRS} can contain configure substitutions (eg @samp{@@DIRS@@});
1234 Automake itself does not actually examine the contents of this variable.
1236 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1237 @code{AC_PROG_MAKE_SET}.
1239 The use of @code{SUBDIRS} is not restricted to just the top-level
1240 @file{Makefile.am}. Automake can be used to construct packages of
1244 @node Programs, Other objects, Top level, Top
1245 @chapter Building Programs and Libraries
1247 A large part of Automake's functionality is dedicated to making it easy
1248 to build C programs and libraries.
1251 * A Program:: Building a program
1252 * A Library:: Building a library
1253 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1254 * A Shared Library:: Building a Libtool library
1255 * Program variables:: Variables used when building a program
1256 * Yacc and Lex:: Yacc and Lex support
1258 * ANSI:: Automatic de-ANSI-fication
1259 * Dependencies:: Automatic dependency tracking
1263 @node A Program, A Library, Programs, Programs
1264 @section Building a program
1266 In a directory containing source that gets built into a program (as
1267 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
1268 can be installed in @samp{bindir}, @samp{sbindir}, @samp{libexecdir},
1269 @samp{pkglibdir}, or not at all (@samp{noinst}).
1274 bin_PROGRAMS = hello
1277 In this simple case, the resulting @file{Makefile.in} will contain code
1278 to generate a program named @code{hello}. The variable
1279 @code{hello_SOURCES} is used to specify which source files get built
1283 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1286 This causes each mentioned @samp{.c} file to be compiled into the
1287 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1289 If @samp{prog_SOURCES} is needed, but not specified, then it defaults to
1290 the single file @file{prog.c}. In the example above, the definition of
1291 @code{hello_SOURCES} is actually redundant.
1295 Multiple programs can be built in a single directory. Multiple programs
1296 can share a single source file. The source file must be listed in each
1297 @samp{_SOURCES} definition.
1299 Header files listed in a @samp{_SOURCES} definition will be included in
1300 the distribution but otherwise ignored. In case it isn't obvious, you
1301 should not include the header file generated by @file{configure} in an
1302 @samp{_SOURCES} variable; this file should not be distributed. Lex
1303 (@samp{.l}) and yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1306 Automake must know all the source files that could possibly go into a
1307 program, even if not all the files are built in every circumstance.
1308 Any files which are only conditionally built should be listed in the
1309 appropriate @samp{EXTRA_} variable. For instance, if
1310 @file{hello-linux.c} were conditionally included in @code{hello}, the
1311 @file{Makefile.am} would contain:
1314 EXTRA_hello_SOURCES = hello-linux.c
1317 Similarly, sometimes it is useful to determine the programs that are to
1318 be built at configure time. For instance, GNU @code{cpio} only builds
1319 @code{mt} and @code{rmt} under special circumstances.
1321 In this case, you must notify @code{automake} of all the programs that
1322 can possibly be built, but at the same time cause the generated
1323 @file{Makefile.in} to use the programs specified by @code{configure}.
1324 This is done by having @code{configure} substitute values into each
1325 @samp{_PROGRAMS} definition, while listing all optionally built programs in
1326 @code{EXTRA_PROGRAMS}.
1327 @vindex EXTRA_PROGRAMS
1329 If you need to link against libraries that are not found by
1330 @code{configure}, you can use @code{LDADD} to do so. This variable
1331 actually can be used to add any options to the linker command line.
1334 Sometimes, multiple programs are built in one directory but do not share
1335 the same link-time requirements. In this case, you can use the
1336 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1337 program as it appears in some @samp{_PROGRAMS} variable, and usually
1338 written in lowercase) to override the global @code{LDADD}. (If this
1339 variable exists for a given program, then that program is not linked
1340 using @code{LDADD}.)
1343 For instance, in GNU cpio, @code{pax}, @code{cpio}, and @code{mt} are
1344 linked against the library @file{libcpio.a}. However, @code{rmt} is
1345 built in the same directory, and has no such link requirement. Also,
1346 @code{mt} and @code{rmt} are only built on certain architectures. Here
1347 is what cpio's @file{src/Makefile.am} looks like (abridged):
1350 bin_PROGRAMS = cpio pax @@MT@@
1351 libexec_PROGRAMS = @@RMT@@
1352 EXTRA_PROGRAMS = mt rmt
1354 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1357 cpio_SOURCES = @dots{}
1358 pax_SOURCES = @dots{}
1359 mt_SOURCES = @dots{}
1360 rmt_SOURCES = @dots{}
1363 @samp{prog_LDADD} is inappropriate for passing program-specific linker
1364 flags (except for @samp{-l} and @samp{-L}). So, use the
1365 @samp{prog_LDFLAGS} variable for this purpose.
1368 It is also occasionally useful to have a program depend on some other
1369 target which is not actually part of that program. This can be done
1370 using the @samp{prog_DEPENDENCIES} variable. Each program depends on
1371 the contents of such a variable, but no further interpretation is done.
1373 If @samp{prog_DEPENDENCIES} is not supplied, it is computed by Automake.
1374 The automatically-assigned value is the contents of @samp{prog_LDADD},
1375 with most configure substitutions, @samp{-l}, and @samp{-L} options
1376 removed. The configure substitutions that are left in are only
1377 @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are left because it is
1378 known that they will not cause an invalid value for
1379 @samp{prog_DEPENDENCIES} to be generated.
1382 @node A Library, LIBOBJS, A Program, Programs
1383 @section Building a library
1385 Building a library is much like building a program. In this case, the
1386 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
1387 @code{libdir} or @code{pkglibdir}.
1389 @xref{A Shared Library}, for information on how to build shared
1390 libraries using Libtool and the @samp{LTLIBRARIES} primary.
1392 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
1393 For instance to create a library named @file{libcpio.a}, but not install
1394 it, you would write:
1397 noinst_LIBRARIES = libcpio.a
1400 The sources that go into a library are determined exactly as they are
1401 for programs, via the @samp{_SOURCES} variables. Note that the library
1402 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
1403 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
1404 not @samp{liblob.a_SOURCES}.
1406 Extra objects can be added to a library using the @samp{library_LIBADD}
1407 variable. This should be used for objects determined by
1408 @code{configure}. Again from cpio:
1413 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
1416 @node LIBOBJS, A Shared Library, A Library, Programs
1417 @section Special handling for LIBOBJS and ALLOCA
1419 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
1420 @code{@@ALLOCA@@}, and uses this information, plus the list of
1421 @code{LIBOBJS} files derived from @file{configure.in} to automatically
1422 include the appropriate source files in the distribution (@pxref{Dist}).
1423 These source files are also automatically handled in the
1424 dependency-tracking scheme, see @xref{Dependencies}.
1426 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
1427 @samp{_LDADD} or @samp{_LIBADD} variable.
1429 @node A Shared Library, Program variables, LIBOBJS, Programs
1430 @section Building a Shared Library
1432 Building shared libraries is a relatively complex matter. For this
1433 reason, GNU Libtool (@pxref{Top, , The Libtool Manual, libtool, The
1434 Libtool Manual}) was created to help build shared libraries in a
1435 platform-independent way.
1437 Automake uses Libtool to build libraries declared with the
1438 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
1439 of shared libraries to build. For instance, to create a library named
1440 @file{libgettext.a} and its corresponding shared libraries, and install
1441 them in @samp{libdir}, write:
1444 lib_LTLIBRARIES = libgettext.la
1447 Note that shared libraries @emph{must} be installed, so
1448 @samp{noinst_LTLIBRARIES} and @samp{check_LTLIBRARIES} are not allowed.
1450 For each library, the @samp{library_LIBADD} variable contains the names
1451 of extra libtool objects (@samp{.lo} files) to add to the shared
1452 library. The @samp{library_LDFLAGS} variable contains any additional
1453 libtool flags, such as @samp{-version-info} or @samp{-static}.
1455 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
1456 library must use @code{@@LTLIBOBJS@@}. This is required because the
1457 object files that libtool operates on do not necessarily end in
1458 @samp{.o}. The libtool manual contains more details on this topic.
1460 For libraries installed in some directory, @code{automake} will
1461 automatically supply the appropriate @samp{-rpath} option. However, for
1462 libraries determined at configure time (and thus mentioned in
1463 @code{EXTRA_LTLIBRARIES}), @code{automake} does not know the eventual
1464 installation directory; for such libraries you must add the
1465 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
1468 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
1469 libtool, The Libtool Manual}, for more information.
1471 @node Program variables, Yacc and Lex, A Shared Library, Programs
1472 @section Variables used when building a program
1474 Occasionally it is useful to know which @file{Makefile} variables
1475 Automake uses for compilations; for instance you might need to do your
1476 own compilation in some special cases.
1478 Some variables are inherited from Autoconf; these are @code{CC},
1479 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
1483 There are some additional variables which Automake itself defines:
1487 A list of @samp{-I} options. This can be set in your @file{Makefile.am}
1488 if you have special directories you want to look in. @code{automake}
1489 already provides some @samp{-I} options automatically. In particular it
1490 generates @samp{-I$(srcdir)} and a @samp{-I} pointing to the directory
1491 holding @file{config.h} (if you've used @code{AC_CONFIG_HEADER} or
1492 @code{AM_CONFIG_HEADER}).
1494 @code{INCLUDES} can actually be used for other @code{cpp} options
1495 besides @samp{-I}. For instance, it is sometimes used to pass arbitrary
1496 @samp{-D} options to the compiler.
1499 This is the command used to actually compile a C source file. The
1500 filename is appended to form the complete command line.
1503 This is the command used to actually link a C program.
1507 @node Yacc and Lex, C++, Program variables, Programs
1508 @section Yacc and Lex support
1510 Automake has somewhat idiosyncratic support for Yacc and Lex.
1512 Automake assumes that the @samp{.c} file generated by yacc (or lex)
1513 should be named using the basename of the input file. That is, for a
1514 yacc source file @file{foo.y}, automake will cause the intermediate file
1515 to be named @file{foo.c} (as opposed to @file{y.tab.c}, which is more
1518 The extension of a yacc source file is used to determine the extension
1519 of the resulting @samp{C} or @samp{C++} file. Files with the extension
1520 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
1521 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
1522 @samp{.cxx}. Likewise, lex source files can be used to generate
1523 @samp{C} or @samp{C++}; the extensions @samp{.l}, @samp{.ll},
1524 @samp{.l++}, and @samp{.lxx} are recognized.
1526 You should never explicitly mention the intermediate (@samp{C} or
1527 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
1530 The intermediate files generated by yacc (or lex) will be included in
1531 any distribution that is made. That way the user doesn't need to have
1534 If a yacc source file is seen, then your @file{configure.in} must define
1535 the variable @samp{YACC}. This is most easily done by invoking the
1536 macro @samp{AC_PROG_YACC}.
1538 Similarly, if a lex source file is seen, then your @file{configure.in}
1539 must define the variable @samp{LEX}. You can use @samp{AC_PROG_LEX} to
1540 do this. Automake's lex support also requires that you use the
1541 @samp{AC_DECL_YYTEXT} macro---automake needs to know the value of
1542 @samp{LEX_OUTPUT_ROOT}.
1544 Any program including a lex source file must be linked against
1545 @samp{@@LEXLIB@@}. You can do this by putting @samp{@@LEXLIB@@} into
1546 the appropriate @samp{LDADD} variable.
1548 Automake makes it possible to include multiple yacc (or lex) source
1549 files in a single program. Automake uses a small program called
1550 @code{ylwrap} to run @code{yacc} (or @code{lex}) in a subdirectory.
1551 This is necessary because yacc's output filename is fixed, and a
1552 parallel make could conceivably invoke more than one instance of
1553 @code{yacc} simultaneously. @code{ylwrap} is distributed with automake.
1554 It should appear in the directory specified by @samp{AC_CONFIG_AUX_DIR},
1555 or the current directory if that macro is not used in
1556 @file{configure.in}.
1558 For @code{yacc}, simply managing locking is insufficient. @code{yacc}
1559 output also always uses the same symbol names internally, so it isn't
1560 possible to link two @code{yacc} parsers into the same executable.
1562 We recommend using the following renaming hack used in @code{gdb}:
1564 #define yymaxdepth c_maxdepth
1565 #define yyparse c_parse
1567 #define yyerror c_error
1568 #define yylval c_lval
1569 #define yychar c_char
1570 #define yydebug c_debug
1571 #define yypact c_pact
1578 #define yyexca c_exca
1579 #define yyerrflag c_errflag
1580 #define yynerrs c_nerrs
1584 #define yy_yys c_yys
1585 #define yystate c_state
1588 #define yy_yyv c_yyv
1590 #define yylloc c_lloc
1591 #define yyreds c_reds
1592 #define yytoks c_toks
1593 #define yylhs c_yylhs
1594 #define yylen c_yylen
1595 #define yydefred c_yydefred
1596 #define yydgoto c_yydgoto
1597 #define yysindex c_yysindex
1598 #define yyrindex c_yyrindex
1599 #define yygindex c_yygindex
1600 #define yytable c_yytable
1601 #define yycheck c_yycheck
1604 For each define, replace the @samp{c_} prefix with whatever you like.
1605 These defines work for @code{bison}, @code{byacc}, and traditional
1606 @code{yacc}s. If you find a parser generator that uses a symbol not
1607 covered here, please report the new name so it can be added to the list.
1610 @node C++, ANSI, Yacc and Lex, Programs
1611 @section C++ and other languages
1613 Automake includes full support for C++, and rudimentary support for
1614 other languages. Support for other languages will be improved based on
1617 Any package including C++ code must define the output variable
1618 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
1619 the @code{AC_PROG_CXX} macro.
1621 A few additional variables are defined when a C++ source file is seen:
1625 The name of the C++ compiler.
1629 Any flags to pass to the C++ compiler.
1633 The command used to actually compile a C++ source file. The file name
1634 is appended to form the complete command line.
1638 The command used to actually link a C++ program.
1643 @node ANSI, Dependencies, C++, Programs
1644 @section Automatic de-ANSI-fication
1646 Although the GNU standards allow the use of ANSI C, this can have the
1647 effect of limiting portability of a package to some older compilers
1650 Automake allows you to work around this problem on such machines by
1651 ``de-ANSI-fying'' each source file before the actual compilation takes
1654 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
1655 @vindex AUTOMAKE_OPTIONS
1656 (@ref{Options}) contains the option @code{ansi2knr}
1658 then code to handle de-ANSI-fication is inserted into the generated
1661 This causes each C source file in the directory to be treated as ANSI C.
1662 If an ANSI C compiler is available, it is used. If no ANSI C compiler
1663 is available, the @code{ansi2knr} program is used to convert the source
1664 files into K&R C, which is then compiled.
1666 The @code{ansi2knr} program is simple-minded. It assumes the source
1667 code will be formatted in a particular way; see the @code{ansi2knr} man
1670 De-ANSI-fication support requires the source files @file{ansi2knr.c} and
1671 @file{ansi2knr.1} to be in the same package as the ANSI C source; these
1672 files are distributed with Automake. Also, the package
1673 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}.
1674 @cvindex AM_C_PROTOTYPES
1676 Automake also handles finding the @code{ansi2knr} support files in some
1677 other directory in the current package. This is done by prepending the
1678 relative path to the appropriate directory to the @code{ansi2knr}
1679 option. For instance, suppose the package has ANSI C code in the
1680 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
1681 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
1682 @file{src/Makefile.am}:
1685 AUTOMAKE_OPTIONS = ../lib/ansi2knr
1688 If no directory prefix is given, the files are assumed to be in the
1691 @node Dependencies, , ANSI, Programs
1692 @section Automatic dependency tracking
1694 As a developer it is often painful to continually update the
1695 @file{Makefile.in} whenever the include-file dependencies change in a
1696 project. @code{automake} supplies a way to automatically track
1697 dependency changes, and distribute the dependencies in the generated
1700 Currently this support requires the use of GNU @code{make} and
1701 @code{gcc}. It might become possible in the future to supply a
1702 different dependency generating program, if there is enough demand. In
1703 the meantime, this mode is enabled by default if any C program or
1704 library is defined in the current directory, so you may get a @samp{Must
1705 be a separator} error from non-GNU make.
1707 When you decide to make a distribution, the @code{dist} target will
1709 re-run @code{automake} with @samp{--include-deps} and other options.
1710 This will cause the previously generated dependencies to be inserted
1711 into the generated @file{Makefile.in}, and thus into the distribution.
1712 This step also turns off inclusion of the dependency generation code, so
1713 that those who download your distribution but don't use GNU @code{make}
1714 and @code{gcc} will not get errors.
1716 When added to the @file{Makefile.in}, the dependencies have all
1717 system-specific dependencies automatically removed. This can be done by
1718 listing the files in @samp{OMIT_DEPENDENCIES}.
1719 @vindex OMIT_DEPENDENCIES
1720 For instance all references to system header files are removed by
1721 @code{automake}. Sometimes it is useful to specify that a certain
1722 header file should be removed. For instance if your @file{configure.in}
1723 uses @samp{AM_WITH_REGEX}, then any dependency on @file{rx.h} or
1724 @file{regex.h} should be removed, because the correct one cannot be
1725 known until the user configures the package.
1727 As it turns out, @code{automake} is actually smart enough to handle the
1728 particular case of the regular expression header. It will also
1729 automatically omit @file{libintl.h} if @samp{AM_GNU_GETTEXT} is used.
1731 Automatic dependency tracking can be suppressed by putting
1732 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}.
1733 @vindex AUTOMAKE_OPTIONS
1734 @opindex no-dependencies
1736 If you unpack a distribution made by @code{make dist}, and you want to
1737 turn on the dependency-tracking code again, simply re-run
1740 The actual dependency files are put under the build directory, in a
1741 subdirectory named @file{.deps}. These dependencies are machine
1742 specific. It is safe to delete them if you like; they will be
1743 automatically recreated during the next build.
1746 @node Other objects, Other GNU Tools, Programs, Top
1747 @chapter Other Derived Objects
1749 Automake can handle derived objects which are not C programs. Sometimes
1750 the support for actually building such objects must be explicitly
1751 supplied, but Automake will still automatically handle installation and
1755 * Scripts:: Executable scripts
1756 * Headers:: Header files
1757 * Data:: Architecture-independent data files
1758 * Sources:: Derived sources
1762 @node Scripts, Headers, Other objects, Other objects
1763 @section Executable Scripts
1765 It is possible to define and install programs which are scripts. Such
1766 programs are listed using the @samp{SCRIPTS} primary name.
1767 @code{automake} doesn't define any dependencies for scripts; the
1768 @file{Makefile.am} should include the appropriate rules.
1771 @code{automake} does not assume that scripts are derived objects; such
1772 objects must be deleted by hand; see @ref{Clean} for more information.
1774 @code{automake} itself is a script that is generated at configure time
1775 from @file{automake.in}. Here is how this is handled:
1778 bin_SCRIPTS = automake
1781 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
1782 for it is automatically generated.
1784 Script objects can be installed in @code{bindir}, @code{sbindir},
1785 @code{libexecdir}, or @code{pkgdatadir}.
1788 @node Headers, Data, Scripts, Other objects
1789 @section Header files
1791 Header files are specified by the @samp{HEADERS} family of variables.
1792 Generally header files are not installed, so the @code{noinst_HEADERS}
1793 variable will be the most used.
1796 All header files must be listed somewhere; missing ones will not appear
1797 in the distribution. Often it is clearest to list uninstalled headers
1798 with the rest of the sources for a program. @xref{A Program}. Headers
1799 listed in a @samp{_SOURCES} variable need not be listed in any
1800 @samp{_HEADERS} variable.
1802 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
1803 @code{pkgincludedir}.
1806 @node Data, Sources, Headers, Other objects
1807 @section Architecture-independent data files
1809 Automake supports the installation of miscellaneous data files using the
1810 @samp{DATA} family of variables.
1813 Such data can be installed in the directories @code{datadir},
1814 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
1817 By default, data files are not included in a distribution.
1819 Here is how @code{automake} installs its auxiliary data files:
1822 pkgdata_DATA = clean-kr.am clean.am @dots{}
1826 @node Sources, , Data, Other objects
1827 @section Built sources
1829 Occasionally a file which would otherwise be called ``source'' (eg a C
1830 @samp{.h} file) is actually derived from some other file. Such files
1831 should be listed in the @code{BUILT_SOURCES} variable.
1832 @vindex BUILT_SOURCES
1834 Built sources are also not compiled by default. You must either
1835 explicitly mention them in some other @samp{_SOURCES} variable for this
1838 Note that, in some cases, @code{BUILT_SOURCES} will work in somewhat
1839 suprising ways. In order to get the built sources to work with
1840 automatic dependency tracking, the @file{Makefile} must depend on
1841 @code{$(BUILT_SOURCES)}. This can cause these sources to be rebuilt at
1842 what might seem like funny times.
1845 @node Other GNU Tools, Documentation, Other objects, Top
1846 @chapter Other GNU Tools
1848 Since Automake is primarily intended to generate @file{Makefile.in}s for
1849 use in GNU programs, it tries hard to interoperate with other GNU tools.
1852 * Emacs Lisp:: Emacs Lisp
1858 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
1861 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
1862 is used to hold a list of @samp{.el} files. Possible prefixes for this
1863 primary are @samp{lisp_} and @samp{noinst_}. Note that if
1864 @code{lisp_LISP} is defined, then @file{configure.in} must run
1865 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
1870 By default Automake will byte-compile all Emacs Lisp source files using
1871 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
1872 byte-compiling, simply define the variable @samp{ELCFILES} to be empty.
1874 Byte-compiled Emacs Lisp files are not portable among all versions of
1875 Emacs, so it makes sense to turn this off if you expect sites to have
1876 more than one version of Emacs installed. Furthermore, many packages
1877 don't actually benefit from byte-compilation. Still, we recommand that
1878 you leave it enabled by default. It is probably better for sites with
1879 strange setups to cope for themselves than to make the installation less
1880 nice for everybody else.
1882 @node gettext, Guile, Emacs Lisp, Other GNU Tools
1885 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
1886 turns on support for GNU gettext, a message catalog system for
1887 internationalization
1888 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
1890 The @code{gettext} support in Automake requires the addition of two
1891 subdirectories to the package, @file{intl} and @file{po}. Automake
1892 ensure that these directories exist and are mentioned in @code{SUBDIRS}.
1894 Furthermore, Automake checks that the definition of @samp{ALL_LINGUAS}
1895 in @file{configure.in} corresponds to all the valid @samp{.po} files,
1899 @node Guile, Libtool, gettext, Other GNU Tools
1902 Automake provides some automatic support for writing Guile modules.
1903 Automake will turn on Guile support if the @code{AM_INIT_GUILE_MODULE}
1904 macro is used in @file{configure.in}.
1906 Right now Guile support just means that the @code{AM_INIT_GUILE_MODULE}
1907 macro is understood to mean:
1910 @code{AM_INIT_AUTOMAKE} is run.
1913 @code{AC_CONFIG_AUX_DIR} is run, with a path of @file{..}.
1916 As the Guile module code matures, no doubt the Automake support will
1919 @node Libtool, , Guile, Other GNU Tools
1922 Automake provides support for GNU Libtool (@pxref{Top, , The Libtool
1923 Manual, libtool, The Libtool Manual}) with the @samp{LTLIBRARIES}
1924 primary. @xref{A Shared Library}.
1926 @node Documentation, Install, Other GNU Tools, Top
1927 @chapter Building documentation
1929 Currently Automake provides support for Texinfo and man pages.
1933 * Man pages:: Man pages
1937 @node Texinfo, Man pages, Documentation, Documentation
1940 If the current directory contains Texinfo source, you must declare it
1941 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
1942 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
1943 here. Note that any Texinfo source file must end in the @samp{.texi} or
1944 @samp{.texinfo} extension.
1946 @vindex info_TEXINFOS
1948 If the @samp{.texi} file @code{@@include}s @file{version.texi}, then that
1949 file will be automatically generated. @file{version.texi} defines three
1950 Texinfo macros you can reference: @code{EDITION}, @code{VERSION}, and
1951 @code{UPDATED}. The first two hold the version number of your package
1952 (but are kept separate for clarity); the last is the date the primary
1953 file was last modified. The @file{version.texi} support requires the
1954 @code{mdate-sh} program; this program is supplied with Automake.
1956 Sometimes an info file actually depends on more than one @samp{.texi}
1957 file. For instance, in GNU Hello, @file{hello.texi} includes the file
1958 @file{gpl.texi}. You can tell Automake about these dependencies using
1959 the @samp{@var{texi}_TEXINFOS} variable. Here is how Hello does it:
1964 info_TEXINFOS = hello.texi
1965 hello_TEXINFOS = gpl.texi
1968 By default, Automake requires the file @file{texinfo.tex} to appear in
1969 the same directory as the Texinfo source. However, if you used
1970 @code{AC_CONFIG_AUX_DIR} in @file{configure.in}, then @file{texinfo.tex}
1971 is looked for there. Automake supplies @file{texinfo.tex} if
1972 @samp{--add-missing} is given.
1974 If your package has Texinfo files in many directories, you can use the
1975 variable @code{TEXINFO_TEX} to tell automake where to find the canonical
1976 @file{texinfo.tex} for your package. The value of this variable should
1977 be the relative path from the current @file{Makefile.am} to
1981 TEXINFO_TEX = ../doc/texinfo.tex
1984 The option @samp{no-texinfo.tex} can be used to eliminate the
1985 requirement for @file{texinfo.tex}. Use of the variable
1986 @code{TEXINFO_TEX} is preferable, however, because that allows the
1987 @code{dvi} target to still work.
1989 Automake generates an @code{install-info} target; some people apparently
1990 use this. By default, info pages are installed by @samp{make install}.
1991 This can be prevented via the @code{no-installinfo} option.
1994 @node Man pages, , Texinfo, Documentation
1997 A package can also include man pages. (Though see the GNU standards on
1998 this matter, @ref{Man Pages, , , standards, The GNU Coding
1999 Standards}.) Man pages are declared using the @samp{MANS} primary.
2000 Generally the @code{man_MANS} macro is used. Man pages are
2001 automatically installed in the correct subdirectory of @code{mandir},
2002 based on the file extension.
2006 @c Use @samp{make install} per documentation: (texi)code.
2007 By default, man pages are installed by @samp{make install}. However,
2008 since the GNU project does not require man pages, many maintainers do
2009 not expend effort to keep the man pages up to date. In these cases, the
2010 @code{no-installman} option will prevent the man pages from being
2011 installed by default. The user can still explicitly install them via
2012 @samp{make install-man}.
2013 @opindex no-installman
2014 @trindex install-man
2016 Here is how the documentation is handled in GNU @code{cpio} (which
2017 includes both Texinfo documentation and man pages):
2020 info_TEXINFOS = cpio.texi
2021 man_MANS = cpio.1 mt.1
2024 Texinfo source and info pages are all considered to be source for the
2025 purposes of making a distribution.
2027 Man pages are not currently considered to be source, because it is not
2028 uncommon for man pages to be automatically generated.
2031 @node Install, Clean, Documentation, Top
2032 @chapter What Gets Installed
2034 Naturally, Automake handles the details of actually installing your
2035 program once it has been built. All @code{PROGRAMS}, @code{SCRIPTS},
2036 @code{LIBRARIES}, @code{LISP}, @code{DATA} and @code{HEADERS} are
2037 automatically installed in the appropriate places.
2039 Automake also handles installing any specified info and man pages.
2041 Automake generates separate @code{install-data} and @code{install-exec}
2042 targets, in case the installer is installing on multiple machines which
2043 share directory structure---these targets allow the machine-independent
2044 parts to be installed only once. The @code{install} target depends on
2045 both of these targets.
2046 @trindex install-data
2047 @trindex install-exec
2050 Automake also generates an @code{uninstall} target, and an
2051 @code{installdirs} target.
2053 @trindex installdirs
2055 It is possible to extend this mechanism by defining an
2056 @code{install-exec-local} or @code{install-data-local} target. If these
2057 targets exist, they will be run at @samp{make install} time.
2058 @trindex install-exec-local
2059 @trindex install-data-local
2061 Variables using the standard directory prefixes @samp{data},
2062 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
2063 @samp{pkgdata}, or @samp{pkginclude} (eg @samp{data_DATA}) are installed
2064 by @samp{install-data}.
2066 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
2067 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
2068 @samp{pkglib} (eg @samp{bin_PROGRAMS}) are installed by
2069 @samp{install-exec}.
2071 Any variable using a user-defined directory prefix with @samp{exec} in
2072 the name (eg @samp{myexecbin_PROGRAMS} is installed by
2073 @samp{install-exec}. All other user-defined prefixes are installed by
2074 @samp{install-data}.
2077 @node Clean, Dist, Install, Top
2078 @chapter What Gets Cleaned
2080 The GNU Makefile Standards specify a number of different clean rules.
2082 Generally the files that can cleaned are determined automatically by
2083 Automake. Of course, Automake also recognizes some variables that can
2084 be defined to specify additional files to clean. These variables are
2085 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
2086 @code{MAINTAINERCLEANFILES}.
2087 @vindex MOSTLYCLEANFILES
2089 @vindex DISTCLEANFILES
2090 @vindex MAINTAINERCLEANFILES
2093 @node Dist, Tests, Clean, Top
2094 @chapter What Goes in a Distribution
2096 The @code{dist} target in the generated @file{Makefile.in} can be used
2097 to generate a gzip'd @code{tar} file for distribution. The tar file is
2098 named based on the @samp{PACKAGE} and @samp{VERSION} variables; more
2099 precisely it is named @samp{@var{package}-@var{version}.tar.gz}.
2104 For the most part, the files to distribute are automatically found by
2105 Automake: all source files are automatically included in a distribution,
2106 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
2107 has a built-in list of commonly used files which, if present in the
2108 current directory, are automatically included. This list is printed by
2109 @samp{automake --help}. Also, files which are read by @code{configure}
2110 (ie, the source files corresponding to the files specified in the
2111 @code{AC_OUTPUT} invocation) are automatically distributed.
2113 Still, sometimes there are files which must be distributed, but which
2114 are not covered in the automatic rules. These files should be listed in
2115 the @code{EXTRA_DIST} variable. Note that @code{EXTRA_DIST} can only
2116 handle files in the current directory; files in other directories will
2117 cause @code{make dist} runtime failures.
2120 If you define @code{SUBDIRS}, automake will recursively include the
2121 subdirectories in the distribution. If @code{SUBDIRS} is defined
2122 conditionally (@pxref{Conditionals}), automake will normally include all
2123 directories that could possibly appear in @code{SUBDIRS} in the
2124 distribution. If you need to specify the set of directories
2125 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
2126 list of subdirectories to include in the distribution.
2127 @vindex DIST_SUBDIRS
2129 Occasionally it is useful to be able to change the distribution before
2130 it is packaged up. If the @code{dist-hook} target exists, it is run
2131 after the distribution directory is filled, but before the actual tar
2132 (or shar) file is created. One way to use this is for distributing
2133 files in subdirectories for which a new @file{Makefile.am} is overkill:
2137 mkdir $(distdir)/random
2138 cp -p random/a1 random/a2 $(distdir)/random
2141 Automake also generates a @code{distcheck} target which can be help to
2142 ensure that a given distribution will actually work. @code{distcheck}
2143 makes a distribution, and then tries to do a @code{VPATH} build.
2145 @c FIXME: document distcheck-hook here
2147 @node Tests, Options, Dist, Top
2148 @chapter Support for test suites
2150 Automake supports a two forms of test suite.
2152 If the variable @code{TESTS} is defined, its value is taken to be a list
2153 of programs to run in order to do the testing. The programs can either
2154 be derived objects or source objects; the generated rule will look both
2155 in @var{srcdir} and @file{.}.
2157 The number of failures will be printed at the end of the run. If a
2158 given test program exits with a status of 77, then its result is ignored
2159 in the final count. This feature allows non-portable tests to be
2160 ignored in environments where they don't make sense.
2162 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
2163 variables for the test run; the environment variable @code{srcdir} is
2164 set in the rule. If all your test programs are scripts, you can also
2165 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (eg
2166 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
2168 @vindex TESTS_ENVIRONMENT
2170 If @samp{dejagnu} appears in @code{AUTOMAKE_OPTIONS}, then the a
2171 @code{dejagnu}-based test suite is assumed. The value of the variable
2172 @code{DEJATOOL} is passed as the @code{--tool} argument to
2173 @code{runtest}; it defaults to the name of the package.
2175 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
2176 @code{--srcdir} flags that are passed to dejagnu by default; this can be
2177 overridden if necessary.
2178 @vindex RUNTESTDEFAULTFLAGS
2180 The variables @code{EXPECT}, @code{RUNTEST} and @code{RUNTESTFLAGS} can
2181 also be overridden to provide project-specific values. For instance,
2182 you will need to do this if you are testing a compiler toolchain,
2183 because the default values do not take into account host and target
2189 @vindex RUNTESTFLAGS
2190 @c FIXME xref dejagnu
2192 In either case, the testing is done via @samp{make check}.
2195 @node Options, Miscellaneous, Tests, Top
2196 @chapter Changing Automake's Behavior
2198 Various features of Automake can be controlled by options in the
2199 @file{Makefile.am}. Such options are listed in a special variable named
2200 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
2201 @vindex AUTOMAKE_OPTIONS
2206 @itemx @code{foreign}
2207 Set the strictness as appropriate.
2209 @item @code{no-installman}
2210 The generated @file{Makefile.in} will not cause man pages to be
2211 installed by default. However, an @code{install-man} target will still
2212 be available for optional installation. This option is disallowed at
2213 @samp{GNU} strictness and above.
2214 @trindex install-man
2216 @item @code{no-installinfo}
2217 The generated @file{Makefile.in} will not cause info pages to be built
2218 or installed by default. However, @code{info} and @code{install-info}
2219 targets will still be available. This option is disallowed at
2220 @samp{GNU} strictness and above.
2222 @trindex install-info
2224 @item @code{ansi2knr}
2225 @itemx @code{path/ansi2knr}
2226 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceeded by a
2227 path, the generated @file{Makefile.in} will look in the specified
2228 directory to find the @file{ansi2knr} program. Generally the path
2229 should be a relative path to another directory in the same distribution
2230 (though Automake currently does not check this).
2232 @item @code{dejagnu}
2233 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
2235 @item @code{dist-shar}
2236 Generate a @code{dist-shar} target as well as the ordinary @code{dist}
2237 target. This new target will create a shar archive of the
2241 @item @code{dist-zip}
2242 Generate a @code{dist-zip} target as well as the ordinary @code{dist}
2243 target. This new target will create a zip archive of the distribution.
2246 @item @code{dist-tarZ}
2247 Generate a @code{dist-tarZ} target as well as the ordinary @code{dist}
2248 target. This new target will create a compressed tar archive of the
2249 distribution; a traditional @code{tar} and @code{compress} will be
2250 assumed. Warning: if you are actually using @code{GNU tar}, then the
2251 generated archive might contain nonportable constructs.
2254 @item @code{no-dependencies}
2255 This is similar to using @samp{--include-deps} on the command line, but
2256 is useful for those situations where you don't have the necessary bits
2257 to make automatic dependency tracking work @xref{Dependencies}. In this
2258 case the effect is to effectively disable automatic dependency tracking.
2260 @item @code{no-texinfo.tex}
2261 Don't require @file{texinfo.tex}, even if there are texinfo files in
2265 A version number (eg @samp{0.30}) can be specified. If Automake is not
2266 newer than the version specified, creation of the @file{Makefile.in}
2270 Unrecognized options are diagnosed by @code{automake}.
2273 @node Miscellaneous, Conditionals, Options, Top
2274 @chapter Miscellaneous Rules
2276 There are a few rules and variables that didn't fit anywhere else.
2279 * Tags:: Interfacing to etags and mkid
2280 * Suffixes:: Handling new file extensions
2284 @node Tags, Suffixes, Miscellaneous, Miscellaneous
2285 @section Interfacing to @code{etags}
2287 @code{automake} will generate rules to generate @file{TAGS} files for
2288 use with GNU Emacs under some circumstances.
2290 If any C source code or headers are present, then @code{tags} and
2291 @code{TAGS} targets will be generated for the directory.
2294 At the topmost directory of a multi-directory package, a @code{tags}
2295 target file will be generated which, when run, will generate a
2296 @file{TAGS} file that includes by reference all @file{TAGS} files from
2299 Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
2300 will be generated. This variable is intended for use in directories
2301 which contain taggable source that @code{etags} does not understand.
2304 Here is how Automake generates tags for its source, and for nodes in its
2308 ETAGS_ARGS = automake.in --lang=none \
2309 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
2312 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
2313 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
2314 are added directly to the dependencies for the @code{tags} target.
2315 @vindex TAGS_DEPENDENCIES
2317 Automake will also generate an @code{ID} target which will run
2318 @code{mkid} on the source. This is only supported on a
2319 directory-by-directory basis.
2323 @node Suffixes, , Tags, Miscellaneous
2324 @section Handling new file extensions
2326 It is sometimes useful to introduce a new implicit rule to handle a file
2327 type that Automake does not know about. If this is done, you must
2328 notify GNU Make of the new suffixes. This can be done by putting a list
2329 of new suffixes in the @code{SUFFIXES} variable.
2332 For instance, currently automake does not provide any Java support. If
2333 you wrote a macro to generate @samp{.class} files from @samp{.java}
2334 source files, you would also need to add these suffixes to the list:
2337 SUFFIXES = .java .class
2340 @node Conditionals, Gnits, Miscellaneous, Top
2341 @chapter Conditionals
2343 Automake supports a simple type of conditionals.
2345 @cvindex AM_CONDITIONAL
2346 Before using a conditional, you must define it by using
2347 @code{AM_CONDITIONAL} in the @code{configure.in} file. The
2348 @code{AM_CONDITIONAL} macro takes two arguments.
2350 The first argument to @code{AM_CONDITIONAL} is the name of the
2351 conditional. This should be a simple string starting with a letter and
2352 containing only letters, digits, and underscores.
2354 The second argument to @code{AM_CONDITIONAL} is a shell condition,
2355 suitable for use in a shell if statement. The condition is evaluated
2356 when @code{configure} is run.
2358 Conditionals typically depend upon options which the user provides to
2359 the @code{configure} script. Here is an example of how to write a
2360 conditional which is true if the user uses the @samp{--enable-debug}
2364 AC_ARG_ENABLE(debug,
2365 [ --enable-debug Turn on debugging],
2366 [case "$@{enableval@}" in
2369 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
2370 esac],[debug=false])
2371 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
2374 Here is an example of how to use that conditional in @file{Makefile.am}:
2382 noinst_PROGRAMS = $(DBG)
2385 This trivial example could also be handled using EXTRA_PROGRAMS
2386 (@pxref{A Program}).
2388 You may only test a single variable in an @code{if} statement. The
2389 @code{else} statement may be omitted. Conditionals may be nested to any
2392 Note that conditionals in Automake are not the same as conditionals in
2393 GNU Make. Automake conditionals are checked at configure time by the
2394 @file{configure} script, and affect the translation from
2395 @file{Makefile.in} to @file{Makefile}. They are based on options passed
2396 to @file{configure} and on results that @file{configure} has discovered
2397 about the host system. GNU Make conditionals are checked at make time,
2398 and are based on variables passed to the make program or defined in the
2401 Automake conditionals will work with any make program.
2403 @node Gnits, Cygnus, Conditionals, Top
2404 @chapter The effect of @code{--gnu} and @code{--gnits}
2406 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
2407 variable) causes @code{automake} to check the following:
2411 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
2412 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
2413 directory of the package.
2416 The options @samp{no-installman} and @samp{no-installinfo} are
2420 Note that this option will be extended in the future to do even more
2421 checking; it is advisable to be familiar with the precise requirements
2422 of the GNU standards. Also, @samp{--gnu} can require certain
2423 non-standard GNU programs to exist for use by various maintainer-only
2424 targets; for instance in the future @code{pathchk} might be required for
2427 The @samp{--gnits} option does everything that @samp{--gnu} does, and
2428 checks the following as well:
2432 @samp{make dist} will check to make sure the @file{NEWS} file has been
2433 updated to the current version.
2436 The file @file{COPYING.LIB} is prohibited. The LGPL is apparently
2437 considered a failed experiment.
2440 @samp{VERSION} is checked to make sure its format complies with Gnits
2442 @c FIXME xref when standards are finished
2445 If @samp{VERSION} indicates that this is an alpha release, and the file
2446 @file{README-alpha} appears in the topmost directory of a package, then
2447 it is included in the distribution. This is done in @samp{--gnits}
2448 mode, and no other, because this mode is the only one where version
2449 number formats are constrained, and hence the only mode where
2450 @code{automake} can automatically determine whether @file{README-alpha}
2454 The file @file{THANKS} is required.
2458 @node Cygnus, Extending, Gnits, Top
2459 @chapter The effect of @code{--cygnus}
2461 Cygnus Solutions has slightly different rules for how a
2462 @file{Makefile.in} is to be constructed. Passing @samp{--cygnus} to
2463 @code{automake} will cause any generated @file{Makefile.in} to comply
2466 Here are the precise effects of @samp{--cygnus}:
2470 Info files are always created in the build directory, and not in the
2474 @file{texinfo.tex} is not required if a Texinfo source file is
2475 specified. The assumption is that the file will be supplied, but in a
2476 place that @code{automake} cannot find. This assumption is an artifact
2477 of how Cygnus packages are typically bundled.
2480 @samp{make dist} will look for files in the build directory as well as
2481 the source directory. This is required to support putting info files
2482 into the build directory.
2485 Certain tools will be searched for in the build tree as well as in the
2486 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
2487 @code{makeinfo} and @code{texi2dvi}.
2490 @code{--foreign} is implied.
2493 The options @samp{no-installinfo} and @samp{no-dependencies} are
2497 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
2501 The @code{check} target doesn't depend on @code{all}.
2504 GNU maintainers are advised to use @samp{gnu} strictness in preference
2505 to the special Cygnus mode.
2508 @node Extending, Distributing, Cygnus, Top
2509 @chapter When Automake Isn't Enough
2511 Automake's implicit copying semantics means that many problems can be
2512 worked around by simply adding some @code{make} targets and rules to
2513 @file{Makefile.in}. @code{automake} will ignore these additions.
2515 There are some caveats to doing this. Although you can overload a
2516 target already used by @code{automake}, it is often inadvisable,
2517 particularly in the topmost directory of a non-flat package. However,
2518 various useful targets have a @samp{-local} version you can specify in your
2519 @file{Makefile.in}. Automake will supplement the standard target with
2520 these user-supplied targets.
2522 The targets that support a local version are @code{all}, @code{info},
2523 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
2524 @code{uninstall}, and the various @code{clean} targets
2525 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
2526 @code{maintainer-clean}). Note that there are no
2527 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
2528 use @code{uninstall-local}. It doesn't make sense to uninstall just
2529 data or just executables.
2534 @trindex install-data
2535 @trindex install-exec
2538 For instance, here is one way to install a file in @file{/etc}:
2542 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
2545 Some targets also have a way to run another target, called a @dfn{hook},
2546 after their work is done. The hook is named after the principal target,
2547 with @samp{-hook} appended. The targets allowing hooks are
2548 @code{install-data}, @code{install-exec}, @code{dist}, and
2550 @trindex install-data-hook
2551 @trindex install-exec-hook
2554 For instance, here is how to create a hard link to an installed program:
2558 ln $(bindir)/program $(bindir)/proglink
2561 @c FIXME should include discussion of variables you can use in these
2565 @node Distributing, Future, Extending, Top
2566 @chapter Distributing @file{Makefile.in}s
2568 Automake places no restrictions on the distribution of the resulting
2569 @file{Makefile.in}s. We still encourage software authors to distribute
2570 their work under terms like those of the GPL, but doing so is not
2571 required to use Automake.
2573 Some of the files that can be automatically installed via the
2574 @code{--add-missing} switch do fall under the GPL; examine each file
2578 @node Future, Index, Distributing, Top
2579 @chapter Some ideas for the future
2581 Here are some things that might happen in the future:
2588 The output will be cleaned up. For instance, only variables which are
2589 actually used will appear in the generated @file{Makefile.in}.
2592 There will be support for automatically recoding a distribution. The
2593 intent is to allow a maintainer to use whatever character set is most
2594 convenient locally, but for all distributions to be Unicode or
2595 @w{ISO 10646} with the UTF-8 encoding.
2598 Support for automatically generating packages (eg Debian packages, RPM
2599 packages, Solaris packages, etc). This will happen more quickly if
2600 someone with package-building experience can tell me what would be
2604 Rewrite in Guile. This won't happen in the near future, but it will
2608 @node Index, , Future, Top