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.
85 @c Define an index of commands.
88 @c Put everything in one index (arbitrarily chosen to be the concept index).
96 @node Top, Introduction, (dir), (dir)
97 @comment node-name, next, previous, up
100 This file documents the GNU Automake package for creating GNU
101 Standards-compliant Makefiles from template files. This edition
102 documents version @value{VERSION}.
105 * Introduction:: Automake's purpose
106 * Generalities:: General ideas
107 * Examples:: Some example packages
108 * Invoking Automake:: Creating a Makefile.in
109 * configure:: Scanning configure.in
110 * Top level:: The top-level Makefile.am
111 * Programs:: Building programs and libraries
112 * Other objects:: Other derived objects
113 * Other GNU Tools:: Other GNU Tools
114 * Documentation:: Building documentation
115 * Install:: What gets installed
116 * Clean:: What gets cleaned
117 * Dist:: What goes in a distribution
118 * Tests:: Support for test suites
119 * Options:: Changing Automake's behavior
120 * Miscellaneous:: Miscellaneous rules
121 * Conditionals:: Conditionals
122 * Include:: Including extra files in an Automake template.
123 * Gnits:: The effect of @code{--gnu} and @code{--gnits}
124 * Cygnus:: The effect of @code{--cygnus}
125 * Extending:: Extending Automake
126 * Distributing:: Distributing the Makefile.in
127 * Future:: Some ideas for the future
128 * Index:: General index
130 --- The Detailed Node Listing ---
134 * General Operation:: General operation of Automake
135 * Depth:: The kinds of packages
136 * Strictness:: Standards conformance checking
137 * Uniform:: The Uniform Naming Scheme
138 * Canonicalization:: How derived variables are named
140 Some example packages
142 * Complete:: A simple example, start to finish
143 * Hello:: A classic program
144 * etags:: Building etags and ctags
146 Scanning @file{configure.in}
148 * Requirements:: Configuration requirements
149 * Optional:: Other things Automake recognizes
150 * Invoking aclocal:: Auto-generating aclocal.m4
151 * Macros:: Autoconf macros supplied with Automake
152 * Extending aclocal:: Writing your own aclocal macros
154 Building Programs and Libraries
156 * A Program:: Building a program
157 * A Library:: Building a library
158 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
159 * A Shared Library:: Building a Libtool library
160 * Program variables:: Variables used when building a program
161 * Yacc and Lex:: Yacc and Lex support
163 * ANSI:: Automatic de-ANSI-fication
164 * Dependencies:: Automatic dependency tracking
166 Other Derived Objects
168 * Scripts:: Executable scripts
169 * Headers:: Header files
170 * Data:: Architecture-independent data files
171 * Sources:: Derived sources
175 * Emacs Lisp:: Emacs Lisp
181 Building documentation
184 * Man pages:: Man pages
188 * Tags:: Interfacing to etags and mkid
189 * Suffixes:: Handling new file extensions
194 @node Introduction, Generalities, Top, Top
195 @chapter Introduction
197 Automake is a tool for automatically generating @file{Makefile.in}s from
198 files called @file{Makefile.am}. Each @file{Makefile.am} is basically a
199 series of @code{make} macro definitions (with rules being thrown in
200 occasionally). The generated @file{Makefile.in}s are compliant with the
201 GNU Makefile standards.
203 The GNU Makefile Standards Document
204 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
205 is long, complicated, and subject to change. The goal of Automake is to
206 remove the burden of Makefile maintenance from the back of the
207 individual GNU maintainer (and put it on the back of the Automake
210 The typical Automake input files is simply a series of macro
211 definitions. Each such file is processed to create a
212 @file{Makefile.in}. There should generally be one @file{Makefile.am}
213 per directory of a project.
215 Automake does constrain a project in certain ways; for instance it
216 assumes that the project uses Autoconf
217 (@pxref{Top, , The Autoconf Manual, autoconf, The Autoconf Manual}),
218 and enforces certain restrictions on the @file{configure.in} contents.
220 Automake requires @code{perl} in order to generate the
221 @file{Makefile.in}s. However, the distributions created by Automake are
222 fully GNU standards-compliant, and do not require @code{perl} in order
225 Mail suggestions and bug reports for Automake to
226 @email{bug-automake@@gnu.org}.
229 @node Generalities, Examples, Introduction, Top
230 @chapter General ideas
232 There are a few basic ideas that will help understand how Automake
236 * General Operation:: General operation of Automake
237 * Depth:: The kinds of packages
238 * Strictness:: Standards conformance checking
239 * Uniform:: The Uniform Naming Scheme
240 * Canonicalization:: How derived variables are named
243 @node General Operation, Depth, Generalities, Generalities
244 @section General Operation
246 Automake works by reading a @file{Makefile.am} and generating a
247 @file{Makefile.in}. Certain macros and targets defined in the
248 @file{Makefile.am} instruct automake to generate more specialized code;
249 for instances a @samp{bin_PROGRAMS} macro definition will cause targets
250 for compiling and linking to be generated.
252 The macro definitions and targets in the @file{Makefile.am} are copied
253 into the generated file. This allows you to add arbitrary code into the
254 generated @file{Makefile.in}. For instance the Automake distribution
255 includes a non-standard @code{cvs-dist} target, which the Automake
256 maintainer uses to make distributions from his source control system.
258 Note that GNU make extensions are not recognized by Automake. Using
259 such extensions in a @file{Makefile.am} will lead to errors or confusing
262 Automake tries to group comments with adjoining targets (or variable
263 definitions) in an intelligent way.
265 A target defined in @file{Makefile.am} generally overrides any such
266 target of a similar name that would be automatically generated by
267 @code{automake}. Although this is a supported feature, it is generally
268 best to avoid making use of it, as sometimes the generated rules are
271 Similarly, a variable defined in @file{Makefile.am} will override any
272 definition of the variable that @code{automake} would ordinarily create.
273 This feature is more often useful than the ability to override a target
274 definition. Be warned that many of the variables generated by
275 @code{automake} are considered to be for internal use only, and their
276 names might change in future releases.
278 When examining a variable definition, Automake will recursively examine
279 variables referenced in the definition. E.g., if Automake is looking at
280 the content of @samp{foo_SOURCES} in this snippet
284 foo_SOURCES = c.c $(xs)
287 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
288 contents of @samp{foo_SOURCES}.
290 Automake also allows a form of comment which is @emph{not} copied into
291 the output; all lines beginning with @samp{##} are completely ignored by
294 It is customary to make the first line of @file{Makefile.am} read:
297 ## Process this file with automake to produce Makefile.in
300 @c FIXME discuss putting a copyright into Makefile.am here? I would but
301 @c I don't know quite what to say.
303 @c FIXME document customary ordering of Makefile.am here!
307 @node Depth, Strictness, General Operation, Generalities
309 @code{automake} supports three kinds of directory hierarchy: ``flat'',
310 ``shallow'', and ``deep''.
312 A @dfn{flat} package is one in which all the files are in a single
313 directory. The @file{Makefile.am} for such a package by definition
314 lacks a @code{SUBDIRS} macro. An example of such a package is
318 A @dfn{deep} package is one in which all the source lies in
319 subdirectories; the top level directory contains mainly configuration
320 information. GNU cpio is a good example of such a package, as is GNU
321 @code{tar}. The top level @file{Makefile.am} for a deep package will
322 contain a @code{SUBDIRS} macro, but no other macros to define objects
325 A @dfn{shallow} package is one in which the primary source resides in
326 the top-level directory, while various parts (typically libraries)
327 reside in subdirectories. Automake is one such package (as is GNU
328 @code{make}, which does not currently use @code{automake}).
331 @node Strictness, Uniform, Depth, Generalities
333 While Automake is intended to be used by maintainers of GNU packages, it
334 does make some effort to accommodate those who wish to use it, but do
335 not want to use all the GNU conventions.
337 To this end, Automake supports three levels of @dfn{strictness}---the
338 strictness indicating how stringently Automake should check standards
341 The valid strictness levels are:
345 Automake will check for only those things which are absolutely
346 required for proper operations. For instance, whereas GNU standards
347 dictate the existence of a @file{NEWS} file, it will not be required in
348 this mode. The name comes from the fact that Automake is intended to be
349 used for GNU programs; these relaxed rules are not the standard mode of
353 Automake will check---as much as possible---for compliance to the GNU
354 standards for packages. This is the default.
357 Automake will check for compliance to the as-yet-unwritten Gnits
358 standards. These are based on the GNU standards, but are even more
359 detailed. Unless you are a Gnits standards contributor, it is
360 recommended that you avoid this option until such time as the Gnits
361 standard is actually published.
364 For more information on the precise implications of the strictness
365 level, see @xref{Gnits}.
368 @node Uniform, Canonicalization, Strictness, Generalities
369 @section The Uniform Naming Scheme
370 Automake variables generally follow a uniform naming scheme that makes
371 it easy to decide how programs (and other derived objects) are built,
372 and how they are installed. This scheme also supports @code{configure}
373 time determination of what should be built.
375 At @code{make} time, certain variables are used to determine which
376 objects are to be built. These variables are called @dfn{primary}
377 variables. For instance, the primary variable @code{PROGRAMS} holds a
378 list of programs which are to be compiled and linked.
381 A different set of variables is used to decide where the built objects
382 should be installed. These variables are named after the primary
383 variables, but have a prefix indicating which standard directory should
384 be used as the installation directory. The standard directory names are
385 given in the GNU standards
386 (@pxref{Directory Variables, , , standards, The GNU Coding
388 Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
389 and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
390 versions, but with @samp{@@PACKAGE@@} appended. For instance,
391 @code{pkglibdir} is defined as @code{$(datadir)/@@PACKAGE@@}.
394 For each primary, there is one additional variable named by prepending
395 @samp{EXTRA_} to the primary name. This variable is used to list
396 objects which may or may not be built, depending on what
397 @code{configure} decides. This variable is required because Automake
398 must statically know the entire list of objects to be built in order to
399 generate a @file{Makefile.in} that will work in all cases.
401 For instance, @code{cpio} decides at configure time which programs are
402 built. Some of the programs are installed in @code{bindir}, and some
403 are installed in @code{sbindir}:
406 EXTRA_PROGRAMS = mt rmt
407 bin_PROGRAMS = cpio pax
408 sbin_PROGRAMS = @@PROGRAMS@@
411 Defining a primary variable without a prefix (eg @code{PROGRAMS}) is an
414 Note that the common @samp{dir} suffix is left off when constructing the
415 variable names; thus one writes @samp{bin_PROGRAMS} and not
416 @samp{bindir_PROGRAMS}.
418 Not every sort of object can be installed in every directory. Automake
419 will flag those attempts it finds in error. Automake will also diagnose
420 obvious misspellings in directory names.
422 Sometimes the standard directories---even as augmented by Automake---
423 are not enough. In particular it is sometimes useful, for clarity, to
424 install objects in a subdirectory of some predefined directory. To this
425 end, Automake allows you to extend the list of possible installation
426 directories. A given prefix (eg @samp{zar}) is valid if a variable of
427 the same name with @samp{dir} appended is defined (eg @samp{zardir}).
429 For instance, until HTML support is part of Automake, you could use this
430 to install raw HTML documentation:
433 htmldir = $(prefix)/html
434 html_DATA = automake.html
437 The special prefix @samp{noinst} indicates that the objects in question
438 should not be installed at all.
440 The special prefix @samp{check} indicates that the objects in question
441 should not be built until the @code{make check} command is run.
443 Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
444 @samp{LISP}, @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS},
456 @node Canonicalization, , Uniform, Generalities
457 @section How derived variables are named
459 Sometimes a Makefile variable name is derived from some text the user
460 supplies. For instance program names are rewritten into Makefile macro
461 names. Automake canonicalizes this text, so that it does not have to
462 follow Makefile variable naming rules. All characters in the name
463 except for letters, numbers, and the underscore are turned into
464 underscores when making macro references. E.g., if your program is named
465 @code{sniff-glue}, the derived variable name would be
466 @code{sniff_glue_SOURCES}, not @code{sniff-glue_SOURCES}.
469 @node Examples, Invoking Automake, Generalities, Top
470 @chapter Some example packages
473 * Complete:: A simple example, start to finish
474 * Hello:: A classic program
475 * etags:: Building etags and ctags
478 @node Complete, Hello, Examples, Examples
479 @section A simple example, start to finish
481 Let's suppose you just finished writing @code{zardoz}, a program to make
482 your head float from vortex to vortex. You've been using
483 @code{autoconf} to provide a portability framework, but your
484 @file{Makefile.in}s have been ad-hoc. You want to make them
485 bulletproof, so you turn to @code{automake}.
487 The first step is to update your @file{configure.in} to include the
488 commands that @code{automake} needs. The simplest way to do this is to
489 add an @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
492 AM_INIT_AUTOMAKE(zardoz, 1.0)
495 Since your program doesn't have any complicating factors (e.g., it
496 doesn't use @code{gettext}, it doesn't want to build a shared library),
497 you're done with this part. That was easy!
499 Now you must regenerate @file{configure}. But to do that, you'll need
500 to tell @code{autoconf} how to find the new macro you've used. The
501 easiest way to do this is to use the @code{aclocal} program to generate
502 your @file{aclocal.m4} for you. But wait... you already have an
503 @file{aclocal.m4}, because you had to write some hairy macros for your
504 program. @code{aclocal} lets you put your own macros into
505 @file{acinclude.m4}, so simply rename and then run:
508 mv aclocal.m4 acinclude.m4
513 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
514 @code{zardoz} is a user program, so you want to install it where the
515 rest of the user programs go. @code{zardoz} also has some Texinfo
516 documentation. Your @file{configure.in} script uses
517 @code{AC_REPLACE_FUNCS}, so you need to link against @samp{@@LIBOBJS@@}.
518 So here's what you'd write:
521 bin_PROGRAMS = zardoz
522 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
523 zardoz_LDADD = @@LIBOBJS@@
525 info_TEXINFOS = zardoz.texi
528 Now you can run @code{automake --add-missing} to generate your
529 @file{Makefile.in} and grab any auxiliary files you might need, and
533 @node Hello, etags, Complete, Examples
534 @section A classic program
536 @code{hello} is renowned for its classic simplicity and versatility.
537 This section shows how Automake could be used with the Hello package.
538 The examples below are from the latest GNU Hello, but all the
539 maintainer-only code has been stripped out, as well as all copyright
542 Of course, GNU Hello is somewhat more featureful than your traditional
543 two-liner. GNU Hello is internationalized, does option processing, and
544 has a manual and a test suite. GNU Hello is a deep package.
546 Here is the @file{configure.in} from GNU Hello:
549 dnl Process this file with autoconf to produce a configure script.
551 AM_INIT_AUTOMAKE(hello, 1.3.11)
552 AM_CONFIG_HEADER(config.h)
554 dnl Set of available languages.
555 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
557 dnl Checks for programs.
561 dnl Checks for libraries.
563 dnl Checks for header files.
565 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
567 dnl Checks for library functions.
570 dnl Check for st_blksize in struct stat
573 dnl internationalization macros
575 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
576 src/Makefile tests/Makefile tests/hello],
577 [chmod +x tests/hello])
580 The @samp{AM_} macros are provided by Automake (or the Gettext library);
581 the rest are standard Autoconf macros.
584 The top-level @file{Makefile.am}:
587 EXTRA_DIST = BUGS ChangeLog.O
588 SUBDIRS = doc intl po src tests
591 As you can see, all the work here is really done in subdirectories.
593 The @file{po} and @file{intl} directories are automatically generated
594 using @code{gettextize}; they will not be discussed here.
596 In @file{doc/Makefile.am} we see:
599 info_TEXINFOS = hello.texi
600 hello_TEXINFOS = gpl.texi
603 This is sufficient to build, install, and distribute the Hello manual.
606 Here is @file{tests/Makefile.am}:
610 EXTRA_DIST = hello.in testdata
613 The script @file{hello} is generated by @code{configure}, and is the
614 only test case. @code{make check} will run this test.
616 Last we have @file{src/Makefile.am}, where all the real work is done:
620 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
621 hello_LDADD = @@INTLLIBS@@ @@ALLOCA@@
622 localedir = $(datadir)/locale
623 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
627 @node etags, , Hello, Examples
628 @section Building etags and ctags
630 Here is another, trickier example. It shows how to generate two
631 programs (@code{ctags} and @code{etags}) from the same source file
632 (@file{etags.c}). The difficult part is that each compilation of
633 @file{etags.c} requires different @code{cpp} flags.
636 bin_PROGRAMS = etags ctags
638 ctags_LDADD = ctags.o
641 $(COMPILE) -DETAGS_REGEXPS -c etags.c
644 $(COMPILE) -DCTAGS -o ctags.o -c etags.c
647 Note that @code{ctags_SOURCES} is defined to be empty---that way no
648 implicit value is substituted. The implicit value, however, is used to
649 generate @code{etags} from @file{etags.o}.
651 @code{ctags_LDADD} is used to get @file{ctags.o} into the link line.
652 @code{ctags_DEPENDENCIES} is generated by Automake.
654 The above rules won't work if your compiler doesn't accept both
655 @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
656 bogus dependency (to avoid problems with a parallel @code{make}):
659 etags.o: etags.c ctags.o
660 $(COMPILE) -DETAGS_REGEXPS -c etags.c
663 $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
666 Also, these explicit rules do not work if the de-ANSI-fication feature
667 is used; supporting that requires a little more work:
670 etags._o: etags._c ctags.o
671 $(COMPILE) -DETAGS_REGEXPS -c etags.c
674 $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
678 @node Invoking Automake, configure, Examples, Top
679 @chapter Creating a @file{Makefile.in}
681 To create all the @file{Makefile.in}s for a package, run the
682 @code{automake} program in the top level directory, with no arguments.
683 @code{automake} will automatically find each appropriate
684 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
685 and generate the corresponding @file{Makefile.in}. Note that
686 @code{automake} has a rather simplistic view of what constitutes a
687 package; it assumes that a package has only one @file{configure.in}, at
688 the top. If your package has multiple @file{configure.in}s, then you
689 must run @code{automake} in each directory holding a
692 You can optionally give @code{automake} an argument; @samp{.am} is
693 appended to the argument and the result is used as the name of the input
694 file. This feature is generally only used to automatically rebuild an
695 out-of-date @file{Makefile.in}. Note that @code{automake} must always
696 be run from the topmost directory of a project, even if being used to
697 regenerate the @file{Makefile.in} in some subdirectory. This is
698 necessary because @code{automake} must scan @file{configure.in}, and
699 because @code{automake} uses the knowledge that a @file{Makefile.in} is
700 in a subdirectory to change its behavior in some cases.
702 @code{automake} accepts the following options:
707 Automake requires certain common files to exist in certain situations;
708 for instance @file{config.guess} is required if @file{configure.in} runs
709 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
710 files; this option will cause the missing ones to be automatically added
711 to the package, whenever possible. In general if Automake tells you a
712 file is missing, try using this option. By default Automake tries to
713 make a symbolic link pointing to its own copy of the missing file; this
714 can be changed with @code{--copy}.
716 @item --amdir=@var{dir}
717 Look for Automake data files in directory @var{dir} instead of in the
718 installation directory. This is typically used for debugging.
720 @item --build-dir=@var{dir}
721 Tell Automake where the build directory is. This option is used when
722 including dependencies into a @file{Makefile.in} generated by @code{make
723 dist}; it should not be used otherwise.
727 When used with @code{--add-missing}, causes installed files to be
728 copied. The default is to make a symbolic link.
731 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
732 of GNU or Gnits rules. @xref{Cygnus} for more information.
735 Set the global strictness to @samp{foreign}. @xref{Strictness} for more
739 Set the global strictness to @samp{gnits}. @xref{Gnits} for more
743 Set the global strictness to @samp{gnu}. @xref{Gnits} for more
744 information. This is the default strictness.
747 Print a summary of the command line options and exit.
750 @itemx --include-deps
751 Include all automatically generated dependency information
752 (@pxref{Dependencies}) in the generated
753 @file{Makefile.in}. This is generally done when making a distribution;
756 @item --generate-deps
757 Generate a file concatenating all automatically generated dependency
758 information (@pxref{Dependencies}) into one file, @file{.dep_segment}.
759 This is generally done when making a distribution; see @ref{Dist}. It
760 is useful when maintaining a @file{SMakefile} or makefiles for other
761 platforms (@file{Makefile.DOS}, etc.) It can only be used in
762 conjunction with @code{--include-deps}, @code{--srcdir-name}, and
763 @code{--build-dir}. Note that if this option is given, no other
767 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
768 @file{configure.in}. This option causes it to only update those
769 @file{Makefile.in}s which are out of date with respect to one of their
773 @itemx --output-dir=@var{dir}
774 Put the generated @file{Makefile.in} in the directory @var{dir}.
775 Ordinarily each @file{Makefile.in} is created in the directory of the
776 corresponding @file{Makefile.am}. This option is used when making
779 @item --srcdir-name=@var{dir}
780 Tell Automake the name of the source directory associated with the
781 current build. This option is used when including dependencies into a
782 @file{Makefile.in} generated by @code{make dist}; it should not be used
787 Cause Automake to print information about which files are being read or
791 Print the version number of Automake and exit.
795 @node configure, Top level, Invoking Automake, Top
796 @chapter Scanning @file{configure.in}
798 Automake scans the package's @file{configure.in} to determine certain
799 information about the package. Some @code{autoconf} macros are required
800 and some variables must be defined in @file{configure.in}. Automake
801 will also use information from @file{configure.in} to further tailor its
804 Automake also supplies some @code{autoconf} macros to make the
805 maintenance easier. These macros can automatically be put into your
806 @file{aclocal.m4} using the @code{aclocal} program.
809 * Requirements:: Configuration requirements
810 * Optional:: Other things Automake recognizes
811 * Invoking aclocal:: Auto-generating aclocal.m4
812 * Macros:: Autoconf macros supplied with Automake
813 * Extending aclocal:: Writing your own aclocal macros
817 @node Requirements, Optional, configure, configure
818 @section Configuration requirements
820 The simplest way to meet the basic Automake requirements is to use the
821 macro @code{AM_INIT_AUTOMAKE} (@pxref{Macros}). But if you prefer, you
822 can do the required steps by hand:
823 @cvindex AM_INIT_AUTOMAKE
827 Define the variables @code{PACKAGE} and @code{VERSION} with
831 @code{PACKAGE} should be the name of the package as it appears when
832 bundled for distribution. For instance, Automake defines @code{PACKAGE}
833 to be @samp{automake}. @code{VERSION} should be the version number of
834 the release that is being developed. We recommend that you make
835 @file{configure.in} the only place in your package where the version
836 number is defined; this makes releases simpler.
838 Automake doesn't do any interpretation of @code{PACKAGE} or
839 @code{VERSION}, except in @samp{Gnits} mode (@pxref{Gnits}).
842 Use the macro @code{AC_ARG_PROGRAM} if a program or script is installed.
843 @cvindex AC_ARG_PROGRAM
846 Use @code{AC_PROG_MAKE_SET} if the package is not flat.
847 @cvindex AC_PROG_MAKE_SET
850 Use @code{AM_SANITY_CHECK} to make sure the build environment is sane.
853 Use @code{AM_PROG_INSTALL} if any scripts (@pxref{Scripts}) are
854 installed by the package. Otherwise, use @code{AC_PROG_INSTALL}.
855 @cvindex AC_PROG_INSTALL
856 @cvindex AM_PROG_INSTALL
859 Use @code{AM_MISSING_PROG} to see whether the programs @code{aclocal},
860 @code{autoconf}, @code{automake}, @code{autoheader}, and @code{makeinfo}
861 are in the build environment. Here is how this is done:
863 missing_dir=`cd $ac_aux_dir && pwd`
864 AM_MISSING_PROG(ACLOCAL, aclocal, $missing_dir)
865 AM_MISSING_PROG(AUTOCONF, autoconf, $missing_dir)
866 AM_MISSING_PROG(AUTOMAKE, automake, $missing_dir)
867 AM_MISSING_PROG(AUTOHEADER, autoheader, $missing_dir)
868 AM_MISSING_PROG(MAKEINFO, makeinfo, $missing_dir)
873 Here are the other macros which Automake requires but which are not run
874 by @code{AM_INIT_AUTOMAKE}:
878 Automake uses this to determine which files to create. Listed files
879 named @code{Makefile} are treated as @file{Makefile}s. Other listed
880 files are treated differently. Currently the only difference is that a
881 @file{Makefile} is removed by @code{make distclean}, while other files
882 are removed by @code{make clean}.
883 @c FIXME: this is in violation of standards!
887 @node Optional, Invoking aclocal, Requirements, configure
888 @section Other things Automake recognizes
890 Automake will also recognize the use of certain macros and tailor the
891 generated @file{Makefile.in} appropriately. Currently recognized macros
892 and their effects are:
895 @item AC_CONFIG_HEADER
896 Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar
897 to @code{AC_CONFIG_HEADER} but does some useful Automake-specific work.
898 @cvindex AC_CONFIG_HEADER
900 @item AC_CONFIG_AUX_DIR
901 Automake will look for various helper scripts, such as
902 @file{mkinstalldirs}, in the directory named in this macro invocation.
903 If not seen, the scripts are looked for in their ``standard'' locations
904 (either the top source directory, or in the source directory
905 corresponding to the current @file{Makefile.am}, whichever is
907 @cvindex AC_CONFIG_AUX_DIR
908 FIXME: give complete list of things looked for in this directory
911 Automake will insert definitions for the variables defined by
912 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
914 @cvindex AC_PATH_XTRA
916 @item AC_CANONICAL_HOST
918 Automake will ensure that @file{config.guess} and @file{config.sub}
919 exist. Also, the @file{Makefile} variables @samp{host_alias} and
920 @samp{host_triplet} are introduced.
921 @c fixme xref autoconf docs.
922 @cvindex AC_CANONICAL_HOST
923 @cvindex AC_CHECK_TOOL
927 @item AC_CANONICAL_SYSTEM
928 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
929 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
930 @cvindex AC_CANONICAL_SYSTEM
935 @itemx AC_FUNC_GETLOADAVG
936 @itemx AC_FUNC_MEMCMP
937 @itemx AC_STRUCT_ST_BLOCKS
938 @itemx AC_FUNC_FNMATCH
939 @itemx AM_FUNC_STRTOD
940 @itemx AC_REPLACE_FUNCS
941 @itemx AC_REPLACE_GNU_GETOPT
943 Automake will ensure that the appropriate dependencies are generated for
944 the objects corresponding to these macros. Also, Automake will verify
945 that the appropriate source files are part of the distribution. Note
946 that Automake does not come with any of the C sources required to use
947 these macros, so @code{automake -a} will not install the sources.
948 @xref{A Library} for more information.
949 @cvindex AC_FUNC_ALLOCA
950 @cvindex AC_FUNC_GETLOADAVG
951 @cvindex AC_FUNC_MEMCMP
952 @cvindex AC_STRUCT_ST_BLOCKS
953 @cvindex AC_FUNC_FNMATCH
954 @cvindex AC_FUNC_FNMATCH
955 @cvindex AC_REPLACE_FUNCS
956 @cvindex AC_REPLACE_GNU_GETOPT
957 @cvindex AM_FUNC_STRTOD
958 @cvindex AM_WITH_REGEX
961 Automake will detect statements which put @samp{.o} files into
962 @code{LIBOBJS}, and will treat these additional files as if they were
963 discovered via @code{AC_REPLACE_FUNCS}.
967 This is required if any libraries are built in the package.
968 @cvindex AC_PROG_RANLIB
971 This is required if any C++ source is included.
974 @item AM_PROG_LIBTOOL
975 Automake will turn on processing for @code{libtool} (@pxref{Top, , The
976 Libtool Manual, libtool, The Libtool Manual}).
977 @cvindex AM_PROG_LIBTOOL
980 If a Yacc source file is seen, then you must either use this macro or
981 define the variable @samp{YACC} in @file{configure.in}. The former is
983 @cvindex AC_PROG_YACC
987 This macro is required if there is Lex source in the package.
988 @cvindex AC_DECL_YYTEXT
991 If a Lex source file is seen, then this macro must be used.
995 If Automake sees that this variable is set in @file{configure.in}, it
996 will check the @file{po} directory to ensure that all the named
997 @samp{.po} files exist, and that all the @samp{.po} files that exist are
1001 @item AM_C_PROTOTYPES
1002 This is required when using automatic de-ANSI-fication, see @ref{ANSI}.
1003 @cvindex AM_C_PROTOTYPES
1005 @item AM_GNU_GETTEXT
1006 This macro is required for packages which use GNU gettext
1007 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1008 this macro it ensures that the package meets some of gettext's
1010 @cvindex AM_GNU_GETTEXT
1012 @item AM_MAINTAINER_MODE
1013 This macro adds a @samp{--enable-maintainer-mode} option to
1014 @code{configure}. If this is used, @code{automake} will cause
1015 ``maintainer-only'' rules to be turned off by default in the generated
1016 @file{Makefile.in}s. This macro is disallowed in @samp{Gnits} mode
1018 @cvindex AM_MAINTAINER_MODE
1021 @itemx AC_CHECK_TOOL
1022 @itemx AC_CHECK_PROG
1023 @itemx AC_CHECK_PROGS
1025 @itemx AC_PATH_PROGS
1026 For each of these macros, the first argument is automatically defined as
1027 a variable in each generated @file{Makefile.in}.
1029 @cvindex AC_CHECK_TOOL
1030 @cvindex AC_CHECK_PROG
1031 @cvindex AC_CHECK_PROGS
1032 @cvindex AC_PATH_PROG
1033 @cvindex AC_PATH_PROGS
1038 @node Invoking aclocal, Macros, Optional, configure
1039 @section Auto-generating aclocal.m4
1041 Automake includes a number of Autoconf macros which can be used in your
1042 package; some of them are actually required by Automake in certain
1043 situations. These macros must be defined in your @file{aclocal.m4};
1044 otherwise they will not be seen by @code{autoconf}.
1046 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1047 files based on the contents of @file{configure.in}. This provides a
1048 convenient way to get Automake-provided macros, without having to
1049 search around. Also, the @code{aclocal} mechanism is extensible for use
1052 At startup, @code{aclocal} scans all the @samp{.m4} files it can find,
1053 looking for macro definitions. Then it scans @file{configure.in}. Any
1054 mention of one of the macros found in the first step causes that macro,
1055 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1057 The contents of @file{acinclude.m4}, if it exists, are also
1058 automatically included in @file{aclocal.m4}. This is useful for
1059 incorporating local macros into @file{configure}.
1061 @code{aclocal} accepts the following options:
1064 @item --acdir=@var{dir}
1065 Look for the macro files in @var{dir} instead of the installation
1066 directory. This is typically used for debugging.
1069 Print a summary of the command line options and exit.
1072 Add the directory @var{dir} to the list of directories searched for
1075 @item --output=@var{file}
1076 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1078 @item --print-ac-dir
1079 Prints the name of the directory which @code{aclocal} will search to
1080 find the @samp{m4} files. When this option is given, normal processing
1081 is suppressed. This option can be used by a package to determine where
1082 to install a macro file.
1085 Print the names of the files it examines.
1088 Print the version number of Automake and exit.
1092 @node Macros, Extending aclocal, Invoking aclocal, configure
1093 @section Autoconf macros supplied with Automake
1095 @c consider generating this node automatically from m4 files.
1098 @item AM_CONFIG_HEADER
1099 Automake will generate rules to automatically regenerate the config
1100 header. If you do use this macro, you must create the file
1101 @file{stamp-h.in} in your source directory. It can be empty.
1102 @cvindex AM_CONFIG_HEADER
1105 Check to see if this @code{configure} is being run in the
1106 @samp{Cygwin32} environment. (FIXME xref). If so, define output
1107 variable @code{EXEEXT} to @samp{.exe}; otherwise define it to the empty
1108 string. Automake recognizes this macro and uses it to generate
1109 @file{Makefile.in}s which will automatically work under @samp{Cygwin32}.
1110 In the @samp{Cygwin32} environment, @code{gcc} generates executables
1111 whose names end in @samp{.exe}, even if this was not specified on the
1112 command line. Automake adds special code to @file{Makefile.in} to
1113 gracefully deal with this.
1115 @item AM_FUNC_STRTOD
1116 If the @code{strtod} function is not available, or does not work
1117 correctly (like the one on SunOS 5.4), add @file{strtod.o} to output
1118 variable @code{LIBOBJS}.
1119 @cvindex AM_FUNC_STRTOD
1121 @item AM_FUNC_ERROR_AT_LINE
1122 If the function @code{error_at_line} is not found, then add
1123 @file{error.o} to @code{LIBOBJS}.
1124 @cvindex AM_FUNC_ERROR_AT_LINE
1126 @item AM_FUNC_MKTIME
1127 Check for a working @code{mktime} function. If not found, add
1128 @file{mktime.o} to @samp{LIBOBJS}.
1129 @cvindex AM_FUNC_MKTIME
1131 @item AM_FUNC_OBSTACK
1132 Check for the GNU obstacks code; if not found, add @file{obstack.o} to
1134 @cvindex AM_FUNC_OBSTACK
1136 @item AM_C_PROTOTYPES
1137 Check to see if function prototypes are understood by the compiler. If
1138 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1139 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1140 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1141 values to implement automatic de-ANSI-fication.
1142 @cvindex AM_C_PROTOTYPES
1144 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1145 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1146 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1147 found in @file{<termios.h>}.
1148 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1150 @item AM_INIT_AUTOMAKE
1151 Runs many macros that most @file{configure.in}'s need. This macro has
1152 two required arguments, the package and the version number. By default
1153 this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}. This
1154 can be avoided by passing in a non-empty third argument.
1156 @item AM_PATH_LISPDIR
1157 Searches for the program @code{emacs}, and, if found, sets the output
1158 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1159 @cvindex AM_PATH_LISPDIR
1161 @item AM_PROG_CC_STDC
1162 If the C compiler in not in ANSI C mode by default, try to add an option
1163 to output variable @code{CC} to make it so. This macro tries various
1164 options that select ANSI C on some system or another. It considers the
1165 compiler to be in ANSI C mode if it handles function prototypes correctly.
1167 If you use this macro, you should check after calling it whether the C
1168 compiler has been set to accept ANSI C; if not, the shell variable
1169 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1170 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1171 @code{ansi2knr} option.
1172 @cvindex AM_PROG_CC_STDC
1174 @item AM_PROG_INSTALL
1175 Like @code{AC_PROG_INSTALL}, but also defines @code{INSTALL_SCRIPT}.
1176 @cvindex AM_PROG_INSTALL
1179 Like @code{AC_PROG_LEX} with @code{AC_DECL_YYTEXT}, but uses the
1180 @code{missing} script on systems that do not have lex. @samp{HP-UX 10}
1182 @cvindex AM_PROG_LEX
1184 @item AM_SANITY_CHECK
1185 This checks to make sure that a file created in the build directory is
1186 newer than a file in the source directory. This can fail on systems
1187 where the clock is set incorrectly. This macro is automatically run
1188 from @code{AM_INIT_AUTOMAKE}.
1189 @cvindex AM_SANITY_CHECK
1191 @item AM_SYS_POSIX_TERMIOS
1192 Check to see if POSIX termios headers and functions are available on the
1193 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1194 @samp{yes}. If not, set the variable to @samp{no}.
1195 @cvindex AM_SYS_POSIX_TERMIOS
1197 @item AM_TYPE_PTRDIFF_T
1198 Define @samp{HAVE_PTRDIFF_T} if the type @samp{ptrdiff_t} is defined in
1200 @cvindex AM_TYPE_PTRDIFF_T
1202 @item AM_WITH_DMALLOC
1203 Add support for the @code{dmalloc} package. If the user configures with
1204 @samp{--with-dmalloc}, then define @code{WITH_DMALLOC} and add
1205 @samp{-ldmalloc} to @code{LIBS}. The @code{dmalloc} package can be
1206 found at @url{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz}
1207 @cvindex AM_WITH_DMALLOC
1210 Adds @samp{--with-regex} to the @code{configure} command line. If
1211 specified (the default), then the @samp{regex} regular expression
1212 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1213 @samp{WITH_REGEX} is defined.. If @samp{--without-regex} is given, then
1214 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1215 into @samp{LIBOBJS}.
1216 @cvindex AM_WITH_REGEX
1220 @node Extending aclocal, , Macros, configure
1221 @section Writing your own aclocal macros
1223 Aclocal doesn't have any built-in knowledge of any macros, so it is easy
1224 to extend it with your own macros.
1226 This is mostly used for libraries which want to supply their own
1227 Autoconf macros for use by other programs. For instance the
1228 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1229 should be used by any package using @code{gettext}. When the library is
1230 installed, it installs this macro so that @code{aclocal} will find it.
1232 A file of macros should be a series of @code{AC_DEFUN}'s. Aclocal also
1233 understands @code{AC_REQUIRE}, so it is safe to put each macro in a
1236 A macro file's name should end in @samp{.m4}. Such files should be
1237 installed in @file{$(datadir)/aclocal}.
1239 @node Top level, Programs, configure, Top
1240 @chapter The top-level @file{Makefile.am}
1242 In non-flat packages, the top level @file{Makefile.am} must tell
1243 Automake which subdirectories are to be built. This is done via the
1244 @code{SUBDIRS} variable.
1247 The @code{SUBDIRS} macro holds a list of subdirectories in which
1248 building of various sorts can occur. Many targets (eg @code{all}) in
1249 the generated @file{Makefile} will run both locally and in all specified
1250 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1251 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1252 (after configuration). This allows inclusion of libraries from packages
1253 which do not use Automake (such as @code{gettext}). The directories
1254 mentioned in @code{SUBDIRS} must be direct children of the current
1255 directory. For instance, you cannot put @samp{src/subdir} into
1258 In a deep package, the top-level @file{Makefile.am} is often very short.
1259 For instance, here is the @file{Makefile.am} from the Hello
1263 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1264 SUBDIRS = doc intl po src tests
1267 It is possible to override the @code{SUBDIRS} variable if, like in the
1268 case of GNU @code{Inetutils}, you want to only build a subset of the
1269 entire package. In your @file{Makefile.am} include:
1272 SUBDIRS = @@SUBDIRS@@
1275 Then in your @file{configure.in} you can specify:
1278 SUBDIRS="src doc lib po"
1282 The upshot of this is that automake is tricked into building the package
1283 to take the subdirs, but doesn't actually bind that list until
1284 @code{configure} is run.
1287 @code{SUBDIRS} can contain configure substitutions (eg @samp{@@DIRS@@});
1288 Automake itself does not actually examine the contents of this variable.
1290 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1291 @code{AC_PROG_MAKE_SET}.
1293 The use of @code{SUBDIRS} is not restricted to just the top-level
1294 @file{Makefile.am}. Automake can be used to construct packages of
1297 By default, Automake generates @file{Makefiles} which work depth-first
1298 (``postfix''). However, it is possible to change this ordering. You
1299 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
1300 putting @samp{.} first will cause a ``prefix'' ordering of directories.
1303 @node Programs, Other objects, Top level, Top
1304 @chapter Building Programs and Libraries
1306 A large part of Automake's functionality is dedicated to making it easy
1307 to build C programs and libraries.
1310 * A Program:: Building a program
1311 * A Library:: Building a library
1312 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1313 * A Shared Library:: Building a Libtool library
1314 * Program variables:: Variables used when building a program
1315 * Yacc and Lex:: Yacc and Lex support
1317 * ANSI:: Automatic de-ANSI-fication
1318 * Dependencies:: Automatic dependency tracking
1322 @node A Program, A Library, Programs, Programs
1323 @section Building a program
1325 In a directory containing source that gets built into a program (as
1326 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
1327 can be installed in @samp{bindir}, @samp{sbindir}, @samp{libexecdir},
1328 @samp{pkglibdir}, or not at all (@samp{noinst}).
1333 bin_PROGRAMS = hello
1336 In this simple case, the resulting @file{Makefile.in} will contain code
1337 to generate a program named @code{hello}. The variable
1338 @code{hello_SOURCES} is used to specify which source files get built
1342 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1345 This causes each mentioned @samp{.c} file to be compiled into the
1346 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1348 If @samp{prog_SOURCES} is needed, but not specified, then it defaults to
1349 the single file @file{prog.c}. In the example above, the definition of
1350 @code{hello_SOURCES} is actually redundant.
1354 Multiple programs can be built in a single directory. Multiple programs
1355 can share a single source file. The source file must be listed in each
1356 @samp{_SOURCES} definition.
1358 Header files listed in a @samp{_SOURCES} definition will be included in
1359 the distribution but otherwise ignored. In case it isn't obvious, you
1360 should not include the header file generated by @file{configure} in an
1361 @samp{_SOURCES} variable; this file should not be distributed. Lex
1362 (@samp{.l}) and yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1365 Automake must know all the source files that could possibly go into a
1366 program, even if not all the files are built in every circumstance.
1367 Any files which are only conditionally built should be listed in the
1368 appropriate @samp{EXTRA_} variable. For instance, if
1369 @file{hello-linux.c} were conditionally included in @code{hello}, the
1370 @file{Makefile.am} would contain:
1373 EXTRA_hello_SOURCES = hello-linux.c
1376 Similarly, sometimes it is useful to determine the programs that are to
1377 be built at configure time. For instance, GNU @code{cpio} only builds
1378 @code{mt} and @code{rmt} under special circumstances.
1380 In this case, you must notify @code{automake} of all the programs that
1381 can possibly be built, but at the same time cause the generated
1382 @file{Makefile.in} to use the programs specified by @code{configure}.
1383 This is done by having @code{configure} substitute values into each
1384 @samp{_PROGRAMS} definition, while listing all optionally built programs in
1385 @code{EXTRA_PROGRAMS}.
1386 @vindex EXTRA_PROGRAMS
1388 If you need to link against libraries that are not found by
1389 @code{configure}, you can use @code{LDADD} to do so. This variable
1390 actually can be used to add any options to the linker command line.
1393 Sometimes, multiple programs are built in one directory but do not share
1394 the same link-time requirements. In this case, you can use the
1395 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1396 program as it appears in some @samp{_PROGRAMS} variable, and usually
1397 written in lowercase) to override the global @code{LDADD}. (If this
1398 variable exists for a given program, then that program is not linked
1399 using @code{LDADD}.)
1402 For instance, in GNU cpio, @code{pax}, @code{cpio}, and @code{mt} are
1403 linked against the library @file{libcpio.a}. However, @code{rmt} is
1404 built in the same directory, and has no such link requirement. Also,
1405 @code{mt} and @code{rmt} are only built on certain architectures. Here
1406 is what cpio's @file{src/Makefile.am} looks like (abridged):
1409 bin_PROGRAMS = cpio pax @@MT@@
1410 libexec_PROGRAMS = @@RMT@@
1411 EXTRA_PROGRAMS = mt rmt
1413 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1416 cpio_SOURCES = @dots{}
1417 pax_SOURCES = @dots{}
1418 mt_SOURCES = @dots{}
1419 rmt_SOURCES = @dots{}
1422 @samp{prog_LDADD} is inappropriate for passing program-specific linker
1423 flags (except for @samp{-l} and @samp{-L}). So, use the
1424 @samp{prog_LDFLAGS} variable for this purpose.
1427 It is also occasionally useful to have a program depend on some other
1428 target which is not actually part of that program. This can be done
1429 using the @samp{prog_DEPENDENCIES} variable. Each program depends on
1430 the contents of such a variable, but no further interpretation is done.
1432 If @samp{prog_DEPENDENCIES} is not supplied, it is computed by Automake.
1433 The automatically-assigned value is the contents of @samp{prog_LDADD},
1434 with most configure substitutions, @samp{-l}, and @samp{-L} options
1435 removed. The configure substitutions that are left in are only
1436 @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are left because it is
1437 known that they will not cause an invalid value for
1438 @samp{prog_DEPENDENCIES} to be generated.
1441 @node A Library, LIBOBJS, A Program, Programs
1442 @section Building a library
1444 Building a library is much like building a program. In this case, the
1445 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
1446 @code{libdir} or @code{pkglibdir}.
1448 @xref{A Shared Library}, for information on how to build shared
1449 libraries using Libtool and the @samp{LTLIBRARIES} primary.
1451 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
1452 For instance to create a library named @file{libcpio.a}, but not install
1453 it, you would write:
1456 noinst_LIBRARIES = libcpio.a
1459 The sources that go into a library are determined exactly as they are
1460 for programs, via the @samp{_SOURCES} variables. Note that the library
1461 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
1462 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
1463 not @samp{liblob.a_SOURCES}.
1465 Extra objects can be added to a library using the @samp{library_LIBADD}
1466 variable. This should be used for objects determined by
1467 @code{configure}. Again from cpio:
1472 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
1475 @node LIBOBJS, A Shared Library, A Library, Programs
1476 @section Special handling for LIBOBJS and ALLOCA
1478 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
1479 @code{@@ALLOCA@@}, and uses this information, plus the list of
1480 @code{LIBOBJS} files derived from @file{configure.in} to automatically
1481 include the appropriate source files in the distribution (@pxref{Dist}).
1482 These source files are also automatically handled in the
1483 dependency-tracking scheme, see @xref{Dependencies}.
1485 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
1486 @samp{_LDADD} or @samp{_LIBADD} variable.
1488 @node A Shared Library, Program variables, LIBOBJS, Programs
1489 @section Building a Shared Library
1491 Building shared libraries is a relatively complex matter. For this
1492 reason, GNU Libtool (@pxref{Top, , The Libtool Manual, libtool, The
1493 Libtool Manual}) was created to help build shared libraries in a
1494 platform-independent way.
1496 Automake uses Libtool to build libraries declared with the
1497 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
1498 of shared libraries to build. For instance, to create a library named
1499 @file{libgettext.a} and its corresponding shared libraries, and install
1500 them in @samp{libdir}, write:
1503 lib_LTLIBRARIES = libgettext.la
1506 Note that shared libraries @emph{must} be installed, so
1507 @samp{noinst_LTLIBRARIES} and @samp{check_LTLIBRARIES} are not allowed.
1509 For each library, the @samp{library_LIBADD} variable contains the names
1510 of extra libtool objects (@samp{.lo} files) to add to the shared
1511 library. The @samp{library_LDFLAGS} variable contains any additional
1512 libtool flags, such as @samp{-version-info} or @samp{-static}.
1514 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
1515 library must use @code{@@LTLIBOBJS@@}. This is required because the
1516 object files that libtool operates on do not necessarily end in
1517 @samp{.o}. The libtool manual contains more details on this topic.
1519 For libraries installed in some directory, @code{automake} will
1520 automatically supply the appropriate @samp{-rpath} option. However, for
1521 libraries determined at configure time (and thus mentioned in
1522 @code{EXTRA_LTLIBRARIES}), @code{automake} does not know the eventual
1523 installation directory; for such libraries you must add the
1524 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
1527 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
1528 libtool, The Libtool Manual}, for more information.
1530 @node Program variables, Yacc and Lex, A Shared Library, Programs
1531 @section Variables used when building a program
1533 Occasionally it is useful to know which @file{Makefile} variables
1534 Automake uses for compilations; for instance you might need to do your
1535 own compilation in some special cases.
1537 Some variables are inherited from Autoconf; these are @code{CC},
1538 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
1542 There are some additional variables which Automake itself defines:
1546 A list of @samp{-I} options. This can be set in your @file{Makefile.am}
1547 if you have special directories you want to look in. @code{automake}
1548 already provides some @samp{-I} options automatically. In particular it
1549 generates @samp{-I$(srcdir)} and a @samp{-I} pointing to the directory
1550 holding @file{config.h} (if you've used @code{AC_CONFIG_HEADER} or
1551 @code{AM_CONFIG_HEADER}).
1553 @code{INCLUDES} can actually be used for other @code{cpp} options
1554 besides @samp{-I}. For instance, it is sometimes used to pass arbitrary
1555 @samp{-D} options to the compiler.
1558 This is the command used to actually compile a C source file. The
1559 filename is appended to form the complete command line.
1562 This is the command used to actually link a C program.
1566 @node Yacc and Lex, C++, Program variables, Programs
1567 @section Yacc and Lex support
1569 Automake has somewhat idiosyncratic support for Yacc and Lex.
1571 Automake assumes that the @samp{.c} file generated by yacc (or lex)
1572 should be named using the basename of the input file. That is, for a
1573 yacc source file @file{foo.y}, automake will cause the intermediate file
1574 to be named @file{foo.c} (as opposed to @file{y.tab.c}, which is more
1577 The extension of a yacc source file is used to determine the extension
1578 of the resulting @samp{C} or @samp{C++} file. Files with the extension
1579 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
1580 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
1581 @samp{.cxx}. Likewise, lex source files can be used to generate
1582 @samp{C} or @samp{C++}; the extensions @samp{.l}, @samp{.ll},
1583 @samp{.l++}, and @samp{.lxx} are recognized.
1585 You should never explicitly mention the intermediate (@samp{C} or
1586 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
1589 The intermediate files generated by yacc (or lex) will be included in
1590 any distribution that is made. That way the user doesn't need to have
1593 If a yacc source file is seen, then your @file{configure.in} must define
1594 the variable @samp{YACC}. This is most easily done by invoking the
1595 macro @samp{AC_PROG_YACC}.
1597 Similarly, if a lex source file is seen, then your @file{configure.in}
1598 must define the variable @samp{LEX}. You can use @samp{AC_PROG_LEX} to
1599 do this. Automake's lex support also requires that you use the
1600 @samp{AC_DECL_YYTEXT} macro---automake needs to know the value of
1601 @samp{LEX_OUTPUT_ROOT}.
1603 Automake makes it possible to include multiple yacc (or lex) source
1604 files in a single program. Automake uses a small program called
1605 @code{ylwrap} to run @code{yacc} (or @code{lex}) in a subdirectory.
1606 This is necessary because yacc's output filename is fixed, and a
1607 parallel make could conceivably invoke more than one instance of
1608 @code{yacc} simultaneously. @code{ylwrap} is distributed with automake.
1609 It should appear in the directory specified by @samp{AC_CONFIG_AUX_DIR},
1610 or the current directory if that macro is not used in
1611 @file{configure.in}.
1613 For @code{yacc}, simply managing locking is insufficient. @code{yacc}
1614 output also always uses the same symbol names internally, so it isn't
1615 possible to link two @code{yacc} parsers into the same executable.
1617 We recommend using the following renaming hack used in @code{gdb}:
1619 #define yymaxdepth c_maxdepth
1620 #define yyparse c_parse
1622 #define yyerror c_error
1623 #define yylval c_lval
1624 #define yychar c_char
1625 #define yydebug c_debug
1626 #define yypact c_pact
1633 #define yyexca c_exca
1634 #define yyerrflag c_errflag
1635 #define yynerrs c_nerrs
1639 #define yy_yys c_yys
1640 #define yystate c_state
1643 #define yy_yyv c_yyv
1645 #define yylloc c_lloc
1646 #define yyreds c_reds
1647 #define yytoks c_toks
1648 #define yylhs c_yylhs
1649 #define yylen c_yylen
1650 #define yydefred c_yydefred
1651 #define yydgoto c_yydgoto
1652 #define yysindex c_yysindex
1653 #define yyrindex c_yyrindex
1654 #define yygindex c_yygindex
1655 #define yytable c_yytable
1656 #define yycheck c_yycheck
1657 #define yyname c_yyname
1658 #define yyrule c_yyrule
1661 For each define, replace the @samp{c_} prefix with whatever you like.
1662 These defines work for @code{bison}, @code{byacc}, and traditional
1663 @code{yacc}s. If you find a parser generator that uses a symbol not
1664 covered here, please report the new name so it can be added to the list.
1667 @node C++, ANSI, Yacc and Lex, Programs
1668 @section C++ and other languages
1670 Automake includes full support for C++, and rudimentary support for
1671 other languages. Support for other languages will be improved based on
1674 Any package including C++ code must define the output variable
1675 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
1676 the @code{AC_PROG_CXX} macro.
1678 A few additional variables are defined when a C++ source file is seen:
1682 The name of the C++ compiler.
1686 Any flags to pass to the C++ compiler.
1690 The command used to actually compile a C++ source file. The file name
1691 is appended to form the complete command line.
1695 The command used to actually link a C++ program.
1700 @node ANSI, Dependencies, C++, Programs
1701 @section Automatic de-ANSI-fication
1703 Although the GNU standards allow the use of ANSI C, this can have the
1704 effect of limiting portability of a package to some older compilers
1707 Automake allows you to work around this problem on such machines by
1708 ``de-ANSI-fying'' each source file before the actual compilation takes
1711 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
1712 @vindex AUTOMAKE_OPTIONS
1713 (@ref{Options}) contains the option @code{ansi2knr}
1715 then code to handle de-ANSI-fication is inserted into the generated
1718 This causes each C source file in the directory to be treated as ANSI C.
1719 If an ANSI C compiler is available, it is used. If no ANSI C compiler
1720 is available, the @code{ansi2knr} program is used to convert the source
1721 files into K&R C, which is then compiled.
1723 The @code{ansi2knr} program is simple-minded. It assumes the source
1724 code will be formatted in a particular way; see the @code{ansi2knr} man
1727 De-ANSI-fication support requires the source files @file{ansi2knr.c} and
1728 @file{ansi2knr.1} to be in the same package as the ANSI C source; these
1729 files are distributed with Automake. Also, the package
1730 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}.
1731 @cvindex AM_C_PROTOTYPES
1733 Automake also handles finding the @code{ansi2knr} support files in some
1734 other directory in the current package. This is done by prepending the
1735 relative path to the appropriate directory to the @code{ansi2knr}
1736 option. For instance, suppose the package has ANSI C code in the
1737 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
1738 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
1739 @file{src/Makefile.am}:
1742 AUTOMAKE_OPTIONS = ../lib/ansi2knr
1745 If no directory prefix is given, the files are assumed to be in the
1748 Files mentioned in @code{LIBOBJS} which need de-ANSI-fication will not
1749 be automatically handled. That's because @code{configure} will generate
1750 an object name like @file{regex.o}, while @code{make} will be looking
1751 for @file{regex_.o} (when de-ANSI-fying). Eventually this problem will
1752 be fixed via @code{autoconf} magic, but for now you must put this code
1753 into your @file{configure.in}, just before the @code{AC_OUTPUT} call:
1756 # This is necessary so that .o files in LIBOBJS are also built via
1757 # the ANSI2KNR-filtering rules.
1758 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
1762 @node Dependencies, , ANSI, Programs
1763 @section Automatic dependency tracking
1765 As a developer it is often painful to continually update the
1766 @file{Makefile.in} whenever the include-file dependencies change in a
1767 project. @code{automake} supplies a way to automatically track
1768 dependency changes, and distribute the dependencies in the generated
1771 Currently this support requires the use of GNU @code{make} and
1772 @code{gcc}. It might become possible in the future to supply a
1773 different dependency generating program, if there is enough demand. In
1774 the meantime, this mode is enabled by default if any C program or
1775 library is defined in the current directory, so you may get a @samp{Must
1776 be a separator} error from non-GNU make.
1778 When you decide to make a distribution, the @code{dist} target will
1780 re-run @code{automake} with @samp{--include-deps} and other options.
1781 This will cause the previously generated dependencies to be inserted
1782 into the generated @file{Makefile.in}, and thus into the distribution.
1783 This step also turns off inclusion of the dependency generation code, so
1784 that those who download your distribution but don't use GNU @code{make}
1785 and @code{gcc} will not get errors.
1787 When added to the @file{Makefile.in}, the dependencies have all
1788 system-specific dependencies automatically removed. This can be done by
1789 listing the files in @samp{OMIT_DEPENDENCIES}.
1790 @vindex OMIT_DEPENDENCIES
1791 For instance all references to system header files are removed by
1792 @code{automake}. Sometimes it is useful to specify that a certain
1793 header file should be removed. For instance if your @file{configure.in}
1794 uses @samp{AM_WITH_REGEX}, then any dependency on @file{rx.h} or
1795 @file{regex.h} should be removed, because the correct one cannot be
1796 known until the user configures the package.
1798 As it turns out, @code{automake} is actually smart enough to handle the
1799 particular case of the regular expression header. It will also
1800 automatically omit @file{libintl.h} if @samp{AM_GNU_GETTEXT} is used.
1802 Automatic dependency tracking can be suppressed by putting
1803 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}.
1804 @vindex AUTOMAKE_OPTIONS
1805 @opindex no-dependencies
1807 If you unpack a distribution made by @code{make dist}, and you want to
1808 turn on the dependency-tracking code again, simply re-run
1811 The actual dependency files are put under the build directory, in a
1812 subdirectory named @file{.deps}. These dependencies are machine
1813 specific. It is safe to delete them if you like; they will be
1814 automatically recreated during the next build.
1817 @node Other objects, Other GNU Tools, Programs, Top
1818 @chapter Other Derived Objects
1820 Automake can handle derived objects which are not C programs. Sometimes
1821 the support for actually building such objects must be explicitly
1822 supplied, but Automake will still automatically handle installation and
1826 * Scripts:: Executable scripts
1827 * Headers:: Header files
1828 * Data:: Architecture-independent data files
1829 * Sources:: Derived sources
1833 @node Scripts, Headers, Other objects, Other objects
1834 @section Executable Scripts
1836 It is possible to define and install programs which are scripts. Such
1837 programs are listed using the @samp{SCRIPTS} primary name.
1838 @code{automake} doesn't define any dependencies for scripts; the
1839 @file{Makefile.am} should include the appropriate rules.
1842 @code{automake} does not assume that scripts are derived objects; such
1843 objects must be deleted by hand; see @ref{Clean} for more information.
1845 @code{automake} itself is a script that is generated at configure time
1846 from @file{automake.in}. Here is how this is handled:
1849 bin_SCRIPTS = automake
1852 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
1853 for it is automatically generated.
1855 Script objects can be installed in @code{bindir}, @code{sbindir},
1856 @code{libexecdir}, or @code{pkgdatadir}.
1859 @node Headers, Data, Scripts, Other objects
1860 @section Header files
1862 Header files are specified by the @samp{HEADERS} family of variables.
1863 Generally header files are not installed, so the @code{noinst_HEADERS}
1864 variable will be the most used.
1867 All header files must be listed somewhere; missing ones will not appear
1868 in the distribution. Often it is clearest to list uninstalled headers
1869 with the rest of the sources for a program. @xref{A Program}. Headers
1870 listed in a @samp{_SOURCES} variable need not be listed in any
1871 @samp{_HEADERS} variable.
1873 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
1874 @code{pkgincludedir}.
1877 @node Data, Sources, Headers, Other objects
1878 @section Architecture-independent data files
1880 Automake supports the installation of miscellaneous data files using the
1881 @samp{DATA} family of variables.
1884 Such data can be installed in the directories @code{datadir},
1885 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
1888 By default, data files are not included in a distribution.
1890 Here is how @code{automake} installs its auxiliary data files:
1893 pkgdata_DATA = clean-kr.am clean.am @dots{}
1897 @node Sources, , Data, Other objects
1898 @section Built sources
1900 Occasionally a file which would otherwise be called ``source'' (eg a C
1901 @samp{.h} file) is actually derived from some other file. Such files
1902 should be listed in the @code{BUILT_SOURCES} variable.
1903 @vindex BUILT_SOURCES
1905 Built sources are also not compiled by default. You must explicitly
1906 mention them in some other @samp{_SOURCES} variable for this to happen.
1908 Note that, in some cases, @code{BUILT_SOURCES} will work in somewhat
1909 suprising ways. In order to get the built sources to work with
1910 automatic dependency tracking, the @file{Makefile} must depend on
1911 @code{$(BUILT_SOURCES)}. This can cause these sources to be rebuilt at
1912 what might seem like funny times.
1915 @node Other GNU Tools, Documentation, Other objects, Top
1916 @chapter Other GNU Tools
1918 Since Automake is primarily intended to generate @file{Makefile.in}s for
1919 use in GNU programs, it tries hard to interoperate with other GNU tools.
1922 * Emacs Lisp:: Emacs Lisp
1929 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
1932 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
1933 is used to hold a list of @samp{.el} files. Possible prefixes for this
1934 primary are @samp{lisp_} and @samp{noinst_}. Note that if
1935 @code{lisp_LISP} is defined, then @file{configure.in} must run
1936 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
1941 By default Automake will byte-compile all Emacs Lisp source files using
1942 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
1943 byte-compiling, simply define the variable @samp{ELCFILES} to be empty.
1945 Byte-compiled Emacs Lisp files are not portable among all versions of
1946 Emacs, so it makes sense to turn this off if you expect sites to have
1947 more than one version of Emacs installed. Furthermore, many packages
1948 don't actually benefit from byte-compilation. Still, we recommand that
1949 you leave it enabled by default. It is probably better for sites with
1950 strange setups to cope for themselves than to make the installation less
1951 nice for everybody else.
1953 @node gettext, Guile, Emacs Lisp, Other GNU Tools
1956 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
1957 turns on support for GNU gettext, a message catalog system for
1958 internationalization
1959 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
1961 The @code{gettext} support in Automake requires the addition of two
1962 subdirectories to the package, @file{intl} and @file{po}. Automake
1963 ensure that these directories exist and are mentioned in @code{SUBDIRS}.
1965 Furthermore, Automake checks that the definition of @samp{ALL_LINGUAS}
1966 in @file{configure.in} corresponds to all the valid @samp{.po} files,
1970 @node Guile, Libtool, gettext, Other GNU Tools
1973 Automake provides some automatic support for writing Guile modules.
1974 Automake will turn on Guile support if the @code{AM_INIT_GUILE_MODULE}
1975 macro is used in @file{configure.in}.
1977 Right now Guile support just means that the @code{AM_INIT_GUILE_MODULE}
1978 macro is understood to mean:
1981 @code{AM_INIT_AUTOMAKE} is run.
1984 @code{AC_CONFIG_AUX_DIR} is run, with a path of @file{..}.
1987 As the Guile module code matures, no doubt the Automake support will
1990 @node Libtool, Java, Guile, Other GNU Tools
1993 Automake provides support for GNU Libtool (@pxref{Top, , The Libtool
1994 Manual, libtool, The Libtool Manual}) with the @samp{LTLIBRARIES}
1995 primary. @xref{A Shared Library}.
1997 @node Java, , Libtool, Other GNU Tools
2000 Automake provides some minimal support for Java compilation with the
2001 @samp{JAVA} primary.
2003 Any @samp{.java} files listed in a @samp{_JAVA} variable will be
2004 compiled with @code{JAVAC} at build time. By default, @samp{.class}
2005 files are not included in the distribution.
2007 Currently Automake enforces the restriction that only one @samp{_JAVA}
2008 primary can be used in a given @file{Makefile.am}. The reason for this
2009 restriction is that, in general, it isn't possible to know which
2010 @samp{.class} files were generated from which @samp{.java} files -- so
2011 it would be impossible to know which files to install where.
2014 @node Documentation, Install, Other GNU Tools, Top
2015 @chapter Building documentation
2017 Currently Automake provides support for Texinfo and man pages.
2021 * Man pages:: Man pages
2025 @node Texinfo, Man pages, Documentation, Documentation
2028 If the current directory contains Texinfo source, you must declare it
2029 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
2030 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
2031 here. Note that any Texinfo source file must end in the @samp{.texi} or
2032 @samp{.texinfo} extension.
2034 @vindex info_TEXINFOS
2036 If the @samp{.texi} file @code{@@include}s @file{version.texi}, then that
2037 file will be automatically generated. @file{version.texi} defines three
2038 Texinfo macros you can reference: @code{EDITION}, @code{VERSION}, and
2039 @code{UPDATED}. The first two hold the version number of your package
2040 (but are kept separate for clarity); the last is the date the primary
2041 file was last modified. The @file{version.texi} support requires the
2042 @code{mdate-sh} program; this program is supplied with Automake.
2044 Sometimes an info file actually depends on more than one @samp{.texi}
2045 file. For instance, in GNU Hello, @file{hello.texi} includes the file
2046 @file{gpl.texi}. You can tell Automake about these dependencies using
2047 the @samp{@var{texi}_TEXINFOS} variable. Here is how Hello does it:
2052 info_TEXINFOS = hello.texi
2053 hello_TEXINFOS = gpl.texi
2056 By default, Automake requires the file @file{texinfo.tex} to appear in
2057 the same directory as the Texinfo source. However, if you used
2058 @code{AC_CONFIG_AUX_DIR} in @file{configure.in}, then @file{texinfo.tex}
2059 is looked for there. Automake supplies @file{texinfo.tex} if
2060 @samp{--add-missing} is given.
2062 If your package has Texinfo files in many directories, you can use the
2063 variable @code{TEXINFO_TEX} to tell automake where to find the canonical
2064 @file{texinfo.tex} for your package. The value of this variable should
2065 be the relative path from the current @file{Makefile.am} to
2069 TEXINFO_TEX = ../doc/texinfo.tex
2072 The option @samp{no-texinfo.tex} can be used to eliminate the
2073 requirement for @file{texinfo.tex}. Use of the variable
2074 @code{TEXINFO_TEX} is preferable, however, because that allows the
2075 @code{dvi} target to still work.
2077 Automake generates an @code{install-info} target; some people apparently
2078 use this. By default, info pages are installed by @samp{make install}.
2079 This can be prevented via the @code{no-installinfo} option.
2082 @node Man pages, , Texinfo, Documentation
2085 A package can also include man pages. (Though see the GNU standards on
2086 this matter, @ref{Man Pages, , , standards, The GNU Coding
2087 Standards}.) Man pages are declared using the @samp{MANS} primary.
2088 Generally the @code{man_MANS} macro is used. Man pages are
2089 automatically installed in the correct subdirectory of @code{mandir},
2090 based on the file extension.
2094 @c Use @samp{make install} per documentation: (texi)code.
2095 By default, man pages are installed by @samp{make install}. However,
2096 since the GNU project does not require man pages, many maintainers do
2097 not expend effort to keep the man pages up to date. In these cases, the
2098 @code{no-installman} option will prevent the man pages from being
2099 installed by default. The user can still explicitly install them via
2100 @samp{make install-man}.
2101 @opindex no-installman
2102 @trindex install-man
2104 Here is how the documentation is handled in GNU @code{cpio} (which
2105 includes both Texinfo documentation and man pages):
2108 info_TEXINFOS = cpio.texi
2109 man_MANS = cpio.1 mt.1
2112 Texinfo source and info pages are all considered to be source for the
2113 purposes of making a distribution.
2115 Man pages are not currently considered to be source, because it is not
2116 uncommon for man pages to be automatically generated.
2119 @node Install, Clean, Documentation, Top
2120 @chapter What Gets Installed
2122 Naturally, Automake handles the details of actually installing your
2123 program once it has been built. All @code{PROGRAMS}, @code{SCRIPTS},
2124 @code{LIBRARIES}, @code{LISP}, @code{DATA} and @code{HEADERS} are
2125 automatically installed in the appropriate places.
2127 Automake also handles installing any specified info and man pages.
2129 Automake generates separate @code{install-data} and @code{install-exec}
2130 targets, in case the installer is installing on multiple machines which
2131 share directory structure---these targets allow the machine-independent
2132 parts to be installed only once. The @code{install} target depends on
2133 both of these targets.
2134 @trindex install-data
2135 @trindex install-exec
2138 Automake also generates an @code{uninstall} target, an
2139 @code{installdirs} target, and an @code{install-strip} target.
2141 @trindex installdirs
2142 @trindex install-strip
2144 It is possible to extend this mechanism by defining an
2145 @code{install-exec-local} or @code{install-data-local} target. If these
2146 targets exist, they will be run at @samp{make install} time.
2147 @trindex install-exec-local
2148 @trindex install-data-local
2150 Variables using the standard directory prefixes @samp{data},
2151 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
2152 @samp{pkgdata}, or @samp{pkginclude} (eg @samp{data_DATA}) are installed
2153 by @samp{install-data}.
2155 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
2156 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
2157 @samp{pkglib} (eg @samp{bin_PROGRAMS}) are installed by
2158 @samp{install-exec}.
2160 Any variable using a user-defined directory prefix with @samp{exec} in
2161 the name (eg @samp{myexecbin_PROGRAMS} is installed by
2162 @samp{install-exec}. All other user-defined prefixes are installed by
2163 @samp{install-data}.
2165 Automake generates support for the @samp{DESTDIR} variable in all
2166 install rules; see @xref{Makefile Conventions, , , standards, The GNU
2171 @node Clean, Dist, Install, Top
2172 @chapter What Gets Cleaned
2174 The GNU Makefile Standards specify a number of different clean rules.
2176 Generally the files that can cleaned are determined automatically by
2177 Automake. Of course, Automake also recognizes some variables that can
2178 be defined to specify additional files to clean. These variables are
2179 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
2180 @code{MAINTAINERCLEANFILES}.
2181 @vindex MOSTLYCLEANFILES
2183 @vindex DISTCLEANFILES
2184 @vindex MAINTAINERCLEANFILES
2187 @node Dist, Tests, Clean, Top
2188 @chapter What Goes in a Distribution
2190 The @code{dist} target in the generated @file{Makefile.in} can be used
2191 to generate a gzip'd @code{tar} file for distribution. The tar file is
2192 named based on the @samp{PACKAGE} and @samp{VERSION} variables; more
2193 precisely it is named @samp{@var{package}-@var{version}.tar.gz}.
2198 For the most part, the files to distribute are automatically found by
2199 Automake: all source files are automatically included in a distribution,
2200 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
2201 has a built-in list of commonly used files which, if present in the
2202 current directory, are automatically included. This list is printed by
2203 @samp{automake --help}. Also, files which are read by @code{configure}
2204 (ie, the source files corresponding to the files specified in the
2205 @code{AC_OUTPUT} invocation) are automatically distributed.
2207 Still, sometimes there are files which must be distributed, but which
2208 are not covered in the automatic rules. These files should be listed in
2209 the @code{EXTRA_DIST} variable. You can mention files from
2210 subdirectories in @code{EXTRA_DIST}. You can also mention a directory
2211 there; in this case the entire directory will be recursively copied into
2215 If you define @code{SUBDIRS}, automake will recursively include the
2216 subdirectories in the distribution. If @code{SUBDIRS} is defined
2217 conditionally (@pxref{Conditionals}), automake will normally include all
2218 directories that could possibly appear in @code{SUBDIRS} in the
2219 distribution. If you need to specify the set of directories
2220 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
2221 list of subdirectories to include in the distribution.
2222 @vindex DIST_SUBDIRS
2224 Occasionally it is useful to be able to change the distribution before
2225 it is packaged up. If the @code{dist-hook} target exists, it is run
2226 after the distribution directory is filled, but before the actual tar
2227 (or shar) file is created. One way to use this is for distributing
2228 files in subdirectories for which a new @file{Makefile.am} is overkill:
2232 mkdir $(distdir)/random
2233 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
2236 Automake also generates a @code{distcheck} target which can be help to
2237 ensure that a given distribution will actually work. @code{distcheck}
2238 makes a distribution, and then tries to do a @code{VPATH} build.
2240 @c FIXME: document distcheck-hook here
2242 @node Tests, Options, Dist, Top
2243 @chapter Support for test suites
2245 Automake supports a two forms of test suite.
2247 If the variable @code{TESTS} is defined, its value is taken to be a list
2248 of programs to run in order to do the testing. The programs can either
2249 be derived objects or source objects; the generated rule will look both
2250 in @var{srcdir} and @file{.}. Programs needing data files should look
2251 for them in @var{srcdir} (which is both an environment variable and a
2252 make variable) so they work when building in a separate directory
2253 (@pxref{Build Directories,, Build Directories ,autoconf, Autoconf}),
2254 and in particular for the
2255 @code{distcheck} target (@pxref{Dist}).
2257 The number of failures will be printed at the end of the run. If a
2258 given test program exits with a status of 77, then its result is ignored
2259 in the final count. This feature allows non-portable tests to be
2260 ignored in environments where they don't make sense.
2262 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
2263 variables for the test run; the environment variable @code{srcdir} is
2264 set in the rule. If all your test programs are scripts, you can also
2265 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (eg
2266 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
2268 @vindex TESTS_ENVIRONMENT
2270 If @samp{dejagnu} appears in @code{AUTOMAKE_OPTIONS}, then the a
2271 @code{dejagnu}-based test suite is assumed. The value of the variable
2272 @code{DEJATOOL} is passed as the @code{--tool} argument to
2273 @code{runtest}; it defaults to the name of the package.
2275 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
2276 @code{--srcdir} flags that are passed to dejagnu by default; this can be
2277 overridden if necessary.
2278 @vindex RUNTESTDEFAULTFLAGS
2280 The variables @code{EXPECT}, @code{RUNTEST} and @code{RUNTESTFLAGS} can
2281 also be overridden to provide project-specific values. For instance,
2282 you will need to do this if you are testing a compiler toolchain,
2283 because the default values do not take into account host and target
2289 @vindex RUNTESTFLAGS
2290 @c FIXME xref dejagnu
2292 In either case, the testing is done via @samp{make check}.
2295 @node Options, Miscellaneous, Tests, Top
2296 @chapter Changing Automake's Behavior
2298 Various features of Automake can be controlled by options in the
2299 @file{Makefile.am}. Such options are listed in a special variable named
2300 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
2301 @vindex AUTOMAKE_OPTIONS
2306 @itemx @code{foreign}
2308 Set the strictness as appropriate. The @code{gnits} option also implies
2309 @code{readme-alpha} and @code{check-news}.
2311 @item @code{ansi2knr}
2312 @itemx @code{path/ansi2knr}
2313 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceeded by a
2314 path, the generated @file{Makefile.in} will look in the specified
2315 directory to find the @file{ansi2knr} program. Generally the path
2316 should be a relative path to another directory in the same distribution
2317 (though Automake currently does not check this).
2319 @item @code{check-news}
2320 Cause @code{make dist} to fail unless the current version number appears
2321 in the first few lines of the @file{NEWS} file.
2323 @item @code{dejagnu}
2324 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
2326 @item @code{dist-shar}
2327 Generate a @code{dist-shar} target as well as the ordinary @code{dist}
2328 target. This new target will create a shar archive of the
2332 @item @code{dist-zip}
2333 Generate a @code{dist-zip} target as well as the ordinary @code{dist}
2334 target. This new target will create a zip archive of the distribution.
2337 @item @code{dist-tarZ}
2338 Generate a @code{dist-tarZ} target as well as the ordinary @code{dist}
2339 target. This new target will create a compressed tar archive of the
2340 distribution; a traditional @code{tar} and @code{compress} will be
2341 assumed. Warning: if you are actually using @code{GNU tar}, then the
2342 generated archive might contain nonportable constructs.
2345 @item @code{no-dependencies}
2346 This is similar to using @samp{--include-deps} on the command line, but
2347 is useful for those situations where you don't have the necessary bits
2348 to make automatic dependency tracking work @xref{Dependencies}. In this
2349 case the effect is to effectively disable automatic dependency tracking.
2351 @item @code{no-installinfo}
2352 The generated @file{Makefile.in} will not cause info pages to be built
2353 or installed by default. However, @code{info} and @code{install-info}
2354 targets will still be available. This option is disallowed at
2355 @samp{GNU} strictness and above.
2357 @trindex install-info
2359 @item @code{no-installman}
2360 The generated @file{Makefile.in} will not cause man pages to be
2361 installed by default. However, an @code{install-man} target will still
2362 be available for optional installation. This option is disallowed at
2363 @samp{GNU} strictness and above.
2364 @trindex install-man
2366 @item @code{no-texinfo.tex}
2367 Don't require @file{texinfo.tex}, even if there are texinfo files in
2370 @item @code{readme-alpha}
2371 If this release is an alpha release, and the file @file{README-alpha}
2372 exists, then it will be added to the distribution. If this option is
2373 given, version numbers are expected to follow one of two forms. The
2374 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
2375 element is a number; the final period and number should be left off for
2376 non-alpha releases. The second form is
2377 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
2378 letter; it should be omitted for non-alpha releases.
2381 A version number (eg @samp{0.30}) can be specified. If Automake is not
2382 newer than the version specified, creation of the @file{Makefile.in}
2386 Unrecognized options are diagnosed by @code{automake}.
2389 @node Miscellaneous, Include, Options, Top
2390 @chapter Miscellaneous Rules
2392 There are a few rules and variables that didn't fit anywhere else.
2395 * Tags:: Interfacing to etags and mkid
2396 * Suffixes:: Handling new file extensions
2400 @node Tags, Suffixes, Miscellaneous, Miscellaneous
2401 @section Interfacing to @code{etags}
2403 @code{automake} will generate rules to generate @file{TAGS} files for
2404 use with GNU Emacs under some circumstances.
2406 If any C source code or headers are present, then @code{tags} and
2407 @code{TAGS} targets will be generated for the directory.
2410 At the topmost directory of a multi-directory package, a @code{tags}
2411 target file will be generated which, when run, will generate a
2412 @file{TAGS} file that includes by reference all @file{TAGS} files from
2415 Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
2416 will be generated. This variable is intended for use in directories
2417 which contain taggable source that @code{etags} does not understand.
2420 Here is how Automake generates tags for its source, and for nodes in its
2424 ETAGS_ARGS = automake.in --lang=none \
2425 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
2428 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
2429 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
2430 are added directly to the dependencies for the @code{tags} target.
2431 @vindex TAGS_DEPENDENCIES
2433 Automake will also generate an @code{ID} target which will run
2434 @code{mkid} on the source. This is only supported on a
2435 directory-by-directory basis.
2439 @node Suffixes, , Tags, Miscellaneous
2440 @section Handling new file extensions
2442 It is sometimes useful to introduce a new implicit rule to handle a file
2443 type that Automake does not know about. If this is done, you must
2444 notify GNU Make of the new suffixes. This can be done by putting a list
2445 of new suffixes in the @code{SUFFIXES} variable.
2448 For instance, currently automake does not provide any Java support. If
2449 you wrote a macro to generate @samp{.class} files from @samp{.java}
2450 source files, you would also need to add these suffixes to the list:
2453 SUFFIXES = .java .class
2456 @node Include, Conditionals, Miscellaneous, Top
2460 To include another file (perhaps for common rules),
2461 the following syntax is supported:
2463 include ($(srcdir)|$(top_srcdir))/filename
2465 Using files in the current directory:
2467 include $(srcdir)/Makefile.extra
2471 include Makefile.generated
2474 Using a file in the top level directory:
2476 include $(top_srcdir)/filename
2479 @node Conditionals, Gnits, Include, Top
2480 @chapter Conditionals
2482 Automake supports a simple type of conditionals.
2484 @cvindex AM_CONDITIONAL
2485 Before using a conditional, you must define it by using
2486 @code{AM_CONDITIONAL} in the @code{configure.in} file. The
2487 @code{AM_CONDITIONAL} macro takes two arguments.
2489 The first argument to @code{AM_CONDITIONAL} is the name of the
2490 conditional. This should be a simple string starting with a letter and
2491 containing only letters, digits, and underscores.
2493 The second argument to @code{AM_CONDITIONAL} is a shell condition,
2494 suitable for use in a shell if statement. The condition is evaluated
2495 when @code{configure} is run.
2497 Conditionals typically depend upon options which the user provides to
2498 the @code{configure} script. Here is an example of how to write a
2499 conditional which is true if the user uses the @samp{--enable-debug}
2503 AC_ARG_ENABLE(debug,
2504 [ --enable-debug Turn on debugging],
2505 [case "$@{enableval@}" in
2508 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
2509 esac],[debug=false])
2510 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
2513 Here is an example of how to use that conditional in @file{Makefile.am}:
2525 noinst_PROGRAMS = $(DBG)
2528 This trivial example could also be handled using EXTRA_PROGRAMS
2529 (@pxref{A Program}).
2531 You may only test a single variable in an @code{if} statement. The
2532 @code{else} statement may be omitted. Conditionals may be nested to any
2535 Note that conditionals in Automake are not the same as conditionals in
2536 GNU Make. Automake conditionals are checked at configure time by the
2537 @file{configure} script, and affect the translation from
2538 @file{Makefile.in} to @file{Makefile}. They are based on options passed
2539 to @file{configure} and on results that @file{configure} has discovered
2540 about the host system. GNU Make conditionals are checked at make time,
2541 and are based on variables passed to the make program or defined in the
2544 Automake conditionals will work with any make program.
2546 @node Gnits, Cygnus, Conditionals, Top
2547 @chapter The effect of @code{--gnu} and @code{--gnits}
2549 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
2550 variable) causes @code{automake} to check the following:
2554 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
2555 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
2556 directory of the package.
2559 The options @samp{no-installman} and @samp{no-installinfo} are
2563 Note that this option will be extended in the future to do even more
2564 checking; it is advisable to be familiar with the precise requirements
2565 of the GNU standards. Also, @samp{--gnu} can require certain
2566 non-standard GNU programs to exist for use by various maintainer-only
2567 targets; for instance in the future @code{pathchk} might be required for
2570 The @samp{--gnits} option does everything that @samp{--gnu} does, and
2571 checks the following as well:
2575 @samp{make dist} will check to make sure the @file{NEWS} file has been
2576 updated to the current version.
2579 The file @file{COPYING.LIB} is prohibited. The LGPL is apparently
2580 considered a failed experiment.
2583 @samp{VERSION} is checked to make sure its format complies with Gnits
2585 @c FIXME xref when standards are finished
2588 If @samp{VERSION} indicates that this is an alpha release, and the file
2589 @file{README-alpha} appears in the topmost directory of a package, then
2590 it is included in the distribution. This is done in @samp{--gnits}
2591 mode, and no other, because this mode is the only one where version
2592 number formats are constrained, and hence the only mode where
2593 @code{automake} can automatically determine whether @file{README-alpha}
2597 The file @file{THANKS} is required.
2601 @node Cygnus, Extending, Gnits, Top
2602 @chapter The effect of @code{--cygnus}
2604 Cygnus Solutions has slightly different rules for how a
2605 @file{Makefile.in} is to be constructed. Passing @samp{--cygnus} to
2606 @code{automake} will cause any generated @file{Makefile.in} to comply
2609 Here are the precise effects of @samp{--cygnus}:
2613 Info files are always created in the build directory, and not in the
2617 @file{texinfo.tex} is not required if a Texinfo source file is
2618 specified. The assumption is that the file will be supplied, but in a
2619 place that @code{automake} cannot find. This assumption is an artifact
2620 of how Cygnus packages are typically bundled.
2623 @samp{make dist} will look for files in the build directory as well as
2624 the source directory. This is required to support putting info files
2625 into the build directory.
2628 Certain tools will be searched for in the build tree as well as in the
2629 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
2630 @code{makeinfo} and @code{texi2dvi}.
2633 @code{--foreign} is implied.
2636 The options @samp{no-installinfo} and @samp{no-dependencies} are
2640 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
2644 The @code{check} target doesn't depend on @code{all}.
2647 GNU maintainers are advised to use @samp{gnu} strictness in preference
2648 to the special Cygnus mode.
2651 @node Extending, Distributing, Cygnus, Top
2652 @chapter When Automake Isn't Enough
2654 Automake's implicit copying semantics means that many problems can be
2655 worked around by simply adding some @code{make} targets and rules to
2656 @file{Makefile.in}. @code{automake} will ignore these additions.
2658 There are some caveats to doing this. Although you can overload a
2659 target already used by @code{automake}, it is often inadvisable,
2660 particularly in the topmost directory of a non-flat package. However,
2661 various useful targets have a @samp{-local} version you can specify in your
2662 @file{Makefile.in}. Automake will supplement the standard target with
2663 these user-supplied targets.
2665 The targets that support a local version are @code{all}, @code{info},
2666 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
2667 @code{uninstall}, and the various @code{clean} targets
2668 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
2669 @code{maintainer-clean}). Note that there are no
2670 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
2671 use @code{uninstall-local}. It doesn't make sense to uninstall just
2672 data or just executables.
2677 @trindex install-data
2678 @trindex install-exec
2681 For instance, here is one way to install a file in @file{/etc}:
2685 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
2688 Some targets also have a way to run another target, called a @dfn{hook},
2689 after their work is done. The hook is named after the principal target,
2690 with @samp{-hook} appended. The targets allowing hooks are
2691 @code{install-data}, @code{install-exec}, @code{dist}, and
2693 @trindex install-data-hook
2694 @trindex install-exec-hook
2697 For instance, here is how to create a hard link to an installed program:
2701 ln $(bindir)/program $(bindir)/proglink
2704 @c FIXME should include discussion of variables you can use in these
2708 @node Distributing, Future, Extending, Top
2709 @chapter Distributing @file{Makefile.in}s
2711 Automake places no restrictions on the distribution of the resulting
2712 @file{Makefile.in}s. We still encourage software authors to distribute
2713 their work under terms like those of the GPL, but doing so is not
2714 required to use Automake.
2716 Some of the files that can be automatically installed via the
2717 @code{--add-missing} switch do fall under the GPL; examine each file
2721 @node Future, Index, Distributing, Top
2722 @chapter Some ideas for the future
2724 Here are some things that might happen in the future:
2731 The output will be cleaned up. For instance, only variables which are
2732 actually used will appear in the generated @file{Makefile.in}.
2735 There will be support for automatically recoding a distribution. The
2736 intent is to allow a maintainer to use whatever character set is most
2737 convenient locally, but for all distributions to be Unicode or
2738 @w{ISO 10646} with the UTF-8 encoding.
2741 Support for automatically generating packages (eg Debian packages, RPM
2742 packages, Solaris packages, etc). This will happen more quickly if
2743 someone with package-building experience can tell me what would be
2747 Rewrite in Guile. This won't happen in the near future, but it will
2751 @node Index, , Future, Top