1 \input texinfo @c -*-texinfo-*-
3 @setfilename automake.info
10 @dircategory GNU programming tools
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 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002
24 Free Software Foundation, Inc.
26 Permission is granted to make and distribute verbatim copies of
27 this manual provided the copyright notice and this permission notice
28 are preserved on all copies.
31 Permission is granted to process this file through TeX and print the
32 results, provided the printed document carries copying permission
33 notice identical to this one except for the removal of this paragraph
37 Permission is granted to copy and distribute modified versions of this
38 manual under the conditions for verbatim copying, provided that the entire
39 resulting derived work is distributed under the terms of a permission
40 notice identical to this one.
42 Permission is granted to copy and distribute translations of this manual
43 into another language, under the above conditions for modified versions,
44 except that this permission notice may be stated in a translation approved
51 @subtitle For version @value{VERSION}, @value{UPDATED}
52 @author David MacKenzie and Tom Tromey
55 @vskip 0pt plus 1filll
56 Copyright @copyright{} 1995, 1996, 2000, 2001, 2002 Free Software Foundation, Inc.
58 This is the first edition of the GNU Automake documentation,@*
59 and is consistent with GNU Automake @value{VERSION}.@*
61 Published by the Free Software Foundation @*
62 59 Temple Place - Suite 330, @*
63 Boston, MA 02111-1307 USA @*
65 Permission is granted to make and distribute verbatim copies of
66 this manual provided the copyright notice and this permission notice
67 are preserved on all copies.
69 Permission is granted to copy and distribute modified versions of this
70 manual under the conditions for verbatim copying, provided that the entire
71 resulting derived work is distributed under the terms of a permission
72 notice identical to this one.
74 Permission is granted to copy and distribute translations of this manual
75 into another language, under the above conditions for modified versions,
76 except that this permission notice may be stated in a translation
77 approved by the Free Software Foundation.
80 @c Define an index of configure output variables.
82 @c Define an index of configure variables.
84 @c Define an index of options.
86 @c Define an index of targets.
88 @c Define an index of commands.
91 @c Put the macros and variables into their own index.
92 @c @syncodeindex fn cp
97 @c Put everything else into one index (arbitrarily chosen to be the concept index).
103 @node Top, Introduction, (dir), (dir)
104 @comment node-name, next, previous, up
107 This file documents the GNU Automake package. Automake is a program
108 which creates GNU standards-compliant Makefiles from template files.
109 This edition documents version @value{VERSION}.
112 * Introduction:: Automake's purpose
113 * Generalities:: General ideas
114 * Examples:: Some example packages
115 * Invoking Automake:: Creating a Makefile.in
116 * configure:: Scanning configure.ac or configure.in
117 * Top level:: The top-level Makefile.am
118 * Alternative:: An alternative approach to subdirectories
119 * Rebuilding:: Automatic rebuilding of Makefile
120 * Programs:: Building programs and libraries
121 * Other objects:: Other derived objects
122 * Other GNU Tools:: Other GNU Tools
123 * Documentation:: Building documentation
124 * Install:: What gets installed
125 * Clean:: What gets cleaned
126 * Dist:: What goes in a distribution
127 * Tests:: Support for test suites
128 * Options:: Changing Automake's behavior
129 * Miscellaneous:: Miscellaneous rules
130 * Include:: Including extra files in an Automake template.
131 * Conditionals:: Conditionals
132 * Gnits:: The effect of @code{--gnu} and @code{--gnits}
133 * Cygnus:: The effect of @code{--cygnus}
134 * Extending:: Extending Automake
135 * Distributing:: Distributing the Makefile.in
136 * API versioning:: About compatibility between Automake versions
137 * Macro and Variable Index::
144 @node Introduction, Generalities, Top, Top
145 @chapter Introduction
147 Automake is a tool for automatically generating @file{Makefile.in}s from
148 files called @file{Makefile.am}. Each @file{Makefile.am} is basically a
149 series of @code{make} variable definitions@footnote{These variables are
150 also called @dfn{make macros} in Make terminology, however in this
151 manual we reserve the term @dfn{macro} for Autoconf's macros.}, with
152 rules being thrown in occasionally. The generated @file{Makefile.in}s
153 are compliant with the GNU Makefile standards.
155 @cindex GNU Makefile standards
157 The GNU Makefile Standards Document
158 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
159 is long, complicated, and subject to change. The goal of Automake is to
160 remove the burden of Makefile maintenance from the back of the
161 individual GNU maintainer (and put it on the back of the Automake
164 The typical Automake input file is simply a series of variable definitions.
165 Each such file is processed to create a @file{Makefile.in}. There
166 should generally be one @file{Makefile.am} per directory of a project.
168 @cindex Constraints of Automake
169 @cindex Automake constraints
171 Automake does constrain a project in certain ways; for instance it
172 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
173 autoconf, The Autoconf Manual}), and enforces certain restrictions on
174 the @file{configure.in} contents@footnote{Autoconf 2.50 promotes
175 @file{configure.ac} over @file{configure.in}. The rest of this
176 documentation will refer to @file{configure.in} as this use is not yet
177 spread, but Automake supports @file{configure.ac} too.}.
179 @cindex Automake requirements
180 @cindex Requirements, Automake
182 Automake requires @code{perl} in order to generate the
183 @file{Makefile.in}s. However, the distributions created by Automake are
184 fully GNU standards-compliant, and do not require @code{perl} in order
187 @cindex BUGS, reporting
188 @cindex Reporting BUGS
189 @cindex E-mail, bug reports
191 Mail suggestions and bug reports for Automake to
192 @email{bug-automake@@gnu.org}.
195 @node Generalities, Examples, Introduction, Top
196 @chapter General ideas
198 The following sections cover a few basic ideas that will help you
199 understand how Automake works.
202 * General Operation:: General operation of Automake
203 * Strictness:: Standards conformance checking
204 * Uniform:: The Uniform Naming Scheme
205 * Canonicalization:: How derived variables are named
206 * User Variables:: Variables reserved for the user
207 * Auxiliary Programs:: Programs automake might require
211 @node General Operation, Strictness, Generalities, Generalities
212 @section General Operation
214 Automake works by reading a @file{Makefile.am} and generating a
215 @file{Makefile.in}. Certain variables and targets defined in the
216 @file{Makefile.am} instruct Automake to generate more specialized code;
217 for instance, a @samp{bin_PROGRAMS} variable definition will cause targets
218 for compiling and linking programs to be generated.
220 @cindex Non-standard targets
221 @cindex cvs-dist, non-standard example
224 The variable definitions and targets in the @file{Makefile.am} are copied
225 verbatim into the generated file. This allows you to add arbitrary code
226 into the generated @file{Makefile.in}. For instance the Automake
227 distribution includes a non-standard @code{cvs-dist} target, which the
228 Automake maintainer uses to make distributions from his source control
231 @cindex GNU make extensions
233 Note that most GNU make extensions are not recognized by Automake. Using
234 such extensions in a @file{Makefile.am} will lead to errors or confusing
237 @cindex Append operator
238 A special exception is that the GNU make append operator, @samp{+=}, is
239 supported. This operator appends its right hand argument to the variable
240 specified on the left. Automake will translate the operator into
241 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
243 Automake tries to keep comments grouped with any adjoining targets or
244 variable definitions.
246 @cindex Make targets, overriding
247 @cindex Overriding make targets
249 A target defined in @file{Makefile.am} generally overrides any such
250 target of a similar name that would be automatically generated by
251 @code{automake}. Although this is a supported feature, it is generally
252 best to avoid making use of it, as sometimes the generated rules are
255 @cindex Variables, overriding
256 @cindex Overriding make variables
258 Similarly, a variable defined in @file{Makefile.am} or @code{AC_SUBST}'ed
259 from @file{configure.in} will override any definition of the variable that
260 @code{automake} would ordinarily create. This feature is more often
261 useful than the ability to override a target definition. Be warned that
262 many of the variables generated by @code{automake} are considered to be for
263 internal use only, and their names might change in future releases.
265 @cindex Recursive operation of Automake
266 @cindex Automake, recursive operation
267 @cindex Example of recursive operation
269 When examining a variable definition, Automake will recursively examine
270 variables referenced in the definition. For example, if Automake is
271 looking at the content of @code{foo_SOURCES} in this snippet
275 foo_SOURCES = c.c $(xs)
278 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
279 contents of @code{foo_SOURCES}.
281 @cindex ## (special Automake comment)
282 @cindex Special Automake comment
283 @cindex Comment, special to Automake
285 Automake also allows a form of comment which is @emph{not} copied into
286 the output; all lines beginning with @samp{##} (leading spaces allowed)
287 are completely ignored by Automake.
289 It is customary to make the first line of @file{Makefile.am} read:
291 @cindex Makefile.am, first line
292 @cindex First line of Makefile.am
295 ## Process this file with automake to produce Makefile.in
298 @c FIXME discuss putting a copyright into Makefile.am here? I would but
299 @c I don't know quite what to say.
301 @c FIXME document customary ordering of Makefile.am here!
304 @node Strictness, Uniform, General Operation, Generalities
307 @cindex Non-GNU packages
309 While Automake is intended to be used by maintainers of GNU packages, it
310 does make some effort to accommodate those who wish to use it, but do
311 not want to use all the GNU conventions.
313 @cindex Strictness, defined
314 @cindex Strictness, foreign
315 @cindex foreign strictness
316 @cindex Strictness, gnu
317 @cindex gnu strictness
318 @cindex Strictness, gnits
319 @cindex gnits strictness
321 To this end, Automake supports three levels of @dfn{strictness}---the
322 strictness indicating how stringently Automake should check standards
325 The valid strictness levels are:
329 Automake will check for only those things which are absolutely
330 required for proper operations. For instance, whereas GNU standards
331 dictate the existence of a @file{NEWS} file, it will not be required in
332 this mode. The name comes from the fact that Automake is intended to be
333 used for GNU programs; these relaxed rules are not the standard mode of
337 Automake will check---as much as possible---for compliance to the GNU
338 standards for packages. This is the default.
341 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
342 standards}. These are based on the GNU standards, but are even more
343 detailed. Unless you are a Gnits standards contributor, it is
344 recommended that you avoid this option until such time as the Gnits
345 standard is actually published (which may never happen).
348 For more information on the precise implications of the strictness
349 level, see @ref{Gnits}.
351 Automake also has a special ``cygnus'' mode which is similar to
352 strictness but handled differently. This mode is useful for packages
353 which are put into a ``Cygnus'' style tree (e.g., the GCC tree). For
354 more information on this mode, see @ref{Cygnus}.
357 @node Uniform, Canonicalization, Strictness, Generalities
358 @section The Uniform Naming Scheme
360 @cindex Uniform naming scheme
362 Automake variables generally follow a @dfn{uniform naming scheme} that
363 makes it easy to decide how programs (and other derived objects) are
364 built, and how they are installed. This scheme also supports
365 @code{configure} time determination of what should be built.
367 @cindex _PROGRAMS primary variable
368 @cindex PROGRAMS primary variable
369 @cindex Primary variable, PROGRAMS
370 @cindex Primary variable, defined
372 At @code{make} time, certain variables are used to determine which
373 objects are to be built. The variable names are made of several pieces
374 which are concatenated together.
376 The piece which tells automake what is being built is commonly called
377 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
378 list of programs which are to be compiled and linked.
381 @cindex pkglibdir, defined
382 @cindex pkgincludedir, defined
383 @cindex pkgdatadir, defined
386 @vindex pkgincludedir
389 A different set of names is used to decide where the built objects
390 should be installed. These names are prefixes to the primary which
391 indicate which standard directory should be used as the installation
392 directory. The standard directory names are given in the GNU standards
393 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
394 Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
395 and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
396 versions, but with @samp{@@PACKAGE@@} appended. For instance,
397 @code{pkglibdir} is defined as @code{$(libdir)/@@PACKAGE@@}.
398 @cvindex PACKAGE, directory
400 @cindex EXTRA_, prepending
402 For each primary, there is one additional variable named by prepending
403 @samp{EXTRA_} to the primary name. This variable is used to list
404 objects which may or may not be built, depending on what
405 @code{configure} decides. This variable is required because Automake
406 must statically know the entire list of objects that may be built in
407 order to generate a @file{Makefile.in} that will work in all cases.
409 @cindex EXTRA_PROGRAMS, defined
410 @cindex Example, EXTRA_PROGRAMS
413 For instance, @code{cpio} decides at configure time which programs are
414 built. Some of the programs are installed in @code{bindir}, and some
415 are installed in @code{sbindir}:
418 EXTRA_PROGRAMS = mt rmt
419 bin_PROGRAMS = cpio pax
420 sbin_PROGRAMS = @@MORE_PROGRAMS@@
423 Defining a primary without a prefix as a variable, e.g.,
424 @code{PROGRAMS}, is an error.
426 Note that the common @samp{dir} suffix is left off when constructing the
427 variable names; thus one writes @samp{bin_PROGRAMS} and not
428 @samp{bindir_PROGRAMS}.
430 Not every sort of object can be installed in every directory. Automake
431 will flag those attempts it finds in error.
432 Automake will also diagnose obvious misspellings in directory names.
434 @cindex Extending list of installation directories
435 @cindex Installation directories, extending list
437 Sometimes the standard directories---even as augmented by Automake---
438 are not enough. In particular it is sometimes useful, for clarity, to
439 install objects in a subdirectory of some predefined directory. To this
440 end, Automake allows you to extend the list of possible installation
441 directories. A given prefix (e.g. @samp{zar}) is valid if a variable of
442 the same name with @samp{dir} appended is defined (e.g. @code{zardir}).
444 @cindex HTML support, example
446 For instance, until HTML support is part of Automake, you could use this
447 to install raw HTML documentation:
450 htmldir = $(prefix)/html
451 html_DATA = automake.html
454 @cindex noinst primary prefix, definition
456 The special prefix @samp{noinst} indicates that the objects in question
457 should be built but not installed at all. This is usually used for
458 objects required to build the rest of your package, for instance static
459 libraries (@pxref{A Library}), or helper scripts.
461 @cindex check primary prefix, definition
463 The special prefix @samp{check} indicates that the objects in question
464 should not be built until the @code{make check} command is run. Those
465 objects are not installed either.
467 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
468 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
469 @samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
481 Some primaries also allow additional prefixes which control other
482 aspects of @code{automake}'s behavior. The currently defined prefixes
483 are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes
484 are explained later (@pxref{Program and Library Variables}).
487 @node Canonicalization, User Variables, Uniform, Generalities
488 @section How derived variables are named
490 @cindex canonicalizing Automake variables
492 Sometimes a Makefile variable name is derived from some text the
493 maintainer supplies. For instance, a program name listed in
494 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
495 variable. In cases like this, Automake canonicalizes the text, so that
496 program names and the like do not have to follow Makefile variable naming
497 rules. All characters in the name except for letters, numbers, the
498 strudel (@@), and the underscore are turned into underscores when making
501 For example, if your program is named @code{sniff-glue}, the derived
502 variable name would be @code{sniff_glue_SOURCES}, not
503 @code{sniff-glue_SOURCES}. Similarly the sources for a library named
504 @code{libmumble++.a} should be listed in the
505 @code{libmumble___a_SOURCES} variable.
507 The strudel is an addition, to make the use of Autoconf substitutions in
508 variable names less obfuscating.
511 @node User Variables, Auxiliary Programs, Canonicalization, Generalities
512 @section Variables reserved for the user
514 @cindex variables, reserved for the user
515 @cindex user variables
517 Some @code{Makefile} variables are reserved by the GNU Coding Standards
518 for the use of the ``user'' -- the person building the package. For
519 instance, @code{CFLAGS} is one such variable.
521 Sometimes package developers are tempted to set user variables such as
522 @code{CFLAGS} because it appears to make their job easier -- they don't
523 have to introduce a second variable into every target.
525 However, the package itself should never set a user variable,
526 particularly not to include switches which are required for proper
527 compilation of the package. Since these variables are documented as
528 being for the package builder, that person rightfully expects to be able
529 to override any of these variables at build time.
530 @c FIXME: maybe Automake could bark if a developer forces a user variable
533 To get around this problem, automake introduces an automake-specific
534 shadow variable for each user flag variable. (Shadow variables are not
535 introduced for variables like @code{CC}, where they would make no
536 sense.) The shadow variable is named by prepending @samp{AM_} to the
537 user variable's name. For instance, the shadow variable for
538 @code{YFLAGS} is @code{AM_YFLAGS}.
541 @node Auxiliary Programs, , User Variables, Generalities
542 @section Programs automake might require
544 @cindex Programs, auxiliary
545 @cindex Auxiliary programs
547 Automake sometimes requires helper programs so that the generated
548 @file{Makefile} can do its work properly. There are a fairly large
549 number of them, and we list them here.
554 These two files are used by the automatic de-ANSI-fication support
558 This is a wrapper for compilers which don't accept both @samp{-c} and
559 @samp{-o} at the same time. It is only used when absolutely required.
560 Such compilers are rare.
564 These programs compute the canonical triplets for the given build, host,
565 or target architecture. These programs are updated regulary to support
566 new architectures and fix probes broken by changes in new kernel
567 versions. You are encouraged to fetch the latest versions of these
568 files from @url{ftp://ftp.gnu.org/gnu/config/} before making a release.
571 This program understands how to run a compiler so that it will generate
572 not only the desired output but also dependency information which is
573 then used by the automatic dependency tracking feature.
576 This program is used to byte-compile Emacs Lisp code.
579 This is a replacement for the @code{install} program which works on
580 platforms where @code{install} is unavailable or unusable.
583 This script is used to generate a @file{version.texi} file. It examines
584 a file and prints some date information about it.
587 This wraps a number of programs which are typically only required by
588 maintainers. If the program in question doesn't exist, @code{missing}
589 prints an informative warning and attempts to fix things so that the
593 This works around the fact that @code{mkdir -p} is not portable.
596 This is used to byte-compile Python scripts.
599 Not a program, this file is required for @code{make dvi}, @code{make ps}
600 and @code{make pdf} to work when Texinfo sources are in the package.
603 This program wraps @code{lex} and @code{yacc} and ensures that, for
604 instance, multiple @code{yacc} instances can be invoked in a single
605 directory in parallel.
610 @node Examples, Invoking Automake, Generalities, Top
611 @chapter Some example packages
614 * Complete:: A simple example, start to finish
615 * Hello:: A classic program
616 * etags:: Building etags and ctags
620 @node Complete, Hello, Examples, Examples
621 @section A simple example, start to finish
623 @cindex Complete example
625 Let's suppose you just finished writing @code{zardoz}, a program to make
626 your head float from vortex to vortex. You've been using Autoconf to
627 provide a portability framework, but your @file{Makefile.in}s have been
628 ad-hoc. You want to make them bulletproof, so you turn to Automake.
630 @cindex AM_INIT_AUTOMAKE, example use
632 The first step is to update your @file{configure.in} to include the
633 commands that @code{automake} needs. The way to do this is to add an
634 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
642 Since your program doesn't have any complicating factors (e.g., it
643 doesn't use @code{gettext}, it doesn't want to build a shared library),
644 you're done with this part. That was easy!
646 @cindex aclocal program, introduction
647 @cindex aclocal.m4, preexisting
648 @cindex acinclude.m4, defined
650 Now you must regenerate @file{configure}. But to do that, you'll need
651 to tell @code{autoconf} how to find the new macro you've used. The
652 easiest way to do this is to use the @code{aclocal} program to generate
653 your @file{aclocal.m4} for you. But wait@dots{} maybe you already have an
654 @file{aclocal.m4}, because you had to write some hairy macros for your
655 program. The @code{aclocal} program lets you put your own macros into
656 @file{acinclude.m4}, so simply rename and then run:
659 mv aclocal.m4 acinclude.m4
664 @cindex zardoz example
666 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
667 Since @code{zardoz} is a user program, you want to install it where the
668 rest of the user programs go: @code{bindir}. Additionally,
669 @code{zardoz} has some Texinfo documentation. Your @file{configure.in}
670 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
671 @samp{@@LIBOBJS@@}. So here's what you'd write:
674 bin_PROGRAMS = zardoz
675 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
676 zardoz_LDADD = @@LIBOBJS@@
678 info_TEXINFOS = zardoz.texi
681 Now you can run @code{automake --add-missing} to generate your
682 @file{Makefile.in} and grab any auxiliary files you might need, and
686 @node Hello, etags, Complete, Examples
687 @section A classic program
689 @cindex Example, GNU Hello
690 @cindex Hello example
691 @cindex GNU Hello, example
693 @uref{ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz, GNU hello} is
694 renowned for its classic simplicity and versatility. This section shows
695 how Automake could be used with the GNU Hello package. The examples
696 below are from the latest beta version of GNU Hello, but with all of the
697 maintainer-only code stripped out, as well as all copyright comments.
699 Of course, GNU Hello is somewhat more featureful than your traditional
700 two-liner. GNU Hello is internationalized, does option processing, and
701 has a manual and a test suite.
703 @cindex configure.in, from GNU Hello
704 @cindex GNU Hello, configure.in
705 @cindex Hello, configure.in
707 Here is the @file{configure.in} from GNU Hello:
708 @c FIXME: This definitively requires an update.
711 dnl Process this file with autoconf to produce a configure script.
713 AM_INIT_AUTOMAKE(hello, 1.3.11)
714 AM_CONFIG_HEADER(config.h)
716 dnl Set of available languages.
717 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
719 dnl Checks for programs.
723 dnl Checks for libraries.
725 dnl Checks for header files.
727 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
729 dnl Checks for library functions.
732 dnl Check for st_blksize in struct stat
735 dnl internationalization macros
737 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
738 src/Makefile tests/Makefile tests/hello],
739 [chmod +x tests/hello])
742 The @samp{AM_} macros are provided by Automake (or the Gettext library);
743 the rest are standard Autoconf macros.
746 The top-level @file{Makefile.am}:
749 EXTRA_DIST = BUGS ChangeLog.O
750 SUBDIRS = doc intl po src tests
753 As you can see, all the work here is really done in subdirectories.
755 The @file{po} and @file{intl} directories are automatically generated
756 using @code{gettextize}; they will not be discussed here.
758 @cindex Texinfo file handling example
759 @cindex Example, handling Texinfo files
761 In @file{doc/Makefile.am} we see:
764 info_TEXINFOS = hello.texi
765 hello_TEXINFOS = gpl.texi
768 This is sufficient to build, install, and distribute the GNU Hello
771 @cindex Regression test example
772 @cindex Example, regression test
774 Here is @file{tests/Makefile.am}:
778 EXTRA_DIST = hello.in testdata
781 The script @file{hello} is generated by @code{configure}, and is the
782 only test case. @code{make check} will run this test.
784 @cindex INCLUDES, example usage
786 Last we have @file{src/Makefile.am}, where all the real work is done:
787 @c FIXME: As all the Hello World excerpts in this manual, this
788 @c shows deprecated features (here: $(INCLUDES)).
792 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
793 hello_LDADD = @@INTLLIBS@@ @@ALLOCA@@
794 localedir = $(datadir)/locale
795 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
799 @node etags, , Hello, Examples
800 @section Building etags and ctags
802 @cindex Example, ctags and etags
803 @cindex ctags Example
804 @cindex etags Example
806 Here is another, trickier example. It shows how to generate two
807 programs (@code{ctags} and @code{etags}) from the same source file
808 (@file{etags.c}). The difficult part is that each compilation of
809 @file{etags.c} requires different @code{cpp} flags.
812 bin_PROGRAMS = etags ctags
814 ctags_LDADD = ctags.o
817 $(COMPILE) -DETAGS_REGEXPS -c etags.c
820 $(COMPILE) -DCTAGS -o ctags.o -c etags.c
823 Note that there is no @code{etags_SOURCES} definition. Automake will
824 implicitly assume that there is a source file named @file{etags.c}, and
825 define rules to compile @file{etags.o} and link @file{etags}. The
826 @code{etags.o: etags.c} rule supplied by the above @file{Makefile.am},
827 will override the Automake generated rule to build @file{etags.o}.
829 @code{ctags_SOURCES} is defined to be empty---that way no implicit value
830 is substituted. Because we have not listed the source of
831 @file{ctags}, we have to tell Automake how to link the program. This is
832 the purpose of the @code{ctags_LDADD} line. A @code{ctags_DEPENDENCIES}
833 variable, holding the dependencies of the @file{ctags} target will be
834 automatically generated by Automake from the contant of
837 The above rules won't work if your compiler doesn't accept both
838 @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
839 bogus dependency (to avoid problems with a parallel @code{make}):
842 etags.o: etags.c ctags.o
843 $(COMPILE) -DETAGS_REGEXPS -c etags.c
846 $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
849 Also, these explicit rules do not work if the de-ANSI-fication feature
850 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
854 etags._o: etags._c ctags.o
855 $(COMPILE) -DETAGS_REGEXPS -c etags.c
858 $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
861 As it turns out, there is also a much easier way to do this same task.
862 Some of the above techniques are useful enough that we've kept the
863 example in the manual. However if you were to build @code{etags} and
864 @code{ctags} in real life, you would probably use per-program
865 compilation flags, like so:
868 bin_PROGRAMS = ctags etags
870 ctags_SOURCES = etags.c
871 ctags_CPPFLAGS = -DCTAGS
873 etags_SOURCES = etags.c
874 etags_CPPFLAGS = -DETAGS_REGEXPS
877 In this case Automake will cause @file{etags.c} to be compiled twice,
878 with different flags. De-ANSI-fication will work automatically. In
879 this instance, the names of the object files would be chosen by
880 automake; they would be @file{ctags-etags.o} and @file{etags-etags.o}.
881 (The name of the object files rarely matters.)
884 @node Invoking Automake, configure, Examples, Top
885 @chapter Creating a @file{Makefile.in}
887 @cindex Multiple configure.in files
888 @cindex Invoking Automake
889 @cindex Automake, invoking
891 To create all the @file{Makefile.in}s for a package, run the
892 @code{automake} program in the top level directory, with no arguments.
893 @code{automake} will automatically find each appropriate
894 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
895 and generate the corresponding @file{Makefile.in}. Note that
896 @code{automake} has a rather simplistic view of what constitutes a
897 package; it assumes that a package has only one @file{configure.in}, at
898 the top. If your package has multiple @file{configure.in}s, then you
899 must run @code{automake} in each directory holding a
900 @file{configure.in}. (Alteratively, you may rely on Autoconf's
901 @code{autoreconf}, which is able to recurse your package tree and run
902 @code{automake} where appropriate.)
904 You can optionally give @code{automake} an argument; @file{.am} is
905 appended to the argument and the result is used as the name of the input
906 file. This feature is generally only used to automatically rebuild an
907 out-of-date @file{Makefile.in}. Note that @code{automake} must always
908 be run from the topmost directory of a project, even if being used to
909 regenerate the @file{Makefile.in} in some subdirectory. This is
910 necessary because @code{automake} must scan @file{configure.in}, and
911 because @code{automake} uses the knowledge that a @file{Makefile.in} is
912 in a subdirectory to change its behavior in some cases.
915 Automake will run @code{autoconf} to scan @file{configure.in} and its
916 dependencies (@file{aclocal.m4}), therefore @code{autoconf} must be in
917 your @code{PATH}. If there is an @code{AUTOCONF} variable in your
918 environment it will be used instead of @code{autoconf}, this allows you
919 to select a particular version of Autoconf. By the way, don't
920 misunderstand this paragraph: Automake runs @code{autoconf} to
921 @strong{scan} your @file{configure.in}, this won't build
922 @file{configure} and you still have to run @code{autoconf} yourself for
925 @cindex Automake options
926 @cindex Options, Automake
927 @cindex Strictness, command line
929 @code{automake} accepts the following options:
931 @cindex Extra files distributed with Automake
932 @cindex Files distributed with Automake
939 @opindex --add-missing
940 Automake requires certain common files to exist in certain situations;
941 for instance @file{config.guess} is required if @file{configure.in} runs
942 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
943 files (@pxref{Auxiliary Programs}); this option will cause the missing
944 ones to be automatically added to the package, whenever possible. In
945 general if Automake tells you a file is missing, try using this option.
946 By default Automake tries to make a symbolic link pointing to its own
947 copy of the missing file; this can be changed with @code{--copy}.
949 @item --libdir=@var{dir}
951 Look for Automake data files in directory @var{dir} instead of in the
952 installation directory. This is typically used for debugging.
958 When used with @code{--add-missing}, causes installed files to be
959 copied. The default is to make a symbolic link.
963 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
964 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
968 @itemx --force-missing
969 @opindex --force-missing
970 When used with @code{--add-missing}, causes standard files to be reinstalled
971 even if they already exist in the source tree. This involves removing
972 the file from the source tree before creating the new symlink (or, with
973 @code{--copy}, copying the new file).
977 Set the global strictness to @samp{foreign}. For more information, see
982 Set the global strictness to @samp{gnits}. For more information, see
987 Set the global strictness to @samp{gnu}. For more information, see
988 @ref{Gnits}. This is the default strictness.
992 Print a summary of the command line options and exit.
997 This disables the dependency tracking feature in generated
998 @file{Makefile}s; see @ref{Dependencies}.
1000 @item --include-deps
1001 @opindex --include-deps
1002 This enables the dependency tracking feature. This feature is enabled
1003 by default. This option is provided for historical reasons only and
1004 probably should not be used.
1008 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
1009 @file{configure.in}. This option causes it to only update those
1010 @file{Makefile.in}s which are out of date with respect to one of their
1014 @itemx --output-dir=@var{dir}
1016 @opindex --output-dir
1017 Put the generated @file{Makefile.in} in the directory @var{dir}.
1018 Ordinarily each @file{Makefile.in} is created in the directory of the
1019 corresponding @file{Makefile.am}. This option is deprecated and will be
1020 removed in a future release.
1026 Cause Automake to print information about which files are being read or
1031 Print the version number of Automake and exit.
1034 @item --warnings=@var{category}
1037 Output warnings falling in @var{category}. @var{category} can be
1041 warnings related to the GNU Coding Standards
1042 (@pxref{Top, , , standards, The GNU Coding Standards}).
1044 obsolete features or constructions
1046 unsupported or incomplete features
1054 turn off all the warnings
1056 treat warnings as errors
1059 A category can be turned off by prefixing its name with @samp{no-}. For
1060 instance @samp{-Wno-unused} will hide the warnings about unused
1063 The categories output by default are @samp{unsupported} and
1064 @samp{unused}. Additionally, @samp{gnu} and @samp{portability} warnings
1065 are enabled in @samp{--gnu} and @samp{--gnits} strictness.
1068 The environment variable @samp{WARNINGS} can contain a comma separated
1069 list of categories to enable. It will be taken into account before the
1070 command-line switches, this way @samp{-Wnone} will also ignore any
1071 warning category enabled by @samp{WARNINGS}. This variable is also used
1072 by other tools like @command{autoconf}; unknown categories are ignored
1078 @node configure, Top level, Invoking Automake, Top
1079 @chapter Scanning @file{configure.in}
1081 @cindex configure.in, scanning
1082 @cindex Scanning configure.in
1084 Automake scans the package's @file{configure.in} to determine certain
1085 information about the package. Some @code{autoconf} macros are required
1086 and some variables must be defined in @file{configure.in}. Automake
1087 will also use information from @file{configure.in} to further tailor its
1090 Automake also supplies some Autoconf macros to make the maintenance
1091 easier. These macros can automatically be put into your
1092 @file{aclocal.m4} using the @code{aclocal} program.
1095 * Requirements:: Configuration requirements
1096 * Optional:: Other things Automake recognizes
1097 * Invoking aclocal:: Auto-generating aclocal.m4
1098 * Macros:: Autoconf macros supplied with Automake
1099 * Extending aclocal:: Writing your own aclocal macros
1103 @node Requirements, Optional, configure, configure
1104 @section Configuration requirements
1106 @cindex Automake requirements
1107 @cindex Requirements of Automake
1109 The one real requirement of Automake is that your @file{configure.in}
1110 call @code{AM_INIT_AUTOMAKE}. This macro does several things which are
1111 required for proper Automake operation (@pxref{Macros}).
1112 @cvindex AM_INIT_AUTOMAKE
1114 Here are the other macros which Automake requires but which are not run
1115 by @code{AM_INIT_AUTOMAKE}:
1117 @cindex AC_OUTPUT, scanning
1120 @item AC_CONFIG_FILES
1122 Automake uses these to determine which files to create (@pxref{Output, ,
1123 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
1124 is considered to be an Automake generated @file{Makefile} if there
1125 exists a file with the same name and the @file{.am} extension appended.
1126 Typically, @code{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
1127 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
1129 Other listed files are treated differently. Currently the only
1130 difference is that an Automake @file{Makefile} is removed by @code{make
1131 distclean}, while other files are removed by @code{make clean}.
1132 @c FIXME: this is in violation of standards!
1137 @node Optional, Invoking aclocal, Requirements, configure
1138 @section Other things Automake recognizes
1140 @cindex Macros Automake recognizes
1141 @cindex Recognized macros by Automake
1143 Automake will also recognize the use of certain macros and tailor the
1144 generated @file{Makefile.in} appropriately. Currently recognized macros
1145 and their effects are:
1148 @item AC_CONFIG_HEADERS
1149 Automake will generate rules to rebuild these headers. Older versions
1150 of Automake required the use of @code{AM_CONFIG_HEADER}
1151 (@pxref{Macros}); this no longuer the case today.
1152 @cvindex AC_CONFIG_HEADERS
1154 @item AC_CONFIG_AUX_DIR
1155 Automake will look for various helper scripts, such as
1156 @file{mkinstalldirs}, in the directory named in this macro invocation.
1157 If not seen, the scripts are looked for in their @samp{standard}
1158 locations (either the top source directory, or in the source directory
1159 corresponding to the current @file{Makefile.am}, whichever is
1160 appropriate). @xref{Input, , Finding `configure' Input, autoconf, The
1162 @cvindex AC_CONFIG_AUX_DIR
1163 FIXME: give complete list of things looked for in this directory
1166 Automake will insert definitions for the variables defined by
1167 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
1168 or library. @xref{System Services, , System Services, autoconf, The
1170 @cvindex AC_PATH_XTRA
1172 @item AC_CANONICAL_HOST
1173 Automake will ensure that @file{config.guess} and @file{config.sub}
1174 exist. Also, the @file{Makefile} variables @samp{host_alias} and
1175 @samp{host_triplet} are introduced. See @ref{Canonicalizing, ,
1176 Getting the Canonical System Type, autoconf, The Autoconf Manual}.
1177 @cvindex AC_CANONICAL_HOST
1179 @vindex host_triplet
1181 @item AC_CANONICAL_SYSTEM
1182 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
1183 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
1184 @xref{Canonicalizing, , Getting the Canonical System Type, autoconf, The
1186 @cvindex AC_CANONICAL_SYSTEM
1188 @vindex target_alias
1190 @item AC_FUNC_ALLOCA
1191 @itemx AC_FUNC_ERROR_AT_LINE
1192 @itemx AC_FUNC_FNMATCH
1193 @itemx AC_FUNC_GETLOADAVG
1194 @itemx AC_FUNC_MEMCMP
1195 @itemx AC_FUNC_MKTIME
1196 @itemx AC_FUNC_OBSTACK
1197 @itemx AC_FUNC_STRTOD
1198 @itemx AC_REPLACE_FUNCS
1199 @itemx AC_REPLACE_GNU_GETOPT
1200 @itemx AC_STRUCT_ST_BLOCKS
1201 @itemx AM_WITH_REGEX
1202 Automake will ensure that the appropriate dependencies are generated for
1203 the objects corresponding to these macros. Also, Automake will verify
1204 that the appropriate source files are part of the distribution. Note
1205 that Automake does not come with any of the C sources required to use
1206 these macros, so @code{automake -a} will not install the sources.
1207 @xref{A Library}, for more information. Also, see @ref{Particular
1208 Functions, , Particular Function Checks, autoconf, The Autoconf Manual}.
1209 @cvindex AC_FUNC_ALLOCA
1210 @cvindex AC_FUNC_ERROR_AT_LINE
1211 @cvindex AC_FUNC_FNMATCH
1212 @cvindex AC_FUNC_GETLOADAVG
1213 @cvindex AC_FUNC_MEMCMP
1214 @cvindex AC_FUNC_MKTIME
1215 @cvindex AC_FUNC_OBSTACK
1216 @cvindex AC_FUNC_STRTOD
1217 @cvindex AC_REPLACE_FUNCS
1218 @cvindex AC_REPLACE_GNU_GETOPT
1219 @cvindex AC_STRUCT_ST_BLOCKS
1220 @cvindex AM_WITH_REGEX
1225 @itemx AC_LIBSOURCES
1226 Automake will detect statements which put @file{.o} files into
1227 @code{LIBOBJS}, or pass @file{.o} files to @code{AC_LIBOBJ}, and will
1228 treat these additional files as if they were discovered via
1229 @code{AC_REPLACE_FUNCS}. Similarly, Automake will also distribute file
1230 listed in @code{AC_LIBSOURCE} and @code{AC_LIBSOURCES}.
1232 Note that assignments to @code{LIBOBJS} is a construct which is being
1233 phased out; they will be ignored in a future release of Automake. You
1234 should call the @code{AC_LIBOBJ} macro instead. @xref{Generic
1235 Functions, , Generic Function Checks, autoconf, The Autoconf Manual}.
1238 @cvindex AC_LIBSOURCE
1239 @cvindex AC_LIBSOURCES
1242 @item AC_PROG_RANLIB
1243 This is required if any libraries are built in the package.
1244 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1246 @cvindex AC_PROG_RANLIB
1249 This is required if any C++ source is included. @xref{Particular
1250 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1251 @cvindex AC_PROG_CXX
1254 This is required if any Fortran 77 source is included. This macro is
1255 distributed with Autoconf version 2.13 and later. @xref{Particular
1256 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1257 @cvindex AC_PROG_F77
1259 @item AC_F77_LIBRARY_LDFLAGS
1260 This is required for programs and shared libraries that are a mixture of
1261 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
1262 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
1263 @cvindex AC_F77_LIBRARY_LDFLAGS
1265 @item AC_PROG_LIBTOOL
1266 Automake will turn on processing for @code{libtool} (@pxref{Top, ,
1267 Introduction, libtool, The Libtool Manual}).
1268 @cvindex AC_PROG_LIBTOOL
1271 If a Yacc source file is seen, then you must either use this macro or
1272 define the variable @samp{YACC} in @file{configure.in}. The former is
1273 preferred (@pxref{Particular Programs, , Particular Program Checks,
1274 autoconf, The Autoconf Manual}).
1275 @cvindex AC_PROG_YACC
1279 If a Lex source file is seen, then this macro must be used.
1280 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1282 @cvindex AC_PROG_LEX
1284 @item AM_C_PROTOTYPES
1285 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
1286 @cvindex AM_C_PROTOTYPES
1288 @item AM_GNU_GETTEXT
1289 This macro is required for packages which use GNU gettext
1290 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1291 this macro it ensures that the package meets some of gettext's
1293 @cvindex AM_GNU_GETTEXT
1295 @item AM_MAINTAINER_MODE
1296 @opindex --enable-maintainer-mode
1297 This macro adds a @samp{--enable-maintainer-mode} option to
1298 @code{configure}. If this is used, @code{automake} will cause
1299 @samp{maintainer-only} rules to be turned off by default in the
1300 generated @file{Makefile.in}s. This macro defines the
1301 @samp{MAINTAINER_MODE} conditional, which you can use in your own
1303 @cvindex AM_MAINTAINER_MODE
1306 @itemx AC_CHECK_TOOL
1307 @itemx AC_CHECK_PROG
1308 @itemx AC_CHECK_PROGS
1310 @itemx AC_PATH_PROGS
1311 For each of these macros, the first argument is automatically defined as
1312 a variable in each generated @file{Makefile.in}. @xref{Setting Output
1313 Variables, , Setting Output Variables, autoconf, The Autoconf Manual},
1314 and @ref{Generic Programs, , Generic Program Checks, autoconf, The
1317 @cvindex AC_CHECK_TOOL
1318 @cvindex AC_CHECK_PROG
1319 @cvindex AC_CHECK_PROGS
1320 @cvindex AC_PATH_PROG
1321 @cvindex AC_PATH_PROGS
1326 @node Invoking aclocal, Macros, Optional, configure
1327 @section Auto-generating aclocal.m4
1329 @cindex Invoking aclocal
1330 @cindex aclocal, Invoking
1332 Automake includes a number of Autoconf macros which can be used in your
1333 package; some of them are actually required by Automake in certain
1334 situations. These macros must be defined in your @file{aclocal.m4};
1335 otherwise they will not be seen by @code{autoconf}.
1337 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1338 files based on the contents of @file{configure.in}. This provides a
1339 convenient way to get Automake-provided macros, without having to
1340 search around. Also, the @code{aclocal} mechanism allows other packages
1341 to supply their own macros.
1343 At startup, @code{aclocal} scans all the @file{.m4} files it can find,
1344 looking for macro definitions. Then it scans @file{configure.in}. Any
1345 mention of one of the macros found in the first step causes that macro,
1346 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1348 The contents of @file{acinclude.m4}, if it exists, are also
1349 automatically included in @file{aclocal.m4}. This is useful for
1350 incorporating local macros into @file{configure}.
1352 @code{aclocal} tries to be smart about looking for new @code{AC_DEFUN}s
1353 in the files it scans. It also
1354 tries to copy the full text of the scanned file into @file{aclocal.m4},
1355 including both @samp{#} and @samp{dnl} comments. If you want to make a
1356 comment which will be completely ignored by @code{aclocal}, use
1357 @samp{##} as the comment leader.
1359 @code{aclocal} accepts the following options:
1362 @item --acdir=@var{dir}
1364 Look for the macro files in @var{dir} instead of the installation
1365 directory. This is typically used for debugging.
1369 Print a summary of the command line options and exit.
1373 Add the directory @var{dir} to the list of directories searched for
1376 @item --output=@var{file}
1378 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1380 @item --print-ac-dir
1381 @opindex --print-ac-dir
1382 Prints the name of the directory which @code{aclocal} will search to
1383 find third-party @file{.m4} files. When this option is given, normal
1384 processing is suppressed. This option can be used by a package to
1385 determine where to install a macro file.
1389 Print the names of the files it examines.
1393 Print the version number of Automake and exit.
1397 @node Macros, Extending aclocal, Invoking aclocal, configure
1398 @section Autoconf macros supplied with Automake
1400 Automake ships with several Autoconf macros that you can use from your
1401 @file{configure.in}. When you use one of them it will be included by
1402 @code{aclocal} in @file{aclocal.m4}.
1405 * Public macros:: Macros that you can use.
1406 * Private macros:: Macros that you should not use.
1409 @c consider generating the following subsections automatically from m4 files.
1411 @node Public macros, Private macros, Macros, Macros
1412 @subsection Public macros
1415 @item AM_CONFIG_HEADER
1416 Automake will generate rules to automatically regenerate the config
1417 header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
1418 today (@pxref{Optional}).
1419 @cvindex AM_CONFIG_HEADER
1421 @item AM_ENABLE_MULTILIB
1422 This is used when a ``multilib'' library is being built. The first
1423 optional argument is the name of the @file{Makefile} being generated; it
1424 defaults to @samp{Makefile}. The second option argument is used to find
1425 the top source directory; it defaults to the empty string (generally
1426 this should not be used unless you are familiar with the internals).
1429 @item AM_C_PROTOTYPES
1430 Check to see if function prototypes are understood by the compiler. If
1431 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1432 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1433 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1434 values to implement automatic de-ANSI-fication.
1435 @cvindex AM_C_PROTOTYPES
1437 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1438 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1439 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1440 found in @file{<termios.h>}.
1441 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1443 @item AM_INIT_AUTOMAKE([OPTIONS])
1444 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
1445 Runs many macros required for proper operation of the generated Makefiles.
1447 This macro has two forms, the second of which has two required
1448 arguments: the package and the version number. This latter form is
1449 obsolete because the @var{package} and @var{version} can be obtained
1450 from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
1453 If your @file{configure.in} has:
1456 AM_INIT_AUTOMAKE(mumble, 1.5)
1458 you can modernize it as follow:
1460 AC_INIT(mumble, 1.5)
1461 AC_CONFIG_SRCDIR(src/foo.c)
1465 Note that if you're upgrading your @file{configure.in} from an earlier
1466 version of Automake, it is not always correct to simply move the package
1467 and version arguments from @code{AM_INIT_AUTOMAKE} directly to
1468 @code{AC_INIT}, as in the example above. The first argument of
1469 @code{AC_INIT} is the name of your package (e.g. @samp{GNU Automake}),
1470 not the tarball name (e.g. @samp{automake}) you used to pass to
1471 @code{AM_INIT_AUTOMAKE}. Autoconf's rule to derive a tarball name from
1472 the package name should work for most but not all packages. Especially,
1473 if your tarball name is not all lower case, you will have to use the
1474 four-argument form of @code{AC_INIT} (supported in Autoconf versions
1475 greater than 2.52g).
1477 When @code{AM_INIT_AUTOMAKE} is called with a single argument, it is
1478 interpreted as a space-separated list of Automake options which should
1479 be applied to every @file{Makefile.am} in the tree. The effect is as if
1480 each option were listed in @code{AUTOMAKE_OPTIONS}.
1482 By default this macro @code{AC_DEFINE}'s @samp{PACKAGE} and
1483 @samp{VERSION}. This can be avoided by passing the @samp{no-define}
1486 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
1488 or by passing a third non-empty argument to the obsolete form.
1490 @cvindex PACKAGE, prevent definition
1491 @cvindex VERSION, prevent definition
1494 @item AM_PATH_LISPDIR
1495 Searches for the program @code{emacs}, and, if found, sets the output
1496 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1498 Note that this test assumes the @code{emacs} found to be a version that
1499 supports Emacs Lisp (such as @sc{gnu} Emacs or XEmacs). Other emacsen
1500 can cause this test to hang (some, like old versions of MicroEmacs,
1501 start up in interactive mode, requiring @samp{C-x C-c} to exit, which
1502 is hardly obvious for a non-emacs user). In most cases, however, you
1503 should be able to use @samp{C-c} to kill the test. In order to avoid
1504 problems, you can set @code{EMACS} to ``no'' in the environment, or
1505 use the @samp{--with-lispdir} option to @command{configure} to
1506 explictly set the correct path (if you're sure you have an @code{emacs}
1507 that supports Emacs Lisp.
1508 @cvindex AM_PATH_LISPDIR
1511 Use this macro when you have assembly code in your project. This will
1512 choose the assembler for you (by default the C compiler) and set
1513 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
1515 @item AM_PROG_CC_C_O
1516 This is like @code{AC_PROG_CC_C_O}, but it generates its results in the
1517 manner required by automake. You must use this instead of
1518 @code{AC_PROG_CC_C_O} when you need this functionality.
1520 @item AM_PROG_CC_STDC
1521 If the C compiler is not in ANSI C mode by default, try to add an option
1522 to output variable @code{CC} to make it so. This macro tries various
1523 options that select ANSI C on some system or another. It considers the
1524 compiler to be in ANSI C mode if it handles function prototypes correctly.
1526 If you use this macro, you should check after calling it whether the C
1527 compiler has been set to accept ANSI C; if not, the shell variable
1528 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1529 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1530 @code{ansi2knr} option (@pxref{ANSI}).
1533 @cindex HP-UX 10, lex problems
1534 @cindex lex problems with HP-UX 10
1535 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
1536 Program Checks, autoconf, The Autoconf Manual}), but uses the
1537 @code{missing} script on systems that do not have @code{lex}.
1538 @samp{HP-UX 10} is one such system.
1541 This macro finds the @code{gcj} program or causes an error. It sets
1542 @samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
1543 GNU Compiler Collection.
1544 @cvindex AM_PROG_GCJ
1546 @item AM_SYS_POSIX_TERMIOS
1547 @cvindex am_cv_sys_posix_termios
1548 @cindex POSIX termios headers
1549 @cindex termios POSIX headers
1550 Check to see if POSIX termios headers and functions are available on the
1551 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1552 @samp{yes}. If not, set the variable to @samp{no}.
1554 @item AM_WITH_DMALLOC
1555 @cvindex WITH_DMALLOC
1556 @cindex dmalloc, support for
1557 @opindex --with-dmalloc
1559 @uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
1560 package. If the user configures with @samp{--with-dmalloc}, then define
1561 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
1565 @opindex --with-regex
1566 @cindex regex package
1568 Adds @samp{--with-regex} to the @code{configure} command line. If
1569 specified (the default), then the @samp{regex} regular expression
1570 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1571 @samp{WITH_REGEX} is defined. If @samp{--without-regex} is given, then
1572 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1573 into @samp{LIBOBJS}.
1577 @node Private macros, , Public macros, Macros
1578 @subsection Private macros
1580 The following macros are private macros you should not call directly.
1581 They are called by the other public macros when appropriate. Do not
1582 rely on them, as they might be changed in a future version. Consider
1583 them as implementation details; or better, do not consider them at all:
1587 @item _AM_DEPENDENCIES
1588 @itemx AM_SET_DEPDIR
1590 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
1591 These macros are used to implement automake's automatic dependency
1592 tracking scheme. They are called automatically by automake when
1593 required, and there should be no need to invoke them manually.
1595 @item AM_MAKE_INCLUDE
1596 This macro is used to discover how the user's @code{make} handles
1597 @code{include} statements. This macro is automatically invoked when
1598 needed; there should be no need to invoke it manually.
1600 @item AM_PROG_INSTALL_STRIP
1601 This is used to find a version of @code{install} which can be used to
1602 @code{strip} a program at installation time. This macro is
1603 automatically included when required.
1605 @item AM_SANITY_CHECK
1606 This checks to make sure that a file created in the build directory is
1607 newer than a file in the source directory. This can fail on systems
1608 where the clock is set incorrectly. This macro is automatically run
1609 from @code{AM_INIT_AUTOMAKE}.
1615 @node Extending aclocal, , Macros, configure
1616 @section Writing your own aclocal macros
1618 @cindex aclocal, extending
1619 @cindex Extending aclocal
1621 The @code{aclocal} program doesn't have any built-in knowledge of any
1622 macros, so it is easy to extend it with your own macros.
1624 This is mostly used for libraries which want to supply their own
1625 Autoconf macros for use by other programs. For instance the
1626 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1627 should be used by any package using @code{gettext}. When the library is
1628 installed, it installs this macro so that @code{aclocal} will find it.
1630 A file of macros should be a series of @code{AC_DEFUN}'s. The
1631 @code{aclocal} programs also understands @code{AC_REQUIRE}, so it is
1632 safe to put each macro in a separate file. @xref{Prerequisite Macros, ,
1633 , autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
1634 autoconf, The Autoconf Manual}.
1636 A macro file's name should end in @file{.m4}. Such files should be
1637 installed in @code{`aclocal --print-ac-dir`} (which usually happens to
1638 be @file{$(datadir)/aclocal}).
1641 @node Top level, Alternative, configure, Top
1642 @chapter The top-level @file{Makefile.am}
1644 @cindex SUBDIRS, explained
1646 In packages with subdirectories, the top level @file{Makefile.am} must
1647 tell Automake which subdirectories are to be built. This is done via
1648 the @code{SUBDIRS} variable.
1651 The @code{SUBDIRS} variable holds a list of subdirectories in which
1652 building of various sorts can occur. Many targets (e.g. @code{all}) in
1653 the generated @file{Makefile} will run both locally and in all specified
1654 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1655 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1656 (after configuration). This allows inclusion of libraries from packages
1657 which do not use Automake (such as @code{gettext}). The directories
1658 mentioned in @code{SUBDIRS} must be direct children of the current
1659 directory. For instance, you cannot put @samp{src/subdir} into
1662 In packages that use subdirectories, the top-level @file{Makefile.am} is
1663 often very short. For instance, here is the @file{Makefile.am} from the
1664 GNU Hello distribution:
1667 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1668 SUBDIRS = doc intl po src tests
1671 @cindex SUBDIRS, overriding
1672 @cindex Overriding SUBDIRS
1674 It is possible to override the @code{SUBDIRS} variable if, like in the
1675 case of GNU @code{Inetutils}, you want to only build a subset of the
1676 entire package. In your @file{Makefile.am} include:
1679 SUBDIRS = @@MY_SUBDIRS@@
1682 Then in your @file{configure.in} you can specify:
1685 MY_SUBDIRS="src doc lib po"
1686 AC_SUBST(MY_SUBDIRS)
1689 (Note that we don't use the variable name @code{SUBDIRS} in our
1690 @file{configure.in}; that would cause Automake to believe that every
1691 @file{Makefile.in} should recurse into the listed subdirectories.)
1693 The upshot of this is that Automake is tricked into building the package
1694 to take the subdirs, but doesn't actually bind that list until
1695 @code{configure} is run.
1697 Although the @code{SUBDIRS} variable can contain configure substitutions
1698 (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
1699 contents of this variable.
1701 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1702 @code{AC_PROG_MAKE_SET}. When Automake invokes @code{make} in a
1703 subdirectory, it uses the value of the @code{MAKE} variable. It passes
1704 the value of the variable @code{AM_MAKEFLAGS} to the @code{make}
1705 invocation; this can be set in @file{Makefile.am} if there are flags you
1706 must always pass to @code{make}.
1710 The use of @code{SUBDIRS} is not restricted to just the top-level
1711 @file{Makefile.am}. Automake can be used to construct packages of
1714 By default, Automake generates @file{Makefiles} which work depth-first
1715 (@samp{postfix}). However, it is possible to change this ordering. You
1716 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
1717 putting @samp{.} first will cause a @samp{prefix} ordering of
1718 directories. All @samp{clean} targets are run in reverse order of build
1721 Sometimes, such as when running @code{make dist}, you want all possible
1722 subdirectories to be examined. In this case Automake will use
1723 @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to
1724 recurse. This variable will also be used when the user runs
1725 @code{distclean} or @code{maintainer-clean}. It should be set to the
1726 full list of subdirectories in the project. If this variable is not set,
1727 Automake will attempt to set it for you.
1730 @node Alternative, Rebuilding, Top level, Top
1731 @chapter An Alternative Approach to Subdirectories
1733 If you've ever read Peter Miller's excellent paper,
1734 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
1735 Recursive Make Considered Harmful}, the preceding section on the use of
1736 subdirectories will probably come as unwelcome advice. For those who
1737 haven't read the paper, Miller's main thesis is that recursive
1738 @code{make} invocations are both slow and error-prone.
1740 Automake provides sufficient cross-directory support @footnote{We
1741 believe. This work is new and there are probably warts.
1742 @xref{Introduction}, for information on reporting bugs.} to enable you
1743 to write a single @file{Makefile.am} for a complex multi-directory
1747 By default an installable file specified in a subdirectory will have its
1748 directory name stripped before installation. For instance, in this
1749 example, the header file will be installed as
1750 @file{$(includedir)/stdio.h}:
1753 include_HEADERS = inc/stdio.h
1757 @cindex Path stripping, avoiding
1758 @cindex Avoiding path stripping
1760 However, the @samp{nobase_} prefix can be used to circumvent this path
1761 stripping. In this example, the header file will be installed as
1762 @file{$(includedir)/sys/types.h}:
1765 nobase_include_HEADERS = sys/types.h
1768 @cindex nobase_ and dist_ or nodist_
1769 @cindex dist_ and nobase_
1770 @cindex nodist_ and nobase_
1772 @samp{nobase_} should be specified first when used in conjonction with
1773 either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
1776 nobase_dist_pkgdata_DATA = images/vortex.pgm
1779 @node Rebuilding, Programs, Alternative, Top
1780 @chapter Rebuilding Makefiles
1782 Automake generates rules to automatically rebuild @file{Makefile}s,
1783 @file{configure}, and other derived files like @file{Makefile.in}.
1785 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.in}, then
1786 these automatic rebuilding rules are only enabled in maintainer mode.
1788 Sometimes you need to run @code{aclocal} with an argument like @code{-I}
1789 to tell it where to find @file{.m4} files. Since sometimes @code{make}
1790 will automatically run @code{aclocal}, you need a way to specify these
1791 arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this
1792 holds arguments which are passed verbatim to @code{aclocal}. This variable
1793 is only useful in the top-level @file{Makefile.am}.
1794 @vindex ACLOCAL_AMFLAGS
1797 @node Programs, Other objects, Rebuilding, Top
1798 @chapter Building Programs and Libraries
1800 A large part of Automake's functionality is dedicated to making it easy
1801 to build programs and libraries.
1804 * A Program:: Building a program
1805 * A Library:: Building a library
1806 * A Shared Library:: Building a Libtool library
1807 * Program and Library Variables:: Variables controlling program and
1809 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1810 * Program variables:: Variables used when building a program
1811 * Yacc and Lex:: Yacc and Lex support
1813 * Assembly Support::
1814 * Fortran 77 Support::
1816 * Support for Other Languages::
1817 * ANSI:: Automatic de-ANSI-fication
1818 * Dependencies:: Automatic dependency tracking
1819 * EXEEXT:: Support for executable extensions
1823 @node A Program, A Library, Programs, Programs
1824 @section Building a program
1826 In order to build a program, you need to tell Automake which sources
1827 are part of it, and which libraries it should be linked with.
1829 This section also covers conditional compilation of sources or
1830 programs. Most of the comments about these also apply to libraries
1831 (@pxref{A Library}) and Libtool libraries (@pxref{A Shared Library}).
1834 * Program Sources:: Defining program sources
1835 * Linking:: Linking with libraries or extra objects
1836 * Conditional Sources:: Handling conditional sources
1837 * Conditional Programs:: Building program conditionally
1840 @node Program Sources, Linking, A Program, A Program
1841 @subsection Defining program sources
1843 @cindex PROGRAMS, bindir
1844 @vindex bin_PROGRAMS
1845 @vindex sbin_PROGRAMS
1846 @vindex libexec_PROGRAMS
1847 @vindex pkglib_PROGRAMS
1848 @vindex noinst_PROGRAMS
1849 @vindex check_PROGRAMS
1851 In a directory containing source that gets built into a program (as
1852 opposed to a library or a script), the @samp{PROGRAMS} primary is used.
1853 Programs can be installed in @code{bindir}, @code{sbindir},
1854 @code{libexecdir}, @code{pkglibdir}, or not at all (@samp{noinst}).
1855 They can also be built only for @code{make check}, in which case the
1856 prefix is @samp{check}.
1861 bin_PROGRAMS = hello
1864 In this simple case, the resulting @file{Makefile.in} will contain code
1865 to generate a program named @code{hello}.
1867 Associated with each program are several assisting variables which are
1868 named after the program. These variables are all optional, and have
1869 reasonable defaults. Each variable, its use, and default is spelled out
1870 below; we use the ``hello'' example throughout.
1872 The variable @code{hello_SOURCES} is used to specify which source files
1873 get built into an executable:
1876 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1879 This causes each mentioned @samp{.c} file to be compiled into the
1880 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1882 @cindex _SOURCES primary, defined
1883 @cindex SOURCES primary, defined
1884 @cindex Primary variable, SOURCES
1886 If @samp{hello_SOURCES} is not specified, then it defaults to the single
1887 file @file{hello.c}; that is, the default is to compile a single C file
1888 whose base name is the name of the program itself. (This is a terrible
1889 default but we are stuck with it for historical reasons.)
1893 Multiple programs can be built in a single directory. Multiple programs
1894 can share a single source file, which must be listed in each
1895 @samp{_SOURCES} definition.
1897 @cindex Header files in _SOURCES
1898 @cindex _SOURCES and header files
1900 Header files listed in a @samp{_SOURCES} definition will be included in
1901 the distribution but otherwise ignored. In case it isn't obvious, you
1902 should not include the header file generated by @file{configure} in a
1903 @samp{_SOURCES} variable; this file should not be distributed. Lex
1904 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1908 @node Linking, Conditional Sources, Program Sources, A Program
1909 @subsection Linking the program
1911 If you need to link against libraries that are not found by
1912 @code{configure}, you can use @code{LDADD} to do so. This variable is
1913 used to specify additional objects or libraries to link with; it is
1914 inappropriate for specifying specific linker flags, you should use
1915 @code{AM_LDFLAGS} for this purpose.
1919 @cindex prog_LDADD, defined
1921 Sometimes, multiple programs are built in one directory but do not share
1922 the same link-time requirements. In this case, you can use the
1923 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1924 program as it appears in some @samp{_PROGRAMS} variable, and usually
1925 written in lowercase) to override the global @code{LDADD}. If this
1926 variable exists for a given program, then that program is not linked
1930 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
1931 linked against the library @file{libcpio.a}. However, @code{rmt} is
1932 built in the same directory, and has no such link requirement. Also,
1933 @code{mt} and @code{rmt} are only built on certain architectures. Here
1934 is what cpio's @file{src/Makefile.am} looks like (abridged):
1937 bin_PROGRAMS = cpio pax @@MT@@
1938 libexec_PROGRAMS = @@RMT@@
1939 EXTRA_PROGRAMS = mt rmt
1941 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1944 cpio_SOURCES = @dots{}
1945 pax_SOURCES = @dots{}
1946 mt_SOURCES = @dots{}
1947 rmt_SOURCES = @dots{}
1950 @cindex _LDFLAGS, defined
1952 @samp{@var{prog}_LDADD} is inappropriate for passing program-specific
1953 linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
1954 @samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
1958 @cindex _DEPENDENCIES, defined
1960 It is also occasionally useful to have a program depend on some other
1961 target which is not actually part of that program. This can be done
1962 using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
1963 on the contents of such a variable, but no further interpretation is
1966 If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
1967 Automake. The automatically-assigned value is the contents of
1968 @samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
1969 @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
1970 configure substitutions that are left in are only @samp{@@LIBOBJS@@} and
1971 @samp{@@ALLOCA@@}; these are left because it is known that they will not
1972 cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
1976 @node Conditional Sources, Conditional Programs, Linking, A Program
1977 @subsection Conditional compilation of sources
1979 You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
1980 @samp{_SOURCES} variable. The reason for this is a bit hard to explain,
1981 but suffice to say that it simply won't work. Automake will give an
1982 error if you try to do this.
1984 Fortunatly there are two other ways to achieve the same result. One is
1985 to use configure substitutions in @code{_LDADD} variables, the other is
1986 to use an Automake conditional.
1988 @subsubsection Conditional compilation using @code{_LDADD} substitutions
1990 @cindex EXTRA_prog_SOURCES, defined
1992 Automake must know all the source files that could possibly go into a
1993 program, even if not all the files are built in every circumstance. Any
1994 files which are only conditionally built should be listed in the
1995 appropriate @samp{EXTRA_} variable. For instance, if
1996 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
1997 in @code{hello}, the @file{Makefile.am} would contain:
2000 bin_PROGRAMS = hello
2001 hello_SOURCES = hello-common.c
2002 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
2003 hello_LDADD = @@HELLO_SYSTEM@@
2004 hello_DEPENDENCIES = @@HELLO_SYSTEM@@
2008 You can then setup the @code{@@HELLO_SYSTEM@@} substitution from
2009 @file{configure.in}:
2014 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
2015 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
2017 AC_SUBST([HELLO_SYSTEM])
2021 In this case, @code{HELLO_SYSTEM} should be replaced by
2022 @file{hello-linux.o} or @file{hello-bsd.o}, and added to
2023 @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be built
2026 @subsubsection Conditional compilation using Automake conditionals
2028 An often simpler way to compile source files conditionally is to use
2029 Automake conditionals. For instance, you could use this
2030 @file{Makefile.am} construct to build the same @file{hello} example:
2033 bin_PROGRAMS = hello
2035 hello_SOURCES = hello-linux.c hello-common.c
2037 hello_SOURCES = hello-generic.c hello-common.c
2041 In this case, your @file{configure.in} should setup the @code{LINUX}
2042 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
2044 When using conditionals like this you don't need to use the
2045 @samp{EXTRA_} variable, because Automake will examine the contents of
2046 each variable to construct the complete list of source files.
2048 If your program uses a lot of files, you will probably prefer a
2049 conditional @code{+=}.
2052 bin_PROGRAMS = hello
2053 hello_SOURCES = hello-common.c
2055 hello_cond += hello-linux.c
2057 hello_cond += hello-generic.c
2061 @node Conditional Programs, , Conditional Sources, A Program
2062 @subsection Conditional compilation of programs
2064 Sometimes it is useful to determine the programs that are to be built at
2065 configure time. For instance, GNU @code{cpio} only builds @code{mt} and
2066 @code{rmt} under special circumstances.
2068 @cindex EXTRA_PROGRAMS, defined
2070 In this case, you must notify Automake of all the programs that can
2071 possibly be built, but at the same time cause the generated
2072 @file{Makefile.in} to use the programs specified by @code{configure}.
2073 This is done by having @code{configure} substitute values into each
2074 @samp{_PROGRAMS} definition, while listing all optionally built programs
2075 in @code{EXTRA_PROGRAMS}.
2076 @vindex EXTRA_PROGRAMS
2078 Of course you can use Automake conditionals to determine the programs to
2082 @node A Library, A Shared Library, A Program, Programs
2083 @section Building a library
2085 @cindex _LIBRARIES primary, defined
2086 @cindex LIBRARIES primary, defined
2087 @cindex Primary variable, LIBRARIES
2089 @vindex lib_LIBRARIES
2090 @vindex pkglib_LIBRARIES
2091 @vindex noinst_LIBRARIES
2093 Building a library is much like building a program. In this case, the
2094 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
2095 @code{libdir} or @code{pkglibdir}.
2097 @xref{A Shared Library}, for information on how to build shared
2098 libraries using Libtool and the @samp{LTLIBRARIES} primary.
2100 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
2101 For instance to create a library named @file{libcpio.a}, but not install
2102 it, you would write:
2105 noinst_LIBRARIES = libcpio.a
2108 The sources that go into a library are determined exactly as they are
2109 for programs, via the @samp{_SOURCES} variables. Note that the library
2110 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
2111 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
2112 not @samp{liblob.a_SOURCES}.
2114 @cindex _LIBADD primary, defined
2115 @cindex LIBADD primary, defined
2116 @cindex Primary variable, LIBADD
2118 Extra objects can be added to a library using the
2119 @samp{@var{library}_LIBADD} variable. This should be used for objects
2120 determined by @code{configure}. Again from @code{cpio}:
2125 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
2128 In addition, sources for extra objects that will not exist until
2129 configure-time must be added to the @code{BUILT_SOURCES} variable
2133 @node A Shared Library, Program and Library Variables, A Library, Programs
2134 @section Building a Shared Library
2136 @cindex Shared libraries, support for
2138 Building shared libraries is a relatively complex matter. For this
2139 reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
2140 Libtool Manual}) was created to help build shared libraries in a
2141 platform-independent way.
2143 @cindex _LTLIBRARIES primary, defined
2144 @cindex LTLIBRARIES primary, defined
2145 @cindex Primary variable, LTLIBRARIES
2146 @cindex Example of shared libraries
2148 @cindex suffix .la, defined
2150 Automake uses Libtool to build libraries declared with the
2151 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
2152 of shared libraries to build. For instance, to create a library named
2153 @file{libgettext.a} and its corresponding shared libraries, and install
2154 them in @samp{libdir}, write:
2157 lib_LTLIBRARIES = libgettext.la
2160 @vindex lib_LTLIBRARIES
2161 @vindex pkglib_LTLIBRARIES
2162 @vindex noinst_LTLIBRARIES
2163 @vindex check_LTLIBRARIES
2165 @cindex check_LTLIBRARIES, not allowed
2167 Note that shared libraries @emph{must} be installed in order to work
2168 properly, so @code{check_LTLIBRARIES} is not allowed. However,
2169 @code{noinst_LTLIBRARIES} is allowed. This feature should be used for
2170 libtool ``convenience libraries''.
2172 @cindex suffix .lo, defined
2174 For each library, the @samp{@var{library}_LIBADD} variable contains the
2175 names of extra libtool objects (@file{.lo} files) to add to the shared
2176 library. The @samp{@var{library}_LDFLAGS} variable contains any
2177 additional libtool flags, such as @samp{-version-info} or
2180 @cindex @@LTLIBOBJS@@, special handling
2182 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
2183 library must use @code{@@LTLIBOBJS@@}. This is required because the
2184 object files that libtool operates on do not necessarily end in
2185 @file{.o}. The libtool manual contains more details on this topic.
2187 For libraries installed in some directory, Automake will automatically
2188 supply the appropriate @samp{-rpath} option. However, for libraries
2189 determined at configure time (and thus mentioned in
2190 @code{EXTRA_LTLIBRARIES}), Automake does not know the eventual
2191 installation directory; for such libraries you must add the
2192 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
2195 Ordinarily, Automake requires that a shared library's name start with
2196 @samp{lib}. However, if you are building a dynamically loadable module
2197 then you might wish to use a "nonstandard" name. In this case, put
2198 @code{-module} into the @samp{_LDFLAGS} variable.
2200 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
2201 libtool, The Libtool Manual}, for more information.
2204 @node Program and Library Variables, LIBOBJS, A Shared Library, Programs
2205 @section Program and Library Variables
2207 Associated with each program are a collection of variables which can be
2208 used to modify how that program is built. There is a similar list of
2209 such variables for each library. The canonical name of the program (or
2210 library) is used as a base for naming these variables.
2212 In the list below, we use the name ``maude'' to refer to the program or
2213 library. In your @file{Makefile.am} you would replace this with the
2214 canonical name of your program. This list also refers to ``maude'' as a
2215 program, but in general the same rules apply for both static and dynamic
2216 libraries; the documentation below notes situations where programs and
2221 This variable, if it exists, lists all the source files which are
2222 compiled to build the program. These files are added to the
2223 distribution by default. When building the program, Automake will cause
2224 each source file to be compiled to a single @file{.o} file (or
2225 @file{.lo} when using libtool). Normally these object files are named
2226 after the source file, but other factors can change this. If a file in
2227 the @samp{_SOURCES} variable has an unrecognized extension, Automake
2228 will do one of two things with it. If a suffix rule exists for turning
2229 files with the unrecognized extension into @file{.o} files, then
2230 automake will treat this file as it will any other source file
2231 (@pxref{Support for Other Languages}). Otherwise, the file will be
2232 ignored as though it were a header file.
2234 The prefixes @samp{dist_} and @samp{nodist_} can be used to control
2235 whether files listed in a @samp{_SOURCES} variable are distributed.
2236 @samp{dist_} is redundant, as sources are distributed by default, but it
2237 can be specified for clarity if desired.
2239 It is possible to have both @samp{dist_} and @samp{nodist_} variants of
2240 a given @samp{_SOURCES} variable at once; this lets you easily
2241 distribute some files and not others, for instance:
2244 nodist_maude_SOURCES = nodist.c
2245 dist_maude_SOURCES = dist-me.c
2248 By default the output file (on Unix systems, the @file{.o} file) will be
2249 put into the current build directory. However, if the option
2250 @code{subdir-objects} is in effect in the current directory then the
2251 @file{.o} file will be put into the subdirectory named after the source
2252 file. For instance, with @code{subdir-objects} enabled,
2253 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
2254 people prefer this mode of operation. You can specify
2255 @code{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
2256 @cindex Subdirectory, objects in
2257 @cindex Objects in subdirectory
2260 @item EXTRA_maude_SOURCES
2261 Automake needs to know the list of files you intend to compile
2262 @emph{statically}. For one thing, this is the only way Automake has of
2263 knowing what sort of language support a given @file{Makefile.in}
2264 requires. @footnote{There are other, more obscure reasons reasons for
2265 this limitation as well.} This means that, for example, you can't put a
2266 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
2267 variable. If you intend to conditionally compile source files and use
2268 @file{configure} to substitute the appropriate object names into, e.g.,
2269 @samp{_LDADD} (see below), then you should list the corresponding source
2270 files in the @samp{EXTRA_} variable.
2272 This variable also supports @samp{dist_} and @samp{nodist_} prefixes,
2273 e.g., @samp{nodist_EXTRA_maude_SOURCES}.
2276 A static library is created by default by invoking @code{$(AR) cru}
2277 followed by the name of the library and then the objects being put into
2278 the library. You can override this by setting the @samp{_AR} variable.
2279 This is usually used with C++; some C++ compilers require a special
2280 invocation in order to instantiate all the templates which should go
2281 into a library. For instance, the SGI C++ compiler likes this variable set
2284 libmaude_a_AR = $(CXX) -ar -o
2288 Extra objects can be added to a static library using the @samp{_LIBADD}
2289 variable. This should be used for objects determined by
2290 @code{configure}. Note that @samp{_LIBADD} is not used for shared
2291 libraries; there you must use @samp{_LDADD}.
2294 Extra objects can be added to a shared library or a program by listing
2295 them in the @samp{_LDADD} variable. This should be used for objects
2296 determined by @code{configure}.
2298 @samp{_LDADD} and @samp{_LIBADD} are inappropriate for passing
2299 program-specific linker flags (except for @samp{-l}, @samp{-L},
2300 @samp{-dlopen} and @samp{-dlpreopen}). Use the @samp{_LDFLAGS} variable
2303 For instance, if your @file{configure.in} uses @code{AC_PATH_XTRA}, you
2304 could link your program against the X libraries like so:
2307 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
2311 This variable is used to pass extra flags to the link step of a program
2312 or a shared library.
2315 You can override the linker on a per-program basis. By default the
2316 linker is chosen according to the languages used by the program. For
2317 instance, a program that includes C++ source code would use the C++
2318 compiler to link. The @samp{_LINK} variable must hold the name of a
2319 command which can be passed all the @file{.o} file names as arguments.
2320 Note that the name of the underlying program is @emph{not} passed to
2321 @samp{_LINK}; typically one uses @samp{$@@}:
2324 maude_LINK = $(CCLD) -magic -o $@@
2327 @item maude_CCASFLAGS
2329 @itemx maude_CPPFLAGS
2330 @itemx maude_CXXFLAGS
2332 @itemx maude_GCJFLAGS
2334 @itemx maude_OBJCFLAGS
2337 Automake allows you to set compilation flags on a per-program (or
2338 per-library) basis. A single source file can be included in several
2339 programs, and it will potentially be compiled with different flags for
2340 each program. This works for any language directly supported by
2341 Automake. The flags are
2353 When using a per-program compilation flag, Automake will choose a
2354 different name for the intermediate object files. Ordinarily a file
2355 like @file{sample.c} will be compiled to produce @file{sample.o}.
2356 However, if the program's @samp{_CFLAGS} variable is set, then the
2357 object file will be named, for instance, @file{maude-sample.o}.
2359 In compilations with per-program flags, the ordinary @samp{AM_} form of
2360 the flags variable is @emph{not} automatically included in the
2361 compilation (however, the user form of the variable @emph{is} included).
2362 So for instance, if you want the hypothetical @file{maude} compilations
2363 to also use the value of @samp{AM_CFLAGS}, you would need to write:
2366 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
2370 @item maude_DEPENDENCIES
2371 It is also occasionally useful to have a program depend on some other
2372 target which is not actually part of that program. This can be done
2373 using the @samp{_DEPENDENCIES} variable. Each program depends on the
2374 contents of such a variable, but no further interpretation is done.
2376 If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake.
2377 The automatically-assigned value is the contents of @samp{_LDADD} or
2378 @samp{_LIBADD}, with most configure substitutions, @samp{-l}, @samp{-L},
2379 @samp{-dlopen} and @samp{-dlpreopen} options removed. The configure
2380 substitutions that are left in are only @samp{@@LIBOBJS@@} and
2381 @samp{@@ALLOCA@@}; these are left because it is known that they will not
2382 cause an invalid value for @samp{_DEPENDENCIES} to be generated.
2384 @item maude_SHORTNAME
2385 On some platforms the allowable file names are very short. In order to
2386 support these systems and per-program compilation flags at the same
2387 time, Automake allows you to set a ``short name'' which will influence
2388 how intermediate object files are named. For instance, if you set
2389 @samp{maude_SHORTNAME} to @samp{m}, then in the above per-program
2390 compilation flag example the object file would be named
2391 @file{m-sample.o} rather than @file{maude-sample.o}. This facility is
2392 rarely needed in practice, and we recommend avoiding it until you find
2397 @node LIBOBJS, Program variables, Program and Library Variables, Programs
2398 @section Special handling for LIBOBJS and ALLOCA
2400 @cindex @@LIBOBJS@@, special handling
2401 @cindex @@ALLOCA@@, special handling
2403 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
2404 @code{@@ALLOCA@@}, and uses this information, plus the list of
2405 @code{LIBOBJS} files derived from @file{configure.in} to automatically
2406 include the appropriate source files in the distribution (@pxref{Dist}).
2407 These source files are also automatically handled in the
2408 dependency-tracking scheme; see @xref{Dependencies}.
2410 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
2411 @samp{_LDADD} or @samp{_LIBADD} variable.
2414 @node Program variables, Yacc and Lex, LIBOBJS, Programs
2415 @section Variables used when building a program
2417 Occasionally it is useful to know which @file{Makefile} variables
2418 Automake uses for compilations; for instance you might need to do your
2419 own compilation in some special cases.
2421 Some variables are inherited from Autoconf; these are @code{CC},
2422 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
2431 There are some additional variables which Automake itself defines:
2435 The contents of this variable are passed to every compilation which invokes
2436 the C preprocessor; it is a list of arguments to the preprocessor. For
2437 instance, @samp{-I} and @samp{-D} options should be listed here.
2439 Automake already provides some @samp{-I} options automatically. In
2440 particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I}
2441 pointing to the directory holding @file{config.h} (if you've used
2442 @code{AC_CONFIG_HEADERS} or @code{AM_CONFIG_HEADER}). You can disable
2443 the default @samp{-I} options using the @samp{nostdinc} option.
2445 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
2446 per-library) @code{_CPPFLAGS} variable if it is defined.
2449 This does the same job as @samp{AM_CPPFLAGS}. It is an older name for
2450 the same functionality. This variable is deprecated; we suggest using
2451 @samp{AM_CPPFLAGS} instead.
2454 This is the variable which the @file{Makefile.am} author can use to pass
2455 in additional C compiler flags. It is more fully documented elsewhere.
2456 In some situations, this is not used, in preference to the
2457 per-executable (or per-library) @code{_CFLAGS}.
2460 This is the command used to actually compile a C source file. The
2461 filename is appended to form the complete command line.
2464 This is the variable which the @file{Makefile.am} author can use to pass
2465 in additional linker flags. In some situations, this is not used, in
2466 preference to the per-executable (or per-library) @code{_LDFLAGS}.
2469 This is the command used to actually link a C program. It already
2470 includes @samp{-o $@@} and the usual variable references (for instance,
2471 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
2472 and libraries to link in.
2476 @node Yacc and Lex, C++ Support, Program variables, Programs
2477 @section Yacc and Lex support
2479 Automake has somewhat idiosyncratic support for Yacc and Lex.
2481 Automake assumes that the @file{.c} file generated by @code{yacc} (or
2482 @code{lex}) should be named using the basename of the input file. That
2483 is, for a yacc source file @file{foo.y}, Automake will cause the
2484 intermediate file to be named @file{foo.c} (as opposed to
2485 @file{y.tab.c}, which is more traditional).
2487 The extension of a yacc source file is used to determine the extension
2488 of the resulting @samp{C} or @samp{C++} file. Files with the extension
2489 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
2490 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
2493 Likewise, lex source files can be used to generate @samp{C} or
2494 @samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
2495 @samp{.lxx} are recognized.
2497 You should never explicitly mention the intermediate (@samp{C} or
2498 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
2501 The intermediate files generated by @code{yacc} (or @code{lex}) will be
2502 included in any distribution that is made. That way the user doesn't
2503 need to have @code{yacc} or @code{lex}.
2505 If a @code{yacc} source file is seen, then your @file{configure.in} must
2506 define the variable @samp{YACC}. This is most easily done by invoking
2507 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
2508 Program Checks, autoconf, The Autoconf Manual}).
2510 When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
2511 @samp{AM_YFLAGS}. The former is a user variable and the latter is
2512 intended for the @file{Makefile.am} author.
2514 Similarly, if a @code{lex} source file is seen, then your
2515 @file{configure.in} must define the variable @samp{LEX}. You can use
2516 @samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
2517 Program Checks, autoconf, The Autoconf Manual}), but using
2518 @code{AM_PROG_LEX} macro (@pxref{Macros}) is recommended.
2520 When @code{lex} is invoked, it is passed @samp{LFLAGS} and
2521 @samp{AM_LFLAGS}. The former is a user variable and the latter is
2522 intended for the @file{Makefile.am} author.
2527 @cindex yacc, multiple parsers
2528 @cindex Multiple yacc parsers
2529 @cindex Multiple lex lexers
2530 @cindex lex, multiple lexers
2533 Automake makes it possible to include multiple @code{yacc} (or
2534 @code{lex}) source files in a single program. Automake uses a small
2535 program called @code{ylwrap} to run @code{yacc} (or @code{lex}) in a
2536 subdirectory. This is necessary because yacc's output filename is
2537 fixed, and a parallel make could conceivably invoke more than one
2538 instance of @code{yacc} simultaneously. The @code{ylwrap} program is
2539 distributed with Automake. It should appear in the directory specified
2540 by @samp{AC_CONFIG_AUX_DIR} (@pxref{Input, , Finding `configure' Input,
2541 autoconf, The Autoconf Manual}), or the current directory if that macro
2542 is not used in @file{configure.in}.
2544 For @code{yacc}, simply managing locking is insufficient. The output of
2545 @code{yacc} always uses the same symbol names internally, so it isn't
2546 possible to link two @code{yacc} parsers into the same executable.
2548 We recommend using the following renaming hack used in @code{gdb}:
2550 #define yymaxdepth c_maxdepth
2551 #define yyparse c_parse
2553 #define yyerror c_error
2554 #define yylval c_lval
2555 #define yychar c_char
2556 #define yydebug c_debug
2557 #define yypact c_pact
2564 #define yyexca c_exca
2565 #define yyerrflag c_errflag
2566 #define yynerrs c_nerrs
2570 #define yy_yys c_yys
2571 #define yystate c_state
2574 #define yy_yyv c_yyv
2576 #define yylloc c_lloc
2577 #define yyreds c_reds
2578 #define yytoks c_toks
2579 #define yylhs c_yylhs
2580 #define yylen c_yylen
2581 #define yydefred c_yydefred
2582 #define yydgoto c_yydgoto
2583 #define yysindex c_yysindex
2584 #define yyrindex c_yyrindex
2585 #define yygindex c_yygindex
2586 #define yytable c_yytable
2587 #define yycheck c_yycheck
2588 #define yyname c_yyname
2589 #define yyrule c_yyrule
2592 For each define, replace the @samp{c_} prefix with whatever you like.
2593 These defines work for @code{bison}, @code{byacc}, and traditional
2594 @code{yacc}s. If you find a parser generator that uses a symbol not
2595 covered here, please report the new name so it can be added to the list.
2598 @node C++ Support, Assembly Support, Yacc and Lex, Programs
2599 @section C++ Support
2602 @cindex Support for C++
2604 Automake includes full support for C++.
2606 Any package including C++ code must define the output variable
2607 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
2608 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
2609 Program Checks, autoconf, The Autoconf Manual}).
2611 A few additional variables are defined when a C++ source file is seen:
2615 The name of the C++ compiler.
2618 Any flags to pass to the C++ compiler.
2621 The maintainer's variant of @code{CXXFLAGS}.
2624 The command used to actually compile a C++ source file. The file name
2625 is appended to form the complete command line.
2628 The command used to actually link a C++ program.
2632 @node Assembly Support, Fortran 77 Support, C++ Support, Programs
2633 @section Assembly Support
2635 Automake includes some support for assembly code.
2637 The variable @code{CCAS} holds the name of the compiler used to build
2638 assembly code. This compiler must work a bit like a C compiler; in
2639 particular it must accept @samp{-c} and @samp{-o}. The value of
2640 @code{CCASFLAGS} is passed to the compilation.
2644 You are required to set @code{CCAS} and @code{CCASFLAGS} via
2645 @file{configure.in}. The autoconf macro @code{AM_PROG_AS} will do this
2646 for you. Unless they are already set, it simply sets @code{CCAS} to the
2647 C compiler and @code{CCASFLAGS} to the C compiler flags.
2649 Only the suffixes @samp{.s} and @samp{.S} are recognized by
2650 @code{automake} as being files containing assembly code.
2653 @node Fortran 77 Support, Java Support, Assembly Support, Programs
2654 @comment node-name, next, previous, up
2655 @section Fortran 77 Support
2657 @cindex Fortran 77 support
2658 @cindex Support for Fortran 77
2660 Automake includes full support for Fortran 77.
2662 Any package including Fortran 77 code must define the output variable
2663 @samp{F77} in @file{configure.in}; the simplest way to do this is to use
2664 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
2665 Program Checks, autoconf, The Autoconf Manual}). @xref{Fortran 77 and
2668 A few additional variables are defined when a Fortran 77 source file is
2674 The name of the Fortran 77 compiler.
2677 Any flags to pass to the Fortran 77 compiler.
2680 The maintainer's variant of @code{FFLAGS}.
2683 Any flags to pass to the Ratfor compiler.
2686 The maintainer's variant of @code{RFLAGS}.
2689 The command used to actually compile a Fortran 77 source file. The file
2690 name is appended to form the complete command line.
2693 The command used to actually link a pure Fortran 77 program or shared
2698 Automake can handle preprocessing Fortran 77 and Ratfor source files in
2699 addition to compiling them@footnote{Much, if not most, of the
2700 information in the following sections pertaining to preprocessing
2701 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
2702 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
2703 also contains some support for creating programs and shared libraries
2704 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
2705 Fortran 77 With C and C++}).
2707 These issues are covered in the following sections.
2710 * Preprocessing Fortran 77::
2711 * Compiling Fortran 77 Files::
2712 * Mixing Fortran 77 With C and C++::
2713 * Fortran 77 and Autoconf::
2717 @node Preprocessing Fortran 77, Compiling Fortran 77 Files, Fortran 77 Support, Fortran 77 Support
2718 @comment node-name, next, previous, up
2719 @subsection Preprocessing Fortran 77
2721 @cindex Preprocessing Fortran 77
2722 @cindex Fortran 77, Preprocessing
2723 @cindex Ratfor programs
2725 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
2726 rule runs just the preprocessor to convert a preprocessable Fortran 77
2727 or Ratfor source file into a strict Fortran 77 source file. The precise
2728 command used is as follows:
2733 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2736 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2741 @node Compiling Fortran 77 Files, Mixing Fortran 77 With C and C++, Preprocessing Fortran 77, Fortran 77 Support
2742 @comment node-name, next, previous, up
2743 @subsection Compiling Fortran 77 Files
2745 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
2746 @file{N.r} by running the Fortran 77 compiler. The precise command used
2752 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
2755 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2758 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2763 @node Mixing Fortran 77 With C and C++, Fortran 77 and Autoconf, Compiling Fortran 77 Files, Fortran 77 Support
2764 @comment node-name, next, previous, up
2765 @subsection Mixing Fortran 77 With C and C++
2767 @cindex Fortran 77, mixing with C and C++
2768 @cindex Mixing Fortran 77 with C and C++
2769 @cindex Linking Fortran 77 with C and C++
2771 @cindex Mixing Fortran 77 with C and/or C++
2773 Automake currently provides @emph{limited} support for creating programs
2774 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
2775 However, there are many other issues related to mixing Fortran 77 with
2776 other languages that are @emph{not} (currently) handled by Automake, but
2777 that are handled by other packages@footnote{For example,
2778 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
2779 addresses all of these inter-language issues, and runs under nearly all
2780 Fortran 77, C and C++ compilers on nearly all platforms. However,
2781 @code{cfortran} is not yet Free Software, but it will be in the next
2785 Automake can help in two ways:
2789 Automatic selection of the linker depending on which combinations of
2793 Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
2794 @samp{-l}) to pass to the automatically selected linker in order to link
2795 in the appropriate Fortran 77 intrinsic and run-time libraries.
2797 @cindex FLIBS, defined
2798 These extra Fortran 77 linker flags are supplied in the output variable
2799 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
2800 supplied with newer versions of Autoconf (Autoconf version 2.13 and
2801 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
2805 If Automake detects that a program or shared library (as mentioned in
2806 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
2807 code that is a mixture of Fortran 77 and C and/or C++, then it requires
2808 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
2809 @file{configure.in}, and that either @code{$(FLIBS)} or @code{@@FLIBS@@}
2810 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
2811 (for shared libraries) variables. It is the responsibility of the
2812 person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
2813 or @code{@@FLIBS@@} appears in the appropriate @code{_LDADD} or
2814 @code{_LIBADD} variable.
2816 @cindex Mixed language example
2817 @cindex Example, mixed language
2819 For example, consider the following @file{Makefile.am}:
2823 foo_SOURCES = main.cc foo.f
2824 foo_LDADD = libfoo.la @@FLIBS@@
2826 pkglib_LTLIBRARIES = libfoo.la
2827 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
2828 libfoo_la_LIBADD = $(FLIBS)
2831 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
2832 is mentioned in @file{configure.in}. Also, if @code{@@FLIBS@@} hadn't
2833 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
2834 Automake would have issued a warning.
2839 * How the Linker is Chosen::
2842 @node How the Linker is Chosen, , Mixing Fortran 77 With C and C++, Mixing Fortran 77 With C and C++
2843 @comment node-name, next, previous, up
2844 @subsubsection How the Linker is Chosen
2846 @cindex Automatic linker selection
2847 @cindex Selecting the linker automatically
2849 The following diagram demonstrates under what conditions a particular
2850 linker is chosen by Automake.
2852 For example, if Fortran 77, C and C++ source code were to be compiled
2853 into a program, then the C++ linker will be used. In this case, if the
2854 C or Fortran 77 linkers required any special libraries that weren't
2855 included by the C++ linker, then they must be manually added to an
2856 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
2862 code \ C C++ Fortran
2863 ----------------- +---------+---------+---------+
2867 +---------+---------+---------+
2871 +---------+---------+---------+
2875 +---------+---------+---------+
2879 +---------+---------+---------+
2881 C + Fortran | | | x |
2883 +---------+---------+---------+
2885 C++ + Fortran | | x | |
2887 +---------+---------+---------+
2889 C + C++ + Fortran | | x | |
2891 +---------+---------+---------+
2895 @node Fortran 77 and Autoconf, , Mixing Fortran 77 With C and C++, Fortran 77 Support
2896 @comment node-name, next, previous, up
2897 @subsection Fortran 77 and Autoconf
2899 The current Automake support for Fortran 77 requires a recent enough
2900 version of Autoconf that also includes support for Fortran 77. Full
2901 Fortran 77 support was added to Autoconf 2.13, so you will want to use
2902 that version of Autoconf or later.
2905 @node Java Support, Support for Other Languages, Fortran 77 Support, Programs
2906 @comment node-name, next, previous, up
2907 @section Java Support
2909 @cindex Java support
2910 @cindex Support for Java
2912 Automake includes support for compiled Java, using @code{gcj}, the Java
2913 front end to the GNU Compiler Collection.
2915 Any package including Java code to be compiled must define the output
2916 variable @samp{GCJ} in @file{configure.in}; the variable @samp{GCJFLAGS}
2917 must also be defined somehow (either in @file{configure.in} or
2918 @file{Makefile.am}). The simplest way to do this is to use the
2919 @code{AM_PROG_GCJ} macro.
2923 By default, programs including Java source files are linked with
2926 As always, the contents of @samp{AM_GCJFLAGS} are passed to every
2927 compilation invoking @code{gcj} (in its role as an ahead-of-time
2928 compiler -- when invoking it to create @file{.class} files,
2929 @samp{AM_JAVACFLAGS} is used instead). If it is necessary to pass
2930 options to @code{gcj} from @file{Makefile.am}, this variable, and not
2931 the user variable @samp{GCJFLAGS}, should be used.
2935 @code{gcj} can be used to compile @file{.java}, @file{.class},
2936 @file{.zip}, or @file{.jar} files.
2938 When linking, @code{gcj} requires that the main class be specified
2939 using the @samp{--main=} option. The easiest way to do this is to use
2940 the @code{_LDFLAGS} variable for the program.
2943 @node Support for Other Languages, ANSI, Java Support, Programs
2944 @comment node-name, next, previous, up
2945 @section Support for Other Languages
2947 Automake currently only includes full support for C, C++ (@pxref{C++
2948 Support}), Fortran 77 (@pxref{Fortran 77 Support}), and Java
2949 (@pxref{Java Support}). There is only rudimentary support for other
2950 languages, support for which will be improved based on user demand.
2952 Some limited support for adding your own languages is available via the
2953 suffix rule handling; see @ref{Suffixes}.
2956 @node ANSI, Dependencies, Support for Other Languages, Programs
2957 @section Automatic de-ANSI-fication
2959 @cindex de-ANSI-fication, defined
2961 Although the GNU standards allow the use of ANSI C, this can have the
2962 effect of limiting portability of a package to some older compilers
2963 (notably the SunOS C compiler).
2965 Automake allows you to work around this problem on such machines by
2966 @dfn{de-ANSI-fying} each source file before the actual compilation takes
2969 @vindex AUTOMAKE_OPTIONS
2972 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
2973 (@pxref{Options}) contains the option @code{ansi2knr} then code to
2974 handle de-ANSI-fication is inserted into the generated
2977 This causes each C source file in the directory to be treated as ANSI C.
2978 If an ANSI C compiler is available, it is used. If no ANSI C compiler
2979 is available, the @code{ansi2knr} program is used to convert the source
2980 files into K&R C, which is then compiled.
2982 The @code{ansi2knr} program is simple-minded. It assumes the source
2983 code will be formatted in a particular way; see the @code{ansi2knr} man
2986 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
2987 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
2988 these files are distributed with Automake. Also, the package
2989 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}
2991 @cvindex AM_C_PROTOTYPES
2993 Automake also handles finding the @code{ansi2knr} support files in some
2994 other directory in the current package. This is done by prepending the
2995 relative path to the appropriate directory to the @code{ansi2knr}
2996 option. For instance, suppose the package has ANSI C code in the
2997 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
2998 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
2999 @file{src/Makefile.am}:
3002 AUTOMAKE_OPTIONS = ../lib/ansi2knr
3005 If no directory prefix is given, the files are assumed to be in the
3008 Files mentioned in @code{LIBOBJS} which need de-ANSI-fication will not
3009 be automatically handled. That's because @code{configure} will generate
3010 an object name like @file{regex.o}, while @code{make} will be looking
3011 for @file{regex_.o} (when de-ANSI-fying). Eventually this problem will
3012 be fixed via @code{autoconf} magic, but for now you must put this code
3013 into your @file{configure.in}, just before the @code{AC_OUTPUT} call:
3016 # This is necessary so that .o files in LIBOBJS are also built via
3017 # the ANSI2KNR-filtering rules.
3018 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
3020 @c FIXME: Ask Akim how this should be handled in the upcoming Autoconf.
3022 Note that automatic de-ANSI-fication will not work when the package is
3023 being built for a different host architecture. That is because automake
3024 currently has no way to build @code{ansi2knr} for the build machine.
3027 @node Dependencies, EXEEXT, ANSI, Programs
3028 @section Automatic dependency tracking
3030 As a developer it is often painful to continually update the
3031 @file{Makefile.in} whenever the include-file dependencies change in a
3032 project. Automake supplies a way to automatically track dependency
3035 @cindex Dependency tracking
3036 @cindex Automatic dependency tracking
3038 Automake always uses complete dependencies for a compilation, including
3039 system headers. Automake's model is that dependency computation should
3040 be a side effect of the build. To this end, dependencies are computed
3041 by running all compilations through a special wrapper program called
3042 @code{depcomp}. @code{depcomp} understands how to coax many different C
3043 and C++ compilers into generating dependency information in the format
3044 it requires. @code{automake -a} will install @code{depcomp} into your
3045 source tree for you. If @code{depcomp} can't figure out how to properly
3046 invoke your compiler, dependency tracking will simply be disabled for
3051 Experience with earlier versions of Automake @footnote{See
3052 @uref{http://sources.redhat.com/automake/dependencies.html} for more
3053 information on the history and experiences with automatic dependency
3054 tracking in Automake} taught us that it is not reliable to generate
3055 dependencies only on the maintainer's system, as configurations vary too
3056 much. So instead Automake implements dependency tracking at build time.
3058 Automatic dependency tracking can be suppressed by putting
3059 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
3060 passing @code{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
3061 (this should be the prefered way). Or, you can invoke @code{automake}
3062 with the @code{-i} option. Dependency tracking is enabled by default.
3064 @vindex AUTOMAKE_OPTIONS
3065 @opindex no-dependencies
3067 The person building your package also can choose to disable dependency
3068 tracking by configuring with @code{--disable-dependency-tracking}.
3070 @cindex Disabling dependency tracking
3071 @cindex Dependency tracking, disabling
3074 @node EXEEXT, , Dependencies, Programs
3075 @section Support for executable extensions
3077 @cindex Executable extension
3078 @cindex Extension, executable
3081 On some platforms, such as Windows, executables are expected to have an
3082 extension such as @samp{.exe}. On these platforms, some compilers (GCC
3083 among them) will automatically generate @file{foo.exe} when asked to
3084 generate @file{foo}.
3086 Automake provides mostly-transparent support for this. Unfortunately
3087 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
3088 dictionary is revised, you will have to assist Automake if your package
3089 must support those platforms.
3091 One thing you must be aware of is that, internally, Automake rewrites
3092 something like this:
3095 bin_PROGRAMS = liver
3101 bin_PROGRAMS = liver$(EXEEXT)
3104 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
3105 extension. @code{EXEEXT}
3107 However, Automake cannot apply this rewriting to @code{configure}
3108 substitutions. This means that if you are conditionally building a
3109 program using such a substitution, then your @file{configure.in} must
3110 take care to add @samp{$(EXEEXT)} when constructing the output variable.
3112 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
3113 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
3114 automatically if you configure a compiler (say, through
3117 Sometimes maintainers like to write an explicit link rule for their
3118 program. Without executable extension support, this is easy---you
3119 simply write a target with the same name as the program. However, when
3120 executable extension support is enabled, you must instead add the
3121 @samp{$(EXEEXT)} suffix.
3123 Unfortunately, due to the change in Autoconf 2.50, this means you must
3124 always add this extension. However, this is a problem for maintainers
3125 who know their package will never run on a platform that has executable
3126 extensions. For those maintainers, the @code{no-exeext} option
3127 (@pxref{Options}) will disable this feature. This works in a fairly
3128 ugly way; if @code{no-exeext} is seen, then the presence of a target
3129 named @code{foo} in @file{Makefile.am} will override an
3130 automake-generated target of the form @code{foo$(EXEEXT)}. Without the
3131 @code{no-exeext} option, this use will give an error.
3134 @node Other objects, Other GNU Tools, Programs, Top
3135 @chapter Other Derived Objects
3137 Automake can handle derived objects which are not C programs. Sometimes
3138 the support for actually building such objects must be explicitly
3139 supplied, but Automake will still automatically handle installation and
3143 * Scripts:: Executable scripts
3144 * Headers:: Header files
3145 * Data:: Architecture-independent data files
3146 * Sources:: Derived sources
3150 @node Scripts, Headers, Other objects, Other objects
3151 @section Executable Scripts
3153 @cindex _SCRIPTS primary, defined
3154 @cindex SCRIPTS primary, defined
3155 @cindex Primary variable, SCRIPTS
3157 It is possible to define and install programs which are scripts. Such
3158 programs are listed using the @samp{SCRIPTS} primary name. Automake
3159 doesn't define any dependencies for scripts; the @file{Makefile.am}
3160 should include the appropriate rules.
3163 Automake does not assume that scripts are derived objects; such objects
3164 must be deleted by hand (@pxref{Clean}).
3166 The @code{automake} program itself is a Perl script that is generated at
3167 configure time from @file{automake.in}. Here is how this is handled:
3170 bin_SCRIPTS = automake
3173 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
3174 for it is automatically generated, and it is also automatically cleaned
3175 (despite the fact it's a script).
3177 @cindex SCRIPTS, installation directories
3178 @cindex Installing scripts
3181 @vindex sbin_SCRIPTS
3182 @vindex libexec_SCRIPTS
3183 @vindex pkgdata_SCRIPTS
3184 @vindex noinst_SCRIPTS
3185 @vindex check_SCRIPTS
3187 Script objects can be installed in @code{bindir}, @code{sbindir},
3188 @code{libexecdir}, or @code{pkgdatadir}.
3190 Scripts that need not being installed can be listed in
3191 @code{noinst_SCRIPTS}, and among them, those which are needed only by
3192 @code{make check} should go in @code{check_SCRIPTS}.
3195 @node Headers, Data, Scripts, Other objects
3196 @section Header files
3198 @cindex _HEADERS primary, defined
3199 @cindex HEADERS primary, defined
3200 @cindex Primary variable, HEADERS
3202 @vindex noinst_HEADERS
3204 Header files are specified by the @samp{HEADERS} family of variables.
3205 Generally header files are not installed, so the @code{noinst_HEADERS}
3206 variable will be the most used. @footnote{However, for the case of a
3207 non-installed header file that is actually used by a particular program,
3208 we recommend listing it in the program's @samp{_SOURCES} variable
3209 instead of in @code{noinst_HEADERS}. We believe this is more clear.}
3212 All header files must be listed somewhere; missing ones will not appear
3213 in the distribution. Often it is clearest to list uninstalled headers
3214 with the rest of the sources for a program. @xref{A Program}. Headers
3215 listed in a @samp{_SOURCES} variable need not be listed in any
3216 @samp{_HEADERS} variable.
3218 @cindex HEADERS, installation directories
3219 @cindex Installing headers
3221 @vindex include_HEADERS
3222 @vindex oldinclude_HEADERS
3223 @vindex pkginclude_HEADERS
3225 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
3226 @code{pkgincludedir}.
3229 @node Data, Sources, Headers, Other objects
3230 @section Architecture-independent data files
3232 @cindex _DATA primary, defined
3233 @cindex DATA primary, defined
3234 @cindex Primary variable, DATA
3236 Automake supports the installation of miscellaneous data files using the
3237 @samp{DATA} family of variables.
3241 @vindex sysconf_DATA
3242 @vindex sharedstate_DATA
3243 @vindex localstate_DATA
3244 @vindex pkgdata_DATA
3246 Such data can be installed in the directories @code{datadir},
3247 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
3250 By default, data files are @emph{not} included in a distribution. Of
3251 course, you can use the @samp{dist_} prefix to change this on a
3254 Here is how Automake declares its auxiliary data files:
3257 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
3261 @node Sources, , Data, Other objects
3262 @section Built sources
3264 @cindex BUILT_SOURCES, defined
3266 Occasionally a file which would otherwise be called @samp{source}
3267 (e.g. a C @samp{.h} file) is actually derived from some other file.
3268 Such files should be listed in the @code{BUILT_SOURCES} variable.
3269 @vindex BUILT_SOURCES
3271 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
3272 must be created early in the build process can be listed in this
3275 A source file listed in @code{BUILT_SOURCES} is created before the other
3276 @code{all} targets are made. However, such a source file is not
3277 compiled unless explicitly requested by mentioning it in some other
3278 @samp{_SOURCES} variable.
3280 So, for instance, if you had header files which were created by a script
3281 run at build time, then you would list these headers in
3282 @code{BUILT_SOURCES}, to ensure that they would be built before any
3283 other compilations (perhaps ones using these headers) were started.
3286 @node Other GNU Tools, Documentation, Other objects, Top
3287 @chapter Other GNU Tools
3289 Since Automake is primarily intended to generate @file{Makefile.in}s for
3290 use in GNU programs, it tries hard to interoperate with other GNU tools.
3293 * Emacs Lisp:: Emacs Lisp
3301 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
3304 @cindex _LISP primary, defined
3305 @cindex LISP primary, defined
3306 @cindex Primary variable, LISP
3312 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
3313 is used to hold a list of @file{.el} files. Possible prefixes for this
3314 primary are @samp{lisp_} and @samp{noinst_}. Note that if
3315 @code{lisp_LISP} is defined, then @file{configure.in} must run
3316 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
3320 By default Automake will byte-compile all Emacs Lisp source files using
3321 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
3322 byte-compiling, simply define the variable @code{ELCFILES} to be empty.
3323 Byte-compiled Emacs Lisp files are not portable among all versions of
3324 Emacs, so it makes sense to turn this off if you expect sites to have
3325 more than one version of Emacs installed. Furthermore, many packages
3326 don't actually benefit from byte-compilation. Still, we recommend that
3327 you leave it enabled by default. It is probably better for sites with
3328 strange setups to cope for themselves than to make the installation less
3329 nice for everybody else.
3332 @node gettext, Libtool, Emacs Lisp, Other GNU Tools
3335 @cindex GNU Gettext support
3336 @cindex Gettext support
3337 @cindex Support for GNU Gettext
3339 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
3340 turns on support for GNU gettext, a message catalog system for
3341 internationalization
3342 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
3344 The @code{gettext} support in Automake requires the addition of two
3345 subdirectories to the package, @file{intl} and @file{po}. Automake
3346 insures that these directories exist and are mentioned in
3350 @node Libtool, Java, gettext, Other GNU Tools
3353 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
3354 libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
3355 @xref{A Shared Library}.
3358 @node Java, Python, Libtool, Other GNU Tools
3361 @cindex _JAVA primary, defined
3362 @cindex JAVA primary, defined
3363 @cindex Primary variable, JAVA
3365 Automake provides some minimal support for Java compilation with the
3366 @samp{JAVA} primary.
3368 Any @file{.java} files listed in a @samp{_JAVA} variable will be
3369 compiled with @code{JAVAC} at build time. By default, @file{.class}
3370 files are not included in the distribution.
3372 @cindex JAVA restrictions
3373 @cindex Restrictions for JAVA
3375 Currently Automake enforces the restriction that only one @samp{_JAVA}
3376 primary can be used in a given @file{Makefile.am}. The reason for this
3377 restriction is that, in general, it isn't possible to know which
3378 @file{.class} files were generated from which @file{.java} files -- so
3379 it would be impossible to know which files to install where. For
3380 instance, a @file{.java} file can define multiple classes; the resulting
3381 @file{.class} file names cannot be predicted without parsing the
3384 There are a few variables which are used when compiling Java sources:
3388 The name of the Java compiler. This defaults to @samp{javac}.
3391 The flags to pass to the compiler. This is considered to be a user
3392 variable (@pxref{User Variables}).
3395 More flags to pass to the Java compiler. This, and not
3396 @code{JAVACFLAGS}, should be used when it is necessary to put Java
3397 compiler flags into @file{Makefile.am}.
3400 The value of this variable is passed to the @samp{-d} option to
3401 @code{javac}. It defaults to @samp{$(top_builddir)}.
3404 This variable is an @code{sh} expression which is used to set the
3405 @code{CLASSPATH} environment variable on the @code{javac} command line.
3406 (In the future we will probably handle class path setting differently.)
3410 @node Python, , Java, Other GNU Tools
3413 @cindex _PYTHON primary, defined
3414 @cindex PYTHON primary, defined
3415 @cindex Primary variable, PYTHON
3418 Automake provides support for Python compilation with the @samp{PYTHON}
3421 Any files listed in a @samp{_PYTHON} variable will be byte-compiled with
3422 @code{py-compile} at install time. @code{py-compile} actually creates
3423 both standard (@file{.pyc}) and byte-compiled (@file{.pyo}) versions of
3424 the source files. Note that because byte-compilation occurs at install
3425 time, any files listed in @samp{noinst_PYTHON} will not be compiled.
3426 Python source files are included in the distribution by default.
3428 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} which
3429 will determine some Python-related directory variables (see below). If
3430 have called @code{AM_PATH_PYTHON} from you @file{configure.in}, then you
3431 may use the following variables to list you Python source files in your
3432 variables: @samp{python_PYTHON}, @samp{pkgpython_PYTHON},
3433 @samp{pkgpython_PYTHON}, @samp{pyexecdir_PYTHON},
3434 @samp{pkgpyexecdir_PYTHON}, depending where you want your files
3437 @code{AM_PATH_PYTHON} takes a single optional argument. This argument,
3438 if present, is the minimum version of Python which can be used for this
3439 package. If the version of Python found on the system is older than the
3440 required version, then @code{AM_PATH_PYTHON} will cause an error.
3442 @code{AM_PATH_PYTHON} creates several output variables based on the
3443 Python installation found during configuration.
3447 The name of the Python executable.
3449 @item PYTHON_VERSION
3450 The Python version number, in the form @var{major}.@var{minor}
3451 (e.g. @samp{1.5}). This is currently the value of
3452 @code{sys.version[:3]}.
3455 The string @code{$prefix}. This term may be used in future work
3456 which needs the contents of Python's @code{sys.prefix}, but general
3457 consensus is to always use the value from configure.
3459 @item PYTHON_EXEC_PREFIX
3460 The string @code{$exec_prefix}. This term may be used in future work
3461 which needs the contents of Python's @code{sys.exec_prefix}, but general
3462 consensus is to always use the value from configure.
3464 @item PYTHON_PLATFORM
3465 The canonical name used by Python to describe the operating system, as
3466 given by @code{sys.platform}. This value is sometimes needed when
3467 building Python extensions.
3470 The directory name for the @file{site-packages} subdirectory of the
3471 standard Python install tree.
3474 This is is the directory under @code{pythondir} which is named after the
3475 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
3479 This is the directory where Python extension modules (shared libraries)
3480 should be installed.
3483 This is a convenience variable which is defined as
3484 @samp{$(pyexecdir)/$(PACKAGE)}.
3488 @node Documentation, Install, Other GNU Tools, Top
3489 @chapter Building documentation
3491 Currently Automake provides support for Texinfo and man pages.
3495 * Man pages:: Man pages
3499 @node Texinfo, Man pages, Documentation, Documentation
3502 @cindex _TEXINFOS primary, defined
3503 @cindex TEXINFOS primary, defined
3504 @cindex Primary variable, TEXINFOS
3506 If the current directory contains Texinfo source, you must declare it
3507 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
3508 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
3509 here. Any Texinfo source file must end in the @file{.texi},
3510 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
3513 @vindex info_TEXINFOS
3515 Automake generates rules to build @file{.info}, @file{.dvi}, @file{.ps},
3516 and @file{.pdf} files from your Texinfo sources. The @file{.info} files
3517 are built by @code{make all} and installed by @code{make install}
3518 (unless you use @code{no-installinfo}, see below). The other files can
3519 be built on request by @code{make dvi}, @code{make ps}, and @code{make
3522 @cindex Texinfo flag, VERSION
3523 @cindex Texinfo flag, UPDATED
3524 @cindex Texinfo flag, EDITION
3525 @cindex Texinfo flag, UPDATED-MONTH
3527 @cindex VERSION Texinfo flag
3528 @cindex UPDATED Texinfo flag
3529 @cindex EDITION Texinfo flag
3530 @cindex UPDATED-MONTH Texinfo flag
3534 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
3535 that file will be automatically generated. The file @file{version.texi}
3536 defines four Texinfo flag you can reference using
3537 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
3538 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
3543 Both of these flags hold the version number of your program. They are
3544 kept separate for clarity.
3547 This holds the date the primary @file{.texi} file was last modified.
3550 This holds the name of the month in which the primary @file{.texi} file
3554 The @file{version.texi} support requires the @code{mdate-sh} program;
3555 this program is supplied with Automake and automatically included when
3556 @code{automake} is invoked with the @code{--add-missing} option.
3558 If you have multiple Texinfo files, and you want to use the
3559 @file{version.texi} feature, then you have to have a separate version
3560 file for each Texinfo file. Automake will treat any include in a
3561 Texinfo file that matches @samp{vers*.texi} just as an automatically
3562 generated version file.
3564 When an info file is rebuilt, the program named by the @code{MAKEINFO}
3565 variable is used to invoke it. If the @code{makeinfo} program is found
3566 on the system then it will be used by default; otherwise @code{missing}
3567 will be used instead. The flags in the variables @code{MAKEINFOFLAGS}
3568 and @code{AM_MAKEINFOFLAGS} will be passed to the @code{makeinfo}
3569 invocation; the first of these is intended for use by the user
3570 (@pxref{User Variables}) and the second by the @file{Makefile.am}
3573 @vindex MAKEINFOFLAGS
3574 @vindex AM_MAKEINFOFLAGS
3576 Sometimes an info file actually depends on more than one @file{.texi}
3577 file. For instance, in GNU Hello, @file{hello.texi} includes the file
3578 @file{gpl.texi}. You can tell Automake about these dependencies using
3579 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
3584 info_TEXINFOS = hello.texi
3585 hello_TEXINFOS = gpl.texi
3590 By default, Automake requires the file @file{texinfo.tex} to appear in
3591 the same directory as the Texinfo source. However, if you used
3592 @code{AC_CONFIG_AUX_DIR} in @file{configure.in} (@pxref{Input, , Finding
3593 `configure' Input, autoconf, The Autoconf Manual}), then
3594 @file{texinfo.tex} is looked for there. Automake supplies
3595 @file{texinfo.tex} if @samp{--add-missing} is given.
3599 If your package has Texinfo files in many directories, you can use the
3600 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
3601 @file{texinfo.tex} for your package. The value of this variable should
3602 be the relative path from the current @file{Makefile.am} to
3606 TEXINFO_TEX = ../doc/texinfo.tex
3609 @opindex no-texinfo.tex
3611 The option @samp{no-texinfo.tex} can be used to eliminate the
3612 requirement for @file{texinfo.tex}. Use of the variable
3613 @code{TEXINFO_TEX} is preferable, however, because that allows the
3614 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
3616 @cindex Target, install-info
3617 @cindex Target, noinstall-info
3618 @cindex install-info target
3619 @cindex noinstall-info target
3621 @opindex no-installinfo
3622 @trindex install-info
3624 Automake generates an @code{install-info} target; some people apparently
3625 use this. By default, info pages are installed by @samp{make install}.
3626 This can be prevented via the @code{no-installinfo} option.
3629 @node Man pages, , Texinfo, Documentation
3632 @cindex _MANS primary, defined
3633 @cindex MANS primary, defined
3634 @cindex Primary variable, MANS
3636 A package can also include man pages (but see the GNU standards on this
3637 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
3638 pages are declared using the @samp{MANS} primary. Generally the
3639 @code{man_MANS} variable is used. Man pages are automatically installed in
3640 the correct subdirectory of @code{mandir}, based on the file extension.
3644 File extensions such as @samp{.1c} are handled by looking for the valid
3645 part of the extension and using that to determine the correct
3646 subdirectory of @code{mandir}. Valid section names are the digits
3647 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
3649 Sometimes developers prefer to name a man page something like
3650 @file{foo.man} in the source, and then rename it to have the correct
3651 suffix, e.g. @file{foo.1}, when installing the file. Automake also
3652 supports this mode. For a valid section named @var{SECTION}, there is a
3653 corresponding directory named @samp{man@var{SECTION}dir}, and a
3654 corresponding @samp{_MANS} variable. Files listed in such a variable
3655 are installed in the indicated section. If the file already has a
3656 valid suffix, then it is installed as-is; otherwise the file suffix is
3657 changed to match the section.
3659 For instance, consider this example:
3661 man1_MANS = rename.man thesame.1 alsothesame.1c
3664 In this case, @file{rename.man} will be renamed to @file{rename.1} when
3665 installed, but the other files will keep their names.
3667 @cindex Target, install-man
3668 @cindex Target, noinstall-man
3669 @cindex install-man target
3670 @cindex noinstall-man target
3672 @c Use @samp{make install} per documentation: (texi)code.
3673 By default, man pages are installed by @samp{make install}. However,
3674 since the GNU project does not require man pages, many maintainers do
3675 not expend effort to keep the man pages up to date. In these cases, the
3676 @code{no-installman} option will prevent the man pages from being
3677 installed by default. The user can still explicitly install them via
3678 @samp{make install-man}.
3679 @opindex no-installman
3680 @trindex install-man
3682 Here is how the man pages are handled in GNU @code{cpio} (which includes
3683 both Texinfo documentation and man pages):
3686 man_MANS = cpio.1 mt.1
3687 EXTRA_DIST = $(man_MANS)
3690 Man pages are not currently considered to be source, because it is not
3691 uncommon for man pages to be automatically generated. Therefore they
3692 are not automatically included in the distribution. However, this can
3693 be changed by use of the @samp{dist_} prefix.
3695 The @samp{nobase_} prefix is meaningless for man pages and is
3699 @node Install, Clean, Documentation, Top
3700 @chapter What Gets Installed
3702 @cindex Installation support
3703 @cindex make install support
3705 @section Basics of installation
3707 Naturally, Automake handles the details of actually installing your
3708 program once it has been built. All files named by the various
3709 primaries are automatically installed in the appropriate places when the
3710 user runs @code{make install}.
3712 A file named in a primary is installed by copying the built file into
3713 the appropriate directory. The base name of the file is used when
3717 bin_PROGRAMS = hello subdir/goodbye
3720 In this example, both @samp{hello} and @samp{goodbye} will be installed
3721 in @code{$(bindir)}.
3723 Sometimes it is useful to avoid the basename step at install time. For
3724 instance, you might have a number of header files in subdirectories of
3725 the source tree which are laid out precisely how you want to install
3726 them. In this situation you can use the @samp{nobase_} prefix to
3727 suppress the base name step. For example:
3730 nobase_include_HEADERS = stdio.h sys/types.h
3733 Will install @file{stdio.h} in @code{$(includedir)} and @file{types.h}
3734 in @code{$(includedir)/sys}.
3736 @section The two parts of install
3738 Automake generates separate @code{install-data} and @code{install-exec}
3739 targets, in case the installer is installing on multiple machines which
3740 share directory structure---these targets allow the machine-independent
3741 parts to be installed only once. @code{install-exec} installs
3742 platform-dependent files, and @code{install-data} installs
3743 platform-independent files. The @code{install} target depends on both
3744 of these targets. While Automake tries to automatically segregate
3745 objects into the correct category, the @file{Makefile.am} author is, in
3746 the end, responsible for making sure this is done correctly.
3747 @trindex install-data
3748 @trindex install-exec
3750 @cindex Install, two parts of
3752 Variables using the standard directory prefixes @samp{data},
3753 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
3754 @samp{pkgdata}, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
3755 installed by @samp{install-data}.
3757 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
3758 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
3759 @samp{pkglib} (e.g. @samp{bin_PROGRAMS}) are installed by
3760 @samp{install-exec}.
3762 Any variable using a user-defined directory prefix with @samp{exec} in
3763 the name (e.g. @samp{myexecbin_PROGRAMS} is installed by
3764 @samp{install-exec}. All other user-defined prefixes are installed by
3765 @samp{install-data}.
3767 @section Extending installation
3769 It is possible to extend this mechanism by defining an
3770 @code{install-exec-local} or @code{install-data-local} target. If these
3771 targets exist, they will be run at @samp{make install} time. These
3772 rules can do almost anything; care is required.
3773 @trindex install-exec-local
3774 @trindex install-data-local
3776 Automake also supports two install hooks, @code{install-exec-hook} and
3777 @code{install-data-hook}. These hooks are run after all other install
3778 rules of the appropriate type, exec or data, have completed. So, for
3779 instance, it is possible to perform post-installation modifications
3780 using an install hook.
3781 @cindex Install hook
3783 @section Staged installs
3786 Automake generates support for the @samp{DESTDIR} variable in all
3787 install rules. @samp{DESTDIR} is used during the @samp{make install}
3788 step to relocate install objects into a staging area. Each object and
3789 path is prefixed with the value of @samp{DESTDIR} before being copied
3790 into the install area. Here is an example of typical DESTDIR usage:
3793 make DESTDIR=/tmp/staging install
3796 This places install objects in a directory tree built under
3797 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
3798 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
3799 would install @file{/tmp/staging/gnu/bin/foo} and
3800 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
3802 This feature is commonly used to build install images and packages. For
3803 more information, see @ref{Makefile Conventions, , , standards, The GNU
3806 Support for @samp{DESTDIR} is implemented by coding it directly into the
3807 install rules. If your @file{Makefile.am} uses a local install rule
3808 (e.g., @code{install-exec-local}) or an install hook, then you must
3809 write that code to respect @samp{DESTDIR}.
3811 @section Rules for the user
3813 Automake also generates an @code{uninstall} target, an
3814 @code{installdirs} target, and an @code{install-strip} target.
3816 @trindex installdirs
3817 @trindex install-strip
3819 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
3820 There is no notion of separate uninstalls for ``exec'' and ``data'', as
3821 these features would not provide additional functionality.
3823 Note that @code{uninstall} is not meant as a replacement for a real
3827 @node Clean, Dist, Install, Top
3828 @chapter What Gets Cleaned
3830 @cindex make clean support
3832 The GNU Makefile Standards specify a number of different clean rules.
3833 See @xref{Standard Targets, , Standard Targets for Users, standards,
3834 The GNU Coding Standards}.
3836 Generally the files that can be cleaned are determined automatically by
3837 Automake. Of course, Automake also recognizes some variables that can
3838 be defined to specify additional files to clean. These variables are
3839 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
3840 @code{MAINTAINERCLEANFILES}.
3841 @vindex MOSTLYCLEANFILES
3843 @vindex DISTCLEANFILES
3844 @vindex MAINTAINERCLEANFILES
3846 As the GNU Standards aren't always explicit as to which files should be
3847 removed by which target, we've adopted a heuristic which we believe was
3848 first formulated by Fran@,{c}ois Pinard:
3852 If @code{make} built it, and it is commonly something that one would
3853 want to rebuild (for instance, a @file{.o} file), then
3854 @code{mostlyclean} should delete it.
3857 Otherwise, if @code{make} built it, then @code{clean} should delete it.
3860 If @code{configure} built it, then @code{distclean} should delete it
3863 If the maintainer built it, then @code{maintainer-clean} should
3867 We recommend that you follow this same set of heuristics in your
3871 @node Dist, Tests, Clean, Top
3872 @chapter What Goes in a Distribution
3874 @section Basics of distribution
3878 The @code{dist} target in the generated @file{Makefile.in} can be used
3879 to generate a gzip'd @code{tar} file and other flavors of archive for
3880 distribution. The files is named based on the @samp{PACKAGE} and
3881 @samp{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
3882 (@pxref{Macros}); more precisely the gzip'd @code{tar} file is named
3883 @samp{@var{package}-@var{version}.tar.gz}.
3887 You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
3888 is run. The default setting is @samp{--best}.
3890 For the most part, the files to distribute are automatically found by
3891 Automake: all source files are automatically included in a distribution,
3892 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
3893 has a built-in list of commonly used files which are automatically
3894 included if they are found in the current directory (either physically,
3895 or as the target of a @file{Makefile.am} rule). This list is printed by
3896 @samp{automake --help}. Also, files which are read by @code{configure}
3897 (i.e. the source files corresponding to the files specified in various
3898 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
3899 automatically distributed.
3901 Still, sometimes there are files which must be distributed, but which
3902 are not covered in the automatic rules. These files should be listed in
3903 the @code{EXTRA_DIST} variable. You can mention files from
3904 subdirectories in @code{EXTRA_DIST}.
3906 You can also mention a directory in @code{EXTRA_DIST}; in this case the
3907 entire directory will be recursively copied into the distribution.
3908 Please note that this will also copy @emph{everything} in the directory,
3909 including CVS/RCS version control files. We recommend against using
3914 @section Fine-grained distribution control
3916 Sometimes you need tighter control over what does @emph{not} go into the
3917 distribution; for instance you might have source files which are
3918 generated and which you do not want to distribute. In this case
3919 Automake gives fine-grained control using the @samp{dist} and
3920 @samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
3921 prefixed with @samp{dist_} to add the listed files to the distribution.
3922 Similarly, @samp{nodist_} can be used to omit the files from the
3927 As an example, here is how you would cause some data to be distributed
3928 while leaving some source code out of the distribution:
3931 dist_data_DATA = distribute-this
3933 nodist_foo_SOURCES = do-not-distribute.c
3936 @section The dist hook
3938 Another way to to use this is for removing unnecessary files that get
3939 recursively included by specifying a directory in EXTRA_DIST:
3945 rm -rf `find $(distdir)/doc -name CVS`
3948 If you define @code{SUBDIRS}, Automake will recursively include the
3949 subdirectories in the distribution. If @code{SUBDIRS} is defined
3950 conditionally (@pxref{Conditionals}), Automake will normally include all
3951 directories that could possibly appear in @code{SUBDIRS} in the
3952 distribution. If you need to specify the set of directories
3953 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
3954 list of subdirectories to include in the distribution.
3955 @vindex DIST_SUBDIRS
3959 Occasionally it is useful to be able to change the distribution before
3960 it is packaged up. If the @code{dist-hook} target exists, it is run
3961 after the distribution directory is filled, but before the actual tar
3962 (or shar) file is created. One way to use this is for distributing
3963 files in subdirectories for which a new @file{Makefile.am} is overkill:
3967 mkdir $(distdir)/random
3968 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
3971 @section Checking the distribution
3973 @cindex make distcheck
3974 @cindex make distcleancheck
3975 @vindex distcleancheck_listfiles
3977 Automake also generates a @code{distcheck} target which can be of help
3978 to ensure that a given distribution will actually work.
3979 @code{distcheck} makes a distribution, then tries to do a @code{VPATH}
3980 build, run the testsuite, and finally make another tarfile to ensure the
3981 distribution is self-contained.
3984 Building the package involves running @code{./configure}. If you need
3985 to supply additional flags to @code{configure}, define them in the
3986 @code{DISTCHECK_CONFIGURE_FLAGS} variable, either in your top-level
3987 @file{Makefile.am}, or on the commande line when invoking @code{make}.
3988 @vindex DISTCHECK_CONFIGURE_FLAGS
3990 If the target @code{distcheck-hook} is defined in your
3991 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
3992 the new distribution has been unpacked, but before the unpacked copy is
3993 configured and built. Your @code{distcheck-hook} can do almost
3994 anything, though as always caution is advised. Generally this hook is
3995 used to check for potential distribution errors not caught by the
3998 Speaking about potential distribution errors, @code{distcheck} will also
3999 ensure that the @code{distclean} target actually removes all built
4000 files. This is done by running @code{make distcleancheck} at the end of
4001 the @code{VPATH} build. By default, @code{distcleancheck} will run
4002 @code{distclean} and then make sure the build tree has been emptied by
4003 running @code{$(distcleancheck_listfiles)}. Usually this check will
4004 find generated files that you forgot to add to the @code{DISTCLEANFILES}
4005 variable (@pxref{Clean}).
4006 @trindex distcleancheck
4008 The @code{distcleancheck} behaviour should be ok for most packages,
4009 otherwise you have the possibility to override the definitition of
4010 either the @code{distcleancheck} target, or the
4011 @code{$(distcleancheck_listfiles)} variable. For instance to disable
4012 @code{distcleancheck} completely, add the following rule to your
4013 top-level @file{Makefile.am}:
4014 @vindex distcleancheck_listfiles
4021 If you want @code{distcleancheck} to ignore built files which have not
4022 been cleaned because they are also part of the distribution, add the
4023 following definition instead:
4026 distcleancheck_listfiles = \
4027 find -type f -exec sh -c 'test -f $(scrdir)/@{@} || echo @{@}'
4030 The above definition is not the default because it's usually an error if
4031 your Makefiles cause some distributed files to be rebuilt when the user
4032 build the package. (Think about the user missing the tool required to
4033 build the file; or if the required tool is built by your package,
4034 consider the cross-compilation case where it can't be run.)
4036 @section The types of distributions
4039 Automake generates a @samp{.tar.gz} file when asked to create a
4040 distribution and other archives formats, @ref{Options}. The target
4041 @code{dist-gzip} generates the @samp{.tar.gz} file only.
4044 @node Tests, Options, Dist, Top
4045 @chapter Support for test suites
4050 Automake supports two forms of test suites.
4052 @section Simple Tests
4054 If the variable @code{TESTS} is defined, its value is taken to be a list
4055 of programs to run in order to do the testing. The programs can either
4056 be derived objects or source objects; the generated rule will look both
4057 in @code{srcdir} and @file{.}. Programs needing data files should look
4058 for them in @code{srcdir} (which is both an environment variable and a
4059 make variable) so they work when building in a separate directory
4060 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
4061 Manual}), and in particular for the @code{distcheck} target
4064 @cindex Exit status 77, special interpretation
4066 The number of failures will be printed at the end of the run. If a
4067 given test program exits with a status of 77, then its result is ignored
4068 in the final count. This feature allows non-portable tests to be
4069 ignored in environments where they don't make sense.
4071 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
4072 variables for the test run; the environment variable @code{srcdir} is
4073 set in the rule. If all your test programs are scripts, you can also
4074 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
4075 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
4077 @vindex TESTS_ENVIRONMENT
4079 @cindex Tests, expected failure
4080 @cindex Expected test failure
4082 You may define the variable @code{XFAIL_TESTS} to a list of tests
4083 (usually a subset of @code{TESTS}) that are expected to fail. This will
4084 reverse the result of those tests.
4087 Automake ensures that each program listed in @code{TESTS} is built
4088 before any tests are run; you can list both source and derived programs
4089 in @code{TESTS}. For instance, you might want to run a C program as a
4090 test. To do this you would list its name in @code{TESTS} and also in
4091 @code{check_PROGRAMS}, and then specify it as you would any other
4094 @section DejaGNU Tests
4096 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @samp{dejagnu}} appears in
4097 @code{AUTOMAKE_OPTIONS}, then a @code{dejagnu}-based test suite is
4098 assumed. The variable @code{DEJATOOL} is a list of names which are
4099 passed, one at a time, as the @code{--tool} argument to @code{runtest}
4100 invocations; it defaults to the name of the package.
4102 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
4103 @code{--srcdir} flags that are passed to dejagnu by default; this can be
4104 overridden if necessary.
4105 @vindex RUNTESTDEFAULTFLAGS
4107 The variables @code{EXPECT} and @code{RUNTEST} can
4108 also be overridden to provide project-specific values. For instance,
4109 you will need to do this if you are testing a compiler toolchain,
4110 because the default values do not take into account host and target
4117 The contents of the variable @code{RUNTESTFLAGS} are passed to the
4118 @code{runtest} invocation. This is considered a ``user variable''
4119 (@pxref{User Variables}). If you need to set @code{runtest} flags in
4120 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
4121 @vindex RUNTESTFLAGS
4122 @vindex AM_RUNTESTFLAGS
4123 @c FIXME xref dejagnu
4125 @cindex @file{site.exp}
4126 Automake will generate rules to create a local @file{site.exp} file,
4127 defining various variables detected by @code{./configure}. This file
4128 is automatically read by DejaGnu. It is ok for the user of a package
4129 to edit this file in order to tune the test suite. However this is
4130 not the place where the test suite author should define new variables:
4131 this should be done elsewhere in the real test suite code.
4132 Especially, @file{site.exp} should not be distributed.
4134 In either case, the testing is done via @samp{make check}.
4136 @section Install Tests
4138 The @code{installcheck} target is available to the user as a way to run
4139 any tests after the package has been installed. You can add tests to
4140 this by writing an @code{installcheck-local} target.
4143 @node Options, Miscellaneous, Tests, Top
4144 @chapter Changing Automake's Behavior
4146 Various features of Automake can be controlled by options in the
4147 @file{Makefile.am}. Such options are applied on a per-@file{Makefile}
4148 basis when listed in a special @file{Makefile} variable named
4149 @code{AUTOMAKE_OPTIONS}. They are applied globally to all processed
4150 @file{Makefiles} when listed in the first argument of
4151 @code{AM_INIT_AUTOMAKE} in @file{configure.in}. Currently understood
4153 @vindex AUTOMAKE_OPTIONS
4158 @itemx @code{foreign}
4159 @itemx @code{cygnus}
4160 @cindex Option, gnits
4162 @cindex Option, foreign
4163 @cindex Option, cygnus
4165 Set the strictness as appropriate. The @code{gnits} option also implies
4166 @code{readme-alpha} and @code{check-news}.
4168 @item @code{ansi2knr}
4169 @itemx @code{@var{path}/ansi2knr}
4170 @cindex Option, ansi2knr
4171 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
4172 path, the generated @file{Makefile.in} will look in the specified
4173 directory to find the @file{ansi2knr} program. The path should be a
4174 relative path to another directory in the same distribution (Automake
4175 currently does not check this).
4177 @item @code{check-news}
4178 @cindex Option, check-news
4179 Cause @code{make dist} to fail unless the current version number appears
4180 in the first few lines of the @file{NEWS} file.
4182 @item @code{dejagnu}
4183 @cindex Option, dejagnu
4184 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
4186 @item @code{dist-bzip2}
4187 @cindex Option, dist-bzip2
4188 Generate a @code{dist-bzip2} target, creating a bzip2 tar archive of the
4189 distribution. @code{dist} will create it in addition to the other
4190 formats. bzip2 archives are frequently smaller than gzipped archives.
4193 @item @code{dist-shar}
4194 @cindex Option, dist-shar
4195 Generate a @code{dist-shar} target, creating a shar archive of the
4196 distribution. @code{dist} will create it in addition to the other
4200 @item @code{dist-zip}
4201 @cindex Option, dist-zip
4202 Generate a @code{dist-zip} target, creating a zip archive of the
4203 distribution. @code{dist} will create it in addition to the other
4207 @item @code{dist-tarZ}
4208 @cindex Option, dist-tarZ
4209 Generate a @code{dist-tarZ} target, creating a compressed tar archive of
4210 the distribution. @code{dist} will create it in addition to the other
4214 @item @code{no-define}
4215 @cindex Option, no-define
4216 This options is meaningful only when passed as an argument to
4217 AM_INIT_AUTOMAKE. It will prevent the @code{PACKAGE} and @code{VERSION}
4218 variable to be @code{AC_DEFINE}d.
4220 @item @code{no-dependencies}
4221 @cindex Option, no-dependencies
4222 This is similar to using @samp{--include-deps} on the command line, but
4223 is useful for those situations where you don't have the necessary bits
4224 to make automatic dependency tracking work @xref{Dependencies}. In this
4225 case the effect is to effectively disable automatic dependency tracking.
4227 @item @code{no-exeext}
4228 @cindex Option, no-exeext
4229 If your @file{Makefile.am} defines a target @samp{foo}, it will override
4230 a target named @samp{foo$(EXEEXT)}. This is necessary when
4231 @code{EXEEXT} is found to be empty. However, by default automake will
4232 generate an error for this use. The @code{no-exeext} option will
4233 disable this error. This is intended for use only where it is known in
4234 advance that the package will not be ported to Windows, or any other
4235 operating system using extensions on executables.
4237 @item @code{no-installinfo}
4238 @cindex Option, no-installinfo
4239 The generated @file{Makefile.in} will not cause info pages to be built
4240 or installed by default. However, @code{info} and @code{install-info}
4241 targets will still be available. This option is disallowed at
4242 @samp{GNU} strictness and above.
4244 @trindex install-info
4246 @item @code{no-installman}
4247 @cindex Option, no-installman
4248 The generated @file{Makefile.in} will not cause man pages to be
4249 installed by default. However, an @code{install-man} target will still
4250 be available for optional installation. This option is disallowed at
4251 @samp{GNU} strictness and above.
4252 @trindex install-man
4254 @item @code{nostdinc}
4255 @cindex Option, nostdinc
4256 This option can be used to disable the standard @samp{-I} options which
4257 are ordinarily automatically provided by Automake.
4259 @item @code{no-texinfo.tex}
4260 @cindex Option, no-texinfo
4261 Don't require @file{texinfo.tex}, even if there are texinfo files in
4264 @item @code{readme-alpha}
4265 @cindex Option, readme-alpha
4266 If this release is an alpha release, and the file @file{README-alpha}
4267 exists, then it will be added to the distribution. If this option is
4268 given, version numbers are expected to follow one of two forms. The
4269 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
4270 element is a number; the final period and number should be left off for
4271 non-alpha releases. The second form is
4272 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
4273 letter; it should be omitted for non-alpha releases.
4275 @item @code{std-options}
4276 @cindex Options, std-options
4277 @cindex make installcheck
4278 Make the @code{installcheck} target check that installed scripts and
4279 programs support the @code{--help} and @code{--version} options.
4280 This also provides a basic check that the program's
4281 run-time dependencies are satisfied after installation.
4283 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
4284 In a few situations, programs (or scripts) have to be exempted from this
4285 test. For instance @command{false} (from GNU sh-utils) is never
4286 successful, even for @code{--help} or @code{--version}. You can
4287 list such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
4289 @item @code{subdir-objects}
4290 If this option is specified, then objects are placed into the
4291 subdirectory of the build directory corresponding to the subdirectory of
4292 the source file. For instance if the source file is
4293 @file{subdir/file.cxx}, then the output file would be
4294 @file{subdir/file.o}.
4297 @cindex Option, version
4298 A version number (e.g. @samp{0.30}) can be specified. If Automake is not
4299 newer than the version specified, creation of the @file{Makefile.in}
4302 @item @code{-W@var{category}} or @code{--warnings=@var{category}}
4303 @cindex Option, warnings
4304 These options behave exactly like their command-line counterpart
4305 (@pxref{Invoking Automake}). This allows you to enable or disable some
4306 warning categories on a per-file basis. You can also setup some warnings
4307 for your entire project; for instance try @code{AM_INIT_AUTOMAKE([-Wall])}
4308 in your @file{configure.in}.
4312 Unrecognized options are diagnosed by @code{automake}.
4314 If you want an option to apply to all the files in the tree, you can use
4315 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.in}.
4319 @node Miscellaneous, Include, Options, Top
4320 @chapter Miscellaneous Rules
4322 There are a few rules and variables that didn't fit anywhere else.
4325 * Tags:: Interfacing to etags and mkid
4326 * Suffixes:: Handling new file extensions
4327 * Multilibs:: Support for multilibbing.
4331 @node Tags, Suffixes, Miscellaneous, Miscellaneous
4332 @section Interfacing to @code{etags}
4334 @cindex TAGS support
4336 Automake will generate rules to generate @file{TAGS} files for use with
4337 GNU Emacs under some circumstances.
4339 If any C, C++ or Fortran 77 source code or headers are present, then
4340 @code{tags} and @code{TAGS} targets will be generated for the directory.
4343 At the topmost directory of a multi-directory package, a @code{tags}
4344 target file will be generated which, when run, will generate a
4345 @file{TAGS} file that includes by reference all @file{TAGS} files from
4348 The @code{tags} target will also be generated if the variable
4349 @code{ETAGS_ARGS} is defined. This variable is intended for use in
4350 directories which contain taggable source that @code{etags} does not
4351 understand. The user can use the @code{ETAGSFLAGS} to pass additional
4352 flags to @code{etags}; @code{AM_ETAGSFLAGS} is also available for use in
4356 @vindex AM_ETAGSFLAGS
4358 Here is how Automake generates tags for its source, and for nodes in its
4362 ETAGS_ARGS = automake.in --lang=none \
4363 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
4366 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
4367 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
4368 are added directly to the dependencies for the @code{tags} target.
4369 @vindex TAGS_DEPENDENCIES
4371 Automake also generates a @code{ctags} target which can be used to
4372 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
4373 is the name of the program to invoke (by default @samp{ctags});
4374 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
4375 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
4377 Automake will also generate an @code{ID} target which will run
4378 @code{mkid} on the source. This is only supported on a
4379 directory-by-directory basis.
4382 Automake also supports the @uref{http://www.gnu.org/software/global/,
4383 GNU Global Tags program}. The @code{GTAGS} target runs Global Tags
4384 automatically and puts the result in the top build directory. The
4385 variable @code{GTAGS_ARGS} holds arguments which are passed to
4390 @node Suffixes, Multilibs, Tags, Miscellaneous
4391 @section Handling new file extensions
4393 @cindex Adding new SUFFIXES
4394 @cindex SUFFIXES, adding
4397 It is sometimes useful to introduce a new implicit rule to handle a file
4398 type that Automake does not know about.
4400 For instance, suppose you had a compiler which could compile @samp{.foo}
4401 files to @samp{.o} files. You would simply define an suffix rule for
4409 Then you could directly use a @samp{.foo} file in a @samp{_SOURCES}
4410 variable and expect the correct results:
4414 doit_SOURCES = doit.foo
4417 This was the simpler and more common case. In other cases, you will
4418 have to help Automake to figure which extensions you are defining your
4419 suffix rule for. This usually happens when your extensions does not
4420 start with a dot. Then, all you have to do is to put a list of new
4421 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
4424 For instance the following definition prevents Automake to misinterpret
4425 @samp{.idlC.cpp:} as an attemp to transform @samp{.idlC} into
4429 SUFFIXES = .idl C.cpp
4434 As you may have noted, the @code{SUFFIXES} variable behaves like the
4435 @code{.SUFFIXES} special target of @code{make}. You should not touch
4436 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
4437 Automake generate the suffix list for @code{.SUFFIXES}. Any given
4438 @code{SUFFIXES} go at the start of the generated suffixes list, followed
4439 by Automake generated suffixes not already in the list.
4441 @node Multilibs, , Suffixes, Miscellaneous
4442 @section Support for Multilibs
4444 Automake has support for an obscure feature called multilibs. A
4445 @dfn{multilib} is a library which is built for multiple different ABIs
4446 at a single time; each time the library is built with a different target
4447 flag combination. This is only useful when the library is intended to
4448 be cross-compiled, and it is almost exclusively used for compiler
4451 The multilib support is still experimental. Only use it if you are
4452 familiar with multilibs and can debug problems you might encounter.
4455 @node Include, Conditionals, Miscellaneous, Top
4459 @cindex Including Makefile fragment
4460 @cindex Makefile fragment, including
4462 Automake supports an @code{include} directive which can be used to
4463 include other @file{Makefile} fragments when @code{automake} is run.
4464 Note that these fragments are read and interpreted by @code{automake},
4465 not by @code{make}. As with conditionals, @code{make} has no idea that
4466 @code{include} is in use.
4468 There are two forms of @code{include}:
4471 @item include $(srcdir)/file
4472 Include a fragment which is found relative to the current source
4475 @item include $(top_srcdir)/file
4476 Include a fragment which is found relative to the top source directory.
4479 Note that if a fragment is included inside a conditional, then the
4480 condition applies to the entire contents of that fragment.
4483 @node Conditionals, Gnits, Include, Top
4484 @chapter Conditionals
4486 @cindex Conditionals
4488 Automake supports a simple type of conditionals.
4490 @cvindex AM_CONDITIONAL
4491 Before using a conditional, you must define it by using
4492 @code{AM_CONDITIONAL} in the @code{configure.in} file (@pxref{Macros}).
4494 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
4495 The conditional name, @var{conditional}, should be a simple string
4496 starting with a letter and containing only letters, digits, and
4497 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
4498 which are reserved by Automake.
4500 The shell @var{condition} (suitable for use in a shell @code{if}
4501 statement) is evaluated when @code{configure} is run. Note that you
4502 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
4503 time @code{configure} is run -- if @code{AM_CONDITIONAL} is run
4504 conditionally (e.g., in a shell @code{if} statement), then the result
4505 will confuse automake.
4508 @cindex --enable-debug, example
4509 @cindex Example conditional --enable-debug
4510 @cindex Conditional example, --enable-debug
4512 Conditionals typically depend upon options which the user provides to
4513 the @code{configure} script. Here is an example of how to write a
4514 conditional which is true if the user uses the @samp{--enable-debug}
4518 AC_ARG_ENABLE(debug,
4519 [ --enable-debug Turn on debugging],
4520 [case "$@{enableval@}" in
4523 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
4524 esac],[debug=false])
4525 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
4528 Here is an example of how to use that conditional in @file{Makefile.am}:
4540 noinst_PROGRAMS = $(DBG)
4543 This trivial example could also be handled using EXTRA_PROGRAMS
4544 (@pxref{Conditional Programs}).
4546 You may only test a single variable in an @code{if} statement, possibly
4547 negated using @samp{!}. The @code{else} statement may be omitted.
4548 Conditionals may be nested to any depth. You may specify an argument to
4549 @code{else} in which case it must be the negation of the condition used
4550 for the current @code{if}. Similarly you may specify the condition
4551 which is closed by an @code{end}:
4562 Unbalanced conditions are errors.
4564 Note that conditionals in Automake are not the same as conditionals in
4565 GNU Make. Automake conditionals are checked at configure time by the
4566 @file{configure} script, and affect the translation from
4567 @file{Makefile.in} to @file{Makefile}. They are based on options passed
4568 to @file{configure} and on results that @file{configure} has discovered
4569 about the host system. GNU Make conditionals are checked at @code{make}
4570 time, and are based on variables passed to the make program or defined
4571 in the @file{Makefile}.
4573 Automake conditionals will work with any make program.
4576 @node Gnits, Cygnus, Conditionals, Top
4577 @chapter The effect of @code{--gnu} and @code{--gnits}
4579 @cindex --gnu, required files
4580 @cindex --gnu, complete description
4582 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
4583 variable) causes @code{automake} to check the following:
4587 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
4588 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
4589 or @file{COPYING}, are required at the topmost directory of the package.
4592 The options @samp{no-installman} and @samp{no-installinfo} are
4596 Note that this option will be extended in the future to do even more
4597 checking; it is advisable to be familiar with the precise requirements
4598 of the GNU standards. Also, @samp{--gnu} can require certain
4599 non-standard GNU programs to exist for use by various maintainer-only
4600 targets; for instance in the future @code{pathchk} might be required for
4603 @cindex --gnits, complete description
4605 The @samp{--gnits} option does everything that @samp{--gnu} does, and
4606 checks the following as well:
4610 @samp{make installcheck} will check to make sure that the @code{--help}
4611 and @code{--version} really print a usage message and a version string,
4612 respectively. This is the @code{std-options} option (@pxref{Options}).
4615 @samp{make dist} will check to make sure the @file{NEWS} file has been
4616 updated to the current version.
4619 @samp{VERSION} is checked to make sure its format complies with Gnits
4621 @c FIXME xref when standards are finished
4624 @cindex README-alpha
4625 If @samp{VERSION} indicates that this is an alpha release, and the file
4626 @file{README-alpha} appears in the topmost directory of a package, then
4627 it is included in the distribution. This is done in @samp{--gnits}
4628 mode, and no other, because this mode is the only one where version
4629 number formats are constrained, and hence the only mode where Automake
4630 can automatically determine whether @file{README-alpha} should be
4634 The file @file{THANKS} is required.
4638 @node Cygnus, Extending, Gnits, Top
4639 @chapter The effect of @code{--cygnus}
4641 @cindex Cygnus strictness
4643 Some packages, notably GNU GCC and GNU gdb, have a build environment
4644 originally written at Cygnus Support (subsequently renamed Cygnus
4645 Solutions, and then later purchased by Red Hat). Packages with this
4646 ancestry are sometimes referred to as ``Cygnus'' trees.
4648 A Cygnus tree has slightly different rules for how a @file{Makefile.in}
4649 is to be constructed. Passing @samp{--cygnus} to @code{automake} will
4650 cause any generated @file{Makefile.in} to comply with Cygnus rules.
4652 Here are the precise effects of @samp{--cygnus}:
4656 Info files are always created in the build directory, and not in the
4660 @file{texinfo.tex} is not required if a Texinfo source file is
4661 specified. The assumption is that the file will be supplied, but in a
4662 place that Automake cannot find. This assumption is an artifact of how
4663 Cygnus packages are typically bundled.
4666 @samp{make dist} is not supported, and the rules for it are not
4667 generated. Cygnus-style trees use their own distribution mechanism.
4670 Certain tools will be searched for in the build tree as well as in the
4671 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
4672 @code{makeinfo} and @code{texi2dvi}.
4675 @code{--foreign} is implied.
4678 The options @samp{no-installinfo} and @samp{no-dependencies} are
4682 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
4686 The @code{check} target doesn't depend on @code{all}.
4689 GNU maintainers are advised to use @samp{gnu} strictness in preference
4690 to the special Cygnus mode. Some day, perhaps, the differences between
4691 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
4692 more standards compliant). At that time the special Cygnus mode will be
4696 @node Extending, Distributing, Cygnus, Top
4697 @chapter When Automake Isn't Enough
4699 Automake's implicit copying semantics means that many problems can be
4700 worked around by simply adding some @code{make} targets and rules to
4701 @file{Makefile.in}. Automake will ignore these additions.
4703 @cindex -local targets
4704 @cindex local targets
4706 There are some caveats to doing this. Although you can overload a
4707 target already used by Automake, it is often inadvisable, particularly
4708 in the topmost directory of a package with subdirectories. However,
4709 various useful targets have a @samp{-local} version you can specify in
4710 your @file{Makefile.in}. Automake will supplement the standard target
4711 with these user-supplied targets.
4724 @trindex check-local
4726 @trindex install-data-local
4727 @trindex install-exec
4728 @trindex install-exec-local
4730 @trindex uninstall-local
4731 @trindex mostlyclean
4732 @trindex mostlyclean-local
4734 @trindex clean-local
4736 @trindex distclean-local
4737 @trindex installdirs
4738 @trindex installdirs-local
4739 @trindex installcheck
4740 @trindex installcheck-local
4742 The targets that support a local version are @code{all}, @code{info},
4743 @code{dvi}, @code{ps}, @code{pdf}, @code{check}, @code{install-data},
4744 @code{install-exec}, @code{uninstall}, @code{installdirs},
4745 @code{installcheck} and the various @code{clean} targets
4746 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
4747 @code{maintainer-clean}). Note that there are no
4748 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
4749 use @code{uninstall-local}. It doesn't make sense to uninstall just
4751 For instance, here is one way to install a file in @file{/etc}:
4755 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
4758 @cindex -hook targets
4759 @cindex hook targets
4761 Some targets also have a way to run another target, called a @dfn{hook},
4762 after their work is done. The hook is named after the principal target,
4763 with @samp{-hook} appended. The targets allowing hooks are
4764 @code{install-data}, @code{install-exec}, @code{uninstall}, @code{dist},
4765 and @code{distcheck}.
4766 @trindex install-data-hook
4767 @trindex install-exec-hook
4768 @trindex uninstall-hook
4771 For instance, here is how to create a hard link to an installed program:
4775 ln $(DESTDIR)$(bindir)/program $(DESTDIR)$(bindir)/proglink
4778 @c FIXME should include discussion of variables you can use in these
4781 @node Distributing, API versioning, Extending, Top
4782 @chapter Distributing @file{Makefile.in}s
4784 Automake places no restrictions on the distribution of the resulting
4785 @file{Makefile.in}s. We still encourage software authors to distribute
4786 their work under terms like those of the GPL, but doing so is not
4787 required to use Automake.
4789 Some of the files that can be automatically installed via the
4790 @code{--add-missing} switch do fall under the GPL. However, these also
4791 have a special exception allowing you to distribute them with your
4792 package, regardless of the licensing you choose.
4795 @node API versioning, Macro and Variable Index, Distributing, Top
4796 @chapter Automake API versioning
4798 New Automake releases usually include bug fixes and new features.
4799 Unfortunately they may also introduce new bugs and incompatibilities.
4800 This makes four reasons why a package may require a particular Automake
4803 Things get worse when maintaining a large tree of packages, each one
4804 requiring a different version of Automake. In the past, this meant that
4805 any developer (and sometime users) had to install several versions of
4806 Automake in different places, and switch @samp{$PATH} appropriately for
4809 Starting with version 1.6, Automake installs versioned binaries. This
4810 means you can install several versions of Automake in the same
4811 @samp{$prefix}, and can select an arbitrary Automake version by running
4812 @samp{automake-1.6} or @samp{automake-1.7} without juggling with
4813 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
4814 will use @samp{automake-1.6} explicitely in their rebuild rules.
4816 Note that @samp{1.6} in @samp{automake-1.6} is Automake's API version,
4817 not Automake's version. If a bug fix release is made, for instance
4818 Automake 1.6.1, the API version will remain 1.6. This means that a
4819 package which work with Automake 1.6 should also work with 1.6.1; after
4820 all, this is what people expect from bug fix releases.
4822 Note that if your package relies on a feature or a bug fix introduced in
4823 a release, you can pass this version as an option to Automake to ensure
4824 older releases will not be used. For instance, use this in your
4825 @file{configure.in}:
4828 AM_INIT_AUTOMAKE(1.6.1) dnl Require Automake 1.6.1 or better.
4831 or, in a particular @file{Makefile.am}:
4834 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
4837 Automake will print an error message if its version is
4838 older than the requested version.
4841 @heading What is in the API
4843 Automake's programing interface is not easy to define. Basically it
4844 should include at least all @strong{documented} variables and targets
4845 that a @samp{Makefile.am} authors can use, the behaviours associated to
4846 them (e.g. the places where @samp{-hook}'s are run), the command line
4847 interface of @samp{automake} and @samp{aclocal}, @dots{}
4849 @heading What is not in the API
4851 Every undocumented variable, target, or command line option, is not part
4852 of the API. You should avoid using them, as they could change from one
4853 version to the other (even in bug fix releases, if this helps to fix a
4856 If it turns out you need to use such a undocumented feature, contact
4857 @email{automake@@gnu.org} and try to get it documented and exercised by
4861 @node Macro and Variable Index, General Index, API versioning, Top
4862 @unnumbered Macro and Variable Index
4868 @node General Index, , Macro and Variable Index, Top
4869 @unnumbered General Index