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, 98 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
177 Building documentation
180 * Man pages:: Man pages
184 * Tags:: Interfacing to etags and mkid
185 * Suffixes:: Handling new file extensions
190 @node Introduction, Generalities, Top, Top
191 @chapter Introduction
193 Automake is a tool for automatically generating @file{Makefile.in}s from
194 files called @file{Makefile.am}. Each @file{Makefile.am} is basically a
195 series of @code{make} macro definitions (with rules being thrown in
196 occasionally). The generated @file{Makefile.in}s are compliant with the
197 GNU Makefile standards.
199 The GNU Makefile Standards Document
200 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
201 is long, complicated, and subject to change. The goal of Automake is to
202 remove the burden of Makefile maintenance from the back of the
203 individual GNU maintainer (and put it on the back of the Automake
206 The typical Automake input files is simply a series of macro
207 definitions. Each such file is processed to create a
208 @file{Makefile.in}. There should generally be one @file{Makefile.am}
209 per directory of a project.
211 Automake does constrain a project in certain ways; for instance it
212 assumes that the project uses Autoconf
213 (@pxref{Top, , The Autoconf Manual, autoconf, The Autoconf Manual}),
214 and enforces certain restrictions on the @file{configure.in} contents.
216 Automake requires @code{perl} in order to generate the
217 @file{Makefile.in}s. However, the distributions created by Automake are
218 fully GNU standards-compliant, and do not require @code{perl} in order
221 Mail suggestions and bug reports for Automake to
222 @email{automake-bugs@@gnu.org}.
225 @node Generalities, Examples, Introduction, Top
226 @chapter General ideas
228 There are a few basic ideas that will help understand how Automake
232 * General Operation:: General operation of Automake
233 * Depth:: The kinds of packages
234 * Strictness:: Standards conformance checking
235 * Uniform:: The Uniform Naming Scheme
236 * Canonicalization:: How derived variables are named
239 @node General Operation, Depth, Generalities, Generalities
240 @section General Operation
242 Automake works by reading a @file{Makefile.am} and generating a
243 @file{Makefile.in}. Certain macros and targets defined in the
244 @file{Makefile.am} instruct automake to generate more specialized code;
245 for instances a @samp{bin_PROGRAMS} macro definition will cause targets
246 for compiling and linking to be generated.
248 The macro definitions and targets in the @file{Makefile.am} are copied
249 into the generated file. This allows you to add arbitrary code into the
250 generated @file{Makefile.in}. For instance the Automake distribution
251 includes a non-standard @code{cvs-dist} target, which the Automake
252 maintainer uses to make distributions from his source control system.
254 Note that GNU make extensions are not recognized by Automake. Using
255 such extensions in a @file{Makefile.am} will lead to errors or confusing
258 Automake tries to group comments with adjoining targets (or variable
259 definitions) in an intelligent way.
261 A target defined in @file{Makefile.am} generally overrides any such
262 target of a similar name that would be automatically generated by
263 @code{automake}. Although this is a supported feature, it is generally
264 best to avoid making use of it, as sometimes the generated rules are
267 Similarly, a variable defined in @file{Makefile.am} will override any
268 definition of the variable that @code{automake} would ordinarily create.
269 This feature is more often useful than the ability to override a target
270 definition. Be warned that many of the variables generated by
271 @code{automake} are considered to be for internal use only, and their
272 names might change in future releases.
274 When examining a variable definition, Automake will recursively examine
275 variables referenced in the definition. E.g., if Automake is looking at
276 the content of @samp{foo_SOURCES} in this snippet
280 foo_SOURCES = c.c $(xs)
283 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
284 contents of @samp{foo_SOURCES}.
286 Automake also allows a form of comment which is @emph{not} copied into
287 the output; all lines beginning with @samp{##} are completely ignored by
290 It is customary to make the first line of @file{Makefile.am} read:
293 ## Process this file with automake to produce Makefile.in
296 @c FIXME discuss putting a copyright into Makefile.am here? I would but
297 @c I don't know quite what to say.
299 @c FIXME document customary ordering of Makefile.am here!
303 @node Depth, Strictness, General Operation, Generalities
305 @code{automake} supports three kinds of directory hierarchy: ``flat'',
306 ``shallow'', and ``deep''.
308 A @dfn{flat} package is one in which all the files are in a single
309 directory. The @file{Makefile.am} for such a package by definition
310 lacks a @code{SUBDIRS} macro. An example of such a package is
314 A @dfn{deep} package is one in which all the source lies in
315 subdirectories; the top level directory contains mainly configuration
316 information. GNU cpio is a good example of such a package, as is GNU
317 @code{tar}. The top level @file{Makefile.am} for a deep package will
318 contain a @code{SUBDIRS} macro, but no other macros to define objects
321 A @dfn{shallow} package is one in which the primary source resides in
322 the top-level directory, while various parts (typically libraries)
323 reside in subdirectories. Automake is one such package (as is GNU
324 @code{make}, which does not currently use @code{automake}).
327 @node Strictness, Uniform, Depth, Generalities
329 While Automake is intended to be used by maintainers of GNU packages, it
330 does make some effort to accommodate those who wish to use it, but do
331 not want to use all the GNU conventions.
333 To this end, Automake supports three levels of @dfn{strictness}---the
334 strictness indicating how stringently Automake should check standards
337 The valid strictness levels are:
341 Automake will check for only those things which are absolutely
342 required for proper operations. For instance, whereas GNU standards
343 dictate the existence of a @file{NEWS} file, it will not be required in
344 this mode. The name comes from the fact that Automake is intended to be
345 used for GNU programs; these relaxed rules are not the standard mode of
349 Automake will check---as much as possible---for compliance to the GNU
350 standards for packages. This is the default.
353 Automake will check for compliance to the as-yet-unwritten Gnits
354 standards. These are based on the GNU standards, but are even more
355 detailed. Unless you are a Gnits standards contributor, it is
356 recommended that you avoid this option until such time as the Gnits
357 standard is actually published.
360 For more information on the precise implications of the strictness
361 level, see @xref{Gnits}.
364 @node Uniform, Canonicalization, Strictness, Generalities
365 @section The Uniform Naming Scheme
366 Automake variables generally follow a uniform naming scheme that makes
367 it easy to decide how programs (and other derived objects) are built,
368 and how they are installed. This scheme also supports @code{configure}
369 time determination of what should be built.
371 At @code{make} time, certain variables are used to determine which
372 objects are to be built. These variables are called @dfn{primary}
373 variables. For instance, the primary variable @code{PROGRAMS} holds a
374 list of programs which are to be compiled and linked.
377 A different set of variables is used to decide where the built objects
378 should be installed. These variables are named after the primary
379 variables, but have a prefix indicating which standard directory should
380 be used as the installation directory. The standard directory names are
381 given in the GNU standards
382 (@pxref{Directory Variables, , , standards, The GNU Coding
384 Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
385 and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
386 versions, but with @samp{@@PACKAGE@@} appended. For instance,
387 @code{pkglibdir} is defined as @code{$(datadir)/@@PACKAGE@@}.
390 For each primary, there is one additional variable named by prepending
391 @samp{EXTRA_} to the primary name. This variable is used to list
392 objects which may or may not be built, depending on what
393 @code{configure} decides. This variable is required because Automake
394 must statically know the entire list of objects to be built in order to
395 generate a @file{Makefile.in} that will work in all cases.
397 For instance, @code{cpio} decides at configure time which programs are
398 built. Some of the programs are installed in @code{bindir}, and some
399 are installed in @code{sbindir}:
402 EXTRA_PROGRAMS = mt rmt
403 bin_PROGRAMS = cpio pax
404 sbin_PROGRAMS = @@PROGRAMS@@
407 Defining a primary variable without a prefix (eg @code{PROGRAMS}) is an
410 Note that the common @samp{dir} suffix is left off when constructing the
411 variable names; thus one writes @samp{bin_PROGRAMS} and not
412 @samp{bindir_PROGRAMS}.
414 Not every sort of object can be installed in every directory. Automake
415 will flag those attempts it finds in error. Automake will also diagnose
416 obvious misspellings in directory names.
418 Sometimes the standard directories---even as augmented by Automake---
419 are not enough. In particular it is sometimes useful, for clarity, to
420 install objects in a subdirectory of some predefined directory. To this
421 end, Automake allows you to extend the list of possible installation
422 directories. A given prefix (eg @samp{zar}) is valid if a variable of
423 the same name with @samp{dir} appended is defined (eg @samp{zardir}).
425 For instance, until HTML support is part of Automake, you could use this
426 to install raw HTML documentation:
429 htmldir = $(prefix)/html
430 html_DATA = automake.html
433 The special prefix @samp{noinst} indicates that the objects in question
434 should not be installed at all.
436 The special prefix @samp{check} indicates that the objects in question
437 should not be built until the @code{make check} command is run.
439 Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
440 @samp{LISP}, @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS},
452 @node Canonicalization, , Uniform, Generalities
453 @section How derived variables are named
455 Sometimes a Makefile variable name is derived from some text the user
456 supplies. For instance program names are rewritten into Makefile macro
457 names. Automake canonicalizes this text, so that it does not have to
458 follow Makefile variable naming rules. All characters in the name
459 except for letters, numbers, and the underscore are turned into
460 underscores when making macro references. E.g., if your program is named
461 @code{sniff-glue}, the derived variable name would be
462 @code{sniff_glue_SOURCES}, not @code{sniff-glue_SOURCES}.
465 @node Examples, Invoking Automake, Generalities, Top
466 @chapter Some example packages
469 * Complete:: A simple example, start to finish
470 * Hello:: A classic program
471 * etags:: Building etags and ctags
474 @node Complete, Hello, Examples, Examples
475 @section A simple example, start to finish
477 Let's suppose you just finished writing @code{zardoz}, a program to make
478 your head float from vortex to vortex. You've been using
479 @code{autoconf} to provide a portability framework, but your
480 @file{Makefile.in}s have been ad-hoc. You want to make them
481 bulletproof, so you turn to @code{automake}.
483 The first step is to update your @file{configure.in} to include the
484 commands that @code{automake} needs. The simplest way to do this is to
485 add an @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
488 AM_INIT_AUTOMAKE(zardoz, 1.0)
491 Since your program doesn't have any complicating factors (e.g., it
492 doesn't use @code{gettext}, it doesn't want to build a shared library),
493 you're done with this part. That was easy!
495 Now you must regenerate @file{configure}. But to do that, you'll need
496 to tell @code{autoconf} how to find the new macro you've used. The
497 easiest way to do this is to use the @code{aclocal} program to generate
498 your @file{aclocal.m4} for you. But wait... you already have an
499 @file{aclocal.m4}, because you had to write some hairy macros for your
500 program. @code{aclocal} lets you put your own macros into
501 @file{acinclude.m4}, so simply rename and then run:
504 mv aclocal.m4 acinclude.m4
509 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
510 @code{zardoz} is a user program, so you want to install it where the
511 rest of the user programs go. @code{zardoz} also has some Texinfo
512 documentation. Your @file{configure.in} script uses
513 @code{AC_REPLACE_FUNCS}, so you need to link against @samp{@@LIBOBJS@@}.
514 So here's what you'd write:
517 bin_PROGRAMS = zardoz
518 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
519 zardoz_LDADD = @@LIBOBJS@@
521 info_TEXINFOS = zardoz.texi
524 Now you can run @code{automake --add-missing} to generate your
525 @file{Makefile.in} and grab any auxiliary files you might need, and
529 @node Hello, etags, Complete, Examples
530 @section A classic program
532 @code{hello} is renowned for its classic simplicity and versatility.
533 This section shows how Automake could be used with the Hello package.
534 The examples below are from the latest GNU Hello, but all the
535 maintainer-only code has been stripped out, as well as all copyright
538 Of course, GNU Hello is somewhat more featureful than your traditional
539 two-liner. GNU Hello is internationalized, does option processing, and
540 has a manual and a test suite. GNU Hello is a deep package.
542 Here is the @file{configure.in} from GNU Hello:
545 dnl Process this file with autoconf to produce a configure script.
547 AM_INIT_AUTOMAKE(hello, 1.3.11)
548 AM_CONFIG_HEADER(config.h)
550 dnl Set of available languages.
551 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
553 dnl Checks for programs.
557 dnl Checks for libraries.
559 dnl Checks for header files.
561 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
563 dnl Checks for library functions.
566 dnl Check for st_blksize in struct stat
569 dnl internationalization macros
571 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
572 src/Makefile tests/Makefile tests/hello],
573 [chmod +x tests/hello])
576 The @samp{AM_} macros are provided by Automake (or the Gettext library);
577 the rest are standard Autoconf macros.
580 The top-level @file{Makefile.am}:
583 EXTRA_DIST = BUGS ChangeLog.O
584 SUBDIRS = doc intl po src tests
587 As you can see, all the work here is really done in subdirectories.
589 The @file{po} and @file{intl} directories are automatically generated
590 using @code{gettextize}; they will not be discussed here.
592 In @file{doc/Makefile.am} we see:
595 info_TEXINFOS = hello.texi
596 hello_TEXINFOS = gpl.texi
599 This is sufficient to build, install, and distribute the Hello manual.
602 Here is @file{tests/Makefile.am}:
606 EXTRA_DIST = hello.in testdata
609 The script @file{hello} is generated by @code{configure}, and is the
610 only test case. @code{make check} will run this test.
612 Last we have @file{src/Makefile.am}, where all the real work is done:
616 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
617 hello_LDADD = @@INTLLIBS@@ @@ALLOCA@@
618 localedir = $(datadir)/locale
619 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
623 @node etags, , Hello, Examples
624 @section Building etags and ctags
626 Here is another, trickier example. It shows how to generate two
627 programs (@code{ctags} and @code{etags}) from the same source file
628 (@file{etags.c}). The difficult part is that each compilation of
629 @file{etags.c} requires different @code{cpp} flags.
632 bin_PROGRAMS = etags ctags
634 ctags_LDADD = ctags.o
637 $(COMPILE) -DETAGS_REGEXPS -c etags.c
640 $(COMPILE) -DCTAGS -o ctags.o -c etags.c
643 Note that @code{ctags_SOURCES} is defined to be empty---that way no
644 implicit value is substituted. The implicit value, however, is used to
645 generate @code{etags} from @file{etags.o}.
647 @code{ctags_LDADD} is used to get @file{ctags.o} into the link line.
648 @code{ctags_DEPENDENCIES} is generated by Automake.
650 The above rules won't work if your compiler doesn't accept both
651 @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
652 bogus dependency (to avoid problems with a parallel @code{make}):
655 etags.o: etags.c ctags.o
656 $(COMPILE) -DETAGS_REGEXPS -c etags.c
659 $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
662 Also, these explicit rules do not work if the de-ANSI-fication feature
663 is used; supporting that requires a little more work:
666 etags._o: etags._c ctags.o
667 $(COMPILE) -DETAGS_REGEXPS -c etags.c
670 $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
674 @node Invoking Automake, configure, Examples, Top
675 @chapter Creating a @file{Makefile.in}
677 To create all the @file{Makefile.in}s for a package, run the
678 @code{automake} program in the top level directory, with no arguments.
679 @code{automake} will automatically find each appropriate
680 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
681 and generate the corresponding @file{Makefile.in}. Note that
682 @code{automake} has a rather simplistic view of what constitutes a
683 package; it assumes that a package has only one @file{configure.in}, at
684 the top. If your package has multiple @file{configure.in}s, then you
685 must run @code{automake} in each directory holding a
688 You can optionally give @code{automake} an argument; @samp{.am} is
689 appended to the argument and the result is used as the name of the input
690 file. This feature is generally only used to automatically rebuild an
691 out-of-date @file{Makefile.in}. Note that @code{automake} must always
692 be run from the topmost directory of a project, even if being used to
693 regenerate the @file{Makefile.in} in some subdirectory. This is
694 necessary because @code{automake} must scan @file{configure.in}, and
695 because @code{automake} uses the knowledge that a @file{Makefile.in} is
696 in a subdirectory to change its behavior in some cases.
698 @code{automake} accepts the following options:
703 Automake requires certain common files to exist in certain situations;
704 for instance @file{config.guess} is required if @file{configure.in} runs
705 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
706 files; this option will cause the missing ones to be automatically added
707 to the package, whenever possible. In general if Automake tells you a
708 file is missing, try using this option.
710 @item --amdir=@var{dir}
711 Look for Automake data files in directory @var{dir} instead of in the
712 installation directory. This is typically used for debugging.
714 @item --build-dir=@var{dir}
715 Tell Automake where the build directory is. This option is used when
716 including dependencies into a @file{Makefile.in} generated by @code{make
717 dist}; it should not be used otherwise.
720 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
721 of GNU or Gnits rules. @xref{Cygnus} for more information.
724 Set the global strictness to @samp{foreign}. @xref{Strictness} for more
728 Set the global strictness to @samp{gnits}. @xref{Gnits} for more
732 Set the global strictness to @samp{gnu}. @xref{Gnits} for more
733 information. This is the default strictness.
736 Print a summary of the command line options and exit.
739 @itemx --include-deps
740 Include all automatically generated dependency information
741 (@pxref{Dependencies}) in the generated
742 @file{Makefile.in}. This is generally done when making a distribution;
745 @item --generate-deps
746 Generate a file concatenating all automatically generated dependency
747 information (@pxref{Dependencies}) into one file, @file{.dep_segment}.
748 This is generally done when making a distribution; see @ref{Dist}. It
749 is useful when maintaining a @file{SMakefile} or makefiles for other
750 platforms (@file{Makefile.DOS}, etc.) It can only be used in
751 conjunction with @code{--include-deps}, @code{--srcdir-name}, and
752 @code{--build-dir}. Note that if this option is given, no other
756 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
757 @file{configure.in}. This option causes it to only update those
758 @file{Makefile.in}s which are out of date with respect to one of their
762 @itemx --output-dir=@var{dir}
763 Put the generated @file{Makefile.in} in the directory @var{dir}.
764 Ordinarily each @file{Makefile.in} is created in the directory of the
765 corresponding @file{Makefile.am}. This option is used when making
768 @item --srcdir-name=@var{dir}
769 Tell Automake the name of the source directory associated with the
770 current build. This option is used when including dependencies into a
771 @file{Makefile.in} generated by @code{make dist}; it should not be used
776 Cause Automake to print information about which files are being read or
780 Print the version number of Automake and exit.
784 @node configure, Top level, Invoking Automake, Top
785 @chapter Scanning @file{configure.in}
787 Automake scans the package's @file{configure.in} to determine certain
788 information about the package. Some @code{autoconf} macros are required
789 and some variables must be defined in @file{configure.in}. Automake
790 will also use information from @file{configure.in} to further tailor its
793 Automake also supplies some @code{autoconf} macros to make the
794 maintenance easier. These macros can automatically be put into your
795 @file{aclocal.m4} using the @code{aclocal} program.
798 * Requirements:: Configuration requirements
799 * Optional:: Other things Automake recognizes
800 * Invoking aclocal:: Auto-generating aclocal.m4
801 * Macros:: Autoconf macros supplied with Automake
802 * Extending aclocal:: Writing your own aclocal macros
806 @node Requirements, Optional, configure, configure
807 @section Configuration requirements
809 The simplest way to meet the basic Automake requirements is to use the
810 macro @code{AM_INIT_AUTOMAKE} (@pxref{Macros}). But if you prefer, you
811 can do the required steps by hand:
812 @cvindex AM_INIT_AUTOMAKE
816 Define the variables @code{PACKAGE} and @code{VERSION} with
820 @code{PACKAGE} should be the name of the package as it appears when
821 bundled for distribution. For instance, Automake defines @code{PACKAGE}
822 to be @samp{automake}. @code{VERSION} should be the version number of
823 the release that is being developed. We recommend that you make
824 @file{configure.in} the only place in your package where the version
825 number is defined; this makes releases simpler.
827 Automake doesn't do any interpretation of @code{PACKAGE} or
828 @code{VERSION}, except in @samp{Gnits} mode (@pxref{Gnits}).
831 Use the macro @code{AC_ARG_PROGRAM} if a program or script is installed.
832 @cvindex AC_ARG_PROGRAM
835 Use @code{AC_PROG_MAKE_SET} if the package is not flat.
836 @cvindex AC_PROG_MAKE_SET
839 Use @code{AM_SANITY_CHECK} to make sure the build environment is sane.
842 Use @code{AM_PROG_INSTALL} if any scripts (@pxref{Scripts}) are
843 installed by the package. Otherwise, use @code{AC_PROG_INSTALL}.
844 @cvindex AC_PROG_INSTALL
845 @cvindex AM_PROG_INSTALL
848 Use @code{AM_MISSING_PROG} to see whether the programs @code{aclocal},
849 @code{autoconf}, @code{automake}, @code{autoheader}, and @code{makeinfo}
850 are in the build environment. Here is how this is done:
852 missing_dir=`cd $ac_aux_dir && pwd`
853 AM_MISSING_PROG(ACLOCAL, aclocal, $missing_dir)
854 AM_MISSING_PROG(AUTOCONF, autoconf, $missing_dir)
855 AM_MISSING_PROG(AUTOMAKE, automake, $missing_dir)
856 AM_MISSING_PROG(AUTOHEADER, autoheader, $missing_dir)
857 AM_MISSING_PROG(MAKEINFO, makeinfo, $missing_dir)
862 Here are the other macros which Automake requires but which are not run
863 by @code{AM_INIT_AUTOMAKE}:
867 Automake uses this to determine which files to create. Listed files
868 named @code{Makefile} are treated as @file{Makefile}s. Other listed
869 files are treated differently. Currently the only difference is that a
870 @file{Makefile} is removed by @code{make distclean}, while other files
871 are removed by @code{make clean}.
872 @c FIXME: this is in violation of standards!
876 @node Optional, Invoking aclocal, Requirements, configure
877 @section Other things Automake recognizes
879 Automake will also recognize the use of certain macros and tailor the
880 generated @file{Makefile.in} appropriately. Currently recognized macros
881 and their effects are:
884 @item AC_CONFIG_HEADER
885 Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar
886 to @code{AC_CONFIG_HEADER} but does some useful Automake-specific work.
887 @cvindex AC_CONFIG_HEADER
889 @item AC_CONFIG_AUX_DIR
890 Automake will look for various helper scripts, such as
891 @file{mkinstalldirs}, in the directory named in this macro invocation.
892 If not seen, the scripts are looked for in their ``standard'' locations
893 (either the top source directory, or in the source directory
894 corresponding to the current @file{Makefile.am}, whichever is
896 @cvindex AC_CONFIG_AUX_DIR
897 FIXME: give complete list of things looked for in this directory
900 Automake will insert definitions for the variables defined by
901 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
903 @cvindex AC_PATH_XTRA
905 @item AC_CANONICAL_HOST
907 Automake will ensure that @file{config.guess} and @file{config.sub}
908 exist. Also, the @file{Makefile} variables @samp{host_alias} and
909 @samp{host_triplet} are introduced.
910 @c fixme xref autoconf docs.
911 @cvindex AC_CANONICAL_HOST
912 @cvindex AC_CHECK_TOOL
916 @item AC_CANONICAL_SYSTEM
917 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
918 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
919 @cvindex AC_CANONICAL_SYSTEM
924 @itemx AC_FUNC_GETLOADAVG
925 @itemx AC_FUNC_MEMCMP
926 @itemx AC_STRUCT_ST_BLOCKS
927 @itemx AC_FUNC_FNMATCH
928 @itemx AM_FUNC_STRTOD
929 @itemx AC_REPLACE_FUNCS
930 @itemx AC_REPLACE_GNU_GETOPT
932 Automake will ensure that the appropriate dependencies are generated for
933 the objects corresponding to these macros. Also, Automake will verify
934 that the appropriate source files are part of the distribution. Note
935 that Automake does not come with any of the C sources required to use
936 these macros, so @code{automake -a} will not install the sources.
937 @xref{A Library} for more information.
938 @cvindex AC_FUNC_ALLOCA
939 @cvindex AC_FUNC_GETLOADAVG
940 @cvindex AC_FUNC_MEMCMP
941 @cvindex AC_STRUCT_ST_BLOCKS
942 @cvindex AC_FUNC_FNMATCH
943 @cvindex AC_FUNC_FNMATCH
944 @cvindex AC_REPLACE_FUNCS
945 @cvindex AC_REPLACE_GNU_GETOPT
946 @cvindex AM_FUNC_STRTOD
947 @cvindex AM_WITH_REGEX
950 Automake will detect statements which put @samp{.o} files into
951 @code{LIBOBJS}, and will treat these additional files as if they were
952 discovered via @code{AC_REPLACE_FUNCS}.
956 This is required if any libraries are built in the package.
957 @cvindex AC_PROG_RANLIB
960 This is required if any C++ source is included.
963 @item AM_PROG_LIBTOOL
964 Automake will turn on processing for @code{libtool} (@pxref{Top, , The
965 Libtool Manual, libtool, The Libtool Manual}).
966 @cvindex AM_PROG_LIBTOOL
969 If a Yacc source file is seen, then you must either use this macro or
970 define the variable @samp{YACC} in @file{configure.in}. The former is
972 @cvindex AC_PROG_YACC
976 This macro is required if there is Lex source in the package.
977 @cvindex AC_DECL_YYTEXT
980 If a Lex source file is seen, then this macro must be used.
984 If Automake sees that this variable is set in @file{configure.in}, it
985 will check the @file{po} directory to ensure that all the named
986 @samp{.po} files exist, and that all the @samp{.po} files that exist are
990 @item AM_C_PROTOTYPES
991 This is required when using automatic de-ANSI-fication, see @ref{ANSI}.
992 @cvindex AM_C_PROTOTYPES
995 This macro is required for packages which use GNU gettext
996 (@pxref{gettext}). It is distributed with gettext. If Automake sees
997 this macro it ensures that the package meets some of gettext's
999 @cvindex AM_GNU_GETTEXT
1001 @item AM_MAINTAINER_MODE
1002 This macro adds a @samp{--enable-maintainer-mode} option to
1003 @code{configure}. If this is used, @code{automake} will cause
1004 ``maintainer-only'' rules to be turned off by default in the generated
1005 @file{Makefile.in}s. This macro is disallowed in @samp{Gnits} mode
1007 @cvindex AM_MAINTAINER_MODE
1010 @itemx AC_CHECK_TOOL
1011 @itemx AC_CHECK_PROG
1012 @itemx AC_CHECK_PROGS
1014 @itemx AC_PATH_PROGS
1015 For each of these macros, the first argument is automatically defined as
1016 a variable in each generated @file{Makefile.in}.
1018 @cvindex AC_CHECK_TOOL
1019 @cvindex AC_CHECK_PROG
1020 @cvindex AC_CHECK_PROGS
1021 @cvindex AC_PATH_PROG
1022 @cvindex AC_PATH_PROGS
1027 @node Invoking aclocal, Macros, Optional, configure
1028 @section Auto-generating aclocal.m4
1030 Automake includes a number of Autoconf macros which can be used in your
1031 package; some of them are actually required by Automake in certain
1032 situations. These macros must be defined in your @file{aclocal.m4};
1033 otherwise they will not be seen by @code{autoconf}.
1035 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1036 files based on the contents of @file{configure.in}. This provides a
1037 convenient way to get Automake-provided macros, without having to
1038 search around. Also, the @code{aclocal} mechanism is extensible for use
1041 At startup, @code{aclocal} scans all the @samp{.m4} files it can find,
1042 looking for macro definitions. Then it scans @file{configure.in}. Any
1043 mention of one of the macros found in the first step causes that macro,
1044 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1046 The contents of @file{acinclude.m4}, if it exists, are also
1047 automatically included in @file{aclocal.m4}. This is useful for
1048 incorporating local macros into @file{configure}.
1050 @code{aclocal} accepts the following options:
1053 @item --acdir=@var{dir}
1054 Look for the macro files in @var{dir} instead of the installation
1055 directory. This is typically used for debugging.
1058 Print a summary of the command line options and exit.
1061 Add the directory @var{dir} to the list of directories searched for
1064 @item --output=@var{file}
1065 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1067 @item --print-ac-dir
1068 Prints the name of the directory which @code{aclocal} will search to
1069 find the @samp{m4} files. When this option is given, normal processing
1070 is suppressed. This option can be used by a package to determine where
1071 to install a macro file.
1074 Print the names of the files it examines.
1077 Print the version number of Automake and exit.
1081 @node Macros, Extending aclocal, Invoking aclocal, configure
1082 @section Autoconf macros supplied with Automake
1084 @c consider generating this node automatically from m4 files.
1087 @item AM_CONFIG_HEADER
1088 Automake will generate rules to automatically regenerate the config
1089 header. If you do use this macro, you must create the file
1090 @file{stamp-h.in} in your source directory. It can be empty.
1091 @cvindex AM_CONFIG_HEADER
1094 Check to see if this @code{configure} is being run in the
1095 @samp{Cygwin32} environment. (FIXME xref). If so, define output
1096 variable @code{EXEEXT} to @samp{.exe}; otherwise define it to the empty
1097 string. Automake recognizes this macro and uses it to generate
1098 @file{Makefile.in}s which will automatically work under @samp{Cygwin32}.
1099 In the @samp{Cygwin32} environment, @code{gcc} generates executables
1100 whose names end in @samp{.exe}, even if this was not specified on the
1101 command line. Automake adds special code to @file{Makefile.in} to
1102 gracefully deal with this.
1104 @item AM_FUNC_STRTOD
1105 If the @code{strtod} function is not available, or does not work
1106 correctly (like the one on SunOS 5.4), add @file{strtod.o} to output
1107 variable @code{LIBOBJS}.
1108 @cvindex AM_FUNC_STRTOD
1110 @item AM_FUNC_ERROR_AT_LINE
1111 If the function @code{error_at_line} is not found, then add
1112 @file{error.o} to @code{LIBOBJS}.
1113 @cvindex AM_FUNC_ERROR_AT_LINE
1115 @item AM_FUNC_MKTIME
1116 Check for a working @code{mktime} function. If not found, add
1117 @file{mktime.o} to @samp{LIBOBJS}.
1118 @cvindex AM_FUNC_MKTIME
1120 @item AM_FUNC_OBSTACK
1121 Check for the GNU obstacks code; if not found, add @file{obstack.o} to
1123 @cvindex AM_FUNC_OBSTACK
1125 @item AM_C_PROTOTYPES
1126 Check to see if function prototypes are understood by the compiler. If
1127 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1128 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1129 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1130 values to implement automatic de-ANSI-fication.
1131 @cvindex AM_C_PROTOTYPES
1133 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1134 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1135 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1136 found in @file{<termios.h>}.
1137 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1139 @item AM_INIT_AUTOMAKE
1140 Runs many macros that most @file{configure.in}'s need. This macro has
1141 two required arguments, the package and the version number. By default
1142 this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}. This
1143 can be avoided by passing in a non-empty third argument.
1145 @item AM_PATH_LISPDIR
1146 Searches for the program @code{emacs}, and, if found, sets the output
1147 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1148 @cvindex AM_PATH_LISPDIR
1150 @item AM_PROG_CC_STDC
1151 If the C compiler in not in ANSI C mode by default, try to add an option
1152 to output variable @code{CC} to make it so. This macro tries various
1153 options that select ANSI C on some system or another. It considers the
1154 compiler to be in ANSI C mode if it handles function prototypes correctly.
1156 If you use this macro, you should check after calling it whether the C
1157 compiler has been set to accept ANSI C; if not, the shell variable
1158 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1159 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1160 @code{ansi2knr} option.
1161 @cvindex AM_PROG_CC_STDC
1163 @item AM_PROG_INSTALL
1164 Like @code{AC_PROG_INSTALL}, but also defines @code{INSTALL_SCRIPT}.
1165 @cvindex AM_PROG_INSTALL
1168 Like @code{AC_PROG_LEX} with @code{AC_DECL_YYTEXT}, but uses the
1169 @code{missing} script on systems that do not have lex. @samp{HP-UX 10}
1171 @cvindex AM_PROG_LEX
1173 @item AM_SANITY_CHECK
1174 This checks to make sure that a file created in the build directory is
1175 newer than a file in the source directory. This can fail on systems
1176 where the clock is set incorrectly. This macro is automatically run
1177 from @code{AM_INIT_AUTOMAKE}.
1178 @cvindex AM_SANITY_CHECK
1180 @item AM_SYS_POSIX_TERMIOS
1181 Check to see if POSIX termios headers and functions are available on the
1182 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1183 @samp{yes}. If not, set the variable to @samp{no}.
1184 @cvindex AM_SYS_POSIX_TERMIOS
1186 @item AM_TYPE_PTRDIFF_T
1187 Define @samp{HAVE_PTRDIFF_T} if the type @samp{ptrdiff_t} is defined in
1189 @cvindex AM_TYPE_PTRDIFF_T
1191 @item AM_WITH_DMALLOC
1192 Add support for the @code{dmalloc} package. If the user configures with
1193 @samp{--with-dmalloc}, then define @code{WITH_DMALLOC} and add
1194 @samp{-ldmalloc} to @code{LIBS}. The @code{dmalloc} package can be
1195 found at @url{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz}
1196 @cvindex AM_WITH_DMALLOC
1199 Adds @samp{--with-regex} to the @code{configure} command line. If
1200 specified (the default), then the @samp{regex} regular expression
1201 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1202 @samp{WITH_REGEX} is defined.. If @samp{--without-regex} is given, then
1203 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1204 into @samp{LIBOBJS}.
1205 @cvindex AM_WITH_REGEX
1209 @node Extending aclocal, , Macros, configure
1210 @section Writing your own aclocal macros
1212 Aclocal doesn't have any built-in knowledge of any macros, so it is easy
1213 to extend it with your own macros.
1215 This is mostly used for libraries which want to supply their own
1216 Autoconf macros for use by other programs. For instance the
1217 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1218 should be used by any package using @code{gettext}. When the library is
1219 installed, it installs this macro so that @code{aclocal} will find it.
1221 A file of macros should be a series of @code{AC_DEFUN}'s. Aclocal also
1222 understands @code{AC_REQUIRE}, so it is safe to put each macro in a
1225 A macro file's name should end in @samp{.m4}. Such files should be
1226 installed in @file{$(datadir)/aclocal}.
1228 @node Top level, Programs, configure, Top
1229 @chapter The top-level @file{Makefile.am}
1231 In non-flat packages, the top level @file{Makefile.am} must tell
1232 Automake which subdirectories are to be built. This is done via the
1233 @code{SUBDIRS} variable.
1236 The @code{SUBDIRS} macro holds a list of subdirectories in which
1237 building of various sorts can occur. Many targets (eg @code{all}) in
1238 the generated @file{Makefile} will run both locally and in all specified
1239 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1240 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1241 (after configuration). This allows inclusion of libraries from packages
1242 which do not use Automake (such as @code{gettext}). The directories
1243 mentioned in @code{SUBDIRS} must be direct children of the current
1244 directory. For instance, you cannot put @samp{src/subdir} into
1247 In a deep package, the top-level @file{Makefile.am} is often very short.
1248 For instance, here is the @file{Makefile.am} from the Hello
1252 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1253 SUBDIRS = doc intl po src tests
1256 It is possible to override the @code{SUBDIRS} variable if, like in the
1257 case of GNU @code{Inetutils}, you want to only build a subset of the
1258 entire package. In your @file{Makefile.am} include:
1261 SUBDIRS = @@SUBDIRS@@
1264 Then in your @file{configure.in} you can specify:
1267 SUBDIRS = "src doc lib po"
1271 The upshot of this is that automake is tricked into building the package
1272 to take the subdirs, but doesn't actually bind that list until
1273 @code{configure} is run.
1276 @code{SUBDIRS} can contain configure substitutions (eg @samp{@@DIRS@@});
1277 Automake itself does not actually examine the contents of this variable.
1279 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1280 @code{AC_PROG_MAKE_SET}.
1282 The use of @code{SUBDIRS} is not restricted to just the top-level
1283 @file{Makefile.am}. Automake can be used to construct packages of
1287 @node Programs, Other objects, Top level, Top
1288 @chapter Building Programs and Libraries
1290 A large part of Automake's functionality is dedicated to making it easy
1291 to build C programs and libraries.
1294 * A Program:: Building a program
1295 * A Library:: Building a library
1296 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1297 * A Shared Library:: Building a Libtool library
1298 * Program variables:: Variables used when building a program
1299 * Yacc and Lex:: Yacc and Lex support
1301 * ANSI:: Automatic de-ANSI-fication
1302 * Dependencies:: Automatic dependency tracking
1306 @node A Program, A Library, Programs, Programs
1307 @section Building a program
1309 In a directory containing source that gets built into a program (as
1310 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
1311 can be installed in @samp{bindir}, @samp{sbindir}, @samp{libexecdir},
1312 @samp{pkglibdir}, or not at all (@samp{noinst}).
1317 bin_PROGRAMS = hello
1320 In this simple case, the resulting @file{Makefile.in} will contain code
1321 to generate a program named @code{hello}. The variable
1322 @code{hello_SOURCES} is used to specify which source files get built
1326 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1329 This causes each mentioned @samp{.c} file to be compiled into the
1330 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1332 If @samp{prog_SOURCES} is needed, but not specified, then it defaults to
1333 the single file @file{prog.c}. In the example above, the definition of
1334 @code{hello_SOURCES} is actually redundant.
1338 Multiple programs can be built in a single directory. Multiple programs
1339 can share a single source file. The source file must be listed in each
1340 @samp{_SOURCES} definition.
1342 Header files listed in a @samp{_SOURCES} definition will be included in
1343 the distribution but otherwise ignored. In case it isn't obvious, you
1344 should not include the header file generated by @file{configure} in an
1345 @samp{_SOURCES} variable; this file should not be distributed. Lex
1346 (@samp{.l}) and yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1349 Automake must know all the source files that could possibly go into a
1350 program, even if not all the files are built in every circumstance.
1351 Any files which are only conditionally built should be listed in the
1352 appropriate @samp{EXTRA_} variable. For instance, if
1353 @file{hello-linux.c} were conditionally included in @code{hello}, the
1354 @file{Makefile.am} would contain:
1357 EXTRA_hello_SOURCES = hello-linux.c
1360 Similarly, sometimes it is useful to determine the programs that are to
1361 be built at configure time. For instance, GNU @code{cpio} only builds
1362 @code{mt} and @code{rmt} under special circumstances.
1364 In this case, you must notify @code{automake} of all the programs that
1365 can possibly be built, but at the same time cause the generated
1366 @file{Makefile.in} to use the programs specified by @code{configure}.
1367 This is done by having @code{configure} substitute values into each
1368 @samp{_PROGRAMS} definition, while listing all optionally built programs in
1369 @code{EXTRA_PROGRAMS}.
1370 @vindex EXTRA_PROGRAMS
1372 If you need to link against libraries that are not found by
1373 @code{configure}, you can use @code{LDADD} to do so. This variable
1374 actually can be used to add any options to the linker command line.
1377 Sometimes, multiple programs are built in one directory but do not share
1378 the same link-time requirements. In this case, you can use the
1379 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1380 program as it appears in some @samp{_PROGRAMS} variable, and usually
1381 written in lowercase) to override the global @code{LDADD}. (If this
1382 variable exists for a given program, then that program is not linked
1383 using @code{LDADD}.)
1386 For instance, in GNU cpio, @code{pax}, @code{cpio}, and @code{mt} are
1387 linked against the library @file{libcpio.a}. However, @code{rmt} is
1388 built in the same directory, and has no such link requirement. Also,
1389 @code{mt} and @code{rmt} are only built on certain architectures. Here
1390 is what cpio's @file{src/Makefile.am} looks like (abridged):
1393 bin_PROGRAMS = cpio pax @@MT@@
1394 libexec_PROGRAMS = @@RMT@@
1395 EXTRA_PROGRAMS = mt rmt
1397 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1400 cpio_SOURCES = @dots{}
1401 pax_SOURCES = @dots{}
1402 mt_SOURCES = @dots{}
1403 rmt_SOURCES = @dots{}
1406 @samp{prog_LDADD} is inappropriate for passing program-specific linker
1407 flags (except for @samp{-l} and @samp{-L}). So, use the
1408 @samp{prog_LDFLAGS} variable for this purpose.
1411 It is also occasionally useful to have a program depend on some other
1412 target which is not actually part of that program. This can be done
1413 using the @samp{prog_DEPENDENCIES} variable. Each program depends on
1414 the contents of such a variable, but no further interpretation is done.
1416 If @samp{prog_DEPENDENCIES} is not supplied, it is computed by Automake.
1417 The automatically-assigned value is the contents of @samp{prog_LDADD},
1418 with most configure substitutions, @samp{-l}, and @samp{-L} options
1419 removed. The configure substitutions that are left in are only
1420 @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are left because it is
1421 known that they will not cause an invalid value for
1422 @samp{prog_DEPENDENCIES} to be generated.
1425 @node A Library, LIBOBJS, A Program, Programs
1426 @section Building a library
1428 Building a library is much like building a program. In this case, the
1429 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
1430 @code{libdir} or @code{pkglibdir}.
1432 @xref{A Shared Library}, for information on how to build shared
1433 libraries using Libtool and the @samp{LTLIBRARIES} primary.
1435 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
1436 For instance to create a library named @file{libcpio.a}, but not install
1437 it, you would write:
1440 noinst_LIBRARIES = libcpio.a
1443 The sources that go into a library are determined exactly as they are
1444 for programs, via the @samp{_SOURCES} variables. Note that the library
1445 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
1446 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
1447 not @samp{liblob.a_SOURCES}.
1449 Extra objects can be added to a library using the @samp{library_LIBADD}
1450 variable. This should be used for objects determined by
1451 @code{configure}. Again from cpio:
1456 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
1459 @node LIBOBJS, A Shared Library, A Library, Programs
1460 @section Special handling for LIBOBJS and ALLOCA
1462 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
1463 @code{@@ALLOCA@@}, and uses this information, plus the list of
1464 @code{LIBOBJS} files derived from @file{configure.in} to automatically
1465 include the appropriate source files in the distribution (@pxref{Dist}).
1466 These source files are also automatically handled in the
1467 dependency-tracking scheme, see @xref{Dependencies}.
1469 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
1470 @samp{_LDADD} or @samp{_LIBADD} variable.
1472 @node A Shared Library, Program variables, LIBOBJS, Programs
1473 @section Building a Shared Library
1475 Building shared libraries is a relatively complex matter. For this
1476 reason, GNU Libtool (@pxref{Top, , The Libtool Manual, libtool, The
1477 Libtool Manual}) was created to help build shared libraries in a
1478 platform-independent way.
1480 Automake uses Libtool to build libraries declared with the
1481 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
1482 of shared libraries to build. For instance, to create a library named
1483 @file{libgettext.a} and its corresponding shared libraries, and install
1484 them in @samp{libdir}, write:
1487 lib_LTLIBRARIES = libgettext.la
1490 Note that shared libraries @emph{must} be installed, so
1491 @samp{noinst_LTLIBRARIES} and @samp{check_LTLIBRARIES} are not allowed.
1493 For each library, the @samp{library_LIBADD} variable contains the names
1494 of extra libtool objects (@samp{.lo} files) to add to the shared
1495 library. The @samp{library_LDFLAGS} variable contains any additional
1496 libtool flags, such as @samp{-version-info} or @samp{-static}.
1498 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
1499 library must use @code{@@LTLIBOBJS@@}. This is required because the
1500 object files that libtool operates on do not necessarily end in
1501 @samp{.o}. The libtool manual contains more details on this topic.
1503 For libraries installed in some directory, @code{automake} will
1504 automatically supply the appropriate @samp{-rpath} option. However, for
1505 libraries determined at configure time (and thus mentioned in
1506 @code{EXTRA_LTLIBRARIES}), @code{automake} does not know the eventual
1507 installation directory; for such libraries you must add the
1508 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
1511 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
1512 libtool, The Libtool Manual}, for more information.
1514 @node Program variables, Yacc and Lex, A Shared Library, Programs
1515 @section Variables used when building a program
1517 Occasionally it is useful to know which @file{Makefile} variables
1518 Automake uses for compilations; for instance you might need to do your
1519 own compilation in some special cases.
1521 Some variables are inherited from Autoconf; these are @code{CC},
1522 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
1526 There are some additional variables which Automake itself defines:
1530 A list of @samp{-I} options. This can be set in your @file{Makefile.am}
1531 if you have special directories you want to look in. @code{automake}
1532 already provides some @samp{-I} options automatically. In particular it
1533 generates @samp{-I$(srcdir)} and a @samp{-I} pointing to the directory
1534 holding @file{config.h} (if you've used @code{AC_CONFIG_HEADER} or
1535 @code{AM_CONFIG_HEADER}).
1537 @code{INCLUDES} can actually be used for other @code{cpp} options
1538 besides @samp{-I}. For instance, it is sometimes used to pass arbitrary
1539 @samp{-D} options to the compiler.
1542 This is the command used to actually compile a C source file. The
1543 filename is appended to form the complete command line.
1546 This is the command used to actually link a C program.
1550 @node Yacc and Lex, C++, Program variables, Programs
1551 @section Yacc and Lex support
1553 Automake has somewhat idiosyncratic support for Yacc and Lex.
1555 Automake assumes that the @samp{.c} file generated by yacc (or lex)
1556 should be named using the basename of the input file. That is, for a
1557 yacc source file @file{foo.y}, automake will cause the intermediate file
1558 to be named @file{foo.c} (as opposed to @file{y.tab.c}, which is more
1561 The extension of a yacc source file is used to determine the extension
1562 of the resulting @samp{C} or @samp{C++} file. Files with the extension
1563 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
1564 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
1565 @samp{.cxx}. Likewise, lex source files can be used to generate
1566 @samp{C} or @samp{C++}; the extensions @samp{.l}, @samp{.ll},
1567 @samp{.l++}, and @samp{.lxx} are recognized.
1569 You should never explicitly mention the intermediate (@samp{C} or
1570 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
1573 The intermediate files generated by yacc (or lex) will be included in
1574 any distribution that is made. That way the user doesn't need to have
1577 If a yacc source file is seen, then your @file{configure.in} must define
1578 the variable @samp{YACC}. This is most easily done by invoking the
1579 macro @samp{AC_PROG_YACC}.
1581 Similarly, if a lex source file is seen, then your @file{configure.in}
1582 must define the variable @samp{LEX}. You can use @samp{AC_PROG_LEX} to
1583 do this. Automake's lex support also requires that you use the
1584 @samp{AC_DECL_YYTEXT} macro---automake needs to know the value of
1585 @samp{LEX_OUTPUT_ROOT}.
1587 Automake makes it possible to include multiple yacc (or lex) source
1588 files in a single program. Automake uses a small program called
1589 @code{ylwrap} to run @code{yacc} (or @code{lex}) in a subdirectory.
1590 This is necessary because yacc's output filename is fixed, and a
1591 parallel make could conceivably invoke more than one instance of
1592 @code{yacc} simultaneously. @code{ylwrap} is distributed with automake.
1593 It should appear in the directory specified by @samp{AC_CONFIG_AUX_DIR},
1594 or the current directory if that macro is not used in
1595 @file{configure.in}.
1597 For @code{yacc}, simply managing locking is insufficient. @code{yacc}
1598 output also always uses the same symbol names internally, so it isn't
1599 possible to link two @code{yacc} parsers into the same executable.
1601 We recommend using the following renaming hack used in @code{gdb}:
1603 #define yymaxdepth c_maxdepth
1604 #define yyparse c_parse
1606 #define yyerror c_error
1607 #define yylval c_lval
1608 #define yychar c_char
1609 #define yydebug c_debug
1610 #define yypact c_pact
1617 #define yyexca c_exca
1618 #define yyerrflag c_errflag
1619 #define yynerrs c_nerrs
1623 #define yy_yys c_yys
1624 #define yystate c_state
1627 #define yy_yyv c_yyv
1629 #define yylloc c_lloc
1630 #define yyreds c_reds
1631 #define yytoks c_toks
1632 #define yylhs c_yylhs
1633 #define yylen c_yylen
1634 #define yydefred c_yydefred
1635 #define yydgoto c_yydgoto
1636 #define yysindex c_yysindex
1637 #define yyrindex c_yyrindex
1638 #define yygindex c_yygindex
1639 #define yytable c_yytable
1640 #define yycheck c_yycheck
1643 For each define, replace the @samp{c_} prefix with whatever you like.
1644 These defines work for @code{bison}, @code{byacc}, and traditional
1645 @code{yacc}s. If you find a parser generator that uses a symbol not
1646 covered here, please report the new name so it can be added to the list.
1649 @node C++, ANSI, Yacc and Lex, Programs
1650 @section C++ and other languages
1652 Automake includes full support for C++, and rudimentary support for
1653 other languages. Support for other languages will be improved based on
1656 Any package including C++ code must define the output variable
1657 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
1658 the @code{AC_PROG_CXX} macro.
1660 A few additional variables are defined when a C++ source file is seen:
1664 The name of the C++ compiler.
1668 Any flags to pass to the C++ compiler.
1672 The command used to actually compile a C++ source file. The file name
1673 is appended to form the complete command line.
1677 The command used to actually link a C++ program.
1682 @node ANSI, Dependencies, C++, Programs
1683 @section Automatic de-ANSI-fication
1685 Although the GNU standards allow the use of ANSI C, this can have the
1686 effect of limiting portability of a package to some older compilers
1689 Automake allows you to work around this problem on such machines by
1690 ``de-ANSI-fying'' each source file before the actual compilation takes
1693 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
1694 @vindex AUTOMAKE_OPTIONS
1695 (@ref{Options}) contains the option @code{ansi2knr}
1697 then code to handle de-ANSI-fication is inserted into the generated
1700 This causes each C source file in the directory to be treated as ANSI C.
1701 If an ANSI C compiler is available, it is used. If no ANSI C compiler
1702 is available, the @code{ansi2knr} program is used to convert the source
1703 files into K&R C, which is then compiled.
1705 The @code{ansi2knr} program is simple-minded. It assumes the source
1706 code will be formatted in a particular way; see the @code{ansi2knr} man
1709 De-ANSI-fication support requires the source files @file{ansi2knr.c} and
1710 @file{ansi2knr.1} to be in the same package as the ANSI C source; these
1711 files are distributed with Automake. Also, the package
1712 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}.
1713 @cvindex AM_C_PROTOTYPES
1715 Automake also handles finding the @code{ansi2knr} support files in some
1716 other directory in the current package. This is done by prepending the
1717 relative path to the appropriate directory to the @code{ansi2knr}
1718 option. For instance, suppose the package has ANSI C code in the
1719 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
1720 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
1721 @file{src/Makefile.am}:
1724 AUTOMAKE_OPTIONS = ../lib/ansi2knr
1727 If no directory prefix is given, the files are assumed to be in the
1730 @node Dependencies, , ANSI, Programs
1731 @section Automatic dependency tracking
1733 As a developer it is often painful to continually update the
1734 @file{Makefile.in} whenever the include-file dependencies change in a
1735 project. @code{automake} supplies a way to automatically track
1736 dependency changes, and distribute the dependencies in the generated
1739 Currently this support requires the use of GNU @code{make} and
1740 @code{gcc}. It might become possible in the future to supply a
1741 different dependency generating program, if there is enough demand. In
1742 the meantime, this mode is enabled by default if any C program or
1743 library is defined in the current directory, so you may get a @samp{Must
1744 be a separator} error from non-GNU make.
1746 When you decide to make a distribution, the @code{dist} target will
1748 re-run @code{automake} with @samp{--include-deps} and other options.
1749 This will cause the previously generated dependencies to be inserted
1750 into the generated @file{Makefile.in}, and thus into the distribution.
1751 This step also turns off inclusion of the dependency generation code, so
1752 that those who download your distribution but don't use GNU @code{make}
1753 and @code{gcc} will not get errors.
1755 When added to the @file{Makefile.in}, the dependencies have all
1756 system-specific dependencies automatically removed. This can be done by
1757 listing the files in @samp{OMIT_DEPENDENCIES}.
1758 @vindex OMIT_DEPENDENCIES
1759 For instance all references to system header files are removed by
1760 @code{automake}. Sometimes it is useful to specify that a certain
1761 header file should be removed. For instance if your @file{configure.in}
1762 uses @samp{AM_WITH_REGEX}, then any dependency on @file{rx.h} or
1763 @file{regex.h} should be removed, because the correct one cannot be
1764 known until the user configures the package.
1766 As it turns out, @code{automake} is actually smart enough to handle the
1767 particular case of the regular expression header. It will also
1768 automatically omit @file{libintl.h} if @samp{AM_GNU_GETTEXT} is used.
1770 Automatic dependency tracking can be suppressed by putting
1771 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}.
1772 @vindex AUTOMAKE_OPTIONS
1773 @opindex no-dependencies
1775 If you unpack a distribution made by @code{make dist}, and you want to
1776 turn on the dependency-tracking code again, simply re-run
1779 The actual dependency files are put under the build directory, in a
1780 subdirectory named @file{.deps}. These dependencies are machine
1781 specific. It is safe to delete them if you like; they will be
1782 automatically recreated during the next build.
1785 @node Other objects, Other GNU Tools, Programs, Top
1786 @chapter Other Derived Objects
1788 Automake can handle derived objects which are not C programs. Sometimes
1789 the support for actually building such objects must be explicitly
1790 supplied, but Automake will still automatically handle installation and
1794 * Scripts:: Executable scripts
1795 * Headers:: Header files
1796 * Data:: Architecture-independent data files
1797 * Sources:: Derived sources
1801 @node Scripts, Headers, Other objects, Other objects
1802 @section Executable Scripts
1804 It is possible to define and install programs which are scripts. Such
1805 programs are listed using the @samp{SCRIPTS} primary name.
1806 @code{automake} doesn't define any dependencies for scripts; the
1807 @file{Makefile.am} should include the appropriate rules.
1810 @code{automake} does not assume that scripts are derived objects; such
1811 objects must be deleted by hand; see @ref{Clean} for more information.
1813 @code{automake} itself is a script that is generated at configure time
1814 from @file{automake.in}. Here is how this is handled:
1817 bin_SCRIPTS = automake
1820 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
1821 for it is automatically generated.
1823 Script objects can be installed in @code{bindir}, @code{sbindir},
1824 @code{libexecdir}, or @code{pkgdatadir}.
1827 @node Headers, Data, Scripts, Other objects
1828 @section Header files
1830 Header files are specified by the @samp{HEADERS} family of variables.
1831 Generally header files are not installed, so the @code{noinst_HEADERS}
1832 variable will be the most used.
1835 All header files must be listed somewhere; missing ones will not appear
1836 in the distribution. Often it is clearest to list uninstalled headers
1837 with the rest of the sources for a program. @xref{A Program}. Headers
1838 listed in a @samp{_SOURCES} variable need not be listed in any
1839 @samp{_HEADERS} variable.
1841 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
1842 @code{pkgincludedir}.
1845 @node Data, Sources, Headers, Other objects
1846 @section Architecture-independent data files
1848 Automake supports the installation of miscellaneous data files using the
1849 @samp{DATA} family of variables.
1852 Such data can be installed in the directories @code{datadir},
1853 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
1856 By default, data files are not included in a distribution.
1858 Here is how @code{automake} installs its auxiliary data files:
1861 pkgdata_DATA = clean-kr.am clean.am @dots{}
1865 @node Sources, , Data, Other objects
1866 @section Built sources
1868 Occasionally a file which would otherwise be called ``source'' (eg a C
1869 @samp{.h} file) is actually derived from some other file. Such files
1870 should be listed in the @code{BUILT_SOURCES} variable.
1871 @vindex BUILT_SOURCES
1873 Built sources are also not compiled by default. You must explicitly
1874 mention them in some other @samp{_SOURCES} variable for this to happen.
1876 Note that, in some cases, @code{BUILT_SOURCES} will work in somewhat
1877 suprising ways. In order to get the built sources to work with
1878 automatic dependency tracking, the @file{Makefile} must depend on
1879 @code{$(BUILT_SOURCES)}. This can cause these sources to be rebuilt at
1880 what might seem like funny times.
1883 @node Other GNU Tools, Documentation, Other objects, Top
1884 @chapter Other GNU Tools
1886 Since Automake is primarily intended to generate @file{Makefile.in}s for
1887 use in GNU programs, it tries hard to interoperate with other GNU tools.
1890 * Emacs Lisp:: Emacs Lisp
1897 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
1900 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
1901 is used to hold a list of @samp{.el} files. Possible prefixes for this
1902 primary are @samp{lisp_} and @samp{noinst_}. Note that if
1903 @code{lisp_LISP} is defined, then @file{configure.in} must run
1904 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
1909 By default Automake will byte-compile all Emacs Lisp source files using
1910 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
1911 byte-compiling, simply define the variable @samp{ELCFILES} to be empty.
1913 Byte-compiled Emacs Lisp files are not portable among all versions of
1914 Emacs, so it makes sense to turn this off if you expect sites to have
1915 more than one version of Emacs installed. Furthermore, many packages
1916 don't actually benefit from byte-compilation. Still, we recommand that
1917 you leave it enabled by default. It is probably better for sites with
1918 strange setups to cope for themselves than to make the installation less
1919 nice for everybody else.
1921 @node gettext, Guile, Emacs Lisp, Other GNU Tools
1924 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
1925 turns on support for GNU gettext, a message catalog system for
1926 internationalization
1927 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
1929 The @code{gettext} support in Automake requires the addition of two
1930 subdirectories to the package, @file{intl} and @file{po}. Automake
1931 ensure that these directories exist and are mentioned in @code{SUBDIRS}.
1933 Furthermore, Automake checks that the definition of @samp{ALL_LINGUAS}
1934 in @file{configure.in} corresponds to all the valid @samp{.po} files,
1938 @node Guile, Libtool, gettext, Other GNU Tools
1941 Automake provides some automatic support for writing Guile modules.
1942 Automake will turn on Guile support if the @code{AM_INIT_GUILE_MODULE}
1943 macro is used in @file{configure.in}.
1945 Right now Guile support just means that the @code{AM_INIT_GUILE_MODULE}
1946 macro is understood to mean:
1949 @code{AM_INIT_AUTOMAKE} is run.
1952 @code{AC_CONFIG_AUX_DIR} is run, with a path of @file{..}.
1955 As the Guile module code matures, no doubt the Automake support will
1958 @node Libtool, Java, Guile, Other GNU Tools
1961 Automake provides support for GNU Libtool (@pxref{Top, , The Libtool
1962 Manual, libtool, The Libtool Manual}) with the @samp{LTLIBRARIES}
1963 primary. @xref{A Shared Library}.
1965 @node Java, , Libtool, Other GNU Tools
1968 Automake provides some minimal support for Java compilation with the
1969 @samp{JAVA} primary.
1971 Any @samp{.java} files listed in a @samp{_JAVA} variable will be
1972 compiled with @code{JAVAC} at build time. By default, @samp{.class}
1973 files are not included in the distribution.
1975 Currently Automake enforces the restriction that only one @samp{_JAVA}
1976 primary can be used in a given @file{Makefile.am}. The reason for this
1977 restriction is that, in general, it isn't possible to know which
1978 @samp{.class} files were generated from which @samp{.java} files -- so
1979 it would be impossible to know which files to install where.
1982 @node Documentation, Install, Other GNU Tools, Top
1983 @chapter Building documentation
1985 Currently Automake provides support for Texinfo and man pages.
1989 * Man pages:: Man pages
1993 @node Texinfo, Man pages, Documentation, Documentation
1996 If the current directory contains Texinfo source, you must declare it
1997 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
1998 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
1999 here. Note that any Texinfo source file must end in the @samp{.texi} or
2000 @samp{.texinfo} extension.
2002 @vindex info_TEXINFOS
2004 If the @samp{.texi} file @code{@@include}s @file{version.texi}, then that
2005 file will be automatically generated. @file{version.texi} defines three
2006 Texinfo macros you can reference: @code{EDITION}, @code{VERSION}, and
2007 @code{UPDATED}. The first two hold the version number of your package
2008 (but are kept separate for clarity); the last is the date the primary
2009 file was last modified. The @file{version.texi} support requires the
2010 @code{mdate-sh} program; this program is supplied with Automake.
2012 Sometimes an info file actually depends on more than one @samp{.texi}
2013 file. For instance, in GNU Hello, @file{hello.texi} includes the file
2014 @file{gpl.texi}. You can tell Automake about these dependencies using
2015 the @samp{@var{texi}_TEXINFOS} variable. Here is how Hello does it:
2020 info_TEXINFOS = hello.texi
2021 hello_TEXINFOS = gpl.texi
2024 By default, Automake requires the file @file{texinfo.tex} to appear in
2025 the same directory as the Texinfo source. However, if you used
2026 @code{AC_CONFIG_AUX_DIR} in @file{configure.in}, then @file{texinfo.tex}
2027 is looked for there. Automake supplies @file{texinfo.tex} if
2028 @samp{--add-missing} is given.
2030 If your package has Texinfo files in many directories, you can use the
2031 variable @code{TEXINFO_TEX} to tell automake where to find the canonical
2032 @file{texinfo.tex} for your package. The value of this variable should
2033 be the relative path from the current @file{Makefile.am} to
2037 TEXINFO_TEX = ../doc/texinfo.tex
2040 The option @samp{no-texinfo.tex} can be used to eliminate the
2041 requirement for @file{texinfo.tex}. Use of the variable
2042 @code{TEXINFO_TEX} is preferable, however, because that allows the
2043 @code{dvi} target to still work.
2045 Automake generates an @code{install-info} target; some people apparently
2046 use this. By default, info pages are installed by @samp{make install}.
2047 This can be prevented via the @code{no-installinfo} option.
2050 @node Man pages, , Texinfo, Documentation
2053 A package can also include man pages. (Though see the GNU standards on
2054 this matter, @ref{Man Pages, , , standards, The GNU Coding
2055 Standards}.) Man pages are declared using the @samp{MANS} primary.
2056 Generally the @code{man_MANS} macro is used. Man pages are
2057 automatically installed in the correct subdirectory of @code{mandir},
2058 based on the file extension.
2062 @c Use @samp{make install} per documentation: (texi)code.
2063 By default, man pages are installed by @samp{make install}. However,
2064 since the GNU project does not require man pages, many maintainers do
2065 not expend effort to keep the man pages up to date. In these cases, the
2066 @code{no-installman} option will prevent the man pages from being
2067 installed by default. The user can still explicitly install them via
2068 @samp{make install-man}.
2069 @opindex no-installman
2070 @trindex install-man
2072 Here is how the documentation is handled in GNU @code{cpio} (which
2073 includes both Texinfo documentation and man pages):
2076 info_TEXINFOS = cpio.texi
2077 man_MANS = cpio.1 mt.1
2080 Texinfo source and info pages are all considered to be source for the
2081 purposes of making a distribution.
2083 Man pages are not currently considered to be source, because it is not
2084 uncommon for man pages to be automatically generated.
2087 @node Install, Clean, Documentation, Top
2088 @chapter What Gets Installed
2090 Naturally, Automake handles the details of actually installing your
2091 program once it has been built. All @code{PROGRAMS}, @code{SCRIPTS},
2092 @code{LIBRARIES}, @code{LISP}, @code{DATA} and @code{HEADERS} are
2093 automatically installed in the appropriate places.
2095 Automake also handles installing any specified info and man pages.
2097 Automake generates separate @code{install-data} and @code{install-exec}
2098 targets, in case the installer is installing on multiple machines which
2099 share directory structure---these targets allow the machine-independent
2100 parts to be installed only once. The @code{install} target depends on
2101 both of these targets.
2102 @trindex install-data
2103 @trindex install-exec
2106 Automake also generates an @code{uninstall} target, an
2107 @code{installdirs} target, and an @code{install-strip} target.
2109 @trindex installdirs
2110 @trindex install-strip
2112 It is possible to extend this mechanism by defining an
2113 @code{install-exec-local} or @code{install-data-local} target. If these
2114 targets exist, they will be run at @samp{make install} time.
2115 @trindex install-exec-local
2116 @trindex install-data-local
2118 Variables using the standard directory prefixes @samp{data},
2119 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
2120 @samp{pkgdata}, or @samp{pkginclude} (eg @samp{data_DATA}) are installed
2121 by @samp{install-data}.
2123 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
2124 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
2125 @samp{pkglib} (eg @samp{bin_PROGRAMS}) are installed by
2126 @samp{install-exec}.
2128 Any variable using a user-defined directory prefix with @samp{exec} in
2129 the name (eg @samp{myexecbin_PROGRAMS} is installed by
2130 @samp{install-exec}. All other user-defined prefixes are installed by
2131 @samp{install-data}.
2133 Automake generates support for the @samp{DESTDIR} variable in all
2134 install rules; see @xref{Makefile Conventions, , , standards, The GNU
2139 @node Clean, Dist, Install, Top
2140 @chapter What Gets Cleaned
2142 The GNU Makefile Standards specify a number of different clean rules.
2144 Generally the files that can cleaned are determined automatically by
2145 Automake. Of course, Automake also recognizes some variables that can
2146 be defined to specify additional files to clean. These variables are
2147 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
2148 @code{MAINTAINERCLEANFILES}.
2149 @vindex MOSTLYCLEANFILES
2151 @vindex DISTCLEANFILES
2152 @vindex MAINTAINERCLEANFILES
2155 @node Dist, Tests, Clean, Top
2156 @chapter What Goes in a Distribution
2158 The @code{dist} target in the generated @file{Makefile.in} can be used
2159 to generate a gzip'd @code{tar} file for distribution. The tar file is
2160 named based on the @samp{PACKAGE} and @samp{VERSION} variables; more
2161 precisely it is named @samp{@var{package}-@var{version}.tar.gz}.
2166 For the most part, the files to distribute are automatically found by
2167 Automake: all source files are automatically included in a distribution,
2168 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
2169 has a built-in list of commonly used files which, if present in the
2170 current directory, are automatically included. This list is printed by
2171 @samp{automake --help}. Also, files which are read by @code{configure}
2172 (ie, the source files corresponding to the files specified in the
2173 @code{AC_OUTPUT} invocation) are automatically distributed.
2175 Still, sometimes there are files which must be distributed, but which
2176 are not covered in the automatic rules. These files should be listed in
2177 the @code{EXTRA_DIST} variable. Note that @code{EXTRA_DIST} can only
2178 handle files in the current directory; files in other directories will
2179 cause @code{make dist} runtime failures.
2182 If you define @code{SUBDIRS}, automake will recursively include the
2183 subdirectories in the distribution. If @code{SUBDIRS} is defined
2184 conditionally (@pxref{Conditionals}), automake will normally include all
2185 directories that could possibly appear in @code{SUBDIRS} in the
2186 distribution. If you need to specify the set of directories
2187 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
2188 list of subdirectories to include in the distribution.
2189 @vindex DIST_SUBDIRS
2191 Occasionally it is useful to be able to change the distribution before
2192 it is packaged up. If the @code{dist-hook} target exists, it is run
2193 after the distribution directory is filled, but before the actual tar
2194 (or shar) file is created. One way to use this is for distributing
2195 files in subdirectories for which a new @file{Makefile.am} is overkill:
2199 mkdir $(distdir)/random
2200 cp -p random/a1 random/a2 $(distdir)/random
2203 Automake also generates a @code{distcheck} target which can be help to
2204 ensure that a given distribution will actually work. @code{distcheck}
2205 makes a distribution, and then tries to do a @code{VPATH} build.
2207 @c FIXME: document distcheck-hook here
2209 @node Tests, Options, Dist, Top
2210 @chapter Support for test suites
2212 Automake supports a two forms of test suite.
2214 If the variable @code{TESTS} is defined, its value is taken to be a list
2215 of programs to run in order to do the testing. The programs can either
2216 be derived objects or source objects; the generated rule will look both
2217 in @var{srcdir} and @file{.}. Programs needing data files should look
2218 for them in @var{srcdir} (which is both an environment variable and a
2219 make variable) so they work when building in a separate directory
2220 (@pxref{Build Directories,,,autoconf}), and in particular for the
2221 @code{distcheck} target (@pxref{Dist}).
2223 The number of failures will be printed at the end of the run. If a
2224 given test program exits with a status of 77, then its result is ignored
2225 in the final count. This feature allows non-portable tests to be
2226 ignored in environments where they don't make sense.
2228 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
2229 variables for the test run; the environment variable @code{srcdir} is
2230 set in the rule. If all your test programs are scripts, you can also
2231 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (eg
2232 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
2234 @vindex TESTS_ENVIRONMENT
2236 If @samp{dejagnu} appears in @code{AUTOMAKE_OPTIONS}, then the a
2237 @code{dejagnu}-based test suite is assumed. The value of the variable
2238 @code{DEJATOOL} is passed as the @code{--tool} argument to
2239 @code{runtest}; it defaults to the name of the package.
2241 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
2242 @code{--srcdir} flags that are passed to dejagnu by default; this can be
2243 overridden if necessary.
2244 @vindex RUNTESTDEFAULTFLAGS
2246 The variables @code{EXPECT}, @code{RUNTEST} and @code{RUNTESTFLAGS} can
2247 also be overridden to provide project-specific values. For instance,
2248 you will need to do this if you are testing a compiler toolchain,
2249 because the default values do not take into account host and target
2255 @vindex RUNTESTFLAGS
2256 @c FIXME xref dejagnu
2258 In either case, the testing is done via @samp{make check}.
2261 @node Options, Miscellaneous, Tests, Top
2262 @chapter Changing Automake's Behavior
2264 Various features of Automake can be controlled by options in the
2265 @file{Makefile.am}. Such options are listed in a special variable named
2266 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
2267 @vindex AUTOMAKE_OPTIONS
2272 @itemx @code{foreign}
2274 Set the strictness as appropriate. The @code{gnits} option also implies
2275 @code{readme-alpha} and @code{check-news}.
2277 @item @code{ansi2knr}
2278 @itemx @code{path/ansi2knr}
2279 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceeded by a
2280 path, the generated @file{Makefile.in} will look in the specified
2281 directory to find the @file{ansi2knr} program. Generally the path
2282 should be a relative path to another directory in the same distribution
2283 (though Automake currently does not check this).
2285 @item @code{check-news}
2286 Cause @code{make dist} to fail unless the current version number appears
2287 in the first few lines of the @file{NEWS} file.
2289 @item @code{dejagnu}
2290 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
2292 @item @code{dist-shar}
2293 Generate a @code{dist-shar} target as well as the ordinary @code{dist}
2294 target. This new target will create a shar archive of the
2298 @item @code{dist-zip}
2299 Generate a @code{dist-zip} target as well as the ordinary @code{dist}
2300 target. This new target will create a zip archive of the distribution.
2303 @item @code{dist-tarZ}
2304 Generate a @code{dist-tarZ} target as well as the ordinary @code{dist}
2305 target. This new target will create a compressed tar archive of the
2306 distribution; a traditional @code{tar} and @code{compress} will be
2307 assumed. Warning: if you are actually using @code{GNU tar}, then the
2308 generated archive might contain nonportable constructs.
2311 @item @code{no-dependencies}
2312 This is similar to using @samp{--include-deps} on the command line, but
2313 is useful for those situations where you don't have the necessary bits
2314 to make automatic dependency tracking work @xref{Dependencies}. In this
2315 case the effect is to effectively disable automatic dependency tracking.
2317 @item @code{no-installinfo}
2318 The generated @file{Makefile.in} will not cause info pages to be built
2319 or installed by default. However, @code{info} and @code{install-info}
2320 targets will still be available. This option is disallowed at
2321 @samp{GNU} strictness and above.
2323 @trindex install-info
2325 @item @code{no-installman}
2326 The generated @file{Makefile.in} will not cause man pages to be
2327 installed by default. However, an @code{install-man} target will still
2328 be available for optional installation. This option is disallowed at
2329 @samp{GNU} strictness and above.
2330 @trindex install-man
2332 @item @code{no-texinfo.tex}
2333 Don't require @file{texinfo.tex}, even if there are texinfo files in
2336 @item @code{readme-alpha}
2337 If this release is an alpha release, and the file @file{README-alpha}
2338 exists, then it will be added to the distribution. If this option is
2339 given, version numbers are expected to follow one of two forms. The
2340 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
2341 element is a number; the final period and number should be left off for
2342 non-alpha releases. The second form is
2343 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
2344 letter; it should be omitted for non-alpha releases.
2347 A version number (eg @samp{0.30}) can be specified. If Automake is not
2348 newer than the version specified, creation of the @file{Makefile.in}
2352 Unrecognized options are diagnosed by @code{automake}.
2355 @node Miscellaneous, Conditionals, Options, Top
2356 @chapter Miscellaneous Rules
2358 There are a few rules and variables that didn't fit anywhere else.
2361 * Tags:: Interfacing to etags and mkid
2362 * Suffixes:: Handling new file extensions
2366 @node Tags, Suffixes, Miscellaneous, Miscellaneous
2367 @section Interfacing to @code{etags}
2369 @code{automake} will generate rules to generate @file{TAGS} files for
2370 use with GNU Emacs under some circumstances.
2372 If any C source code or headers are present, then @code{tags} and
2373 @code{TAGS} targets will be generated for the directory.
2376 At the topmost directory of a multi-directory package, a @code{tags}
2377 target file will be generated which, when run, will generate a
2378 @file{TAGS} file that includes by reference all @file{TAGS} files from
2381 Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
2382 will be generated. This variable is intended for use in directories
2383 which contain taggable source that @code{etags} does not understand.
2386 Here is how Automake generates tags for its source, and for nodes in its
2390 ETAGS_ARGS = automake.in --lang=none \
2391 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
2394 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
2395 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
2396 are added directly to the dependencies for the @code{tags} target.
2397 @vindex TAGS_DEPENDENCIES
2399 Automake will also generate an @code{ID} target which will run
2400 @code{mkid} on the source. This is only supported on a
2401 directory-by-directory basis.
2405 @node Suffixes, , Tags, Miscellaneous
2406 @section Handling new file extensions
2408 It is sometimes useful to introduce a new implicit rule to handle a file
2409 type that Automake does not know about. If this is done, you must
2410 notify GNU Make of the new suffixes. This can be done by putting a list
2411 of new suffixes in the @code{SUFFIXES} variable.
2414 For instance, currently automake does not provide any Java support. If
2415 you wrote a macro to generate @samp{.class} files from @samp{.java}
2416 source files, you would also need to add these suffixes to the list:
2419 SUFFIXES = .java .class
2422 @node Conditionals, Gnits, Miscellaneous, Top
2423 @chapter Conditionals
2425 Automake supports a simple type of conditionals.
2427 @cvindex AM_CONDITIONAL
2428 Before using a conditional, you must define it by using
2429 @code{AM_CONDITIONAL} in the @code{configure.in} file. The
2430 @code{AM_CONDITIONAL} macro takes two arguments.
2432 The first argument to @code{AM_CONDITIONAL} is the name of the
2433 conditional. This should be a simple string starting with a letter and
2434 containing only letters, digits, and underscores.
2436 The second argument to @code{AM_CONDITIONAL} is a shell condition,
2437 suitable for use in a shell if statement. The condition is evaluated
2438 when @code{configure} is run.
2440 Conditionals typically depend upon options which the user provides to
2441 the @code{configure} script. Here is an example of how to write a
2442 conditional which is true if the user uses the @samp{--enable-debug}
2446 AC_ARG_ENABLE(debug,
2447 [ --enable-debug Turn on debugging],
2448 [case "$@{enableval@}" in
2451 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
2452 esac],[debug=false])
2453 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
2456 Here is an example of how to use that conditional in @file{Makefile.am}:
2464 noinst_PROGRAMS = $(DBG)
2467 This trivial example could also be handled using EXTRA_PROGRAMS
2468 (@pxref{A Program}).
2470 You may only test a single variable in an @code{if} statement. The
2471 @code{else} statement may be omitted. Conditionals may be nested to any
2474 Note that conditionals in Automake are not the same as conditionals in
2475 GNU Make. Automake conditionals are checked at configure time by the
2476 @file{configure} script, and affect the translation from
2477 @file{Makefile.in} to @file{Makefile}. They are based on options passed
2478 to @file{configure} and on results that @file{configure} has discovered
2479 about the host system. GNU Make conditionals are checked at make time,
2480 and are based on variables passed to the make program or defined in the
2483 Automake conditionals will work with any make program.
2485 @node Gnits, Cygnus, Conditionals, Top
2486 @chapter The effect of @code{--gnu} and @code{--gnits}
2488 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
2489 variable) causes @code{automake} to check the following:
2493 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
2494 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
2495 directory of the package.
2498 The options @samp{no-installman} and @samp{no-installinfo} are
2502 Note that this option will be extended in the future to do even more
2503 checking; it is advisable to be familiar with the precise requirements
2504 of the GNU standards. Also, @samp{--gnu} can require certain
2505 non-standard GNU programs to exist for use by various maintainer-only
2506 targets; for instance in the future @code{pathchk} might be required for
2509 The @samp{--gnits} option does everything that @samp{--gnu} does, and
2510 checks the following as well:
2514 @samp{make dist} will check to make sure the @file{NEWS} file has been
2515 updated to the current version.
2518 The file @file{COPYING.LIB} is prohibited. The LGPL is apparently
2519 considered a failed experiment.
2522 @samp{VERSION} is checked to make sure its format complies with Gnits
2524 @c FIXME xref when standards are finished
2527 If @samp{VERSION} indicates that this is an alpha release, and the file
2528 @file{README-alpha} appears in the topmost directory of a package, then
2529 it is included in the distribution. This is done in @samp{--gnits}
2530 mode, and no other, because this mode is the only one where version
2531 number formats are constrained, and hence the only mode where
2532 @code{automake} can automatically determine whether @file{README-alpha}
2536 The file @file{THANKS} is required.
2540 @node Cygnus, Extending, Gnits, Top
2541 @chapter The effect of @code{--cygnus}
2543 Cygnus Solutions has slightly different rules for how a
2544 @file{Makefile.in} is to be constructed. Passing @samp{--cygnus} to
2545 @code{automake} will cause any generated @file{Makefile.in} to comply
2548 Here are the precise effects of @samp{--cygnus}:
2552 Info files are always created in the build directory, and not in the
2556 @file{texinfo.tex} is not required if a Texinfo source file is
2557 specified. The assumption is that the file will be supplied, but in a
2558 place that @code{automake} cannot find. This assumption is an artifact
2559 of how Cygnus packages are typically bundled.
2562 @samp{make dist} will look for files in the build directory as well as
2563 the source directory. This is required to support putting info files
2564 into the build directory.
2567 Certain tools will be searched for in the build tree as well as in the
2568 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
2569 @code{makeinfo} and @code{texi2dvi}.
2572 @code{--foreign} is implied.
2575 The options @samp{no-installinfo} and @samp{no-dependencies} are
2579 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
2583 The @code{check} target doesn't depend on @code{all}.
2586 GNU maintainers are advised to use @samp{gnu} strictness in preference
2587 to the special Cygnus mode.
2590 @node Extending, Distributing, Cygnus, Top
2591 @chapter When Automake Isn't Enough
2593 Automake's implicit copying semantics means that many problems can be
2594 worked around by simply adding some @code{make} targets and rules to
2595 @file{Makefile.in}. @code{automake} will ignore these additions.
2597 There are some caveats to doing this. Although you can overload a
2598 target already used by @code{automake}, it is often inadvisable,
2599 particularly in the topmost directory of a non-flat package. However,
2600 various useful targets have a @samp{-local} version you can specify in your
2601 @file{Makefile.in}. Automake will supplement the standard target with
2602 these user-supplied targets.
2604 The targets that support a local version are @code{all}, @code{info},
2605 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
2606 @code{uninstall}, and the various @code{clean} targets
2607 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
2608 @code{maintainer-clean}). Note that there are no
2609 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
2610 use @code{uninstall-local}. It doesn't make sense to uninstall just
2611 data or just executables.
2616 @trindex install-data
2617 @trindex install-exec
2620 For instance, here is one way to install a file in @file{/etc}:
2624 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
2627 Some targets also have a way to run another target, called a @dfn{hook},
2628 after their work is done. The hook is named after the principal target,
2629 with @samp{-hook} appended. The targets allowing hooks are
2630 @code{install-data}, @code{install-exec}, @code{dist}, and
2632 @trindex install-data-hook
2633 @trindex install-exec-hook
2636 For instance, here is how to create a hard link to an installed program:
2640 ln $(bindir)/program $(bindir)/proglink
2643 @c FIXME should include discussion of variables you can use in these
2647 @node Distributing, Future, Extending, Top
2648 @chapter Distributing @file{Makefile.in}s
2650 Automake places no restrictions on the distribution of the resulting
2651 @file{Makefile.in}s. We still encourage software authors to distribute
2652 their work under terms like those of the GPL, but doing so is not
2653 required to use Automake.
2655 Some of the files that can be automatically installed via the
2656 @code{--add-missing} switch do fall under the GPL; examine each file
2660 @node Future, Index, Distributing, Top
2661 @chapter Some ideas for the future
2663 Here are some things that might happen in the future:
2670 The output will be cleaned up. For instance, only variables which are
2671 actually used will appear in the generated @file{Makefile.in}.
2674 There will be support for automatically recoding a distribution. The
2675 intent is to allow a maintainer to use whatever character set is most
2676 convenient locally, but for all distributions to be Unicode or
2677 @w{ISO 10646} with the UTF-8 encoding.
2680 Support for automatically generating packages (eg Debian packages, RPM
2681 packages, Solaris packages, etc). This will happen more quickly if
2682 someone with package-building experience can tell me what would be
2686 Rewrite in Guile. This won't happen in the near future, but it will
2690 @node Index, , Future, Top