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}:
625 Since your program doesn't have any complicating factors (e.g., it
626 doesn't use @code{gettext}, it doesn't want to build a shared library),
627 you're done with this part. That was easy!
629 @cindex aclocal program, introduction
630 @cindex aclocal.m4, preexisting
631 @cindex acinclude.m4, defined
633 Now you must regenerate @file{configure}. But to do that, you'll need
634 to tell @code{autoconf} how to find the new macro you've used. The
635 easiest way to do this is to use the @code{aclocal} program to generate
636 your @file{aclocal.m4} for you. But wait... you already have an
637 @file{aclocal.m4}, because you had to write some hairy macros for your
638 program. The @code{aclocal} program lets you put your own macros into
639 @file{acinclude.m4}, so simply rename and then run:
642 mv aclocal.m4 acinclude.m4
647 @cindex zardoz example
649 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
650 Since @code{zardoz} is a user program, you want to install it where the
651 rest of the user programs go. Additionally, @code{zardoz} has some
652 Texinfo documentation. Your @file{configure.in} script uses
653 @code{AC_REPLACE_FUNCS}, so you need to link against @samp{@@LIBOBJS@@}.
654 So here's what you'd write:
657 bin_PROGRAMS = zardoz
658 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
659 zardoz_LDADD = @@LIBOBJS@@
661 info_TEXINFOS = zardoz.texi
664 Now you can run @code{automake --add-missing} to generate your
665 @file{Makefile.in} and grab any auxiliary files you might need, and
669 @node Hello, etags, Complete, Examples
670 @section A classic program
672 @cindex Example, GNU Hello
673 @cindex Hello example
674 @cindex GNU Hello, example
676 @uref{ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz, GNU hello} is
677 renowned for its classic simplicity and versatility. This section shows
678 how Automake could be used with the GNU Hello package. The examples
679 below are from the latest beta version of GNU Hello, but with all of the
680 maintainer-only code stripped out, as well as all copyright comments.
682 Of course, GNU Hello is somewhat more featureful than your traditional
683 two-liner. GNU Hello is internationalized, does option processing, and
684 has a manual and a test suite.
686 @cindex configure.in, from GNU Hello
687 @cindex GNU Hello, configure.in
688 @cindex Hello, configure.in
690 Here is the @file{configure.in} from GNU Hello:
691 @c FIXME: This definitively requires an update.
694 dnl Process this file with autoconf to produce a configure script.
696 AM_INIT_AUTOMAKE(hello, 1.3.11)
697 AM_CONFIG_HEADER(config.h)
699 dnl Set of available languages.
700 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
702 dnl Checks for programs.
706 dnl Checks for libraries.
708 dnl Checks for header files.
710 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
712 dnl Checks for library functions.
715 dnl Check for st_blksize in struct stat
718 dnl internationalization macros
720 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
721 src/Makefile tests/Makefile tests/hello],
722 [chmod +x tests/hello])
725 The @samp{AM_} macros are provided by Automake (or the Gettext library);
726 the rest are standard Autoconf macros.
729 The top-level @file{Makefile.am}:
732 EXTRA_DIST = BUGS ChangeLog.O
733 SUBDIRS = doc intl po src tests
736 As you can see, all the work here is really done in subdirectories.
738 The @file{po} and @file{intl} directories are automatically generated
739 using @code{gettextize}; they will not be discussed here.
741 @cindex Texinfo file handling example
742 @cindex Example, handling Texinfo files
744 In @file{doc/Makefile.am} we see:
747 info_TEXINFOS = hello.texi
748 hello_TEXINFOS = gpl.texi
751 This is sufficient to build, install, and distribute the GNU Hello
754 @cindex Regression test example
755 @cindex Example, regression test
757 Here is @file{tests/Makefile.am}:
761 EXTRA_DIST = hello.in testdata
764 The script @file{hello} is generated by @code{configure}, and is the
765 only test case. @code{make check} will run this test.
767 @cindex INCLUDES, example usage
769 Last we have @file{src/Makefile.am}, where all the real work is done:
773 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
774 hello_LDADD = @@INTLLIBS@@ @@ALLOCA@@
775 localedir = $(datadir)/locale
776 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
780 @node etags, , Hello, Examples
781 @section Building etags and ctags
783 @cindex Example, ctags and etags
784 @cindex ctags Example
785 @cindex etags Example
787 Here is another, trickier example. It shows how to generate two
788 programs (@code{ctags} and @code{etags}) from the same source file
789 (@file{etags.c}). The difficult part is that each compilation of
790 @file{etags.c} requires different @code{cpp} flags.
793 bin_PROGRAMS = etags ctags
795 ctags_LDADD = ctags.o
798 $(COMPILE) -DETAGS_REGEXPS -c etags.c
801 $(COMPILE) -DCTAGS -o ctags.o -c etags.c
804 Note that @code{ctags_SOURCES} is defined to be empty---that way no
805 implicit value is substituted. The implicit value, however, is used to
806 generate @code{etags} from @file{etags.o}.
808 @code{ctags_LDADD} is used to get @file{ctags.o} into the link line.
809 @code{ctags_DEPENDENCIES} is generated by Automake.
811 The above rules won't work if your compiler doesn't accept both
812 @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
813 bogus dependency (to avoid problems with a parallel @code{make}):
816 etags.o: etags.c ctags.o
817 $(COMPILE) -DETAGS_REGEXPS -c etags.c
820 $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
823 Also, these explicit rules do not work if the de-ANSI-fication feature
824 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
828 etags._o: etags._c ctags.o
829 $(COMPILE) -DETAGS_REGEXPS -c etags.c
832 $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
835 As it turns out, there is also a much easier way to do this same task.
836 Some of the above techniques are useful enough that we've kept the
837 example in the manual. However if you were to build @code{etags} and
838 @code{ctags} in real life, you would probably use per-program
839 compilation flags, like so:
842 bin_PROGRAMS = ctags etags
844 ctags_SOURCES = etags.c
845 ctags_CFLAGS = -DCTAGS
847 etags_SOURCES = etags.c
848 etags_CFLAGS = -DETAGS_REGEXPS
851 In this case Automake will cause @file{etags.c} to be compiled twice,
852 with different flags. De-ANSI-fication will work automatically. In
853 this instance, the names of the object files would be chosen by
854 automake; they would be @file{ctags-etags.o} and @file{etags-etags.o}.
855 (The name of the object files rarely matters.)
858 @node Invoking Automake, configure, Examples, Top
859 @chapter Creating a @file{Makefile.in}
861 @cindex Multiple configure.in files
862 @cindex Invoking Automake
863 @cindex Automake, invoking
865 To create all the @file{Makefile.in}s for a package, run the
866 @code{automake} program in the top level directory, with no arguments.
867 @code{automake} will automatically find each appropriate
868 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
869 and generate the corresponding @file{Makefile.in}. Note that
870 @code{automake} has a rather simplistic view of what constitutes a
871 package; it assumes that a package has only one @file{configure.in}, at
872 the top. If your package has multiple @file{configure.in}s, then you
873 must run @code{automake} in each directory holding a
876 You can optionally give @code{automake} an argument; @file{.am} is
877 appended to the argument and the result is used as the name of the input
878 file. This feature is generally only used to automatically rebuild an
879 out-of-date @file{Makefile.in}. Note that @code{automake} must always
880 be run from the topmost directory of a project, even if being used to
881 regenerate the @file{Makefile.in} in some subdirectory. This is
882 necessary because @code{automake} must scan @file{configure.in}, and
883 because @code{automake} uses the knowledge that a @file{Makefile.in} is
884 in a subdirectory to change its behavior in some cases.
886 @cindex Automake options
887 @cindex Options, Automake
889 @code{automake} accepts the following options:
891 @cindex Extra files distributed with Automake
892 @cindex Files distributed with Automake
899 @opindex --add-missing
900 Automake requires certain common files to exist in certain situations;
901 for instance @file{config.guess} is required if @file{configure.in} runs
902 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
903 files; this option will cause the missing ones to be automatically added
904 to the package, whenever possible. In general if Automake tells you a
905 file is missing, try using this option. By default Automake tries to
906 make a symbolic link pointing to its own copy of the missing file; this
907 can be changed with @code{--copy}.
909 @item --libdir=@var{dir}
911 Look for Automake data files in directory @var{dir} instead of in the
912 installation directory. This is typically used for debugging.
918 When used with @code{--add-missing}, causes installed files to be
919 copied. The default is to make a symbolic link.
923 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
924 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
928 @itemx --force-missing
929 @opindex --force-missing
930 When used with @code{--add-missing}, causes standard files to be rebuilt
931 even if they already exist in the source tree. This involves removing
932 the file from the source tree before creating the new symlink (or, with
933 @code{--copy}, copying the new file).
937 Set the global strictness to @samp{foreign}. For more information, see
942 Set the global strictness to @samp{gnits}. For more information, see
947 Set the global strictness to @samp{gnu}. For more information, see
948 @ref{Gnits}. This is the default strictness.
952 Print a summary of the command line options and exit.
957 This disables the dependency tracking feature; see @ref{Dependencies}.
960 @opindex --include-deps
961 This enables the dependency tracking feature. This feature is enabled
962 by default. This option is provided for historical reasons only and
963 probably should not be used.
967 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
968 @file{configure.in}. This option causes it to only update those
969 @file{Makefile.in}s which are out of date with respect to one of their
973 @itemx --output-dir=@var{dir}
975 @opindex --output-dir
976 Put the generated @file{Makefile.in} in the directory @var{dir}.
977 Ordinarily each @file{Makefile.in} is created in the directory of the
978 corresponding @file{Makefile.am}. This option is used when making
985 Cause Automake to print information about which files are being read or
990 Print the version number of Automake and exit.
996 @samp{--Werror} will cause all warnings issued by @code{automake} to
997 become errors. Errors affect the exit status of @code{automake}, while
998 warnings do not. @samp{--Wno-error}, the default, causes warnings to be
999 treated as warnings only.
1003 @node configure, Top level, Invoking Automake, Top
1004 @chapter Scanning @file{configure.in}
1006 @cindex configure.in, scanning
1007 @cindex Scanning configure.in
1009 Automake scans the package's @file{configure.in} to determine certain
1010 information about the package. Some @code{autoconf} macros are required
1011 and some variables must be defined in @file{configure.in}. Automake
1012 will also use information from @file{configure.in} to further tailor its
1015 Automake also supplies some Autoconf macros to make the maintenance
1016 easier. These macros can automatically be put into your
1017 @file{aclocal.m4} using the @code{aclocal} program.
1020 * Requirements:: Configuration requirements
1021 * Optional:: Other things Automake recognizes
1022 * Invoking aclocal:: Auto-generating aclocal.m4
1023 * Macros:: Autoconf macros supplied with Automake
1024 * Extending aclocal:: Writing your own aclocal macros
1028 @node Requirements, Optional, configure, configure
1029 @section Configuration requirements
1031 @cindex Automake requirements
1032 @cindex Requirements of Automake
1034 The one real requirement of Automake is that your @file{configure.in}
1035 call @code{AM_INIT_AUTOMAKE}. This macro does several things which are
1036 required for proper Automake operation.
1037 @cvindex AM_INIT_AUTOMAKE
1039 Here are the other macros which Automake requires but which are not run
1040 by @code{AM_INIT_AUTOMAKE}:
1042 @cindex AC_OUTPUT, scanning
1046 Automake uses this to determine which files to create (@pxref{Output, ,
1047 Creating Output Files, autoconf, The Autoconf Manual}). Listed files
1048 named @code{Makefile} are treated as @file{Makefile}s. Other listed
1049 files are treated differently. Currently the only difference is that a
1050 @file{Makefile} is removed by @code{make distclean}, while other files
1051 are removed by @code{make clean}.
1052 @c FIXME: this is in violation of standards!
1056 You may need the following macros in some conditions, even though they
1060 @item AC_CHECK_TOOL([STRIP],[strip])
1061 @cindex STRIP, how to setup
1062 @cindex install-strip and STRIP
1063 @cvindex AC_CHECK_TOOL([STRIP],[strip])
1064 Installed binaries are usually stripped using @code{strip} when you run
1065 @code{make install-strip}. However @code{strip} might not be the
1066 right tool to use in cross-compilation environments, therefore
1067 Automake will honor the @code{STRIP} environment variable to overrule
1068 the program used to perform stripping. Automake will not set @code{STRIP}
1069 itself. If your package is not setup for cross-compilation you do not
1070 have to care (@code{strip} is ok), otherwise you can set @code{STRIP}
1071 automatically by calling @code{AC_CHECK_TOOL([STRIP],[strip])} from
1072 your @file{configure.in}.
1076 @node Optional, Invoking aclocal, Requirements, configure
1077 @section Other things Automake recognizes
1079 @cindex Macros Automake recognizes
1080 @cindex Recognized macros by Automake
1082 Automake will also recognize the use of certain macros and tailor the
1083 generated @file{Makefile.in} appropriately. Currently recognized macros
1084 and their effects are:
1087 @item AC_CONFIG_HEADER
1088 Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar
1089 to @code{AC_CONFIG_HEADER} (@pxref{Configuration Headers, ,
1090 Configuration Header Files, autoconf, The Autoconf Manual}), but does
1091 some useful Automake-specific work.
1092 @cvindex AC_CONFIG_HEADER
1094 @item AC_CONFIG_AUX_DIR
1095 Automake will look for various helper scripts, such as
1096 @file{mkinstalldirs}, in the directory named in this macro invocation.
1097 If not seen, the scripts are looked for in their @samp{standard}
1098 locations (either the top source directory, or in the source directory
1099 corresponding to the current @file{Makefile.am}, whichever is
1100 appropriate). @xref{Input, , Finding `configure' Input, autoconf, The
1102 @cvindex AC_CONFIG_AUX_DIR
1103 FIXME: give complete list of things looked for in this directory
1106 Automake will insert definitions for the variables defined by
1107 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
1108 or library. @xref{System Services, , System Services, autoconf, The
1110 @cvindex AC_PATH_XTRA
1112 @item AC_CANONICAL_HOST
1113 @itemx AC_CHECK_TOOL
1114 Automake will ensure that @file{config.guess} and @file{config.sub}
1115 exist. Also, the @file{Makefile} variables @samp{host_alias} and
1116 @samp{host_triplet} are introduced. See both @ref{Canonicalizing, ,
1117 Getting the Canonical System Type, autoconf, The Autoconf Manual}, and
1118 @ref{Generic Programs, , Generic Program Checks, autoconf, The Autoconf
1120 @c fixme xref autoconf docs.
1121 @cvindex AC_CANONICAL_HOST
1122 @cvindex AC_CHECK_TOOL
1124 @vindex host_triplet
1126 @item AC_CANONICAL_SYSTEM
1127 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
1128 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
1129 @xref{Canonicalizing, , Getting the Canonical System Type, autoconf, The
1131 @cvindex AC_CANONICAL_SYSTEM
1133 @vindex target_alias
1135 @item AC_FUNC_ALLOCA
1136 @itemx AC_FUNC_ERROR_AT_LINE
1137 @itemx AC_FUNC_FNMATCH
1138 @itemx AC_FUNC_GETLOADAVG
1139 @itemx AC_FUNC_MEMCMP
1140 @itemx AC_FUNC_MKTIME
1141 @itemx AC_FUNC_OBSTACK
1142 @itemx AC_FUNC_STRTOD
1143 @itemx AC_REPLACE_FUNCS
1144 @itemx AC_REPLACE_GNU_GETOPT
1145 @itemx AC_STRUCT_ST_BLOCKS
1146 @itemx AM_WITH_REGEX
1147 Automake will ensure that the appropriate dependencies are generated for
1148 the objects corresponding to these macros. Also, Automake will verify
1149 that the appropriate source files are part of the distribution. Note
1150 that Automake does not come with any of the C sources required to use
1151 these macros, so @code{automake -a} will not install the sources.
1152 @xref{A Library}, for more information. Also, see @ref{Particular
1153 Functions, , Particular Function Checks, autoconf, The Autoconf Manual}.
1154 @cvindex AC_FUNC_ALLOCA
1155 @cvindex AC_FUNC_ERROR_AT_LINE
1156 @cvindex AC_FUNC_FNMATCH
1157 @cvindex AC_FUNC_GETLOADAVG
1158 @cvindex AC_FUNC_MEMCMP
1159 @cvindex AC_FUNC_MKTIME
1160 @cvindex AC_FUNC_OBSTACK
1161 @cvindex AC_FUNC_STRTOD
1162 @cvindex AC_REPLACE_FUNCS
1163 @cvindex AC_REPLACE_GNU_GETOPT
1164 @cvindex AC_STRUCT_ST_BLOCKS
1165 @cvindex AM_WITH_REGEX
1168 Automake will detect statements which put @file{.o} files into
1169 @code{LIBOBJS}, and will treat these additional files as if they were
1170 discovered via @code{AC_REPLACE_FUNCS}. @xref{Generic Functions, ,
1171 Generic Function Checks, autoconf, The Autoconf Manual}.
1174 @item AC_PROG_RANLIB
1175 This is required if any libraries are built in the package.
1176 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1178 @cvindex AC_PROG_RANLIB
1181 This is required if any C++ source is included. @xref{Particular
1182 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1183 @cvindex AC_PROG_CXX
1186 This is required if any Fortran 77 source is included. This macro is
1187 distributed with Autoconf version 2.13 and later. @xref{Particular
1188 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1189 @cvindex AC_PROG_F77
1191 @item AC_F77_LIBRARY_LDFLAGS
1192 This is required for programs and shared libraries that are a mixture of
1193 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
1194 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
1195 @cvindex AC_F77_LIBRARY_LDFLAGS
1197 @item AC_PROG_LIBTOOL
1198 Automake will turn on processing for @code{libtool} (@pxref{Top, ,
1199 Introduction, libtool, The Libtool Manual}).
1200 @cvindex AC_PROG_LIBTOOL
1203 If a Yacc source file is seen, then you must either use this macro or
1204 define the variable @samp{YACC} in @file{configure.in}. The former is
1205 preferred (@pxref{Particular Programs, , Particular Program Checks,
1206 autoconf, The Autoconf Manual}).
1207 @cvindex AC_PROG_YACC
1211 If a Lex source file is seen, then this macro must be used.
1212 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1214 @cvindex AC_PROG_LEX
1216 @item AM_C_PROTOTYPES
1217 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
1218 @cvindex AM_C_PROTOTYPES
1220 @item AM_GNU_GETTEXT
1221 This macro is required for packages which use GNU gettext
1222 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1223 this macro it ensures that the package meets some of gettext's
1225 @cvindex AM_GNU_GETTEXT
1227 @item AM_MAINTAINER_MODE
1228 @opindex --enable-maintainer-mode
1229 This macro adds a @samp{--enable-maintainer-mode} option to
1230 @code{configure}. If this is used, @code{automake} will cause
1231 @samp{maintainer-only} rules to be turned off by default in the
1232 generated @file{Makefile.in}s. This macro is disallowed in @samp{Gnits}
1233 mode (@pxref{Gnits}). This macro defines the @samp{MAINTAINER_MODE}
1234 conditional, which you can use in your own @file{Makefile.am}.
1235 @cvindex AM_MAINTAINER_MODE
1238 @itemx AC_CHECK_TOOL
1239 @itemx AC_CHECK_PROG
1240 @itemx AC_CHECK_PROGS
1242 @itemx AC_PATH_PROGS
1243 For each of these macros, the first argument is automatically defined as
1244 a variable in each generated @file{Makefile.in}. @xref{Setting Output
1245 Variables, , Setting Output Variables, autoconf, The Autoconf Manual},
1246 and @ref{Generic Programs, , Generic Program Checks, autoconf, The
1249 @cvindex AC_CHECK_TOOL
1250 @cvindex AC_CHECK_PROG
1251 @cvindex AC_CHECK_PROGS
1252 @cvindex AC_PATH_PROG
1253 @cvindex AC_PATH_PROGS
1258 @node Invoking aclocal, Macros, Optional, configure
1259 @section Auto-generating aclocal.m4
1261 @cindex Invoking aclocal
1262 @cindex aclocal, Invoking
1264 Automake includes a number of Autoconf macros which can be used in your
1265 package; some of them are actually required by Automake in certain
1266 situations. These macros must be defined in your @file{aclocal.m4};
1267 otherwise they will not be seen by @code{autoconf}.
1269 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1270 files based on the contents of @file{configure.in}. This provides a
1271 convenient way to get Automake-provided macros, without having to
1272 search around. Also, the @code{aclocal} mechanism is extensible for use
1275 At startup, @code{aclocal} scans all the @file{.m4} files it can find,
1276 looking for macro definitions. Then it scans @file{configure.in}. Any
1277 mention of one of the macros found in the first step causes that macro,
1278 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1280 The contents of @file{acinclude.m4}, if it exists, are also
1281 automatically included in @file{aclocal.m4}. This is useful for
1282 incorporating local macros into @file{configure}.
1284 @code{aclocal} tries to be smart about looking for new @code{AC_DEFUN}s
1285 in the files it scans. It will warn if it finds duplicates. It also
1286 tries to copy the full text of the scanned file into @file{aclocal.m4},
1287 including both @samp{#} and @samp{dnl} comments. If you want to make a
1288 comment which will be completely ignored by @code{aclocal}, use
1289 @samp{##} as the comment leader.
1291 @code{aclocal} accepts the following options:
1294 @item --acdir=@var{dir}
1296 Look for the macro files in @var{dir} instead of the installation
1297 directory. This is typically used for debugging.
1301 Print a summary of the command line options and exit.
1305 Add the directory @var{dir} to the list of directories searched for
1308 @item --output=@var{file}
1310 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1312 @item --print-ac-dir
1313 @opindex --print-ac-dir
1314 Prints the name of the directory which @code{aclocal} will search to
1315 find the @file{.m4} files. When this option is given, normal processing
1316 is suppressed. This option can be used by a package to determine where
1317 to install a macro file.
1321 Print the names of the files it examines.
1325 Print the version number of Automake and exit.
1329 @node Macros, Extending aclocal, Invoking aclocal, configure
1330 @section Autoconf macros supplied with Automake
1332 @c consider generating this node automatically from m4 files.
1335 @item AM_CONFIG_HEADER
1336 Automake will generate rules to automatically regenerate the config
1338 @cvindex AM_CONFIG_HEADER
1340 @item AM_ENABLE_MULTILIB
1341 This is used when a ``multilib'' library is being built. The first
1342 optional argument is the name of the @file{Makefile} being generated; it
1343 defaults to @samp{Makefile}. The second option argument is used to find
1344 the top source directory; it defaults to the empty string (generally
1345 this should not be used unless you are familiar with the internals).
1348 @item _AM_DEPENDENCIES
1349 @itemx AM_SET_DEPDIR
1351 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
1352 These macros are used to implement automake's automatic dependency
1353 tracking scheme. They are called automatically by automake when
1354 required, and there should be no need to invoke them manually.
1356 @item AM_C_PROTOTYPES
1357 Check to see if function prototypes are understood by the compiler. If
1358 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1359 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1360 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1361 values to implement automatic de-ANSI-fication.
1362 @cvindex AM_C_PROTOTYPES
1364 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1365 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1366 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1367 found in @file{<termios.h>}.
1368 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1370 @item AM_INIT_AUTOMAKE([OPTIONS])
1371 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
1372 Runs many macros that most @file{configure.in}'s need. This macro has
1373 two forms, the second of which has two required arguments: the package
1374 and the version number. This latter form is obsolete because the
1375 @var{package} and @var{version} are now arguments of the @samp{AC_INIT}
1376 Autoconf macro, and Automake can get this information from there.
1378 If your @file{configure.in} has:
1381 AM_INIT_AUTOMAKE(mumble, 1.5)
1383 you can modernize it as follow:
1385 AC_INIT(mumble, 1.5)
1386 AC_CONFIG_SRCDIR(src/foo.c)
1390 If this macro is called with a single argument, it is interpreted as a
1391 space-separated list of Automake options which should be applied to
1392 every @file{Makefile.am} in the tree. The effect is as if each option
1393 were listed in @code{AUTOMAKE_OPTIONS}.
1395 By default this macro @code{AC_DEFINE}'s @samp{PACKAGE} and
1396 @samp{VERSION}. This can be avoided by passing the @samp{no-define}
1399 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
1401 or by passing a third non-empty argument to the obsolete form.
1403 @cvindex PACKAGE, prevent definition
1404 @cvindex VERSION, prevent definition
1406 @item AM_MAKE_INCLUDE
1407 This macro is used to discover how the user's @code{make} handles
1408 @code{include} statements. This macro is automatically invoked when
1409 needed; there should be no need to invoke it manually.
1411 @item AM_PATH_LISPDIR
1412 Searches for the program @code{emacs}, and, if found, sets the output
1413 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1414 @cvindex AM_PATH_LISPDIR
1417 Use this macro when you have assembly code in your project. This will
1418 choose the assembler for you (by default the C compiler), and will set
1419 @code{ASFLAGS} if required.
1421 @item AM_PROG_CC_C_O
1422 This is like @code{AC_PROG_CC_C_O}, but it generates its results in the
1423 manner required by automake. You must use this instead of
1424 @code{AC_PROG_CC_C_O} when you need this functionality.
1426 @item AM_PROG_CC_STDC
1427 If the C compiler is not in ANSI C mode by default, try to add an option
1428 to output variable @code{CC} to make it so. This macro tries various
1429 options that select ANSI C on some system or another. It considers the
1430 compiler to be in ANSI C mode if it handles function prototypes correctly.
1432 If you use this macro, you should check after calling it whether the C
1433 compiler has been set to accept ANSI C; if not, the shell variable
1434 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1435 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1436 @code{ansi2knr} option (@pxref{ANSI}).
1439 @cindex HP-UX 10, lex problems
1440 @cindex lex problems with HP-UX 10
1441 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
1442 Program Checks, autoconf, The Autoconf Manual}), but uses the
1443 @code{missing} script on systems that do not have @code{lex}.
1444 @samp{HP-UX 10} is one such system.
1447 This macro finds the @code{gcj} program or causes an error. It sets
1448 @samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
1449 GNU Compiler Collection.
1450 @cvindex AM_PROG_GCJ
1452 @item AM_PROG_INSTALL_STRIP
1453 This is used to find a version of @code{install} which can be used to
1454 @code{strip} a program at installation time. This macro is
1455 automatically included when required.
1457 @item AM_SANITY_CHECK
1458 This checks to make sure that a file created in the build directory is
1459 newer than a file in the source directory. This can fail on systems
1460 where the clock is set incorrectly. This macro is automatically run
1461 from @code{AM_INIT_AUTOMAKE}.
1463 @item AM_SYS_POSIX_TERMIOS
1464 @cvindex am_cv_sys_posix_termios
1465 @cindex POSIX termios headers
1466 @cindex termios POSIX headers
1467 Check to see if POSIX termios headers and functions are available on the
1468 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1469 @samp{yes}. If not, set the variable to @samp{no}.
1471 @item AM_WITH_DMALLOC
1472 @cvindex WITH_DMALLOC
1473 @cindex dmalloc, support for
1474 @opindex --with-dmalloc
1476 @uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
1477 package. If the user configures with @samp{--with-dmalloc}, then define
1478 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
1482 @opindex --with-regex
1483 @cindex regex package
1485 Adds @samp{--with-regex} to the @code{configure} command line. If
1486 specified (the default), then the @samp{regex} regular expression
1487 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1488 @samp{WITH_REGEX} is defined.. If @samp{--without-regex} is given, then
1489 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1490 into @samp{LIBOBJS}.
1495 @node Extending aclocal, , Macros, configure
1496 @section Writing your own aclocal macros
1498 @cindex aclocal, extending
1499 @cindex Extending aclocal
1501 The @code{aclocal} program doesn't have any built-in knowledge of any
1502 macros, so it is easy to extend it with your own macros.
1504 This is mostly used for libraries which want to supply their own
1505 Autoconf macros for use by other programs. For instance the
1506 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1507 should be used by any package using @code{gettext}. When the library is
1508 installed, it installs this macro so that @code{aclocal} will find it.
1510 A file of macros should be a series of @code{AC_DEFUN}'s. The
1511 @code{aclocal} programs also understands @code{AC_REQUIRE}, so it is
1512 safe to put each macro in a separate file. @xref{Prerequisite Macros, ,
1513 , autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
1514 autoconf, The Autoconf Manual}.
1516 A macro file's name should end in @file{.m4}. Such files should be
1517 installed in @file{$(datadir)/aclocal}.
1520 @node Top level, Alternative, configure, Top
1521 @chapter The top-level @file{Makefile.am}
1523 @cindex SUBDIRS, explained
1525 In packages with subdirectories, the top level @file{Makefile.am} must
1526 tell Automake which subdirectories are to be built. This is done via
1527 the @code{SUBDIRS} variable.
1530 The @code{SUBDIRS} macro holds a list of subdirectories in which
1531 building of various sorts can occur. Many targets (e.g. @code{all}) in
1532 the generated @file{Makefile} will run both locally and in all specified
1533 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1534 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1535 (after configuration). This allows inclusion of libraries from packages
1536 which do not use Automake (such as @code{gettext}). The directories
1537 mentioned in @code{SUBDIRS} must be direct children of the current
1538 directory. For instance, you cannot put @samp{src/subdir} into
1541 In packages that use subdirectories, the top-level @file{Makefile.am} is
1542 often very short. For instance, here is the @file{Makefile.am} from the
1543 GNU Hello distribution:
1546 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1547 SUBDIRS = doc intl po src tests
1550 @cindex SUBDIRS, overriding
1551 @cindex Overriding SUBDIRS
1553 It is possible to override the @code{SUBDIRS} variable if, like in the
1554 case of GNU @code{Inetutils}, you want to only build a subset of the
1555 entire package. In your @file{Makefile.am} include:
1558 SUBDIRS = @@MY_SUBDIRS@@
1561 Then in your @file{configure.in} you can specify:
1564 MY_SUBDIRS="src doc lib po"
1565 AC_SUBST(MY_SUBDIRS)
1568 (Note that we don't use the variable name @code{SUBDIRS} in our
1569 @file{configure.in}; that would cause Automake to believe that every
1570 @file{Makefile.in} should recurse into the listed subdirectories.)
1572 The upshot of this is that Automake is tricked into building the package
1573 to take the subdirs, but doesn't actually bind that list until
1574 @code{configure} is run.
1576 Although the @code{SUBDIRS} macro can contain configure substitutions
1577 (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
1578 contents of this variable.
1580 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1581 @code{AC_PROG_MAKE_SET}. When Automake invokes @code{make} in a
1582 subdirectory, it uses the value of the @code{MAKE} variable. It passes
1583 the value of the variable @code{AM_MAKEFLAGS} to the @code{make}
1584 invocation; this can be set in @file{Makefile.am} if there are flags you
1585 must always pass to @code{make}.
1589 The use of @code{SUBDIRS} is not restricted to just the top-level
1590 @file{Makefile.am}. Automake can be used to construct packages of
1593 By default, Automake generates @file{Makefiles} which work depth-first
1594 (@samp{postfix}). However, it is possible to change this ordering. You
1595 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
1596 putting @samp{.} first will cause a @samp{prefix} ordering of
1597 directories. All @samp{clean} targets are run in reverse order of build
1600 Sometimes, such as when running @code{make dist}, you want all possible
1601 subdirectories to be examined. In this case Automake will use
1602 @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to
1603 recurse. This variable will also be used when the user runs
1604 @code{distclean} or @code{maintainer-clean}. It should be set to the
1605 full list of subdirectories in the project. If this macro is not set,
1606 Automake will attempt to set it for you.
1609 @node Alternative, Rebuilding, Top level, Top
1610 @chapter An Alternative Approach to Subdirectories
1612 If you've ever read Peter Miller's excellent paper,
1613 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
1614 Recursive Make Considered Harmful}, the preceding section on the use of
1615 subdirectories will probably come as unwelcome advice. For those who
1616 haven't read the paper, Miller's main thesis is that recursive
1617 @code{make} invocations are both slow and error-prone.
1619 Automake provides sufficient cross-directory support @footnote{We
1620 believe. This work is new and there are probably warts.
1621 @xref{Introduction}, for information on reporting bugs.} to enable you
1622 to write a single @file{Makefile.am} for a complex multi-directory
1626 By default an installable file specified in a subdirectory will have its
1627 directory name stripped before installation. For instance, in this
1628 example, the header file will be installed as
1629 @file{$(includedir)/stdio.h}:
1632 include_HEADERS = inc/stdio.h
1636 @cindex Path stripping, avoiding
1637 @cindex Avoiding path stripping
1639 However, the @samp{nobase_} prefix can be used to circumvent this path
1640 stripping. In this example, the header file will be installed as
1641 @file{$(includedir)/sys/types.h}:
1644 nobase_include_HEADERS = sys/types.h
1648 @node Rebuilding, Programs, Alternative, Top
1649 @chapter Rebuilding Makefiles
1651 Automake generates rules to automatically rebuild @file{Makefile}s,
1652 @file{configure}, and other derived files like @file{Makefile.in}.
1654 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.in}, then
1655 these automatic rebuilding rules are only enabled in maintainer mode.
1657 Sometimes you need to run @code{aclocal} with an argument like @code{-I}
1658 to tell it where to find @file{.m4} files. Since sometimes @code{make}
1659 will automatically run @code{aclocal}, you need a way to specify these
1660 arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this
1661 holds arguments which are passed verbatim to @code{aclocal}. This macro
1662 is only useful in the top-level @file{Makefile.am}.
1663 @vindex ACLOCAL_AMFLAGS
1666 @node Programs, Other objects, Rebuilding, Top
1667 @chapter Building Programs and Libraries
1669 A large part of Automake's functionality is dedicated to making it easy
1670 to build programs and libraries.
1673 * A Program:: Building a program
1674 * A Library:: Building a library
1675 * A Shared Library:: Building a Libtool library
1676 * Program and Library Variables::
1677 Variables controlling program and
1679 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1680 * Program variables:: Variables used when building a program
1681 * Yacc and Lex:: Yacc and Lex support
1683 * Assembly Support::
1684 * Fortran 77 Support::
1686 * Support for Other Languages::
1687 * ANSI:: Automatic de-ANSI-fication
1688 * Dependencies:: Automatic dependency tracking
1689 * EXEEXT:: Support for executable extensions
1693 @node A Program, A Library, Programs, Programs
1694 @section Building a program
1696 @subsection Introductory blathering
1698 @cindex PROGRAMS, bindir
1699 @vindex bin_PROGRAMS
1700 @vindex sbin_PROGRAMS
1701 @vindex libexec_PROGRAMS
1702 @vindex pkglib_PROGRAMS
1703 @vindex noinst_PROGRAMS
1705 In a directory containing source that gets built into a program (as
1706 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
1707 can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
1708 @code{pkglibdir}, or not at all (@samp{noinst}). They can also be built
1709 only for @code{make check}, in which case the prefix is @samp{check}.
1714 bin_PROGRAMS = hello
1717 In this simple case, the resulting @file{Makefile.in} will contain code
1718 to generate a program named @code{hello}.
1720 Associated with each program are several assisting variables which are
1721 named after the program. These variables are all optional, and have
1722 reasonable defaults. Each variable, its use, and default is spelled out
1723 below; we use the ``hello'' example throughout.
1725 The variable @code{hello_SOURCES} is used to specify which source files
1726 get built into an executable:
1729 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1732 This causes each mentioned @samp{.c} file to be compiled into the
1733 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1735 @cindex _SOURCES primary, defined
1736 @cindex SOURCES primary, defined
1737 @cindex Primary variable, SOURCES
1739 If @samp{hello_SOURCES} is not specified, then it defaults to the single
1740 file @file{hello.c}; that is, the default is to compile a single C file
1741 whose base name is the name of the program itself. (This is a terrible
1742 default but we are stuck with it for historical reasons.)
1746 Multiple programs can be built in a single directory. Multiple programs
1747 can share a single source file, which must be listed in each
1748 @samp{_SOURCES} definition.
1750 @cindex Header files in _SOURCES
1751 @cindex _SOURCES and header files
1753 Header files listed in a @samp{_SOURCES} definition will be included in
1754 the distribution but otherwise ignored. In case it isn't obvious, you
1755 should not include the header file generated by @file{configure} in a
1756 @samp{_SOURCES} variable; this file should not be distributed. Lex
1757 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1760 @subsection Conditional compilations
1762 You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
1763 @samp{_SOURCES} variable. The reason for this is a bit hard to explain,
1764 but suffice to say that it simply won't work. Automake will give an
1765 error if you try to do this.
1767 @cindex EXTRA_prog_SOURCES, defined
1769 Automake must know all the source files that could possibly go into a
1770 program, even if not all the files are built in every circumstance.
1771 Any files which are only conditionally built should be listed in the
1772 appropriate @samp{EXTRA_} variable. For instance, if
1773 @file{hello-linux.c} were conditionally included in @code{hello}, the
1774 @file{Makefile.am} would contain:
1777 EXTRA_hello_SOURCES = hello-linux.c
1780 In this case, @file{hello-linux.o} would be added, via a
1781 @file{configure} substitution, to @code{hello_LDADD} in order to cause
1782 it to be built and linked in.
1784 An often simpler way to compile source files conditionally is to use
1785 Automake conditionals. For instance, you could use this construct to
1786 conditionally use @file{hello-linux.c} or @file{hello-generic.c} as the
1787 basis for your program @file{hello}:
1791 hello_SOURCES = hello-linux.c
1793 hello_SOURCES = hello-generic.c
1797 When using conditionals like this you don't need to use the
1798 @samp{EXTRA_} variable, because Automake will examine the contents of
1799 each variable to construct the complete list of source files.
1801 Sometimes it is useful to determine the programs that are to be built at
1802 configure time. For instance, GNU @code{cpio} only builds @code{mt} and
1803 @code{rmt} under special circumstances.
1805 @cindex EXTRA_PROGRAMS, defined
1807 In this case, you must notify Automake of all the programs that can
1808 possibly be built, but at the same time cause the generated
1809 @file{Makefile.in} to use the programs specified by @code{configure}.
1810 This is done by having @code{configure} substitute values into each
1811 @samp{_PROGRAMS} definition, while listing all optionally built programs
1812 in @code{EXTRA_PROGRAMS}.
1813 @vindex EXTRA_PROGRAMS
1815 Of course you can use Automake conditionals to determine the programs to
1818 @subsection Linking the program
1820 If you need to link against libraries that are not found by
1821 @code{configure}, you can use @code{LDADD} to do so. This variable
1822 actually can be used to add any options to the linker command line.
1825 @cindex prog_LDADD, defined
1827 Sometimes, multiple programs are built in one directory but do not share
1828 the same link-time requirements. In this case, you can use the
1829 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1830 program as it appears in some @samp{_PROGRAMS} variable, and usually
1831 written in lowercase) to override the global @code{LDADD}. If this
1832 variable exists for a given program, then that program is not linked
1836 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
1837 linked against the library @file{libcpio.a}. However, @code{rmt} is
1838 built in the same directory, and has no such link requirement. Also,
1839 @code{mt} and @code{rmt} are only built on certain architectures. Here
1840 is what cpio's @file{src/Makefile.am} looks like (abridged):
1843 bin_PROGRAMS = cpio pax @@MT@@
1844 libexec_PROGRAMS = @@RMT@@
1845 EXTRA_PROGRAMS = mt rmt
1847 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1850 cpio_SOURCES = @dots{}
1851 pax_SOURCES = @dots{}
1852 mt_SOURCES = @dots{}
1853 rmt_SOURCES = @dots{}
1856 @cindex _LDFLAGS, defined
1858 @samp{@var{prog}_LDADD} is inappropriate for passing program-specific
1859 linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
1860 @samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
1864 @cindex _DEPENDENCIES, defined
1866 It is also occasionally useful to have a program depend on some other
1867 target which is not actually part of that program. This can be done
1868 using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
1869 on the contents of such a variable, but no further interpretation is
1872 If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
1873 Automake. The automatically-assigned value is the contents of
1874 @samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
1875 @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
1876 configure substitutions that are left in are only @samp{@@LIBOBJS@@} and
1877 @samp{@@ALLOCA@@}; these are left because it is known that they will not
1878 cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
1882 @node A Library, A Shared Library, A Program, Programs
1883 @section Building a library
1885 @cindex _LIBRARIES primary, defined
1886 @cindex LIBRARIES primary, defined
1887 @cindex Primary variable, LIBRARIES
1889 @vindex lib_LIBRARIES
1890 @vindex pkglib_LIBRARIES
1891 @vindex noinst_LIBRARIES
1893 Building a library is much like building a program. In this case, the
1894 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
1895 @code{libdir} or @code{pkglibdir}.
1897 @xref{A Shared Library}, for information on how to build shared
1898 libraries using Libtool and the @samp{LTLIBRARIES} primary.
1900 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
1901 For instance to create a library named @file{libcpio.a}, but not install
1902 it, you would write:
1905 noinst_LIBRARIES = libcpio.a
1908 The sources that go into a library are determined exactly as they are
1909 for programs, via the @samp{_SOURCES} variables. Note that the library
1910 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
1911 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
1912 not @samp{liblob.a_SOURCES}.
1914 @cindex _LIBADD primary, defined
1915 @cindex LIBADD primary, defined
1916 @cindex Primary variable, LIBADD
1918 Extra objects can be added to a library using the
1919 @samp{@var{library}_LIBADD} variable. This should be used for objects
1920 determined by @code{configure}. Again from @code{cpio}:
1925 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
1928 In addition, sources for extra objects that will not exist until
1929 configure-time must be added to the @code{BUILT_SOURCES} variable
1933 @node A Shared Library, Program and Library Variables, A Library, Programs
1934 @section Building a Shared Library
1936 @cindex Shared libraries, support for
1938 Building shared libraries is a relatively complex matter. For this
1939 reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
1940 Libtool Manual}) was created to help build shared libraries in a
1941 platform-independent way.
1943 @cindex _LTLIBRARIES primary, defined
1944 @cindex LTLIBRARIES primary, defined
1945 @cindex Primary variable, LTLIBRARIES
1946 @cindex Example of shared libraries
1948 @cindex suffix .la, defined
1950 Automake uses Libtool to build libraries declared with the
1951 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
1952 of shared libraries to build. For instance, to create a library named
1953 @file{libgettext.a} and its corresponding shared libraries, and install
1954 them in @samp{libdir}, write:
1957 lib_LTLIBRARIES = libgettext.la
1960 @vindex lib_LTLIBRARIES
1961 @vindex pkglib_LTLIBRARIES
1962 @vindex noinst_LTLIBRARIES
1963 @vindex check_LTLIBRARIES
1965 @cindex check_LTLIBRARIES, not allowed
1967 Note that shared libraries @emph{must} be installed in order to work
1968 properly, so @code{check_LTLIBRARIES} is not allowed. However,
1969 @code{noinst_LTLIBRARIES} is allowed. This feature should be used for
1970 libtool ``convenience libraries''.
1972 @cindex suffix .lo, defined
1974 For each library, the @samp{@var{library}_LIBADD} variable contains the
1975 names of extra libtool objects (@file{.lo} files) to add to the shared
1976 library. The @samp{@var{library}_LDFLAGS} variable contains any
1977 additional libtool flags, such as @samp{-version-info} or
1980 @cindex @@LTLIBOBJS@@, special handling
1982 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
1983 library must use @code{@@LTLIBOBJS@@}. This is required because the
1984 object files that libtool operates on do not necessarily end in
1985 @file{.o}. The libtool manual contains more details on this topic.
1987 For libraries installed in some directory, Automake will automatically
1988 supply the appropriate @samp{-rpath} option. However, for libraries
1989 determined at configure time (and thus mentioned in
1990 @code{EXTRA_LTLIBRARIES}), Automake does not know the eventual
1991 installation directory; for such libraries you must add the
1992 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
1995 Ordinarily, Automake requires that a shared library's name start with
1996 @samp{lib}. However, if you are building a dynamically loadable module
1997 then you might wish to use a "nonstandard" name. In this case, put
1998 @code{-module} into the @samp{_LDFLAGS} variable.
2000 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
2001 libtool, The Libtool Manual}, for more information.
2004 @node Program and Library Variables, LIBOBJS, A Shared Library, Programs
2005 @section Program and Library Variables
2007 Associated with each program are a collection of variables which can be
2008 used to modify how that program is built. There is a similar list of
2009 such variables for each library. The canonical name of the program (or
2010 library) is used as a base for naming these variables.
2012 In the list below, we use the name ``maude'' to refer to the program or
2013 library. In your @file{Makefile.am} you would replace this with the
2014 canonical name of your program. This list also refers to ``maude'' as a
2015 program, but in general the same rules apply for both static and dynamic
2016 libraries; the documentation below notes situations where programs and
2021 This variable, if it exists, lists all the source files which are
2022 compiled to build the program. These files are added to the
2023 distribution by default. When building the program, Automake will cause
2024 each source file to be compiled to a single @file{.o} file (or
2025 @file{.lo} when using libtool). Normally these object files are named
2026 after the source file, but other factors can change this. If a file in
2027 the @samp{_SOURCES} variable has an unrecognized extension, Automake
2028 will do one of two things with it. If a suffix rule exists for turning
2029 files with the unrecognized extension into @file{.o} files, then
2030 automake will treat this file as it will any other source file
2031 (@pxref{Support for Other Languages}). Otherwise, the file will be
2032 ignored as though it were a header file.
2034 The prefixes @samp{dist_} and @samp{nodist_} can be used to control
2035 whether files listed in a @samp{_SOURCES} variable are distributed.
2036 @samp{dist_} is redundant, as sources are distributed by default, but it
2037 can be specified for clarity if desired.
2039 It is possible to have both @samp{dist_} and @samp{nodist_} variants of
2040 a given @samp{_SOURCES} variable at once; this lets you easily
2041 distribute some files and not others, for instance:
2044 nodist_maude_SOURCES = nodist.c
2045 dist_maude_SOURCES = dist-me.c
2048 By default the output file (on Unix systems, the @file{.o} file) will be
2049 put into the current build directory. However, if the option
2050 @code{subdir-objects} is in effect in the current directory then the
2051 @file{.o} file will be put into the subdirectory named after the source
2052 file. For instance, with @code{subdir-objects} enabled,
2053 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
2054 people prefer this mode of operation. You can specify
2055 @code{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
2056 @cindex Subdirectory, objects in
2057 @cindex Objects in subdirectory
2060 @item EXTRA_maude_SOURCES
2061 Automake needs to know the list of files you intend to compile
2062 @emph{statically}. For one thing, this is the only way Automake has of
2063 knowing what sort of language support a given @file{Makefile.in}
2064 requires. @footnote{There are other, more obscure reasons reasons for
2065 this limitation as well.} This means that, for example, you can't put a
2066 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
2067 variable. If you intend to conditionally compile source files and use
2068 @file{configure} to substitute the appropriate object names into, e.g.,
2069 @samp{_LDADD} (see below), then you should list the corresponding source
2070 files in the @samp{EXTRA_} variable.
2072 This variable also supports @samp{dist_} and @samp{nodist_} prefixes,
2073 e.g., @samp{nodist_EXTRA_maude_SOURCES}.
2076 A static library is created by default by invoking @code{$(AR) cru}
2077 followed by the name of the library and then the objects being put into
2078 the library. You can override this by setting the @samp{_AR} variable.
2079 This is usually used with C++; some C++ compilers require a special
2080 invocation in order to instantiate all the templates which should go
2081 into a library. For instance, the SGI C++ compiler likes this macro set
2084 libmaude_a_AR = $(CXX) -ar -o
2088 Extra objects can be added to a static library using the @samp{_LIBADD}
2089 variable. This should be used for objects determined by
2090 @code{configure}. Note that @samp{_LIBADD} is not used for shared
2091 libraries; there you must use @samp{_LDADD}.
2094 Extra objects can be added to a shared library or a program by listing
2095 them in the @samp{_LDADD} variable. This should be used for objects
2096 determined by @code{configure}.
2098 @samp{_LDADD} is inappropriate for passing program-specific linker flags
2099 (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen}).
2100 Use the @samp{_LDFLAGS} variable for this purpose.
2102 For instance, if your @file{configure.in} uses @code{AC_PATH_XTRA}, you
2103 could link your program against the X libraries like so:
2106 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
2110 This variable is used to pass extra flags to the link step of a program
2111 or a shared library.
2114 You can override the linker on a per-program basis. By default the
2115 linker is chosen according to the languages used by the program. For
2116 instance, a program that includes C++ source code would use the C++
2117 compiler to link. The @samp{_LINK} variable must hold the name of a
2118 command which can be passed all the @file{.o} file names as arguments.
2119 Note that the name of the underlying program is @emph{not} passed to
2120 @samp{_LINK}; typically one uses @samp{$@@}:
2123 maude_LINK = $(CCLD) -magic -o $@@
2127 Automake allows you to set compilation flags on a per-program (or
2128 per-library) basis. A single source file can be included in several
2129 programs, and it will potentially be compiled with different flags for
2130 each program. This works for any language directly supported by
2131 Automake. The flags are @samp{_CFLAGS}, @samp{_CXXFLAGS},
2132 @samp{_OBJCFLAGS}, @samp{_YFLAGS}, @samp{_ASFLAGS}, @samp{_FFLAGS},
2133 @samp{_RFLAGS}, and @samp{_GCJFLAGS}.
2135 When using a per-program compilation flag, Automake will choose a
2136 different name for the intermediate object files. Ordinarily a file
2137 like @file{sample.c} will be compiled to produce @file{sample.o}.
2138 However, if the program's @samp{_CFLAGS} variable is set, then the
2139 object file will be named, for instance, @file{maude-sample.o}.
2141 In compilations with per-program flags, the ordinary @samp{AM_} form of
2142 the flags variable is @emph{not} automatically included in the
2143 compilation (however, the user form of the variable @emph{is} included).
2144 So for instance, if you want the hypothetical @file{maude} compilations
2145 to also use the value of @samp{AM_CFLAGS}, you would need to write:
2148 maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
2151 @item maude_DEPENDENCIES
2152 It is also occasionally useful to have a program depend on some other
2153 target which is not actually part of that program. This can be done
2154 using the @samp{_DEPENDENCIES} variable. Each program depends on the
2155 contents of such a variable, but no further interpretation is done.
2157 If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake.
2158 The automatically-assigned value is the contents of @samp{_LDADD}, with
2159 most configure substitutions, @samp{-l}, @samp{-L}, @samp{-dlopen} and
2160 @samp{-dlpreopen} options removed. The configure substitutions that are
2161 left in are only @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are
2162 left because it is known that they will not cause an invalid value for
2163 @samp{_DEPENDENCIES} to be generated.
2165 @item maude_SHORTNAME
2166 On some platforms the allowable file names are very short. In order to
2167 support these systems and per-program compilation flags at the same
2168 time, Automake allows you to set a ``short name'' which will influence
2169 how intermediate object files are named. For instance, if you set
2170 @samp{maude_SHORTNAME} to @samp{m}, then in the above per-program
2171 compilation flag example the object file would be named
2172 @file{m-sample.o} rather than @file{maude-sample.o}. This facility is
2173 rarely needed in practice, and we recommend avoiding it until you find
2178 @node LIBOBJS, Program variables, Program and Library Variables, Programs
2179 @section Special handling for LIBOBJS and ALLOCA
2181 @cindex @@LIBOBJS@@, special handling
2182 @cindex @@ALLOCA@@, special handling
2184 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
2185 @code{@@ALLOCA@@}, and uses this information, plus the list of
2186 @code{LIBOBJS} files derived from @file{configure.in} to automatically
2187 include the appropriate source files in the distribution (@pxref{Dist}).
2188 These source files are also automatically handled in the
2189 dependency-tracking scheme; see @xref{Dependencies}.
2191 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
2192 @samp{_LDADD} or @samp{_LIBADD} variable.
2195 @node Program variables, Yacc and Lex, LIBOBJS, Programs
2196 @section Variables used when building a program
2198 Occasionally it is useful to know which @file{Makefile} variables
2199 Automake uses for compilations; for instance you might need to do your
2200 own compilation in some special cases.
2202 Some variables are inherited from Autoconf; these are @code{CC},
2203 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
2207 There are some additional variables which Automake itself defines:
2211 The contents of this macro are passed to every compilation which invokes
2212 the C preprocessor; it is a list of arguments to the preprocessor. For
2213 instance, @samp{-I} and @samp{-D} options should be listed here.
2215 Automake already provides some @samp{-I} options automatically. In
2216 particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I}
2217 pointing to the directory holding @file{config.h} (if you've used
2218 @code{AC_CONFIG_HEADER} or @code{AM_CONFIG_HEADER}). You can disable
2219 the default @samp{-I} options using the @samp{nostdinc} option.
2222 This does the same job as @samp{AM_CPPFLAGS}. It is an older name for
2223 the same functionality. This macro is deprecated; we suggest using
2224 @samp{AM_CPPFLAGS} instead.
2227 This is the variable which the @file{Makefile.am} author can use to pass
2228 in additional C compiler flags. It is more fully documented elsewhere.
2229 In some situations, this is not used, in preference to the
2230 per-executable (or per-library) @code{CFLAGS}.
2233 This is the command used to actually compile a C source file. The
2234 filename is appended to form the complete command line.
2237 This is the command used to actually link a C program. It already
2238 includes @samp{-o $@@} and the usual variable references (for instance,
2239 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
2240 and libraries to link in.
2244 @node Yacc and Lex, C++ Support, Program variables, Programs
2245 @section Yacc and Lex support
2247 Automake has somewhat idiosyncratic support for Yacc and Lex.
2249 Automake assumes that the @file{.c} file generated by @code{yacc} (or
2250 @code{lex}) should be named using the basename of the input file. That
2251 is, for a yacc source file @file{foo.y}, Automake will cause the
2252 intermediate file to be named @file{foo.c} (as opposed to
2253 @file{y.tab.c}, which is more traditional).
2255 The extension of a yacc source file is used to determine the extension
2256 of the resulting @samp{C} or @samp{C++} file. Files with the extension
2257 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
2258 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
2261 Likewise, lex source files can be used to generate @samp{C} or
2262 @samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
2263 @samp{.lxx} are recognized.
2265 You should never explicitly mention the intermediate (@samp{C} or
2266 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
2269 The intermediate files generated by @code{yacc} (or @code{lex}) will be
2270 included in any distribution that is made. That way the user doesn't
2271 need to have @code{yacc} or @code{lex}.
2273 If a @code{yacc} source file is seen, then your @file{configure.in} must
2274 define the variable @samp{YACC}. This is most easily done by invoking
2275 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
2276 Program Checks, autoconf, The Autoconf Manual}).
2278 When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
2279 @samp{AM_YFLAGS}. The former is a user variable and the latter is
2280 intended for the @file{Makefile.am} author.
2282 Similarly, if a @code{lex} source file is seen, then your
2283 @file{configure.in} must define the variable @samp{LEX}. You can use
2284 @samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
2285 Program Checks, autoconf, The Autoconf Manual}), but using
2286 @code{AM_PROG_LEX} macro (@pxref{Macros}) is recommended.
2288 When @code{lex} is invoked, it is passed @samp{LFLAGS} and
2289 @samp{AM_LFLAGS}. The former is a user variable and the latter is
2290 intended for the @file{Makefile.am} author.
2295 @cindex yacc, multiple parsers
2296 @cindex Multiple yacc parsers
2297 @cindex Multiple lex lexers
2298 @cindex lex, multiple lexers
2301 Automake makes it possible to include multiple @code{yacc} (or
2302 @code{lex}) source files in a single program. Automake uses a small
2303 program called @code{ylwrap} to run @code{yacc} (or @code{lex}) in a
2304 subdirectory. This is necessary because yacc's output filename is
2305 fixed, and a parallel make could conceivably invoke more than one
2306 instance of @code{yacc} simultaneously. The @code{ylwrap} program is
2307 distributed with Automake. It should appear in the directory specified
2308 by @samp{AC_CONFIG_AUX_DIR} (@pxref{Input, , Finding `configure' Input,
2309 autoconf, The Autoconf Manual}), or the current directory if that macro
2310 is not used in @file{configure.in}.
2312 For @code{yacc}, simply managing locking is insufficient. The output of
2313 @code{yacc} always uses the same symbol names internally, so it isn't
2314 possible to link two @code{yacc} parsers into the same executable.
2316 We recommend using the following renaming hack used in @code{gdb}:
2318 #define yymaxdepth c_maxdepth
2319 #define yyparse c_parse
2321 #define yyerror c_error
2322 #define yylval c_lval
2323 #define yychar c_char
2324 #define yydebug c_debug
2325 #define yypact c_pact
2332 #define yyexca c_exca
2333 #define yyerrflag c_errflag
2334 #define yynerrs c_nerrs
2338 #define yy_yys c_yys
2339 #define yystate c_state
2342 #define yy_yyv c_yyv
2344 #define yylloc c_lloc
2345 #define yyreds c_reds
2346 #define yytoks c_toks
2347 #define yylhs c_yylhs
2348 #define yylen c_yylen
2349 #define yydefred c_yydefred
2350 #define yydgoto c_yydgoto
2351 #define yysindex c_yysindex
2352 #define yyrindex c_yyrindex
2353 #define yygindex c_yygindex
2354 #define yytable c_yytable
2355 #define yycheck c_yycheck
2356 #define yyname c_yyname
2357 #define yyrule c_yyrule
2360 For each define, replace the @samp{c_} prefix with whatever you like.
2361 These defines work for @code{bison}, @code{byacc}, and traditional
2362 @code{yacc}s. If you find a parser generator that uses a symbol not
2363 covered here, please report the new name so it can be added to the list.
2366 @node C++ Support, Assembly Support, Yacc and Lex, Programs
2367 @section C++ Support
2370 @cindex Support for C++
2372 Automake includes full support for C++.
2374 Any package including C++ code must define the output variable
2375 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
2376 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
2377 Program Checks, autoconf, The Autoconf Manual}).
2379 A few additional variables are defined when a C++ source file is seen:
2383 The name of the C++ compiler.
2386 Any flags to pass to the C++ compiler.
2389 The maintainer's variant of @code{CXXFLAGS}.
2392 The command used to actually compile a C++ source file. The file name
2393 is appended to form the complete command line.
2396 The command used to actually link a C++ program.
2400 @node Assembly Support, Fortran 77 Support, C++ Support, Programs
2401 @section Assembly Support
2403 Automake includes some support for assembly code.
2405 The variable @code{AS} holds the name of the compiler used to build
2406 assembly code. This compiler must work a bit like a C compiler; in
2407 particular it must accept @samp{-c} and @samp{-o}. The value of
2408 @code{ASFLAGS} is passed to the compilation.
2412 You are required to set @code{AS} and @code{ASFLAGS} via
2413 @file{configure.in}. The autoconf macro @code{AM_PROG_AS} will do this
2414 for you. Unless they are already set, it simply sets @code{AS} to the C
2415 compiler and @code{ASFLAGS} to the C compiler flags.
2417 Only the suffixes @samp{.s} and @samp{.S} are recognized by
2418 @code{automake} as being files containing assembly code.
2421 @node Fortran 77 Support, Java Support, Assembly Support, Programs
2422 @comment node-name, next, previous, up
2423 @section Fortran 77 Support
2425 @cindex Fortran 77 support
2426 @cindex Support for Fortran 77
2428 Automake includes full support for Fortran 77.
2430 Any package including Fortran 77 code must define the output variable
2431 @samp{F77} in @file{configure.in}; the simplest way to do this is to use
2432 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
2433 Program Checks, autoconf, The Autoconf Manual}). @xref{Fortran 77 and
2436 A few additional variables are defined when a Fortran 77 source file is
2442 The name of the Fortran 77 compiler.
2445 Any flags to pass to the Fortran 77 compiler.
2448 The maintainer's variant of @code{FFLAGS}.
2451 Any flags to pass to the Ratfor compiler.
2454 The maintainer's variant of @code{RFLAGS}.
2457 The command used to actually compile a Fortran 77 source file. The file
2458 name is appended to form the complete command line.
2461 The command used to actually link a pure Fortran 77 program or shared
2466 Automake can handle preprocessing Fortran 77 and Ratfor source files in
2467 addition to compiling them@footnote{Much, if not most, of the
2468 information in the following sections pertaining to preprocessing
2469 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
2470 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
2471 also contains some support for creating programs and shared libraries
2472 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
2473 Fortran 77 With C and C++}).
2475 These issues are covered in the following sections.
2478 * Preprocessing Fortran 77::
2479 * Compiling Fortran 77 Files::
2480 * Mixing Fortran 77 With C and C++::
2481 * Fortran 77 and Autoconf::
2485 @node Preprocessing Fortran 77, Compiling Fortran 77 Files, Fortran 77 Support, Fortran 77 Support
2486 @comment node-name, next, previous, up
2487 @subsection Preprocessing Fortran 77
2489 @cindex Preprocessing Fortran 77
2490 @cindex Fortran 77, Preprocessing
2491 @cindex Ratfor programs
2493 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
2494 rule runs just the preprocessor to convert a preprocessable Fortran 77
2495 or Ratfor source file into a strict Fortran 77 source file. The precise
2496 command used is as follows:
2501 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2504 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2509 @node Compiling Fortran 77 Files, Mixing Fortran 77 With C and C++, Preprocessing Fortran 77, Fortran 77 Support
2510 @comment node-name, next, previous, up
2511 @subsection Compiling Fortran 77 Files
2513 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
2514 @file{N.r} by running the Fortran 77 compiler. The precise command used
2520 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
2523 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2526 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2531 @node Mixing Fortran 77 With C and C++, Fortran 77 and Autoconf, Compiling Fortran 77 Files, Fortran 77 Support
2532 @comment node-name, next, previous, up
2533 @subsection Mixing Fortran 77 With C and C++
2535 @cindex Fortran 77, mixing with C and C++
2536 @cindex Mixing Fortran 77 with C and C++
2537 @cindex Linking Fortran 77 with C and C++
2539 @cindex Mixing Fortran 77 with C and/or C++
2541 Automake currently provides @emph{limited} support for creating programs
2542 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
2543 However, there are many other issues related to mixing Fortran 77 with
2544 other languages that are @emph{not} (currently) handled by Automake, but
2545 that are handled by other packages@footnote{For example,
2546 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
2547 addresses all of these inter-language issues, and runs under nearly all
2548 Fortran 77, C and C++ compilers on nearly all platforms. However,
2549 @code{cfortran} is not yet Free Software, but it will be in the next
2553 Automake can help in two ways:
2557 Automatic selection of the linker depending on which combinations of
2561 Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
2562 @samp{-l}) to pass to the automatically selected linker in order to link
2563 in the appropriate Fortran 77 intrinsic and run-time libraries.
2565 @cindex FLIBS, defined
2566 These extra Fortran 77 linker flags are supplied in the output variable
2567 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
2568 supplied with newer versions of Autoconf (Autoconf version 2.13 and
2569 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
2573 If Automake detects that a program or shared library (as mentioned in
2574 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
2575 code that is a mixture of Fortran 77 and C and/or C++, then it requires
2576 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
2577 @file{configure.in}, and that either @code{$(FLIBS)} or @code{@@FLIBS@@}
2578 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
2579 (for shared libraries) variables. It is the responsibility of the
2580 person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
2581 or @code{@@FLIBS@@} appears in the appropriate @code{_LDADD} or
2582 @code{_LIBADD} variable.
2584 @cindex Mixed language example
2585 @cindex Example, mixed language
2587 For example, consider the following @file{Makefile.am}:
2591 foo_SOURCES = main.cc foo.f
2592 foo_LDADD = libfoo.la @@FLIBS@@
2594 pkglib_LTLIBRARIES = libfoo.la
2595 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
2596 libfoo_la_LIBADD = $(FLIBS)
2599 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
2600 is mentioned in @file{configure.in}. Also, if @code{@@FLIBS@@} hadn't
2601 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
2602 Automake would have issued a warning.
2607 * How the Linker is Chosen::
2610 @node How the Linker is Chosen, , Mixing Fortran 77 With C and C++, Mixing Fortran 77 With C and C++
2611 @comment node-name, next, previous, up
2612 @subsubsection How the Linker is Chosen
2614 @cindex Automatic linker selection
2615 @cindex Selecting the linker automatically
2617 The following diagram demonstrates under what conditions a particular
2618 linker is chosen by Automake.
2620 For example, if Fortran 77, C and C++ source code were to be compiled
2621 into a program, then the C++ linker will be used. In this case, if the
2622 C or Fortran 77 linkers required any special libraries that weren't
2623 included by the C++ linker, then they must be manually added to an
2624 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
2630 code \ C C++ Fortran
2631 ----------------- +---------+---------+---------+
2635 +---------+---------+---------+
2639 +---------+---------+---------+
2643 +---------+---------+---------+
2647 +---------+---------+---------+
2649 C + Fortran | | | x |
2651 +---------+---------+---------+
2653 C++ + Fortran | | x | |
2655 +---------+---------+---------+
2657 C + C++ + Fortran | | x | |
2659 +---------+---------+---------+
2663 @node Fortran 77 and Autoconf, , Mixing Fortran 77 With C and C++, Fortran 77 Support
2664 @comment node-name, next, previous, up
2665 @subsection Fortran 77 and Autoconf
2667 The current Automake support for Fortran 77 requires a recent enough
2668 version of Autoconf that also includes support for Fortran 77. Full
2669 Fortran 77 support was added to Autoconf 2.13, so you will want to use
2670 that version of Autoconf or later.
2673 @node Java Support, Support for Other Languages, Fortran 77 Support, Programs
2674 @comment node-name, next, previous, up
2675 @section Java Support
2677 @cindex Java support
2678 @cindex Support for Java
2680 Automake includes support for compiled Java, using @code{gcj}, the Java
2681 front end to the GNU Compiler Collection.
2683 Any package including Java code to be compiled must define the output
2684 variable @samp{GCJ} in @file{configure.in}; the variable @samp{GCJFLAGS}
2685 must also be defined somehow (either in @file{configure.in} or
2686 @file{Makefile.am}). The simplest way to do this is to use the
2687 @code{AM_PROG_GCJ} macro.
2691 By default, programs including Java source files are linked with
2694 As always, the contents of @samp{AM_GCJFLAGS} are passed to every
2695 compilation invoking @code{gcj} (in its role as an ahead-of-time
2696 compiler -- when invoking it to create @file{.class} files,
2697 @samp{AM_JAVACFLAGS} is used instead). If it is necessary to pass
2698 options to @code{gcj} from @file{Makefile.am}, this macro, and not the
2699 user macro @samp{GCJFLAGS}, should be used.
2703 @code{gcj} can be used to compile @file{.java}, @file{.class},
2704 @file{.zip}, or @file{.jar} files.
2707 @node Support for Other Languages, ANSI, Java Support, Programs
2708 @comment node-name, next, previous, up
2709 @section Support for Other Languages
2711 Automake currently only includes full support for C, C++ (@pxref{C++
2712 Support}), Fortran 77 (@pxref{Fortran 77 Support}), and Java
2713 (@pxref{Java Support}). There is only rudimentary support for other
2714 languages, support for which will be improved based on user demand.
2716 Some limited support for adding your own languages is available via the
2717 suffix rule handling; see @ref{Suffixes}.
2720 @node ANSI, Dependencies, Support for Other Languages, Programs
2721 @section Automatic de-ANSI-fication
2723 @cindex de-ANSI-fication, defined
2725 Although the GNU standards allow the use of ANSI C, this can have the
2726 effect of limiting portability of a package to some older compilers
2727 (notably the SunOS C compiler).
2729 Automake allows you to work around this problem on such machines by
2730 @dfn{de-ANSI-fying} each source file before the actual compilation takes
2733 @vindex AUTOMAKE_OPTIONS
2736 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
2737 (@pxref{Options}) contains the option @code{ansi2knr} then code to
2738 handle de-ANSI-fication is inserted into the generated
2741 This causes each C source file in the directory to be treated as ANSI C.
2742 If an ANSI C compiler is available, it is used. If no ANSI C compiler
2743 is available, the @code{ansi2knr} program is used to convert the source
2744 files into K&R C, which is then compiled.
2746 The @code{ansi2knr} program is simple-minded. It assumes the source
2747 code will be formatted in a particular way; see the @code{ansi2knr} man
2750 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
2751 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
2752 these files are distributed with Automake. Also, the package
2753 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}
2755 @cvindex AM_C_PROTOTYPES
2757 Automake also handles finding the @code{ansi2knr} support files in some
2758 other directory in the current package. This is done by prepending the
2759 relative path to the appropriate directory to the @code{ansi2knr}
2760 option. For instance, suppose the package has ANSI C code in the
2761 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
2762 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
2763 @file{src/Makefile.am}:
2766 AUTOMAKE_OPTIONS = ../lib/ansi2knr
2769 If no directory prefix is given, the files are assumed to be in the
2772 Files mentioned in @code{LIBOBJS} which need de-ANSI-fication will not
2773 be automatically handled. That's because @code{configure} will generate
2774 an object name like @file{regex.o}, while @code{make} will be looking
2775 for @file{regex_.o} (when de-ANSI-fying). Eventually this problem will
2776 be fixed via @code{autoconf} magic, but for now you must put this code
2777 into your @file{configure.in}, just before the @code{AC_OUTPUT} call:
2780 # This is necessary so that .o files in LIBOBJS are also built via
2781 # the ANSI2KNR-filtering rules.
2782 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
2785 Note that automatic de-ANSI-fication will not work when the package is
2786 being built for a different host architecture. That is because automake
2787 currently has no way to build @code{ansi2knr} for the build machine.
2790 @node Dependencies, EXEEXT, ANSI, Programs
2791 @section Automatic dependency tracking
2793 As a developer it is often painful to continually update the
2794 @file{Makefile.in} whenever the include-file dependencies change in a
2795 project. Automake supplies a way to automatically track dependency
2798 @cindex Dependency tracking
2799 @cindex Automatic dependency tracking
2801 Automake always uses complete dependencies for a compilation, including
2802 system headers. Automake's model is that dependency computation should
2803 be a side effect of the build. To this end, dependencies are computed
2804 by running all compilations through a special wrapper program called
2805 @code{depcomp}. @code{depcomp} understands how to coax many different C
2806 and C++ compilers into generating dependency information in the format
2807 it requires. @code{automake -a} will install @code{depcomp} into your
2808 source tree for you. If @code{depcomp} can't figure out how to properly
2809 invoke your compiler, dependency tracking will simply be disabled for
2814 Experience with earlier versions of Automake @footnote{See
2815 @uref{http://sources.redhat.com/automake/dependencies.html} for more
2816 information on the history and experiences with automatic dependency
2817 tracking in Automake} taught us that it is not reliable to generate
2818 dependencies only on the maintainer's system, as configurations vary too
2819 much. So instead Automake implements dependency tracking at build time.
2821 Automatic dependency tracking can be suppressed by putting
2822 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}. Or, you
2823 can invoke @code{automake} with the @code{-i} option. Dependency
2824 tracking is enabled by default.
2826 @vindex AUTOMAKE_OPTIONS
2827 @opindex no-dependencies
2829 The person building your package also can choose to disable dependency
2830 tracking by configuring with @code{--disable-dependency-tracking}.
2832 @cindex Disabling dependency tracking
2833 @cindex Dependency tracking, disabling
2836 @node EXEEXT, , Dependencies, Programs
2837 @section Support for executable extensions
2839 @cindex Executable extension
2840 @cindex Extension, executable
2843 On some platforms, such as Windows, executables are expected to have an
2844 extension such as @samp{.exe}. On these platforms, some compilers (GCC
2845 among them) will automatically generate @file{foo.exe} when asked to
2846 generate @file{foo}.
2848 Automake provides mostly-transparent support for this. Unfortunately
2849 the support isn't completely transparent; if you want your package to
2850 support these platforms then you must assist.
2852 One thing you must be aware of is that, internally, Automake rewrites
2853 something like this:
2856 bin_PROGRAMS = liver
2862 bin_PROGRAMS = liver$(EXEEXT)
2865 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
2866 extension. @code{EXEEXT}
2868 However, Automake cannot apply this rewriting to @code{configure}
2869 substitutions. This means that if you are conditionally building a
2870 program using such a substitution, then your @file{configure.in} must
2871 take care to add @samp{$(EXEEXT)} when constructing the output variable.
2873 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
2874 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
2875 automatically if you configure a compiler (say, through
2878 Sometimes maintainers like to write an explicit link rule for their
2879 program. Without executable extension support, this is easy---you
2880 simply write a target with the same name as the program. However, when
2881 executable extension support is enabled, you must instead add the
2882 @samp{$(EXEEXT)} suffix.
2884 Unfortunately, due to the change in Autoconf 2.50, this means you must
2885 always add this extension. However, this is a problem for maintainers
2886 who know their package will never run on a platform that has executable
2887 extensions. For those maintainers, the @code{no-exeext} option
2888 (@pxref{Options}) will disable this feature. This works in a fairly
2889 ugly way; if @code{no-exeext} is seen, then the presence of a target
2890 named @code{foo} in @file{Makefile.am} will override an
2891 automake-generated target of the form @code{foo$(EXEEXT)}. Without the
2892 @code{no-exeext} option, this use will give an error.
2895 @node Other objects, Other GNU Tools, Programs, Top
2896 @chapter Other Derived Objects
2898 Automake can handle derived objects which are not C programs. Sometimes
2899 the support for actually building such objects must be explicitly
2900 supplied, but Automake will still automatically handle installation and
2904 * Scripts:: Executable scripts
2905 * Headers:: Header files
2906 * Data:: Architecture-independent data files
2907 * Sources:: Derived sources
2911 @node Scripts, Headers, Other objects, Other objects
2912 @section Executable Scripts
2914 @cindex _SCRIPTS primary, defined
2915 @cindex SCRIPTS primary, defined
2916 @cindex Primary variable, SCRIPTS
2918 It is possible to define and install programs which are scripts. Such
2919 programs are listed using the @samp{SCRIPTS} primary name. Automake
2920 doesn't define any dependencies for scripts; the @file{Makefile.am}
2921 should include the appropriate rules.
2924 Automake does not assume that scripts are derived objects; such objects
2925 must be deleted by hand (@pxref{Clean}).
2927 The @code{automake} program itself is a Perl script that is generated at
2928 configure time from @file{automake.in}. Here is how this is handled:
2931 bin_SCRIPTS = automake
2934 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
2935 for it is automatically generated.
2937 @cindex SCRIPTS, installation directories
2938 @cindex Installing scripts
2941 @vindex sbin_SCRIPTS
2942 @vindex libexec_SCRIPTS
2943 @vindex pkgdata_SCRIPTS
2944 @vindex noinst_SCRIPTS
2946 Script objects can be installed in @code{bindir}, @code{sbindir},
2947 @code{libexecdir}, or @code{pkgdatadir}.
2950 @node Headers, Data, Scripts, Other objects
2951 @section Header files
2953 @cindex _HEADERS primary, defined
2954 @cindex HEADERS primary, defined
2955 @cindex Primary variable, HEADERS
2957 @vindex noinst_HEADERS
2959 Header files are specified by the @samp{HEADERS} family of variables.
2960 Generally header files are not installed, so the @code{noinst_HEADERS}
2961 variable will be the most used. @footnote{However, for the case of a
2962 non-installed header file that is actually used by a particular program,
2963 we recommend listing it in the program's @samp{_SOURCES} variable
2964 instead of in @code{noinst_HEADERS}. We believe this is more clear.}
2967 All header files must be listed somewhere; missing ones will not appear
2968 in the distribution. Often it is clearest to list uninstalled headers
2969 with the rest of the sources for a program. @xref{A Program}. Headers
2970 listed in a @samp{_SOURCES} variable need not be listed in any
2971 @samp{_HEADERS} variable.
2973 @cindex HEADERS, installation directories
2974 @cindex Installing headers
2976 @vindex include_HEADERS
2977 @vindex oldinclude_HEADERS
2978 @vindex pkginclude_HEADERS
2980 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
2981 @code{pkgincludedir}.
2984 @node Data, Sources, Headers, Other objects
2985 @section Architecture-independent data files
2987 @cindex _DATA primary, defined
2988 @cindex DATA primary, defined
2989 @cindex Primary variable, DATA
2991 Automake supports the installation of miscellaneous data files using the
2992 @samp{DATA} family of variables.
2996 @vindex sysconf_DATA
2997 @vindex sharedstate_DATA
2998 @vindex localstate_DATA
2999 @vindex pkgdata_DATA
3001 Such data can be installed in the directories @code{datadir},
3002 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
3005 By default, data files are @emph{not} included in a distribution. Of
3006 course, you can use the @samp{dist_} prefix to change this on a
3009 Here is how Automake installs its auxiliary data files:
3012 pkgdata_DATA = clean-kr.am clean.am @dots{}
3016 @node Sources, , Data, Other objects
3017 @section Built sources
3019 @cindex BUILT_SOURCES, defined
3021 Occasionally a file which would otherwise be called @samp{source}
3022 (e.g. a C @samp{.h} file) is actually derived from some other file.
3023 Such files should be listed in the @code{BUILT_SOURCES} variable.
3024 @vindex BUILT_SOURCES
3026 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
3027 must be created early in the build process can be listed in this
3030 A source file listed in @code{BUILT_SOURCES} is created before the other
3031 @code{all} targets are made. However, such a source file is not
3032 compiled unless explicitly requested by mentioning it in some other
3033 @samp{_SOURCES} variable.
3035 So, for instance, if you had header files which were created by a script
3036 run at build time, then you would list these headers in
3037 @code{BUILT_SOURCES}, to ensure that they would be built before any
3038 other compilations (perhaps ones using these headers) were started.
3041 @node Other GNU Tools, Documentation, Other objects, Top
3042 @chapter Other GNU Tools
3044 Since Automake is primarily intended to generate @file{Makefile.in}s for
3045 use in GNU programs, it tries hard to interoperate with other GNU tools.
3048 * Emacs Lisp:: Emacs Lisp
3056 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
3059 @cindex _LISP primary, defined
3060 @cindex LISP primary, defined
3061 @cindex Primary variable, LISP
3067 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
3068 is used to hold a list of @file{.el} files. Possible prefixes for this
3069 primary are @samp{lisp_} and @samp{noinst_}. Note that if
3070 @code{lisp_LISP} is defined, then @file{configure.in} must run
3071 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
3075 By default Automake will byte-compile all Emacs Lisp source files using
3076 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
3077 byte-compiling, simply define the variable @code{ELCFILES} to be empty.
3078 Byte-compiled Emacs Lisp files are not portable among all versions of
3079 Emacs, so it makes sense to turn this off if you expect sites to have
3080 more than one version of Emacs installed. Furthermore, many packages
3081 don't actually benefit from byte-compilation. Still, we recommend that
3082 you leave it enabled by default. It is probably better for sites with
3083 strange setups to cope for themselves than to make the installation less
3084 nice for everybody else.
3087 @node gettext, Libtool, Emacs Lisp, Other GNU Tools
3090 @cindex GNU Gettext support
3091 @cindex Gettext support
3092 @cindex Support for GNU Gettext
3094 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
3095 turns on support for GNU gettext, a message catalog system for
3096 internationalization
3097 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
3099 The @code{gettext} support in Automake requires the addition of two
3100 subdirectories to the package, @file{intl} and @file{po}. Automake
3101 insures that these directories exist and are mentioned in
3105 @node Libtool, Java, gettext, Other GNU Tools
3108 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
3109 libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
3110 @xref{A Shared Library}.
3113 @node Java, Python, Libtool, Other GNU Tools
3116 @cindex _JAVA primary, defined
3117 @cindex JAVA primary, defined
3118 @cindex Primary variable, JAVA
3120 Automake provides some minimal support for Java compilation with the
3121 @samp{JAVA} primary.
3123 Any @file{.java} files listed in a @samp{_JAVA} variable will be
3124 compiled with @code{JAVAC} at build time. By default, @file{.class}
3125 files are not included in the distribution.
3127 @cindex JAVA restrictions
3128 @cindex Restrictions for JAVA
3130 Currently Automake enforces the restriction that only one @samp{_JAVA}
3131 primary can be used in a given @file{Makefile.am}. The reason for this
3132 restriction is that, in general, it isn't possible to know which
3133 @file{.class} files were generated from which @file{.java} files -- so
3134 it would be impossible to know which files to install where. For
3135 instance, a @file{.java} file can define multiple classes; the resulting
3136 @file{.class} file names cannot be predicted without parsing the
3139 There are a few variables which are used when compiling Java sources:
3143 The name of the Java compiler. This defaults to @samp{javac}.
3146 The flags to pass to the compiler. This is considered to be a user
3147 variable (@pxref{User Variables}).
3150 More flags to pass to the Java compiler. This, and not
3151 @code{JAVACFLAGS}, should be used when it is necessary to put Java
3152 compiler flags into @file{Makefile.am}.
3155 The value of this variable is passed to the @samp{-d} option to
3156 @code{javac}. It defaults to @samp{$(top_builddir)}.
3159 This variable is an @code{sh} expression which is used to set the
3160 @code{CLASSPATH} environment variable on the @code{javac} command line.
3161 (In the future we will probably handle class path setting differently.)
3165 @node Python, , Java, Other GNU Tools
3168 @cindex _PYTHON primary, defined
3169 @cindex PYTHON primary, defined
3170 @cindex Primary variable, PYTHON
3173 Automake provides support for Python compilation with the @samp{PYTHON}
3176 Any files listed in a @samp{_PYTHON} variable will be byte-compiled with
3177 @code{py-compile} at install time. @code{py-compile} actually creates
3178 both standard (@file{.pyc}) and byte-compiled (@file{.pyo}) versions of
3179 the source files. Note that because byte-compilation occurs at install
3180 time, any files listed in @samp{noinst_PYTHON} will not be compiled.
3181 Python source files are included in the distribution by default.
3183 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} which
3184 will determine some Python-related directory variables (see below). If
3185 have called @code{AM_PATH_PYTHON} from you @file{configure.in}, then you
3186 may use the following variables to list you Python source files in your
3187 variables: @samp{python_PYTHON}, @samp{pkgpython_PYTHON},
3188 @samp{pkgpython_PYTHON}, @samp{pyexecdir_PYTHON},
3189 @samp{pkgpyexecdir_PYTHON}, depending where you want your files
3192 @code{AM_PATH_PYTHON} takes a single optional argument. This argument,
3193 if present, is the minimum version of Python which can be used for this
3194 package. If the version of Python found on the system is older than the
3195 required version, then @code{AM_PATH_PYTHON} will cause an error.
3197 @code{AM_PATH_PYTHON} creates several output variables based on the
3198 Python installation found during configuration.
3202 The name of the Python executable.
3204 @item PYTHON_VERSION
3205 The Python version number, in the form @var{major}.@var{minor}
3206 (e.g. @samp{1.5}). This is currently the value of
3207 @code{sys.version[:3]}.
3210 The string @code{$prefix}. This term may be used in future work
3211 which needs the contents of Python's @code{sys.prefix}, but general
3212 consensus is to always use the value from configure.
3214 @item PYTHON_EXEC_PREFIX
3215 The string @code{$exec_prefix}. This term may be used in future work
3216 which needs the contents of Python's @code{sys.exec_prefix}, but general
3217 consensus is to always use the value from configure.
3219 @item PYTHON_PLATFORM
3220 The canonical name used by Python to describe the operating system, as
3221 given by @code{sys.platform}. This value is sometimes needed when
3222 building Python extensions.
3225 The directory name for the @file{site-packages} subdirectory of the
3226 standard Python install tree.
3229 This is is the directory under @code{pythondir} which is named after the
3230 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
3234 This is the directory where Python extension modules (shared libraries)
3235 should be installed.
3238 This is a convenience variable which is defined as
3239 @samp{$(pyexecdir)/$(PACKAGE)}.
3243 @node Documentation, Install, Other GNU Tools, Top
3244 @chapter Building documentation
3246 Currently Automake provides support for Texinfo and man pages.
3250 * Man pages:: Man pages
3254 @node Texinfo, Man pages, Documentation, Documentation
3257 @cindex _TEXINFOS primary, defined
3258 @cindex TEXINFOS primary, defined
3259 @cindex Primary variable, TEXINFOS
3261 If the current directory contains Texinfo source, you must declare it
3262 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
3263 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
3264 here. Any Texinfo source file must end in the @file{.texi},
3265 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
3268 @vindex info_TEXINFOS
3270 @cindex Texinfo macro, VERSION
3271 @cindex Texinfo macro, UPDATED
3272 @cindex Texinfo macro, EDITION
3273 @cindex Texinfo macro, UPDATED-MONTH
3275 @cindex VERSION Texinfo macro
3276 @cindex UPDATED Texinfo macro
3277 @cindex EDITION Texinfo macro
3278 @cindex UPDATED-MONTH Texinfo macro
3282 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
3283 that file will be automatically generated. The file @file{version.texi}
3284 defines four Texinfo macros you can reference:
3289 Both of these macros hold the version number of your program. They are
3290 kept separate for clarity.
3293 This holds the date the primary @file{.texi} file was last modified.
3296 This holds the name of the month in which the primary @file{.texi} file
3300 The @file{version.texi} support requires the @code{mdate-sh} program;
3301 this program is supplied with Automake and automatically included when
3302 @code{automake} is invoked with the @code{--add-missing} option.
3304 If you have multiple Texinfo files, and you want to use the
3305 @file{version.texi} feature, then you have to have a separate version
3306 file for each Texinfo file. Automake will treat any include in a
3307 Texinfo file that matches @samp{vers*.texi} just as an automatically
3308 generated version file.
3310 When an info file is rebuilt, the program named by the @code{MAKEINFO}
3311 variable is used to invoke it. If the @code{makeinfo} program is found
3312 on the system then it will be used by default; otherwise @code{missing}
3313 will be used instead. The flags in the variables @code{MAKEINFOFLAGS}
3314 and @code{AM_MAKEINFOFLAGS} will be passed to the @code{makeinfo}
3315 invocation; the first of these is intended for use by the user
3316 (@pxref{User Variables}) and the second by the @file{Makefile.am}
3319 @vindex MAKEINFOFLAGS
3320 @vindex AM_MAKEINFOFLAGS
3322 Sometimes an info file actually depends on more than one @file{.texi}
3323 file. For instance, in GNU Hello, @file{hello.texi} includes the file
3324 @file{gpl.texi}. You can tell Automake about these dependencies using
3325 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
3330 info_TEXINFOS = hello.texi
3331 hello_TEXINFOS = gpl.texi
3336 By default, Automake requires the file @file{texinfo.tex} to appear in
3337 the same directory as the Texinfo source. However, if you used
3338 @code{AC_CONFIG_AUX_DIR} in @file{configure.in} (@pxref{Input, , Finding
3339 `configure' Input, autoconf, The Autoconf Manual}), then
3340 @file{texinfo.tex} is looked for there. Automake supplies
3341 @file{texinfo.tex} if @samp{--add-missing} is given.
3345 If your package has Texinfo files in many directories, you can use the
3346 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
3347 @file{texinfo.tex} for your package. The value of this variable should
3348 be the relative path from the current @file{Makefile.am} to
3352 TEXINFO_TEX = ../doc/texinfo.tex
3355 @opindex no-texinfo.tex
3357 The option @samp{no-texinfo.tex} can be used to eliminate the
3358 requirement for @file{texinfo.tex}. Use of the variable
3359 @code{TEXINFO_TEX} is preferable, however, because that allows the
3360 @code{dvi} target to still work.
3362 @cindex Target, install-info
3363 @cindex Target, noinstall-info
3364 @cindex install-info target
3365 @cindex noinstall-info target
3367 @opindex no-installinfo
3368 @trindex install-info
3370 Automake generates an @code{install-info} target; some people apparently
3371 use this. By default, info pages are installed by @samp{make install}.
3372 This can be prevented via the @code{no-installinfo} option.
3375 @node Man pages, , Texinfo, Documentation
3378 @cindex _MANS primary, defined
3379 @cindex MANS primary, defined
3380 @cindex Primary variable, MANS
3382 A package can also include man pages (but see the GNU standards on this
3383 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
3384 pages are declared using the @samp{MANS} primary. Generally the
3385 @code{man_MANS} macro is used. Man pages are automatically installed in
3386 the correct subdirectory of @code{mandir}, based on the file extension.
3390 File extensions such as @samp{.1c} are handled by looking for the valid
3391 part of the extension and using that to determine the correct
3392 subdirectory of @code{mandir}. Valid section names are the digits
3393 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
3395 Sometimes developers prefer to name a man page something like
3396 @file{foo.man} in the source, and then rename it to have the correct
3397 suffix, e.g. @file{foo.1}, when installing the file. Automake also
3398 supports this mode. For a valid section named @var{SECTION}, there is a
3399 corresponding directory named @samp{man@var{SECTION}dir}, and a
3400 corresponding @samp{_MANS} variable. Files listed in such a variable
3401 are installed in the indicated section. If the file already has a
3402 valid suffix, then it is installed as-is; otherwise the file suffix is
3403 changed to match the section.
3405 For instance, consider this example:
3407 man1_MANS = rename.man thesame.1 alsothesame.1c
3410 In this case, @file{rename.man} will be renamed to @file{rename.1} when
3411 installed, but the other files will keep their names.
3413 @cindex Target, install-man
3414 @cindex Target, noinstall-man
3415 @cindex install-man target
3416 @cindex noinstall-man target
3418 @c Use @samp{make install} per documentation: (texi)code.
3419 By default, man pages are installed by @samp{make install}. However,
3420 since the GNU project does not require man pages, many maintainers do
3421 not expend effort to keep the man pages up to date. In these cases, the
3422 @code{no-installman} option will prevent the man pages from being
3423 installed by default. The user can still explicitly install them via
3424 @samp{make install-man}.
3425 @opindex no-installman
3426 @trindex install-man
3428 Here is how the man pages are handled in GNU @code{cpio} (which includes
3429 both Texinfo documentation and man pages):
3432 man_MANS = cpio.1 mt.1
3433 EXTRA_DIST = $(man_MANS)
3436 Man pages are not currently considered to be source, because it is not
3437 uncommon for man pages to be automatically generated. Therefore they
3438 are not automatically included in the distribution. However, this can
3439 be changed by use of the @samp{dist_} prefix.
3441 The @samp{nobase_} prefix is meaningless for man pages and is
3445 @node Install, Clean, Documentation, Top
3446 @chapter What Gets Installed
3448 @cindex Installation support
3449 @cindex make install support
3451 @section Basics of installation
3453 Naturally, Automake handles the details of actually installing your
3454 program once it has been built. All files named by the various
3455 primaries are automatically installed in the appropriate places when the
3456 user runs @code{make install}.
3458 A file named in a primary is installed by copying the built file into
3459 the appropriate directory. The base name of the file is used when
3463 bin_PROGRAMS = hello subdir/goodbye
3466 In this example, both @samp{hello} and @samp{goodbye} will be installed
3467 in @code{$(bindir)}.
3469 Sometimes it is useful to avoid the basename step at install time. For
3470 instance, you might have a number of header files in subdirectories of
3471 the source tree which are laid out precisely how you want to install
3472 them. In this situation you can use the @samp{nobase_} prefix to
3473 suppress the base name step. For example:
3476 nobase_include_HEADERS = stdio.h sys/types.h
3479 Will install @file{stdio.h} in @code{$(includedir)} and @file{types.h}
3480 in @code{$(includedir)/sys}.
3482 @section The two parts of install
3484 Automake generates separate @code{install-data} and @code{install-exec}
3485 targets, in case the installer is installing on multiple machines which
3486 share directory structure---these targets allow the machine-independent
3487 parts to be installed only once. @code{install-exec} installs
3488 platform-dependent files, and @code{install-data} installs
3489 platform-independent files. The @code{install} target depends on both
3490 of these targets. While Automake tries to automatically segregate
3491 objects into the correct category, the @file{Makefile.am} author is, in
3492 the end, responsible for making sure this is done correctly.
3493 @trindex install-data
3494 @trindex install-exec
3496 @cindex Install, two parts of
3498 Variables using the standard directory prefixes @samp{data},
3499 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
3500 @samp{pkgdata}, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
3501 installed by @samp{install-data}.
3503 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
3504 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
3505 @samp{pkglib} (e.g. @samp{bin_PROGRAMS}) are installed by
3506 @samp{install-exec}.
3508 Any variable using a user-defined directory prefix with @samp{exec} in
3509 the name (e.g. @samp{myexecbin_PROGRAMS} is installed by
3510 @samp{install-exec}. All other user-defined prefixes are installed by
3511 @samp{install-data}.
3513 @section Extending installation
3515 It is possible to extend this mechanism by defining an
3516 @code{install-exec-local} or @code{install-data-local} target. If these
3517 targets exist, they will be run at @samp{make install} time. These
3518 rules can do almost anything; care is required.
3519 @trindex install-exec-local
3520 @trindex install-data-local
3522 Automake also supports two install hooks, @code{install-exec-hook} and
3523 @code{install-data-hook}. These hooks are run after all other install
3524 rules of the appropriate type, exec or data, have completed. So, for
3525 instance, it is possible to perform post-installation modifications
3526 using an install hook.
3527 @cindex Install hook
3529 @section Staged installs
3532 Automake generates support for the @samp{DESTDIR} variable in all
3533 install rules. @samp{DESTDIR} is used during the @samp{make install}
3534 step to relocate install objects into a staging area. Each object and
3535 path is prefixed with the value of @samp{DESTDIR} before being copied
3536 into the install area. Here is an example of typical DESTDIR usage:
3539 make DESTDIR=/tmp/staging install
3542 This places install objects in a directory tree built under
3543 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
3544 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
3545 would install @file{/tmp/staging/gnu/bin/foo} and
3546 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
3548 This feature is commonly used to build install images and packages. For
3549 more information, see @ref{Makefile Conventions, , , standards, The GNU
3552 Support for @samp{DESTDIR} is implemented by coding it directly into the
3553 install rules. If your @file{Makefile.am} uses a local install rule
3554 (e.g., @code{install-exec-local}) or an install hook, then you must
3555 write that code to respect @samp{DESTDIR}.
3557 @section Rules for the user
3559 Automake also generates an @code{uninstall} target, an
3560 @code{installdirs} target, and an @code{install-strip} target.
3562 @trindex installdirs
3563 @trindex install-strip
3565 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
3566 There is no notion of separate uninstalls for ``exec'' and ``data'', as
3567 these features would not provide additional functionality.
3569 Note that @code{uninstall} is not meant as a replacement for a real
3573 @node Clean, Dist, Install, Top
3574 @chapter What Gets Cleaned
3576 @cindex make clean support
3578 The GNU Makefile Standards specify a number of different clean rules.
3580 Generally the files that can be cleaned are determined automatically by
3581 Automake. Of course, Automake also recognizes some variables that can
3582 be defined to specify additional files to clean. These variables are
3583 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
3584 @code{MAINTAINERCLEANFILES}.
3585 @vindex MOSTLYCLEANFILES
3587 @vindex DISTCLEANFILES
3588 @vindex MAINTAINERCLEANFILES
3590 As the GNU Standards aren't always explicit as to which files should be
3591 removed by which target, we've adopted a heuristic which we believe was
3592 first formulated by Fran@,{c}ois Pinard:
3596 If @code{make} built it, and it is commonly something that one would
3597 want to rebuild (for instance, a @file{.o} file), then
3598 @code{mostlyclean} should delete it.
3601 Otherwise, if @code{make} built it, then @code{clean} should delete it.
3604 If @code{configure} built it, then @code{distclean} should delete it
3607 If the maintainer built it, then @code{maintainer-clean} should
3611 We recommend that you follow this same set of heuristics in your
3615 @node Dist, Tests, Clean, Top
3616 @chapter What Goes in a Distribution
3618 @section Basics of distribution
3622 The @code{dist} target in the generated @file{Makefile.in} can be used
3623 to generate a gzip'd @code{tar} file and other flavors of archive for
3624 distribution. The files is named based on the @samp{PACKAGE} and
3625 @samp{VERSION} variables; more precisely the gzip'd @code{tar} file is
3626 named @samp{@var{package}-@var{version}.tar.gz}.
3630 You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
3631 is run. The default setting is @samp{--best}.
3633 For the most part, the files to distribute are automatically found by
3634 Automake: all source files are automatically included in a distribution,
3635 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
3636 has a built-in list of commonly used files which are automatically
3637 included if they are found in the current directory (either physically,
3638 or as the target of a @file{Makefile.am} rule). This list is printed by
3639 @samp{automake --help}. Also, files which are read by @code{configure}
3640 (i.e. the source files corresponding to the files specified in the
3641 @code{AC_OUTPUT} invocation) are automatically distributed.
3643 Still, sometimes there are files which must be distributed, but which
3644 are not covered in the automatic rules. These files should be listed in
3645 the @code{EXTRA_DIST} variable. You can mention files from
3646 subdirectories in @code{EXTRA_DIST}.
3648 You can also mention a directory in @code{EXTRA_DIST}; in this case the
3649 entire directory will be recursively copied into the distribution.
3650 Please note that this will also copy @emph{everything} in the directory,
3651 including CVS/RCS version control files. We recommend against using
3656 @section Fine-grained distribution control
3658 Sometimes you need tighter control over what does @emph{not} go into the
3659 distribution; for instance you might have source files which are
3660 generated and which you do not want to distribute. In this case
3661 Automake gives fine-grained control using the @samp{dist} and
3662 @samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
3663 prefixed with @samp{dist_} to add the listed files to the distribution.
3664 Similarly, @samp{nodist_} can be used to omit the files from the
3669 As an example, here is how you would cause some data to be distributed
3670 while leaving some source code out of the distribution:
3673 dist_data_DATA = distribute-this
3675 nodist_foo_SOURCES = do-not-distribute.c
3678 @section The dist hook
3680 Another way to to use this is for removing unnecessary files that get
3681 recursively included by specifying a directory in EXTRA_DIST:
3687 rm -rf `find $(distdir)/doc -name CVS`
3690 If you define @code{SUBDIRS}, Automake will recursively include the
3691 subdirectories in the distribution. If @code{SUBDIRS} is defined
3692 conditionally (@pxref{Conditionals}), Automake will normally include all
3693 directories that could possibly appear in @code{SUBDIRS} in the
3694 distribution. If you need to specify the set of directories
3695 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
3696 list of subdirectories to include in the distribution.
3697 @vindex DIST_SUBDIRS
3701 Occasionally it is useful to be able to change the distribution before
3702 it is packaged up. If the @code{dist-hook} target exists, it is run
3703 after the distribution directory is filled, but before the actual tar
3704 (or shar) file is created. One way to use this is for distributing
3705 files in subdirectories for which a new @file{Makefile.am} is overkill:
3709 mkdir $(distdir)/random
3710 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
3713 @section Checking the distribution
3715 @cindex make distcheck
3716 @cindex make distcleancheck
3717 @vindex distcleancheck_listfiles
3719 Automake also generates a @code{distcheck} target which can be of help
3720 to ensure that a given distribution will actually work.
3721 @code{distcheck} makes a distribution, then tries to do a @code{VPATH}
3722 build, run the testsuite, and finally make another tarfile to ensure the
3723 distribution is self-contained.
3726 Building the package involves running @code{./configure}. If you need
3727 to supply additional flags to @code{configure}, define them in the
3728 @code{DISTCHECK_CONFIGURE_FLAGS} variable, either in your top-level
3729 @file{Makefile.am}, or on the commande line when invoking @code{make}.
3730 @vindex DISTCHECK_CONFIGURE_FLAGS
3732 If the target @code{distcheck-hook} is defined in your
3733 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
3734 the new distribution has been unpacked, but before the unpacked copy is
3735 configured and built. Your @code{distcheck-hook} can do almost
3736 anything, though as always caution is advised. Generally this hook is
3737 used to check for potential distribution errors not caught by the
3740 Speaking about potential distribution errors, @code{distcheck} will also
3741 ensure that the @code{distclean} target actually removes all built
3742 files. This is done by running @code{make distcleancheck} at the end of
3743 the @code{VPATH} build. By default, @code{distcleancheck} will run
3744 @code{distclean} and then make sure the build tree has been emptied by
3745 running @code{$(distcleancheck_listfiles)}. Usually this check will
3746 find generated files that you forgot to add to the @code{DISTCLEANFILES}
3747 variable (@pxref{Clean}).
3748 @trindex distcleancheck
3750 The @code{distcleancheck} behaviour should be ok for most packages,
3751 otherwise you have the possibility to override the definitition of
3752 either the @code{distcleancheck} target, or the
3753 @code{$(distcleancheck_listfiles)} variable. For instance to disable
3754 @code{distcleancheck} completely, add the following rule to your
3755 top-level @file{Makefile.am}:
3756 @vindex distcleancheck_listfiles
3763 If you want @code{distcleancheck} to ignore built files which have not
3764 been cleaned because they are also part of the distribution, add the
3765 following definition instead:
3768 distcleancheck_listfiles = \
3769 find -type f -exec sh -c 'test -f $(scrdir)/@{@} || echo @{@}'
3772 The above definition is not the default because it's usually an error if
3773 your Makefiles cause some distributed files to be rebuilt when the user
3774 build the package. (Think about the user missing the tool required to
3775 build the file; or if the required tool is built by your package,
3776 consider the cross-compilation case where it can't be run.)
3778 @section The types of distributions
3781 Automake generates a @samp{.tar.gz} file when asked to create a
3782 distribution and other archives formats, @ref{Options}. The target
3783 @code{dist-gzip} generates the @samp{.tar.gz} file only.
3786 @node Tests, Options, Dist, Top
3787 @chapter Support for test suites
3792 Automake supports two forms of test suites.
3794 @section Simple Tests
3796 If the variable @code{TESTS} is defined, its value is taken to be a list
3797 of programs to run in order to do the testing. The programs can either
3798 be derived objects or source objects; the generated rule will look both
3799 in @code{srcdir} and @file{.}. Programs needing data files should look
3800 for them in @code{srcdir} (which is both an environment variable and a
3801 make variable) so they work when building in a separate directory
3802 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
3803 Manual}), and in particular for the @code{distcheck} target
3806 @cindex Exit status 77, special interpretation
3808 The number of failures will be printed at the end of the run. If a
3809 given test program exits with a status of 77, then its result is ignored
3810 in the final count. This feature allows non-portable tests to be
3811 ignored in environments where they don't make sense.
3813 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
3814 variables for the test run; the environment variable @code{srcdir} is
3815 set in the rule. If all your test programs are scripts, you can also
3816 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
3817 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
3819 @vindex TESTS_ENVIRONMENT
3821 @cindex Tests, expected failure
3822 @cindex Expected test failure
3824 You may define the variable @code{XFAIL_TESTS} to a list of tests
3825 (usually a subset of @code{TESTS}) that are expected to fail. This will
3826 reverse the result of those tests.
3829 Automake ensures that each program listed in @code{TESTS} is built
3830 before any tests are run; you can list both source and derived programs
3831 in @code{TESTS}. For instance, you might want to run a C program as a
3832 test. To do this you would list its name in @code{TESTS} and also in
3833 @code{check_PROGRAMS}, and then specify it as you would any other
3836 @section DejaGNU Tests
3838 If @uref{ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz,
3839 @samp{dejagnu}} appears in @code{AUTOMAKE_OPTIONS}, then a
3840 @code{dejagnu}-based test suite is assumed. The variable
3841 @code{DEJATOOL} is a list of names which are passed, one at a time, as
3842 the @code{--tool} argument to @code{runtest} invocations; it defaults to
3843 the name of the package.
3845 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
3846 @code{--srcdir} flags that are passed to dejagnu by default; this can be
3847 overridden if necessary.
3848 @vindex RUNTESTDEFAULTFLAGS
3850 The variables @code{EXPECT} and @code{RUNTEST} can
3851 also be overridden to provide project-specific values. For instance,
3852 you will need to do this if you are testing a compiler toolchain,
3853 because the default values do not take into account host and target
3860 The contents of the variable @code{RUNTESTFLAGS} are passed to the
3861 @code{runtest} invocation. This is considered a ``user variable''
3862 (@pxref{User Variables}). If you need to set @code{runtest} flags in
3863 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
3864 @vindex RUNTESTFLAGS
3865 @vindex AM_RUNTESTFLAGS
3866 @c FIXME xref dejagnu
3868 In either case, the testing is done via @samp{make check}.
3870 @section Install Tests
3872 The @code{installcheck} target is available to the user as a way to run
3873 any tests after the package has been installed. You can add tests to
3874 this by writing an @code{installcheck-local} target.
3877 @node Options, Miscellaneous, Tests, Top
3878 @chapter Changing Automake's Behavior
3880 Various features of Automake can be controlled by options in the
3881 @file{Makefile.am}. Such options are applied on a per-@file{Makefile}
3882 basis when listed in a special @file{Makefile} variable named
3883 @code{AUTOMAKE_OPTIONS}. They are applied globally to all processed
3884 @file{Makefiles} when listed in the first argument of
3885 @code{AM_INIT_AUTOMAKE} in @file{configure.in}. Currently understood
3887 @vindex AUTOMAKE_OPTIONS
3892 @itemx @code{foreign}
3893 @itemx @code{cygnus}
3894 @cindex Option, gnits
3896 @cindex Option, foreign
3897 @cindex Option, cygnus
3899 Set the strictness as appropriate. The @code{gnits} option also implies
3900 @code{readme-alpha} and @code{check-news}.
3902 @item @code{ansi2knr}
3903 @itemx @code{@var{path}/ansi2knr}
3904 @cindex Option, ansi2knr
3905 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
3906 path, the generated @file{Makefile.in} will look in the specified
3907 directory to find the @file{ansi2knr} program. The path should be a
3908 relative path to another directory in the same distribution (Automake
3909 currently does not check this).
3911 @item @code{check-news}
3912 @cindex Option, check-news
3913 Cause @code{make dist} to fail unless the current version number appears
3914 in the first few lines of the @file{NEWS} file.
3916 @item @code{dejagnu}
3917 @cindex Option, dejagnu
3918 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
3920 @item @code{dist-bzip2}
3921 @cindex Option, dist-bzip2
3922 Generate a @code{dist-bzip2} target, creating a bzip2 tar archive of the
3923 distribution. @code{dist} will create it in addition to the other
3924 formats. bzip2 archives are frequently smaller than gzipped archives.
3927 @item @code{dist-shar}
3928 @cindex Option, dist-shar
3929 Generate a @code{dist-shar} target, creating a shar archive of the
3930 distribution. @code{dist} will create it in addition to the other
3934 @item @code{dist-zip}
3935 @cindex Option, dist-zip
3936 Generate a @code{dist-zip} target, creating a zip archive of the
3937 distribution. @code{dist} will create it in addition to the other
3941 @item @code{dist-tarZ}
3942 @cindex Option, dist-tarZ
3943 Generate a @code{dist-tarZ} target, creating a compressed tar archive of
3944 the distribution. @code{dist} will create it in addition to the other
3948 @item @code{no-define}
3949 @cindex Option, no-define
3950 This options is meaningful only when passed as an argument to
3951 AM_INIT_AUTOMAKE. It will prevent the @code{PACKAGE} and @code{VERSION}
3952 variable to be @code{AC_DEFINE}d.
3954 @item @code{no-dependencies}
3955 @cindex Option, no-dependencies
3956 This is similar to using @samp{--include-deps} on the command line, but
3957 is useful for those situations where you don't have the necessary bits
3958 to make automatic dependency tracking work @xref{Dependencies}. In this
3959 case the effect is to effectively disable automatic dependency tracking.
3961 @item @code{no-exeext}
3962 @cindex Option, no-exeext
3963 If your @file{Makefile.am} defines a target @samp{foo}, it will override
3964 a target named @samp{foo$(EXEEXT)}. This is necessary when
3965 @code{EXEEXT} is found to be empty. However, by default automake will
3966 generate an error for this use. The @code{no-exeext} option will
3967 disable this error. This is intended for use only where it is known in
3968 advance that the package will not be ported to Windows, or any other
3969 operating system using extensions on executables.
3971 @item @code{no-installinfo}
3972 @cindex Option, no-installinfo
3973 The generated @file{Makefile.in} will not cause info pages to be built
3974 or installed by default. However, @code{info} and @code{install-info}
3975 targets will still be available. This option is disallowed at
3976 @samp{GNU} strictness and above.
3978 @trindex install-info
3980 @item @code{no-installman}
3981 @cindex Option, no-installman
3982 The generated @file{Makefile.in} will not cause man pages to be
3983 installed by default. However, an @code{install-man} target will still
3984 be available for optional installation. This option is disallowed at
3985 @samp{GNU} strictness and above.
3986 @trindex install-man
3988 @item @code{nostdinc}
3989 @cindex Option, nostdinc
3990 This option can be used to disable the standard @samp{-I} options which
3991 are ordinarily automatically provided by Automake.
3993 @item @code{no-texinfo.tex}
3994 @cindex Option, no-texinfo
3995 Don't require @file{texinfo.tex}, even if there are texinfo files in
3998 @item @code{readme-alpha}
3999 @cindex Option, readme-alpha
4000 If this release is an alpha release, and the file @file{README-alpha}
4001 exists, then it will be added to the distribution. If this option is
4002 given, version numbers are expected to follow one of two forms. The
4003 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
4004 element is a number; the final period and number should be left off for
4005 non-alpha releases. The second form is
4006 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
4007 letter; it should be omitted for non-alpha releases.
4009 @item @code{subdir-objects}
4010 If this option is specified, then objects are placed into the
4011 subdirectory of the build directory corresponding to the subdirectory of
4012 the source file. For instance if the source file is
4013 @file{subdir/file.cxx}, then the output file would be
4014 @file{subdir/file.o}.
4017 @cindex Option, version
4018 A version number (e.g. @samp{0.30}) can be specified. If Automake is not
4019 newer than the version specified, creation of the @file{Makefile.in}
4023 Unrecognized options are diagnosed by @code{automake}.
4025 If you want an option to apply to all the files in the tree, you can use
4026 the @code{AM_AUTOMAKE_OPTIONS} macro in @file{configure.in}.
4030 @node Miscellaneous, Include, Options, Top
4031 @chapter Miscellaneous Rules
4033 There are a few rules and variables that didn't fit anywhere else.
4036 * Tags:: Interfacing to etags and mkid
4037 * Suffixes:: Handling new file extensions
4038 * Multilibs:: Support for multilibbing.
4042 @node Tags, Suffixes, Miscellaneous, Miscellaneous
4043 @section Interfacing to @code{etags}
4045 @cindex TAGS support
4047 Automake will generate rules to generate @file{TAGS} files for use with
4048 GNU Emacs under some circumstances.
4050 If any C, C++ or Fortran 77 source code or headers are present, then
4051 @code{tags} and @code{TAGS} targets will be generated for the directory.
4054 At the topmost directory of a multi-directory package, a @code{tags}
4055 target file will be generated which, when run, will generate a
4056 @file{TAGS} file that includes by reference all @file{TAGS} files from
4059 The @code{tags} target will also be generated if the variable
4060 @code{ETAGS_ARGS} is defined. This variable is intended for use in
4061 directories which contain taggable source that @code{etags} does not
4062 understand. The user can use the @code{ETAGSFLAGS} to pass additional
4063 flags to @code{etags}; @code{AM_ETAGSFLAGS} is also available for use in
4067 @vindex AM_ETAGSFLAGS
4069 Here is how Automake generates tags for its source, and for nodes in its
4073 ETAGS_ARGS = automake.in --lang=none \
4074 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
4077 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
4078 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
4079 are added directly to the dependencies for the @code{tags} target.
4080 @vindex TAGS_DEPENDENCIES
4082 Automake will also generate an @code{ID} target which will run
4083 @code{mkid} on the source. This is only supported on a
4084 directory-by-directory basis.
4087 Automake also supports the @uref{http://www.gnu.org/software/global/,
4088 GNU Global Tags program}. The @code{GTAGS} target runs Global Tags
4089 automatically and puts the result in the top build directory. The
4090 variable @code{GTAGS_ARGS} holds arguments which are passed to
4095 @node Suffixes, Multilibs, Tags, Miscellaneous
4096 @section Handling new file extensions
4098 @cindex Adding new SUFFIXES
4099 @cindex SUFFIXES, adding
4102 It is sometimes useful to introduce a new implicit rule to handle a file
4103 type that Automake does not know about.
4105 For instance, suppose you had a compiler which could compile @samp{.foo}
4106 files to @samp{.o} files. You would simply define an suffix rule for
4114 Then you could directly use a @samp{.foo} file in a @samp{_SOURCES}
4115 variable and expect the correct results:
4119 doit_SOURCES = doit.foo
4122 This was the simpler and more common case. In other cases, you will
4123 have to help Automake to figure which extensions you are defining your
4124 suffix rule for. This usually happens when your extensions does not
4125 start with a dot. Then, all you have to do is to put a list of new
4126 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
4129 For instance the following definition prevents Automake to misinterpret
4130 @samp{.idlC.cpp:} as an attemp to transform @samp{.idlC} into
4134 SUFFIXES = .idl C.cpp
4139 As you may have noted, the @code{SUFFIXES} macro behaves like the
4140 @code{.SUFFIXES} special target of @code{make}. You should not touch
4141 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
4142 Automake generate the suffix list for @code{.SUFFIXES}. Any given
4143 @code{SUFFIXES} go at the start of the generated suffixes list, followed
4144 by Automake generated suffixes not already in the list.
4146 @node Multilibs, , Suffixes, Miscellaneous
4147 @section Support for Multilibs
4149 Automake has support for an obscure feature called multilibs. A
4150 @dfn{multilib} is a library which is built for multiple different ABIs
4151 at a single time; each time the library is built with a different target
4152 flag combination. This is only useful when the library is intended to
4153 be cross-compiled, and it is almost exclusively used for compiler
4156 The multilib support is still experimental. Only use it if you are
4157 familiar with multilibs and can debug problems you might encounter.
4160 @node Include, Conditionals, Miscellaneous, Top
4164 @cindex Including Makefile fragment
4165 @cindex Makefile fragment, including
4167 Automake supports an @code{include} directive which can be used to
4168 include other @file{Makefile} fragments when @code{automake} is run.
4169 Note that these fragments are read and interpreted by @code{automake},
4170 not by @code{make}. As with conditionals, @code{make} has no idea that
4171 @code{include} is in use.
4173 There are two forms of @code{include}:
4176 @item include $(srcdir)/file
4177 Include a fragment which is found relative to the current source
4180 @item include $(top_srcdir)/file
4181 Include a fragment which is found relative to the top source directory.
4184 Note that if a fragment is included inside a conditional, then the
4185 condition applies to the entire contents of that fragment.
4188 @node Conditionals, Gnits, Include, Top
4189 @chapter Conditionals
4191 @cindex Conditionals
4193 Automake supports a simple type of conditionals.
4195 @cvindex AM_CONDITIONAL
4196 Before using a conditional, you must define it by using
4197 @code{AM_CONDITIONAL} in the @code{configure.in} file (@pxref{Macros}).
4199 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
4200 The conditional name, @var{conditional}, should be a simple string
4201 starting with a letter and containing only letters, digits, and
4202 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
4203 which are reserved by Automake.
4205 The shell @var{condition} (suitable for use in a shell @code{if}
4206 statement) is evaluated when @code{configure} is run. Note that you
4207 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
4208 time @code{configure} is run -- if @code{AM_CONDITIONAL} is run
4209 conditionally (e.g., in a shell @code{if} statement), then the result
4210 will confuse automake.
4213 @cindex --enable-debug, example
4214 @cindex Example conditional --enable-debug
4215 @cindex Conditional example, --enable-debug
4217 Conditionals typically depend upon options which the user provides to
4218 the @code{configure} script. Here is an example of how to write a
4219 conditional which is true if the user uses the @samp{--enable-debug}
4223 AC_ARG_ENABLE(debug,
4224 [ --enable-debug Turn on debugging],
4225 [case "$@{enableval@}" in
4228 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
4229 esac],[debug=false])
4230 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
4233 Here is an example of how to use that conditional in @file{Makefile.am}:
4245 noinst_PROGRAMS = $(DBG)
4248 This trivial example could also be handled using EXTRA_PROGRAMS
4249 (@pxref{A Program}).
4251 You may only test a single variable in an @code{if} statement, possibly
4252 negated using @samp{!}. The @code{else} statement may be omitted.
4253 Conditionals may be nested to any depth. You may specify an argument to
4254 @code{else} in which case it must be the negation of the condition used
4255 for the current @code{if}. Similarly you may specify the condition
4256 which is closed by an @code{end}:
4267 Unbalanced conditions are errors.
4269 Note that conditionals in Automake are not the same as conditionals in
4270 GNU Make. Automake conditionals are checked at configure time by the
4271 @file{configure} script, and affect the translation from
4272 @file{Makefile.in} to @file{Makefile}. They are based on options passed
4273 to @file{configure} and on results that @file{configure} has discovered
4274 about the host system. GNU Make conditionals are checked at @code{make}
4275 time, and are based on variables passed to the make program or defined
4276 in the @file{Makefile}.
4278 Automake conditionals will work with any make program.
4281 @node Gnits, Cygnus, Conditionals, Top
4282 @chapter The effect of @code{--gnu} and @code{--gnits}
4284 @cindex --gnu, required files
4285 @cindex --gnu, complete description
4287 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
4288 variable) causes @code{automake} to check the following:
4292 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
4293 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
4294 directory of the package.
4297 The options @samp{no-installman} and @samp{no-installinfo} are
4301 Note that this option will be extended in the future to do even more
4302 checking; it is advisable to be familiar with the precise requirements
4303 of the GNU standards. Also, @samp{--gnu} can require certain
4304 non-standard GNU programs to exist for use by various maintainer-only
4305 targets; for instance in the future @code{pathchk} might be required for
4308 @cindex --gnits, complete description
4310 The @samp{--gnits} option does everything that @samp{--gnu} does, and
4311 checks the following as well:
4315 @samp{make dist} will check to make sure the @file{NEWS} file has been
4316 updated to the current version.
4319 @samp{VERSION} is checked to make sure its format complies with Gnits
4321 @c FIXME xref when standards are finished
4324 @cindex README-alpha
4325 If @samp{VERSION} indicates that this is an alpha release, and the file
4326 @file{README-alpha} appears in the topmost directory of a package, then
4327 it is included in the distribution. This is done in @samp{--gnits}
4328 mode, and no other, because this mode is the only one where version
4329 number formats are constrained, and hence the only mode where Automake
4330 can automatically determine whether @file{README-alpha} should be
4334 The file @file{THANKS} is required.
4338 @node Cygnus, Extending, Gnits, Top
4339 @chapter The effect of @code{--cygnus}
4341 @cindex Cygnus strictness
4343 Some packages, notably GNU GCC and GNU gdb, have a build environment
4344 originally written at Cygnus Support (subsequently renamed Cygnus
4345 Solutions, and then later purchased by Red Hat). Packages with this
4346 ancestry are sometimes referred to as ``Cygnus'' trees.
4348 A Cygnus tree has slightly different rules for how a @file{Makefile.in}
4349 is to be constructed. Passing @samp{--cygnus} to @code{automake} will
4350 cause any generated @file{Makefile.in} to comply with Cygnus rules.
4352 Here are the precise effects of @samp{--cygnus}:
4356 Info files are always created in the build directory, and not in the
4360 @file{texinfo.tex} is not required if a Texinfo source file is
4361 specified. The assumption is that the file will be supplied, but in a
4362 place that Automake cannot find. This assumption is an artifact of how
4363 Cygnus packages are typically bundled.
4366 @samp{make dist} is not supported, and the rules for it are not
4367 generated. Cygnus-style trees use their own distribution mechanism.
4370 Certain tools will be searched for in the build tree as well as in the
4371 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
4372 @code{makeinfo} and @code{texi2dvi}.
4375 @code{--foreign} is implied.
4378 The options @samp{no-installinfo} and @samp{no-dependencies} are
4382 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
4386 The @code{check} target doesn't depend on @code{all}.
4389 GNU maintainers are advised to use @samp{gnu} strictness in preference
4390 to the special Cygnus mode. Some day, perhaps, the differences between
4391 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
4392 more standards compliant). At that time the special Cygnus mode will be
4396 @node Extending, Distributing, Cygnus, Top
4397 @chapter When Automake Isn't Enough
4399 Automake's implicit copying semantics means that many problems can be
4400 worked around by simply adding some @code{make} targets and rules to
4401 @file{Makefile.in}. Automake will ignore these additions.
4403 @cindex -local targets
4404 @cindex local targets
4406 There are some caveats to doing this. Although you can overload a
4407 target already used by Automake, it is often inadvisable, particularly
4408 in the topmost directory of a package with subdirectories. However,
4409 various useful targets have a @samp{-local} version you can specify in
4410 your @file{Makefile.in}. Automake will supplement the standard target
4411 with these user-supplied targets.
4416 @trindex check-local
4417 @trindex install-data-local
4418 @trindex install-exec-local
4419 @trindex uninstall-local
4420 @trindex mostlyclean-local
4421 @trindex clean-local
4422 @trindex distclean-local
4423 @trindex installdirs-local
4424 @trindex installcheck-local
4426 The targets that support a local version are @code{all}, @code{info},
4427 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
4428 @code{uninstall}, @code{installdirs}, @code{installcheck} and the
4429 various @code{clean} targets (@code{mostlyclean}, @code{clean},
4430 @code{distclean}, and @code{maintainer-clean}). Note that there are no
4431 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
4432 use @code{uninstall-local}. It doesn't make sense to uninstall just
4433 data or just executables.
4438 @trindex install-data
4439 @trindex install-exec
4442 For instance, here is one way to install a file in @file{/etc}:
4446 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
4449 @cindex -hook targets
4450 @cindex hook targets
4452 Some targets also have a way to run another target, called a @dfn{hook},
4453 after their work is done. The hook is named after the principal target,
4454 with @samp{-hook} appended. The targets allowing hooks are
4455 @code{install-data}, @code{install-exec}, @code{uninstall}, @code{dist},
4456 and @code{distcheck}.
4457 @trindex install-data-hook
4458 @trindex install-exec-hook
4459 @trindex uninstall-hook
4462 For instance, here is how to create a hard link to an installed program:
4466 ln $(bindir)/program $(bindir)/proglink
4469 @c FIXME should include discussion of variables you can use in these
4473 @node Distributing, Macro and Variable Index, Extending, Top
4474 @chapter Distributing @file{Makefile.in}s
4476 Automake places no restrictions on the distribution of the resulting
4477 @file{Makefile.in}s. We still encourage software authors to distribute
4478 their work under terms like those of the GPL, but doing so is not
4479 required to use Automake.
4481 Some of the files that can be automatically installed via the
4482 @code{--add-missing} switch do fall under the GPL. However, these also
4483 have a special exception allowing you to distribute them with your
4484 package, regardless of the licensing you choose.
4488 @node Macro and Variable Index, General Index, Distributing, Top
4489 @unnumbered Macro and Variable Index
4495 @node General Index, , Macro and Variable Index, Top
4496 @unnumbered General Index