1 \input texinfo @c -*-texinfo-*-
3 @setfilename automake.info
10 @dircategory GNU programming tools
12 * automake: (automake). Making Makefile.in's
15 @dircategory Individual utilities
17 * aclocal: (automake)Invoking aclocal. Generating aclocal.m4
21 This file documents GNU automake @value{VERSION}
23 Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001
24 Free Software Foundation, Inc.
26 Permission is granted to make and distribute verbatim copies of
27 this manual provided the copyright notice and this permission notice
28 are preserved on all copies.
31 Permission is granted to process this file through TeX and print the
32 results, provided the printed document carries copying permission
33 notice identical to this one except for the removal of this paragraph
37 Permission is granted to copy and distribute modified versions of this
38 manual under the conditions for verbatim copying, provided that the entire
39 resulting derived work is distributed under the terms of a permission
40 notice identical to this one.
42 Permission is granted to copy and distribute translations of this manual
43 into another language, under the above conditions for modified versions,
44 except that this permission notice may be stated in a translation approved
51 @subtitle For version @value{VERSION}, @value{UPDATED}
52 @author David MacKenzie and Tom Tromey
55 @vskip 0pt plus 1filll
56 Copyright @copyright{} 1995, 1996, 2000, 2001 Free Software Foundation, Inc.
58 This is the first edition of the GNU Automake documentation,@*
59 and is consistent with GNU Automake @value{VERSION}.@*
61 Published by the Free Software Foundation @*
62 59 Temple Place - Suite 330, @*
63 Boston, MA 02111-1307 USA @*
65 Permission is granted to make and distribute verbatim copies of
66 this manual provided the copyright notice and this permission notice
67 are preserved on all copies.
69 Permission is granted to copy and distribute modified versions of this
70 manual under the conditions for verbatim copying, provided that the entire
71 resulting derived work is distributed under the terms of a permission
72 notice identical to this one.
74 Permission is granted to copy and distribute translations of this manual
75 into another language, under the above conditions for modified versions,
76 except that this permission notice may be stated in a translation
77 approved by the Free Software Foundation.
80 @c Define an index of configure output variables.
82 @c Define an index of configure variables.
84 @c Define an index of options.
86 @c Define an index of targets.
88 @c Define an index of commands.
91 @c Put the macros and variables into their own index.
92 @c @syncodeindex fn cp
97 @c Put everything else into one index (arbitrarily chosen to be the concept index).
103 @node Top, Introduction, (dir), (dir)
104 @comment node-name, next, previous, up
107 This file documents the GNU Automake package. Automake is a program
108 which creates GNU standards-compliant Makefiles from template files.
109 This edition documents version @value{VERSION}.
112 * Introduction:: Automake's purpose
113 * Generalities:: General ideas
114 * Examples:: Some example packages
115 * Invoking Automake:: Creating a Makefile.in
116 * configure:: Scanning configure.ac or configure.in
117 * Top level:: The top-level Makefile.am
118 * Alternative:: An alternative approach to subdirectories
119 * Rebuilding:: Automatic rebuilding of Makefile
120 * Programs:: Building programs and libraries
121 * Other objects:: Other derived objects
122 * Other GNU Tools:: Other GNU Tools
123 * Documentation:: Building documentation
124 * Install:: What gets installed
125 * Clean:: What gets cleaned
126 * Dist:: What goes in a distribution
127 * Tests:: Support for test suites
128 * Options:: Changing Automake's behavior
129 * Miscellaneous:: Miscellaneous rules
130 * Include:: Including extra files in an Automake template.
131 * Conditionals:: Conditionals
132 * Gnits:: The effect of @code{--gnu} and @code{--gnits}
133 * Cygnus:: The effect of @code{--cygnus}
134 * Extending:: Extending Automake
135 * Distributing:: Distributing the Makefile.in
136 * Macro and Variable Index::
143 @node Introduction, Generalities, Top, Top
144 @chapter Introduction
146 Automake is a tool for automatically generating @file{Makefile.in}s from
147 files called @file{Makefile.am}. Each @file{Makefile.am} is basically a
148 series of @code{make} macro definitions (with rules being thrown in
149 occasionally). The generated @file{Makefile.in}s are compliant with the
150 GNU Makefile standards.
152 @cindex GNU Makefile standards
154 The GNU Makefile Standards Document
155 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
156 is long, complicated, and subject to change. The goal of Automake is to
157 remove the burden of Makefile maintenance from the back of the
158 individual GNU maintainer (and put it on the back of the Automake
161 The typical Automake input file is simply a series of macro definitions.
162 Each such file is processed to create a @file{Makefile.in}. There
163 should generally be one @file{Makefile.am} per directory of a project.
165 @cindex Constraints of Automake
166 @cindex Automake constraints
168 Automake does constrain a project in certain ways; for instance it
169 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
170 autoconf, The Autoconf Manual}), and enforces certain restrictions on
171 the @file{configure.in} contents@footnote{Autoconf 2.50 promotes
172 @file{configure.ac} over @file{configure.in}. The rest of this
173 documentation will refer to @file{configure.in} as this use is not yet
174 spread, but Automake supports @file{configure.ac} too.}.
176 @cindex Automake requirements
177 @cindex Requirements, Automake
179 Automake requires @code{perl} in order to generate the
180 @file{Makefile.in}s. However, the distributions created by Automake are
181 fully GNU standards-compliant, and do not require @code{perl} in order
184 @cindex BUGS, reporting
185 @cindex Reporting BUGS
186 @cindex E-mail, bug reports
188 Mail suggestions and bug reports for Automake to
189 @email{bug-automake@@gnu.org}.
192 @node Generalities, Examples, Introduction, Top
193 @chapter General ideas
195 The following sections cover a few basic ideas that will help you
196 understand how Automake works.
199 * General Operation:: General operation of Automake
200 * Strictness:: Standards conformance checking
201 * Uniform:: The Uniform Naming Scheme
202 * Canonicalization:: How derived variables are named
203 * User Variables:: Variables reserved for the user
204 * Auxiliary Programs:: Programs automake might require
208 @node General Operation, Strictness, Generalities, Generalities
209 @section General Operation
211 Automake works by reading a @file{Makefile.am} and generating a
212 @file{Makefile.in}. Certain macros and targets defined in the
213 @file{Makefile.am} instruct Automake to generate more specialized code;
214 for instance, a @samp{bin_PROGRAMS} macro definition will cause targets
215 for compiling and linking programs to be generated.
217 @cindex Non-standard targets
218 @cindex cvs-dist, non-standard example
221 The macro definitions and targets in the @file{Makefile.am} are copied
222 verbatim into the generated file. This allows you to add arbitrary code
223 into the generated @file{Makefile.in}. For instance the Automake
224 distribution includes a non-standard @code{cvs-dist} target, which the
225 Automake maintainer uses to make distributions from his source control
228 @cindex GNU make extensions
230 Note that GNU make extensions are not recognized by Automake. Using
231 such extensions in a @file{Makefile.am} will lead to errors or confusing
234 Automake tries to group comments with adjoining targets and macro
235 definitions in an intelligent way.
237 @cindex Make targets, overriding
238 @cindex Overriding make targets
240 A target defined in @file{Makefile.am} generally overrides any such
241 target of a similar name that would be automatically generated by
242 @code{automake}. Although this is a supported feature, it is generally
243 best to avoid making use of it, as sometimes the generated rules are
246 @cindex Macros, overriding
247 @cindex Overriding make macros
249 Similarly, a macro defined in @file{Makefile.am} will override any
250 definition of the macro that @code{automake} would ordinarily create.
251 This feature is more often useful than the ability to override a target
252 definition. Be warned that many of the macros generated by
253 @code{automake} are considered to be for internal use only, and their
254 names might change in future releases.
256 @cindex Recursive operation of Automake
257 @cindex Automake, recursive operation
258 @cindex Example of recursive operation
260 When examining a macro definition, Automake will recursively examine
261 macros referenced in the definition. For example, if Automake is
262 looking at the content of @code{foo_SOURCES} in this snippet
266 foo_SOURCES = c.c $(xs)
269 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
270 contents of @code{foo_SOURCES}.
272 @cindex ## (special Automake comment)
273 @cindex Special Automake comment
274 @cindex Comment, special to Automake
276 Automake also allows a form of comment which is @emph{not} copied into
277 the output; all lines beginning with @samp{##} (leading spaces allowed)
278 are completely ignored by Automake.
280 It is customary to make the first line of @file{Makefile.am} read:
282 @cindex Makefile.am, first line
283 @cindex First line of Makefile.am
286 ## Process this file with automake to produce Makefile.in
289 @c FIXME discuss putting a copyright into Makefile.am here? I would but
290 @c I don't know quite what to say.
292 @c FIXME document customary ordering of Makefile.am here!
295 @node Strictness, Uniform, General Operation, Generalities
298 @cindex Non-GNU packages
300 While Automake is intended to be used by maintainers of GNU packages, it
301 does make some effort to accommodate those who wish to use it, but do
302 not want to use all the GNU conventions.
304 @cindex Strictness, defined
305 @cindex Strictness, foreign
306 @cindex foreign strictness
307 @cindex Strictness, gnu
308 @cindex gnits strictness
309 @cindex Strictness, gnits
310 @cindex gnits strictness
312 To this end, Automake supports three levels of @dfn{strictness}---the
313 strictness indicating how stringently Automake should check standards
316 The valid strictness levels are:
320 Automake will check for only those things which are absolutely
321 required for proper operations. For instance, whereas GNU standards
322 dictate the existence of a @file{NEWS} file, it will not be required in
323 this mode. The name comes from the fact that Automake is intended to be
324 used for GNU programs; these relaxed rules are not the standard mode of
328 Automake will check---as much as possible---for compliance to the GNU
329 standards for packages. This is the default.
332 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
333 standards}. These are based on the GNU standards, but are even more
334 detailed. Unless you are a Gnits standards contributor, it is
335 recommended that you avoid this option until such time as the Gnits
336 standard is actually published (which may never happen).
339 For more information on the precise implications of the strictness
340 level, see @ref{Gnits}.
342 Automake also has a special ``cygnus'' mode which is similar to
343 strictness but handled differently. This mode is useful for packages
344 which are put into a ``Cygnus'' style tree (e.g., the GCC tree). For
345 more information on this mode, see @ref{Cygnus}.
348 @node Uniform, Canonicalization, Strictness, Generalities
349 @section The Uniform Naming Scheme
351 @cindex Uniform naming scheme
353 Automake macros (from here on referred to as @emph{variables}) generally
354 follow a @dfn{uniform naming scheme} that makes it easy to decide how
355 programs (and other derived objects) are built, and how they are
356 installed. This scheme also supports @code{configure} time
357 determination of what should be built.
359 @cindex _PROGRAMS primary variable
360 @cindex PROGRAMS primary variable
361 @cindex Primary variable, PROGRAMS
363 @cindex Primary variable, defined
365 At @code{make} time, certain variables are used to determine which
366 objects are to be built. The variable names are made of several pieces
367 which are concatenated together.
369 The piece which tells automake what is being built is commonly called
370 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
371 list of programs which are to be compiled and linked.
374 @cindex pkglibdir, defined
375 @cindex pkgincludedir, defined
376 @cindex pkgdatadir, defined
379 @vindex pkgincludedir
382 A different set of names is used to decide where the built objects
383 should be installed. These names are prefixes to the primary which
384 indicate which standard directory should be used as the installation
385 directory. The standard directory names are given in the GNU standards
386 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
387 Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
388 and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
389 versions, but with @samp{@@PACKAGE@@} appended. For instance,
390 @code{pkglibdir} is defined as @code{$(libdir)/@@PACKAGE@@}.
393 @cindex EXTRA_, prepending
395 For each primary, there is one additional variable named by prepending
396 @samp{EXTRA_} to the primary name. This variable is used to list
397 objects which may or may not be built, depending on what
398 @code{configure} decides. This variable is required because Automake
399 must statically know the entire list of objects that may be built in
400 order to generate a @file{Makefile.in} that will work in all cases.
402 @cindex EXTRA_PROGRAMS, defined
403 @cindex Example, EXTRA_PROGRAMS
406 For instance, @code{cpio} decides at configure time which programs are
407 built. Some of the programs are installed in @code{bindir}, and some
408 are installed in @code{sbindir}:
411 EXTRA_PROGRAMS = mt rmt
412 bin_PROGRAMS = cpio pax
413 sbin_PROGRAMS = @@MORE_PROGRAMS@@
416 Defining a primary without a prefix as a variable, e.g.,
417 @code{PROGRAMS}, is an error.
419 Note that the common @samp{dir} suffix is left off when constructing the
420 variable names; thus one writes @samp{bin_PROGRAMS} and not
421 @samp{bindir_PROGRAMS}.
423 Not every sort of object can be installed in every directory. Automake
424 will flag those attempts it finds in error. Automake will also diagnose
425 obvious misspellings in directory names.
427 @cindex Extending list of installation directories
428 @cindex Installation directories, extending list
430 Sometimes the standard directories---even as augmented by Automake---
431 are not enough. In particular it is sometimes useful, for clarity, to
432 install objects in a subdirectory of some predefined directory. To this
433 end, Automake allows you to extend the list of possible installation
434 directories. A given prefix (e.g. @samp{zar}) is valid if a variable of
435 the same name with @samp{dir} appended is defined (e.g. @code{zardir}).
437 @cindex HTML support, example
439 For instance, until HTML support is part of Automake, you could use this
440 to install raw HTML documentation:
443 htmldir = $(prefix)/html
444 html_DATA = automake.html
447 @cindex noinst primary prefix, definition
449 The special prefix @samp{noinst} indicates that the objects in question
450 should not be installed at all.
452 @cindex check primary prefix, definition
454 The special prefix @samp{check} indicates that the objects in question
455 should not be built until the @code{make check} command is run.
457 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
458 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
459 @samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
471 Some primaries also allow additional prefixes which control other
472 aspects of @code{automake}'s behavior. The currently defined prefixes
473 are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes
477 @node Canonicalization, User Variables, Uniform, Generalities
478 @section How derived variables are named
480 @cindex canonicalizing Automake macros
482 Sometimes a Makefile variable name is derived from some text the
483 maintainer supplies. For instance, a program name listed in
484 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
485 variable. In cases like this, Automake canonicalizes the text, so that
486 program names and the like do not have to follow Makefile macro naming
487 rules. All characters in the name except for letters, numbers, the
488 strudel (@@), and the underscore are turned into underscores when making
491 For example, if your program is named @code{sniff-glue}, the derived
492 variable name would be @code{sniff_glue_SOURCES}, not
493 @code{sniff-glue_SOURCES}.
495 The strudel is an addition, to make the use of Autoconf substitutions in
496 macro names less obfuscating.
499 @node User Variables, Auxiliary Programs, Canonicalization, Generalities
500 @section Variables reserved for the user
502 @cindex variables, reserved for the user
503 @cindex user variables
505 Some @code{Makefile} variables are reserved by the GNU Coding Standards
506 for the use of the ``user'' -- the person building the package. For
507 instance, @code{CFLAGS} is one such variable.
509 Sometimes package developers are tempted to set user variables such as
510 @code{CFLAGS} because it appears to make their job easier -- they don't
511 have to introduce a second variable into every target.
513 However, the package itself should never set a user variable,
514 particularly not to include switches which are required for proper
515 compilation of the package. Since these variables are documented as
516 being for the package builder, that person rightfully expects to be able
517 to override any of these variables at build time.
519 To get around this problem, automake introduces an automake-specific
520 shadow variable for each user flag variable. (Shadow variables are not
521 introduced for variables like @code{CC}, where they would make no
522 sense.) The shadow variable is named by prepending @samp{AM_} to the
523 user variable's name. For instance, the shadow variable for
524 @code{YFLAGS} is @code{AM_YFLAGS}.
527 @node Auxiliary Programs, , User Variables, Generalities
528 @section Programs automake might require
530 @cindex Programs, auxiliary
531 @cindex Auxiliary programs
533 Automake sometimes requires helper programs so that the generated
534 @file{Makefile} can do its work properly. There are a fairly large
535 number of them, and we list them here.
540 These two files are used by the automatic de-ANSI-fication support
544 This is a wrapper for compilers which don't accept both @samp{-c} and
545 @samp{-o} at the same time. It is only used when absolutely required.
546 Such compilers are rare.
550 These programs compute the canonical triplets for the given build, host,
551 or target architecture.
554 This program understands how to run a compiler so that it will generate
555 not only the desired output but also dependency information which is
556 then used by the automatic dependency tracking feature.
559 This program is used to byte-compile Emacs Lisp code.
562 This is a replacement for the @code{install} program which works on
563 platforms where @code{install} is unavailable or unusable.
566 This script is used to generate a @file{version.texi} file. It examines
567 a file and prints some date information about it.
570 This wraps a number of programs which are typically only required by
571 maintainers. If the program in question doesn't exist, @code{missing}
572 prints an informative warning and attempts to fix things so that the
576 This works around the fact that @code{mkdir -p} is not portable.
579 This is used to byte-compile Python scripts.
582 Not a program, this file is required for @code{make dvi} to work when
583 Texinfo sources are in the package.
586 This program wraps @code{lex} and @code{yacc} and ensures that, for
587 instance, multiple @code{yacc} instances can be invoked in a single
588 directory in parallel.
593 @node Examples, Invoking Automake, Generalities, Top
594 @chapter Some example packages
597 * Complete:: A simple example, start to finish
598 * Hello:: A classic program
599 * etags:: Building etags and ctags
603 @node Complete, Hello, Examples, Examples
604 @section A simple example, start to finish
606 @cindex Complete example
608 Let's suppose you just finished writing @code{zardoz}, a program to make
609 your head float from vortex to vortex. You've been using Autoconf to
610 provide a portability framework, but your @file{Makefile.in}s have been
611 ad-hoc. You want to make them bulletproof, so you turn to Automake.
613 @cindex AM_INIT_AUTOMAKE, example use
615 The first step is to update your @file{configure.in} to include the
616 commands that @code{automake} needs. The way to do this is to add an
617 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
620 AM_INIT_AUTOMAKE(zardoz, 1.0)
623 Since your program doesn't have any complicating factors (e.g., it
624 doesn't use @code{gettext}, it doesn't want to build a shared library),
625 you're done with this part. That was easy!
627 @cindex aclocal program, introduction
628 @cindex aclocal.m4, preexisting
629 @cindex acinclude.m4, defined
631 Now you must regenerate @file{configure}. But to do that, you'll need
632 to tell @code{autoconf} how to find the new macro you've used. The
633 easiest way to do this is to use the @code{aclocal} program to generate
634 your @file{aclocal.m4} for you. But wait... you already have an
635 @file{aclocal.m4}, because you had to write some hairy macros for your
636 program. The @code{aclocal} program lets you put your own macros into
637 @file{acinclude.m4}, so simply rename and then run:
640 mv aclocal.m4 acinclude.m4
645 @cindex zardoz example
647 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
648 Since @code{zardoz} is a user program, you want to install it where the
649 rest of the user programs go. Additionally, @code{zardoz} has some
650 Texinfo documentation. Your @file{configure.in} script uses
651 @code{AC_REPLACE_FUNCS}, so you need to link against @samp{@@LIBOBJS@@}.
652 So here's what you'd write:
655 bin_PROGRAMS = zardoz
656 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
657 zardoz_LDADD = @@LIBOBJS@@
659 info_TEXINFOS = zardoz.texi
662 Now you can run @code{automake --add-missing} to generate your
663 @file{Makefile.in} and grab any auxiliary files you might need, and
667 @node Hello, etags, Complete, Examples
668 @section A classic program
670 @cindex Example, GNU Hello
671 @cindex Hello example
672 @cindex GNU Hello, example
674 @uref{ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz, GNU hello} is
675 renowned for its classic simplicity and versatility. This section shows
676 how Automake could be used with the GNU Hello package. The examples
677 below are from the latest beta version of GNU Hello, but with all of the
678 maintainer-only code stripped out, as well as all copyright comments.
680 Of course, GNU Hello is somewhat more featureful than your traditional
681 two-liner. GNU Hello is internationalized, does option processing, and
682 has a manual and a test suite.
684 @cindex configure.in, from GNU Hello
685 @cindex GNU Hello, configure.in
686 @cindex Hello, configure.in
688 Here is the @file{configure.in} from GNU Hello:
691 dnl Process this file with autoconf to produce a configure script.
693 AM_INIT_AUTOMAKE(hello, 1.3.11)
694 AM_CONFIG_HEADER(config.h)
696 dnl Set of available languages.
697 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
699 dnl Checks for programs.
703 dnl Checks for libraries.
705 dnl Checks for header files.
707 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
709 dnl Checks for library functions.
712 dnl Check for st_blksize in struct stat
715 dnl internationalization macros
717 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
718 src/Makefile tests/Makefile tests/hello],
719 [chmod +x tests/hello])
722 The @samp{AM_} macros are provided by Automake (or the Gettext library);
723 the rest are standard Autoconf macros.
726 The top-level @file{Makefile.am}:
729 EXTRA_DIST = BUGS ChangeLog.O
730 SUBDIRS = doc intl po src tests
733 As you can see, all the work here is really done in subdirectories.
735 The @file{po} and @file{intl} directories are automatically generated
736 using @code{gettextize}; they will not be discussed here.
738 @cindex Texinfo file handling example
739 @cindex Example, handling Texinfo files
741 In @file{doc/Makefile.am} we see:
744 info_TEXINFOS = hello.texi
745 hello_TEXINFOS = gpl.texi
748 This is sufficient to build, install, and distribute the GNU Hello
751 @cindex Regression test example
752 @cindex Example, regression test
754 Here is @file{tests/Makefile.am}:
758 EXTRA_DIST = hello.in testdata
761 The script @file{hello} is generated by @code{configure}, and is the
762 only test case. @code{make check} will run this test.
764 @cindex INCLUDES, example usage
766 Last we have @file{src/Makefile.am}, where all the real work is done:
770 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
771 hello_LDADD = @@INTLLIBS@@ @@ALLOCA@@
772 localedir = $(datadir)/locale
773 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
777 @node etags, , Hello, Examples
778 @section Building etags and ctags
780 @cindex Example, ctags and etags
781 @cindex ctags Example
782 @cindex etags Example
784 Here is another, trickier example. It shows how to generate two
785 programs (@code{ctags} and @code{etags}) from the same source file
786 (@file{etags.c}). The difficult part is that each compilation of
787 @file{etags.c} requires different @code{cpp} flags.
790 bin_PROGRAMS = etags ctags
792 ctags_LDADD = ctags.o
795 $(COMPILE) -DETAGS_REGEXPS -c etags.c
798 $(COMPILE) -DCTAGS -o ctags.o -c etags.c
801 Note that @code{ctags_SOURCES} is defined to be empty---that way no
802 implicit value is substituted. The implicit value, however, is used to
803 generate @code{etags} from @file{etags.o}.
805 @code{ctags_LDADD} is used to get @file{ctags.o} into the link line.
806 @code{ctags_DEPENDENCIES} is generated by Automake.
808 The above rules won't work if your compiler doesn't accept both
809 @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
810 bogus dependency (to avoid problems with a parallel @code{make}):
813 etags.o: etags.c ctags.o
814 $(COMPILE) -DETAGS_REGEXPS -c etags.c
817 $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
820 Also, these explicit rules do not work if the de-ANSI-fication feature
821 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
825 etags._o: etags._c ctags.o
826 $(COMPILE) -DETAGS_REGEXPS -c etags.c
829 $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
832 As it turns out, there is also a much easier way to do this same task.
833 Some of the above techniques are useful enough that we've kept the
834 example in the manual. However if you were to build @code{etags} and
835 @code{ctags} in real life, you would probably use per-program
836 compilation flags, like so:
839 bin_PROGRAMS = ctags etags
841 ctags_SOURCES = etags.c
842 ctags_CFLAGS = -DCTAGS
844 etags_SOURCES = etags.c
845 etags_CFLAGS = -DETAGS_REGEXPS
848 In this case Automake will cause @file{etags.c} to be compiled twice,
849 with different flags. De-ANSI-fication will work automatically. In
850 this instance, the names of the object files would be chosen by
851 automake; they would be @file{ctags-etags.o} and @file{etags-etags.o}.
852 (The name of the object files rarely matters.)
855 @node Invoking Automake, configure, Examples, Top
856 @chapter Creating a @file{Makefile.in}
858 @cindex Multiple configure.in files
859 @cindex Invoking Automake
860 @cindex Automake, invoking
862 To create all the @file{Makefile.in}s for a package, run the
863 @code{automake} program in the top level directory, with no arguments.
864 @code{automake} will automatically find each appropriate
865 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
866 and generate the corresponding @file{Makefile.in}. Note that
867 @code{automake} has a rather simplistic view of what constitutes a
868 package; it assumes that a package has only one @file{configure.in}, at
869 the top. If your package has multiple @file{configure.in}s, then you
870 must run @code{automake} in each directory holding a
873 You can optionally give @code{automake} an argument; @file{.am} is
874 appended to the argument and the result is used as the name of the input
875 file. This feature is generally only used to automatically rebuild an
876 out-of-date @file{Makefile.in}. Note that @code{automake} must always
877 be run from the topmost directory of a project, even if being used to
878 regenerate the @file{Makefile.in} in some subdirectory. This is
879 necessary because @code{automake} must scan @file{configure.in}, and
880 because @code{automake} uses the knowledge that a @file{Makefile.in} is
881 in a subdirectory to change its behavior in some cases.
883 @cindex Automake options
884 @cindex Options, Automake
886 @code{automake} accepts the following options:
888 @cindex Extra files distributed with Automake
889 @cindex Files distributed with Automake
896 @opindex --add-missing
897 Automake requires certain common files to exist in certain situations;
898 for instance @file{config.guess} is required if @file{configure.in} runs
899 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
900 files; this option will cause the missing ones to be automatically added
901 to the package, whenever possible. In general if Automake tells you a
902 file is missing, try using this option. By default Automake tries to
903 make a symbolic link pointing to its own copy of the missing file; this
904 can be changed with @code{--copy}.
906 @item --libdir=@var{dir}
908 Look for Automake data files in directory @var{dir} instead of in the
909 installation directory. This is typically used for debugging.
915 When used with @code{--add-missing}, causes installed files to be
916 copied. The default is to make a symbolic link.
920 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
921 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
925 @itemx --force-missing
926 @opindex --force-missing
927 When used with @code{--add-missing}, causes standard files to be rebuilt
928 even if they already exist in the source tree. This involves removing
929 the file from the source tree before creating the new symlink (or, with
930 @code{--copy}, copying the new file).
934 Set the global strictness to @samp{foreign}. For more information, see
939 Set the global strictness to @samp{gnits}. For more information, see
944 Set the global strictness to @samp{gnu}. For more information, see
945 @ref{Gnits}. This is the default strictness.
949 Print a summary of the command line options and exit.
954 This disables the dependency tracking feature; see @ref{Dependencies}.
957 @opindex --include-deps
958 This enables the dependency tracking feature. This feature is enabled
959 by default. This option is provided for historical reasons only and
960 probably should not be used.
964 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
965 @file{configure.in}. This option causes it to only update those
966 @file{Makefile.in}s which are out of date with respect to one of their
970 @itemx --output-dir=@var{dir}
972 @opindex --output-dir
973 Put the generated @file{Makefile.in} in the directory @var{dir}.
974 Ordinarily each @file{Makefile.in} is created in the directory of the
975 corresponding @file{Makefile.am}. This option is used when making
982 Cause Automake to print information about which files are being read or
987 Print the version number of Automake and exit.
993 @samp{--Werror} will cause all warnings issued by @code{automake} to
994 become errors. Errors affect the exit status of @code{automake}, while
995 warnings do not. @samp{--Wno-error}, the default, causes warnings to be
996 treated as warnings only.
1000 @node configure, Top level, Invoking Automake, Top
1001 @chapter Scanning @file{configure.in}
1003 @cindex configure.in, scanning
1004 @cindex Scanning configure.in
1006 Automake scans the package's @file{configure.in} to determine certain
1007 information about the package. Some @code{autoconf} macros are required
1008 and some variables must be defined in @file{configure.in}. Automake
1009 will also use information from @file{configure.in} to further tailor its
1012 Automake also supplies some Autoconf macros to make the maintenance
1013 easier. These macros can automatically be put into your
1014 @file{aclocal.m4} using the @code{aclocal} program.
1017 * Requirements:: Configuration requirements
1018 * Optional:: Other things Automake recognizes
1019 * Invoking aclocal:: Auto-generating aclocal.m4
1020 * Macros:: Autoconf macros supplied with Automake
1021 * Extending aclocal:: Writing your own aclocal macros
1025 @node Requirements, Optional, configure, configure
1026 @section Configuration requirements
1028 @cindex Automake requirements
1029 @cindex Requirements of Automake
1031 The one real requirement of Automake is that your @file{configure.in}
1032 call @code{AM_INIT_AUTOMAKE}. This macro does several things which are
1033 required for proper Automake operation.
1034 @cvindex AM_INIT_AUTOMAKE
1036 Here are the other macros which Automake requires but which are not run
1037 by @code{AM_INIT_AUTOMAKE}:
1039 @cindex AC_OUTPUT, scanning
1043 Automake uses this to determine which files to create (@pxref{Output, ,
1044 Creating Output Files, autoconf, The Autoconf Manual}). Listed files
1045 named @code{Makefile} are treated as @file{Makefile}s. Other listed
1046 files are treated differently. Currently the only difference is that a
1047 @file{Makefile} is removed by @code{make distclean}, while other files
1048 are removed by @code{make clean}.
1049 @c FIXME: this is in violation of standards!
1053 You may need the following macros in some conditions, even though they
1057 @item AC_CHECK_TOOL([STRIP],[strip])
1058 @cindex STRIP, how to setup
1059 @cindex install-strip and STRIP
1060 @cvindex AC_CHECK_TOOL([STRIP],[strip])
1061 Installed binaries are usually stripped using @code{strip} when you run
1062 @code{make install-strip}. However @code{strip} might not be the
1063 right tool to use in cross-compilation environments, therefore
1064 Automake will honor the @code{STRIP} environment variable to overrule
1065 the program used to perform stripping. Automake will not set @code{STRIP}
1066 itself. If your package is not setup for cross-compilation you do not
1067 have to care (@code{strip} is ok), otherwise you can set @code{STRIP}
1068 automatically by calling @code{AC_CHECK_TOOL([STRIP],[strip])} from
1069 your @file{configure.in}.
1073 @node Optional, Invoking aclocal, Requirements, configure
1074 @section Other things Automake recognizes
1076 @cindex Macros Automake recognizes
1077 @cindex Recognized macros by Automake
1079 Automake will also recognize the use of certain macros and tailor the
1080 generated @file{Makefile.in} appropriately. Currently recognized macros
1081 and their effects are:
1084 @item AC_CONFIG_HEADER
1085 Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar
1086 to @code{AC_CONFIG_HEADER} (@pxref{Configuration Headers, ,
1087 Configuration Header Files, autoconf, The Autoconf Manual}), but does
1088 some useful Automake-specific work.
1089 @cvindex AC_CONFIG_HEADER
1091 @item AC_CONFIG_AUX_DIR
1092 Automake will look for various helper scripts, such as
1093 @file{mkinstalldirs}, in the directory named in this macro invocation.
1094 If not seen, the scripts are looked for in their @samp{standard}
1095 locations (either the top source directory, or in the source directory
1096 corresponding to the current @file{Makefile.am}, whichever is
1097 appropriate). @xref{Input, , Finding `configure' Input, autoconf, The
1099 @cvindex AC_CONFIG_AUX_DIR
1100 FIXME: give complete list of things looked for in this directory
1103 Automake will insert definitions for the variables defined by
1104 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
1105 or library. @xref{System Services, , System Services, autoconf, The
1107 @cvindex AC_PATH_XTRA
1109 @item AC_CANONICAL_HOST
1110 @itemx AC_CHECK_TOOL
1111 Automake will ensure that @file{config.guess} and @file{config.sub}
1112 exist. Also, the @file{Makefile} variables @samp{host_alias} and
1113 @samp{host_triplet} are introduced. See both @ref{Canonicalizing, ,
1114 Getting the Canonical System Type, autoconf, The Autoconf Manual}, and
1115 @ref{Generic Programs, , Generic Program Checks, autoconf, The Autoconf
1117 @c fixme xref autoconf docs.
1118 @cvindex AC_CANONICAL_HOST
1119 @cvindex AC_CHECK_TOOL
1121 @vindex host_triplet
1123 @item AC_CANONICAL_SYSTEM
1124 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
1125 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
1126 @xref{Canonicalizing, , Getting the Canonical System Type, autoconf, The
1128 @cvindex AC_CANONICAL_SYSTEM
1130 @vindex target_alias
1132 @item AC_FUNC_ALLOCA
1133 @itemx AC_FUNC_ERROR_AT_LINE
1134 @itemx AC_FUNC_FNMATCH
1135 @itemx AC_FUNC_GETLOADAVG
1136 @itemx AC_FUNC_MEMCMP
1137 @itemx AC_FUNC_MKTIME
1138 @itemx AC_FUNC_OBSTACK
1139 @itemx AC_FUNC_STRTOD
1140 @itemx AC_REPLACE_FUNCS
1141 @itemx AC_REPLACE_GNU_GETOPT
1142 @itemx AC_STRUCT_ST_BLOCKS
1143 @itemx AM_WITH_REGEX
1144 Automake will ensure that the appropriate dependencies are generated for
1145 the objects corresponding to these macros. Also, Automake will verify
1146 that the appropriate source files are part of the distribution. Note
1147 that Automake does not come with any of the C sources required to use
1148 these macros, so @code{automake -a} will not install the sources.
1149 @xref{A Library}, for more information. Also, see @ref{Particular
1150 Functions, , Particular Function Checks, autoconf, The Autoconf Manual}.
1151 @cvindex AC_FUNC_ALLOCA
1152 @cvindex AC_FUNC_ERROR_AT_LINE
1153 @cvindex AC_FUNC_FNMATCH
1154 @cvindex AC_FUNC_GETLOADAVG
1155 @cvindex AC_FUNC_MEMCMP
1156 @cvindex AC_FUNC_MKTIME
1157 @cvindex AC_FUNC_OBSTACK
1158 @cvindex AC_FUNC_STRTOD
1159 @cvindex AC_REPLACE_FUNCS
1160 @cvindex AC_REPLACE_GNU_GETOPT
1161 @cvindex AC_STRUCT_ST_BLOCKS
1162 @cvindex AM_WITH_REGEX
1165 Automake will detect statements which put @file{.o} files into
1166 @code{LIBOBJS}, and will treat these additional files as if they were
1167 discovered via @code{AC_REPLACE_FUNCS}. @xref{Generic Functions, ,
1168 Generic Function Checks, autoconf, The Autoconf Manual}.
1171 @item AC_PROG_RANLIB
1172 This is required if any libraries are built in the package.
1173 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1175 @cvindex AC_PROG_RANLIB
1178 This is required if any C++ source is included. @xref{Particular
1179 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1180 @cvindex AC_PROG_CXX
1183 This is required if any Fortran 77 source is included. This macro is
1184 distributed with Autoconf version 2.13 and later. @xref{Particular
1185 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1186 @cvindex AC_PROG_F77
1188 @item AC_F77_LIBRARY_LDFLAGS
1189 This is required for programs and shared libraries that are a mixture of
1190 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
1191 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
1192 @cvindex AC_F77_LIBRARY_LDFLAGS
1194 @item AC_PROG_LIBTOOL
1195 Automake will turn on processing for @code{libtool} (@pxref{Top, ,
1196 Introduction, libtool, The Libtool Manual}).
1197 @cvindex AC_PROG_LIBTOOL
1200 If a Yacc source file is seen, then you must either use this macro or
1201 define the variable @samp{YACC} in @file{configure.in}. The former is
1202 preferred (@pxref{Particular Programs, , Particular Program Checks,
1203 autoconf, The Autoconf Manual}).
1204 @cvindex AC_PROG_YACC
1208 If a Lex source file is seen, then this macro must be used.
1209 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1211 @cvindex AC_PROG_LEX
1213 @item AM_C_PROTOTYPES
1214 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
1215 @cvindex AM_C_PROTOTYPES
1217 @item AM_GNU_GETTEXT
1218 This macro is required for packages which use GNU gettext
1219 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1220 this macro it ensures that the package meets some of gettext's
1222 @cvindex AM_GNU_GETTEXT
1224 @item AM_MAINTAINER_MODE
1225 @opindex --enable-maintainer-mode
1226 This macro adds a @samp{--enable-maintainer-mode} option to
1227 @code{configure}. If this is used, @code{automake} will cause
1228 @samp{maintainer-only} rules to be turned off by default in the
1229 generated @file{Makefile.in}s. This macro is disallowed in @samp{Gnits}
1230 mode (@pxref{Gnits}). This macro defines the @samp{MAINTAINER_MODE}
1231 conditional, which you can use in your own @file{Makefile.am}.
1232 @cvindex AM_MAINTAINER_MODE
1235 @itemx AC_CHECK_TOOL
1236 @itemx AC_CHECK_PROG
1237 @itemx AC_CHECK_PROGS
1239 @itemx AC_PATH_PROGS
1240 For each of these macros, the first argument is automatically defined as
1241 a variable in each generated @file{Makefile.in}. @xref{Setting Output
1242 Variables, , Setting Output Variables, autoconf, The Autoconf Manual},
1243 and @ref{Generic Programs, , Generic Program Checks, autoconf, The
1246 @cvindex AC_CHECK_TOOL
1247 @cvindex AC_CHECK_PROG
1248 @cvindex AC_CHECK_PROGS
1249 @cvindex AC_PATH_PROG
1250 @cvindex AC_PATH_PROGS
1255 @node Invoking aclocal, Macros, Optional, configure
1256 @section Auto-generating aclocal.m4
1258 @cindex Invoking aclocal
1259 @cindex aclocal, Invoking
1261 Automake includes a number of Autoconf macros which can be used in your
1262 package; some of them are actually required by Automake in certain
1263 situations. These macros must be defined in your @file{aclocal.m4};
1264 otherwise they will not be seen by @code{autoconf}.
1266 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1267 files based on the contents of @file{configure.in}. This provides a
1268 convenient way to get Automake-provided macros, without having to
1269 search around. Also, the @code{aclocal} mechanism is extensible for use
1272 At startup, @code{aclocal} scans all the @file{.m4} files it can find,
1273 looking for macro definitions. Then it scans @file{configure.in}. Any
1274 mention of one of the macros found in the first step causes that macro,
1275 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1277 The contents of @file{acinclude.m4}, if it exists, are also
1278 automatically included in @file{aclocal.m4}. This is useful for
1279 incorporating local macros into @file{configure}.
1281 @code{aclocal} tries to be smart about looking for new @code{AC_DEFUN}s
1282 in the files it scans. It will warn if it finds duplicates. It also
1283 tries to copy the full text of the scanned file into @file{aclocal.m4},
1284 including both @samp{#} and @samp{dnl} comments. If you want to make a
1285 comment which will be completely ignored by @code{aclocal}, use
1286 @samp{##} as the comment leader.
1288 @code{aclocal} accepts the following options:
1291 @item --acdir=@var{dir}
1293 Look for the macro files in @var{dir} instead of the installation
1294 directory. This is typically used for debugging.
1298 Print a summary of the command line options and exit.
1302 Add the directory @var{dir} to the list of directories searched for
1305 @item --output=@var{file}
1307 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1309 @item --print-ac-dir
1310 @opindex --print-ac-dir
1311 Prints the name of the directory which @code{aclocal} will search to
1312 find the @file{.m4} files. When this option is given, normal processing
1313 is suppressed. This option can be used by a package to determine where
1314 to install a macro file.
1318 Print the names of the files it examines.
1322 Print the version number of Automake and exit.
1326 @node Macros, Extending aclocal, Invoking aclocal, configure
1327 @section Autoconf macros supplied with Automake
1329 @c consider generating this node automatically from m4 files.
1332 @item AM_CONFIG_HEADER
1333 Automake will generate rules to automatically regenerate the config
1335 @cvindex AM_CONFIG_HEADER
1337 @item AM_ENABLE_MULTILIB
1338 This is used when a ``multilib'' library is being built. The first
1339 optional argument is the name of the @file{Makefile} being generated; it
1340 defaults to @samp{Makefile}. The second option argument is used to find
1341 the top source directory; it defaults to the empty string (generally
1342 this should not be used unless you are familiar with the internals).
1345 @item _AM_DEPENDENCIES
1346 @itemx AM_SET_DEPDIR
1348 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
1349 These macros are used to implement automake's automatic dependency
1350 tracking scheme. They are called automatically by automake when
1351 required, and there should be no need to invoke them manually.
1353 @item AM_C_PROTOTYPES
1354 Check to see if function prototypes are understood by the compiler. If
1355 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1356 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1357 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1358 values to implement automatic de-ANSI-fication.
1359 @cvindex AM_C_PROTOTYPES
1361 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1362 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1363 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1364 found in @file{<termios.h>}.
1365 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1367 @item AM_INIT_AUTOMAKE
1368 Runs many macros that most @file{configure.in}'s need. This macro has
1369 two required arguments, the package and the version number. By default
1370 this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}. This
1371 can be avoided by passing in a non-empty third argument.
1373 @item AM_MAKE_INCLUDE
1374 This macro is used to discover how the user's @code{make} handles
1375 @code{include} statements. This macro is automatically invoked when
1376 needed; there should be no need to invoke it manually.
1378 @item AM_PATH_LISPDIR
1379 Searches for the program @code{emacs}, and, if found, sets the output
1380 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1381 @cvindex AM_PATH_LISPDIR
1384 Use this macro when you have assembly code in your project. This will
1385 choose the assembler for you (by default the C compiler), and will set
1386 @code{ASFLAGS} if required.
1388 @item AM_PROG_CC_C_O
1389 This is like @code{AC_PROG_CC_C_O}, but it generates its results in the
1390 manner required by automake. You must use this instead of
1391 @code{AC_PROG_CC_C_O} when you need this functionality.
1393 @item AM_PROG_CC_STDC
1394 If the C compiler is not in ANSI C mode by default, try to add an option
1395 to output variable @code{CC} to make it so. This macro tries various
1396 options that select ANSI C on some system or another. It considers the
1397 compiler to be in ANSI C mode if it handles function prototypes correctly.
1399 If you use this macro, you should check after calling it whether the C
1400 compiler has been set to accept ANSI C; if not, the shell variable
1401 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1402 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1403 @code{ansi2knr} option (@pxref{ANSI}).
1406 @cindex HP-UX 10, lex problems
1407 @cindex lex problems with HP-UX 10
1408 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
1409 Program Checks, autoconf, The Autoconf Manual}), but uses the
1410 @code{missing} script on systems that do not have @code{lex}.
1411 @samp{HP-UX 10} is one such system.
1414 This macro finds the @code{gcj} program or causes an error. It sets
1415 @samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
1416 GNU Compiler Collection.
1417 @cvindex AM_PROG_GCJ
1419 @item AM_PROG_INSTALL_STRIP
1420 This is used to find a version of @code{install} which can be used to
1421 @code{strip} a program at installation time. This macro is
1422 automatically included when required.
1424 @item AM_SANITY_CHECK
1425 This checks to make sure that a file created in the build directory is
1426 newer than a file in the source directory. This can fail on systems
1427 where the clock is set incorrectly. This macro is automatically run
1428 from @code{AM_INIT_AUTOMAKE}.
1430 @item AM_SYS_POSIX_TERMIOS
1431 @cvindex am_cv_sys_posix_termios
1432 @cindex POSIX termios headers
1433 @cindex termios POSIX headers
1434 Check to see if POSIX termios headers and functions are available on the
1435 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1436 @samp{yes}. If not, set the variable to @samp{no}.
1438 @item AM_WITH_DMALLOC
1439 @cvindex WITH_DMALLOC
1440 @cindex dmalloc, support for
1441 @opindex --with-dmalloc
1443 @uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
1444 package. If the user configures with @samp{--with-dmalloc}, then define
1445 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
1449 @opindex --with-regex
1450 @cindex regex package
1452 Adds @samp{--with-regex} to the @code{configure} command line. If
1453 specified (the default), then the @samp{regex} regular expression
1454 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1455 @samp{WITH_REGEX} is defined.. If @samp{--without-regex} is given, then
1456 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1457 into @samp{LIBOBJS}.
1462 @node Extending aclocal, , Macros, configure
1463 @section Writing your own aclocal macros
1465 @cindex aclocal, extending
1466 @cindex Extending aclocal
1468 The @code{aclocal} program doesn't have any built-in knowledge of any
1469 macros, so it is easy to extend it with your own macros.
1471 This is mostly used for libraries which want to supply their own
1472 Autoconf macros for use by other programs. For instance the
1473 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1474 should be used by any package using @code{gettext}. When the library is
1475 installed, it installs this macro so that @code{aclocal} will find it.
1477 A file of macros should be a series of @code{AC_DEFUN}'s. The
1478 @code{aclocal} programs also understands @code{AC_REQUIRE}, so it is
1479 safe to put each macro in a separate file. @xref{Prerequisite Macros, ,
1480 , autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
1481 autoconf, The Autoconf Manual}.
1483 A macro file's name should end in @file{.m4}. Such files should be
1484 installed in @file{$(datadir)/aclocal}.
1487 @node Top level, Alternative, configure, Top
1488 @chapter The top-level @file{Makefile.am}
1490 @cindex SUBDIRS, explained
1492 In packages with subdirectories, the top level @file{Makefile.am} must
1493 tell Automake which subdirectories are to be built. This is done via
1494 the @code{SUBDIRS} variable.
1497 The @code{SUBDIRS} macro holds a list of subdirectories in which
1498 building of various sorts can occur. Many targets (e.g. @code{all}) in
1499 the generated @file{Makefile} will run both locally and in all specified
1500 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1501 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1502 (after configuration). This allows inclusion of libraries from packages
1503 which do not use Automake (such as @code{gettext}). The directories
1504 mentioned in @code{SUBDIRS} must be direct children of the current
1505 directory. For instance, you cannot put @samp{src/subdir} into
1508 In packages that use subdirectories, the top-level @file{Makefile.am} is
1509 often very short. For instance, here is the @file{Makefile.am} from the
1510 GNU Hello distribution:
1513 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1514 SUBDIRS = doc intl po src tests
1517 @cindex SUBDIRS, overriding
1518 @cindex Overriding SUBDIRS
1520 It is possible to override the @code{SUBDIRS} variable if, like in the
1521 case of GNU @code{Inetutils}, you want to only build a subset of the
1522 entire package. In your @file{Makefile.am} include:
1525 SUBDIRS = @@MY_SUBDIRS@@
1528 Then in your @file{configure.in} you can specify:
1531 MY_SUBDIRS="src doc lib po"
1532 AC_SUBST(MY_SUBDIRS)
1535 (Note that we don't use the variable name @code{SUBDIRS} in our
1536 @file{configure.in}; that would cause Automake to believe that every
1537 @file{Makefile.in} should recurse into the listed subdirectories.)
1539 The upshot of this is that Automake is tricked into building the package
1540 to take the subdirs, but doesn't actually bind that list until
1541 @code{configure} is run.
1543 Although the @code{SUBDIRS} macro can contain configure substitutions
1544 (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
1545 contents of this variable.
1547 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1548 @code{AC_PROG_MAKE_SET}. When Automake invokes @code{make} in a
1549 subdirectory, it uses the value of the @code{MAKE} variable. It passes
1550 the value of the variable @code{AM_MAKEFLAGS} to the @code{make}
1551 invocation; this can be set in @file{Makefile.am} if there are flags you
1552 must always pass to @code{make}.
1556 The use of @code{SUBDIRS} is not restricted to just the top-level
1557 @file{Makefile.am}. Automake can be used to construct packages of
1560 By default, Automake generates @file{Makefiles} which work depth-first
1561 (@samp{postfix}). However, it is possible to change this ordering. You
1562 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
1563 putting @samp{.} first will cause a @samp{prefix} ordering of
1564 directories. All @samp{clean} targets are run in reverse order of build
1567 Sometimes, such as when running @code{make dist}, you want all possible
1568 subdirectories to be examined. In this case Automake will use
1569 @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to
1570 recurse. This variable will also be used when the user runs
1571 @code{distclean} or @code{maintainer-clean}. It should be set to the
1572 full list of subdirectories in the project. If this macro is not set,
1573 Automake will attempt to set it for you.
1576 @node Alternative, Rebuilding, Top level, Top
1577 @chapter An Alternative Approach to Subdirectories
1579 If you've ever read Peter Miller's excellent paper,
1580 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
1581 Recursive Make Considered Harmful}, the preceding section on the use of
1582 subdirectories will probably come as unwelcome advice. For those who
1583 haven't read the paper, Miller's main thesis is that recursive
1584 @code{make} invocations are both slow and error-prone.
1586 Automake provides sufficient cross-directory support @footnote{We
1587 believe. This work is new and there are probably warts.
1588 @xref{Introduction}, for information on reporting bugs.} to enable you
1589 to write a single @file{Makefile.am} for a complex multi-directory
1593 By default an installable file specified in a subdirectory will have its
1594 directory name stripped before installation. For instance, in this
1595 example, the header file will be installed as
1596 @file{$(includedir)/stdio.h}:
1599 include_HEADERS = inc/stdio.h
1603 @cindex Path stripping, avoiding
1604 @cindex Avoiding path stripping
1606 However, the @samp{nobase_} prefix can be used to circumvent this path
1607 stripping. In this example, the header file will be installed as
1608 @file{$(includedir)/sys/types.h}:
1611 nobase_include_HEADERS = sys/types.h
1615 @node Rebuilding, Programs, Alternative, Top
1616 @chapter Rebuilding Makefiles
1618 Automake generates rules to automatically rebuild @file{Makefile}s,
1619 @file{configure}, and other derived files like @file{Makefile.in}.
1621 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.in}, then
1622 these automatic rebuilding rules are only enabled in maintainer mode.
1624 Sometimes you need to run @code{aclocal} with an argument like @code{-I}
1625 to tell it where to find @file{.m4} files. Since sometimes @code{make}
1626 will automatically run @code{aclocal}, you need a way to specify these
1627 arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this
1628 holds arguments which are passed verbatim to @code{aclocal}. This macro
1629 is only useful in the top-level @file{Makefile.am}.
1630 @cindex ACLOCAL_AMFLAGS
1633 @node Programs, Other objects, Rebuilding, Top
1634 @chapter Building Programs and Libraries
1636 A large part of Automake's functionality is dedicated to making it easy
1637 to build programs and libraries.
1640 * A Program:: Building a program
1641 * A Library:: Building a library
1642 * A Shared Library:: Building a Libtool library
1643 * Program and Library Variables::
1644 Variables controlling program and
1646 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1647 * Program variables:: Variables used when building a program
1648 * Yacc and Lex:: Yacc and Lex support
1650 * Assembly Support::
1651 * Fortran 77 Support::
1653 * Support for Other Languages::
1654 * ANSI:: Automatic de-ANSI-fication
1655 * Dependencies:: Automatic dependency tracking
1656 * EXEEXT:: Support for executable extensions
1660 @node A Program, A Library, Programs, Programs
1661 @section Building a program
1663 @subsection Introductory blathering
1665 @cindex PROGRAMS, bindir
1666 @vindex bin_PROGRAMS
1667 @vindex sbin_PROGRAMS
1668 @vindex libexec_PROGRAMS
1669 @vindex pkglib_PROGRAMS
1670 @vindex noinst_PROGRAMS
1672 In a directory containing source that gets built into a program (as
1673 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
1674 can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
1675 @code{pkglibdir}, or not at all (@samp{noinst}). They can also be built
1676 only for @code{make check}, in which case the prefix is @samp{check}.
1681 bin_PROGRAMS = hello
1684 In this simple case, the resulting @file{Makefile.in} will contain code
1685 to generate a program named @code{hello}.
1687 Associated with each program are several assisting variables which are
1688 named after the program. These variables are all optional, and have
1689 reasonable defaults. Each variable, its use, and default is spelled out
1690 below; we use the ``hello'' example throughout.
1692 The variable @code{hello_SOURCES} is used to specify which source files
1693 get built into an executable:
1696 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1699 This causes each mentioned @samp{.c} file to be compiled into the
1700 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1702 @cindex _SOURCES primary, defined
1703 @cindex SOURCES primary, defined
1704 @cindex Primary variable, SOURCES
1706 If @samp{hello_SOURCES} is not specified, then it defaults to the single
1707 file @file{hello.c}; that is, the default is to compile a single C file
1708 whose base name is the name of the program itself. (This is a terrible
1709 default but we are stuck with it for historical reasons.)
1713 Multiple programs can be built in a single directory. Multiple programs
1714 can share a single source file, which must be listed in each
1715 @samp{_SOURCES} definition.
1717 @cindex Header files in _SOURCES
1718 @cindex _SOURCES and header files
1720 Header files listed in a @samp{_SOURCES} definition will be included in
1721 the distribution but otherwise ignored. In case it isn't obvious, you
1722 should not include the header file generated by @file{configure} in a
1723 @samp{_SOURCES} variable; this file should not be distributed. Lex
1724 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1727 @subsection Conditional compilations
1729 You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
1730 @samp{_SOURCES} variable. The reason for this is a bit hard to explain,
1731 but suffice to say that it simply won't work. Automake will give an
1732 error if you try to do this.
1734 @cindex EXTRA_prog_SOURCES, defined
1736 Automake must know all the source files that could possibly go into a
1737 program, even if not all the files are built in every circumstance.
1738 Any files which are only conditionally built should be listed in the
1739 appropriate @samp{EXTRA_} variable. For instance, if
1740 @file{hello-linux.c} were conditionally included in @code{hello}, the
1741 @file{Makefile.am} would contain:
1744 EXTRA_hello_SOURCES = hello-linux.c
1747 In this case, @file{hello-linux.o} would be added, via a
1748 @file{configure} substitution, to @code{hello_LDADD} in order to cause
1749 it to be built and linked in.
1751 An often simpler way to compile source files conditionally is to use
1752 Automake conditionals. For instance, you could use this construct to
1753 conditionally use @file{hello-linux.c} or @file{hello-generic.c} as the
1754 basis for your program @file{hello}:
1758 hello_SOURCES = hello-linux.c
1760 hello_SOURCES = hello-generic.c
1764 When using conditionals like this you don't need to use the
1765 @samp{EXTRA_} variable, because Automake will examine the contents of
1766 each variable to construct the complete list of source files.
1768 Sometimes it is useful to determine the programs that are to be built at
1769 configure time. For instance, GNU @code{cpio} only builds @code{mt} and
1770 @code{rmt} under special circumstances.
1772 @cindex EXTRA_PROGRAMS, defined
1774 In this case, you must notify Automake of all the programs that can
1775 possibly be built, but at the same time cause the generated
1776 @file{Makefile.in} to use the programs specified by @code{configure}.
1777 This is done by having @code{configure} substitute values into each
1778 @samp{_PROGRAMS} definition, while listing all optionally built programs
1779 in @code{EXTRA_PROGRAMS}.
1780 @vindex EXTRA_PROGRAMS
1782 Of course you can use Automake conditionals to determine the programs to
1785 @subsection Linking the program
1787 If you need to link against libraries that are not found by
1788 @code{configure}, you can use @code{LDADD} to do so. This variable
1789 actually can be used to add any options to the linker command line.
1792 @cindex prog_LDADD, defined
1794 Sometimes, multiple programs are built in one directory but do not share
1795 the same link-time requirements. In this case, you can use the
1796 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1797 program as it appears in some @samp{_PROGRAMS} variable, and usually
1798 written in lowercase) to override the global @code{LDADD}. If this
1799 variable exists for a given program, then that program is not linked
1803 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
1804 linked against the library @file{libcpio.a}. However, @code{rmt} is
1805 built in the same directory, and has no such link requirement. Also,
1806 @code{mt} and @code{rmt} are only built on certain architectures. Here
1807 is what cpio's @file{src/Makefile.am} looks like (abridged):
1810 bin_PROGRAMS = cpio pax @@MT@@
1811 libexec_PROGRAMS = @@RMT@@
1812 EXTRA_PROGRAMS = mt rmt
1814 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1817 cpio_SOURCES = @dots{}
1818 pax_SOURCES = @dots{}
1819 mt_SOURCES = @dots{}
1820 rmt_SOURCES = @dots{}
1823 @cindex _LDFLAGS, defined
1825 @samp{@var{prog}_LDADD} is inappropriate for passing program-specific
1826 linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
1827 @samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
1831 @cindex _DEPENDENCIES, defined
1833 It is also occasionally useful to have a program depend on some other
1834 target which is not actually part of that program. This can be done
1835 using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
1836 on the contents of such a variable, but no further interpretation is
1839 If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
1840 Automake. The automatically-assigned value is the contents of
1841 @samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
1842 @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
1843 configure substitutions that are left in are only @samp{@@LIBOBJS@@} and
1844 @samp{@@ALLOCA@@}; these are left because it is known that they will not
1845 cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
1849 @node A Library, A Shared Library, A Program, Programs
1850 @section Building a library
1852 @cindex _LIBRARIES primary, defined
1853 @cindex LIBRARIES primary, defined
1854 @cindex Primary variable, LIBRARIES
1856 @vindex lib_LIBRARIES
1857 @vindex pkglib_LIBRARIES
1858 @vindex noinst_LIBRARIES
1860 Building a library is much like building a program. In this case, the
1861 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
1862 @code{libdir} or @code{pkglibdir}.
1864 @xref{A Shared Library}, for information on how to build shared
1865 libraries using Libtool and the @samp{LTLIBRARIES} primary.
1867 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
1868 For instance to create a library named @file{libcpio.a}, but not install
1869 it, you would write:
1872 noinst_LIBRARIES = libcpio.a
1875 The sources that go into a library are determined exactly as they are
1876 for programs, via the @samp{_SOURCES} variables. Note that the library
1877 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
1878 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
1879 not @samp{liblob.a_SOURCES}.
1881 @cindex _LIBADD primary, defined
1882 @cindex LIBADD primary, defined
1883 @cindex Primary variable, LIBADD
1885 Extra objects can be added to a library using the
1886 @samp{@var{library}_LIBADD} variable. This should be used for objects
1887 determined by @code{configure}. Again from @code{cpio}:
1892 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
1895 In addition, sources for extra objects that will not exist until
1896 configure-time must be added to the @code{BUILT_SOURCES} variable
1900 @node A Shared Library, Program and Library Variables, A Library, Programs
1901 @section Building a Shared Library
1903 @cindex Shared libraries, support for
1905 Building shared libraries is a relatively complex matter. For this
1906 reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
1907 Libtool Manual}) was created to help build shared libraries in a
1908 platform-independent way.
1910 @cindex _LTLIBRARIES primary, defined
1911 @cindex LTLIBRARIES primary, defined
1912 @cindex Primary variable, LTLIBRARIES
1913 @cindex Example of shared libraries
1915 @cindex suffix .la, defined
1917 Automake uses Libtool to build libraries declared with the
1918 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
1919 of shared libraries to build. For instance, to create a library named
1920 @file{libgettext.a} and its corresponding shared libraries, and install
1921 them in @samp{libdir}, write:
1924 lib_LTLIBRARIES = libgettext.la
1927 @vindex lib_LTLIBRARIES
1928 @vindex pkglib_LTLIBRARIES
1929 @vindex noinst_LTLIBRARIES
1930 @vindex check_LTLIBRARIES
1932 @cindex check_LTLIBRARIES, not allowed
1934 Note that shared libraries @emph{must} be installed in order to work
1935 properly, so @code{check_LTLIBRARIES} is not allowed. However,
1936 @code{noinst_LTLIBRARIES} is allowed. This feature should be used for
1937 libtool ``convenience libraries''.
1939 @cindex suffix .lo, defined
1941 For each library, the @samp{@var{library}_LIBADD} variable contains the
1942 names of extra libtool objects (@file{.lo} files) to add to the shared
1943 library. The @samp{@var{library}_LDFLAGS} variable contains any
1944 additional libtool flags, such as @samp{-version-info} or
1947 @cindex @@LTLIBOBJS@@, special handling
1949 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
1950 library must use @code{@@LTLIBOBJS@@}. This is required because the
1951 object files that libtool operates on do not necessarily end in
1952 @file{.o}. The libtool manual contains more details on this topic.
1954 For libraries installed in some directory, Automake will automatically
1955 supply the appropriate @samp{-rpath} option. However, for libraries
1956 determined at configure time (and thus mentioned in
1957 @code{EXTRA_LTLIBRARIES}), Automake does not know the eventual
1958 installation directory; for such libraries you must add the
1959 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
1962 Ordinarily, Automake requires that a shared library's name start with
1963 @samp{lib}. However, if you are building a dynamically loadable module
1964 then you might wish to use a "nonstandard" name. In this case, put
1965 @code{-module} into the @samp{_LDFLAGS} variable.
1967 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
1968 libtool, The Libtool Manual}, for more information.
1971 @node Program and Library Variables, LIBOBJS, A Shared Library, Programs
1972 @section Program and Library Variables
1974 Associated with each program are a collection of variables which can be
1975 used to modify how that program is built. There is a similar list of
1976 such variables for each library. The canonical name of the program (or
1977 library) is used as a base for naming these variables.
1979 In the list below, we use the name ``maude'' to refer to the program or
1980 library. In your @file{Makefile.am} you would replace this with the
1981 canonical name of your program. This list also refers to ``maude'' as a
1982 program, but in general the same rules apply for both static and dynamic
1983 libraries; the documentation below notes situations where programs and
1988 This variable, if it exists, lists all the source files which are
1989 compiled to build the program. These files are added to the
1990 distribution by default. When building the program, Automake will cause
1991 each source file to be compiled to a single @file{.o} file (or
1992 @file{.lo} when using libtool). Normally these object files are named
1993 after the source file, but other factors can change this. If a file in
1994 the @samp{_SOURCES} variable has an unrecognized extension, Automake
1995 will do one of two things with it. If a suffix rule exists for turning
1996 files with the unrecognized extension into @file{.o} files, then
1997 automake will treat this file as it will any other source file
1998 (@pxref{Support for Other Languages}). Otherwise, the file will be
1999 ignored as though it were a header file.
2001 The prefixes @samp{dist_} and @samp{nodist_} can be used to control
2002 whether files listed in a @samp{_SOURCES} variable are distributed.
2003 @samp{dist_} is redundant, as sources are distributed by default, but it
2004 can be specified for clarity if desired.
2006 It is possible to have both @samp{dist_} and @samp{nodist_} variants of
2007 a given @samp{_SOURCES} variable at once; this lets you easily
2008 distribute some files and not others, for instance:
2011 nodist_maude_SOURCES = nodist.c
2012 dist_maude_SOURCES = dist-me.c
2015 By default the output file (on Unix systems, the @file{.o} file) will be
2016 put into the current build directory. However, if the option
2017 @code{subdir-objects} is in effect in the current directory then the
2018 @file{.o} file will be put into the subdirectory named after the source
2019 file. For instance, with @code{subdir-objects} enabled,
2020 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
2021 people prefer this mode of operation. You can specify
2022 @code{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
2023 @cindex Subdirectory, objects in
2024 @cindex Objects in subdirectory
2027 @item EXTRA_maude_SOURCES
2028 Automake needs to know the list of files you intend to compile
2029 @emph{statically}. For one thing, this is the only way Automake has of
2030 knowing what sort of language support a given @file{Makefile.in}
2031 requires. @footnote{There are other, more obscure reasons reasons for
2032 this limitation as well.} This means that, for example, you can't put a
2033 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
2034 variable. If you intend to conditionally compile source files and use
2035 @file{configure} to substitute the appropriate object names into, e.g.,
2036 @samp{_LDADD} (see below), then you should list the corresponding source
2037 files in the @samp{EXTRA_} variable.
2039 This variable also supports @samp{dist_} and @samp{nodist_} prefixes,
2040 e.g., @samp{nodist_EXTRA_maude_SOURCES}.
2043 A static library is created by default by invoking @code{$(AR) cru}
2044 followed by the name of the library and then the objects being put into
2045 the library. You can override this by setting the @samp{_AR} variable.
2046 This is usually used with C++; some C++ compilers require a special
2047 invocation in order to instantiate all the templates which should go
2048 into a library. For instance, the SGI C++ compiler likes this macro set
2051 libmaude_a_AR = $(CXX) -ar -o
2055 Extra objects can be added to a static library using the @samp{_LIBADD}
2056 variable. This should be used for objects determined by
2057 @code{configure}. Note that @samp{_LIBADD} is not used for shared
2058 libraries; there you must use @samp{_LDADD}.
2061 Extra objects can be added to a shared library or a program by listing
2062 them in the @samp{_LDADD} variable. This should be used for objects
2063 determined by @code{configure}.
2065 @samp{_LDADD} is inappropriate for passing program-specific linker flags
2066 (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen}).
2067 Use the @samp{_LDFLAGS} variable for this purpose.
2069 For instance, if your @file{configure.in} uses @code{AC_PATH_XTRA}, you
2070 could link your program against the X libraries like so:
2073 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
2077 This variable is used to pass extra flags to the link step of a program
2078 or a shared library.
2081 You can override the linker on a per-program basis. By default the
2082 linker is chosen according to the languages used by the program. For
2083 instance, a program that includes C++ source code would use the C++
2084 compiler to link. The @samp{_LINK} variable must hold the name of a
2085 command which can be passed all the @file{.o} file names as arguments.
2086 Note that the name of the underlying program is @emph{not} passed to
2087 @samp{_LINK}; typically one uses @samp{$@@}:
2090 maude_LINK = $(CCLD) -magic -o $@@
2094 Automake allows you to set compilation flags on a per-program (or
2095 per-library) basis. A single source file can be included in several
2096 programs, and it will potentially be compiled with different flags for
2097 each program. This works for any language directly supported by
2098 Automake. The flags are @samp{_CFLAGS}, @samp{_CXXFLAGS},
2099 @samp{_OBJCFLAGS}, @samp{_YFLAGS}, @samp{_ASFLAGS}, @samp{_FFLAGS},
2100 @samp{_RFLAGS}, and @samp{_GCJFLAGS}.
2102 When using a per-program compilation flag, Automake will choose a
2103 different name for the intermediate object files. Ordinarily a file
2104 like @file{sample.c} will be compiled to produce @file{sample.o}.
2105 However, if the program's @samp{_CFLAGS} variable is set, then the
2106 object file will be named, for instance, @file{maude-sample.o}.
2108 In compilations with per-program flags, the ordinary @samp{AM_} form of
2109 the flags variable is @emph{not} automatically included in the
2110 compilation (however, the user form of the variable @emph{is} included).
2111 So for instance, if you want the hypothetical @file{maude} compilations
2112 to also use the value of @samp{AM_CFLAGS}, you would need to write:
2115 maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
2118 @item maude_DEPENDENCIES
2119 It is also occasionally useful to have a program depend on some other
2120 target which is not actually part of that program. This can be done
2121 using the @samp{_DEPENDENCIES} variable. Each program depends on the
2122 contents of such a variable, but no further interpretation is done.
2124 If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake.
2125 The automatically-assigned value is the contents of @samp{_LDADD}, with
2126 most configure substitutions, @samp{-l}, @samp{-L}, @samp{-dlopen} and
2127 @samp{-dlpreopen} options removed. The configure substitutions that are
2128 left in are only @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are
2129 left because it is known that they will not cause an invalid value for
2130 @samp{_DEPENDENCIES} to be generated.
2132 @item maude_SHORTNAME
2133 On some platforms the allowable file names are very short. In order to
2134 support these systems and per-program compilation flags at the same
2135 time, Automake allows you to set a ``short name'' which will influence
2136 how intermediate object files are named. For instance, if you set
2137 @samp{maude_SHORTNAME} to @samp{m}, then in the above per-program
2138 compilation flag example the object file would be named
2139 @file{m-sample.o} rather than @file{maude-sample.o}. This facility is
2140 rarely needed in practice, and we recommend avoiding it until you find
2145 @node LIBOBJS, Program variables, Program and Library Variables, Programs
2146 @section Special handling for LIBOBJS and ALLOCA
2148 @cindex @@LIBOBJS@@, special handling
2149 @cindex @@ALLOCA@@, special handling
2151 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
2152 @code{@@ALLOCA@@}, and uses this information, plus the list of
2153 @code{LIBOBJS} files derived from @file{configure.in} to automatically
2154 include the appropriate source files in the distribution (@pxref{Dist}).
2155 These source files are also automatically handled in the
2156 dependency-tracking scheme; see @xref{Dependencies}.
2158 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
2159 @samp{_LDADD} or @samp{_LIBADD} variable.
2162 @node Program variables, Yacc and Lex, LIBOBJS, Programs
2163 @section Variables used when building a program
2165 Occasionally it is useful to know which @file{Makefile} variables
2166 Automake uses for compilations; for instance you might need to do your
2167 own compilation in some special cases.
2169 Some variables are inherited from Autoconf; these are @code{CC},
2170 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
2174 There are some additional variables which Automake itself defines:
2178 The contents of this macro are passed to every compilation which invokes
2179 the C preprocessor; it is a list of arguments to the preprocessor. For
2180 instance, @samp{-I} and @samp{-D} options should be listed here.
2182 Automake already provides some @samp{-I} options automatically. In
2183 particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I}
2184 pointing to the directory holding @file{config.h} (if you've used
2185 @code{AC_CONFIG_HEADER} or @code{AM_CONFIG_HEADER}). You can disable
2186 the default @samp{-I} options using the @samp{nostdinc} option.
2189 This does the same job as @samp{AM_CPPFLAGS}. It is an older name for
2190 the same functionality. This macro is deprecated; we suggest using
2191 @samp{AM_CPPFLAGS} instead.
2194 This is the variable which the @file{Makefile.am} author can use to pass
2195 in additional C compiler flags. It is more fully documented elsewhere.
2196 In some situations, this is not used, in preference to the
2197 per-executable (or per-library) @code{CFLAGS}.
2200 This is the command used to actually compile a C source file. The
2201 filename is appended to form the complete command line.
2204 This is the command used to actually link a C program. It already
2205 includes @samp{-o $@@} and the usual variable references (for instance,
2206 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
2207 and libraries to link in.
2211 @node Yacc and Lex, C++ Support, Program variables, Programs
2212 @section Yacc and Lex support
2214 Automake has somewhat idiosyncratic support for Yacc and Lex.
2216 Automake assumes that the @file{.c} file generated by @code{yacc} (or
2217 @code{lex}) should be named using the basename of the input file. That
2218 is, for a yacc source file @file{foo.y}, Automake will cause the
2219 intermediate file to be named @file{foo.c} (as opposed to
2220 @file{y.tab.c}, which is more traditional).
2222 The extension of a yacc source file is used to determine the extension
2223 of the resulting @samp{C} or @samp{C++} file. Files with the extension
2224 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
2225 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
2228 Likewise, lex source files can be used to generate @samp{C} or
2229 @samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
2230 @samp{.lxx} are recognized.
2232 You should never explicitly mention the intermediate (@samp{C} or
2233 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
2236 The intermediate files generated by @code{yacc} (or @code{lex}) will be
2237 included in any distribution that is made. That way the user doesn't
2238 need to have @code{yacc} or @code{lex}.
2240 If a @code{yacc} source file is seen, then your @file{configure.in} must
2241 define the variable @samp{YACC}. This is most easily done by invoking
2242 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
2243 Program Checks, autoconf, The Autoconf Manual}).
2245 When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
2246 @samp{AM_YFLAGS}. The former is a user variable and the latter is
2247 intended for the @file{Makefile.am} author.
2249 Similarly, if a @code{lex} source file is seen, then your
2250 @file{configure.in} must define the variable @samp{LEX}. You can use
2251 @samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
2252 Program Checks, autoconf, The Autoconf Manual}), but using
2253 @code{AM_PROG_LEX} macro (@pxref{Macros}) is recommended.
2255 When @code{lex} is invoked, it is passed @samp{LFLAGS} and
2256 @samp{AM_LFLAGS}. The former is a user variable and the latter is
2257 intended for the @file{Makefile.am} author.
2262 @cindex yacc, multiple parsers
2263 @cindex Multiple yacc parsers
2264 @cindex Multiple lex lexers
2265 @cindex lex, multiple lexers
2268 Automake makes it possible to include multiple @code{yacc} (or
2269 @code{lex}) source files in a single program. Automake uses a small
2270 program called @code{ylwrap} to run @code{yacc} (or @code{lex}) in a
2271 subdirectory. This is necessary because yacc's output filename is
2272 fixed, and a parallel make could conceivably invoke more than one
2273 instance of @code{yacc} simultaneously. The @code{ylwrap} program is
2274 distributed with Automake. It should appear in the directory specified
2275 by @samp{AC_CONFIG_AUX_DIR} (@pxref{Input, , Finding `configure' Input,
2276 autoconf, The Autoconf Manual}), or the current directory if that macro
2277 is not used in @file{configure.in}.
2279 For @code{yacc}, simply managing locking is insufficient. The output of
2280 @code{yacc} always uses the same symbol names internally, so it isn't
2281 possible to link two @code{yacc} parsers into the same executable.
2283 We recommend using the following renaming hack used in @code{gdb}:
2285 #define yymaxdepth c_maxdepth
2286 #define yyparse c_parse
2288 #define yyerror c_error
2289 #define yylval c_lval
2290 #define yychar c_char
2291 #define yydebug c_debug
2292 #define yypact c_pact
2299 #define yyexca c_exca
2300 #define yyerrflag c_errflag
2301 #define yynerrs c_nerrs
2305 #define yy_yys c_yys
2306 #define yystate c_state
2309 #define yy_yyv c_yyv
2311 #define yylloc c_lloc
2312 #define yyreds c_reds
2313 #define yytoks c_toks
2314 #define yylhs c_yylhs
2315 #define yylen c_yylen
2316 #define yydefred c_yydefred
2317 #define yydgoto c_yydgoto
2318 #define yysindex c_yysindex
2319 #define yyrindex c_yyrindex
2320 #define yygindex c_yygindex
2321 #define yytable c_yytable
2322 #define yycheck c_yycheck
2323 #define yyname c_yyname
2324 #define yyrule c_yyrule
2327 For each define, replace the @samp{c_} prefix with whatever you like.
2328 These defines work for @code{bison}, @code{byacc}, and traditional
2329 @code{yacc}s. If you find a parser generator that uses a symbol not
2330 covered here, please report the new name so it can be added to the list.
2333 @node C++ Support, Assembly Support, Yacc and Lex, Programs
2334 @section C++ Support
2337 @cindex Support for C++
2339 Automake includes full support for C++.
2341 Any package including C++ code must define the output variable
2342 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
2343 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
2344 Program Checks, autoconf, The Autoconf Manual}).
2346 A few additional variables are defined when a C++ source file is seen:
2350 The name of the C++ compiler.
2353 Any flags to pass to the C++ compiler.
2356 The maintainer's variant of @code{CXXFLAGS}.
2359 The command used to actually compile a C++ source file. The file name
2360 is appended to form the complete command line.
2363 The command used to actually link a C++ program.
2367 @node Assembly Support, Fortran 77 Support, C++ Support, Programs
2368 @section Assembly Support
2370 Automake includes some support for assembly code.
2372 The variable @code{AS} holds the name of the compiler used to build
2373 assembly code. This compiler must work a bit like a C compiler; in
2374 particular it must accept @samp{-c} and @samp{-o}. The value of
2375 @code{ASFLAGS} is passed to the compilation.
2379 You are required to set @code{AS} and @code{ASFLAGS} via
2380 @file{configure.in}. The autoconf macro @code{AM_PROG_AS} will do this
2381 for you. Unless they are already set, it simply sets @code{AS} to the C
2382 compiler and @code{ASFLAGS} to the C compiler flags.
2385 @node Fortran 77 Support, Java Support, Assembly Support, Programs
2386 @comment node-name, next, previous, up
2387 @section Fortran 77 Support
2389 @cindex Fortran 77 support
2390 @cindex Support for Fortran 77
2392 Automake includes full support for Fortran 77.
2394 Any package including Fortran 77 code must define the output variable
2395 @samp{F77} in @file{configure.in}; the simplest way to do this is to use
2396 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
2397 Program Checks, autoconf, The Autoconf Manual}). @xref{Fortran 77 and
2400 A few additional variables are defined when a Fortran 77 source file is
2406 The name of the Fortran 77 compiler.
2409 Any flags to pass to the Fortran 77 compiler.
2412 The maintainer's variant of @code{FFLAGS}.
2415 Any flags to pass to the Ratfor compiler.
2418 The maintainer's variant of @code{RFLAGS}.
2421 The command used to actually compile a Fortran 77 source file. The file
2422 name is appended to form the complete command line.
2425 The command used to actually link a pure Fortran 77 program or shared
2430 Automake can handle preprocessing Fortran 77 and Ratfor source files in
2431 addition to compiling them@footnote{Much, if not most, of the
2432 information in the following sections pertaining to preprocessing
2433 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
2434 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
2435 also contains some support for creating programs and shared libraries
2436 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
2437 Fortran 77 With C and C++}).
2439 These issues are covered in the following sections.
2442 * Preprocessing Fortran 77::
2443 * Compiling Fortran 77 Files::
2444 * Mixing Fortran 77 With C and C++::
2445 * Fortran 77 and Autoconf::
2449 @node Preprocessing Fortran 77, Compiling Fortran 77 Files, Fortran 77 Support, Fortran 77 Support
2450 @comment node-name, next, previous, up
2451 @subsection Preprocessing Fortran 77
2453 @cindex Preprocessing Fortran 77
2454 @cindex Fortran 77, Preprocessing
2455 @cindex Ratfor programs
2457 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
2458 rule runs just the preprocessor to convert a preprocessable Fortran 77
2459 or Ratfor source file into a strict Fortran 77 source file. The precise
2460 command used is as follows:
2465 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2468 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2473 @node Compiling Fortran 77 Files, Mixing Fortran 77 With C and C++, Preprocessing Fortran 77, Fortran 77 Support
2474 @comment node-name, next, previous, up
2475 @subsection Compiling Fortran 77 Files
2477 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
2478 @file{N.r} by running the Fortran 77 compiler. The precise command used
2484 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
2487 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2490 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2495 @node Mixing Fortran 77 With C and C++, Fortran 77 and Autoconf, Compiling Fortran 77 Files, Fortran 77 Support
2496 @comment node-name, next, previous, up
2497 @subsection Mixing Fortran 77 With C and C++
2499 @cindex Fortran 77, mixing with C and C++
2500 @cindex Mixing Fortran 77 with C and C++
2501 @cindex Linking Fortran 77 with C and C++
2503 @cindex Mixing Fortran 77 with C and/or C++
2505 Automake currently provides @emph{limited} support for creating programs
2506 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
2507 However, there are many other issues related to mixing Fortran 77 with
2508 other languages that are @emph{not} (currently) handled by Automake, but
2509 that are handled by other packages@footnote{For example,
2510 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
2511 addresses all of these inter-language issues, and runs under nearly all
2512 Fortran 77, C and C++ compilers on nearly all platforms. However,
2513 @code{cfortran} is not yet Free Software, but it will be in the next
2517 Automake can help in two ways:
2521 Automatic selection of the linker depending on which combinations of
2525 Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
2526 @samp{-l}) to pass to the automatically selected linker in order to link
2527 in the appropriate Fortran 77 intrinsic and run-time libraries.
2529 @cindex FLIBS, defined
2530 These extra Fortran 77 linker flags are supplied in the output variable
2531 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
2532 supplied with newer versions of Autoconf (Autoconf version 2.13 and
2533 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
2537 If Automake detects that a program or shared library (as mentioned in
2538 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
2539 code that is a mixture of Fortran 77 and C and/or C++, then it requires
2540 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
2541 @file{configure.in}, and that either @code{$(FLIBS)} or @code{@@FLIBS@@}
2542 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
2543 (for shared libraries) variables. It is the responsibility of the
2544 person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
2545 or @code{@@FLIBS@@} appears in the appropriate @code{_LDADD} or
2546 @code{_LIBADD} variable.
2548 @cindex Mixed language example
2549 @cindex Example, mixed language
2551 For example, consider the following @file{Makefile.am}:
2555 foo_SOURCES = main.cc foo.f
2556 foo_LDADD = libfoo.la @@FLIBS@@
2558 pkglib_LTLIBRARIES = libfoo.la
2559 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
2560 libfoo_la_LIBADD = $(FLIBS)
2563 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
2564 is mentioned in @file{configure.in}. Also, if @code{@@FLIBS@@} hadn't
2565 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
2566 Automake would have issued a warning.
2571 * How the Linker is Chosen::
2574 @node How the Linker is Chosen, , Mixing Fortran 77 With C and C++, Mixing Fortran 77 With C and C++
2575 @comment node-name, next, previous, up
2576 @subsubsection How the Linker is Chosen
2578 @cindex Automatic linker selection
2579 @cindex Selecting the linker automatically
2581 The following diagram demonstrates under what conditions a particular
2582 linker is chosen by Automake.
2584 For example, if Fortran 77, C and C++ source code were to be compiled
2585 into a program, then the C++ linker will be used. In this case, if the
2586 C or Fortran 77 linkers required any special libraries that weren't
2587 included by the C++ linker, then they must be manually added to an
2588 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
2594 code \ C C++ Fortran
2595 ----------------- +---------+---------+---------+
2599 +---------+---------+---------+
2603 +---------+---------+---------+
2607 +---------+---------+---------+
2611 +---------+---------+---------+
2613 C + Fortran | | | x |
2615 +---------+---------+---------+
2617 C++ + Fortran | | x | |
2619 +---------+---------+---------+
2621 C + C++ + Fortran | | x | |
2623 +---------+---------+---------+
2627 @node Fortran 77 and Autoconf, , Mixing Fortran 77 With C and C++, Fortran 77 Support
2628 @comment node-name, next, previous, up
2629 @subsection Fortran 77 and Autoconf
2631 The current Automake support for Fortran 77 requires a recent enough
2632 version of Autoconf that also includes support for Fortran 77. Full
2633 Fortran 77 support was added to Autoconf 2.13, so you will want to use
2634 that version of Autoconf or later.
2637 @node Java Support, Support for Other Languages, Fortran 77 Support, Programs
2638 @comment node-name, next, previous, up
2639 @section Java Support
2641 @cindex Java support
2642 @cindex Support for Java
2644 Automake includes support for compiled Java, using @code{gcj}, the Java
2645 front end to the GNU Compiler Collection.
2647 Any package including Java code to be compiled must define the output
2648 variable @samp{GCJ} in @file{configure.in}; the variable @samp{GCJFLAGS}
2649 must also be defined somehow (either in @file{configure.in} or
2650 @file{Makefile.am}). The simplest way to do this is to use the
2651 @code{AM_PROG_GCJ} macro.
2655 By default, programs including Java source files are linked with
2658 As always, the contents of @samp{AM_GCJFLAGS} are passed to every
2659 compilation invoking @code{gcj} (in its role as an ahead-of-time
2660 compiler -- when invoking it to create @file{.class} files,
2661 @samp{AM_JAVACFLAGS} is used instead). If it is necessary to pass
2662 options to @code{gcj} from @file{Makefile.am}, this macro, and not the
2663 user macro @samp{GCJFLAGS}, should be used.
2667 @code{gcj} can be used to compile @file{.java}, @file{.class},
2668 @file{.zip}, or @file{.jar} files.
2671 @node Support for Other Languages, ANSI, Java Support, Programs
2672 @comment node-name, next, previous, up
2673 @section Support for Other Languages
2675 Automake currently only includes full support for C, C++ (@pxref{C++
2676 Support}), Fortran 77 (@pxref{Fortran 77 Support}), and Java
2677 (@pxref{Java Support}). There is only rudimentary support for other
2678 languages, support for which will be improved based on user demand.
2680 Some limited support for adding your own languages is available via the
2681 suffix rule handling; see @ref{Suffixes}.
2684 @node ANSI, Dependencies, Support for Other Languages, Programs
2685 @section Automatic de-ANSI-fication
2687 @cindex de-ANSI-fication, defined
2689 Although the GNU standards allow the use of ANSI C, this can have the
2690 effect of limiting portability of a package to some older compilers
2691 (notably the SunOS C compiler).
2693 Automake allows you to work around this problem on such machines by
2694 @dfn{de-ANSI-fying} each source file before the actual compilation takes
2697 @vindex AUTOMAKE_OPTIONS
2700 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
2701 (@pxref{Options}) contains the option @code{ansi2knr} then code to
2702 handle de-ANSI-fication is inserted into the generated
2705 This causes each C source file in the directory to be treated as ANSI C.
2706 If an ANSI C compiler is available, it is used. If no ANSI C compiler
2707 is available, the @code{ansi2knr} program is used to convert the source
2708 files into K&R C, which is then compiled.
2710 The @code{ansi2knr} program is simple-minded. It assumes the source
2711 code will be formatted in a particular way; see the @code{ansi2knr} man
2714 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
2715 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
2716 these files are distributed with Automake. Also, the package
2717 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}
2719 @cvindex AM_C_PROTOTYPES
2721 Automake also handles finding the @code{ansi2knr} support files in some
2722 other directory in the current package. This is done by prepending the
2723 relative path to the appropriate directory to the @code{ansi2knr}
2724 option. For instance, suppose the package has ANSI C code in the
2725 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
2726 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
2727 @file{src/Makefile.am}:
2730 AUTOMAKE_OPTIONS = ../lib/ansi2knr
2733 If no directory prefix is given, the files are assumed to be in the
2736 Files mentioned in @code{LIBOBJS} which need de-ANSI-fication will not
2737 be automatically handled. That's because @code{configure} will generate
2738 an object name like @file{regex.o}, while @code{make} will be looking
2739 for @file{regex_.o} (when de-ANSI-fying). Eventually this problem will
2740 be fixed via @code{autoconf} magic, but for now you must put this code
2741 into your @file{configure.in}, just before the @code{AC_OUTPUT} call:
2744 # This is necessary so that .o files in LIBOBJS are also built via
2745 # the ANSI2KNR-filtering rules.
2746 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
2749 Note that automatic de-ANSI-fication will not work when the package is
2750 being built for a different host architecture. That is because automake
2751 currently has no way to build @code{ansi2knr} for the build machine.
2754 @node Dependencies, EXEEXT, ANSI, Programs
2755 @section Automatic dependency tracking
2757 As a developer it is often painful to continually update the
2758 @file{Makefile.in} whenever the include-file dependencies change in a
2759 project. Automake supplies a way to automatically track dependency
2762 @cindex Dependency tracking
2763 @cindex Automatic dependency tracking
2765 Automake always uses complete dependencies for a compilation, including
2766 system headers. Automake's model is that dependency computation should
2767 be a side effect of the build. To this end, dependencies are computed
2768 by running all compilations through a special wrapper program called
2769 @code{depcomp}. @code{depcomp} understands how to coax many different C
2770 and C++ compilers into generating dependency information in the format
2771 it requires. @code{automake -a} will install @code{depcomp} into your
2772 source tree for you. If @code{depcomp} can't figure out how to properly
2773 invoke your compiler, dependency tracking will simply be disabled for
2778 Experience with earlier versions of Automake @footnote{See
2779 @uref{http://sources.redhat.com/automake/dependencies.html} for more
2780 information on the history and experiences with automatic dependency
2781 tracking in Automake} taught us that it is not reliable to generate
2782 dependencies only on the maintainer's system, as configurations vary too
2783 much. So instead Automake implements dependency tracking at build time.
2785 Automatic dependency tracking can be suppressed by putting
2786 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}. Or, you
2787 can invoke @code{automake} with the @code{-i} option. Dependency
2788 tracking is enabled by default.
2790 @vindex AUTOMAKE_OPTIONS
2791 @opindex no-dependencies
2793 The person building your package also can choose to disable dependency
2794 tracking by configuring with @code{--disable-dependency-tracking}.
2796 @cindex Disabling dependency tracking
2797 @cindex Dependency tracking, disabling
2800 @node EXEEXT, , Dependencies, Programs
2801 @section Support for executable extensions
2803 @cindex Executable extension
2804 @cindex Extension, executable
2807 On some platforms, such as Windows, executables are expected to have an
2808 extension such as @samp{.exe}. On these platforms, some compilers (GCC
2809 among them) will automatically generate @file{foo.exe} when asked to
2810 generate @file{foo}.
2812 Automake provides mostly-transparent support for this. Unfortunately
2813 the support isn't completely transparent; if you want your package to
2814 support these platforms then you must assist.
2816 One thing you must be aware of is that, internally, Automake rewrites
2817 something like this:
2820 bin_PROGRAMS = liver
2826 bin_PROGRAMS = liver$(EXEEXT)
2829 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
2830 extension. @code{EXEEXT}
2832 However, Automake cannot apply this rewriting to @code{configure}
2833 substitutions. This means that if you are conditionally building a
2834 program using such a substitution, then your @file{configure.in} must
2835 take care to add @samp{$(EXEEXT)} when constructing the output variable.
2837 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
2838 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
2839 automatically if you configure a compiler (say, through
2842 Sometimes maintainers like to write an explicit link rule for their
2843 program. Without executable extension support, this is easy---you
2844 simply write a target with the same name as the program. However, when
2845 executable extension support is enabled, you must instead add the
2846 @samp{$(EXEEXT)} suffix.
2848 Unfortunately, due to the change in Autoconf 2.50, this means you must
2849 always add this extension. However, this is a problem for maintainers
2850 who know their package will never run on a platform that has executable
2851 extensions. For those maintainers, the @code{no-exeext} option
2852 (@pxref{Options}) will disable this feature. This works in a fairly
2853 ugly way; if @code{no-exeext} is seen, then the presence of a target
2854 named @code{foo} in @file{Makefile.am} will override an
2855 automake-generated target of the form @code{foo$(EXEEXT)}. Without the
2856 @code{no-exeext} option, this use will give an error.
2859 @node Other objects, Other GNU Tools, Programs, Top
2860 @chapter Other Derived Objects
2862 Automake can handle derived objects which are not C programs. Sometimes
2863 the support for actually building such objects must be explicitly
2864 supplied, but Automake will still automatically handle installation and
2868 * Scripts:: Executable scripts
2869 * Headers:: Header files
2870 * Data:: Architecture-independent data files
2871 * Sources:: Derived sources
2875 @node Scripts, Headers, Other objects, Other objects
2876 @section Executable Scripts
2878 @cindex _SCRIPTS primary, defined
2879 @cindex SCRIPTS primary, defined
2880 @cindex Primary variable, SCRIPTS
2882 It is possible to define and install programs which are scripts. Such
2883 programs are listed using the @samp{SCRIPTS} primary name. Automake
2884 doesn't define any dependencies for scripts; the @file{Makefile.am}
2885 should include the appropriate rules.
2888 Automake does not assume that scripts are derived objects; such objects
2889 must be deleted by hand (@pxref{Clean}).
2891 The @code{automake} program itself is a Perl script that is generated at
2892 configure time from @file{automake.in}. Here is how this is handled:
2895 bin_SCRIPTS = automake
2898 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
2899 for it is automatically generated.
2901 @cindex SCRIPTS, installation directories
2902 @cindex Installing scripts
2905 @vindex sbin_SCRIPTS
2906 @vindex libexec_SCRIPTS
2907 @vindex pkgdata_SCRIPTS
2908 @vindex noinst_SCRIPTS
2910 Script objects can be installed in @code{bindir}, @code{sbindir},
2911 @code{libexecdir}, or @code{pkgdatadir}.
2914 @node Headers, Data, Scripts, Other objects
2915 @section Header files
2917 @cindex _HEADERS primary, defined
2918 @cindex HEADERS primary, defined
2919 @cindex Primary variable, HEADERS
2921 @vindex noinst_HEADERS
2923 Header files are specified by the @samp{HEADERS} family of variables.
2924 Generally header files are not installed, so the @code{noinst_HEADERS}
2925 variable will be the most used. @footnote{However, for the case of a
2926 non-installed header file that is actually used by a particular program,
2927 we recommend listing it in the program's @samp{_SOURCES} variable
2928 instead of in @code{noinst_HEADERS}. We believe this is more clear.}
2931 All header files must be listed somewhere; missing ones will not appear
2932 in the distribution. Often it is clearest to list uninstalled headers
2933 with the rest of the sources for a program. @xref{A Program}. Headers
2934 listed in a @samp{_SOURCES} variable need not be listed in any
2935 @samp{_HEADERS} variable.
2937 @cindex HEADERS, installation directories
2938 @cindex Installing headers
2940 @vindex include_HEADERS
2941 @vindex oldinclude_HEADERS
2942 @vindex pkginclude_HEADERS
2944 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
2945 @code{pkgincludedir}.
2948 @node Data, Sources, Headers, Other objects
2949 @section Architecture-independent data files
2951 @cindex _DATA primary, defined
2952 @cindex DATA primary, defined
2953 @cindex Primary variable, DATA
2955 Automake supports the installation of miscellaneous data files using the
2956 @samp{DATA} family of variables.
2960 @vindex sysconf_DATA
2961 @vindex sharedstate_DATA
2962 @vindex localstate_DATA
2963 @vindex pkgdata_DATA
2965 Such data can be installed in the directories @code{datadir},
2966 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
2969 By default, data files are @emph{not} included in a distribution. Of
2970 course, you can use the @samp{dist_} prefix to change this on a
2973 Here is how Automake installs its auxiliary data files:
2976 pkgdata_DATA = clean-kr.am clean.am @dots{}
2980 @node Sources, , Data, Other objects
2981 @section Built sources
2983 @cindex BUILT_SOURCES, defined
2985 Occasionally a file which would otherwise be called @samp{source}
2986 (e.g. a C @samp{.h} file) is actually derived from some other file.
2987 Such files should be listed in the @code{BUILT_SOURCES} variable.
2988 @vindex BUILT_SOURCES
2990 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
2991 must be created early in the build process can be listed in this
2994 A source file listed in @code{BUILT_SOURCES} is created before the other
2995 @code{all} targets are made. However, such a source file is not
2996 compiled unless explicitly requested by mentioning it in some other
2997 @samp{_SOURCES} variable.
2999 So, for instance, if you had header files which were created by a script
3000 run at build time, then you would list these headers in
3001 @code{BUILT_SOURCES}, to ensure that they would be built before any
3002 other compilations (perhaps ones using these headers) were started.
3005 @node Other GNU Tools, Documentation, Other objects, Top
3006 @chapter Other GNU Tools
3008 Since Automake is primarily intended to generate @file{Makefile.in}s for
3009 use in GNU programs, it tries hard to interoperate with other GNU tools.
3012 * Emacs Lisp:: Emacs Lisp
3020 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
3023 @cindex _LISP primary, defined
3024 @cindex LISP primary, defined
3025 @cindex Primary variable, LISP
3031 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
3032 is used to hold a list of @file{.el} files. Possible prefixes for this
3033 primary are @samp{lisp_} and @samp{noinst_}. Note that if
3034 @code{lisp_LISP} is defined, then @file{configure.in} must run
3035 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
3039 By default Automake will byte-compile all Emacs Lisp source files using
3040 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
3041 byte-compiling, simply define the variable @code{ELCFILES} to be empty.
3042 Byte-compiled Emacs Lisp files are not portable among all versions of
3043 Emacs, so it makes sense to turn this off if you expect sites to have
3044 more than one version of Emacs installed. Furthermore, many packages
3045 don't actually benefit from byte-compilation. Still, we recommend that
3046 you leave it enabled by default. It is probably better for sites with
3047 strange setups to cope for themselves than to make the installation less
3048 nice for everybody else.
3051 @node gettext, Libtool, Emacs Lisp, Other GNU Tools
3054 @cindex GNU Gettext support
3055 @cindex Gettext support
3056 @cindex Support for GNU Gettext
3058 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
3059 turns on support for GNU gettext, a message catalog system for
3060 internationalization
3061 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
3063 The @code{gettext} support in Automake requires the addition of two
3064 subdirectories to the package, @file{intl} and @file{po}. Automake
3065 insures that these directories exist and are mentioned in
3069 @node Libtool, Java, gettext, Other GNU Tools
3072 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
3073 libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
3074 @xref{A Shared Library}.
3077 @node Java, Python, Libtool, Other GNU Tools
3080 @cindex _JAVA primary, defined
3081 @cindex JAVA primary, defined
3082 @cindex Primary variable, JAVA
3084 Automake provides some minimal support for Java compilation with the
3085 @samp{JAVA} primary.
3087 Any @file{.java} files listed in a @samp{_JAVA} variable will be
3088 compiled with @code{JAVAC} at build time. By default, @file{.class}
3089 files are not included in the distribution.
3091 @cindex JAVA restrictions
3092 @cindex Restrictions for JAVA
3094 Currently Automake enforces the restriction that only one @samp{_JAVA}
3095 primary can be used in a given @file{Makefile.am}. The reason for this
3096 restriction is that, in general, it isn't possible to know which
3097 @file{.class} files were generated from which @file{.java} files -- so
3098 it would be impossible to know which files to install where. For
3099 instance, a @file{.java} file can define multiple classes; the resulting
3100 @file{.class} file names cannot be predicted without parsing the
3103 There are a few variables which are used when compiling Java sources:
3107 The name of the Java compiler. This defaults to @samp{javac}.
3110 The flags to pass to the compiler. This is considered to be a user
3111 variable (@pxref{User Variables}).
3114 More flags to pass to the Java compiler. This, and not
3115 @code{JAVACFLAGS}, should be used when it is necessary to put Java
3116 compiler flags into @file{Makefile.am}.
3119 The value of this variable is passed to the @samp{-d} option to
3120 @code{javac}. It defaults to @samp{$(top_builddir)}.
3123 This variable is an @code{sh} expression which is used to set the
3124 @code{CLASSPATH} environment variable on the @code{javac} command line.
3125 (In the future we will probably handle class path setting differently.)
3129 @node Python, , Java, Other GNU Tools
3132 @cindex _PYTHON primary, defined
3133 @cindex PYTHON primary, defined
3134 @cindex Primary variable, PYTHON
3137 Automake provides support for Python compilation with the @samp{PYTHON}
3140 Any files listed in a @samp{_PYTHON} variable will be byte-compiled with
3141 @code{py-compile} at install time. @code{py-compile} actually creates
3142 both standard (@file{.pyc}) and byte-compiled (@file{.pyo}) versions of
3143 the source files. Note that because byte-compilation occurs at install
3144 time, any files listed in @samp{noinst_PYTHON} will not be compiled.
3145 Python source files are included in the distribution by default.
3147 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} which
3148 will determine some Python-related directory variables (see below). If
3149 have called @code{AM_PATH_PYTHON} from you @file{configure.in}, then you
3150 may use the following variables to list you Python source files in your
3151 variables: @samp{python_PYTHON}, @samp{pkgpython_PYTHON},
3152 @samp{pkgpython_PYTHON}, @samp{pyexecdir_PYTHON},
3153 @samp{pkgpyexecdir_PYTHON}, depending where you want your files
3156 @code{AM_PATH_PYTHON} takes a single optional argument. This argument,
3157 if present, is the minimum version of Python which can be used for this
3158 package. If the version of Python found on the system is older than the
3159 required version, then @code{AM_PATH_PYTHON} will cause an error.
3161 @code{AM_PATH_PYTHON} creates several output variables based on the
3162 Python installation found during configuration.
3166 The name of the Python executable.
3168 @item PYTHON_VERSION
3169 The Python version number, in the form @var{major}.@var{minor}
3170 (e.g. @samp{1.5}). This is currently the value of
3171 @code{sys.version[:3]}.
3174 The string @code{$prefix}. This term may be used in future work
3175 which needs the contents of Python's @code{sys.prefix}, but general
3176 consensus is to always use the value from configure.
3178 @item PYTHON_EXEC_PREFIX
3179 The string @code{$exec_prefix}. This term may be used in future work
3180 which needs the contents of Python's @code{sys.exec_prefix}, but general
3181 consensus is to always use the value from configure.
3183 @item PYTHON_PLATFORM
3184 The canonical name used by Python to describe the operating system, as
3185 given by @code{sys.platform}. This value is sometimes needed when
3186 building Python extensions.
3189 The directory name for the @file{site-packages} subdirectory of the
3190 standard Python install tree.
3193 This is is the directory under @code{pythondir} which is named after the
3194 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
3198 This is the directory where Python extension modules (shared libraries)
3199 should be installed.
3202 This is a convenience variable which is defined as
3203 @samp{$(pyexecdir)/$(PACKAGE)}.
3207 @node Documentation, Install, Other GNU Tools, Top
3208 @chapter Building documentation
3210 Currently Automake provides support for Texinfo and man pages.
3214 * Man pages:: Man pages
3218 @node Texinfo, Man pages, Documentation, Documentation
3221 @cindex _TEXINFOS primary, defined
3222 @cindex TEXINFOS primary, defined
3223 @cindex Primary variable, TEXINFOS
3225 If the current directory contains Texinfo source, you must declare it
3226 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
3227 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
3228 here. Any Texinfo source file must end in the @file{.texi},
3229 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
3232 @vindex info_TEXINFOS
3234 @cindex Texinfo macro, VERSION
3235 @cindex Texinfo macro, UPDATED
3236 @cindex Texinfo macro, EDITION
3237 @cindex Texinfo macro, UPDATED-MONTH
3239 @cindex VERSION Texinfo macro
3240 @cindex UPDATED Texinfo macro
3241 @cindex EDITION Texinfo macro
3242 @cindex UPDATED-MONTH Texinfo macro
3246 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
3247 that file will be automatically generated. The file @file{version.texi}
3248 defines four Texinfo macros you can reference:
3253 Both of these macros hold the version number of your program. They are
3254 kept separate for clarity.
3257 This holds the date the primary @file{.texi} file was last modified.
3260 This holds the name of the month in which the primary @file{.texi} file
3264 The @file{version.texi} support requires the @code{mdate-sh} program;
3265 this program is supplied with Automake and automatically included when
3266 @code{automake} is invoked with the @code{--add-missing} option.
3268 If you have multiple Texinfo files, and you want to use the
3269 @file{version.texi} feature, then you have to have a separate version
3270 file for each Texinfo file. Automake will treat any include in a
3271 Texinfo file that matches @samp{vers*.texi} just as an automatically
3272 generated version file.
3274 When an info file is rebuilt, the program named by the @code{MAKEINFO}
3275 variable is used to invoke it. If the @code{makeinfo} program is found
3276 on the system then it will be used by default; otherwise @code{missing}
3277 will be used instead. The flags in the variables @code{MAKEINFOFLAGS}
3278 and @code{AM_MAKEINFOFLAGS} will be passed to the @code{makeinfo}
3279 invocation; the first of these is intended for use by the user
3280 (@pxref{User Variables}) and the second by the @file{Makefile.am}
3283 @vindex MAKEINFOFLAGS
3284 @vindex AM_MAKEINFOFLAGS
3286 Sometimes an info file actually depends on more than one @file{.texi}
3287 file. For instance, in GNU Hello, @file{hello.texi} includes the file
3288 @file{gpl.texi}. You can tell Automake about these dependencies using
3289 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
3294 info_TEXINFOS = hello.texi
3295 hello_TEXINFOS = gpl.texi
3300 By default, Automake requires the file @file{texinfo.tex} to appear in
3301 the same directory as the Texinfo source. However, if you used
3302 @code{AC_CONFIG_AUX_DIR} in @file{configure.in} (@pxref{Input, , Finding
3303 `configure' Input, autoconf, The Autoconf Manual}), then
3304 @file{texinfo.tex} is looked for there. Automake supplies
3305 @file{texinfo.tex} if @samp{--add-missing} is given.
3309 If your package has Texinfo files in many directories, you can use the
3310 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
3311 @file{texinfo.tex} for your package. The value of this variable should
3312 be the relative path from the current @file{Makefile.am} to
3316 TEXINFO_TEX = ../doc/texinfo.tex
3319 @opindex no-texinfo.tex
3321 The option @samp{no-texinfo.tex} can be used to eliminate the
3322 requirement for @file{texinfo.tex}. Use of the variable
3323 @code{TEXINFO_TEX} is preferable, however, because that allows the
3324 @code{dvi} target to still work.
3326 @cindex Target, install-info
3327 @cindex Target, noinstall-info
3328 @cindex install-info target
3329 @cindex noinstall-info target
3331 @opindex no-installinfo
3332 @trindex install-info
3334 Automake generates an @code{install-info} target; some people apparently
3335 use this. By default, info pages are installed by @samp{make install}.
3336 This can be prevented via the @code{no-installinfo} option.
3339 @node Man pages, , Texinfo, Documentation
3342 @cindex _MANS primary, defined
3343 @cindex MANS primary, defined
3344 @cindex Primary variable, MANS
3346 A package can also include man pages (but see the GNU standards on this
3347 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
3348 pages are declared using the @samp{MANS} primary. Generally the
3349 @code{man_MANS} macro is used. Man pages are automatically installed in
3350 the correct subdirectory of @code{mandir}, based on the file extension.
3354 File extensions such as @samp{.1c} are handled by looking for the valid
3355 part of the extension and using that to determine the correct
3356 subdirectory of @code{mandir}. Valid section names are the digits
3357 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
3359 Sometimes developers prefer to name a man page something like
3360 @file{foo.man} in the source, and then rename it to have the correct
3361 suffix, e.g. @file{foo.1}, when installing the file. Automake also
3362 supports this mode. For a valid section named @var{SECTION}, there is a
3363 corresponding directory named @samp{man@var{SECTION}dir}, and a
3364 corresponding @samp{_MANS} variable. Files listed in such a variable
3365 are installed in the indicated section. If the file already has a
3366 valid suffix, then it is installed as-is; otherwise the file suffix is
3367 changed to match the section.
3369 For instance, consider this example:
3371 man1_MANS = rename.man thesame.1 alsothesame.1c
3374 In this case, @file{rename.man} will be renamed to @file{rename.1} when
3375 installed, but the other files will keep their names.
3377 @cindex Target, install-man
3378 @cindex Target, noinstall-man
3379 @cindex install-man target
3380 @cindex noinstall-man target
3382 @c Use @samp{make install} per documentation: (texi)code.
3383 By default, man pages are installed by @samp{make install}. However,
3384 since the GNU project does not require man pages, many maintainers do
3385 not expend effort to keep the man pages up to date. In these cases, the
3386 @code{no-installman} option will prevent the man pages from being
3387 installed by default. The user can still explicitly install them via
3388 @samp{make install-man}.
3389 @opindex no-installman
3390 @trindex install-man
3392 Here is how the man pages are handled in GNU @code{cpio} (which includes
3393 both Texinfo documentation and man pages):
3396 man_MANS = cpio.1 mt.1
3397 EXTRA_DIST = $(man_MANS)
3400 Man pages are not currently considered to be source, because it is not
3401 uncommon for man pages to be automatically generated. Therefore they
3402 are not automatically included in the distribution. However, this can
3403 be changed by use of the @samp{dist_} prefix.
3405 The @samp{nobase_} prefix is meaningless for man pages and is
3409 @node Install, Clean, Documentation, Top
3410 @chapter What Gets Installed
3412 @cindex Installation support
3413 @cindex make install support
3415 @section Basics of installation
3417 Naturally, Automake handles the details of actually installing your
3418 program once it has been built. All files named by the various
3419 primaries are automatically installed in the appropriate places when the
3420 user runs @code{make install}.
3422 A file named in a primary is installed by copying the built file into
3423 the appropriate directory. The base name of the file is used when
3427 bin_PROGRAMS = hello subdir/goodbye
3430 In this example, both @samp{hello} and @samp{goodbye} will be installed
3431 in @code{$(bindir)}.
3433 Sometimes it is useful to avoid the basename step at install time. For
3434 instance, you might have a number of header files in subdirectories of
3435 the source tree which are laid out precisely how you want to install
3436 them. In this situation you can use the @samp{nobase_} prefix to
3437 suppress the base name step. For example:
3440 nobase_include_HEADERS = stdio.h sys/types.h
3443 Will install @file{stdio.h} in @code{$(includedir)} and @file{types.h}
3444 in @code{$(includedir)/sys}.
3446 @section The two parts of install
3448 Automake generates separate @code{install-data} and @code{install-exec}
3449 targets, in case the installer is installing on multiple machines which
3450 share directory structure---these targets allow the machine-independent
3451 parts to be installed only once. @code{install-exec} installs
3452 platform-dependent files, and @code{install-data} installs
3453 platform-independent files. The @code{install} target depends on both
3454 of these targets. While Automake tries to automatically segregate
3455 objects into the correct category, the @file{Makefile.am} author is, in
3456 the end, responsible for making sure this is done correctly.
3457 @trindex install-data
3458 @trindex install-exec
3460 @cindex Install, two parts of
3462 Variables using the standard directory prefixes @samp{data},
3463 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
3464 @samp{pkgdata}, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
3465 installed by @samp{install-data}.
3467 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
3468 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
3469 @samp{pkglib} (e.g. @samp{bin_PROGRAMS}) are installed by
3470 @samp{install-exec}.
3472 Any variable using a user-defined directory prefix with @samp{exec} in
3473 the name (e.g. @samp{myexecbin_PROGRAMS} is installed by
3474 @samp{install-exec}. All other user-defined prefixes are installed by
3475 @samp{install-data}.
3477 @section Extending installation
3479 It is possible to extend this mechanism by defining an
3480 @code{install-exec-local} or @code{install-data-local} target. If these
3481 targets exist, they will be run at @samp{make install} time. These
3482 rules can do almost anything; care is required.
3483 @trindex install-exec-local
3484 @trindex install-data-local
3486 Automake also supports two install hooks, @code{install-exec-hook} and
3487 @code{install-data-hook}. These hooks are run after all other install
3488 rules of the appropriate type, exec or data, have completed. So, for
3489 instance, it is possible to perform post-installation modifications
3490 using an install hook.
3491 @cindex Install hook
3493 @section Staged installs
3496 Automake generates support for the @samp{DESTDIR} variable in all
3497 install rules. @samp{DESTDIR} is used during the @samp{make install}
3498 step to relocate install objects into a staging area. Each object and
3499 path is prefixed with the value of @samp{DESTDIR} before being copied
3500 into the install area. Here is an example of typical DESTDIR usage:
3503 make DESTDIR=/tmp/staging install
3506 This places install objects in a directory tree built under
3507 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
3508 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
3509 would install @file{/tmp/staging/gnu/bin/foo} and
3510 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
3512 This feature is commonly used to build install images and packages. For
3513 more information, see @ref{Makefile Conventions, , , standards, The GNU
3516 Support for @samp{DESTDIR} is implemented by coding it directly into the
3517 install rules. If your @file{Makefile.am} uses a local install rule
3518 (e.g., @code{install-exec-local}) or an install hook, then you must
3519 write that code to respect @samp{DESTDIR}.
3521 @section Rules for the user
3523 Automake also generates an @code{uninstall} target, an
3524 @code{installdirs} target, and an @code{install-strip} target.
3526 @trindex installdirs
3527 @trindex install-strip
3529 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
3530 There is no notion of separate uninstalls for ``exec'' and ``data'', as
3531 that does not make sense.
3533 Note that @code{uninstall} is not meant as a replacement for a real
3537 @node Clean, Dist, Install, Top
3538 @chapter What Gets Cleaned
3540 @cindex make clean support
3542 The GNU Makefile Standards specify a number of different clean rules.
3544 Generally the files that can be cleaned are determined automatically by
3545 Automake. Of course, Automake also recognizes some variables that can
3546 be defined to specify additional files to clean. These variables are
3547 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
3548 @code{MAINTAINERCLEANFILES}.
3549 @vindex MOSTLYCLEANFILES
3551 @vindex DISTCLEANFILES
3552 @vindex MAINTAINERCLEANFILES
3554 As the GNU Standards aren't always explicit as to which files should be
3555 removed by which target, we've adopted a heuristic which we believe was
3556 first formulated by Fran@,{c}ois Pinard:
3560 If @code{make} built it, and it is commonly something that one would
3561 want to rebuild (for instance, a @file{.o} file), then
3562 @code{mostlyclean} should delete it.
3565 Otherwise, if @code{make} built it, then @code{clean} should delete it.
3568 If @code{configure} built it, then @code{distclean} should delete it
3571 If the maintainer built it, then @code{maintainer-clean} should
3575 We recommend that you follow this same set of heuristics in your
3579 @node Dist, Tests, Clean, Top
3580 @chapter What Goes in a Distribution
3582 @section Basics of distribution
3585 @cindex make distcheck
3587 The @code{dist} target in the generated @file{Makefile.in} can be used
3588 to generate a gzip'd @code{tar} file and other flavors of archive for
3589 distribution. The files is named based on the @samp{PACKAGE} and
3590 @samp{VERSION} variables; more precisely the gzip'd @code{tar} file is
3591 named @samp{@var{package}-@var{version}.tar.gz}.
3595 You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
3596 is run. The default setting is @samp{--best}.
3598 For the most part, the files to distribute are automatically found by
3599 Automake: all source files are automatically included in a distribution,
3600 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
3601 has a built-in list of commonly used files which, if present in the
3602 current directory, are automatically included. This list is printed by
3603 @samp{automake --help}. Also, files which are read by @code{configure}
3604 (i.e. the source files corresponding to the files specified in the
3605 @code{AC_OUTPUT} invocation) are automatically distributed.
3607 Still, sometimes there are files which must be distributed, but which
3608 are not covered in the automatic rules. These files should be listed in
3609 the @code{EXTRA_DIST} variable. You can mention files from
3610 subdirectories in @code{EXTRA_DIST}.
3612 You can also mention a directory in @code{EXTRA_DIST}; in this case the
3613 entire directory will be recursively copied into the distribution.
3614 Please note that this will also copy @emph{everything} in the directory,
3615 including CVS/RCS version control files. We recommend against using
3620 @section Fine-grained distribution control
3622 Sometimes you need tighter control over what does @emph{not} go into the
3623 distribution; for instance you might have source files which are
3624 generated and which you do not want to distribute. In this case
3625 Automake gives fine-grained control using the @samp{dist} and
3626 @samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
3627 prefixed with @samp{dist_} to add the listed files to the distribution.
3628 Similarly, @samp{nodist_} can be used to omit the files from the
3633 As an example, here is how you would cause some data to be distributed
3634 while leaving some source code out of the distribution:
3637 dist_data_DATA = distribute-this
3639 nodist_foo_SOURCES = do-not-distribute.c
3642 @section The dist hook
3644 Another way to to use this is for removing unnecessary files that get
3645 recursively included by specifying a directory in EXTRA_DIST:
3651 rm -rf `find $(distdir)/doc -name CVS`
3654 If you define @code{SUBDIRS}, Automake will recursively include the
3655 subdirectories in the distribution. If @code{SUBDIRS} is defined
3656 conditionally (@pxref{Conditionals}), Automake will normally include all
3657 directories that could possibly appear in @code{SUBDIRS} in the
3658 distribution. If you need to specify the set of directories
3659 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
3660 list of subdirectories to include in the distribution.
3661 @vindex DIST_SUBDIRS
3665 Occasionally it is useful to be able to change the distribution before
3666 it is packaged up. If the @code{dist-hook} target exists, it is run
3667 after the distribution directory is filled, but before the actual tar
3668 (or shar) file is created. One way to use this is for distributing
3669 files in subdirectories for which a new @file{Makefile.am} is overkill:
3673 mkdir $(distdir)/random
3674 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
3677 @section Checking the distribution
3679 Automake also generates a @code{distcheck} target which can be of help
3680 to ensure that a given distribution will actually work.
3681 @code{distcheck} makes a distribution, and then tries to do a
3685 If the target @code{distcheck-hook} is defined in your
3686 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
3687 the new distribution has been unpacked, but before the unpacked copy is
3688 configured and built. Your @code{distcheck-hook} can do almost
3689 anything, though as always caution is advised. Generally this hook is
3690 used to check for potential distribution errors not caught by the
3693 @section The types of distributions
3696 Automake generates a @samp{.tar.gz} file when asked to create a
3697 distribution and other archives formats, @ref{Options}. The target
3698 @code{dist-gzip} generates the @samp{.tar.gz} file only.
3701 @node Tests, Options, Dist, Top
3702 @chapter Support for test suites
3707 Automake supports two forms of test suites.
3709 @section Simple Tests
3711 If the variable @code{TESTS} is defined, its value is taken to be a list
3712 of programs to run in order to do the testing. The programs can either
3713 be derived objects or source objects; the generated rule will look both
3714 in @code{srcdir} and @file{.}. Programs needing data files should look
3715 for them in @code{srcdir} (which is both an environment variable and a
3716 make variable) so they work when building in a separate directory
3717 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
3718 Manual}), and in particular for the @code{distcheck} target
3721 @cindex Exit status 77, special interpretation
3723 The number of failures will be printed at the end of the run. If a
3724 given test program exits with a status of 77, then its result is ignored
3725 in the final count. This feature allows non-portable tests to be
3726 ignored in environments where they don't make sense.
3728 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
3729 variables for the test run; the environment variable @code{srcdir} is
3730 set in the rule. If all your test programs are scripts, you can also
3731 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
3732 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
3734 @vindex TESTS_ENVIRONMENT
3736 @cindex Tests, expected failure
3737 @cindex Expected test failure
3739 You may define the variable @code{XFAIL_TESTS} to a list of tests
3740 (usually a subset of @code{TESTS}) that are expected to fail. This will
3741 reverse the result of those tests.
3744 Automake ensures that each program listed in @code{TESTS} is built
3745 before any tests are run; you can list both source and derived programs
3746 in @code{TESTS}. For instance, you might want to run a C program as a
3747 test. To do this you would list its name in @code{TESTS} and also in
3748 @code{check_PROGRAMS}, and then specify it as you would any other
3751 @section DejaGNU Tests
3753 If @uref{ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz,
3754 @samp{dejagnu}} appears in @code{AUTOMAKE_OPTIONS}, then a
3755 @code{dejagnu}-based test suite is assumed. The variable
3756 @code{DEJATOOL} is a list of names which are passed, one at a time, as
3757 the @code{--tool} argument to @code{runtest} invocations; it defaults to
3758 the name of the package.
3760 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
3761 @code{--srcdir} flags that are passed to dejagnu by default; this can be
3762 overridden if necessary.
3763 @vindex RUNTESTDEFAULTFLAGS
3765 The variables @code{EXPECT} and @code{RUNTEST} can
3766 also be overridden to provide project-specific values. For instance,
3767 you will need to do this if you are testing a compiler toolchain,
3768 because the default values do not take into account host and target
3775 The contents of the variable @code{RUNTESTFLAGS} are passed to the
3776 @code{runtest} invocation. This is considered a ``user variable''
3777 (@pxref{User Variables}). If you need to set @code{runtest} flags in
3778 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
3779 @vindex RUNTESTFLAGS
3780 @vindex AM_RUNTESTFLAGS
3781 @c FIXME xref dejagnu
3783 In either case, the testing is done via @samp{make check}.
3786 @node Options, Miscellaneous, Tests, Top
3787 @chapter Changing Automake's Behavior
3789 Various features of Automake can be controlled by options in the
3790 @file{Makefile.am}. Such options are listed in a special variable named
3791 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
3792 @vindex AUTOMAKE_OPTIONS
3797 @itemx @code{foreign}
3798 @itemx @code{cygnus}
3799 @cindex Option, gnits
3801 @cindex Option, foreign
3802 @cindex Option, cygnus
3804 Set the strictness as appropriate. The @code{gnits} option also implies
3805 @code{readme-alpha} and @code{check-news}.
3807 @item @code{ansi2knr}
3808 @itemx @code{@var{path}/ansi2knr}
3809 @cindex Option, ansi2knr
3810 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
3811 path, the generated @file{Makefile.in} will look in the specified
3812 directory to find the @file{ansi2knr} program. The path should be a
3813 relative path to another directory in the same distribution (Automake
3814 currently does not check this).
3816 @item @code{check-news}
3817 @cindex Option, check-news
3818 Cause @code{make dist} to fail unless the current version number appears
3819 in the first few lines of the @file{NEWS} file.
3821 @item @code{dejagnu}
3822 @cindex Option, dejagnu
3823 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
3825 @item @code{dist-bzip2}
3826 @cindex Option, dist-bzip2
3827 Generate a @code{dist-bzip2} target, creating a bzip2 tar archive of the
3828 distribution. @code{dist} will create it in addition to the other
3829 formats. bzip2 archives are frequently smaller than gzipped archives.
3832 @item @code{dist-shar}
3833 @cindex Option, dist-shar
3834 Generate a @code{dist-shar} target, creating a shar archive of the
3835 distribution. @code{dist} will create it in addition to the other
3839 @item @code{dist-zip}
3840 @cindex Option, dist-zip
3841 Generate a @code{dist-zip} target, creating a zip archive of the
3842 distribution. @code{dist} will create it in addition to the other
3846 @item @code{dist-tarZ}
3847 @cindex Option, dist-tarZ
3848 Generate a @code{dist-tarZ} target, creating a compressed tar archive of
3849 the distribution. @code{dist} will create it in addition to the other
3853 @item @code{no-dependencies}
3854 @cindex Option, no-dependencies
3855 This is similar to using @samp{--include-deps} on the command line, but
3856 is useful for those situations where you don't have the necessary bits
3857 to make automatic dependency tracking work @xref{Dependencies}. In this
3858 case the effect is to effectively disable automatic dependency tracking.
3860 @item @code{no-exeext}
3861 @cindex Option, no-exeext
3862 If your @file{Makefile.am} defines a target @samp{foo}, it will override
3863 a target named @samp{foo$(EXEEXT)}. This is necessary when
3864 @code{EXEEXT} is found to be empty. However, by default automake will
3865 generate an error for this use. The @code{no-exeext} option will
3866 disable this error. This is intended for use only where it is known in
3867 advance that the package will not be ported to Windows, or any other
3868 operating system using extensions on executables.
3870 @item @code{no-installinfo}
3871 @cindex Option, no-installinfo
3872 The generated @file{Makefile.in} will not cause info pages to be built
3873 or installed by default. However, @code{info} and @code{install-info}
3874 targets will still be available. This option is disallowed at
3875 @samp{GNU} strictness and above.
3877 @trindex install-info
3879 @item @code{no-installman}
3880 @cindex Option, no-installman
3881 The generated @file{Makefile.in} will not cause man pages to be
3882 installed by default. However, an @code{install-man} target will still
3883 be available for optional installation. This option is disallowed at
3884 @samp{GNU} strictness and above.
3885 @trindex install-man
3887 @item @code{nostdinc}
3888 @cindex Option, nostdinc
3889 This option can be used to disable the standard @samp{-I} options which
3890 are ordinarily automatically provided by Automake.
3892 @item @code{no-texinfo.tex}
3893 @cindex Option, no-texinfo
3894 Don't require @file{texinfo.tex}, even if there are texinfo files in
3897 @item @code{readme-alpha}
3898 @cindex Option, readme-alpha
3899 If this release is an alpha release, and the file @file{README-alpha}
3900 exists, then it will be added to the distribution. If this option is
3901 given, version numbers are expected to follow one of two forms. The
3902 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
3903 element is a number; the final period and number should be left off for
3904 non-alpha releases. The second form is
3905 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
3906 letter; it should be omitted for non-alpha releases.
3908 @item @code{subdir-objects}
3909 If this option is specified, then objects are placed into the
3910 subdirectory of the build directory corresponding to the subdirectory of
3911 the source file. For instance if the source file is
3912 @file{subdir/file.cxx}, then the output file would be
3913 @file{subdir/file.o}.
3916 @cindex Option, version
3917 A version number (e.g. @samp{0.30}) can be specified. If Automake is not
3918 newer than the version specified, creation of the @file{Makefile.in}
3922 Unrecognized options are diagnosed by @code{automake}.
3925 @node Miscellaneous, Include, Options, Top
3926 @chapter Miscellaneous Rules
3928 There are a few rules and variables that didn't fit anywhere else.
3931 * Tags:: Interfacing to etags and mkid
3932 * Suffixes:: Handling new file extensions
3933 * Multilibs:: Support for multilibbing.
3937 @node Tags, Suffixes, Miscellaneous, Miscellaneous
3938 @section Interfacing to @code{etags}
3940 @cindex TAGS support
3942 Automake will generate rules to generate @file{TAGS} files for use with
3943 GNU Emacs under some circumstances.
3945 If any C, C++ or Fortran 77 source code or headers are present, then
3946 @code{tags} and @code{TAGS} targets will be generated for the directory.
3949 At the topmost directory of a multi-directory package, a @code{tags}
3950 target file will be generated which, when run, will generate a
3951 @file{TAGS} file that includes by reference all @file{TAGS} files from
3954 The @code{tags} target will also be generated if the variable
3955 @code{ETAGS_ARGS} is defined. This variable is intended for use in
3956 directories which contain taggable source that @code{etags} does not
3960 Here is how Automake generates tags for its source, and for nodes in its
3964 ETAGS_ARGS = automake.in --lang=none \
3965 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
3968 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
3969 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
3970 are added directly to the dependencies for the @code{tags} target.
3971 @vindex TAGS_DEPENDENCIES
3973 Automake will also generate an @code{ID} target which will run
3974 @code{mkid} on the source. This is only supported on a
3975 directory-by-directory basis.
3978 Automake also supports the @uref{http://www.gnu.org/software/global/,
3979 GNU Global Tags program}. The @code{GTAGS} target runs Global Tags
3980 automatically and puts the result in the top build directory. The
3981 variable @code{GTAGS_ARGS} holds arguments which are passed to
3986 @node Suffixes, Multilibs, Tags, Miscellaneous
3987 @section Handling new file extensions
3989 @cindex Adding new SUFFIXES
3990 @cindex SUFFIXES, adding
3992 It is sometimes useful to introduce a new implicit rule to handle a file
3993 type that Automake does not know about. If this is done, you must
3994 notify GNU Make of the new suffixes. This can be done by putting a list
3995 of new suffixes in the @code{SUFFIXES} variable.
3998 For instance, suppose you had a compiler which could compile @samp{.foo}
3999 files to @samp{.o} files. Then you would add @samp{.foo} to your suffix
4006 Then you could directly use a @samp{.foo} file in a @samp{_SOURCES}
4007 variable and expect the correct results:
4011 doit_SOURCES = doit.foo
4014 Any given @code{SUFFIXES} go at the start of the generated suffixes
4015 list, followed by automake generated suffixes not already in the list.
4018 @node Multilibs, , Suffixes, Miscellaneous
4019 @section Support for Multilibs
4021 Automake has support for an obscure feature called multilibs. A
4022 @dfn{multilib} is a library which is built for multiple different ABIs
4023 at a single time; each time the library is built with a different target
4024 flag combination. This is only useful when the library is intended to
4025 be cross-compiled, and it is almost exclusively used for compiler
4028 The multilib support is still experimental. Only use it if you are
4029 familiar with multilibs and can debug problems you might encounter.
4032 @node Include, Conditionals, Miscellaneous, Top
4036 @cindex Including Makefile fragment
4037 @cindex Makefile fragment, including
4039 Automake supports an @code{include} directive which can be used to
4040 include other @file{Makefile} fragments when @code{automake} is run.
4041 Note that these fragments are read and interpreted by @code{automake},
4042 not by @code{make}. As with conditionals, @code{make} has no idea that
4043 @code{include} is in use.
4045 There are two forms of @code{include}:
4048 @item include $(srcdir)/file
4049 Include a fragment which is found relative to the current source
4052 @item include $(top_srcdir)/file
4053 Include a fragment which is found relative to the top source directory.
4056 Note that if a fragment is included inside a conditional, then the
4057 condition applies to the entire contents of that fragment.
4060 @node Conditionals, Gnits, Include, Top
4061 @chapter Conditionals
4063 @cindex Conditionals
4065 Automake supports a simple type of conditionals.
4067 @cvindex AM_CONDITIONAL
4068 Before using a conditional, you must define it by using
4069 @code{AM_CONDITIONAL} in the @code{configure.in} file (@pxref{Macros}).
4071 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
4072 The conditional name, @var{conditional}, should be a simple string
4073 starting with a letter and containing only letters, digits, and
4074 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
4075 which are reserved by Automake.
4077 The shell @var{condition} (suitable for use in a shell @code{if}
4078 statement) is evaluated when @code{configure} is run. Note that you
4079 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
4080 time @code{configure} is run -- if @code{AM_CONDITIONAL} is run
4081 conditionally (e.g., in a shell @code{if} statement), then the result
4082 will confuse automake.
4085 @cindex --enable-debug, example
4086 @cindex Example conditional --enable-debug
4087 @cindex Conditional example, --enable-debug
4089 Conditionals typically depend upon options which the user provides to
4090 the @code{configure} script. Here is an example of how to write a
4091 conditional which is true if the user uses the @samp{--enable-debug}
4095 AC_ARG_ENABLE(debug,
4096 [ --enable-debug Turn on debugging],
4097 [case "$@{enableval@}" in
4100 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
4101 esac],[debug=false])
4102 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
4105 Here is an example of how to use that conditional in @file{Makefile.am}:
4117 noinst_PROGRAMS = $(DBG)
4120 This trivial example could also be handled using EXTRA_PROGRAMS
4121 (@pxref{A Program}).
4123 You may only test a single variable in an @code{if} statement, possibly
4124 negated using @samp{!}. The @code{else} statement may be omitted.
4125 Conditionals may be nested to any depth. You may specify an argument to
4126 @code{else} in which case it must be the negation of the condition used
4127 for the current @code{if}. Similarly you may specify the condition
4128 which is closed by an @code{end}:
4139 Unbalanced conditions are errors.
4141 Note that conditionals in Automake are not the same as conditionals in
4142 GNU Make. Automake conditionals are checked at configure time by the
4143 @file{configure} script, and affect the translation from
4144 @file{Makefile.in} to @file{Makefile}. They are based on options passed
4145 to @file{configure} and on results that @file{configure} has discovered
4146 about the host system. GNU Make conditionals are checked at @code{make}
4147 time, and are based on variables passed to the make program or defined
4148 in the @file{Makefile}.
4150 Automake conditionals will work with any make program.
4153 @node Gnits, Cygnus, Conditionals, Top
4154 @chapter The effect of @code{--gnu} and @code{--gnits}
4156 @cindex --gnu, required files
4157 @cindex --gnu, complete description
4159 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
4160 variable) causes @code{automake} to check the following:
4164 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
4165 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
4166 directory of the package.
4169 The options @samp{no-installman} and @samp{no-installinfo} are
4173 Note that this option will be extended in the future to do even more
4174 checking; it is advisable to be familiar with the precise requirements
4175 of the GNU standards. Also, @samp{--gnu} can require certain
4176 non-standard GNU programs to exist for use by various maintainer-only
4177 targets; for instance in the future @code{pathchk} might be required for
4180 @cindex --gnits, complete description
4182 The @samp{--gnits} option does everything that @samp{--gnu} does, and
4183 checks the following as well:
4187 @samp{make dist} will check to make sure the @file{NEWS} file has been
4188 updated to the current version.
4191 @samp{VERSION} is checked to make sure its format complies with Gnits
4193 @c FIXME xref when standards are finished
4196 @cindex README-alpha
4197 If @samp{VERSION} indicates that this is an alpha release, and the file
4198 @file{README-alpha} appears in the topmost directory of a package, then
4199 it is included in the distribution. This is done in @samp{--gnits}
4200 mode, and no other, because this mode is the only one where version
4201 number formats are constrained, and hence the only mode where Automake
4202 can automatically determine whether @file{README-alpha} should be
4206 The file @file{THANKS} is required.
4210 @node Cygnus, Extending, Gnits, Top
4211 @chapter The effect of @code{--cygnus}
4213 @cindex Cygnus strictness
4215 Some packages, notably GNU GCC and GNU gdb, have a build environment
4216 originally written at Cygnus Support (subsequently renamed Cygnus
4217 Solutions, and then later purchased by Red Hat). Packages with this
4218 ancestry are sometimes referred to as ``Cygnus'' trees.
4220 A Cygnus tree has slightly different rules for how a @file{Makefile.in}
4221 is to be constructed. Passing @samp{--cygnus} to @code{automake} will
4222 cause any generated @file{Makefile.in} to comply with Cygnus rules.
4224 Here are the precise effects of @samp{--cygnus}:
4228 Info files are always created in the build directory, and not in the
4232 @file{texinfo.tex} is not required if a Texinfo source file is
4233 specified. The assumption is that the file will be supplied, but in a
4234 place that Automake cannot find. This assumption is an artifact of how
4235 Cygnus packages are typically bundled.
4238 @samp{make dist} is not supported, and the rules for it are not
4239 generated. Cygnus-style trees use their own distribution mechanism.
4242 Certain tools will be searched for in the build tree as well as in the
4243 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
4244 @code{makeinfo} and @code{texi2dvi}.
4247 @code{--foreign} is implied.
4250 The options @samp{no-installinfo} and @samp{no-dependencies} are
4254 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
4258 The @code{check} target doesn't depend on @code{all}.
4261 GNU maintainers are advised to use @samp{gnu} strictness in preference
4262 to the special Cygnus mode. Some day, perhaps, the differences between
4263 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
4264 more standards compliant). At that time the special Cygnus mode will be
4268 @node Extending, Distributing, Cygnus, Top
4269 @chapter When Automake Isn't Enough
4271 Automake's implicit copying semantics means that many problems can be
4272 worked around by simply adding some @code{make} targets and rules to
4273 @file{Makefile.in}. Automake will ignore these additions.
4275 @cindex -local targets
4276 @cindex local targets
4278 There are some caveats to doing this. Although you can overload a
4279 target already used by Automake, it is often inadvisable, particularly
4280 in the topmost directory of a package with subdirectories. However,
4281 various useful targets have a @samp{-local} version you can specify in
4282 your @file{Makefile.in}. Automake will supplement the standard target
4283 with these user-supplied targets.
4288 @trindex check-local
4289 @trindex install-data-local
4290 @trindex install-exec-local
4291 @trindex uninstall-local
4292 @trindex mostlyclean-local
4293 @trindex clean-local
4294 @trindex distclean-local
4296 The targets that support a local version are @code{all}, @code{info},
4297 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
4298 @code{uninstall}, and the various @code{clean} targets
4299 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
4300 @code{maintainer-clean}). Note that there are no
4301 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
4302 use @code{uninstall-local}. It doesn't make sense to uninstall just
4303 data or just executables.
4308 @trindex install-data
4309 @trindex install-exec
4312 For instance, here is one way to install a file in @file{/etc}:
4316 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
4319 @cindex -hook targets
4320 @cindex hook targets
4322 Some targets also have a way to run another target, called a @dfn{hook},
4323 after their work is done. The hook is named after the principal target,
4324 with @samp{-hook} appended. The targets allowing hooks are
4325 @code{install-data}, @code{install-exec}, @code{dist}, and
4327 @trindex install-data-hook
4328 @trindex install-exec-hook
4331 For instance, here is how to create a hard link to an installed program:
4335 ln $(bindir)/program $(bindir)/proglink
4338 @c FIXME should include discussion of variables you can use in these
4342 @node Distributing, Macro and Variable Index, Extending, Top
4343 @chapter Distributing @file{Makefile.in}s
4345 Automake places no restrictions on the distribution of the resulting
4346 @file{Makefile.in}s. We still encourage software authors to distribute
4347 their work under terms like those of the GPL, but doing so is not
4348 required to use Automake.
4350 Some of the files that can be automatically installed via the
4351 @code{--add-missing} switch do fall under the GPL. However, these also
4352 have a special exception allowing you to distribute them with your
4353 package, regardless of the licensing you choose.
4357 @node Macro and Variable Index, General Index, Distributing, Top
4358 @unnumbered Macro and Variable Index
4364 @node General Index, , Macro and Variable Index, Top
4365 @unnumbered General Index