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
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 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 * Macro and Variable Index::
143 @node Introduction, Generalities, Top, Top
144 @chapter Introduction
146 Automake is a tool for automatically generating @file{Makefile.in}s from
147 files called @file{Makefile.am}. Each @file{Makefile.am} is basically a
148 series of @code{make} macro definitions (with rules being thrown in
149 occasionally). The generated @file{Makefile.in}s are compliant with the
150 GNU Makefile standards.
152 @cindex GNU Makefile standards
154 The GNU Makefile Standards Document
155 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
156 is long, complicated, and subject to change. The goal of Automake is to
157 remove the burden of Makefile maintenance from the back of the
158 individual GNU maintainer (and put it on the back of the Automake
161 The typical Automake input file is simply a series of macro definitions.
162 Each such file is processed to create a @file{Makefile.in}. There
163 should generally be one @file{Makefile.am} per directory of a project.
165 @cindex Constraints of Automake
166 @cindex Automake constraints
168 Automake does constrain a project in certain ways; for instance it
169 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
170 autoconf, The Autoconf Manual}), and enforces certain restrictions on
171 the @file{configure.in} contents@footnote{Autoconf 2.50 promotes
172 @file{configure.ac} over @file{configure.in}. The rest of this
173 documentation will refer to @file{configure.in} as this use is not yet
174 spread, but Automake supports @file{configure.ac} too.}.
176 @cindex Automake requirements
177 @cindex Requirements, Automake
179 Automake requires @code{perl} in order to generate the
180 @file{Makefile.in}s. However, the distributions created by Automake are
181 fully GNU standards-compliant, and do not require @code{perl} in order
184 @cindex BUGS, reporting
185 @cindex Reporting BUGS
186 @cindex E-mail, bug reports
188 Mail suggestions and bug reports for Automake to
189 @email{bug-automake@@gnu.org}.
192 @node Generalities, Examples, Introduction, Top
193 @chapter General ideas
195 The following sections cover a few basic ideas that will help you
196 understand how Automake works.
199 * General Operation:: General operation of Automake
200 * Strictness:: Standards conformance checking
201 * Uniform:: The Uniform Naming Scheme
202 * Canonicalization:: How derived variables are named
203 * User Variables:: Variables reserved for the user
204 * Auxiliary Programs:: Programs automake might require
208 @node General Operation, Strictness, Generalities, Generalities
209 @section General Operation
211 Automake works by reading a @file{Makefile.am} and generating a
212 @file{Makefile.in}. Certain macros and targets defined in the
213 @file{Makefile.am} instruct Automake to generate more specialized code;
214 for instance, a @samp{bin_PROGRAMS} macro definition will cause targets
215 for compiling and linking programs to be generated.
217 @cindex Non-standard targets
218 @cindex cvs-dist, non-standard example
221 The macro definitions and targets in the @file{Makefile.am} are copied
222 verbatim into the generated file. This allows you to add arbitrary code
223 into the generated @file{Makefile.in}. For instance the Automake
224 distribution includes a non-standard @code{cvs-dist} target, which the
225 Automake maintainer uses to make distributions from his source control
228 @cindex GNU make extensions
230 Note that GNU make extensions are not recognized by Automake. Using
231 such extensions in a @file{Makefile.am} will lead to errors or confusing
234 Automake tries to group comments with adjoining targets and macro
235 definitions in an intelligent way.
237 @cindex Make targets, overriding
238 @cindex Overriding make targets
240 A target defined in @file{Makefile.am} generally overrides any such
241 target of a similar name that would be automatically generated by
242 @code{automake}. Although this is a supported feature, it is generally
243 best to avoid making use of it, as sometimes the generated rules are
246 @cindex Macros, overriding
247 @cindex Overriding make macros
249 Similarly, a macro defined in @file{Makefile.am} will override any
250 definition of the macro that @code{automake} would ordinarily create.
251 This feature is more often useful than the ability to override a target
252 definition. Be warned that many of the macros generated by
253 @code{automake} are considered to be for internal use only, and their
254 names might change in future releases.
256 @cindex Recursive operation of Automake
257 @cindex Automake, recursive operation
258 @cindex Example of recursive operation
260 When examining a macro definition, Automake will recursively examine
261 macros referenced in the definition. For example, if Automake is
262 looking at the content of @code{foo_SOURCES} in this snippet
266 foo_SOURCES = c.c $(xs)
269 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
270 contents of @code{foo_SOURCES}.
272 @cindex ## (special Automake comment)
273 @cindex Special Automake comment
274 @cindex Comment, special to Automake
276 Automake also allows a form of comment which is @emph{not} copied into
277 the output; all lines beginning with @samp{##} (leading spaces allowed)
278 are completely ignored by Automake.
280 It is customary to make the first line of @file{Makefile.am} read:
282 @cindex Makefile.am, first line
283 @cindex First line of Makefile.am
286 ## Process this file with automake to produce Makefile.in
289 @c FIXME discuss putting a copyright into Makefile.am here? I would but
290 @c I don't know quite what to say.
292 @c FIXME document customary ordering of Makefile.am here!
295 @node Strictness, Uniform, General Operation, Generalities
298 @cindex Non-GNU packages
300 While Automake is intended to be used by maintainers of GNU packages, it
301 does make some effort to accommodate those who wish to use it, but do
302 not want to use all the GNU conventions.
304 @cindex Strictness, defined
305 @cindex Strictness, foreign
306 @cindex foreign strictness
307 @cindex Strictness, gnu
308 @cindex gnits strictness
309 @cindex Strictness, gnits
310 @cindex gnits strictness
312 To this end, Automake supports three levels of @dfn{strictness}---the
313 strictness indicating how stringently Automake should check standards
316 The valid strictness levels are:
320 Automake will check for only those things which are absolutely
321 required for proper operations. For instance, whereas GNU standards
322 dictate the existence of a @file{NEWS} file, it will not be required in
323 this mode. The name comes from the fact that Automake is intended to be
324 used for GNU programs; these relaxed rules are not the standard mode of
328 Automake will check---as much as possible---for compliance to the GNU
329 standards for packages. This is the default.
332 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
333 standards}. These are based on the GNU standards, but are even more
334 detailed. Unless you are a Gnits standards contributor, it is
335 recommended that you avoid this option until such time as the Gnits
336 standard is actually published (which may never happen).
339 For more information on the precise implications of the strictness
340 level, see @ref{Gnits}.
342 Automake also has a special ``cygnus'' mode which is similar to
343 strictness but handled differently. This mode is useful for packages
344 which are put into a ``Cygnus'' style tree (e.g., the GCC tree). For
345 more information on this mode, see @ref{Cygnus}.
348 @node Uniform, Canonicalization, Strictness, Generalities
349 @section The Uniform Naming Scheme
351 @cindex Uniform naming scheme
353 Automake macros (from here on referred to as @emph{variables}) generally
354 follow a @dfn{uniform naming scheme} that makes it easy to decide how
355 programs (and other derived objects) are built, and how they are
356 installed. This scheme also supports @code{configure} time
357 determination of what should be built.
359 @cindex _PROGRAMS primary variable
360 @cindex PROGRAMS primary variable
361 @cindex Primary variable, PROGRAMS
363 @cindex Primary variable, defined
365 At @code{make} time, certain variables are used to determine which
366 objects are to be built. The variable names are made of several pieces
367 which are concatenated together.
369 The piece which tells automake what is being built is commonly called
370 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
371 list of programs which are to be compiled and linked.
374 @cindex pkglibdir, defined
375 @cindex pkgincludedir, defined
376 @cindex pkgdatadir, defined
379 @vindex pkgincludedir
382 A different set of names is used to decide where the built objects
383 should be installed. These names are prefixes to the primary which
384 indicate which standard directory should be used as the installation
385 directory. The standard directory names are given in the GNU standards
386 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
387 Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
388 and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
389 versions, but with @samp{@@PACKAGE@@} appended. For instance,
390 @code{pkglibdir} is defined as @code{$(libdir)/@@PACKAGE@@}.
393 @cindex EXTRA_, prepending
395 For each primary, there is one additional variable named by prepending
396 @samp{EXTRA_} to the primary name. This variable is used to list
397 objects which may or may not be built, depending on what
398 @code{configure} decides. This variable is required because Automake
399 must statically know the entire list of objects that may be built in
400 order to generate a @file{Makefile.in} that will work in all cases.
402 @cindex EXTRA_PROGRAMS, defined
403 @cindex Example, EXTRA_PROGRAMS
406 For instance, @code{cpio} decides at configure time which programs are
407 built. Some of the programs are installed in @code{bindir}, and some
408 are installed in @code{sbindir}:
411 EXTRA_PROGRAMS = mt rmt
412 bin_PROGRAMS = cpio pax
413 sbin_PROGRAMS = @@MORE_PROGRAMS@@
416 Defining a primary without a prefix as a variable, e.g.,
417 @code{PROGRAMS}, is an error.
419 Note that the common @samp{dir} suffix is left off when constructing the
420 variable names; thus one writes @samp{bin_PROGRAMS} and not
421 @samp{bindir_PROGRAMS}.
423 Not every sort of object can be installed in every directory. Automake
424 will flag those attempts it finds in error. Automake will also diagnose
425 obvious misspellings in directory names.
427 @cindex Extending list of installation directories
428 @cindex Installation directories, extending list
430 Sometimes the standard directories---even as augmented by Automake---
431 are not enough. In particular it is sometimes useful, for clarity, to
432 install objects in a subdirectory of some predefined directory. To this
433 end, Automake allows you to extend the list of possible installation
434 directories. A given prefix (e.g. @samp{zar}) is valid if a variable of
435 the same name with @samp{dir} appended is defined (e.g. @code{zardir}).
437 @cindex HTML support, example
439 For instance, until HTML support is part of Automake, you could use this
440 to install raw HTML documentation:
443 htmldir = $(prefix)/html
444 html_DATA = automake.html
447 @cindex noinst primary prefix, definition
449 The special prefix @samp{noinst} indicates that the objects in question
450 should not be installed at all.
452 @cindex check primary prefix, definition
454 The special prefix @samp{check} indicates that the objects in question
455 should not be built until the @code{make check} command is run.
457 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
458 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
459 @samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
471 Some primaries also allow additional prefixes which control other
472 aspects of @code{automake}'s behavior. The currently defined prefixes
473 are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes
477 @node Canonicalization, User Variables, Uniform, Generalities
478 @section How derived variables are named
480 @cindex canonicalizing Automake macros
482 Sometimes a Makefile variable name is derived from some text the
483 maintainer supplies. For instance, a program name listed in
484 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
485 variable. In cases like this, Automake canonicalizes the text, so that
486 program names and the like do not have to follow Makefile macro naming
487 rules. All characters in the name except for letters, numbers, the
488 strudel (@@), and the underscore are turned into underscores when making
491 For example, if your program is named @code{sniff-glue}, the derived
492 variable name would be @code{sniff_glue_SOURCES}, not
493 @code{sniff-glue_SOURCES}.
495 The strudel is an addition, to make the use of Autoconf substitutions in
496 macro names less obfuscating.
499 @node User Variables, Auxiliary Programs, Canonicalization, Generalities
500 @section Variables reserved for the user
502 @cindex variables, reserved for the user
503 @cindex user variables
505 Some @code{Makefile} variables are reserved by the GNU Coding Standards
506 for the use of the ``user'' -- the person building the package. For
507 instance, @code{CFLAGS} is one such variable.
509 Sometimes package developers are tempted to set user variables such as
510 @code{CFLAGS} because it appears to make their job easier -- they don't
511 have to introduce a second variable into every target.
513 However, the package itself should never set a user variable,
514 particularly not to include switches which are required for proper
515 compilation of the package. Since these variables are documented as
516 being for the package builder, that person rightfully expects to be able
517 to override any of these variables at build time.
519 To get around this problem, automake introduces an automake-specific
520 shadow variable for each user flag variable. (Shadow variables are not
521 introduced for variables like @code{CC}, where they would make no
522 sense.) The shadow variable is named by prepending @samp{AM_} to the
523 user variable's name. For instance, the shadow variable for
524 @code{YFLAGS} is @code{AM_YFLAGS}.
527 @node Auxiliary Programs, , User Variables, Generalities
528 @section Programs automake might require
530 @cindex Programs, auxiliary
531 @cindex Auxiliary programs
533 Automake sometimes requires helper programs so that the generated
534 @file{Makefile} can do its work properly. There are a fairly large
535 number of them, and we list them here.
540 These two files are used by the automatic de-ANSI-fication support
544 This is a wrapper for compilers which don't accept both @samp{-c} and
545 @samp{-o} at the same time. It is only used when absolutely required.
546 Such compilers are rare.
550 These programs compute the canonical triplets for the given build, host,
551 or target architecture.
554 This program understands how to run a compiler so that it will generate
555 not only the desired output but also dependency information which is
556 then used by the automatic dependency tracking feature.
559 This program is used to byte-compile Emacs Lisp code.
562 This is a replacement for the @code{install} program which works on
563 platforms where @code{install} is unavailable or unusable.
566 This script is used to generate a @file{version.texi} file. It examines
567 a file and prints some date information about it.
570 This wraps a number of programs which are typically only required by
571 maintainers. If the program in question doesn't exist, @code{missing}
572 prints an informative warning and attempts to fix things so that the
576 This works around the fact that @code{mkdir -p} is not portable.
579 This is used to byte-compile Python scripts.
582 Not a program, this file is required for @code{make dvi} to work when
583 Texinfo sources are in the package.
586 This program wraps @code{lex} and @code{yacc} and ensures that, for
587 instance, multiple @code{yacc} instances can be invoked in a single
588 directory in parallel.
593 @node Examples, Invoking Automake, Generalities, Top
594 @chapter Some example packages
597 * Complete:: A simple example, start to finish
598 * Hello:: A classic program
599 * etags:: Building etags and ctags
603 @node Complete, Hello, Examples, Examples
604 @section A simple example, start to finish
606 @cindex Complete example
608 Let's suppose you just finished writing @code{zardoz}, a program to make
609 your head float from vortex to vortex. You've been using Autoconf to
610 provide a portability framework, but your @file{Makefile.in}s have been
611 ad-hoc. You want to make them bulletproof, so you turn to Automake.
613 @cindex AM_INIT_AUTOMAKE, example use
615 The first step is to update your @file{configure.in} to include the
616 commands that @code{automake} needs. The way to do this is to add an
617 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
620 AM_INIT_AUTOMAKE(zardoz, 1.0)
623 Since your program doesn't have any complicating factors (e.g., it
624 doesn't use @code{gettext}, it doesn't want to build a shared library),
625 you're done with this part. That was easy!
627 @cindex aclocal program, introduction
628 @cindex aclocal.m4, preexisting
629 @cindex acinclude.m4, defined
631 Now you must regenerate @file{configure}. But to do that, you'll need
632 to tell @code{autoconf} how to find the new macro you've used. The
633 easiest way to do this is to use the @code{aclocal} program to generate
634 your @file{aclocal.m4} for you. But wait... you already have an
635 @file{aclocal.m4}, because you had to write some hairy macros for your
636 program. The @code{aclocal} program lets you put your own macros into
637 @file{acinclude.m4}, so simply rename and then run:
640 mv aclocal.m4 acinclude.m4
645 @cindex zardoz example
647 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
648 Since @code{zardoz} is a user program, you want to install it where the
649 rest of the user programs go. Additionally, @code{zardoz} has some
650 Texinfo documentation. Your @file{configure.in} script uses
651 @code{AC_REPLACE_FUNCS}, so you need to link against @samp{@@LIBOBJS@@}.
652 So here's what you'd write:
655 bin_PROGRAMS = zardoz
656 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
657 zardoz_LDADD = @@LIBOBJS@@
659 info_TEXINFOS = zardoz.texi
662 Now you can run @code{automake --add-missing} to generate your
663 @file{Makefile.in} and grab any auxiliary files you might need, and
667 @node Hello, etags, Complete, Examples
668 @section A classic program
670 @cindex Example, GNU Hello
671 @cindex Hello example
672 @cindex GNU Hello, example
674 @uref{ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz, GNU hello} is
675 renowned for its classic simplicity and versatility. This section shows
676 how Automake could be used with the GNU Hello package. The examples
677 below are from the latest beta version of GNU Hello, but with all of the
678 maintainer-only code stripped out, as well as all copyright comments.
680 Of course, GNU Hello is somewhat more featureful than your traditional
681 two-liner. GNU Hello is internationalized, does option processing, and
682 has a manual and a test suite.
684 @cindex configure.in, from GNU Hello
685 @cindex GNU Hello, configure.in
686 @cindex Hello, configure.in
688 Here is the @file{configure.in} from GNU Hello:
691 dnl Process this file with autoconf to produce a configure script.
693 AM_INIT_AUTOMAKE(hello, 1.3.11)
694 AM_CONFIG_HEADER(config.h)
696 dnl Set of available languages.
697 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
699 dnl Checks for programs.
703 dnl Checks for libraries.
705 dnl Checks for header files.
707 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
709 dnl Checks for library functions.
712 dnl Check for st_blksize in struct stat
715 dnl internationalization macros
717 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
718 src/Makefile tests/Makefile tests/hello],
719 [chmod +x tests/hello])
722 The @samp{AM_} macros are provided by Automake (or the Gettext library);
723 the rest are standard Autoconf macros.
726 The top-level @file{Makefile.am}:
729 EXTRA_DIST = BUGS ChangeLog.O
730 SUBDIRS = doc intl po src tests
733 As you can see, all the work here is really done in subdirectories.
735 The @file{po} and @file{intl} directories are automatically generated
736 using @code{gettextize}; they will not be discussed here.
738 @cindex Texinfo file handling example
739 @cindex Example, handling Texinfo files
741 In @file{doc/Makefile.am} we see:
744 info_TEXINFOS = hello.texi
745 hello_TEXINFOS = gpl.texi
748 This is sufficient to build, install, and distribute the GNU Hello
751 @cindex Regression test example
752 @cindex Example, regression test
754 Here is @file{tests/Makefile.am}:
758 EXTRA_DIST = hello.in testdata
761 The script @file{hello} is generated by @code{configure}, and is the
762 only test case. @code{make check} will run this test.
764 @cindex INCLUDES, example usage
766 Last we have @file{src/Makefile.am}, where all the real work is done:
770 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
771 hello_LDADD = @@INTLLIBS@@ @@ALLOCA@@
772 localedir = $(datadir)/locale
773 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
777 @node etags, , Hello, Examples
778 @section Building etags and ctags
780 @cindex Example, ctags and etags
781 @cindex ctags Example
782 @cindex etags Example
784 Here is another, trickier example. It shows how to generate two
785 programs (@code{ctags} and @code{etags}) from the same source file
786 (@file{etags.c}). The difficult part is that each compilation of
787 @file{etags.c} requires different @code{cpp} flags.
790 bin_PROGRAMS = etags ctags
792 ctags_LDADD = ctags.o
795 $(COMPILE) -DETAGS_REGEXPS -c etags.c
798 $(COMPILE) -DCTAGS -o ctags.o -c etags.c
801 Note that @code{ctags_SOURCES} is defined to be empty---that way no
802 implicit value is substituted. The implicit value, however, is used to
803 generate @code{etags} from @file{etags.o}.
805 @code{ctags_LDADD} is used to get @file{ctags.o} into the link line.
806 @code{ctags_DEPENDENCIES} is generated by Automake.
808 The above rules won't work if your compiler doesn't accept both
809 @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
810 bogus dependency (to avoid problems with a parallel @code{make}):
813 etags.o: etags.c ctags.o
814 $(COMPILE) -DETAGS_REGEXPS -c etags.c
817 $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
820 Also, these explicit rules do not work if the de-ANSI-fication feature
821 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
825 etags._o: etags._c ctags.o
826 $(COMPILE) -DETAGS_REGEXPS -c etags.c
829 $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
832 As it turns out, there is also a much easier way to do this same task.
833 Some of the above techniques are useful enough that we've kept the
834 example in the manual. However if you were to build @code{etags} and
835 @code{ctags} in real life, you would probably use per-program
836 compilation flags, like so:
839 bin_PROGRAMS = ctags etags
841 ctags_SOURCES = etags.c
842 ctags_CFLAGS = -DCTAGS
844 etags_SOURCES = etags.c
845 etags_CFLAGS = -DETAGS_REGEXPS
848 In this case Automake will cause @file{etags.c} to be compiled twice,
849 with different flags. De-ANSI-fication will work automatically. In
850 this instance, the names of the object files would be chosen by
851 automake; they would be @file{ctags-etags.o} and @file{etags-etags.o}.
852 (The name of the object files rarely matters.)
855 @node Invoking Automake, configure, Examples, Top
856 @chapter Creating a @file{Makefile.in}
858 @cindex Multiple configure.in files
859 @cindex Invoking Automake
860 @cindex Automake, invoking
862 To create all the @file{Makefile.in}s for a package, run the
863 @code{automake} program in the top level directory, with no arguments.
864 @code{automake} will automatically find each appropriate
865 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
866 and generate the corresponding @file{Makefile.in}. Note that
867 @code{automake} has a rather simplistic view of what constitutes a
868 package; it assumes that a package has only one @file{configure.in}, at
869 the top. If your package has multiple @file{configure.in}s, then you
870 must run @code{automake} in each directory holding a
873 You can optionally give @code{automake} an argument; @file{.am} is
874 appended to the argument and the result is used as the name of the input
875 file. This feature is generally only used to automatically rebuild an
876 out-of-date @file{Makefile.in}. Note that @code{automake} must always
877 be run from the topmost directory of a project, even if being used to
878 regenerate the @file{Makefile.in} in some subdirectory. This is
879 necessary because @code{automake} must scan @file{configure.in}, and
880 because @code{automake} uses the knowledge that a @file{Makefile.in} is
881 in a subdirectory to change its behavior in some cases.
883 @cindex Automake options
884 @cindex Options, Automake
886 @code{automake} accepts the following options:
888 @cindex Extra files distributed with Automake
889 @cindex Files distributed with Automake
896 @opindex --add-missing
897 Automake requires certain common files to exist in certain situations;
898 for instance @file{config.guess} is required if @file{configure.in} runs
899 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
900 files; this option will cause the missing ones to be automatically added
901 to the package, whenever possible. In general if Automake tells you a
902 file is missing, try using this option. By default Automake tries to
903 make a symbolic link pointing to its own copy of the missing file; this
904 can be changed with @code{--copy}.
906 @item --libdir=@var{dir}
908 Look for Automake data files in directory @var{dir} instead of in the
909 installation directory. This is typically used for debugging.
915 When used with @code{--add-missing}, causes installed files to be
916 copied. The default is to make a symbolic link.
920 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
921 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
925 @itemx --force-missing
926 @opindex --force-missing
927 When used with @code{--add-missing}, causes standard files to be rebuilt
928 even if they already exist in the source tree. This involves removing
929 the file from the source tree before creating the new symlink (or, with
930 @code{--copy}, copying the new file).
934 Set the global strictness to @samp{foreign}. For more information, see
939 Set the global strictness to @samp{gnits}. For more information, see
944 Set the global strictness to @samp{gnu}. For more information, see
945 @ref{Gnits}. This is the default strictness.
949 Print a summary of the command line options and exit.
954 This disables the dependency tracking feature; see @ref{Dependencies}.
957 @opindex --include-deps
958 This enables the dependency tracking feature. This feature is enabled
959 by default. This option is provided for historical reasons only and
960 probably should not be used.
964 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
965 @file{configure.in}. This option causes it to only update those
966 @file{Makefile.in}s which are out of date with respect to one of their
970 @itemx --output-dir=@var{dir}
972 @opindex --output-dir
973 Put the generated @file{Makefile.in} in the directory @var{dir}.
974 Ordinarily each @file{Makefile.in} is created in the directory of the
975 corresponding @file{Makefile.am}. This option is used when making
982 Cause Automake to print information about which files are being read or
987 Print the version number of Automake and exit.
993 @samp{--Werror} will cause all warnings issued by @code{automake} to
994 become errors. Errors affect the exit status of @code{automake}, while
995 warnings do not. @samp{--Wno-error}, the default, causes warnings to be
996 treated as warnings only.
1000 @node configure, Top level, Invoking Automake, Top
1001 @chapter Scanning @file{configure.in}
1003 @cindex configure.in, scanning
1004 @cindex Scanning configure.in
1006 Automake scans the package's @file{configure.in} to determine certain
1007 information about the package. Some @code{autoconf} macros are required
1008 and some variables must be defined in @file{configure.in}. Automake
1009 will also use information from @file{configure.in} to further tailor its
1012 Automake also supplies some Autoconf macros to make the maintenance
1013 easier. These macros can automatically be put into your
1014 @file{aclocal.m4} using the @code{aclocal} program.
1017 * Requirements:: Configuration requirements
1018 * Optional:: Other things Automake recognizes
1019 * Invoking aclocal:: Auto-generating aclocal.m4
1020 * Macros:: Autoconf macros supplied with Automake
1021 * Extending aclocal:: Writing your own aclocal macros
1025 @node Requirements, Optional, configure, configure
1026 @section Configuration requirements
1028 @cindex Automake requirements
1029 @cindex Requirements of Automake
1031 The one real requirement of Automake is that your @file{configure.in}
1032 call @code{AM_INIT_AUTOMAKE}. This macro does several things which are
1033 required for proper Automake operation.
1034 @cvindex AM_INIT_AUTOMAKE
1036 Here are the other macros which Automake requires but which are not run
1037 by @code{AM_INIT_AUTOMAKE}:
1039 @cindex AC_OUTPUT, scanning
1043 Automake uses this to determine which files to create (@pxref{Output, ,
1044 Creating Output Files, autoconf, The Autoconf Manual}). Listed files
1045 named @code{Makefile} are treated as @file{Makefile}s. Other listed
1046 files are treated differently. Currently the only difference is that a
1047 @file{Makefile} is removed by @code{make distclean}, while other files
1048 are removed by @code{make clean}.
1049 @c FIXME: this is in violation of standards!
1053 You may need the following macros in some conditions, even though they
1057 @item AC_CHECK_TOOL([STRIP],[strip])
1058 @cindex STRIP, how to setup
1059 @cindex install-strip and STRIP
1060 @cvindex AC_CHECK_TOOL([STRIP],[strip])
1061 Installed binaries are usually stripped using @code{strip} when you run
1062 @code{make install-strip}. However @code{strip} might not be the
1063 right tool to use in cross-compilation environments, therefore
1064 Automake will honor the @code{STRIP} environment variable to overrule
1065 the program used to perform stripping. Automake will not set @code{STRIP}
1066 itself. If your package is not setup for cross-compilation you do not
1067 have to care (@code{strip} is ok), otherwise you can set @code{STRIP}
1068 automatically by calling @code{AC_CHECK_TOOL([STRIP],[strip])} from
1069 your @file{configure.in}.
1073 @node Optional, Invoking aclocal, Requirements, configure
1074 @section Other things Automake recognizes
1076 @cindex Macros Automake recognizes
1077 @cindex Recognized macros by Automake
1079 Automake will also recognize the use of certain macros and tailor the
1080 generated @file{Makefile.in} appropriately. Currently recognized macros
1081 and their effects are:
1084 @item AC_CONFIG_HEADER
1085 Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar
1086 to @code{AC_CONFIG_HEADER} (@pxref{Configuration Headers, ,
1087 Configuration Header Files, autoconf, The Autoconf Manual}), but does
1088 some useful Automake-specific work.
1089 @cvindex AC_CONFIG_HEADER
1091 @item AC_CONFIG_AUX_DIR
1092 Automake will look for various helper scripts, such as
1093 @file{mkinstalldirs}, in the directory named in this macro invocation.
1094 If not seen, the scripts are looked for in their @samp{standard}
1095 locations (either the top source directory, or in the source directory
1096 corresponding to the current @file{Makefile.am}, whichever is
1097 appropriate). @xref{Input, , Finding `configure' Input, autoconf, The
1099 @cvindex AC_CONFIG_AUX_DIR
1100 FIXME: give complete list of things looked for in this directory
1103 Automake will insert definitions for the variables defined by
1104 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
1105 or library. @xref{System Services, , System Services, autoconf, The
1107 @cvindex AC_PATH_XTRA
1109 @item AC_CANONICAL_HOST
1110 @itemx AC_CHECK_TOOL
1111 Automake will ensure that @file{config.guess} and @file{config.sub}
1112 exist. Also, the @file{Makefile} variables @samp{host_alias} and
1113 @samp{host_triplet} are introduced. See both @ref{Canonicalizing, ,
1114 Getting the Canonical System Type, autoconf, The Autoconf Manual}, and
1115 @ref{Generic Programs, , Generic Program Checks, autoconf, The Autoconf
1117 @c fixme xref autoconf docs.
1118 @cvindex AC_CANONICAL_HOST
1119 @cvindex AC_CHECK_TOOL
1121 @vindex host_triplet
1123 @item AC_CANONICAL_SYSTEM
1124 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
1125 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
1126 @xref{Canonicalizing, , Getting the Canonical System Type, autoconf, The
1128 @cvindex AC_CANONICAL_SYSTEM
1130 @vindex target_alias
1132 @item AC_FUNC_ALLOCA
1133 @itemx AC_FUNC_ERROR_AT_LINE
1134 @itemx AC_FUNC_FNMATCH
1135 @itemx AC_FUNC_GETLOADAVG
1136 @itemx AC_FUNC_MEMCMP
1137 @itemx AC_FUNC_MKTIME
1138 @itemx AC_FUNC_OBSTACK
1139 @itemx AC_FUNC_STRTOD
1140 @itemx AC_REPLACE_FUNCS
1141 @itemx AC_REPLACE_GNU_GETOPT
1142 @itemx AC_STRUCT_ST_BLOCKS
1143 @itemx AM_WITH_REGEX
1144 Automake will ensure that the appropriate dependencies are generated for
1145 the objects corresponding to these macros. Also, Automake will verify
1146 that the appropriate source files are part of the distribution. Note
1147 that Automake does not come with any of the C sources required to use
1148 these macros, so @code{automake -a} will not install the sources.
1149 @xref{A Library}, for more information. Also, see @ref{Particular
1150 Functions, , Particular Function Checks, autoconf, The Autoconf Manual}.
1151 @cvindex AC_FUNC_ALLOCA
1152 @cvindex AC_FUNC_ERROR_AT_LINE
1153 @cvindex AC_FUNC_FNMATCH
1154 @cvindex AC_FUNC_GETLOADAVG
1155 @cvindex AC_FUNC_MEMCMP
1156 @cvindex AC_FUNC_MKTIME
1157 @cvindex AC_FUNC_OBSTACK
1158 @cvindex AC_FUNC_STRTOD
1159 @cvindex AC_REPLACE_FUNCS
1160 @cvindex AC_REPLACE_GNU_GETOPT
1161 @cvindex AC_STRUCT_ST_BLOCKS
1162 @cvindex AM_WITH_REGEX
1165 Automake will detect statements which put @file{.o} files into
1166 @code{LIBOBJS}, and will treat these additional files as if they were
1167 discovered via @code{AC_REPLACE_FUNCS}. @xref{Generic Functions, ,
1168 Generic Function Checks, autoconf, The Autoconf Manual}.
1171 @item AC_PROG_RANLIB
1172 This is required if any libraries are built in the package.
1173 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1175 @cvindex AC_PROG_RANLIB
1178 This is required if any C++ source is included. @xref{Particular
1179 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1180 @cvindex AC_PROG_CXX
1183 This is required if any Fortran 77 source is included. This macro is
1184 distributed with Autoconf version 2.13 and later. @xref{Particular
1185 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1186 @cvindex AC_PROG_F77
1188 @item AC_F77_LIBRARY_LDFLAGS
1189 This is required for programs and shared libraries that are a mixture of
1190 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
1191 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
1192 @cvindex AC_F77_LIBRARY_LDFLAGS
1194 @item AC_PROG_LIBTOOL
1195 Automake will turn on processing for @code{libtool} (@pxref{Top, ,
1196 Introduction, libtool, The Libtool Manual}).
1197 @cvindex AC_PROG_LIBTOOL
1200 If a Yacc source file is seen, then you must either use this macro or
1201 define the variable @samp{YACC} in @file{configure.in}. The former is
1202 preferred (@pxref{Particular Programs, , Particular Program Checks,
1203 autoconf, The Autoconf Manual}).
1204 @cvindex AC_PROG_YACC
1208 If a Lex source file is seen, then this macro must be used.
1209 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1211 @cvindex AC_PROG_LEX
1213 @item AM_C_PROTOTYPES
1214 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
1215 @cvindex AM_C_PROTOTYPES
1217 @item AM_GNU_GETTEXT
1218 This macro is required for packages which use GNU gettext
1219 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1220 this macro it ensures that the package meets some of gettext's
1222 @cvindex AM_GNU_GETTEXT
1224 @item AM_MAINTAINER_MODE
1225 @opindex --enable-maintainer-mode
1226 This macro adds a @samp{--enable-maintainer-mode} option to
1227 @code{configure}. If this is used, @code{automake} will cause
1228 @samp{maintainer-only} rules to be turned off by default in the
1229 generated @file{Makefile.in}s. This macro is disallowed in @samp{Gnits}
1230 mode (@pxref{Gnits}). This macro defines the @samp{MAINTAINER_MODE}
1231 conditional, which you can use in your own @file{Makefile.am}.
1232 @cvindex AM_MAINTAINER_MODE
1235 @itemx AC_CHECK_TOOL
1236 @itemx AC_CHECK_PROG
1237 @itemx AC_CHECK_PROGS
1239 @itemx AC_PATH_PROGS
1240 For each of these macros, the first argument is automatically defined as
1241 a variable in each generated @file{Makefile.in}. @xref{Setting Output
1242 Variables, , Setting Output Variables, autoconf, The Autoconf Manual},
1243 and @ref{Generic Programs, , Generic Program Checks, autoconf, The
1246 @cvindex AC_CHECK_TOOL
1247 @cvindex AC_CHECK_PROG
1248 @cvindex AC_CHECK_PROGS
1249 @cvindex AC_PATH_PROG
1250 @cvindex AC_PATH_PROGS
1255 @node Invoking aclocal, Macros, Optional, configure
1256 @section Auto-generating aclocal.m4
1258 @cindex Invoking aclocal
1259 @cindex aclocal, Invoking
1261 Automake includes a number of Autoconf macros which can be used in your
1262 package; some of them are actually required by Automake in certain
1263 situations. These macros must be defined in your @file{aclocal.m4};
1264 otherwise they will not be seen by @code{autoconf}.
1266 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1267 files based on the contents of @file{configure.in}. This provides a
1268 convenient way to get Automake-provided macros, without having to
1269 search around. Also, the @code{aclocal} mechanism is extensible for use
1272 At startup, @code{aclocal} scans all the @file{.m4} files it can find,
1273 looking for macro definitions. Then it scans @file{configure.in}. Any
1274 mention of one of the macros found in the first step causes that macro,
1275 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1277 The contents of @file{acinclude.m4}, if it exists, are also
1278 automatically included in @file{aclocal.m4}. This is useful for
1279 incorporating local macros into @file{configure}.
1281 @code{aclocal} tries to be smart about looking for new @code{AC_DEFUN}s
1282 in the files it scans. It will warn if it finds duplicates. It also
1283 tries to copy the full text of the scanned file into @file{aclocal.m4},
1284 including both @samp{#} and @samp{dnl} comments. If you want to make a
1285 comment which will be completely ignored by @code{aclocal}, use
1286 @samp{##} as the comment leader.
1288 @code{aclocal} accepts the following options:
1291 @item --acdir=@var{dir}
1293 Look for the macro files in @var{dir} instead of the installation
1294 directory. This is typically used for debugging.
1298 Print a summary of the command line options and exit.
1302 Add the directory @var{dir} to the list of directories searched for
1305 @item --output=@var{file}
1307 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1309 @item --print-ac-dir
1310 @opindex --print-ac-dir
1311 Prints the name of the directory which @code{aclocal} will search to
1312 find the @file{.m4} files. When this option is given, normal processing
1313 is suppressed. This option can be used by a package to determine where
1314 to install a macro file.
1318 Print the names of the files it examines.
1322 Print the version number of Automake and exit.
1326 @node Macros, Extending aclocal, Invoking aclocal, configure
1327 @section Autoconf macros supplied with Automake
1329 @c consider generating this node automatically from m4 files.
1332 @item AM_AUTOMAKE_OPTIONS
1333 This takes a single argument which is a list of options which should be
1334 applied to every @file{Makefile.am} in the tree. The effect is as if
1335 each option were listed in @code{AUTOMAKE_OPTIONS}.
1337 @item AM_CONFIG_HEADER
1338 Automake will generate rules to automatically regenerate the config
1340 @cvindex AM_CONFIG_HEADER
1342 @item AM_ENABLE_MULTILIB
1343 This is used when a ``multilib'' library is being built. The first
1344 optional argument is the name of the @file{Makefile} being generated; it
1345 defaults to @samp{Makefile}. The second option argument is used to find
1346 the top source directory; it defaults to the empty string (generally
1347 this should not be used unless you are familiar with the internals).
1350 @item _AM_DEPENDENCIES
1351 @itemx AM_SET_DEPDIR
1353 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
1354 These macros are used to implement automake's automatic dependency
1355 tracking scheme. They are called automatically by automake when
1356 required, and there should be no need to invoke them manually.
1358 @item AM_C_PROTOTYPES
1359 Check to see if function prototypes are understood by the compiler. If
1360 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1361 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1362 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1363 values to implement automatic de-ANSI-fication.
1364 @cvindex AM_C_PROTOTYPES
1366 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1367 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1368 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1369 found in @file{<termios.h>}.
1370 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1372 @item AM_INIT_AUTOMAKE
1373 Runs many macros that most @file{configure.in}'s need. This macro has
1374 two required arguments, the package and the version number. By default
1375 this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}. This
1376 can be avoided by passing in a non-empty third argument.
1378 @item AM_MAKE_INCLUDE
1379 This macro is used to discover how the user's @code{make} handles
1380 @code{include} statements. This macro is automatically invoked when
1381 needed; there should be no need to invoke it manually.
1383 @item AM_PATH_LISPDIR
1384 Searches for the program @code{emacs}, and, if found, sets the output
1385 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1386 @cvindex AM_PATH_LISPDIR
1389 Use this macro when you have assembly code in your project. This will
1390 choose the assembler for you (by default the C compiler), and will set
1391 @code{ASFLAGS} if required.
1393 @item AM_PROG_CC_C_O
1394 This is like @code{AC_PROG_CC_C_O}, but it generates its results in the
1395 manner required by automake. You must use this instead of
1396 @code{AC_PROG_CC_C_O} when you need this functionality.
1398 @item AM_PROG_CC_STDC
1399 If the C compiler is not in ANSI C mode by default, try to add an option
1400 to output variable @code{CC} to make it so. This macro tries various
1401 options that select ANSI C on some system or another. It considers the
1402 compiler to be in ANSI C mode if it handles function prototypes correctly.
1404 If you use this macro, you should check after calling it whether the C
1405 compiler has been set to accept ANSI C; if not, the shell variable
1406 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1407 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1408 @code{ansi2knr} option (@pxref{ANSI}).
1411 @cindex HP-UX 10, lex problems
1412 @cindex lex problems with HP-UX 10
1413 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
1414 Program Checks, autoconf, The Autoconf Manual}), but uses the
1415 @code{missing} script on systems that do not have @code{lex}.
1416 @samp{HP-UX 10} is one such system.
1419 This macro finds the @code{gcj} program or causes an error. It sets
1420 @samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
1421 GNU Compiler Collection.
1422 @cvindex AM_PROG_GCJ
1424 @item AM_PROG_INSTALL_STRIP
1425 This is used to find a version of @code{install} which can be used to
1426 @code{strip} a program at installation time. This macro is
1427 automatically included when required.
1429 @item AM_SANITY_CHECK
1430 This checks to make sure that a file created in the build directory is
1431 newer than a file in the source directory. This can fail on systems
1432 where the clock is set incorrectly. This macro is automatically run
1433 from @code{AM_INIT_AUTOMAKE}.
1435 @item AM_SYS_POSIX_TERMIOS
1436 @cvindex am_cv_sys_posix_termios
1437 @cindex POSIX termios headers
1438 @cindex termios POSIX headers
1439 Check to see if POSIX termios headers and functions are available on the
1440 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1441 @samp{yes}. If not, set the variable to @samp{no}.
1443 @item AM_WITH_DMALLOC
1444 @cvindex WITH_DMALLOC
1445 @cindex dmalloc, support for
1446 @opindex --with-dmalloc
1448 @uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
1449 package. If the user configures with @samp{--with-dmalloc}, then define
1450 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
1454 @opindex --with-regex
1455 @cindex regex package
1457 Adds @samp{--with-regex} to the @code{configure} command line. If
1458 specified (the default), then the @samp{regex} regular expression
1459 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1460 @samp{WITH_REGEX} is defined.. If @samp{--without-regex} is given, then
1461 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1462 into @samp{LIBOBJS}.
1467 @node Extending aclocal, , Macros, configure
1468 @section Writing your own aclocal macros
1470 @cindex aclocal, extending
1471 @cindex Extending aclocal
1473 The @code{aclocal} program doesn't have any built-in knowledge of any
1474 macros, so it is easy to extend it with your own macros.
1476 This is mostly used for libraries which want to supply their own
1477 Autoconf macros for use by other programs. For instance the
1478 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1479 should be used by any package using @code{gettext}. When the library is
1480 installed, it installs this macro so that @code{aclocal} will find it.
1482 A file of macros should be a series of @code{AC_DEFUN}'s. The
1483 @code{aclocal} programs also understands @code{AC_REQUIRE}, so it is
1484 safe to put each macro in a separate file. @xref{Prerequisite Macros, ,
1485 , autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
1486 autoconf, The Autoconf Manual}.
1488 A macro file's name should end in @file{.m4}. Such files should be
1489 installed in @file{$(datadir)/aclocal}.
1492 @node Top level, Alternative, configure, Top
1493 @chapter The top-level @file{Makefile.am}
1495 @cindex SUBDIRS, explained
1497 In packages with subdirectories, the top level @file{Makefile.am} must
1498 tell Automake which subdirectories are to be built. This is done via
1499 the @code{SUBDIRS} variable.
1502 The @code{SUBDIRS} macro holds a list of subdirectories in which
1503 building of various sorts can occur. Many targets (e.g. @code{all}) in
1504 the generated @file{Makefile} will run both locally and in all specified
1505 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1506 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1507 (after configuration). This allows inclusion of libraries from packages
1508 which do not use Automake (such as @code{gettext}). The directories
1509 mentioned in @code{SUBDIRS} must be direct children of the current
1510 directory. For instance, you cannot put @samp{src/subdir} into
1513 In packages that use subdirectories, the top-level @file{Makefile.am} is
1514 often very short. For instance, here is the @file{Makefile.am} from the
1515 GNU Hello distribution:
1518 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1519 SUBDIRS = doc intl po src tests
1522 @cindex SUBDIRS, overriding
1523 @cindex Overriding SUBDIRS
1525 It is possible to override the @code{SUBDIRS} variable if, like in the
1526 case of GNU @code{Inetutils}, you want to only build a subset of the
1527 entire package. In your @file{Makefile.am} include:
1530 SUBDIRS = @@MY_SUBDIRS@@
1533 Then in your @file{configure.in} you can specify:
1536 MY_SUBDIRS="src doc lib po"
1537 AC_SUBST(MY_SUBDIRS)
1540 (Note that we don't use the variable name @code{SUBDIRS} in our
1541 @file{configure.in}; that would cause Automake to believe that every
1542 @file{Makefile.in} should recurse into the listed subdirectories.)
1544 The upshot of this is that Automake is tricked into building the package
1545 to take the subdirs, but doesn't actually bind that list until
1546 @code{configure} is run.
1548 Although the @code{SUBDIRS} macro can contain configure substitutions
1549 (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
1550 contents of this variable.
1552 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1553 @code{AC_PROG_MAKE_SET}. When Automake invokes @code{make} in a
1554 subdirectory, it uses the value of the @code{MAKE} variable. It passes
1555 the value of the variable @code{AM_MAKEFLAGS} to the @code{make}
1556 invocation; this can be set in @file{Makefile.am} if there are flags you
1557 must always pass to @code{make}.
1561 The use of @code{SUBDIRS} is not restricted to just the top-level
1562 @file{Makefile.am}. Automake can be used to construct packages of
1565 By default, Automake generates @file{Makefiles} which work depth-first
1566 (@samp{postfix}). However, it is possible to change this ordering. You
1567 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
1568 putting @samp{.} first will cause a @samp{prefix} ordering of
1569 directories. All @samp{clean} targets are run in reverse order of build
1572 Sometimes, such as when running @code{make dist}, you want all possible
1573 subdirectories to be examined. In this case Automake will use
1574 @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to
1575 recurse. This variable will also be used when the user runs
1576 @code{distclean} or @code{maintainer-clean}. It should be set to the
1577 full list of subdirectories in the project. If this macro is not set,
1578 Automake will attempt to set it for you.
1581 @node Alternative, Rebuilding, Top level, Top
1582 @chapter An Alternative Approach to Subdirectories
1584 If you've ever read Peter Miller's excellent paper,
1585 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
1586 Recursive Make Considered Harmful}, the preceding section on the use of
1587 subdirectories will probably come as unwelcome advice. For those who
1588 haven't read the paper, Miller's main thesis is that recursive
1589 @code{make} invocations are both slow and error-prone.
1591 Automake provides sufficient cross-directory support @footnote{We
1592 believe. This work is new and there are probably warts.
1593 @xref{Introduction}, for information on reporting bugs.} to enable you
1594 to write a single @file{Makefile.am} for a complex multi-directory
1598 By default an installable file specified in a subdirectory will have its
1599 directory name stripped before installation. For instance, in this
1600 example, the header file will be installed as
1601 @file{$(includedir)/stdio.h}:
1604 include_HEADERS = inc/stdio.h
1608 @cindex Path stripping, avoiding
1609 @cindex Avoiding path stripping
1611 However, the @samp{nobase_} prefix can be used to circumvent this path
1612 stripping. In this example, the header file will be installed as
1613 @file{$(includedir)/sys/types.h}:
1616 nobase_include_HEADERS = sys/types.h
1620 @node Rebuilding, Programs, Alternative, Top
1621 @chapter Rebuilding Makefiles
1623 Automake generates rules to automatically rebuild @file{Makefile}s,
1624 @file{configure}, and other derived files like @file{Makefile.in}.
1626 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.in}, then
1627 these automatic rebuilding rules are only enabled in maintainer mode.
1629 Sometimes you need to run @code{aclocal} with an argument like @code{-I}
1630 to tell it where to find @file{.m4} files. Since sometimes @code{make}
1631 will automatically run @code{aclocal}, you need a way to specify these
1632 arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this
1633 holds arguments which are passed verbatim to @code{aclocal}. This macro
1634 is only useful in the top-level @file{Makefile.am}.
1635 @vindex ACLOCAL_AMFLAGS
1638 @node Programs, Other objects, Rebuilding, Top
1639 @chapter Building Programs and Libraries
1641 A large part of Automake's functionality is dedicated to making it easy
1642 to build programs and libraries.
1645 * A Program:: Building a program
1646 * A Library:: Building a library
1647 * A Shared Library:: Building a Libtool library
1648 * Program and Library Variables::
1649 Variables controlling program and
1651 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1652 * Program variables:: Variables used when building a program
1653 * Yacc and Lex:: Yacc and Lex support
1655 * Assembly Support::
1656 * Fortran 77 Support::
1658 * Support for Other Languages::
1659 * ANSI:: Automatic de-ANSI-fication
1660 * Dependencies:: Automatic dependency tracking
1661 * EXEEXT:: Support for executable extensions
1665 @node A Program, A Library, Programs, Programs
1666 @section Building a program
1668 @subsection Introductory blathering
1670 @cindex PROGRAMS, bindir
1671 @vindex bin_PROGRAMS
1672 @vindex sbin_PROGRAMS
1673 @vindex libexec_PROGRAMS
1674 @vindex pkglib_PROGRAMS
1675 @vindex noinst_PROGRAMS
1677 In a directory containing source that gets built into a program (as
1678 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
1679 can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
1680 @code{pkglibdir}, or not at all (@samp{noinst}). They can also be built
1681 only for @code{make check}, in which case the prefix is @samp{check}.
1686 bin_PROGRAMS = hello
1689 In this simple case, the resulting @file{Makefile.in} will contain code
1690 to generate a program named @code{hello}.
1692 Associated with each program are several assisting variables which are
1693 named after the program. These variables are all optional, and have
1694 reasonable defaults. Each variable, its use, and default is spelled out
1695 below; we use the ``hello'' example throughout.
1697 The variable @code{hello_SOURCES} is used to specify which source files
1698 get built into an executable:
1701 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1704 This causes each mentioned @samp{.c} file to be compiled into the
1705 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1707 @cindex _SOURCES primary, defined
1708 @cindex SOURCES primary, defined
1709 @cindex Primary variable, SOURCES
1711 If @samp{hello_SOURCES} is not specified, then it defaults to the single
1712 file @file{hello.c}; that is, the default is to compile a single C file
1713 whose base name is the name of the program itself. (This is a terrible
1714 default but we are stuck with it for historical reasons.)
1718 Multiple programs can be built in a single directory. Multiple programs
1719 can share a single source file, which must be listed in each
1720 @samp{_SOURCES} definition.
1722 @cindex Header files in _SOURCES
1723 @cindex _SOURCES and header files
1725 Header files listed in a @samp{_SOURCES} definition will be included in
1726 the distribution but otherwise ignored. In case it isn't obvious, you
1727 should not include the header file generated by @file{configure} in a
1728 @samp{_SOURCES} variable; this file should not be distributed. Lex
1729 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1732 @subsection Conditional compilations
1734 You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
1735 @samp{_SOURCES} variable. The reason for this is a bit hard to explain,
1736 but suffice to say that it simply won't work. Automake will give an
1737 error if you try to do this.
1739 @cindex EXTRA_prog_SOURCES, defined
1741 Automake must know all the source files that could possibly go into a
1742 program, even if not all the files are built in every circumstance.
1743 Any files which are only conditionally built should be listed in the
1744 appropriate @samp{EXTRA_} variable. For instance, if
1745 @file{hello-linux.c} were conditionally included in @code{hello}, the
1746 @file{Makefile.am} would contain:
1749 EXTRA_hello_SOURCES = hello-linux.c
1752 In this case, @file{hello-linux.o} would be added, via a
1753 @file{configure} substitution, to @code{hello_LDADD} in order to cause
1754 it to be built and linked in.
1756 An often simpler way to compile source files conditionally is to use
1757 Automake conditionals. For instance, you could use this construct to
1758 conditionally use @file{hello-linux.c} or @file{hello-generic.c} as the
1759 basis for your program @file{hello}:
1763 hello_SOURCES = hello-linux.c
1765 hello_SOURCES = hello-generic.c
1769 When using conditionals like this you don't need to use the
1770 @samp{EXTRA_} variable, because Automake will examine the contents of
1771 each variable to construct the complete list of source files.
1773 Sometimes it is useful to determine the programs that are to be built at
1774 configure time. For instance, GNU @code{cpio} only builds @code{mt} and
1775 @code{rmt} under special circumstances.
1777 @cindex EXTRA_PROGRAMS, defined
1779 In this case, you must notify Automake of all the programs that can
1780 possibly be built, but at the same time cause the generated
1781 @file{Makefile.in} to use the programs specified by @code{configure}.
1782 This is done by having @code{configure} substitute values into each
1783 @samp{_PROGRAMS} definition, while listing all optionally built programs
1784 in @code{EXTRA_PROGRAMS}.
1785 @vindex EXTRA_PROGRAMS
1787 Of course you can use Automake conditionals to determine the programs to
1790 @subsection Linking the program
1792 If you need to link against libraries that are not found by
1793 @code{configure}, you can use @code{LDADD} to do so. This variable
1794 actually can be used to add any options to the linker command line.
1797 @cindex prog_LDADD, defined
1799 Sometimes, multiple programs are built in one directory but do not share
1800 the same link-time requirements. In this case, you can use the
1801 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1802 program as it appears in some @samp{_PROGRAMS} variable, and usually
1803 written in lowercase) to override the global @code{LDADD}. If this
1804 variable exists for a given program, then that program is not linked
1808 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
1809 linked against the library @file{libcpio.a}. However, @code{rmt} is
1810 built in the same directory, and has no such link requirement. Also,
1811 @code{mt} and @code{rmt} are only built on certain architectures. Here
1812 is what cpio's @file{src/Makefile.am} looks like (abridged):
1815 bin_PROGRAMS = cpio pax @@MT@@
1816 libexec_PROGRAMS = @@RMT@@
1817 EXTRA_PROGRAMS = mt rmt
1819 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1822 cpio_SOURCES = @dots{}
1823 pax_SOURCES = @dots{}
1824 mt_SOURCES = @dots{}
1825 rmt_SOURCES = @dots{}
1828 @cindex _LDFLAGS, defined
1830 @samp{@var{prog}_LDADD} is inappropriate for passing program-specific
1831 linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
1832 @samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
1836 @cindex _DEPENDENCIES, defined
1838 It is also occasionally useful to have a program depend on some other
1839 target which is not actually part of that program. This can be done
1840 using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
1841 on the contents of such a variable, but no further interpretation is
1844 If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
1845 Automake. The automatically-assigned value is the contents of
1846 @samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
1847 @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
1848 configure substitutions that are left in are only @samp{@@LIBOBJS@@} and
1849 @samp{@@ALLOCA@@}; these are left because it is known that they will not
1850 cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
1854 @node A Library, A Shared Library, A Program, Programs
1855 @section Building a library
1857 @cindex _LIBRARIES primary, defined
1858 @cindex LIBRARIES primary, defined
1859 @cindex Primary variable, LIBRARIES
1861 @vindex lib_LIBRARIES
1862 @vindex pkglib_LIBRARIES
1863 @vindex noinst_LIBRARIES
1865 Building a library is much like building a program. In this case, the
1866 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
1867 @code{libdir} or @code{pkglibdir}.
1869 @xref{A Shared Library}, for information on how to build shared
1870 libraries using Libtool and the @samp{LTLIBRARIES} primary.
1872 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
1873 For instance to create a library named @file{libcpio.a}, but not install
1874 it, you would write:
1877 noinst_LIBRARIES = libcpio.a
1880 The sources that go into a library are determined exactly as they are
1881 for programs, via the @samp{_SOURCES} variables. Note that the library
1882 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
1883 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
1884 not @samp{liblob.a_SOURCES}.
1886 @cindex _LIBADD primary, defined
1887 @cindex LIBADD primary, defined
1888 @cindex Primary variable, LIBADD
1890 Extra objects can be added to a library using the
1891 @samp{@var{library}_LIBADD} variable. This should be used for objects
1892 determined by @code{configure}. Again from @code{cpio}:
1897 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
1900 In addition, sources for extra objects that will not exist until
1901 configure-time must be added to the @code{BUILT_SOURCES} variable
1905 @node A Shared Library, Program and Library Variables, A Library, Programs
1906 @section Building a Shared Library
1908 @cindex Shared libraries, support for
1910 Building shared libraries is a relatively complex matter. For this
1911 reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
1912 Libtool Manual}) was created to help build shared libraries in a
1913 platform-independent way.
1915 @cindex _LTLIBRARIES primary, defined
1916 @cindex LTLIBRARIES primary, defined
1917 @cindex Primary variable, LTLIBRARIES
1918 @cindex Example of shared libraries
1920 @cindex suffix .la, defined
1922 Automake uses Libtool to build libraries declared with the
1923 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
1924 of shared libraries to build. For instance, to create a library named
1925 @file{libgettext.a} and its corresponding shared libraries, and install
1926 them in @samp{libdir}, write:
1929 lib_LTLIBRARIES = libgettext.la
1932 @vindex lib_LTLIBRARIES
1933 @vindex pkglib_LTLIBRARIES
1934 @vindex noinst_LTLIBRARIES
1935 @vindex check_LTLIBRARIES
1937 @cindex check_LTLIBRARIES, not allowed
1939 Note that shared libraries @emph{must} be installed in order to work
1940 properly, so @code{check_LTLIBRARIES} is not allowed. However,
1941 @code{noinst_LTLIBRARIES} is allowed. This feature should be used for
1942 libtool ``convenience libraries''.
1944 @cindex suffix .lo, defined
1946 For each library, the @samp{@var{library}_LIBADD} variable contains the
1947 names of extra libtool objects (@file{.lo} files) to add to the shared
1948 library. The @samp{@var{library}_LDFLAGS} variable contains any
1949 additional libtool flags, such as @samp{-version-info} or
1952 @cindex @@LTLIBOBJS@@, special handling
1954 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
1955 library must use @code{@@LTLIBOBJS@@}. This is required because the
1956 object files that libtool operates on do not necessarily end in
1957 @file{.o}. The libtool manual contains more details on this topic.
1959 For libraries installed in some directory, Automake will automatically
1960 supply the appropriate @samp{-rpath} option. However, for libraries
1961 determined at configure time (and thus mentioned in
1962 @code{EXTRA_LTLIBRARIES}), Automake does not know the eventual
1963 installation directory; for such libraries you must add the
1964 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
1967 Ordinarily, Automake requires that a shared library's name start with
1968 @samp{lib}. However, if you are building a dynamically loadable module
1969 then you might wish to use a "nonstandard" name. In this case, put
1970 @code{-module} into the @samp{_LDFLAGS} variable.
1972 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
1973 libtool, The Libtool Manual}, for more information.
1976 @node Program and Library Variables, LIBOBJS, A Shared Library, Programs
1977 @section Program and Library Variables
1979 Associated with each program are a collection of variables which can be
1980 used to modify how that program is built. There is a similar list of
1981 such variables for each library. The canonical name of the program (or
1982 library) is used as a base for naming these variables.
1984 In the list below, we use the name ``maude'' to refer to the program or
1985 library. In your @file{Makefile.am} you would replace this with the
1986 canonical name of your program. This list also refers to ``maude'' as a
1987 program, but in general the same rules apply for both static and dynamic
1988 libraries; the documentation below notes situations where programs and
1993 This variable, if it exists, lists all the source files which are
1994 compiled to build the program. These files are added to the
1995 distribution by default. When building the program, Automake will cause
1996 each source file to be compiled to a single @file{.o} file (or
1997 @file{.lo} when using libtool). Normally these object files are named
1998 after the source file, but other factors can change this. If a file in
1999 the @samp{_SOURCES} variable has an unrecognized extension, Automake
2000 will do one of two things with it. If a suffix rule exists for turning
2001 files with the unrecognized extension into @file{.o} files, then
2002 automake will treat this file as it will any other source file
2003 (@pxref{Support for Other Languages}). Otherwise, the file will be
2004 ignored as though it were a header file.
2006 The prefixes @samp{dist_} and @samp{nodist_} can be used to control
2007 whether files listed in a @samp{_SOURCES} variable are distributed.
2008 @samp{dist_} is redundant, as sources are distributed by default, but it
2009 can be specified for clarity if desired.
2011 It is possible to have both @samp{dist_} and @samp{nodist_} variants of
2012 a given @samp{_SOURCES} variable at once; this lets you easily
2013 distribute some files and not others, for instance:
2016 nodist_maude_SOURCES = nodist.c
2017 dist_maude_SOURCES = dist-me.c
2020 By default the output file (on Unix systems, the @file{.o} file) will be
2021 put into the current build directory. However, if the option
2022 @code{subdir-objects} is in effect in the current directory then the
2023 @file{.o} file will be put into the subdirectory named after the source
2024 file. For instance, with @code{subdir-objects} enabled,
2025 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
2026 people prefer this mode of operation. You can specify
2027 @code{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
2028 @cindex Subdirectory, objects in
2029 @cindex Objects in subdirectory
2032 @item EXTRA_maude_SOURCES
2033 Automake needs to know the list of files you intend to compile
2034 @emph{statically}. For one thing, this is the only way Automake has of
2035 knowing what sort of language support a given @file{Makefile.in}
2036 requires. @footnote{There are other, more obscure reasons reasons for
2037 this limitation as well.} This means that, for example, you can't put a
2038 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
2039 variable. If you intend to conditionally compile source files and use
2040 @file{configure} to substitute the appropriate object names into, e.g.,
2041 @samp{_LDADD} (see below), then you should list the corresponding source
2042 files in the @samp{EXTRA_} variable.
2044 This variable also supports @samp{dist_} and @samp{nodist_} prefixes,
2045 e.g., @samp{nodist_EXTRA_maude_SOURCES}.
2048 A static library is created by default by invoking @code{$(AR) cru}
2049 followed by the name of the library and then the objects being put into
2050 the library. You can override this by setting the @samp{_AR} variable.
2051 This is usually used with C++; some C++ compilers require a special
2052 invocation in order to instantiate all the templates which should go
2053 into a library. For instance, the SGI C++ compiler likes this macro set
2056 libmaude_a_AR = $(CXX) -ar -o
2060 Extra objects can be added to a static library using the @samp{_LIBADD}
2061 variable. This should be used for objects determined by
2062 @code{configure}. Note that @samp{_LIBADD} is not used for shared
2063 libraries; there you must use @samp{_LDADD}.
2066 Extra objects can be added to a shared library or a program by listing
2067 them in the @samp{_LDADD} variable. This should be used for objects
2068 determined by @code{configure}.
2070 @samp{_LDADD} is inappropriate for passing program-specific linker flags
2071 (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen}).
2072 Use the @samp{_LDFLAGS} variable for this purpose.
2074 For instance, if your @file{configure.in} uses @code{AC_PATH_XTRA}, you
2075 could link your program against the X libraries like so:
2078 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
2082 This variable is used to pass extra flags to the link step of a program
2083 or a shared library.
2086 You can override the linker on a per-program basis. By default the
2087 linker is chosen according to the languages used by the program. For
2088 instance, a program that includes C++ source code would use the C++
2089 compiler to link. The @samp{_LINK} variable must hold the name of a
2090 command which can be passed all the @file{.o} file names as arguments.
2091 Note that the name of the underlying program is @emph{not} passed to
2092 @samp{_LINK}; typically one uses @samp{$@@}:
2095 maude_LINK = $(CCLD) -magic -o $@@
2099 Automake allows you to set compilation flags on a per-program (or
2100 per-library) basis. A single source file can be included in several
2101 programs, and it will potentially be compiled with different flags for
2102 each program. This works for any language directly supported by
2103 Automake. The flags are @samp{_CFLAGS}, @samp{_CXXFLAGS},
2104 @samp{_OBJCFLAGS}, @samp{_YFLAGS}, @samp{_ASFLAGS}, @samp{_FFLAGS},
2105 @samp{_RFLAGS}, and @samp{_GCJFLAGS}.
2107 When using a per-program compilation flag, Automake will choose a
2108 different name for the intermediate object files. Ordinarily a file
2109 like @file{sample.c} will be compiled to produce @file{sample.o}.
2110 However, if the program's @samp{_CFLAGS} variable is set, then the
2111 object file will be named, for instance, @file{maude-sample.o}.
2113 In compilations with per-program flags, the ordinary @samp{AM_} form of
2114 the flags variable is @emph{not} automatically included in the
2115 compilation (however, the user form of the variable @emph{is} included).
2116 So for instance, if you want the hypothetical @file{maude} compilations
2117 to also use the value of @samp{AM_CFLAGS}, you would need to write:
2120 maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
2123 @item maude_DEPENDENCIES
2124 It is also occasionally useful to have a program depend on some other
2125 target which is not actually part of that program. This can be done
2126 using the @samp{_DEPENDENCIES} variable. Each program depends on the
2127 contents of such a variable, but no further interpretation is done.
2129 If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake.
2130 The automatically-assigned value is the contents of @samp{_LDADD}, with
2131 most configure substitutions, @samp{-l}, @samp{-L}, @samp{-dlopen} and
2132 @samp{-dlpreopen} options removed. The configure substitutions that are
2133 left in are only @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are
2134 left because it is known that they will not cause an invalid value for
2135 @samp{_DEPENDENCIES} to be generated.
2137 @item maude_SHORTNAME
2138 On some platforms the allowable file names are very short. In order to
2139 support these systems and per-program compilation flags at the same
2140 time, Automake allows you to set a ``short name'' which will influence
2141 how intermediate object files are named. For instance, if you set
2142 @samp{maude_SHORTNAME} to @samp{m}, then in the above per-program
2143 compilation flag example the object file would be named
2144 @file{m-sample.o} rather than @file{maude-sample.o}. This facility is
2145 rarely needed in practice, and we recommend avoiding it until you find
2150 @node LIBOBJS, Program variables, Program and Library Variables, Programs
2151 @section Special handling for LIBOBJS and ALLOCA
2153 @cindex @@LIBOBJS@@, special handling
2154 @cindex @@ALLOCA@@, special handling
2156 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
2157 @code{@@ALLOCA@@}, and uses this information, plus the list of
2158 @code{LIBOBJS} files derived from @file{configure.in} to automatically
2159 include the appropriate source files in the distribution (@pxref{Dist}).
2160 These source files are also automatically handled in the
2161 dependency-tracking scheme; see @xref{Dependencies}.
2163 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
2164 @samp{_LDADD} or @samp{_LIBADD} variable.
2167 @node Program variables, Yacc and Lex, LIBOBJS, Programs
2168 @section Variables used when building a program
2170 Occasionally it is useful to know which @file{Makefile} variables
2171 Automake uses for compilations; for instance you might need to do your
2172 own compilation in some special cases.
2174 Some variables are inherited from Autoconf; these are @code{CC},
2175 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
2179 There are some additional variables which Automake itself defines:
2183 The contents of this macro are passed to every compilation which invokes
2184 the C preprocessor; it is a list of arguments to the preprocessor. For
2185 instance, @samp{-I} and @samp{-D} options should be listed here.
2187 Automake already provides some @samp{-I} options automatically. In
2188 particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I}
2189 pointing to the directory holding @file{config.h} (if you've used
2190 @code{AC_CONFIG_HEADER} or @code{AM_CONFIG_HEADER}). You can disable
2191 the default @samp{-I} options using the @samp{nostdinc} option.
2194 This does the same job as @samp{AM_CPPFLAGS}. It is an older name for
2195 the same functionality. This macro is deprecated; we suggest using
2196 @samp{AM_CPPFLAGS} instead.
2199 This is the variable which the @file{Makefile.am} author can use to pass
2200 in additional C compiler flags. It is more fully documented elsewhere.
2201 In some situations, this is not used, in preference to the
2202 per-executable (or per-library) @code{CFLAGS}.
2205 This is the command used to actually compile a C source file. The
2206 filename is appended to form the complete command line.
2209 This is the command used to actually link a C program. It already
2210 includes @samp{-o $@@} and the usual variable references (for instance,
2211 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
2212 and libraries to link in.
2216 @node Yacc and Lex, C++ Support, Program variables, Programs
2217 @section Yacc and Lex support
2219 Automake has somewhat idiosyncratic support for Yacc and Lex.
2221 Automake assumes that the @file{.c} file generated by @code{yacc} (or
2222 @code{lex}) should be named using the basename of the input file. That
2223 is, for a yacc source file @file{foo.y}, Automake will cause the
2224 intermediate file to be named @file{foo.c} (as opposed to
2225 @file{y.tab.c}, which is more traditional).
2227 The extension of a yacc source file is used to determine the extension
2228 of the resulting @samp{C} or @samp{C++} file. Files with the extension
2229 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
2230 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
2233 Likewise, lex source files can be used to generate @samp{C} or
2234 @samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
2235 @samp{.lxx} are recognized.
2237 You should never explicitly mention the intermediate (@samp{C} or
2238 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
2241 The intermediate files generated by @code{yacc} (or @code{lex}) will be
2242 included in any distribution that is made. That way the user doesn't
2243 need to have @code{yacc} or @code{lex}.
2245 If a @code{yacc} source file is seen, then your @file{configure.in} must
2246 define the variable @samp{YACC}. This is most easily done by invoking
2247 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
2248 Program Checks, autoconf, The Autoconf Manual}).
2250 When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
2251 @samp{AM_YFLAGS}. The former is a user variable and the latter is
2252 intended for the @file{Makefile.am} author.
2254 Similarly, if a @code{lex} source file is seen, then your
2255 @file{configure.in} must define the variable @samp{LEX}. You can use
2256 @samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
2257 Program Checks, autoconf, The Autoconf Manual}), but using
2258 @code{AM_PROG_LEX} macro (@pxref{Macros}) is recommended.
2260 When @code{lex} is invoked, it is passed @samp{LFLAGS} and
2261 @samp{AM_LFLAGS}. The former is a user variable and the latter is
2262 intended for the @file{Makefile.am} author.
2267 @cindex yacc, multiple parsers
2268 @cindex Multiple yacc parsers
2269 @cindex Multiple lex lexers
2270 @cindex lex, multiple lexers
2273 Automake makes it possible to include multiple @code{yacc} (or
2274 @code{lex}) source files in a single program. Automake uses a small
2275 program called @code{ylwrap} to run @code{yacc} (or @code{lex}) in a
2276 subdirectory. This is necessary because yacc's output filename is
2277 fixed, and a parallel make could conceivably invoke more than one
2278 instance of @code{yacc} simultaneously. The @code{ylwrap} program is
2279 distributed with Automake. It should appear in the directory specified
2280 by @samp{AC_CONFIG_AUX_DIR} (@pxref{Input, , Finding `configure' Input,
2281 autoconf, The Autoconf Manual}), or the current directory if that macro
2282 is not used in @file{configure.in}.
2284 For @code{yacc}, simply managing locking is insufficient. The output of
2285 @code{yacc} always uses the same symbol names internally, so it isn't
2286 possible to link two @code{yacc} parsers into the same executable.
2288 We recommend using the following renaming hack used in @code{gdb}:
2290 #define yymaxdepth c_maxdepth
2291 #define yyparse c_parse
2293 #define yyerror c_error
2294 #define yylval c_lval
2295 #define yychar c_char
2296 #define yydebug c_debug
2297 #define yypact c_pact
2304 #define yyexca c_exca
2305 #define yyerrflag c_errflag
2306 #define yynerrs c_nerrs
2310 #define yy_yys c_yys
2311 #define yystate c_state
2314 #define yy_yyv c_yyv
2316 #define yylloc c_lloc
2317 #define yyreds c_reds
2318 #define yytoks c_toks
2319 #define yylhs c_yylhs
2320 #define yylen c_yylen
2321 #define yydefred c_yydefred
2322 #define yydgoto c_yydgoto
2323 #define yysindex c_yysindex
2324 #define yyrindex c_yyrindex
2325 #define yygindex c_yygindex
2326 #define yytable c_yytable
2327 #define yycheck c_yycheck
2328 #define yyname c_yyname
2329 #define yyrule c_yyrule
2332 For each define, replace the @samp{c_} prefix with whatever you like.
2333 These defines work for @code{bison}, @code{byacc}, and traditional
2334 @code{yacc}s. If you find a parser generator that uses a symbol not
2335 covered here, please report the new name so it can be added to the list.
2338 @node C++ Support, Assembly Support, Yacc and Lex, Programs
2339 @section C++ Support
2342 @cindex Support for C++
2344 Automake includes full support for C++.
2346 Any package including C++ code must define the output variable
2347 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
2348 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
2349 Program Checks, autoconf, The Autoconf Manual}).
2351 A few additional variables are defined when a C++ source file is seen:
2355 The name of the C++ compiler.
2358 Any flags to pass to the C++ compiler.
2361 The maintainer's variant of @code{CXXFLAGS}.
2364 The command used to actually compile a C++ source file. The file name
2365 is appended to form the complete command line.
2368 The command used to actually link a C++ program.
2372 @node Assembly Support, Fortran 77 Support, C++ Support, Programs
2373 @section Assembly Support
2375 Automake includes some support for assembly code.
2377 The variable @code{AS} holds the name of the compiler used to build
2378 assembly code. This compiler must work a bit like a C compiler; in
2379 particular it must accept @samp{-c} and @samp{-o}. The value of
2380 @code{ASFLAGS} is passed to the compilation.
2384 You are required to set @code{AS} and @code{ASFLAGS} via
2385 @file{configure.in}. The autoconf macro @code{AM_PROG_AS} will do this
2386 for you. Unless they are already set, it simply sets @code{AS} to the C
2387 compiler and @code{ASFLAGS} to the C compiler flags.
2389 Only the suffixes @samp{.s} and @samp{.S} are recognized by
2390 @code{automake} as being files containing assembly code.
2393 @node Fortran 77 Support, Java Support, Assembly Support, Programs
2394 @comment node-name, next, previous, up
2395 @section Fortran 77 Support
2397 @cindex Fortran 77 support
2398 @cindex Support for Fortran 77
2400 Automake includes full support for Fortran 77.
2402 Any package including Fortran 77 code must define the output variable
2403 @samp{F77} in @file{configure.in}; the simplest way to do this is to use
2404 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
2405 Program Checks, autoconf, The Autoconf Manual}). @xref{Fortran 77 and
2408 A few additional variables are defined when a Fortran 77 source file is
2414 The name of the Fortran 77 compiler.
2417 Any flags to pass to the Fortran 77 compiler.
2420 The maintainer's variant of @code{FFLAGS}.
2423 Any flags to pass to the Ratfor compiler.
2426 The maintainer's variant of @code{RFLAGS}.
2429 The command used to actually compile a Fortran 77 source file. The file
2430 name is appended to form the complete command line.
2433 The command used to actually link a pure Fortran 77 program or shared
2438 Automake can handle preprocessing Fortran 77 and Ratfor source files in
2439 addition to compiling them@footnote{Much, if not most, of the
2440 information in the following sections pertaining to preprocessing
2441 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
2442 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
2443 also contains some support for creating programs and shared libraries
2444 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
2445 Fortran 77 With C and C++}).
2447 These issues are covered in the following sections.
2450 * Preprocessing Fortran 77::
2451 * Compiling Fortran 77 Files::
2452 * Mixing Fortran 77 With C and C++::
2453 * Fortran 77 and Autoconf::
2457 @node Preprocessing Fortran 77, Compiling Fortran 77 Files, Fortran 77 Support, Fortran 77 Support
2458 @comment node-name, next, previous, up
2459 @subsection Preprocessing Fortran 77
2461 @cindex Preprocessing Fortran 77
2462 @cindex Fortran 77, Preprocessing
2463 @cindex Ratfor programs
2465 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
2466 rule runs just the preprocessor to convert a preprocessable Fortran 77
2467 or Ratfor source file into a strict Fortran 77 source file. The precise
2468 command used is as follows:
2473 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2476 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2481 @node Compiling Fortran 77 Files, Mixing Fortran 77 With C and C++, Preprocessing Fortran 77, Fortran 77 Support
2482 @comment node-name, next, previous, up
2483 @subsection Compiling Fortran 77 Files
2485 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
2486 @file{N.r} by running the Fortran 77 compiler. The precise command used
2492 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
2495 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2498 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2503 @node Mixing Fortran 77 With C and C++, Fortran 77 and Autoconf, Compiling Fortran 77 Files, Fortran 77 Support
2504 @comment node-name, next, previous, up
2505 @subsection Mixing Fortran 77 With C and C++
2507 @cindex Fortran 77, mixing with C and C++
2508 @cindex Mixing Fortran 77 with C and C++
2509 @cindex Linking Fortran 77 with C and C++
2511 @cindex Mixing Fortran 77 with C and/or C++
2513 Automake currently provides @emph{limited} support for creating programs
2514 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
2515 However, there are many other issues related to mixing Fortran 77 with
2516 other languages that are @emph{not} (currently) handled by Automake, but
2517 that are handled by other packages@footnote{For example,
2518 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
2519 addresses all of these inter-language issues, and runs under nearly all
2520 Fortran 77, C and C++ compilers on nearly all platforms. However,
2521 @code{cfortran} is not yet Free Software, but it will be in the next
2525 Automake can help in two ways:
2529 Automatic selection of the linker depending on which combinations of
2533 Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
2534 @samp{-l}) to pass to the automatically selected linker in order to link
2535 in the appropriate Fortran 77 intrinsic and run-time libraries.
2537 @cindex FLIBS, defined
2538 These extra Fortran 77 linker flags are supplied in the output variable
2539 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
2540 supplied with newer versions of Autoconf (Autoconf version 2.13 and
2541 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
2545 If Automake detects that a program or shared library (as mentioned in
2546 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
2547 code that is a mixture of Fortran 77 and C and/or C++, then it requires
2548 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
2549 @file{configure.in}, and that either @code{$(FLIBS)} or @code{@@FLIBS@@}
2550 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
2551 (for shared libraries) variables. It is the responsibility of the
2552 person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
2553 or @code{@@FLIBS@@} appears in the appropriate @code{_LDADD} or
2554 @code{_LIBADD} variable.
2556 @cindex Mixed language example
2557 @cindex Example, mixed language
2559 For example, consider the following @file{Makefile.am}:
2563 foo_SOURCES = main.cc foo.f
2564 foo_LDADD = libfoo.la @@FLIBS@@
2566 pkglib_LTLIBRARIES = libfoo.la
2567 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
2568 libfoo_la_LIBADD = $(FLIBS)
2571 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
2572 is mentioned in @file{configure.in}. Also, if @code{@@FLIBS@@} hadn't
2573 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
2574 Automake would have issued a warning.
2579 * How the Linker is Chosen::
2582 @node How the Linker is Chosen, , Mixing Fortran 77 With C and C++, Mixing Fortran 77 With C and C++
2583 @comment node-name, next, previous, up
2584 @subsubsection How the Linker is Chosen
2586 @cindex Automatic linker selection
2587 @cindex Selecting the linker automatically
2589 The following diagram demonstrates under what conditions a particular
2590 linker is chosen by Automake.
2592 For example, if Fortran 77, C and C++ source code were to be compiled
2593 into a program, then the C++ linker will be used. In this case, if the
2594 C or Fortran 77 linkers required any special libraries that weren't
2595 included by the C++ linker, then they must be manually added to an
2596 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
2602 code \ C C++ Fortran
2603 ----------------- +---------+---------+---------+
2607 +---------+---------+---------+
2611 +---------+---------+---------+
2615 +---------+---------+---------+
2619 +---------+---------+---------+
2621 C + Fortran | | | x |
2623 +---------+---------+---------+
2625 C++ + Fortran | | x | |
2627 +---------+---------+---------+
2629 C + C++ + Fortran | | x | |
2631 +---------+---------+---------+
2635 @node Fortran 77 and Autoconf, , Mixing Fortran 77 With C and C++, Fortran 77 Support
2636 @comment node-name, next, previous, up
2637 @subsection Fortran 77 and Autoconf
2639 The current Automake support for Fortran 77 requires a recent enough
2640 version of Autoconf that also includes support for Fortran 77. Full
2641 Fortran 77 support was added to Autoconf 2.13, so you will want to use
2642 that version of Autoconf or later.
2645 @node Java Support, Support for Other Languages, Fortran 77 Support, Programs
2646 @comment node-name, next, previous, up
2647 @section Java Support
2649 @cindex Java support
2650 @cindex Support for Java
2652 Automake includes support for compiled Java, using @code{gcj}, the Java
2653 front end to the GNU Compiler Collection.
2655 Any package including Java code to be compiled must define the output
2656 variable @samp{GCJ} in @file{configure.in}; the variable @samp{GCJFLAGS}
2657 must also be defined somehow (either in @file{configure.in} or
2658 @file{Makefile.am}). The simplest way to do this is to use the
2659 @code{AM_PROG_GCJ} macro.
2663 By default, programs including Java source files are linked with
2666 As always, the contents of @samp{AM_GCJFLAGS} are passed to every
2667 compilation invoking @code{gcj} (in its role as an ahead-of-time
2668 compiler -- when invoking it to create @file{.class} files,
2669 @samp{AM_JAVACFLAGS} is used instead). If it is necessary to pass
2670 options to @code{gcj} from @file{Makefile.am}, this macro, and not the
2671 user macro @samp{GCJFLAGS}, should be used.
2675 @code{gcj} can be used to compile @file{.java}, @file{.class},
2676 @file{.zip}, or @file{.jar} files.
2679 @node Support for Other Languages, ANSI, Java Support, Programs
2680 @comment node-name, next, previous, up
2681 @section Support for Other Languages
2683 Automake currently only includes full support for C, C++ (@pxref{C++
2684 Support}), Fortran 77 (@pxref{Fortran 77 Support}), and Java
2685 (@pxref{Java Support}). There is only rudimentary support for other
2686 languages, support for which will be improved based on user demand.
2688 Some limited support for adding your own languages is available via the
2689 suffix rule handling; see @ref{Suffixes}.
2692 @node ANSI, Dependencies, Support for Other Languages, Programs
2693 @section Automatic de-ANSI-fication
2695 @cindex de-ANSI-fication, defined
2697 Although the GNU standards allow the use of ANSI C, this can have the
2698 effect of limiting portability of a package to some older compilers
2699 (notably the SunOS C compiler).
2701 Automake allows you to work around this problem on such machines by
2702 @dfn{de-ANSI-fying} each source file before the actual compilation takes
2705 @vindex AUTOMAKE_OPTIONS
2708 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
2709 (@pxref{Options}) contains the option @code{ansi2knr} then code to
2710 handle de-ANSI-fication is inserted into the generated
2713 This causes each C source file in the directory to be treated as ANSI C.
2714 If an ANSI C compiler is available, it is used. If no ANSI C compiler
2715 is available, the @code{ansi2knr} program is used to convert the source
2716 files into K&R C, which is then compiled.
2718 The @code{ansi2knr} program is simple-minded. It assumes the source
2719 code will be formatted in a particular way; see the @code{ansi2knr} man
2722 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
2723 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
2724 these files are distributed with Automake. Also, the package
2725 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}
2727 @cvindex AM_C_PROTOTYPES
2729 Automake also handles finding the @code{ansi2knr} support files in some
2730 other directory in the current package. This is done by prepending the
2731 relative path to the appropriate directory to the @code{ansi2knr}
2732 option. For instance, suppose the package has ANSI C code in the
2733 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
2734 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
2735 @file{src/Makefile.am}:
2738 AUTOMAKE_OPTIONS = ../lib/ansi2knr
2741 If no directory prefix is given, the files are assumed to be in the
2744 Files mentioned in @code{LIBOBJS} which need de-ANSI-fication will not
2745 be automatically handled. That's because @code{configure} will generate
2746 an object name like @file{regex.o}, while @code{make} will be looking
2747 for @file{regex_.o} (when de-ANSI-fying). Eventually this problem will
2748 be fixed via @code{autoconf} magic, but for now you must put this code
2749 into your @file{configure.in}, just before the @code{AC_OUTPUT} call:
2752 # This is necessary so that .o files in LIBOBJS are also built via
2753 # the ANSI2KNR-filtering rules.
2754 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
2757 Note that automatic de-ANSI-fication will not work when the package is
2758 being built for a different host architecture. That is because automake
2759 currently has no way to build @code{ansi2knr} for the build machine.
2762 @node Dependencies, EXEEXT, ANSI, Programs
2763 @section Automatic dependency tracking
2765 As a developer it is often painful to continually update the
2766 @file{Makefile.in} whenever the include-file dependencies change in a
2767 project. Automake supplies a way to automatically track dependency
2770 @cindex Dependency tracking
2771 @cindex Automatic dependency tracking
2773 Automake always uses complete dependencies for a compilation, including
2774 system headers. Automake's model is that dependency computation should
2775 be a side effect of the build. To this end, dependencies are computed
2776 by running all compilations through a special wrapper program called
2777 @code{depcomp}. @code{depcomp} understands how to coax many different C
2778 and C++ compilers into generating dependency information in the format
2779 it requires. @code{automake -a} will install @code{depcomp} into your
2780 source tree for you. If @code{depcomp} can't figure out how to properly
2781 invoke your compiler, dependency tracking will simply be disabled for
2786 Experience with earlier versions of Automake @footnote{See
2787 @uref{http://sources.redhat.com/automake/dependencies.html} for more
2788 information on the history and experiences with automatic dependency
2789 tracking in Automake} taught us that it is not reliable to generate
2790 dependencies only on the maintainer's system, as configurations vary too
2791 much. So instead Automake implements dependency tracking at build time.
2793 Automatic dependency tracking can be suppressed by putting
2794 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}. Or, you
2795 can invoke @code{automake} with the @code{-i} option. Dependency
2796 tracking is enabled by default.
2798 @vindex AUTOMAKE_OPTIONS
2799 @opindex no-dependencies
2801 The person building your package also can choose to disable dependency
2802 tracking by configuring with @code{--disable-dependency-tracking}.
2804 @cindex Disabling dependency tracking
2805 @cindex Dependency tracking, disabling
2808 @node EXEEXT, , Dependencies, Programs
2809 @section Support for executable extensions
2811 @cindex Executable extension
2812 @cindex Extension, executable
2815 On some platforms, such as Windows, executables are expected to have an
2816 extension such as @samp{.exe}. On these platforms, some compilers (GCC
2817 among them) will automatically generate @file{foo.exe} when asked to
2818 generate @file{foo}.
2820 Automake provides mostly-transparent support for this. Unfortunately
2821 the support isn't completely transparent; if you want your package to
2822 support these platforms then you must assist.
2824 One thing you must be aware of is that, internally, Automake rewrites
2825 something like this:
2828 bin_PROGRAMS = liver
2834 bin_PROGRAMS = liver$(EXEEXT)
2837 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
2838 extension. @code{EXEEXT}
2840 However, Automake cannot apply this rewriting to @code{configure}
2841 substitutions. This means that if you are conditionally building a
2842 program using such a substitution, then your @file{configure.in} must
2843 take care to add @samp{$(EXEEXT)} when constructing the output variable.
2845 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
2846 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
2847 automatically if you configure a compiler (say, through
2850 Sometimes maintainers like to write an explicit link rule for their
2851 program. Without executable extension support, this is easy---you
2852 simply write a target with the same name as the program. However, when
2853 executable extension support is enabled, you must instead add the
2854 @samp{$(EXEEXT)} suffix.
2856 Unfortunately, due to the change in Autoconf 2.50, this means you must
2857 always add this extension. However, this is a problem for maintainers
2858 who know their package will never run on a platform that has executable
2859 extensions. For those maintainers, the @code{no-exeext} option
2860 (@pxref{Options}) will disable this feature. This works in a fairly
2861 ugly way; if @code{no-exeext} is seen, then the presence of a target
2862 named @code{foo} in @file{Makefile.am} will override an
2863 automake-generated target of the form @code{foo$(EXEEXT)}. Without the
2864 @code{no-exeext} option, this use will give an error.
2867 @node Other objects, Other GNU Tools, Programs, Top
2868 @chapter Other Derived Objects
2870 Automake can handle derived objects which are not C programs. Sometimes
2871 the support for actually building such objects must be explicitly
2872 supplied, but Automake will still automatically handle installation and
2876 * Scripts:: Executable scripts
2877 * Headers:: Header files
2878 * Data:: Architecture-independent data files
2879 * Sources:: Derived sources
2883 @node Scripts, Headers, Other objects, Other objects
2884 @section Executable Scripts
2886 @cindex _SCRIPTS primary, defined
2887 @cindex SCRIPTS primary, defined
2888 @cindex Primary variable, SCRIPTS
2890 It is possible to define and install programs which are scripts. Such
2891 programs are listed using the @samp{SCRIPTS} primary name. Automake
2892 doesn't define any dependencies for scripts; the @file{Makefile.am}
2893 should include the appropriate rules.
2896 Automake does not assume that scripts are derived objects; such objects
2897 must be deleted by hand (@pxref{Clean}).
2899 The @code{automake} program itself is a Perl script that is generated at
2900 configure time from @file{automake.in}. Here is how this is handled:
2903 bin_SCRIPTS = automake
2906 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
2907 for it is automatically generated.
2909 @cindex SCRIPTS, installation directories
2910 @cindex Installing scripts
2913 @vindex sbin_SCRIPTS
2914 @vindex libexec_SCRIPTS
2915 @vindex pkgdata_SCRIPTS
2916 @vindex noinst_SCRIPTS
2918 Script objects can be installed in @code{bindir}, @code{sbindir},
2919 @code{libexecdir}, or @code{pkgdatadir}.
2922 @node Headers, Data, Scripts, Other objects
2923 @section Header files
2925 @cindex _HEADERS primary, defined
2926 @cindex HEADERS primary, defined
2927 @cindex Primary variable, HEADERS
2929 @vindex noinst_HEADERS
2931 Header files are specified by the @samp{HEADERS} family of variables.
2932 Generally header files are not installed, so the @code{noinst_HEADERS}
2933 variable will be the most used. @footnote{However, for the case of a
2934 non-installed header file that is actually used by a particular program,
2935 we recommend listing it in the program's @samp{_SOURCES} variable
2936 instead of in @code{noinst_HEADERS}. We believe this is more clear.}
2939 All header files must be listed somewhere; missing ones will not appear
2940 in the distribution. Often it is clearest to list uninstalled headers
2941 with the rest of the sources for a program. @xref{A Program}. Headers
2942 listed in a @samp{_SOURCES} variable need not be listed in any
2943 @samp{_HEADERS} variable.
2945 @cindex HEADERS, installation directories
2946 @cindex Installing headers
2948 @vindex include_HEADERS
2949 @vindex oldinclude_HEADERS
2950 @vindex pkginclude_HEADERS
2952 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
2953 @code{pkgincludedir}.
2956 @node Data, Sources, Headers, Other objects
2957 @section Architecture-independent data files
2959 @cindex _DATA primary, defined
2960 @cindex DATA primary, defined
2961 @cindex Primary variable, DATA
2963 Automake supports the installation of miscellaneous data files using the
2964 @samp{DATA} family of variables.
2968 @vindex sysconf_DATA
2969 @vindex sharedstate_DATA
2970 @vindex localstate_DATA
2971 @vindex pkgdata_DATA
2973 Such data can be installed in the directories @code{datadir},
2974 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
2977 By default, data files are @emph{not} included in a distribution. Of
2978 course, you can use the @samp{dist_} prefix to change this on a
2981 Here is how Automake installs its auxiliary data files:
2984 pkgdata_DATA = clean-kr.am clean.am @dots{}
2988 @node Sources, , Data, Other objects
2989 @section Built sources
2991 @cindex BUILT_SOURCES, defined
2993 Occasionally a file which would otherwise be called @samp{source}
2994 (e.g. a C @samp{.h} file) is actually derived from some other file.
2995 Such files should be listed in the @code{BUILT_SOURCES} variable.
2996 @vindex BUILT_SOURCES
2998 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
2999 must be created early in the build process can be listed in this
3002 A source file listed in @code{BUILT_SOURCES} is created before the other
3003 @code{all} targets are made. However, such a source file is not
3004 compiled unless explicitly requested by mentioning it in some other
3005 @samp{_SOURCES} variable.
3007 So, for instance, if you had header files which were created by a script
3008 run at build time, then you would list these headers in
3009 @code{BUILT_SOURCES}, to ensure that they would be built before any
3010 other compilations (perhaps ones using these headers) were started.
3013 @node Other GNU Tools, Documentation, Other objects, Top
3014 @chapter Other GNU Tools
3016 Since Automake is primarily intended to generate @file{Makefile.in}s for
3017 use in GNU programs, it tries hard to interoperate with other GNU tools.
3020 * Emacs Lisp:: Emacs Lisp
3028 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
3031 @cindex _LISP primary, defined
3032 @cindex LISP primary, defined
3033 @cindex Primary variable, LISP
3039 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
3040 is used to hold a list of @file{.el} files. Possible prefixes for this
3041 primary are @samp{lisp_} and @samp{noinst_}. Note that if
3042 @code{lisp_LISP} is defined, then @file{configure.in} must run
3043 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
3047 By default Automake will byte-compile all Emacs Lisp source files using
3048 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
3049 byte-compiling, simply define the variable @code{ELCFILES} to be empty.
3050 Byte-compiled Emacs Lisp files are not portable among all versions of
3051 Emacs, so it makes sense to turn this off if you expect sites to have
3052 more than one version of Emacs installed. Furthermore, many packages
3053 don't actually benefit from byte-compilation. Still, we recommend that
3054 you leave it enabled by default. It is probably better for sites with
3055 strange setups to cope for themselves than to make the installation less
3056 nice for everybody else.
3059 @node gettext, Libtool, Emacs Lisp, Other GNU Tools
3062 @cindex GNU Gettext support
3063 @cindex Gettext support
3064 @cindex Support for GNU Gettext
3066 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
3067 turns on support for GNU gettext, a message catalog system for
3068 internationalization
3069 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
3071 The @code{gettext} support in Automake requires the addition of two
3072 subdirectories to the package, @file{intl} and @file{po}. Automake
3073 insures that these directories exist and are mentioned in
3077 @node Libtool, Java, gettext, Other GNU Tools
3080 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
3081 libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
3082 @xref{A Shared Library}.
3085 @node Java, Python, Libtool, Other GNU Tools
3088 @cindex _JAVA primary, defined
3089 @cindex JAVA primary, defined
3090 @cindex Primary variable, JAVA
3092 Automake provides some minimal support for Java compilation with the
3093 @samp{JAVA} primary.
3095 Any @file{.java} files listed in a @samp{_JAVA} variable will be
3096 compiled with @code{JAVAC} at build time. By default, @file{.class}
3097 files are not included in the distribution.
3099 @cindex JAVA restrictions
3100 @cindex Restrictions for JAVA
3102 Currently Automake enforces the restriction that only one @samp{_JAVA}
3103 primary can be used in a given @file{Makefile.am}. The reason for this
3104 restriction is that, in general, it isn't possible to know which
3105 @file{.class} files were generated from which @file{.java} files -- so
3106 it would be impossible to know which files to install where. For
3107 instance, a @file{.java} file can define multiple classes; the resulting
3108 @file{.class} file names cannot be predicted without parsing the
3111 There are a few variables which are used when compiling Java sources:
3115 The name of the Java compiler. This defaults to @samp{javac}.
3118 The flags to pass to the compiler. This is considered to be a user
3119 variable (@pxref{User Variables}).
3122 More flags to pass to the Java compiler. This, and not
3123 @code{JAVACFLAGS}, should be used when it is necessary to put Java
3124 compiler flags into @file{Makefile.am}.
3127 The value of this variable is passed to the @samp{-d} option to
3128 @code{javac}. It defaults to @samp{$(top_builddir)}.
3131 This variable is an @code{sh} expression which is used to set the
3132 @code{CLASSPATH} environment variable on the @code{javac} command line.
3133 (In the future we will probably handle class path setting differently.)
3137 @node Python, , Java, Other GNU Tools
3140 @cindex _PYTHON primary, defined
3141 @cindex PYTHON primary, defined
3142 @cindex Primary variable, PYTHON
3145 Automake provides support for Python compilation with the @samp{PYTHON}
3148 Any files listed in a @samp{_PYTHON} variable will be byte-compiled with
3149 @code{py-compile} at install time. @code{py-compile} actually creates
3150 both standard (@file{.pyc}) and byte-compiled (@file{.pyo}) versions of
3151 the source files. Note that because byte-compilation occurs at install
3152 time, any files listed in @samp{noinst_PYTHON} will not be compiled.
3153 Python source files are included in the distribution by default.
3155 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} which
3156 will determine some Python-related directory variables (see below). If
3157 have called @code{AM_PATH_PYTHON} from you @file{configure.in}, then you
3158 may use the following variables to list you Python source files in your
3159 variables: @samp{python_PYTHON}, @samp{pkgpython_PYTHON},
3160 @samp{pkgpython_PYTHON}, @samp{pyexecdir_PYTHON},
3161 @samp{pkgpyexecdir_PYTHON}, depending where you want your files
3164 @code{AM_PATH_PYTHON} takes a single optional argument. This argument,
3165 if present, is the minimum version of Python which can be used for this
3166 package. If the version of Python found on the system is older than the
3167 required version, then @code{AM_PATH_PYTHON} will cause an error.
3169 @code{AM_PATH_PYTHON} creates several output variables based on the
3170 Python installation found during configuration.
3174 The name of the Python executable.
3176 @item PYTHON_VERSION
3177 The Python version number, in the form @var{major}.@var{minor}
3178 (e.g. @samp{1.5}). This is currently the value of
3179 @code{sys.version[:3]}.
3182 The string @code{$prefix}. This term may be used in future work
3183 which needs the contents of Python's @code{sys.prefix}, but general
3184 consensus is to always use the value from configure.
3186 @item PYTHON_EXEC_PREFIX
3187 The string @code{$exec_prefix}. This term may be used in future work
3188 which needs the contents of Python's @code{sys.exec_prefix}, but general
3189 consensus is to always use the value from configure.
3191 @item PYTHON_PLATFORM
3192 The canonical name used by Python to describe the operating system, as
3193 given by @code{sys.platform}. This value is sometimes needed when
3194 building Python extensions.
3197 The directory name for the @file{site-packages} subdirectory of the
3198 standard Python install tree.
3201 This is is the directory under @code{pythondir} which is named after the
3202 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
3206 This is the directory where Python extension modules (shared libraries)
3207 should be installed.
3210 This is a convenience variable which is defined as
3211 @samp{$(pyexecdir)/$(PACKAGE)}.
3215 @node Documentation, Install, Other GNU Tools, Top
3216 @chapter Building documentation
3218 Currently Automake provides support for Texinfo and man pages.
3222 * Man pages:: Man pages
3226 @node Texinfo, Man pages, Documentation, Documentation
3229 @cindex _TEXINFOS primary, defined
3230 @cindex TEXINFOS primary, defined
3231 @cindex Primary variable, TEXINFOS
3233 If the current directory contains Texinfo source, you must declare it
3234 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
3235 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
3236 here. Any Texinfo source file must end in the @file{.texi},
3237 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
3240 @vindex info_TEXINFOS
3242 @cindex Texinfo macro, VERSION
3243 @cindex Texinfo macro, UPDATED
3244 @cindex Texinfo macro, EDITION
3245 @cindex Texinfo macro, UPDATED-MONTH
3247 @cindex VERSION Texinfo macro
3248 @cindex UPDATED Texinfo macro
3249 @cindex EDITION Texinfo macro
3250 @cindex UPDATED-MONTH Texinfo macro
3254 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
3255 that file will be automatically generated. The file @file{version.texi}
3256 defines four Texinfo macros you can reference:
3261 Both of these macros hold the version number of your program. They are
3262 kept separate for clarity.
3265 This holds the date the primary @file{.texi} file was last modified.
3268 This holds the name of the month in which the primary @file{.texi} file
3272 The @file{version.texi} support requires the @code{mdate-sh} program;
3273 this program is supplied with Automake and automatically included when
3274 @code{automake} is invoked with the @code{--add-missing} option.
3276 If you have multiple Texinfo files, and you want to use the
3277 @file{version.texi} feature, then you have to have a separate version
3278 file for each Texinfo file. Automake will treat any include in a
3279 Texinfo file that matches @samp{vers*.texi} just as an automatically
3280 generated version file.
3282 When an info file is rebuilt, the program named by the @code{MAKEINFO}
3283 variable is used to invoke it. If the @code{makeinfo} program is found
3284 on the system then it will be used by default; otherwise @code{missing}
3285 will be used instead. The flags in the variables @code{MAKEINFOFLAGS}
3286 and @code{AM_MAKEINFOFLAGS} will be passed to the @code{makeinfo}
3287 invocation; the first of these is intended for use by the user
3288 (@pxref{User Variables}) and the second by the @file{Makefile.am}
3291 @vindex MAKEINFOFLAGS
3292 @vindex AM_MAKEINFOFLAGS
3294 Sometimes an info file actually depends on more than one @file{.texi}
3295 file. For instance, in GNU Hello, @file{hello.texi} includes the file
3296 @file{gpl.texi}. You can tell Automake about these dependencies using
3297 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
3302 info_TEXINFOS = hello.texi
3303 hello_TEXINFOS = gpl.texi
3308 By default, Automake requires the file @file{texinfo.tex} to appear in
3309 the same directory as the Texinfo source. However, if you used
3310 @code{AC_CONFIG_AUX_DIR} in @file{configure.in} (@pxref{Input, , Finding
3311 `configure' Input, autoconf, The Autoconf Manual}), then
3312 @file{texinfo.tex} is looked for there. Automake supplies
3313 @file{texinfo.tex} if @samp{--add-missing} is given.
3317 If your package has Texinfo files in many directories, you can use the
3318 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
3319 @file{texinfo.tex} for your package. The value of this variable should
3320 be the relative path from the current @file{Makefile.am} to
3324 TEXINFO_TEX = ../doc/texinfo.tex
3327 @opindex no-texinfo.tex
3329 The option @samp{no-texinfo.tex} can be used to eliminate the
3330 requirement for @file{texinfo.tex}. Use of the variable
3331 @code{TEXINFO_TEX} is preferable, however, because that allows the
3332 @code{dvi} target to still work.
3334 @cindex Target, install-info
3335 @cindex Target, noinstall-info
3336 @cindex install-info target
3337 @cindex noinstall-info target
3339 @opindex no-installinfo
3340 @trindex install-info
3342 Automake generates an @code{install-info} target; some people apparently
3343 use this. By default, info pages are installed by @samp{make install}.
3344 This can be prevented via the @code{no-installinfo} option.
3347 @node Man pages, , Texinfo, Documentation
3350 @cindex _MANS primary, defined
3351 @cindex MANS primary, defined
3352 @cindex Primary variable, MANS
3354 A package can also include man pages (but see the GNU standards on this
3355 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
3356 pages are declared using the @samp{MANS} primary. Generally the
3357 @code{man_MANS} macro is used. Man pages are automatically installed in
3358 the correct subdirectory of @code{mandir}, based on the file extension.
3362 File extensions such as @samp{.1c} are handled by looking for the valid
3363 part of the extension and using that to determine the correct
3364 subdirectory of @code{mandir}. Valid section names are the digits
3365 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
3367 Sometimes developers prefer to name a man page something like
3368 @file{foo.man} in the source, and then rename it to have the correct
3369 suffix, e.g. @file{foo.1}, when installing the file. Automake also
3370 supports this mode. For a valid section named @var{SECTION}, there is a
3371 corresponding directory named @samp{man@var{SECTION}dir}, and a
3372 corresponding @samp{_MANS} variable. Files listed in such a variable
3373 are installed in the indicated section. If the file already has a
3374 valid suffix, then it is installed as-is; otherwise the file suffix is
3375 changed to match the section.
3377 For instance, consider this example:
3379 man1_MANS = rename.man thesame.1 alsothesame.1c
3382 In this case, @file{rename.man} will be renamed to @file{rename.1} when
3383 installed, but the other files will keep their names.
3385 @cindex Target, install-man
3386 @cindex Target, noinstall-man
3387 @cindex install-man target
3388 @cindex noinstall-man target
3390 @c Use @samp{make install} per documentation: (texi)code.
3391 By default, man pages are installed by @samp{make install}. However,
3392 since the GNU project does not require man pages, many maintainers do
3393 not expend effort to keep the man pages up to date. In these cases, the
3394 @code{no-installman} option will prevent the man pages from being
3395 installed by default. The user can still explicitly install them via
3396 @samp{make install-man}.
3397 @opindex no-installman
3398 @trindex install-man
3400 Here is how the man pages are handled in GNU @code{cpio} (which includes
3401 both Texinfo documentation and man pages):
3404 man_MANS = cpio.1 mt.1
3405 EXTRA_DIST = $(man_MANS)
3408 Man pages are not currently considered to be source, because it is not
3409 uncommon for man pages to be automatically generated. Therefore they
3410 are not automatically included in the distribution. However, this can
3411 be changed by use of the @samp{dist_} prefix.
3413 The @samp{nobase_} prefix is meaningless for man pages and is
3417 @node Install, Clean, Documentation, Top
3418 @chapter What Gets Installed
3420 @cindex Installation support
3421 @cindex make install support
3423 @section Basics of installation
3425 Naturally, Automake handles the details of actually installing your
3426 program once it has been built. All files named by the various
3427 primaries are automatically installed in the appropriate places when the
3428 user runs @code{make install}.
3430 A file named in a primary is installed by copying the built file into
3431 the appropriate directory. The base name of the file is used when
3435 bin_PROGRAMS = hello subdir/goodbye
3438 In this example, both @samp{hello} and @samp{goodbye} will be installed
3439 in @code{$(bindir)}.
3441 Sometimes it is useful to avoid the basename step at install time. For
3442 instance, you might have a number of header files in subdirectories of
3443 the source tree which are laid out precisely how you want to install
3444 them. In this situation you can use the @samp{nobase_} prefix to
3445 suppress the base name step. For example:
3448 nobase_include_HEADERS = stdio.h sys/types.h
3451 Will install @file{stdio.h} in @code{$(includedir)} and @file{types.h}
3452 in @code{$(includedir)/sys}.
3454 @section The two parts of install
3456 Automake generates separate @code{install-data} and @code{install-exec}
3457 targets, in case the installer is installing on multiple machines which
3458 share directory structure---these targets allow the machine-independent
3459 parts to be installed only once. @code{install-exec} installs
3460 platform-dependent files, and @code{install-data} installs
3461 platform-independent files. The @code{install} target depends on both
3462 of these targets. While Automake tries to automatically segregate
3463 objects into the correct category, the @file{Makefile.am} author is, in
3464 the end, responsible for making sure this is done correctly.
3465 @trindex install-data
3466 @trindex install-exec
3468 @cindex Install, two parts of
3470 Variables using the standard directory prefixes @samp{data},
3471 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
3472 @samp{pkgdata}, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
3473 installed by @samp{install-data}.
3475 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
3476 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
3477 @samp{pkglib} (e.g. @samp{bin_PROGRAMS}) are installed by
3478 @samp{install-exec}.
3480 Any variable using a user-defined directory prefix with @samp{exec} in
3481 the name (e.g. @samp{myexecbin_PROGRAMS} is installed by
3482 @samp{install-exec}. All other user-defined prefixes are installed by
3483 @samp{install-data}.
3485 @section Extending installation
3487 It is possible to extend this mechanism by defining an
3488 @code{install-exec-local} or @code{install-data-local} target. If these
3489 targets exist, they will be run at @samp{make install} time. These
3490 rules can do almost anything; care is required.
3491 @trindex install-exec-local
3492 @trindex install-data-local
3494 Automake also supports two install hooks, @code{install-exec-hook} and
3495 @code{install-data-hook}. These hooks are run after all other install
3496 rules of the appropriate type, exec or data, have completed. So, for
3497 instance, it is possible to perform post-installation modifications
3498 using an install hook.
3499 @cindex Install hook
3501 @section Staged installs
3504 Automake generates support for the @samp{DESTDIR} variable in all
3505 install rules. @samp{DESTDIR} is used during the @samp{make install}
3506 step to relocate install objects into a staging area. Each object and
3507 path is prefixed with the value of @samp{DESTDIR} before being copied
3508 into the install area. Here is an example of typical DESTDIR usage:
3511 make DESTDIR=/tmp/staging install
3514 This places install objects in a directory tree built under
3515 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
3516 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
3517 would install @file{/tmp/staging/gnu/bin/foo} and
3518 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
3520 This feature is commonly used to build install images and packages. For
3521 more information, see @ref{Makefile Conventions, , , standards, The GNU
3524 Support for @samp{DESTDIR} is implemented by coding it directly into the
3525 install rules. If your @file{Makefile.am} uses a local install rule
3526 (e.g., @code{install-exec-local}) or an install hook, then you must
3527 write that code to respect @samp{DESTDIR}.
3529 @section Rules for the user
3531 Automake also generates an @code{uninstall} target, an
3532 @code{installdirs} target, and an @code{install-strip} target.
3534 @trindex installdirs
3535 @trindex install-strip
3537 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
3538 There is no notion of separate uninstalls for ``exec'' and ``data'', as
3539 these features would not provide additional functionality.
3541 Note that @code{uninstall} is not meant as a replacement for a real
3545 @node Clean, Dist, Install, Top
3546 @chapter What Gets Cleaned
3548 @cindex make clean support
3550 The GNU Makefile Standards specify a number of different clean rules.
3552 Generally the files that can be cleaned are determined automatically by
3553 Automake. Of course, Automake also recognizes some variables that can
3554 be defined to specify additional files to clean. These variables are
3555 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
3556 @code{MAINTAINERCLEANFILES}.
3557 @vindex MOSTLYCLEANFILES
3559 @vindex DISTCLEANFILES
3560 @vindex MAINTAINERCLEANFILES
3562 As the GNU Standards aren't always explicit as to which files should be
3563 removed by which target, we've adopted a heuristic which we believe was
3564 first formulated by Fran@,{c}ois Pinard:
3568 If @code{make} built it, and it is commonly something that one would
3569 want to rebuild (for instance, a @file{.o} file), then
3570 @code{mostlyclean} should delete it.
3573 Otherwise, if @code{make} built it, then @code{clean} should delete it.
3576 If @code{configure} built it, then @code{distclean} should delete it
3579 If the maintainer built it, then @code{maintainer-clean} should
3583 We recommend that you follow this same set of heuristics in your
3587 @node Dist, Tests, Clean, Top
3588 @chapter What Goes in a Distribution
3590 @section Basics of distribution
3594 The @code{dist} target in the generated @file{Makefile.in} can be used
3595 to generate a gzip'd @code{tar} file and other flavors of archive for
3596 distribution. The files is named based on the @samp{PACKAGE} and
3597 @samp{VERSION} variables; more precisely the gzip'd @code{tar} file is
3598 named @samp{@var{package}-@var{version}.tar.gz}.
3602 You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
3603 is run. The default setting is @samp{--best}.
3605 For the most part, the files to distribute are automatically found by
3606 Automake: all source files are automatically included in a distribution,
3607 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
3608 has a built-in list of commonly used files which are automatically
3609 included if they are found in the current directory (either physically,
3610 or as the target of a @file{Makefile.am} rule). This list is printed by
3611 @samp{automake --help}. Also, files which are read by @code{configure}
3612 (i.e. the source files corresponding to the files specified in the
3613 @code{AC_OUTPUT} invocation) are automatically distributed.
3615 Still, sometimes there are files which must be distributed, but which
3616 are not covered in the automatic rules. These files should be listed in
3617 the @code{EXTRA_DIST} variable. You can mention files from
3618 subdirectories in @code{EXTRA_DIST}.
3620 You can also mention a directory in @code{EXTRA_DIST}; in this case the
3621 entire directory will be recursively copied into the distribution.
3622 Please note that this will also copy @emph{everything} in the directory,
3623 including CVS/RCS version control files. We recommend against using
3628 @section Fine-grained distribution control
3630 Sometimes you need tighter control over what does @emph{not} go into the
3631 distribution; for instance you might have source files which are
3632 generated and which you do not want to distribute. In this case
3633 Automake gives fine-grained control using the @samp{dist} and
3634 @samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
3635 prefixed with @samp{dist_} to add the listed files to the distribution.
3636 Similarly, @samp{nodist_} can be used to omit the files from the
3641 As an example, here is how you would cause some data to be distributed
3642 while leaving some source code out of the distribution:
3645 dist_data_DATA = distribute-this
3647 nodist_foo_SOURCES = do-not-distribute.c
3650 @section The dist hook
3652 Another way to to use this is for removing unnecessary files that get
3653 recursively included by specifying a directory in EXTRA_DIST:
3659 rm -rf `find $(distdir)/doc -name CVS`
3662 If you define @code{SUBDIRS}, Automake will recursively include the
3663 subdirectories in the distribution. If @code{SUBDIRS} is defined
3664 conditionally (@pxref{Conditionals}), Automake will normally include all
3665 directories that could possibly appear in @code{SUBDIRS} in the
3666 distribution. If you need to specify the set of directories
3667 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
3668 list of subdirectories to include in the distribution.
3669 @vindex DIST_SUBDIRS
3673 Occasionally it is useful to be able to change the distribution before
3674 it is packaged up. If the @code{dist-hook} target exists, it is run
3675 after the distribution directory is filled, but before the actual tar
3676 (or shar) file is created. One way to use this is for distributing
3677 files in subdirectories for which a new @file{Makefile.am} is overkill:
3681 mkdir $(distdir)/random
3682 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
3685 @section Checking the distribution
3687 @cindex make distcheck
3688 @cindex make distcleancheck
3689 @vindex distcleancheck_listfiles
3691 Automake also generates a @code{distcheck} target which can be of help
3692 to ensure that a given distribution will actually work.
3693 @code{distcheck} makes a distribution, then tries to do a @code{VPATH}
3694 build, run the testsuite, and finally make another tarfile to ensure the
3695 distribution is self-contained.
3698 Building the package involves running @code{./configure}. If you need
3699 to supply additional flags to @code{configure}, define them in the
3700 @code{DISTCHECK_CONFIGURE_FLAGS} variable, either in your top-level
3701 @file{Makefile.am}, or on the commande line when invoking @code{make}.
3702 @vindex DISTCHECK_CONFIGURE_FLAGS
3704 If the target @code{distcheck-hook} is defined in your
3705 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
3706 the new distribution has been unpacked, but before the unpacked copy is
3707 configured and built. Your @code{distcheck-hook} can do almost
3708 anything, though as always caution is advised. Generally this hook is
3709 used to check for potential distribution errors not caught by the
3712 Speaking about potential distribution errors, @code{distcheck} will also
3713 ensure that the @code{distclean} target actually removes all built
3714 files. This is done by running @code{make distcleancheck} at the end of
3715 the @code{VPATH} build. By default, @code{distcleancheck} will run
3716 @code{distclean} and then make sure the build tree has been emptied by
3717 running @code{$(distcleancheck_listfiles)}. Usually this check will
3718 find generated files that you forgot to add to the @code{DISTCLEANFILES}
3719 variable (@pxref{Clean}).
3720 @trindex distcleancheck
3722 The @code{distcleancheck} behaviour should be ok for most packages,
3723 otherwise you have the possibility to override the definitition of
3724 either the @code{distcleancheck} target, or the
3725 @code{$(distcleancheck_listfiles)} variable. For instance to disable
3726 @code{distcleancheck} completely, add the following rule to your
3727 top-level @file{Makefile.am}:
3728 @vindex distcleancheck_listfiles
3735 If you want @code{distcleancheck} to ignore built files which have not
3736 been cleaned because they are also part of the distribution, add the
3737 following definition instead:
3740 distcleancheck_listfiles = \
3741 find -type f -exec sh -c 'test -f $(scrdir)/@{@} || echo @{@}'
3744 The above definition is not the default because it's usually an error if
3745 your Makefiles cause some distributed files to be rebuilt when the user
3746 build the package. (Think about the user missing the tool required to
3747 build the file; or if the required tool is built by your package,
3748 consider the cross-compilation case where it can't be run.)
3750 @section The types of distributions
3753 Automake generates a @samp{.tar.gz} file when asked to create a
3754 distribution and other archives formats, @ref{Options}. The target
3755 @code{dist-gzip} generates the @samp{.tar.gz} file only.
3758 @node Tests, Options, Dist, Top
3759 @chapter Support for test suites
3764 Automake supports two forms of test suites.
3766 @section Simple Tests
3768 If the variable @code{TESTS} is defined, its value is taken to be a list
3769 of programs to run in order to do the testing. The programs can either
3770 be derived objects or source objects; the generated rule will look both
3771 in @code{srcdir} and @file{.}. Programs needing data files should look
3772 for them in @code{srcdir} (which is both an environment variable and a
3773 make variable) so they work when building in a separate directory
3774 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
3775 Manual}), and in particular for the @code{distcheck} target
3778 @cindex Exit status 77, special interpretation
3780 The number of failures will be printed at the end of the run. If a
3781 given test program exits with a status of 77, then its result is ignored
3782 in the final count. This feature allows non-portable tests to be
3783 ignored in environments where they don't make sense.
3785 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
3786 variables for the test run; the environment variable @code{srcdir} is
3787 set in the rule. If all your test programs are scripts, you can also
3788 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
3789 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
3791 @vindex TESTS_ENVIRONMENT
3793 @cindex Tests, expected failure
3794 @cindex Expected test failure
3796 You may define the variable @code{XFAIL_TESTS} to a list of tests
3797 (usually a subset of @code{TESTS}) that are expected to fail. This will
3798 reverse the result of those tests.
3801 Automake ensures that each program listed in @code{TESTS} is built
3802 before any tests are run; you can list both source and derived programs
3803 in @code{TESTS}. For instance, you might want to run a C program as a
3804 test. To do this you would list its name in @code{TESTS} and also in
3805 @code{check_PROGRAMS}, and then specify it as you would any other
3808 @section DejaGNU Tests
3810 If @uref{ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz,
3811 @samp{dejagnu}} appears in @code{AUTOMAKE_OPTIONS}, then a
3812 @code{dejagnu}-based test suite is assumed. The variable
3813 @code{DEJATOOL} is a list of names which are passed, one at a time, as
3814 the @code{--tool} argument to @code{runtest} invocations; it defaults to
3815 the name of the package.
3817 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
3818 @code{--srcdir} flags that are passed to dejagnu by default; this can be
3819 overridden if necessary.
3820 @vindex RUNTESTDEFAULTFLAGS
3822 The variables @code{EXPECT} and @code{RUNTEST} can
3823 also be overridden to provide project-specific values. For instance,
3824 you will need to do this if you are testing a compiler toolchain,
3825 because the default values do not take into account host and target
3832 The contents of the variable @code{RUNTESTFLAGS} are passed to the
3833 @code{runtest} invocation. This is considered a ``user variable''
3834 (@pxref{User Variables}). If you need to set @code{runtest} flags in
3835 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
3836 @vindex RUNTESTFLAGS
3837 @vindex AM_RUNTESTFLAGS
3838 @c FIXME xref dejagnu
3840 In either case, the testing is done via @samp{make check}.
3842 @section Install Tests
3844 The @code{installcheck} target is available to the user as a way to run
3845 any tests after the package has been installed. You can add tests to
3846 this by writing an @code{installcheck-local} target.
3849 @node Options, Miscellaneous, Tests, Top
3850 @chapter Changing Automake's Behavior
3852 Various features of Automake can be controlled by options in the
3853 @file{Makefile.am}. Such options are listed in a special variable named
3854 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
3855 @vindex AUTOMAKE_OPTIONS
3860 @itemx @code{foreign}
3861 @itemx @code{cygnus}
3862 @cindex Option, gnits
3864 @cindex Option, foreign
3865 @cindex Option, cygnus
3867 Set the strictness as appropriate. The @code{gnits} option also implies
3868 @code{readme-alpha} and @code{check-news}.
3870 @item @code{ansi2knr}
3871 @itemx @code{@var{path}/ansi2knr}
3872 @cindex Option, ansi2knr
3873 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
3874 path, the generated @file{Makefile.in} will look in the specified
3875 directory to find the @file{ansi2knr} program. The path should be a
3876 relative path to another directory in the same distribution (Automake
3877 currently does not check this).
3879 @item @code{check-news}
3880 @cindex Option, check-news
3881 Cause @code{make dist} to fail unless the current version number appears
3882 in the first few lines of the @file{NEWS} file.
3884 @item @code{dejagnu}
3885 @cindex Option, dejagnu
3886 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
3888 @item @code{dist-bzip2}
3889 @cindex Option, dist-bzip2
3890 Generate a @code{dist-bzip2} target, creating a bzip2 tar archive of the
3891 distribution. @code{dist} will create it in addition to the other
3892 formats. bzip2 archives are frequently smaller than gzipped archives.
3895 @item @code{dist-shar}
3896 @cindex Option, dist-shar
3897 Generate a @code{dist-shar} target, creating a shar archive of the
3898 distribution. @code{dist} will create it in addition to the other
3902 @item @code{dist-zip}
3903 @cindex Option, dist-zip
3904 Generate a @code{dist-zip} target, creating a zip archive of the
3905 distribution. @code{dist} will create it in addition to the other
3909 @item @code{dist-tarZ}
3910 @cindex Option, dist-tarZ
3911 Generate a @code{dist-tarZ} target, creating a compressed tar archive of
3912 the distribution. @code{dist} will create it in addition to the other
3916 @item @code{no-dependencies}
3917 @cindex Option, no-dependencies
3918 This is similar to using @samp{--include-deps} on the command line, but
3919 is useful for those situations where you don't have the necessary bits
3920 to make automatic dependency tracking work @xref{Dependencies}. In this
3921 case the effect is to effectively disable automatic dependency tracking.
3923 @item @code{no-exeext}
3924 @cindex Option, no-exeext
3925 If your @file{Makefile.am} defines a target @samp{foo}, it will override
3926 a target named @samp{foo$(EXEEXT)}. This is necessary when
3927 @code{EXEEXT} is found to be empty. However, by default automake will
3928 generate an error for this use. The @code{no-exeext} option will
3929 disable this error. This is intended for use only where it is known in
3930 advance that the package will not be ported to Windows, or any other
3931 operating system using extensions on executables.
3933 @item @code{no-installinfo}
3934 @cindex Option, no-installinfo
3935 The generated @file{Makefile.in} will not cause info pages to be built
3936 or installed by default. However, @code{info} and @code{install-info}
3937 targets will still be available. This option is disallowed at
3938 @samp{GNU} strictness and above.
3940 @trindex install-info
3942 @item @code{no-installman}
3943 @cindex Option, no-installman
3944 The generated @file{Makefile.in} will not cause man pages to be
3945 installed by default. However, an @code{install-man} target will still
3946 be available for optional installation. This option is disallowed at
3947 @samp{GNU} strictness and above.
3948 @trindex install-man
3950 @item @code{nostdinc}
3951 @cindex Option, nostdinc
3952 This option can be used to disable the standard @samp{-I} options which
3953 are ordinarily automatically provided by Automake.
3955 @item @code{no-texinfo.tex}
3956 @cindex Option, no-texinfo
3957 Don't require @file{texinfo.tex}, even if there are texinfo files in
3960 @item @code{readme-alpha}
3961 @cindex Option, readme-alpha
3962 If this release is an alpha release, and the file @file{README-alpha}
3963 exists, then it will be added to the distribution. If this option is
3964 given, version numbers are expected to follow one of two forms. The
3965 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
3966 element is a number; the final period and number should be left off for
3967 non-alpha releases. The second form is
3968 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
3969 letter; it should be omitted for non-alpha releases.
3971 @item @code{subdir-objects}
3972 If this option is specified, then objects are placed into the
3973 subdirectory of the build directory corresponding to the subdirectory of
3974 the source file. For instance if the source file is
3975 @file{subdir/file.cxx}, then the output file would be
3976 @file{subdir/file.o}.
3979 @cindex Option, version
3980 A version number (e.g. @samp{0.30}) can be specified. If Automake is not
3981 newer than the version specified, creation of the @file{Makefile.in}
3985 Unrecognized options are diagnosed by @code{automake}.
3987 If you want an option to apply to all the files in the tree, you can use
3988 the @code{AM_AUTOMAKE_OPTIONS} macro in @file{configure.in}.
3992 @node Miscellaneous, Include, Options, Top
3993 @chapter Miscellaneous Rules
3995 There are a few rules and variables that didn't fit anywhere else.
3998 * Tags:: Interfacing to etags and mkid
3999 * Suffixes:: Handling new file extensions
4000 * Multilibs:: Support for multilibbing.
4004 @node Tags, Suffixes, Miscellaneous, Miscellaneous
4005 @section Interfacing to @code{etags}
4007 @cindex TAGS support
4009 Automake will generate rules to generate @file{TAGS} files for use with
4010 GNU Emacs under some circumstances.
4012 If any C, C++ or Fortran 77 source code or headers are present, then
4013 @code{tags} and @code{TAGS} targets will be generated for the directory.
4016 At the topmost directory of a multi-directory package, a @code{tags}
4017 target file will be generated which, when run, will generate a
4018 @file{TAGS} file that includes by reference all @file{TAGS} files from
4021 The @code{tags} target will also be generated if the variable
4022 @code{ETAGS_ARGS} is defined. This variable is intended for use in
4023 directories which contain taggable source that @code{etags} does not
4027 Here is how Automake generates tags for its source, and for nodes in its
4031 ETAGS_ARGS = automake.in --lang=none \
4032 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
4035 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
4036 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
4037 are added directly to the dependencies for the @code{tags} target.
4038 @vindex TAGS_DEPENDENCIES
4040 Automake will also generate an @code{ID} target which will run
4041 @code{mkid} on the source. This is only supported on a
4042 directory-by-directory basis.
4045 Automake also supports the @uref{http://www.gnu.org/software/global/,
4046 GNU Global Tags program}. The @code{GTAGS} target runs Global Tags
4047 automatically and puts the result in the top build directory. The
4048 variable @code{GTAGS_ARGS} holds arguments which are passed to
4053 @node Suffixes, Multilibs, Tags, Miscellaneous
4054 @section Handling new file extensions
4056 @cindex Adding new SUFFIXES
4057 @cindex SUFFIXES, adding
4060 It is sometimes useful to introduce a new implicit rule to handle a file
4061 type that Automake does not know about.
4063 For instance, suppose you had a compiler which could compile @samp{.foo}
4064 files to @samp{.o} files. You would simply define an suffix rule for
4072 Then you could directly use a @samp{.foo} file in a @samp{_SOURCES}
4073 variable and expect the correct results:
4077 doit_SOURCES = doit.foo
4080 This was the simpler and more common case. In other cases, you will
4081 have to help Automake to figure which extensions you are defining your
4082 suffix rule for. This usually happens when your extensions does not
4083 start with a dot. Then, all you have to do is to put a list of new
4084 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
4087 For instance the following definition prevents Automake to misinterpret
4088 @samp{.idlC.cpp:} as an attemp to transform @samp{.idlC} into
4092 SUFFIXES = .idl C.cpp
4097 As you may have noted, the @code{SUFFIXES} macro behaves like the
4098 @code{.SUFFIXES} special target of @code{make}. You should not touch
4099 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
4100 Automake generate the suffix list for @code{.SUFFIXES}. Any given
4101 @code{SUFFIXES} go at the start of the generated suffixes list, followed
4102 by Automake generated suffixes not already in the list.
4104 @node Multilibs, , Suffixes, Miscellaneous
4105 @section Support for Multilibs
4107 Automake has support for an obscure feature called multilibs. A
4108 @dfn{multilib} is a library which is built for multiple different ABIs
4109 at a single time; each time the library is built with a different target
4110 flag combination. This is only useful when the library is intended to
4111 be cross-compiled, and it is almost exclusively used for compiler
4114 The multilib support is still experimental. Only use it if you are
4115 familiar with multilibs and can debug problems you might encounter.
4118 @node Include, Conditionals, Miscellaneous, Top
4122 @cindex Including Makefile fragment
4123 @cindex Makefile fragment, including
4125 Automake supports an @code{include} directive which can be used to
4126 include other @file{Makefile} fragments when @code{automake} is run.
4127 Note that these fragments are read and interpreted by @code{automake},
4128 not by @code{make}. As with conditionals, @code{make} has no idea that
4129 @code{include} is in use.
4131 There are two forms of @code{include}:
4134 @item include $(srcdir)/file
4135 Include a fragment which is found relative to the current source
4138 @item include $(top_srcdir)/file
4139 Include a fragment which is found relative to the top source directory.
4142 Note that if a fragment is included inside a conditional, then the
4143 condition applies to the entire contents of that fragment.
4146 @node Conditionals, Gnits, Include, Top
4147 @chapter Conditionals
4149 @cindex Conditionals
4151 Automake supports a simple type of conditionals.
4153 @cvindex AM_CONDITIONAL
4154 Before using a conditional, you must define it by using
4155 @code{AM_CONDITIONAL} in the @code{configure.in} file (@pxref{Macros}).
4157 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
4158 The conditional name, @var{conditional}, should be a simple string
4159 starting with a letter and containing only letters, digits, and
4160 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
4161 which are reserved by Automake.
4163 The shell @var{condition} (suitable for use in a shell @code{if}
4164 statement) is evaluated when @code{configure} is run. Note that you
4165 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
4166 time @code{configure} is run -- if @code{AM_CONDITIONAL} is run
4167 conditionally (e.g., in a shell @code{if} statement), then the result
4168 will confuse automake.
4171 @cindex --enable-debug, example
4172 @cindex Example conditional --enable-debug
4173 @cindex Conditional example, --enable-debug
4175 Conditionals typically depend upon options which the user provides to
4176 the @code{configure} script. Here is an example of how to write a
4177 conditional which is true if the user uses the @samp{--enable-debug}
4181 AC_ARG_ENABLE(debug,
4182 [ --enable-debug Turn on debugging],
4183 [case "$@{enableval@}" in
4186 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
4187 esac],[debug=false])
4188 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
4191 Here is an example of how to use that conditional in @file{Makefile.am}:
4203 noinst_PROGRAMS = $(DBG)
4206 This trivial example could also be handled using EXTRA_PROGRAMS
4207 (@pxref{A Program}).
4209 You may only test a single variable in an @code{if} statement, possibly
4210 negated using @samp{!}. The @code{else} statement may be omitted.
4211 Conditionals may be nested to any depth. You may specify an argument to
4212 @code{else} in which case it must be the negation of the condition used
4213 for the current @code{if}. Similarly you may specify the condition
4214 which is closed by an @code{end}:
4225 Unbalanced conditions are errors.
4227 Note that conditionals in Automake are not the same as conditionals in
4228 GNU Make. Automake conditionals are checked at configure time by the
4229 @file{configure} script, and affect the translation from
4230 @file{Makefile.in} to @file{Makefile}. They are based on options passed
4231 to @file{configure} and on results that @file{configure} has discovered
4232 about the host system. GNU Make conditionals are checked at @code{make}
4233 time, and are based on variables passed to the make program or defined
4234 in the @file{Makefile}.
4236 Automake conditionals will work with any make program.
4239 @node Gnits, Cygnus, Conditionals, Top
4240 @chapter The effect of @code{--gnu} and @code{--gnits}
4242 @cindex --gnu, required files
4243 @cindex --gnu, complete description
4245 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
4246 variable) causes @code{automake} to check the following:
4250 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
4251 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
4252 directory of the package.
4255 The options @samp{no-installman} and @samp{no-installinfo} are
4259 Note that this option will be extended in the future to do even more
4260 checking; it is advisable to be familiar with the precise requirements
4261 of the GNU standards. Also, @samp{--gnu} can require certain
4262 non-standard GNU programs to exist for use by various maintainer-only
4263 targets; for instance in the future @code{pathchk} might be required for
4266 @cindex --gnits, complete description
4268 The @samp{--gnits} option does everything that @samp{--gnu} does, and
4269 checks the following as well:
4273 @samp{make dist} will check to make sure the @file{NEWS} file has been
4274 updated to the current version.
4277 @samp{VERSION} is checked to make sure its format complies with Gnits
4279 @c FIXME xref when standards are finished
4282 @cindex README-alpha
4283 If @samp{VERSION} indicates that this is an alpha release, and the file
4284 @file{README-alpha} appears in the topmost directory of a package, then
4285 it is included in the distribution. This is done in @samp{--gnits}
4286 mode, and no other, because this mode is the only one where version
4287 number formats are constrained, and hence the only mode where Automake
4288 can automatically determine whether @file{README-alpha} should be
4292 The file @file{THANKS} is required.
4296 @node Cygnus, Extending, Gnits, Top
4297 @chapter The effect of @code{--cygnus}
4299 @cindex Cygnus strictness
4301 Some packages, notably GNU GCC and GNU gdb, have a build environment
4302 originally written at Cygnus Support (subsequently renamed Cygnus
4303 Solutions, and then later purchased by Red Hat). Packages with this
4304 ancestry are sometimes referred to as ``Cygnus'' trees.
4306 A Cygnus tree has slightly different rules for how a @file{Makefile.in}
4307 is to be constructed. Passing @samp{--cygnus} to @code{automake} will
4308 cause any generated @file{Makefile.in} to comply with Cygnus rules.
4310 Here are the precise effects of @samp{--cygnus}:
4314 Info files are always created in the build directory, and not in the
4318 @file{texinfo.tex} is not required if a Texinfo source file is
4319 specified. The assumption is that the file will be supplied, but in a
4320 place that Automake cannot find. This assumption is an artifact of how
4321 Cygnus packages are typically bundled.
4324 @samp{make dist} is not supported, and the rules for it are not
4325 generated. Cygnus-style trees use their own distribution mechanism.
4328 Certain tools will be searched for in the build tree as well as in the
4329 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
4330 @code{makeinfo} and @code{texi2dvi}.
4333 @code{--foreign} is implied.
4336 The options @samp{no-installinfo} and @samp{no-dependencies} are
4340 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
4344 The @code{check} target doesn't depend on @code{all}.
4347 GNU maintainers are advised to use @samp{gnu} strictness in preference
4348 to the special Cygnus mode. Some day, perhaps, the differences between
4349 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
4350 more standards compliant). At that time the special Cygnus mode will be
4354 @node Extending, Distributing, Cygnus, Top
4355 @chapter When Automake Isn't Enough
4357 Automake's implicit copying semantics means that many problems can be
4358 worked around by simply adding some @code{make} targets and rules to
4359 @file{Makefile.in}. Automake will ignore these additions.
4361 @cindex -local targets
4362 @cindex local targets
4364 There are some caveats to doing this. Although you can overload a
4365 target already used by Automake, it is often inadvisable, particularly
4366 in the topmost directory of a package with subdirectories. However,
4367 various useful targets have a @samp{-local} version you can specify in
4368 your @file{Makefile.in}. Automake will supplement the standard target
4369 with these user-supplied targets.
4374 @trindex check-local
4375 @trindex install-data-local
4376 @trindex install-exec-local
4377 @trindex uninstall-local
4378 @trindex mostlyclean-local
4379 @trindex clean-local
4380 @trindex distclean-local
4381 @trindex installdirs-local
4382 @trindex installcheck-local
4384 The targets that support a local version are @code{all}, @code{info},
4385 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
4386 @code{uninstall}, @code{installdirs}, @code{installcheck} and the
4387 various @code{clean} targets (@code{mostlyclean}, @code{clean},
4388 @code{distclean}, and @code{maintainer-clean}). Note that there are no
4389 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
4390 use @code{uninstall-local}. It doesn't make sense to uninstall just
4391 data or just executables.
4396 @trindex install-data
4397 @trindex install-exec
4400 For instance, here is one way to install a file in @file{/etc}:
4404 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
4407 @cindex -hook targets
4408 @cindex hook targets
4410 Some targets also have a way to run another target, called a @dfn{hook},
4411 after their work is done. The hook is named after the principal target,
4412 with @samp{-hook} appended. The targets allowing hooks are
4413 @code{install-data}, @code{install-exec}, @code{uninstall}, @code{dist},
4414 and @code{distcheck}.
4415 @trindex install-data-hook
4416 @trindex install-exec-hook
4419 For instance, here is how to create a hard link to an installed program:
4423 ln $(bindir)/program $(bindir)/proglink
4426 @c FIXME should include discussion of variables you can use in these
4430 @node Distributing, Macro and Variable Index, Extending, Top
4431 @chapter Distributing @file{Makefile.in}s
4433 Automake places no restrictions on the distribution of the resulting
4434 @file{Makefile.in}s. We still encourage software authors to distribute
4435 their work under terms like those of the GPL, but doing so is not
4436 required to use Automake.
4438 Some of the files that can be automatically installed via the
4439 @code{--add-missing} switch do fall under the GPL. However, these also
4440 have a special exception allowing you to distribute them with your
4441 package, regardless of the licensing you choose.
4445 @node Macro and Variable Index, General Index, Distributing, Top
4446 @unnumbered Macro and Variable Index
4452 @node General Index, , Macro and Variable Index, Top
4453 @unnumbered General Index