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
1334 header. If you do use this macro, you must create the file
1335 @file{stamp-h.in} in your source directory. It can be empty.
1336 @cvindex AM_CONFIG_HEADER
1338 @item AM_ENABLE_MULTILIB
1339 This is used when a ``multilib'' library is being built. The first
1340 optional argument is the name of the @file{Makefile} being generated; it
1341 defaults to @samp{Makefile}. The second option argument is used to find
1342 the top source directory; it defaults to the empty string (generally
1343 this should not be used unless you are familiar with the internals).
1346 @item _AM_DEPENDENCIES
1347 @itemx AM_SET_DEPDIR
1349 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
1350 These macros are used to implement automake's automatic dependency
1351 tracking scheme. They are called automatically by automake when
1352 required, and there should be no need to invoke them manually.
1354 @item AM_C_PROTOTYPES
1355 Check to see if function prototypes are understood by the compiler. If
1356 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1357 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1358 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1359 values to implement automatic de-ANSI-fication.
1360 @cvindex AM_C_PROTOTYPES
1362 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1363 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1364 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1365 found in @file{<termios.h>}.
1366 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1368 @item AM_INIT_AUTOMAKE
1369 Runs many macros that most @file{configure.in}'s need. This macro has
1370 two required arguments, the package and the version number. By default
1371 this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}. This
1372 can be avoided by passing in a non-empty third argument.
1374 @item AM_MAKE_INCLUDE
1375 This macro is used to discover how the user's @code{make} handles
1376 @code{include} statements. This macro is automatically invoked when
1377 needed; there should be no need to invoke it manually.
1379 @item AM_PATH_LISPDIR
1380 Searches for the program @code{emacs}, and, if found, sets the output
1381 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1382 @cvindex AM_PATH_LISPDIR
1385 Use this macro when you have assembly code in your project. This will
1386 choose the assembler for you (by default the C compiler), and will set
1387 @code{ASFLAGS} if required.
1389 @item AM_PROG_CC_C_O
1390 This is like @code{AC_PROG_CC_C_O}, but it generates its results in the
1391 manner required by automake. You must use this instead of
1392 @code{AC_PROG_CC_C_O} when you need this functionality.
1394 @item AM_PROG_CC_STDC
1395 If the C compiler is not in ANSI C mode by default, try to add an option
1396 to output variable @code{CC} to make it so. This macro tries various
1397 options that select ANSI C on some system or another. It considers the
1398 compiler to be in ANSI C mode if it handles function prototypes correctly.
1400 If you use this macro, you should check after calling it whether the C
1401 compiler has been set to accept ANSI C; if not, the shell variable
1402 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1403 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1404 @code{ansi2knr} option (@pxref{ANSI}).
1407 @cindex HP-UX 10, lex problems
1408 @cindex lex problems with HP-UX 10
1409 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
1410 Program Checks, autoconf, The Autoconf Manual}), but uses the
1411 @code{missing} script on systems that do not have @code{lex}.
1412 @samp{HP-UX 10} is one such system.
1415 This macro finds the @code{gcj} program or causes an error. It sets
1416 @samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
1417 GNU Compiler Collection.
1418 @cvindex AM_PROG_GCJ
1420 @item AM_PROG_INSTALL_STRIP
1421 This is used to find a version of @code{install} which can be used to
1422 @code{strip} a program at installation time. This macro is
1423 automatically included when required.
1425 @item AM_SANITY_CHECK
1426 This checks to make sure that a file created in the build directory is
1427 newer than a file in the source directory. This can fail on systems
1428 where the clock is set incorrectly. This macro is automatically run
1429 from @code{AM_INIT_AUTOMAKE}.
1431 @item AM_SYS_POSIX_TERMIOS
1432 @cvindex am_cv_sys_posix_termios
1433 @cindex POSIX termios headers
1434 @cindex termios POSIX headers
1435 Check to see if POSIX termios headers and functions are available on the
1436 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1437 @samp{yes}. If not, set the variable to @samp{no}.
1439 @item AM_WITH_DMALLOC
1440 @cvindex WITH_DMALLOC
1441 @cindex dmalloc, support for
1442 @opindex --with-dmalloc
1444 @uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
1445 package. If the user configures with @samp{--with-dmalloc}, then define
1446 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
1450 @opindex --with-regex
1451 @cindex regex package
1453 Adds @samp{--with-regex} to the @code{configure} command line. If
1454 specified (the default), then the @samp{regex} regular expression
1455 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1456 @samp{WITH_REGEX} is defined.. If @samp{--without-regex} is given, then
1457 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1458 into @samp{LIBOBJS}.
1463 @node Extending aclocal, , Macros, configure
1464 @section Writing your own aclocal macros
1466 @cindex aclocal, extending
1467 @cindex Extending aclocal
1469 The @code{aclocal} program doesn't have any built-in knowledge of any
1470 macros, so it is easy to extend it with your own macros.
1472 This is mostly used for libraries which want to supply their own
1473 Autoconf macros for use by other programs. For instance the
1474 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1475 should be used by any package using @code{gettext}. When the library is
1476 installed, it installs this macro so that @code{aclocal} will find it.
1478 A file of macros should be a series of @code{AC_DEFUN}'s. The
1479 @code{aclocal} programs also understands @code{AC_REQUIRE}, so it is
1480 safe to put each macro in a separate file. @xref{Prerequisite Macros, ,
1481 , autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
1482 autoconf, The Autoconf Manual}.
1484 A macro file's name should end in @file{.m4}. Such files should be
1485 installed in @file{$(datadir)/aclocal}.
1488 @node Top level, Alternative, configure, Top
1489 @chapter The top-level @file{Makefile.am}
1491 @cindex SUBDIRS, explained
1493 In packages with subdirectories, the top level @file{Makefile.am} must
1494 tell Automake which subdirectories are to be built. This is done via
1495 the @code{SUBDIRS} variable.
1498 The @code{SUBDIRS} macro holds a list of subdirectories in which
1499 building of various sorts can occur. Many targets (e.g. @code{all}) in
1500 the generated @file{Makefile} will run both locally and in all specified
1501 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1502 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1503 (after configuration). This allows inclusion of libraries from packages
1504 which do not use Automake (such as @code{gettext}). The directories
1505 mentioned in @code{SUBDIRS} must be direct children of the current
1506 directory. For instance, you cannot put @samp{src/subdir} into
1509 In packages that use subdirectories, the top-level @file{Makefile.am} is
1510 often very short. For instance, here is the @file{Makefile.am} from the
1511 GNU Hello distribution:
1514 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1515 SUBDIRS = doc intl po src tests
1518 @cindex SUBDIRS, overriding
1519 @cindex Overriding SUBDIRS
1521 It is possible to override the @code{SUBDIRS} variable if, like in the
1522 case of GNU @code{Inetutils}, you want to only build a subset of the
1523 entire package. In your @file{Makefile.am} include:
1526 SUBDIRS = @@MY_SUBDIRS@@
1529 Then in your @file{configure.in} you can specify:
1532 MY_SUBDIRS="src doc lib po"
1533 AC_SUBST(MY_SUBDIRS)
1536 (Note that we don't use the variable name @code{SUBDIRS} in our
1537 @file{configure.in}; that would cause Automake to believe that every
1538 @file{Makefile.in} should recurse into the listed subdirectories.)
1540 The upshot of this is that Automake is tricked into building the package
1541 to take the subdirs, but doesn't actually bind that list until
1542 @code{configure} is run.
1544 Although the @code{SUBDIRS} macro can contain configure substitutions
1545 (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
1546 contents of this variable.
1548 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1549 @code{AC_PROG_MAKE_SET}. When Automake invokes @code{make} in a
1550 subdirectory, it uses the value of the @code{MAKE} variable. It passes
1551 the value of the variable @code{AM_MAKEFLAGS} to the @code{make}
1552 invocation; this can be set in @file{Makefile.am} if there are flags you
1553 must always pass to @code{make}.
1557 The use of @code{SUBDIRS} is not restricted to just the top-level
1558 @file{Makefile.am}. Automake can be used to construct packages of
1561 By default, Automake generates @file{Makefiles} which work depth-first
1562 (@samp{postfix}). However, it is possible to change this ordering. You
1563 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
1564 putting @samp{.} first will cause a @samp{prefix} ordering of
1565 directories. All @samp{clean} targets are run in reverse order of build
1568 Sometimes, such as when running @code{make dist}, you want all possible
1569 subdirectories to be examined. In this case Automake will use
1570 @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to
1571 recurse. This variable will also be used when the user runs
1572 @code{distclean} or @code{maintainer-clean}. It should be set to the
1573 full list of subdirectories in the project. If this macro is not set,
1574 Automake will attempt to set it for you.
1577 @node Alternative, Rebuilding, Top level, Top
1578 @chapter An Alternative Approach to Subdirectories
1580 If you've ever read Peter Miller's excellent paper,
1581 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
1582 Recursive Make Considered Harmful}, the preceding section on the use of
1583 subdirectories will probably come as unwelcome advice. For those who
1584 haven't read the paper, Miller's main thesis is that recursive
1585 @code{make} invocations are both slow and error-prone.
1587 Automake provides sufficient cross-directory support @footnote{We
1588 believe. This work is new and there are probably warts.
1589 @xref{Introduction}, for information on reporting bugs.} to enable you
1590 to write a single @file{Makefile.am} for a complex multi-directory
1594 By default an installable file specified in a subdirectory will have its
1595 directory name stripped before installation. For instance, in this
1596 example, the header file will be installed as
1597 @file{$(includedir)/stdio.h}:
1600 include_HEADERS = inc/stdio.h
1604 @cindex Path stripping, avoiding
1605 @cindex Avoiding path stripping
1607 However, the @samp{nobase_} prefix can be used to circumvent this path
1608 stripping. In this example, the header file will be installed as
1609 @file{$(includedir)/sys/types.h}:
1612 nobase_include_HEADERS = sys/types.h
1616 @node Rebuilding, Programs, Alternative, Top
1617 @chapter Rebuilding Makefiles
1619 Automake generates rules to automatically rebuild @file{Makefile}s,
1620 @file{configure}, and other derived files like @file{Makefile.in}.
1622 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.in}, then
1623 these automatic rebuilding rules are only enabled in maintainer mode.
1625 Sometimes you need to run @code{aclocal} with an argument like @code{-I}
1626 to tell it where to find @file{.m4} files. Since sometimes @code{make}
1627 will automatically run @code{aclocal}, you need a way to specify these
1628 arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this
1629 holds arguments which are passed verbatim to @code{aclocal}. This macro
1630 is only useful in the top-level @file{Makefile.am}.
1631 @cindex ACLOCAL_AMFLAGS
1634 @node Programs, Other objects, Rebuilding, Top
1635 @chapter Building Programs and Libraries
1637 A large part of Automake's functionality is dedicated to making it easy
1638 to build programs and libraries.
1641 * A Program:: Building a program
1642 * A Library:: Building a library
1643 * A Shared Library:: Building a Libtool library
1644 * Program and Library Variables::
1645 Variables controlling program and
1647 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1648 * Program variables:: Variables used when building a program
1649 * Yacc and Lex:: Yacc and Lex support
1651 * Assembly Support::
1652 * Fortran 77 Support::
1654 * Support for Other Languages::
1655 * ANSI:: Automatic de-ANSI-fication
1656 * Dependencies:: Automatic dependency tracking
1657 * EXEEXT:: Support for executable extensions
1661 @node A Program, A Library, Programs, Programs
1662 @section Building a program
1664 @subsection Introductory blathering
1666 @cindex PROGRAMS, bindir
1667 @vindex bin_PROGRAMS
1668 @vindex sbin_PROGRAMS
1669 @vindex libexec_PROGRAMS
1670 @vindex pkglib_PROGRAMS
1671 @vindex noinst_PROGRAMS
1673 In a directory containing source that gets built into a program (as
1674 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
1675 can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
1676 @code{pkglibdir}, or not at all (@samp{noinst}). They can also be built
1677 only for @code{make check}, in which case the prefix is @samp{check}.
1682 bin_PROGRAMS = hello
1685 In this simple case, the resulting @file{Makefile.in} will contain code
1686 to generate a program named @code{hello}.
1688 Associated with each program are several assisting variables which are
1689 named after the program. These variables are all optional, and have
1690 reasonable defaults. Each variable, its use, and default is spelled out
1691 below; we use the ``hello'' example throughout.
1693 The variable @code{hello_SOURCES} is used to specify which source files
1694 get built into an executable:
1697 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1700 This causes each mentioned @samp{.c} file to be compiled into the
1701 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1703 @cindex _SOURCES primary, defined
1704 @cindex SOURCES primary, defined
1705 @cindex Primary variable, SOURCES
1707 If @samp{hello_SOURCES} is not specified, then it defaults to the single
1708 file @file{hello.c}; that is, the default is to compile a single C file
1709 whose base name is the name of the program itself. (This is a terrible
1710 default but we are stuck with it for historical reasons.)
1714 Multiple programs can be built in a single directory. Multiple programs
1715 can share a single source file, which must be listed in each
1716 @samp{_SOURCES} definition.
1718 @cindex Header files in _SOURCES
1719 @cindex _SOURCES and header files
1721 Header files listed in a @samp{_SOURCES} definition will be included in
1722 the distribution but otherwise ignored. In case it isn't obvious, you
1723 should not include the header file generated by @file{configure} in a
1724 @samp{_SOURCES} variable; this file should not be distributed. Lex
1725 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1728 @subsection Conditional compilations
1730 You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
1731 @samp{_SOURCES} variable. The reason for this is a bit hard to explain,
1732 but suffice to say that it simply won't work. Automake will give an
1733 error if you try to do this.
1735 @cindex EXTRA_prog_SOURCES, defined
1737 Automake must know all the source files that could possibly go into a
1738 program, even if not all the files are built in every circumstance.
1739 Any files which are only conditionally built should be listed in the
1740 appropriate @samp{EXTRA_} variable. For instance, if
1741 @file{hello-linux.c} were conditionally included in @code{hello}, the
1742 @file{Makefile.am} would contain:
1745 EXTRA_hello_SOURCES = hello-linux.c
1748 In this case, @file{hello-linux.o} would be added, via a
1749 @file{configure} substitution, to @code{hello_LDADD} in order to cause
1750 it to be built and linked in.
1752 An often simpler way to compile source files conditionally is to use
1753 Automake conditionals. For instance, you could use this construct to
1754 conditionally use @file{hello-linux.c} or @file{hello-generic.c} as the
1755 basis for your program @file{hello}:
1759 hello_SOURCES = hello-linux.c
1761 hello_SOURCES = hello-generic.c
1765 When using conditionals like this you don't need to use the
1766 @samp{EXTRA_} variable, because Automake will examine the contents of
1767 each variable to construct the complete list of source files.
1769 Sometimes it is useful to determine the programs that are to be built at
1770 configure time. For instance, GNU @code{cpio} only builds @code{mt} and
1771 @code{rmt} under special circumstances.
1773 @cindex EXTRA_PROGRAMS, defined
1775 In this case, you must notify Automake of all the programs that can
1776 possibly be built, but at the same time cause the generated
1777 @file{Makefile.in} to use the programs specified by @code{configure}.
1778 This is done by having @code{configure} substitute values into each
1779 @samp{_PROGRAMS} definition, while listing all optionally built programs
1780 in @code{EXTRA_PROGRAMS}.
1781 @vindex EXTRA_PROGRAMS
1783 Of course you can use Automake conditionals to determine the programs to
1786 @subsection Linking the program
1788 If you need to link against libraries that are not found by
1789 @code{configure}, you can use @code{LDADD} to do so. This variable
1790 actually can be used to add any options to the linker command line.
1793 @cindex prog_LDADD, defined
1795 Sometimes, multiple programs are built in one directory but do not share
1796 the same link-time requirements. In this case, you can use the
1797 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1798 program as it appears in some @samp{_PROGRAMS} variable, and usually
1799 written in lowercase) to override the global @code{LDADD}. If this
1800 variable exists for a given program, then that program is not linked
1804 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
1805 linked against the library @file{libcpio.a}. However, @code{rmt} is
1806 built in the same directory, and has no such link requirement. Also,
1807 @code{mt} and @code{rmt} are only built on certain architectures. Here
1808 is what cpio's @file{src/Makefile.am} looks like (abridged):
1811 bin_PROGRAMS = cpio pax @@MT@@
1812 libexec_PROGRAMS = @@RMT@@
1813 EXTRA_PROGRAMS = mt rmt
1815 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1818 cpio_SOURCES = @dots{}
1819 pax_SOURCES = @dots{}
1820 mt_SOURCES = @dots{}
1821 rmt_SOURCES = @dots{}
1824 @cindex _LDFLAGS, defined
1826 @samp{@var{prog}_LDADD} is inappropriate for passing program-specific
1827 linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
1828 @samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
1832 @cindex _DEPENDENCIES, defined
1834 It is also occasionally useful to have a program depend on some other
1835 target which is not actually part of that program. This can be done
1836 using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
1837 on the contents of such a variable, but no further interpretation is
1840 If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
1841 Automake. The automatically-assigned value is the contents of
1842 @samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
1843 @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
1844 configure substitutions that are left in are only @samp{@@LIBOBJS@@} and
1845 @samp{@@ALLOCA@@}; these are left because it is known that they will not
1846 cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
1850 @node A Library, A Shared Library, A Program, Programs
1851 @section Building a library
1853 @cindex _LIBRARIES primary, defined
1854 @cindex LIBRARIES primary, defined
1855 @cindex Primary variable, LIBRARIES
1857 @vindex lib_LIBRARIES
1858 @vindex pkglib_LIBRARIES
1859 @vindex noinst_LIBRARIES
1861 Building a library is much like building a program. In this case, the
1862 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
1863 @code{libdir} or @code{pkglibdir}.
1865 @xref{A Shared Library}, for information on how to build shared
1866 libraries using Libtool and the @samp{LTLIBRARIES} primary.
1868 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
1869 For instance to create a library named @file{libcpio.a}, but not install
1870 it, you would write:
1873 noinst_LIBRARIES = libcpio.a
1876 The sources that go into a library are determined exactly as they are
1877 for programs, via the @samp{_SOURCES} variables. Note that the library
1878 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
1879 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
1880 not @samp{liblob.a_SOURCES}.
1882 @cindex _LIBADD primary, defined
1883 @cindex LIBADD primary, defined
1884 @cindex Primary variable, LIBADD
1886 Extra objects can be added to a library using the
1887 @samp{@var{library}_LIBADD} variable. This should be used for objects
1888 determined by @code{configure}. Again from @code{cpio}:
1893 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
1896 In addition, sources for extra objects that will not exist until
1897 configure-time must be added to the @code{BUILT_SOURCES} variable
1901 @node A Shared Library, Program and Library Variables, A Library, Programs
1902 @section Building a Shared Library
1904 @cindex Shared libraries, support for
1906 Building shared libraries is a relatively complex matter. For this
1907 reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
1908 Libtool Manual}) was created to help build shared libraries in a
1909 platform-independent way.
1911 @cindex _LTLIBRARIES primary, defined
1912 @cindex LTLIBRARIES primary, defined
1913 @cindex Primary variable, LTLIBRARIES
1914 @cindex Example of shared libraries
1916 @cindex suffix .la, defined
1918 Automake uses Libtool to build libraries declared with the
1919 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
1920 of shared libraries to build. For instance, to create a library named
1921 @file{libgettext.a} and its corresponding shared libraries, and install
1922 them in @samp{libdir}, write:
1925 lib_LTLIBRARIES = libgettext.la
1928 @vindex lib_LTLIBRARIES
1929 @vindex pkglib_LTLIBRARIES
1930 @vindex noinst_LTLIBRARIES
1931 @vindex check_LTLIBRARIES
1933 @cindex check_LTLIBRARIES, not allowed
1935 Note that shared libraries @emph{must} be installed in order to work
1936 properly, so @code{check_LTLIBRARIES} is not allowed. However,
1937 @code{noinst_LTLIBRARIES} is allowed. This feature should be used for
1938 libtool ``convenience libraries''.
1940 @cindex suffix .lo, defined
1942 For each library, the @samp{@var{library}_LIBADD} variable contains the
1943 names of extra libtool objects (@file{.lo} files) to add to the shared
1944 library. The @samp{@var{library}_LDFLAGS} variable contains any
1945 additional libtool flags, such as @samp{-version-info} or
1948 @cindex @@LTLIBOBJS@@, special handling
1950 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
1951 library must use @code{@@LTLIBOBJS@@}. This is required because the
1952 object files that libtool operates on do not necessarily end in
1953 @file{.o}. The libtool manual contains more details on this topic.
1955 For libraries installed in some directory, Automake will automatically
1956 supply the appropriate @samp{-rpath} option. However, for libraries
1957 determined at configure time (and thus mentioned in
1958 @code{EXTRA_LTLIBRARIES}), Automake does not know the eventual
1959 installation directory; for such libraries you must add the
1960 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
1963 Ordinarily, Automake requires that a shared library's name start with
1964 @samp{lib}. However, if you are building a dynamically loadable module
1965 then you might wish to use a "nonstandard" name. In this case, put
1966 @code{-module} into the @samp{_LDFLAGS} variable.
1968 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
1969 libtool, The Libtool Manual}, for more information.
1972 @node Program and Library Variables, LIBOBJS, A Shared Library, Programs
1973 @section Program and Library Variables
1975 Associated with each program are a collection of variables which can be
1976 used to modify how that program is built. There is a similar list of
1977 such variables for each library. The canonical name of the program (or
1978 library) is used as a base for naming these variables.
1980 In the list below, we use the name ``maude'' to refer to the program or
1981 library. In your @file{Makefile.am} you would replace this with the
1982 canonical name of your program. This list also refers to ``maude'' as a
1983 program, but in general the same rules apply for both static and dynamic
1984 libraries; the documentation below notes situations where programs and
1989 This variable, if it exists, lists all the source files which are
1990 compiled to build the program. These files are added to the
1991 distribution by default. When building the program, Automake will cause
1992 each source file to be compiled to a single @file{.o} file (or
1993 @file{.lo} when using libtool). Normally these object files are named
1994 after the source file, but other factors can change this. If a file in
1995 the @samp{_SOURCES} variable has an unrecognized extension, Automake
1996 will do one of two things with it. If a suffix rule exists for turning
1997 files with the unrecognized extension into @file{.o} files, then
1998 automake will treat this file as it will any other source file
1999 (@pxref{Support for Other Languages}). Otherwise, the file will be
2000 ignored as though it were a header file.
2002 The prefixes @samp{dist_} and @samp{nodist_} can be used to control
2003 whether files listed in a @samp{_SOURCES} variable are distributed.
2004 @samp{dist_} is redundant, as sources are distributed by default, but it
2005 can be specified for clarity if desired.
2007 It is possible to have both @samp{dist_} and @samp{nodist_} variants of
2008 a given @samp{_SOURCES} variable at once; this lets you easily
2009 distribute some files and not others, for instance:
2012 nodist_maude_SOURCES = nodist.c
2013 dist_maude_SOURCES = dist-me.c
2016 By default the output file (on Unix systems, the @file{.o} file) will be
2017 put into the current build directory. However, if the option
2018 @code{subdir-objects} is in effect in the current directory then the
2019 @file{.o} file will be put into the subdirectory named after the source
2020 file. For instance, with @code{subdir-objects} enabled,
2021 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
2022 people prefer this mode of operation. You can specify
2023 @code{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
2024 @cindex Subdirectory, objects in
2025 @cindex Objects in subdirectory
2028 @item EXTRA_maude_SOURCES
2029 Automake needs to know the list of files you intend to compile
2030 @emph{statically}. For one thing, this is the only way Automake has of
2031 knowing what sort of language support a given @file{Makefile.in}
2032 requires. @footnote{There are other, more obscure reasons reasons for
2033 this limitation as well.} This means that, for example, you can't put a
2034 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
2035 variable. If you intend to conditionally compile source files and use
2036 @file{configure} to substitute the appropriate object names into, e.g.,
2037 @samp{_LDADD} (see below), then you should list the corresponding source
2038 files in the @samp{EXTRA_} variable.
2040 This variable also supports @samp{dist_} and @samp{nodist_} prefixes,
2041 e.g., @samp{nodist_EXTRA_maude_SOURCES}.
2044 A static library is created by default by invoking @code{$(AR) cru}
2045 followed by the name of the library and then the objects being put into
2046 the library. You can override this by setting the @samp{_AR} variable.
2047 This is usually used with C++; some C++ compilers require a special
2048 invocation in order to instantiate all the templates which should go
2049 into a library. For instance, the SGI C++ compiler likes this macro set
2052 libmaude_a_AR = $(CXX) -ar -o
2056 Extra objects can be added to a static library using the @samp{_LIBADD}
2057 variable. This should be used for objects determined by
2058 @code{configure}. Note that @samp{_LIBADD} is not used for shared
2059 libraries; there you must use @samp{_LDADD}.
2062 Extra objects can be added to a shared library or a program by listing
2063 them in the @samp{_LDADD} variable. This should be used for objects
2064 determined by @code{configure}.
2066 @samp{_LDADD} is inappropriate for passing program-specific linker flags
2067 (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen}).
2068 Use the @samp{_LDFLAGS} variable for this purpose.
2070 For instance, if your @file{configure.in} uses @code{AC_PATH_XTRA}, you
2071 could link your program against the X libraries like so:
2074 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
2078 This variable is used to pass extra flags to the link step of a program
2079 or a shared library.
2082 You can override the linker on a per-program basis. By default the
2083 linker is chosen according to the languages used by the program. For
2084 instance, a program that includes C++ source code would use the C++
2085 compiler to link. The @samp{_LINK} variable must hold the name of a
2086 command which can be passed all the @file{.o} file names as arguments.
2087 Note that the name of the underlying program is @emph{not} passed to
2088 @samp{_LINK}; typically one uses @samp{$@@}:
2091 maude_LINK = $(CCLD) -magic -o $@@
2095 Automake allows you to set compilation flags on a per-program (or
2096 per-library) basis. A single source file can be included in several
2097 programs, and it will potentially be compiled with different flags for
2098 each program. This works for any language directly supported by
2099 Automake. The flags are @samp{_CFLAGS}, @samp{_CXXFLAGS},
2100 @samp{_OBJCFLAGS}, @samp{_YFLAGS}, @samp{_ASFLAGS}, @samp{_FFLAGS},
2101 @samp{_RFLAGS}, and @samp{_GCJFLAGS}.
2103 When using a per-program compilation flag, Automake will choose a
2104 different name for the intermediate object files. Ordinarily a file
2105 like @file{sample.c} will be compiled to produce @file{sample.o}.
2106 However, if the program's @samp{_CFLAGS} variable is set, then the
2107 object file will be named, for instance, @file{maude-sample.o}.
2109 In compilations with per-program flags, the ordinary @samp{AM_} form of
2110 the flags variable is @emph{not} automatically included in the
2111 compilation (however, the user form of the variable @emph{is} included).
2112 So for instance, if you want the hypothetical @file{maude} compilations
2113 to also use the value of @samp{AM_CFLAGS}, you would need to write:
2116 maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
2119 @item maude_DEPENDENCIES
2120 It is also occasionally useful to have a program depend on some other
2121 target which is not actually part of that program. This can be done
2122 using the @samp{_DEPENDENCIES} variable. Each program depends on the
2123 contents of such a variable, but no further interpretation is done.
2125 If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake.
2126 The automatically-assigned value is the contents of @samp{_LDADD}, with
2127 most configure substitutions, @samp{-l}, @samp{-L}, @samp{-dlopen} and
2128 @samp{-dlpreopen} options removed. The configure substitutions that are
2129 left in are only @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are
2130 left because it is known that they will not cause an invalid value for
2131 @samp{_DEPENDENCIES} to be generated.
2133 @item maude_SHORTNAME
2134 On some platforms the allowable file names are very short. In order to
2135 support these systems and per-program compilation flags at the same
2136 time, Automake allows you to set a ``short name'' which will influence
2137 how intermediate object files are named. For instance, if you set
2138 @samp{maude_SHORTNAME} to @samp{m}, then in the above per-program
2139 compilation flag example the object file would be named
2140 @file{m-sample.o} rather than @file{maude-sample.o}. This facility is
2141 rarely needed in practice, and we recommend avoiding it until you find
2146 @node LIBOBJS, Program variables, Program and Library Variables, Programs
2147 @section Special handling for LIBOBJS and ALLOCA
2149 @cindex @@LIBOBJS@@, special handling
2150 @cindex @@ALLOCA@@, special handling
2152 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
2153 @code{@@ALLOCA@@}, and uses this information, plus the list of
2154 @code{LIBOBJS} files derived from @file{configure.in} to automatically
2155 include the appropriate source files in the distribution (@pxref{Dist}).
2156 These source files are also automatically handled in the
2157 dependency-tracking scheme; see @xref{Dependencies}.
2159 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
2160 @samp{_LDADD} or @samp{_LIBADD} variable.
2163 @node Program variables, Yacc and Lex, LIBOBJS, Programs
2164 @section Variables used when building a program
2166 Occasionally it is useful to know which @file{Makefile} variables
2167 Automake uses for compilations; for instance you might need to do your
2168 own compilation in some special cases.
2170 Some variables are inherited from Autoconf; these are @code{CC},
2171 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
2175 There are some additional variables which Automake itself defines:
2179 The contents of this macro are passed to every compilation which invokes
2180 the C preprocessor; it is a list of arguments to the preprocessor. For
2181 instance, @samp{-I} and @samp{-D} options should be listed here.
2183 Automake already provides some @samp{-I} options automatically. In
2184 particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I}
2185 pointing to the directory holding @file{config.h} (if you've used
2186 @code{AC_CONFIG_HEADER} or @code{AM_CONFIG_HEADER}). You can disable
2187 the default @samp{-I} options using the @samp{nostdinc} option.
2190 This does the same job as @samp{AM_CPPFLAGS}. It is an older name for
2191 the same functionality. This macro is deprecated; we suggest using
2192 @samp{AM_CPPFLAGS} instead.
2195 This is the variable which the @file{Makefile.am} author can use to pass
2196 in additional C compiler flags. It is more fully documented elsewhere.
2197 In some situations, this is not used, in preference to the
2198 per-executable (or per-library) @code{CFLAGS}.
2201 This is the command used to actually compile a C source file. The
2202 filename is appended to form the complete command line.
2205 This is the command used to actually link a C program. It already
2206 includes @samp{-o $@@} and the usual variable references (for instance,
2207 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
2208 and libraries to link in.
2212 @node Yacc and Lex, C++ Support, Program variables, Programs
2213 @section Yacc and Lex support
2215 Automake has somewhat idiosyncratic support for Yacc and Lex.
2217 Automake assumes that the @file{.c} file generated by @code{yacc} (or
2218 @code{lex}) should be named using the basename of the input file. That
2219 is, for a yacc source file @file{foo.y}, Automake will cause the
2220 intermediate file to be named @file{foo.c} (as opposed to
2221 @file{y.tab.c}, which is more traditional).
2223 The extension of a yacc source file is used to determine the extension
2224 of the resulting @samp{C} or @samp{C++} file. Files with the extension
2225 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
2226 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
2229 Likewise, lex source files can be used to generate @samp{C} or
2230 @samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
2231 @samp{.lxx} are recognized.
2233 You should never explicitly mention the intermediate (@samp{C} or
2234 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
2237 The intermediate files generated by @code{yacc} (or @code{lex}) will be
2238 included in any distribution that is made. That way the user doesn't
2239 need to have @code{yacc} or @code{lex}.
2241 If a @code{yacc} source file is seen, then your @file{configure.in} must
2242 define the variable @samp{YACC}. This is most easily done by invoking
2243 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
2244 Program Checks, autoconf, The Autoconf Manual}).
2246 When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
2247 @samp{AM_YFLAGS}. The former is a user variable and the latter is
2248 intended for the @file{Makefile.am} author.
2250 Similarly, if a @code{lex} source file is seen, then your
2251 @file{configure.in} must define the variable @samp{LEX}. You can use
2252 @samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
2253 Program Checks, autoconf, The Autoconf Manual}), but using
2254 @code{AM_PROG_LEX} macro (@pxref{Macros}) is recommended.
2256 When @code{lex} is invoked, it is passed @samp{LFLAGS} and
2257 @samp{AM_LFLAGS}. The former is a user variable and the latter is
2258 intended for the @file{Makefile.am} author.
2263 @cindex yacc, multiple parsers
2264 @cindex Multiple yacc parsers
2265 @cindex Multiple lex lexers
2266 @cindex lex, multiple lexers
2269 Automake makes it possible to include multiple @code{yacc} (or
2270 @code{lex}) source files in a single program. Automake uses a small
2271 program called @code{ylwrap} to run @code{yacc} (or @code{lex}) in a
2272 subdirectory. This is necessary because yacc's output filename is
2273 fixed, and a parallel make could conceivably invoke more than one
2274 instance of @code{yacc} simultaneously. The @code{ylwrap} program is
2275 distributed with Automake. It should appear in the directory specified
2276 by @samp{AC_CONFIG_AUX_DIR} (@pxref{Input, , Finding `configure' Input,
2277 autoconf, The Autoconf Manual}), or the current directory if that macro
2278 is not used in @file{configure.in}.
2280 For @code{yacc}, simply managing locking is insufficient. The output of
2281 @code{yacc} always uses the same symbol names internally, so it isn't
2282 possible to link two @code{yacc} parsers into the same executable.
2284 We recommend using the following renaming hack used in @code{gdb}:
2286 #define yymaxdepth c_maxdepth
2287 #define yyparse c_parse
2289 #define yyerror c_error
2290 #define yylval c_lval
2291 #define yychar c_char
2292 #define yydebug c_debug
2293 #define yypact c_pact
2300 #define yyexca c_exca
2301 #define yyerrflag c_errflag
2302 #define yynerrs c_nerrs
2306 #define yy_yys c_yys
2307 #define yystate c_state
2310 #define yy_yyv c_yyv
2312 #define yylloc c_lloc
2313 #define yyreds c_reds
2314 #define yytoks c_toks
2315 #define yylhs c_yylhs
2316 #define yylen c_yylen
2317 #define yydefred c_yydefred
2318 #define yydgoto c_yydgoto
2319 #define yysindex c_yysindex
2320 #define yyrindex c_yyrindex
2321 #define yygindex c_yygindex
2322 #define yytable c_yytable
2323 #define yycheck c_yycheck
2324 #define yyname c_yyname
2325 #define yyrule c_yyrule
2328 For each define, replace the @samp{c_} prefix with whatever you like.
2329 These defines work for @code{bison}, @code{byacc}, and traditional
2330 @code{yacc}s. If you find a parser generator that uses a symbol not
2331 covered here, please report the new name so it can be added to the list.
2334 @node C++ Support, Assembly Support, Yacc and Lex, Programs
2335 @section C++ Support
2338 @cindex Support for C++
2340 Automake includes full support for C++.
2342 Any package including C++ code must define the output variable
2343 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
2344 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
2345 Program Checks, autoconf, The Autoconf Manual}).
2347 A few additional variables are defined when a C++ source file is seen:
2351 The name of the C++ compiler.
2354 Any flags to pass to the C++ compiler.
2357 The maintainer's variant of @code{CXXFLAGS}.
2360 The command used to actually compile a C++ source file. The file name
2361 is appended to form the complete command line.
2364 The command used to actually link a C++ program.
2368 @node Assembly Support, Fortran 77 Support, C++ Support, Programs
2369 @section Assembly Support
2371 Automake includes some support for assembly code.
2373 The variable @code{AS} holds the name of the compiler used to build
2374 assembly code. This compiler must work a bit like a C compiler; in
2375 particular it must accept @samp{-c} and @samp{-o}. The value of
2376 @code{ASFLAGS} is passed to the compilation.
2380 You are required to set @code{AS} and @code{ASFLAGS} via
2381 @file{configure.in}. The autoconf macro @code{AM_PROG_AS} will do this
2382 for you. Unless they are already set, it simply sets @code{AS} to the C
2383 compiler and @code{ASFLAGS} to the C compiler flags.
2386 @node Fortran 77 Support, Java Support, Assembly Support, Programs
2387 @comment node-name, next, previous, up
2388 @section Fortran 77 Support
2390 @cindex Fortran 77 support
2391 @cindex Support for Fortran 77
2393 Automake includes full support for Fortran 77.
2395 Any package including Fortran 77 code must define the output variable
2396 @samp{F77} in @file{configure.in}; the simplest way to do this is to use
2397 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
2398 Program Checks, autoconf, The Autoconf Manual}). @xref{Fortran 77 and
2401 A few additional variables are defined when a Fortran 77 source file is
2407 The name of the Fortran 77 compiler.
2410 Any flags to pass to the Fortran 77 compiler.
2413 The maintainer's variant of @code{FFLAGS}.
2416 Any flags to pass to the Ratfor compiler.
2419 The maintainer's variant of @code{RFLAGS}.
2422 The command used to actually compile a Fortran 77 source file. The file
2423 name is appended to form the complete command line.
2426 The command used to actually link a pure Fortran 77 program or shared
2431 Automake can handle preprocessing Fortran 77 and Ratfor source files in
2432 addition to compiling them@footnote{Much, if not most, of the
2433 information in the following sections pertaining to preprocessing
2434 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
2435 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
2436 also contains some support for creating programs and shared libraries
2437 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
2438 Fortran 77 With C and C++}).
2440 These issues are covered in the following sections.
2443 * Preprocessing Fortran 77::
2444 * Compiling Fortran 77 Files::
2445 * Mixing Fortran 77 With C and C++::
2446 * Fortran 77 and Autoconf::
2450 @node Preprocessing Fortran 77, Compiling Fortran 77 Files, Fortran 77 Support, Fortran 77 Support
2451 @comment node-name, next, previous, up
2452 @subsection Preprocessing Fortran 77
2454 @cindex Preprocessing Fortran 77
2455 @cindex Fortran 77, Preprocessing
2456 @cindex Ratfor programs
2458 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
2459 rule runs just the preprocessor to convert a preprocessable Fortran 77
2460 or Ratfor source file into a strict Fortran 77 source file. The precise
2461 command used is as follows:
2466 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2469 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2474 @node Compiling Fortran 77 Files, Mixing Fortran 77 With C and C++, Preprocessing Fortran 77, Fortran 77 Support
2475 @comment node-name, next, previous, up
2476 @subsection Compiling Fortran 77 Files
2478 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
2479 @file{N.r} by running the Fortran 77 compiler. The precise command used
2485 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
2488 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2491 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2496 @node Mixing Fortran 77 With C and C++, Fortran 77 and Autoconf, Compiling Fortran 77 Files, Fortran 77 Support
2497 @comment node-name, next, previous, up
2498 @subsection Mixing Fortran 77 With C and C++
2500 @cindex Fortran 77, mixing with C and C++
2501 @cindex Mixing Fortran 77 with C and C++
2502 @cindex Linking Fortran 77 with C and C++
2504 @cindex Mixing Fortran 77 with C and/or C++
2506 Automake currently provides @emph{limited} support for creating programs
2507 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
2508 However, there are many other issues related to mixing Fortran 77 with
2509 other languages that are @emph{not} (currently) handled by Automake, but
2510 that are handled by other packages@footnote{For example,
2511 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
2512 addresses all of these inter-language issues, and runs under nearly all
2513 Fortran 77, C and C++ compilers on nearly all platforms. However,
2514 @code{cfortran} is not yet Free Software, but it will be in the next
2518 Automake can help in two ways:
2522 Automatic selection of the linker depending on which combinations of
2526 Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
2527 @samp{-l}) to pass to the automatically selected linker in order to link
2528 in the appropriate Fortran 77 intrinsic and run-time libraries.
2530 @cindex FLIBS, defined
2531 These extra Fortran 77 linker flags are supplied in the output variable
2532 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
2533 supplied with newer versions of Autoconf (Autoconf version 2.13 and
2534 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
2538 If Automake detects that a program or shared library (as mentioned in
2539 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
2540 code that is a mixture of Fortran 77 and C and/or C++, then it requires
2541 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
2542 @file{configure.in}, and that either @code{$(FLIBS)} or @code{@@FLIBS@@}
2543 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
2544 (for shared libraries) variables. It is the responsibility of the
2545 person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
2546 or @code{@@FLIBS@@} appears in the appropriate @code{_LDADD} or
2547 @code{_LIBADD} variable.
2549 @cindex Mixed language example
2550 @cindex Example, mixed language
2552 For example, consider the following @file{Makefile.am}:
2556 foo_SOURCES = main.cc foo.f
2557 foo_LDADD = libfoo.la @@FLIBS@@
2559 pkglib_LTLIBRARIES = libfoo.la
2560 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
2561 libfoo_la_LIBADD = $(FLIBS)
2564 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
2565 is mentioned in @file{configure.in}. Also, if @code{@@FLIBS@@} hadn't
2566 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
2567 Automake would have issued a warning.
2572 * How the Linker is Chosen::
2575 @node How the Linker is Chosen, , Mixing Fortran 77 With C and C++, Mixing Fortran 77 With C and C++
2576 @comment node-name, next, previous, up
2577 @subsubsection How the Linker is Chosen
2579 @cindex Automatic linker selection
2580 @cindex Selecting the linker automatically
2582 The following diagram demonstrates under what conditions a particular
2583 linker is chosen by Automake.
2585 For example, if Fortran 77, C and C++ source code were to be compiled
2586 into a program, then the C++ linker will be used. In this case, if the
2587 C or Fortran 77 linkers required any special libraries that weren't
2588 included by the C++ linker, then they must be manually added to an
2589 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
2595 code \ C C++ Fortran
2596 ----------------- +---------+---------+---------+
2600 +---------+---------+---------+
2604 +---------+---------+---------+
2608 +---------+---------+---------+
2612 +---------+---------+---------+
2614 C + Fortran | | | x |
2616 +---------+---------+---------+
2618 C++ + Fortran | | x | |
2620 +---------+---------+---------+
2622 C + C++ + Fortran | | x | |
2624 +---------+---------+---------+
2628 @node Fortran 77 and Autoconf, , Mixing Fortran 77 With C and C++, Fortran 77 Support
2629 @comment node-name, next, previous, up
2630 @subsection Fortran 77 and Autoconf
2632 The current Automake support for Fortran 77 requires a recent enough
2633 version of Autoconf that also includes support for Fortran 77. Full
2634 Fortran 77 support was added to Autoconf 2.13, so you will want to use
2635 that version of Autoconf or later.
2638 @node Java Support, Support for Other Languages, Fortran 77 Support, Programs
2639 @comment node-name, next, previous, up
2640 @section Java Support
2642 @cindex Java support
2643 @cindex Support for Java
2645 Automake includes support for compiled Java, using @code{gcj}, the Java
2646 front end to the GNU Compiler Collection.
2648 Any package including Java code to be compiled must define the output
2649 variable @samp{GCJ} in @file{configure.in}; the variable @samp{GCJFLAGS}
2650 must also be defined somehow (either in @file{configure.in} or
2651 @file{Makefile.am}). The simplest way to do this is to use the
2652 @code{AM_PROG_GCJ} macro.
2656 By default, programs including Java source files are linked with
2659 As always, the contents of @samp{AM_GCJFLAGS} are passed to every
2660 compilation invoking @code{gcj} (in its role as an ahead-of-time
2661 compiler -- when invoking it to create @file{.class} files,
2662 @samp{AM_JAVACFLAGS} is used instead). If it is necessary to pass
2663 options to @code{gcj} from @file{Makefile.am}, this macro, and not the
2664 user macro @samp{GCJFLAGS}, should be used.
2668 @code{gcj} can be used to compile @file{.java}, @file{.class},
2669 @file{.zip}, or @file{.jar} files.
2672 @node Support for Other Languages, ANSI, Java Support, Programs
2673 @comment node-name, next, previous, up
2674 @section Support for Other Languages
2676 Automake currently only includes full support for C, C++ (@pxref{C++
2677 Support}), Fortran 77 (@pxref{Fortran 77 Support}), and Java
2678 (@pxref{Java Support}). There is only rudimentary support for other
2679 languages, support for which will be improved based on user demand.
2681 Some limited support for adding your own languages is available via the
2682 suffix rule handling; see @ref{Suffixes}.
2685 @node ANSI, Dependencies, Support for Other Languages, Programs
2686 @section Automatic de-ANSI-fication
2688 @cindex de-ANSI-fication, defined
2690 Although the GNU standards allow the use of ANSI C, this can have the
2691 effect of limiting portability of a package to some older compilers
2692 (notably the SunOS C compiler).
2694 Automake allows you to work around this problem on such machines by
2695 @dfn{de-ANSI-fying} each source file before the actual compilation takes
2698 @vindex AUTOMAKE_OPTIONS
2701 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
2702 (@pxref{Options}) contains the option @code{ansi2knr} then code to
2703 handle de-ANSI-fication is inserted into the generated
2706 This causes each C source file in the directory to be treated as ANSI C.
2707 If an ANSI C compiler is available, it is used. If no ANSI C compiler
2708 is available, the @code{ansi2knr} program is used to convert the source
2709 files into K&R C, which is then compiled.
2711 The @code{ansi2knr} program is simple-minded. It assumes the source
2712 code will be formatted in a particular way; see the @code{ansi2knr} man
2715 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
2716 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
2717 these files are distributed with Automake. Also, the package
2718 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}
2720 @cvindex AM_C_PROTOTYPES
2722 Automake also handles finding the @code{ansi2knr} support files in some
2723 other directory in the current package. This is done by prepending the
2724 relative path to the appropriate directory to the @code{ansi2knr}
2725 option. For instance, suppose the package has ANSI C code in the
2726 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
2727 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
2728 @file{src/Makefile.am}:
2731 AUTOMAKE_OPTIONS = ../lib/ansi2knr
2734 If no directory prefix is given, the files are assumed to be in the
2737 Files mentioned in @code{LIBOBJS} which need de-ANSI-fication will not
2738 be automatically handled. That's because @code{configure} will generate
2739 an object name like @file{regex.o}, while @code{make} will be looking
2740 for @file{regex_.o} (when de-ANSI-fying). Eventually this problem will
2741 be fixed via @code{autoconf} magic, but for now you must put this code
2742 into your @file{configure.in}, just before the @code{AC_OUTPUT} call:
2745 # This is necessary so that .o files in LIBOBJS are also built via
2746 # the ANSI2KNR-filtering rules.
2747 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
2750 Note that automatic de-ANSI-fication will not work when the package is
2751 being built for a different host architecture. That is because automake
2752 currently has no way to build @code{ansi2knr} for the build machine.
2755 @node Dependencies, EXEEXT, ANSI, Programs
2756 @section Automatic dependency tracking
2758 As a developer it is often painful to continually update the
2759 @file{Makefile.in} whenever the include-file dependencies change in a
2760 project. Automake supplies a way to automatically track dependency
2763 @cindex Dependency tracking
2764 @cindex Automatic dependency tracking
2766 Automake always uses complete dependencies for a compilation, including
2767 system headers. Automake's model is that dependency computation should
2768 be a side effect of the build. To this end, dependencies are computed
2769 by running all compilations through a special wrapper program called
2770 @code{depcomp}. @code{depcomp} understands how to coax many different C
2771 and C++ compilers into generating dependency information in the format
2772 it requires. @code{automake -a} will install @code{depcomp} into your
2773 source tree for you. If @code{depcomp} can't figure out how to properly
2774 invoke your compiler, dependency tracking will simply be disabled for
2779 Experience with earlier versions of Automake @footnote{See
2780 @uref{http://sources.redhat.com/automake/dependencies.html} for more
2781 information on the history and experiences with automatic dependency
2782 tracking in Automake} taught us that it is not reliable to generate
2783 dependencies only on the maintainer's system, as configurations vary too
2784 much. So instead Automake implements dependency tracking at build time.
2786 Automatic dependency tracking can be suppressed by putting
2787 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}. Or, you
2788 can invoke @code{automake} with the @code{-i} option. Dependency
2789 tracking is enabled by default.
2791 @vindex AUTOMAKE_OPTIONS
2792 @opindex no-dependencies
2794 The person building your package also can choose to disable dependency
2795 tracking by configuring with @code{--disable-dependency-tracking}.
2797 @cindex Disabling dependency tracking
2798 @cindex Dependency tracking, disabling
2801 @node EXEEXT, , Dependencies, Programs
2802 @section Support for executable extensions
2804 @cindex Executable extension
2805 @cindex Extension, executable
2808 On some platforms, such as Windows, executables are expected to have an
2809 extension such as @samp{.exe}. On these platforms, some compilers (GCC
2810 among them) will automatically generate @file{foo.exe} when asked to
2811 generate @file{foo}.
2813 Automake provides mostly-transparent support for this. Unfortunately
2814 the support isn't completely transparent; if you want your package to
2815 support these platforms then you must assist.
2817 One thing you must be aware of is that, internally, Automake rewrites
2818 something like this:
2821 bin_PROGRAMS = liver
2827 bin_PROGRAMS = liver$(EXEEXT)
2830 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
2831 extension. @code{EXEEXT}
2833 However, Automake cannot apply this rewriting to @code{configure}
2834 substitutions. This means that if you are conditionally building a
2835 program using such a substitution, then your @file{configure.in} must
2836 take care to add @samp{$(EXEEXT)} when constructing the output variable.
2838 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
2839 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
2840 automatically if you configure a compiler (say, through
2843 Sometimes maintainers like to write an explicit link rule for their
2844 program. Without executable extension support, this is easy---you
2845 simply write a target with the same name as the program. However, when
2846 executable extension support is enabled, you must instead add the
2847 @samp{$(EXEEXT)} suffix.
2849 Unfortunately, due to the change in Autoconf 2.50, this means you must
2850 always add this extension. However, this is a problem for maintainers
2851 who know their package will never run on a platform that has executable
2852 extensions. For those maintainers, the @code{no-exeext} option
2853 (@pxref{Options}) will disable this feature. This works in a fairly
2854 ugly way; if @code{no-exeext} is seen, then the presence of a target
2855 named @code{foo} in @file{Makefile.am} will override an
2856 automake-generated target of the form @code{foo$(EXEEXT)}. Without the
2857 @code{no-exeext} option, this use will give an error.
2860 @node Other objects, Other GNU Tools, Programs, Top
2861 @chapter Other Derived Objects
2863 Automake can handle derived objects which are not C programs. Sometimes
2864 the support for actually building such objects must be explicitly
2865 supplied, but Automake will still automatically handle installation and
2869 * Scripts:: Executable scripts
2870 * Headers:: Header files
2871 * Data:: Architecture-independent data files
2872 * Sources:: Derived sources
2876 @node Scripts, Headers, Other objects, Other objects
2877 @section Executable Scripts
2879 @cindex _SCRIPTS primary, defined
2880 @cindex SCRIPTS primary, defined
2881 @cindex Primary variable, SCRIPTS
2883 It is possible to define and install programs which are scripts. Such
2884 programs are listed using the @samp{SCRIPTS} primary name. Automake
2885 doesn't define any dependencies for scripts; the @file{Makefile.am}
2886 should include the appropriate rules.
2889 Automake does not assume that scripts are derived objects; such objects
2890 must be deleted by hand (@pxref{Clean}).
2892 The @code{automake} program itself is a Perl script that is generated at
2893 configure time from @file{automake.in}. Here is how this is handled:
2896 bin_SCRIPTS = automake
2899 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
2900 for it is automatically generated.
2902 @cindex SCRIPTS, installation directories
2903 @cindex Installing scripts
2906 @vindex sbin_SCRIPTS
2907 @vindex libexec_SCRIPTS
2908 @vindex pkgdata_SCRIPTS
2909 @vindex noinst_SCRIPTS
2911 Script objects can be installed in @code{bindir}, @code{sbindir},
2912 @code{libexecdir}, or @code{pkgdatadir}.
2915 @node Headers, Data, Scripts, Other objects
2916 @section Header files
2918 @cindex _HEADERS primary, defined
2919 @cindex HEADERS primary, defined
2920 @cindex Primary variable, HEADERS
2922 @vindex noinst_HEADERS
2924 Header files are specified by the @samp{HEADERS} family of variables.
2925 Generally header files are not installed, so the @code{noinst_HEADERS}
2926 variable will be the most used. @footnote{However, for the case of a
2927 non-installed header file that is actually used by a particular program,
2928 we recommend listing it in the program's @samp{_SOURCES} variable
2929 instead of in @code{noinst_HEADERS}. We believe this is more clear.}
2932 All header files must be listed somewhere; missing ones will not appear
2933 in the distribution. Often it is clearest to list uninstalled headers
2934 with the rest of the sources for a program. @xref{A Program}. Headers
2935 listed in a @samp{_SOURCES} variable need not be listed in any
2936 @samp{_HEADERS} variable.
2938 @cindex HEADERS, installation directories
2939 @cindex Installing headers
2941 @vindex include_HEADERS
2942 @vindex oldinclude_HEADERS
2943 @vindex pkginclude_HEADERS
2945 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
2946 @code{pkgincludedir}.
2949 @node Data, Sources, Headers, Other objects
2950 @section Architecture-independent data files
2952 @cindex _DATA primary, defined
2953 @cindex DATA primary, defined
2954 @cindex Primary variable, DATA
2956 Automake supports the installation of miscellaneous data files using the
2957 @samp{DATA} family of variables.
2961 @vindex sysconf_DATA
2962 @vindex sharedstate_DATA
2963 @vindex localstate_DATA
2964 @vindex pkgdata_DATA
2966 Such data can be installed in the directories @code{datadir},
2967 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
2970 By default, data files are @emph{not} included in a distribution. Of
2971 course, you can use the @samp{dist_} prefix to change this on a
2974 Here is how Automake installs its auxiliary data files:
2977 pkgdata_DATA = clean-kr.am clean.am @dots{}
2981 @node Sources, , Data, Other objects
2982 @section Built sources
2984 @cindex BUILT_SOURCES, defined
2986 Occasionally a file which would otherwise be called @samp{source}
2987 (e.g. a C @samp{.h} file) is actually derived from some other file.
2988 Such files should be listed in the @code{BUILT_SOURCES} variable.
2989 @vindex BUILT_SOURCES
2991 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
2992 must be created early in the build process can be listed in this
2995 A source file listed in @code{BUILT_SOURCES} is created before the other
2996 @code{all} targets are made. However, such a source file is not
2997 compiled unless explicitly requested by mentioning it in some other
2998 @samp{_SOURCES} variable.
3000 So, for instance, if you had header files which were created by a script
3001 run at build time, then you would list these headers in
3002 @code{BUILT_SOURCES}, to ensure that they would be built before any
3003 other compilations (perhaps ones using these headers) were started.
3006 @node Other GNU Tools, Documentation, Other objects, Top
3007 @chapter Other GNU Tools
3009 Since Automake is primarily intended to generate @file{Makefile.in}s for
3010 use in GNU programs, it tries hard to interoperate with other GNU tools.
3013 * Emacs Lisp:: Emacs Lisp
3021 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
3024 @cindex _LISP primary, defined
3025 @cindex LISP primary, defined
3026 @cindex Primary variable, LISP
3032 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
3033 is used to hold a list of @file{.el} files. Possible prefixes for this
3034 primary are @samp{lisp_} and @samp{noinst_}. Note that if
3035 @code{lisp_LISP} is defined, then @file{configure.in} must run
3036 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
3040 By default Automake will byte-compile all Emacs Lisp source files using
3041 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
3042 byte-compiling, simply define the variable @code{ELCFILES} to be empty.
3043 Byte-compiled Emacs Lisp files are not portable among all versions of
3044 Emacs, so it makes sense to turn this off if you expect sites to have
3045 more than one version of Emacs installed. Furthermore, many packages
3046 don't actually benefit from byte-compilation. Still, we recommend that
3047 you leave it enabled by default. It is probably better for sites with
3048 strange setups to cope for themselves than to make the installation less
3049 nice for everybody else.
3052 @node gettext, Libtool, Emacs Lisp, Other GNU Tools
3055 @cindex GNU Gettext support
3056 @cindex Gettext support
3057 @cindex Support for GNU Gettext
3059 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
3060 turns on support for GNU gettext, a message catalog system for
3061 internationalization
3062 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
3064 The @code{gettext} support in Automake requires the addition of two
3065 subdirectories to the package, @file{intl} and @file{po}. Automake
3066 insures that these directories exist and are mentioned in
3070 @node Libtool, Java, gettext, Other GNU Tools
3073 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
3074 libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
3075 @xref{A Shared Library}.
3078 @node Java, Python, Libtool, Other GNU Tools
3081 @cindex _JAVA primary, defined
3082 @cindex JAVA primary, defined
3083 @cindex Primary variable, JAVA
3085 Automake provides some minimal support for Java compilation with the
3086 @samp{JAVA} primary.
3088 Any @file{.java} files listed in a @samp{_JAVA} variable will be
3089 compiled with @code{JAVAC} at build time. By default, @file{.class}
3090 files are not included in the distribution.
3092 @cindex JAVA restrictions
3093 @cindex Restrictions for JAVA
3095 Currently Automake enforces the restriction that only one @samp{_JAVA}
3096 primary can be used in a given @file{Makefile.am}. The reason for this
3097 restriction is that, in general, it isn't possible to know which
3098 @file{.class} files were generated from which @file{.java} files -- so
3099 it would be impossible to know which files to install where. For
3100 instance, a @file{.java} file can define multiple classes; the resulting
3101 @file{.class} file names cannot be predicted without parsing the
3104 There are a few variables which are used when compiling Java sources:
3108 The name of the Java compiler. This defaults to @samp{javac}.
3111 The flags to pass to the compiler. This is considered to be a user
3112 variable (@pxref{User Variables}).
3115 More flags to pass to the Java compiler. This, and not
3116 @code{JAVACFLAGS}, should be used when it is necessary to put Java
3117 compiler flags into @file{Makefile.am}.
3120 The value of this variable is passed to the @samp{-d} option to
3121 @code{javac}. It defaults to @samp{$(top_builddir)}.
3124 This variable is an @code{sh} expression which is used to set the
3125 @code{CLASSPATH} environment variable on the @code{javac} command line.
3126 (In the future we will probably handle class path setting differently.)
3130 @node Python, , Java, Other GNU Tools
3133 @cindex _PYTHON primary, defined
3134 @cindex PYTHON primary, defined
3135 @cindex Primary variable, PYTHON
3138 Automake provides support for Python compilation with the @samp{PYTHON}
3141 Any files listed in a @samp{_PYTHON} variable will be byte-compiled with
3142 @code{py-compile} at install time. @code{py-compile} actually creates
3143 both standard (@file{.pyc}) and byte-compiled (@file{.pyo}) versions of
3144 the source files. Note that because byte-compilation occurs at install
3145 time, any files listed in @samp{noinst_PYTHON} will not be compiled.
3146 Python source files are included in the distribution by default.
3148 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} which
3149 will determine some Python-related directory variables (see below). If
3150 have called @code{AM_PATH_PYTHON} from you @file{configure.in}, then you
3151 may use the following variables to list you Python source files in your
3152 variables: @samp{python_PYTHON}, @samp{pkgpython_PYTHON},
3153 @samp{pkgpython_PYTHON}, @samp{pyexecdir_PYTHON},
3154 @samp{pkgpyexecdir_PYTHON}, depending where you want your files
3157 @code{AM_PATH_PYTHON} takes a single optional argument. This argument,
3158 if present, is the minimum version of Python which can be used for this
3159 package. If the version of Python found on the system is older than the
3160 required version, then @code{AM_PATH_PYTHON} will cause an error.
3162 @code{AM_PATH_PYTHON} creates several output variables based on the
3163 Python installation found during configuration.
3167 The name of the Python executable.
3169 @item PYTHON_VERSION
3170 The Python version number, in the form @var{major}.@var{minor}
3171 (e.g. @samp{1.5}). This is currently the value of
3172 @code{sys.version[:3]}.
3175 The string @code{$prefix}. This term may be used in future work
3176 which needs the contents of Python's @code{sys.prefix}, but general
3177 consensus is to always use the value from configure.
3179 @item PYTHON_EXEC_PREFIX
3180 The string @code{$exec_prefix}. This term may be used in future work
3181 which needs the contents of Python's @code{sys.exec_prefix}, but general
3182 consensus is to always use the value from configure.
3184 @item PYTHON_PLATFORM
3185 The canonical name used by Python to describe the operating system, as
3186 given by @code{sys.platform}. This value is sometimes needed when
3187 building Python extensions.
3190 The directory name for the @file{site-packages} subdirectory of the
3191 standard Python install tree.
3194 This is is the directory under @code{pythondir} which is named after the
3195 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
3199 This is the directory where Python extension modules (shared libraries)
3200 should be installed.
3203 This is a convenience variable which is defined as
3204 @samp{$(pyexecdir)/$(PACKAGE)}.
3208 @node Documentation, Install, Other GNU Tools, Top
3209 @chapter Building documentation
3211 Currently Automake provides support for Texinfo and man pages.
3215 * Man pages:: Man pages
3219 @node Texinfo, Man pages, Documentation, Documentation
3222 @cindex _TEXINFOS primary, defined
3223 @cindex TEXINFOS primary, defined
3224 @cindex Primary variable, TEXINFOS
3226 If the current directory contains Texinfo source, you must declare it
3227 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
3228 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
3229 here. Any Texinfo source file must end in the @file{.texi},
3230 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
3233 @vindex info_TEXINFOS
3235 @cindex Texinfo macro, VERSION
3236 @cindex Texinfo macro, UPDATED
3237 @cindex Texinfo macro, EDITION
3238 @cindex Texinfo macro, UPDATED-MONTH
3240 @cindex VERSION Texinfo macro
3241 @cindex UPDATED Texinfo macro
3242 @cindex EDITION Texinfo macro
3243 @cindex UPDATED-MONTH Texinfo macro
3247 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
3248 that file will be automatically generated. The file @file{version.texi}
3249 defines four Texinfo macros you can reference:
3254 Both of these macros hold the version number of your program. They are
3255 kept separate for clarity.
3258 This holds the date the primary @file{.texi} file was last modified.
3261 This holds the name of the month in which the primary @file{.texi} file
3265 The @file{version.texi} support requires the @code{mdate-sh} program;
3266 this program is supplied with Automake and automatically included when
3267 @code{automake} is invoked with the @code{--add-missing} option.
3269 If you have multiple Texinfo files, and you want to use the
3270 @file{version.texi} feature, then you have to have a separate version
3271 file for each Texinfo file. Automake will treat any include in a
3272 Texinfo file that matches @samp{vers*.texi} just as an automatically
3273 generated version file.
3275 When an info file is rebuilt, the program named by the @code{MAKEINFO}
3276 variable is used to invoke it. If the @code{makeinfo} program is found
3277 on the system then it will be used by default; otherwise @code{missing}
3278 will be used instead. The flags in the variables @code{MAKEINFOFLAGS}
3279 and @code{AM_MAKEINFOFLAGS} will be passed to the @code{makeinfo}
3280 invocation; the first of these is intended for use by the user
3281 (@pxref{User Variables}) and the second by the @file{Makefile.am}
3284 @vindex MAKEINFOFLAGS
3285 @vindex AM_MAKEINFOFLAGS
3287 Sometimes an info file actually depends on more than one @file{.texi}
3288 file. For instance, in GNU Hello, @file{hello.texi} includes the file
3289 @file{gpl.texi}. You can tell Automake about these dependencies using
3290 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
3295 info_TEXINFOS = hello.texi
3296 hello_TEXINFOS = gpl.texi
3301 By default, Automake requires the file @file{texinfo.tex} to appear in
3302 the same directory as the Texinfo source. However, if you used
3303 @code{AC_CONFIG_AUX_DIR} in @file{configure.in} (@pxref{Input, , Finding
3304 `configure' Input, autoconf, The Autoconf Manual}), then
3305 @file{texinfo.tex} is looked for there. Automake supplies
3306 @file{texinfo.tex} if @samp{--add-missing} is given.
3310 If your package has Texinfo files in many directories, you can use the
3311 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
3312 @file{texinfo.tex} for your package. The value of this variable should
3313 be the relative path from the current @file{Makefile.am} to
3317 TEXINFO_TEX = ../doc/texinfo.tex
3320 @opindex no-texinfo.tex
3322 The option @samp{no-texinfo.tex} can be used to eliminate the
3323 requirement for @file{texinfo.tex}. Use of the variable
3324 @code{TEXINFO_TEX} is preferable, however, because that allows the
3325 @code{dvi} target to still work.
3327 @cindex Target, install-info
3328 @cindex Target, noinstall-info
3329 @cindex install-info target
3330 @cindex noinstall-info target
3332 @opindex no-installinfo
3333 @trindex install-info
3335 Automake generates an @code{install-info} target; some people apparently
3336 use this. By default, info pages are installed by @samp{make install}.
3337 This can be prevented via the @code{no-installinfo} option.
3340 @node Man pages, , Texinfo, Documentation
3343 @cindex _MANS primary, defined
3344 @cindex MANS primary, defined
3345 @cindex Primary variable, MANS
3347 A package can also include man pages (but see the GNU standards on this
3348 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
3349 pages are declared using the @samp{MANS} primary. Generally the
3350 @code{man_MANS} macro is used. Man pages are automatically installed in
3351 the correct subdirectory of @code{mandir}, based on the file extension.
3355 File extensions such as @samp{.1c} are handled by looking for the valid
3356 part of the extension and using that to determine the correct
3357 subdirectory of @code{mandir}. Valid section names are the digits
3358 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
3360 Sometimes developers prefer to name a man page something like
3361 @file{foo.man} in the source, and then rename it to have the correct
3362 suffix, e.g. @file{foo.1}, when installing the file. Automake also
3363 supports this mode. For a valid section named @var{SECTION}, there is a
3364 corresponding directory named @samp{man@var{SECTION}dir}, and a
3365 corresponding @samp{_MANS} variable. Files listed in such a variable
3366 are installed in the indicated section. If the file already has a
3367 valid suffix, then it is installed as-is; otherwise the file suffix is
3368 changed to match the section.
3370 For instance, consider this example:
3372 man1_MANS = rename.man thesame.1 alsothesame.1c
3375 In this case, @file{rename.man} will be renamed to @file{rename.1} when
3376 installed, but the other files will keep their names.
3378 @cindex Target, install-man
3379 @cindex Target, noinstall-man
3380 @cindex install-man target
3381 @cindex noinstall-man target
3383 @c Use @samp{make install} per documentation: (texi)code.
3384 By default, man pages are installed by @samp{make install}. However,
3385 since the GNU project does not require man pages, many maintainers do
3386 not expend effort to keep the man pages up to date. In these cases, the
3387 @code{no-installman} option will prevent the man pages from being
3388 installed by default. The user can still explicitly install them via
3389 @samp{make install-man}.
3390 @opindex no-installman
3391 @trindex install-man
3393 Here is how the man pages are handled in GNU @code{cpio} (which includes
3394 both Texinfo documentation and man pages):
3397 man_MANS = cpio.1 mt.1
3398 EXTRA_DIST = $(man_MANS)
3401 Man pages are not currently considered to be source, because it is not
3402 uncommon for man pages to be automatically generated. Therefore they
3403 are not automatically included in the distribution. However, this can
3404 be changed by use of the @samp{dist_} prefix.
3406 The @samp{nobase_} prefix is meaningless for man pages and is
3410 @node Install, Clean, Documentation, Top
3411 @chapter What Gets Installed
3413 @cindex Installation support
3414 @cindex make install support
3416 @section Basics of installation
3418 Naturally, Automake handles the details of actually installing your
3419 program once it has been built. All files named by the various
3420 primaries are automatically installed in the appropriate places when the
3421 user runs @code{make install}.
3423 A file named in a primary is installed by copying the built file into
3424 the appropriate directory. The base name of the file is used when
3428 bin_PROGRAMS = hello subdir/goodbye
3431 In this example, both @samp{hello} and @samp{goodbye} will be installed
3432 in @code{$(bindir)}.
3434 Sometimes it is useful to avoid the basename step at install time. For
3435 instance, you might have a number of header files in subdirectories of
3436 the source tree which are laid out precisely how you want to install
3437 them. In this situation you can use the @samp{nobase_} prefix to
3438 suppress the base name step. For example:
3441 nobase_include_HEADERS = stdio.h sys/types.h
3444 Will install @file{stdio.h} in @code{$(includedir)} and @file{types.h}
3445 in @code{$(includedir)/sys}.
3447 @section The two parts of install
3449 Automake generates separate @code{install-data} and @code{install-exec}
3450 targets, in case the installer is installing on multiple machines which
3451 share directory structure---these targets allow the machine-independent
3452 parts to be installed only once. @code{install-exec} installs
3453 platform-dependent files, and @code{install-data} installs
3454 platform-independent files. The @code{install} target depends on both
3455 of these targets. While Automake tries to automatically segregate
3456 objects into the correct category, the @file{Makefile.am} author is, in
3457 the end, responsible for making sure this is done correctly.
3458 @trindex install-data
3459 @trindex install-exec
3461 @cindex Install, two parts of
3463 Variables using the standard directory prefixes @samp{data},
3464 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
3465 @samp{pkgdata}, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
3466 installed by @samp{install-data}.
3468 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
3469 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
3470 @samp{pkglib} (e.g. @samp{bin_PROGRAMS}) are installed by
3471 @samp{install-exec}.
3473 Any variable using a user-defined directory prefix with @samp{exec} in
3474 the name (e.g. @samp{myexecbin_PROGRAMS} is installed by
3475 @samp{install-exec}. All other user-defined prefixes are installed by
3476 @samp{install-data}.
3478 @section Extending installation
3480 It is possible to extend this mechanism by defining an
3481 @code{install-exec-local} or @code{install-data-local} target. If these
3482 targets exist, they will be run at @samp{make install} time. These
3483 rules can do almost anything; care is required.
3484 @trindex install-exec-local
3485 @trindex install-data-local
3487 Automake also supports two install hooks, @code{install-exec-hook} and
3488 @code{install-data-hook}. These hooks are run after all other install
3489 rules of the appropriate type, exec or data, have completed. So, for
3490 instance, it is possible to perform post-installation modifications
3491 using an install hook.
3492 @cindex Install hook
3494 @section Staged installs
3497 Automake generates support for the @samp{DESTDIR} variable in all
3498 install rules. @samp{DESTDIR} is used during the @samp{make install}
3499 step to relocate install objects into a staging area. Each object and
3500 path is prefixed with the value of @samp{DESTDIR} before being copied
3501 into the install area. Here is an example of typical DESTDIR usage:
3504 make DESTDIR=/tmp/staging install
3507 This places install objects in a directory tree built under
3508 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
3509 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
3510 would install @file{/tmp/staging/gnu/bin/foo} and
3511 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
3513 This feature is commonly used to build install images and packages. For
3514 more information, see @ref{Makefile Conventions, , , standards, The GNU
3517 Support for @samp{DESTDIR} is implemented by coding it directly into the
3518 install rules. If your @file{Makefile.am} uses a local install rule
3519 (e.g., @code{install-exec-local}) or an install hook, then you must
3520 write that code to respect @samp{DESTDIR}.
3522 @section Rules for the user
3524 Automake also generates an @code{uninstall} target, an
3525 @code{installdirs} target, and an @code{install-strip} target.
3527 @trindex installdirs
3528 @trindex install-strip
3530 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
3531 There is no notion of separate uninstalls for ``exec'' and ``data'', as
3532 that does not make sense.
3534 Note that @code{uninstall} is not meant as a replacement for a real
3538 @node Clean, Dist, Install, Top
3539 @chapter What Gets Cleaned
3541 @cindex make clean support
3543 The GNU Makefile Standards specify a number of different clean rules.
3545 Generally the files that can be cleaned are determined automatically by
3546 Automake. Of course, Automake also recognizes some variables that can
3547 be defined to specify additional files to clean. These variables are
3548 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
3549 @code{MAINTAINERCLEANFILES}.
3550 @vindex MOSTLYCLEANFILES
3552 @vindex DISTCLEANFILES
3553 @vindex MAINTAINERCLEANFILES
3555 As the GNU Standards aren't always explicit as to which files should be
3556 removed by which target, we've adopted a heuristic which we believe was
3557 first formulated by Fran@,{c}ois Pinard:
3561 If @code{make} built it, and it is commonly something that one would
3562 want to rebuild (for instance, a @file{.o} file), then
3563 @code{mostlyclean} should delete it.
3566 Otherwise, if @code{make} built it, then @code{clean} should delete it.
3569 If @code{configure} built it, then @code{distclean} should delete it
3572 If the maintainer built it, then @code{maintainer-clean} should
3576 We recommend that you follow this same set of heuristics in your
3580 @node Dist, Tests, Clean, Top
3581 @chapter What Goes in a Distribution
3583 @section Basics of distribution
3586 @cindex make distcheck
3588 The @code{dist} target in the generated @file{Makefile.in} can be used
3589 to generate a gzip'd @code{tar} file and other flavors of archive for
3590 distribution. The files is named based on the @samp{PACKAGE} and
3591 @samp{VERSION} variables; more precisely the gzip'd @code{tar} file is
3592 named @samp{@var{package}-@var{version}.tar.gz}.
3596 You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
3597 is run. The default setting is @samp{--best}.
3599 For the most part, the files to distribute are automatically found by
3600 Automake: all source files are automatically included in a distribution,
3601 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
3602 has a built-in list of commonly used files which, if present in the
3603 current directory, are automatically included. This list is printed by
3604 @samp{automake --help}. Also, files which are read by @code{configure}
3605 (i.e. the source files corresponding to the files specified in the
3606 @code{AC_OUTPUT} invocation) are automatically distributed.
3608 Still, sometimes there are files which must be distributed, but which
3609 are not covered in the automatic rules. These files should be listed in
3610 the @code{EXTRA_DIST} variable. You can mention files from
3611 subdirectories in @code{EXTRA_DIST}.
3613 You can also mention a directory in @code{EXTRA_DIST}; in this case the
3614 entire directory will be recursively copied into the distribution.
3615 Please note that this will also copy @emph{everything} in the directory,
3616 including CVS/RCS version control files. We recommend against using
3621 @section Fine-grained distribution control
3623 Sometimes you need tighter control over what does @emph{not} go into the
3624 distribution; for instance you might have source files which are
3625 generated and which you do not want to distribute. In this case
3626 Automake gives fine-grained control using the @samp{dist} and
3627 @samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
3628 prefixed with @samp{dist_} to add the listed files to the distribution.
3629 Similarly, @samp{nodist_} can be used to omit the files from the
3634 As an example, here is how you would cause some data to be distributed
3635 while leaving some source code out of the distribution:
3638 dist_data_DATA = distribute-this
3640 nodist_foo_SOURCES = do-not-distribute.c
3643 @section The dist hook
3645 Another way to to use this is for removing unnecessary files that get
3646 recursively included by specifying a directory in EXTRA_DIST:
3652 rm -rf `find $(distdir)/doc -name CVS`
3655 If you define @code{SUBDIRS}, Automake will recursively include the
3656 subdirectories in the distribution. If @code{SUBDIRS} is defined
3657 conditionally (@pxref{Conditionals}), Automake will normally include all
3658 directories that could possibly appear in @code{SUBDIRS} in the
3659 distribution. If you need to specify the set of directories
3660 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
3661 list of subdirectories to include in the distribution.
3662 @vindex DIST_SUBDIRS
3666 Occasionally it is useful to be able to change the distribution before
3667 it is packaged up. If the @code{dist-hook} target exists, it is run
3668 after the distribution directory is filled, but before the actual tar
3669 (or shar) file is created. One way to use this is for distributing
3670 files in subdirectories for which a new @file{Makefile.am} is overkill:
3674 mkdir $(distdir)/random
3675 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
3678 @section Checking the distribution
3680 Automake also generates a @code{distcheck} target which can be of help
3681 to ensure that a given distribution will actually work.
3682 @code{distcheck} makes a distribution, and then tries to do a
3686 If the target @code{distcheck-hook} is defined in your
3687 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
3688 the new distribution has been unpacked, but before the unpacked copy is
3689 configured and built. Your @code{distcheck-hook} can do almost
3690 anything, though as always caution is advised. Generally this hook is
3691 used to check for potential distribution errors not caught by the
3694 @section The types of distributions
3697 Automake generates a @samp{.tar.gz} file when asked to create a
3698 distribution and other archives formats, @ref{Options}. The target
3699 @code{dist-gzip} generates the @samp{.tar.gz} file only.
3702 @node Tests, Options, Dist, Top
3703 @chapter Support for test suites
3708 Automake supports two forms of test suites.
3710 @section Simple Tests
3712 If the variable @code{TESTS} is defined, its value is taken to be a list
3713 of programs to run in order to do the testing. The programs can either
3714 be derived objects or source objects; the generated rule will look both
3715 in @code{srcdir} and @file{.}. Programs needing data files should look
3716 for them in @code{srcdir} (which is both an environment variable and a
3717 make variable) so they work when building in a separate directory
3718 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
3719 Manual}), and in particular for the @code{distcheck} target
3722 @cindex Exit status 77, special interpretation
3724 The number of failures will be printed at the end of the run. If a
3725 given test program exits with a status of 77, then its result is ignored
3726 in the final count. This feature allows non-portable tests to be
3727 ignored in environments where they don't make sense.
3729 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
3730 variables for the test run; the environment variable @code{srcdir} is
3731 set in the rule. If all your test programs are scripts, you can also
3732 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
3733 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
3735 @vindex TESTS_ENVIRONMENT
3737 @cindex Tests, expected failure
3738 @cindex Expected test failure
3740 You may define the variable @code{XFAIL_TESTS} to a list of tests
3741 (usually a subset of @code{TESTS}) that are expected to fail. This will
3742 reverse the result of those tests.
3745 Automake ensures that each program listed in @code{TESTS} is built
3746 before any tests are run; you can list both source and derived programs
3747 in @code{TESTS}. For instance, you might want to run a C program as a
3748 test. To do this you would list its name in @code{TESTS} and also in
3749 @code{check_PROGRAMS}, and then specify it as you would any other
3752 @section DejaGNU Tests
3754 If @uref{ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz,
3755 @samp{dejagnu}} appears in @code{AUTOMAKE_OPTIONS}, then a
3756 @code{dejagnu}-based test suite is assumed. The variable
3757 @code{DEJATOOL} is a list of names which are passed, one at a time, as
3758 the @code{--tool} argument to @code{runtest} invocations; it defaults to
3759 the name of the package.
3761 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
3762 @code{--srcdir} flags that are passed to dejagnu by default; this can be
3763 overridden if necessary.
3764 @vindex RUNTESTDEFAULTFLAGS
3766 The variables @code{EXPECT} and @code{RUNTEST} can
3767 also be overridden to provide project-specific values. For instance,
3768 you will need to do this if you are testing a compiler toolchain,
3769 because the default values do not take into account host and target
3776 The contents of the variable @code{RUNTESTFLAGS} are passed to the
3777 @code{runtest} invocation. This is considered a ``user variable''
3778 (@pxref{User Variables}). If you need to set @code{runtest} flags in
3779 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
3780 @vindex RUNTESTFLAGS
3781 @vindex AM_RUNTESTFLAGS
3782 @c FIXME xref dejagnu
3784 In either case, the testing is done via @samp{make check}.
3787 @node Options, Miscellaneous, Tests, Top
3788 @chapter Changing Automake's Behavior
3790 Various features of Automake can be controlled by options in the
3791 @file{Makefile.am}. Such options are listed in a special variable named
3792 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
3793 @vindex AUTOMAKE_OPTIONS
3798 @itemx @code{foreign}
3799 @itemx @code{cygnus}
3800 @cindex Option, gnits
3802 @cindex Option, foreign
3803 @cindex Option, cygnus
3805 Set the strictness as appropriate. The @code{gnits} option also implies
3806 @code{readme-alpha} and @code{check-news}.
3808 @item @code{ansi2knr}
3809 @itemx @code{@var{path}/ansi2knr}
3810 @cindex Option, ansi2knr
3811 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
3812 path, the generated @file{Makefile.in} will look in the specified
3813 directory to find the @file{ansi2knr} program. The path should be a
3814 relative path to another directory in the same distribution (Automake
3815 currently does not check this).
3817 @item @code{check-news}
3818 @cindex Option, check-news
3819 Cause @code{make dist} to fail unless the current version number appears
3820 in the first few lines of the @file{NEWS} file.
3822 @item @code{dejagnu}
3823 @cindex Option, dejagnu
3824 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
3826 @item @code{dist-bzip2}
3827 @cindex Option, dist-bzip2
3828 Generate a @code{dist-bzip2} target, creating a bzip2 tar archive of the
3829 distribution. @code{dist} will create it in addition to the other
3830 formats. bzip2 archives are frequently smaller than gzipped archives.
3833 @item @code{dist-shar}
3834 @cindex Option, dist-shar
3835 Generate a @code{dist-shar} target, creating a shar archive of the
3836 distribution. @code{dist} will create it in addition to the other
3840 @item @code{dist-zip}
3841 @cindex Option, dist-zip
3842 Generate a @code{dist-zip} target, creating a zip archive of the
3843 distribution. @code{dist} will create it in addition to the other
3847 @item @code{dist-tarZ}
3848 @cindex Option, dist-tarZ
3849 Generate a @code{dist-tarZ} target, creating a compressed tar archive of
3850 the distribution. @code{dist} will create it in addition to the other
3854 @item @code{no-dependencies}
3855 @cindex Option, no-dependencies
3856 This is similar to using @samp{--include-deps} on the command line, but
3857 is useful for those situations where you don't have the necessary bits
3858 to make automatic dependency tracking work @xref{Dependencies}. In this
3859 case the effect is to effectively disable automatic dependency tracking.
3861 @item @code{no-exeext}
3862 @cindex Option, no-exeext
3863 If your @file{Makefile.am} defines a target @samp{foo}, it will override
3864 a target named @samp{foo$(EXEEXT)}. This is necessary when
3865 @code{EXEEXT} is found to be empty. However, by default automake will
3866 generate an error for this use. The @code{no-exeext} option will
3867 disable this error. This is intended for use only where it is known in
3868 advance that the package will not be ported to Windows, or any other
3869 operating system using extensions on executables.
3871 @item @code{no-installinfo}
3872 @cindex Option, no-installinfo
3873 The generated @file{Makefile.in} will not cause info pages to be built
3874 or installed by default. However, @code{info} and @code{install-info}
3875 targets will still be available. This option is disallowed at
3876 @samp{GNU} strictness and above.
3878 @trindex install-info
3880 @item @code{no-installman}
3881 @cindex Option, no-installman
3882 The generated @file{Makefile.in} will not cause man pages to be
3883 installed by default. However, an @code{install-man} target will still
3884 be available for optional installation. This option is disallowed at
3885 @samp{GNU} strictness and above.
3886 @trindex install-man
3888 @item @code{nostdinc}
3889 @cindex Option, nostdinc
3890 This option can be used to disable the standard @samp{-I} options which
3891 are ordinarily automatically provided by Automake.
3893 @item @code{no-texinfo.tex}
3894 @cindex Option, no-texinfo
3895 Don't require @file{texinfo.tex}, even if there are texinfo files in
3898 @item @code{readme-alpha}
3899 @cindex Option, readme-alpha
3900 If this release is an alpha release, and the file @file{README-alpha}
3901 exists, then it will be added to the distribution. If this option is
3902 given, version numbers are expected to follow one of two forms. The
3903 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
3904 element is a number; the final period and number should be left off for
3905 non-alpha releases. The second form is
3906 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
3907 letter; it should be omitted for non-alpha releases.
3909 @item @code{subdir-objects}
3910 If this option is specified, then objects are placed into the
3911 subdirectory of the build directory corresponding to the subdirectory of
3912 the source file. For instance if the source file is
3913 @file{subdir/file.cxx}, then the output file would be
3914 @file{subdir/file.o}.
3917 @cindex Option, version
3918 A version number (e.g. @samp{0.30}) can be specified. If Automake is not
3919 newer than the version specified, creation of the @file{Makefile.in}
3923 Unrecognized options are diagnosed by @code{automake}.
3926 @node Miscellaneous, Include, Options, Top
3927 @chapter Miscellaneous Rules
3929 There are a few rules and variables that didn't fit anywhere else.
3932 * Tags:: Interfacing to etags and mkid
3933 * Suffixes:: Handling new file extensions
3934 * Multilibs:: Support for multilibbing.
3938 @node Tags, Suffixes, Miscellaneous, Miscellaneous
3939 @section Interfacing to @code{etags}
3941 @cindex TAGS support
3943 Automake will generate rules to generate @file{TAGS} files for use with
3944 GNU Emacs under some circumstances.
3946 If any C, C++ or Fortran 77 source code or headers are present, then
3947 @code{tags} and @code{TAGS} targets will be generated for the directory.
3950 At the topmost directory of a multi-directory package, a @code{tags}
3951 target file will be generated which, when run, will generate a
3952 @file{TAGS} file that includes by reference all @file{TAGS} files from
3955 The @code{tags} target will also be generated if the variable
3956 @code{ETAGS_ARGS} is defined. This variable is intended for use in
3957 directories which contain taggable source that @code{etags} does not
3961 Here is how Automake generates tags for its source, and for nodes in its
3965 ETAGS_ARGS = automake.in --lang=none \
3966 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
3969 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
3970 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
3971 are added directly to the dependencies for the @code{tags} target.
3972 @vindex TAGS_DEPENDENCIES
3974 Automake will also generate an @code{ID} target which will run
3975 @code{mkid} on the source. This is only supported on a
3976 directory-by-directory basis.
3979 Automake also supports the @uref{http://www.gnu.org/software/global/,
3980 GNU Global Tags program}. The @code{GTAGS} target runs Global Tags
3981 automatically and puts the result in the top build directory. The
3982 variable @code{GTAGS_ARGS} holds arguments which are passed to
3987 @node Suffixes, Multilibs, Tags, Miscellaneous
3988 @section Handling new file extensions
3990 @cindex Adding new SUFFIXES
3991 @cindex SUFFIXES, adding
3993 It is sometimes useful to introduce a new implicit rule to handle a file
3994 type that Automake does not know about. If this is done, you must
3995 notify GNU Make of the new suffixes. This can be done by putting a list
3996 of new suffixes in the @code{SUFFIXES} variable.
3999 For instance, suppose you had a compiler which could compile @samp{.foo}
4000 files to @samp{.o} files. Then you would add @samp{.foo} to your suffix
4007 Then you could directly use a @samp{.foo} file in a @samp{_SOURCES}
4008 variable and expect the correct results:
4012 doit_SOURCES = doit.foo
4015 Any given @code{SUFFIXES} go at the start of the generated suffixes
4016 list, followed by automake generated suffixes not already in the list.
4019 @node Multilibs, , Suffixes, Miscellaneous
4020 @section Support for Multilibs
4022 Automake has support for an obscure feature called multilibs. A
4023 @dfn{multilib} is a library which is built for multiple different ABIs
4024 at a single time; each time the library is built with a different target
4025 flag combination. This is only useful when the library is intended to
4026 be cross-compiled, and it is almost exclusively used for compiler
4029 The multilib support is still experimental. Only use it if you are
4030 familiar with multilibs and can debug problems you might encounter.
4033 @node Include, Conditionals, Miscellaneous, Top
4037 @cindex Including Makefile fragment
4038 @cindex Makefile fragment, including
4040 Automake supports an @code{include} directive which can be used to
4041 include other @file{Makefile} fragments when @code{automake} is run.
4042 Note that these fragments are read and interpreted by @code{automake},
4043 not by @code{make}. As with conditionals, @code{make} has no idea that
4044 @code{include} is in use.
4046 There are two forms of @code{include}:
4049 @item include $(srcdir)/file
4050 Include a fragment which is found relative to the current source
4053 @item include $(top_srcdir)/file
4054 Include a fragment which is found relative to the top source directory.
4057 Note that if a fragment is included inside a conditional, then the
4058 condition applies to the entire contents of that fragment.
4061 @node Conditionals, Gnits, Include, Top
4062 @chapter Conditionals
4064 @cindex Conditionals
4066 Automake supports a simple type of conditionals.
4068 @cvindex AM_CONDITIONAL
4069 Before using a conditional, you must define it by using
4070 @code{AM_CONDITIONAL} in the @code{configure.in} file (@pxref{Macros}).
4072 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
4073 The conditional name, @var{conditional}, should be a simple string
4074 starting with a letter and containing only letters, digits, and
4075 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
4076 which are reserved by Automake.
4078 The shell @var{condition} (suitable for use in a shell @code{if}
4079 statement) is evaluated when @code{configure} is run. Note that you
4080 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
4081 time @code{configure} is run -- if @code{AM_CONDITIONAL} is run
4082 conditionally (e.g., in a shell @code{if} statement), then the result
4083 will confuse automake.
4086 @cindex --enable-debug, example
4087 @cindex Example conditional --enable-debug
4088 @cindex Conditional example, --enable-debug
4090 Conditionals typically depend upon options which the user provides to
4091 the @code{configure} script. Here is an example of how to write a
4092 conditional which is true if the user uses the @samp{--enable-debug}
4096 AC_ARG_ENABLE(debug,
4097 [ --enable-debug Turn on debugging],
4098 [case "$@{enableval@}" in
4101 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
4102 esac],[debug=false])
4103 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
4106 Here is an example of how to use that conditional in @file{Makefile.am}:
4118 noinst_PROGRAMS = $(DBG)
4121 This trivial example could also be handled using EXTRA_PROGRAMS
4122 (@pxref{A Program}).
4124 You may only test a single variable in an @code{if} statement, possibly
4125 negated using @samp{!}. The @code{else} statement may be omitted.
4126 Conditionals may be nested to any depth. You may specify an argument to
4127 @code{else} in which case it must be the negation of the condition used
4128 for the current @code{if}. Similarly you may specify the condition
4129 which is closed by an @code{end}:
4140 Unbalanced conditions are errors.
4142 Note that conditionals in Automake are not the same as conditionals in
4143 GNU Make. Automake conditionals are checked at configure time by the
4144 @file{configure} script, and affect the translation from
4145 @file{Makefile.in} to @file{Makefile}. They are based on options passed
4146 to @file{configure} and on results that @file{configure} has discovered
4147 about the host system. GNU Make conditionals are checked at @code{make}
4148 time, and are based on variables passed to the make program or defined
4149 in the @file{Makefile}.
4151 Automake conditionals will work with any make program.
4154 @node Gnits, Cygnus, Conditionals, Top
4155 @chapter The effect of @code{--gnu} and @code{--gnits}
4157 @cindex --gnu, required files
4158 @cindex --gnu, complete description
4160 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
4161 variable) causes @code{automake} to check the following:
4165 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
4166 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
4167 directory of the package.
4170 The options @samp{no-installman} and @samp{no-installinfo} are
4174 Note that this option will be extended in the future to do even more
4175 checking; it is advisable to be familiar with the precise requirements
4176 of the GNU standards. Also, @samp{--gnu} can require certain
4177 non-standard GNU programs to exist for use by various maintainer-only
4178 targets; for instance in the future @code{pathchk} might be required for
4181 @cindex --gnits, complete description
4183 The @samp{--gnits} option does everything that @samp{--gnu} does, and
4184 checks the following as well:
4188 @samp{make dist} will check to make sure the @file{NEWS} file has been
4189 updated to the current version.
4192 @samp{VERSION} is checked to make sure its format complies with Gnits
4194 @c FIXME xref when standards are finished
4197 @cindex README-alpha
4198 If @samp{VERSION} indicates that this is an alpha release, and the file
4199 @file{README-alpha} appears in the topmost directory of a package, then
4200 it is included in the distribution. This is done in @samp{--gnits}
4201 mode, and no other, because this mode is the only one where version
4202 number formats are constrained, and hence the only mode where Automake
4203 can automatically determine whether @file{README-alpha} should be
4207 The file @file{THANKS} is required.
4211 @node Cygnus, Extending, Gnits, Top
4212 @chapter The effect of @code{--cygnus}
4214 @cindex Cygnus strictness
4216 Some packages, notably GNU GCC and GNU gdb, have a build environment
4217 originally written at Cygnus Support (subsequently renamed Cygnus
4218 Solutions, and then later purchased by Red Hat). Packages with this
4219 ancestry are sometimes referred to as ``Cygnus'' trees.
4221 A Cygnus tree has slightly different rules for how a @file{Makefile.in}
4222 is to be constructed. Passing @samp{--cygnus} to @code{automake} will
4223 cause any generated @file{Makefile.in} to comply with Cygnus rules.
4225 Here are the precise effects of @samp{--cygnus}:
4229 Info files are always created in the build directory, and not in the
4233 @file{texinfo.tex} is not required if a Texinfo source file is
4234 specified. The assumption is that the file will be supplied, but in a
4235 place that Automake cannot find. This assumption is an artifact of how
4236 Cygnus packages are typically bundled.
4239 @samp{make dist} is not supported, and the rules for it are not
4240 generated. Cygnus-style trees use their own distribution mechanism.
4243 Certain tools will be searched for in the build tree as well as in the
4244 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
4245 @code{makeinfo} and @code{texi2dvi}.
4248 @code{--foreign} is implied.
4251 The options @samp{no-installinfo} and @samp{no-dependencies} are
4255 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
4259 The @code{check} target doesn't depend on @code{all}.
4262 GNU maintainers are advised to use @samp{gnu} strictness in preference
4263 to the special Cygnus mode. Some day, perhaps, the differences between
4264 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
4265 more standards compliant). At that time the special Cygnus mode will be
4269 @node Extending, Distributing, Cygnus, Top
4270 @chapter When Automake Isn't Enough
4272 Automake's implicit copying semantics means that many problems can be
4273 worked around by simply adding some @code{make} targets and rules to
4274 @file{Makefile.in}. Automake will ignore these additions.
4276 @cindex -local targets
4277 @cindex local targets
4279 There are some caveats to doing this. Although you can overload a
4280 target already used by Automake, it is often inadvisable, particularly
4281 in the topmost directory of a package with subdirectories. However,
4282 various useful targets have a @samp{-local} version you can specify in
4283 your @file{Makefile.in}. Automake will supplement the standard target
4284 with these user-supplied targets.
4289 @trindex check-local
4290 @trindex install-data-local
4291 @trindex install-exec-local
4292 @trindex uninstall-local
4293 @trindex mostlyclean-local
4294 @trindex clean-local
4295 @trindex distclean-local
4297 The targets that support a local version are @code{all}, @code{info},
4298 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
4299 @code{uninstall}, and the various @code{clean} targets
4300 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
4301 @code{maintainer-clean}). Note that there are no
4302 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
4303 use @code{uninstall-local}. It doesn't make sense to uninstall just
4304 data or just executables.
4309 @trindex install-data
4310 @trindex install-exec
4313 For instance, here is one way to install a file in @file{/etc}:
4317 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
4320 @cindex -hook targets
4321 @cindex hook targets
4323 Some targets also have a way to run another target, called a @dfn{hook},
4324 after their work is done. The hook is named after the principal target,
4325 with @samp{-hook} appended. The targets allowing hooks are
4326 @code{install-data}, @code{install-exec}, @code{dist}, and
4328 @trindex install-data-hook
4329 @trindex install-exec-hook
4332 For instance, here is how to create a hard link to an installed program:
4336 ln $(bindir)/program $(bindir)/proglink
4339 @c FIXME should include discussion of variables you can use in these
4343 @node Distributing, Macro and Variable Index, Extending, Top
4344 @chapter Distributing @file{Makefile.in}s
4346 Automake places no restrictions on the distribution of the resulting
4347 @file{Makefile.in}s. We still encourage software authors to distribute
4348 their work under terms like those of the GPL, but doing so is not
4349 required to use Automake.
4351 Some of the files that can be automatically installed via the
4352 @code{--add-missing} switch do fall under the GPL. However, these also
4353 have a special exception allowing you to distribute them with your
4354 package, regardless of the licensing you choose.
4358 @node Macro and Variable Index, General Index, Distributing, Top
4359 @unnumbered Macro and Variable Index
4365 @node General Index, , Macro and Variable Index, Top
4366 @unnumbered General Index