1 \input texinfo @c -*-texinfo-*-
3 @setfilename automake.info
10 @dircategory GNU programming tools
12 * automake: (automake). Making Makefile.in's
15 @dircategory Individual utilities
17 * aclocal: (automake)Invoking aclocal. Generating aclocal.m4
21 This file documents GNU automake @value{VERSION}
23 Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002
24 Free Software Foundation, Inc.
26 Permission is granted to make and distribute verbatim copies of
27 this manual provided the copyright notice and this permission notice
28 are preserved on all copies.
31 Permission is granted to process this file through TeX and print the
32 results, provided the printed document carries copying permission
33 notice identical to this one except for the removal of this paragraph
37 Permission is granted to copy and distribute modified versions of this
38 manual under the conditions for verbatim copying, provided that the entire
39 resulting derived work is distributed under the terms of a permission
40 notice identical to this one.
42 Permission is granted to copy and distribute translations of this manual
43 into another language, under the above conditions for modified versions,
44 except that this permission notice may be stated in a translation approved
51 @subtitle For version @value{VERSION}, @value{UPDATED}
52 @author David MacKenzie and Tom Tromey
55 @vskip 0pt plus 1filll
56 Copyright @copyright{} 1995, 1996, 2000, 2001, 2002 Free Software Foundation, Inc.
58 This is the first edition of the GNU Automake documentation,@*
59 and is consistent with GNU Automake @value{VERSION}.@*
61 Published by the Free Software Foundation @*
62 59 Temple Place - Suite 330, @*
63 Boston, MA 02111-1307 USA @*
65 Permission is granted to make and distribute verbatim copies of
66 this manual provided the copyright notice and this permission notice
67 are preserved on all copies.
69 Permission is granted to copy and distribute modified versions of this
70 manual under the conditions for verbatim copying, provided that the entire
71 resulting derived work is distributed under the terms of a permission
72 notice identical to this one.
74 Permission is granted to copy and distribute translations of this manual
75 into another language, under the above conditions for modified versions,
76 except that this permission notice may be stated in a translation
77 approved by the Free Software Foundation.
80 @c Define an index of configure output variables.
82 @c Define an index of configure variables.
84 @c Define an index of options.
86 @c Define an index of targets.
88 @c Define an index of commands.
91 @c Put the macros and variables into their own index.
92 @c @syncodeindex fn cp
97 @c Put everything else into one index (arbitrarily chosen to be the concept index).
103 @node Top, Introduction, (dir), (dir)
104 @comment node-name, next, previous, up
107 This file documents the GNU Automake package. Automake is a program
108 which creates GNU standards-compliant Makefiles from template files.
109 This edition documents version @value{VERSION}.
112 * Introduction:: Automake's purpose
113 * Generalities:: General ideas
114 * Examples:: Some example packages
115 * Invoking Automake:: Creating a Makefile.in
116 * configure:: Scanning configure.ac or configure.in
117 * Top level:: The top-level Makefile.am
118 * Alternative:: An alternative approach to subdirectories
119 * Rebuilding:: Automatic rebuilding of Makefile
120 * Programs:: Building programs and libraries
121 * Other objects:: Other derived objects
122 * Other GNU Tools:: Other GNU Tools
123 * Documentation:: Building documentation
124 * Install:: What gets installed
125 * Clean:: What gets cleaned
126 * Dist:: What goes in a distribution
127 * Tests:: Support for test suites
128 * Options:: Changing Automake's behavior
129 * Miscellaneous:: Miscellaneous rules
130 * Include:: Including extra files in an Automake template.
131 * Conditionals:: Conditionals
132 * Gnits:: The effect of @code{--gnu} and @code{--gnits}
133 * Cygnus:: The effect of @code{--cygnus}
134 * Extending:: Extending Automake
135 * Distributing:: Distributing the Makefile.in
136 * API versioning:: About compatibility between Automake versions
137 * Macro and Variable Index::
144 @node Introduction, Generalities, Top, Top
145 @chapter Introduction
147 Automake is a tool for automatically generating @file{Makefile.in}s from
148 files called @file{Makefile.am}. Each @file{Makefile.am} is basically a
149 series of @code{make} macro definitions (with rules being thrown in
150 occasionally). The generated @file{Makefile.in}s are compliant with the
151 GNU Makefile standards.
153 @cindex GNU Makefile standards
155 The GNU Makefile Standards Document
156 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
157 is long, complicated, and subject to change. The goal of Automake is to
158 remove the burden of Makefile maintenance from the back of the
159 individual GNU maintainer (and put it on the back of the Automake
162 The typical Automake input file is simply a series of macro definitions.
163 Each such file is processed to create a @file{Makefile.in}. There
164 should generally be one @file{Makefile.am} per directory of a project.
166 @cindex Constraints of Automake
167 @cindex Automake constraints
169 Automake does constrain a project in certain ways; for instance it
170 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
171 autoconf, The Autoconf Manual}), and enforces certain restrictions on
172 the @file{configure.in} contents@footnote{Autoconf 2.50 promotes
173 @file{configure.ac} over @file{configure.in}. The rest of this
174 documentation will refer to @file{configure.in} as this use is not yet
175 spread, but Automake supports @file{configure.ac} too.}.
177 @cindex Automake requirements
178 @cindex Requirements, Automake
180 Automake requires @code{perl} in order to generate the
181 @file{Makefile.in}s. However, the distributions created by Automake are
182 fully GNU standards-compliant, and do not require @code{perl} in order
185 @cindex BUGS, reporting
186 @cindex Reporting BUGS
187 @cindex E-mail, bug reports
189 Mail suggestions and bug reports for Automake to
190 @email{bug-automake@@gnu.org}.
193 @node Generalities, Examples, Introduction, Top
194 @chapter General ideas
196 The following sections cover a few basic ideas that will help you
197 understand how Automake works.
200 * General Operation:: General operation of Automake
201 * Strictness:: Standards conformance checking
202 * Uniform:: The Uniform Naming Scheme
203 * Canonicalization:: How derived variables are named
204 * User Variables:: Variables reserved for the user
205 * Auxiliary Programs:: Programs automake might require
209 @node General Operation, Strictness, Generalities, Generalities
210 @section General Operation
212 Automake works by reading a @file{Makefile.am} and generating a
213 @file{Makefile.in}. Certain macros and targets defined in the
214 @file{Makefile.am} instruct Automake to generate more specialized code;
215 for instance, a @samp{bin_PROGRAMS} macro definition will cause targets
216 for compiling and linking programs to be generated.
218 @cindex Non-standard targets
219 @cindex cvs-dist, non-standard example
222 The macro definitions and targets in the @file{Makefile.am} are copied
223 verbatim into the generated file. This allows you to add arbitrary code
224 into the generated @file{Makefile.in}. For instance the Automake
225 distribution includes a non-standard @code{cvs-dist} target, which the
226 Automake maintainer uses to make distributions from his source control
229 @cindex GNU make extensions
231 Note that most GNU make extensions are not recognized by Automake. Using
232 such extensions in a @file{Makefile.am} will lead to errors or confusing
235 @cindex Append operator
236 A special exception is that the GNU make append operator, @samp{+=}, is
237 supported. This operator appends its right hand argument to the macro
238 specified on the left. Automake will translate the operator into
239 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
241 Automake tries to group comments with adjoining targets and macro
242 definitions in an intelligent way.
243 @c FIXME: What does this imply practically?
245 @cindex Make targets, overriding
246 @cindex Overriding make targets
248 A target defined in @file{Makefile.am} generally overrides any such
249 target of a similar name that would be automatically generated by
250 @code{automake}. Although this is a supported feature, it is generally
251 best to avoid making use of it, as sometimes the generated rules are
254 @cindex Macros, overriding
255 @cindex Overriding make macros
257 Similarly, a macro defined in @file{Makefile.am} or @code{AC_SUBST}'ed
258 from @file{configure.in} will override any definition of the macro that
259 @code{automake} would ordinarily create. This feature is more often
260 useful than the ability to override a target definition. Be warned that
261 many of the macros generated by @code{automake} are considered to be for
262 internal use only, and their names might change in future releases.
264 @cindex Recursive operation of Automake
265 @cindex Automake, recursive operation
266 @cindex Example of recursive operation
268 When examining a macro definition, Automake will recursively examine
269 macros referenced in the definition. For example, if Automake is
270 looking at the content of @code{foo_SOURCES} in this snippet
274 foo_SOURCES = c.c $(xs)
277 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
278 contents of @code{foo_SOURCES}.
280 @cindex ## (special Automake comment)
281 @cindex Special Automake comment
282 @cindex Comment, special to Automake
284 Automake also allows a form of comment which is @emph{not} copied into
285 the output; all lines beginning with @samp{##} (leading spaces allowed)
286 are completely ignored by Automake.
288 It is customary to make the first line of @file{Makefile.am} read:
290 @cindex Makefile.am, first line
291 @cindex First line of Makefile.am
294 ## Process this file with automake to produce Makefile.in
297 @c FIXME discuss putting a copyright into Makefile.am here? I would but
298 @c I don't know quite what to say.
300 @c FIXME document customary ordering of Makefile.am here!
303 @node Strictness, Uniform, General Operation, Generalities
306 @cindex Non-GNU packages
308 While Automake is intended to be used by maintainers of GNU packages, it
309 does make some effort to accommodate those who wish to use it, but do
310 not want to use all the GNU conventions.
312 @cindex Strictness, defined
313 @cindex Strictness, foreign
314 @cindex foreign strictness
315 @cindex Strictness, gnu
316 @cindex gnu strictness
317 @cindex Strictness, gnits
318 @cindex gnits strictness
320 To this end, Automake supports three levels of @dfn{strictness}---the
321 strictness indicating how stringently Automake should check standards
324 The valid strictness levels are:
328 Automake will check for only those things which are absolutely
329 required for proper operations. For instance, whereas GNU standards
330 dictate the existence of a @file{NEWS} file, it will not be required in
331 this mode. The name comes from the fact that Automake is intended to be
332 used for GNU programs; these relaxed rules are not the standard mode of
336 Automake will check---as much as possible---for compliance to the GNU
337 standards for packages. This is the default.
340 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
341 standards}. These are based on the GNU standards, but are even more
342 detailed. Unless you are a Gnits standards contributor, it is
343 recommended that you avoid this option until such time as the Gnits
344 standard is actually published (which may never happen).
347 For more information on the precise implications of the strictness
348 level, see @ref{Gnits}.
350 Automake also has a special ``cygnus'' mode which is similar to
351 strictness but handled differently. This mode is useful for packages
352 which are put into a ``Cygnus'' style tree (e.g., the GCC tree). For
353 more information on this mode, see @ref{Cygnus}.
356 @node Uniform, Canonicalization, Strictness, Generalities
357 @section The Uniform Naming Scheme
359 @cindex Uniform naming scheme
361 Automake macros (from here on referred to as @emph{variables}) generally
362 follow a @dfn{uniform naming scheme} that makes it easy to decide how
363 programs (and other derived objects) are built, and how they are
364 installed. This scheme also supports @code{configure} time
365 determination of what should be built.
367 @cindex _PROGRAMS primary variable
368 @cindex PROGRAMS primary variable
369 @cindex Primary variable, PROGRAMS
370 @cindex Primary variable, defined
372 At @code{make} time, certain variables are used to determine which
373 objects are to be built. The variable names are made of several pieces
374 which are concatenated together.
376 The piece which tells automake what is being built is commonly called
377 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
378 list of programs which are to be compiled and linked.
381 @cindex pkglibdir, defined
382 @cindex pkgincludedir, defined
383 @cindex pkgdatadir, defined
386 @vindex pkgincludedir
389 A different set of names is used to decide where the built objects
390 should be installed. These names are prefixes to the primary which
391 indicate which standard directory should be used as the installation
392 directory. The standard directory names are given in the GNU standards
393 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
394 Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
395 and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
396 versions, but with @samp{@@PACKAGE@@} appended. For instance,
397 @code{pkglibdir} is defined as @code{$(libdir)/@@PACKAGE@@}.
398 @cvindex PACKAGE, directory
400 @cindex EXTRA_, prepending
402 For each primary, there is one additional variable named by prepending
403 @samp{EXTRA_} to the primary name. This variable is used to list
404 objects which may or may not be built, depending on what
405 @code{configure} decides. This variable is required because Automake
406 must statically know the entire list of objects that may be built in
407 order to generate a @file{Makefile.in} that will work in all cases.
409 @cindex EXTRA_PROGRAMS, defined
410 @cindex Example, EXTRA_PROGRAMS
413 For instance, @code{cpio} decides at configure time which programs are
414 built. Some of the programs are installed in @code{bindir}, and some
415 are installed in @code{sbindir}:
418 EXTRA_PROGRAMS = mt rmt
419 bin_PROGRAMS = cpio pax
420 sbin_PROGRAMS = @@MORE_PROGRAMS@@
423 Defining a primary without a prefix as a variable, e.g.,
424 @code{PROGRAMS}, is an error.
426 Note that the common @samp{dir} suffix is left off when constructing the
427 variable names; thus one writes @samp{bin_PROGRAMS} and not
428 @samp{bindir_PROGRAMS}.
430 Not every sort of object can be installed in every directory. Automake
431 will flag those attempts it finds in error.
432 Automake will also diagnose obvious misspellings in directory names.
434 @cindex Extending list of installation directories
435 @cindex Installation directories, extending list
437 Sometimes the standard directories---even as augmented by Automake---
438 are not enough. In particular it is sometimes useful, for clarity, to
439 install objects in a subdirectory of some predefined directory. To this
440 end, Automake allows you to extend the list of possible installation
441 directories. A given prefix (e.g. @samp{zar}) is valid if a variable of
442 the same name with @samp{dir} appended is defined (e.g. @code{zardir}).
444 @cindex HTML support, example
446 For instance, until HTML support is part of Automake, you could use this
447 to install raw HTML documentation:
450 htmldir = $(prefix)/html
451 html_DATA = automake.html
454 @cindex noinst primary prefix, definition
456 The special prefix @samp{noinst} indicates that the objects in question
457 should be built but not installed at all. This is usually used for
458 objects required to build the rest of your package, for instance static
459 libraries (@pxref{A Library}), or helper scripts.
461 @cindex check primary prefix, definition
463 The special prefix @samp{check} indicates that the objects in question
464 should not be built until the @code{make check} command is run. Those
465 objects are not installed either.
467 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
468 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
469 @samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
481 Some primaries also allow additional prefixes which control other
482 aspects of @code{automake}'s behavior. The currently defined prefixes
483 are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes
484 are explained later (@pxref{Program and Library Variables}).
487 @node Canonicalization, User Variables, Uniform, Generalities
488 @section How derived variables are named
490 @cindex canonicalizing Automake macros
492 Sometimes a Makefile variable name is derived from some text the
493 maintainer supplies. For instance, a program name listed in
494 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
495 variable. In cases like this, Automake canonicalizes the text, so that
496 program names and the like do not have to follow Makefile macro naming
497 rules. All characters in the name except for letters, numbers, the
498 strudel (@@), and the underscore are turned into underscores when making
501 For example, if your program is named @code{sniff-glue}, the derived
502 variable name would be @code{sniff_glue_SOURCES}, not
503 @code{sniff-glue_SOURCES}. Similarly the sources for a library named
504 @code{libmumble++.a} should be listed in the
505 @code{libmumble___a_SOURCES} variable.
507 The strudel is an addition, to make the use of Autoconf substitutions in
508 macro names less obfuscating.
511 @node User Variables, Auxiliary Programs, Canonicalization, Generalities
512 @section Variables reserved for the user
514 @cindex variables, reserved for the user
515 @cindex user variables
517 Some @code{Makefile} variables are reserved by the GNU Coding Standards
518 for the use of the ``user'' -- the person building the package. For
519 instance, @code{CFLAGS} is one such variable.
521 Sometimes package developers are tempted to set user variables such as
522 @code{CFLAGS} because it appears to make their job easier -- they don't
523 have to introduce a second variable into every target.
525 However, the package itself should never set a user variable,
526 particularly not to include switches which are required for proper
527 compilation of the package. Since these variables are documented as
528 being for the package builder, that person rightfully expects to be able
529 to override any of these variables at build time.
530 @c FIXME: maybe Automake could bark if a developer forces a user variable
533 To get around this problem, automake introduces an automake-specific
534 shadow variable for each user flag variable. (Shadow variables are not
535 introduced for variables like @code{CC}, where they would make no
536 sense.) The shadow variable is named by prepending @samp{AM_} to the
537 user variable's name. For instance, the shadow variable for
538 @code{YFLAGS} is @code{AM_YFLAGS}.
541 @node Auxiliary Programs, , User Variables, Generalities
542 @section Programs automake might require
544 @cindex Programs, auxiliary
545 @cindex Auxiliary programs
547 Automake sometimes requires helper programs so that the generated
548 @file{Makefile} can do its work properly. There are a fairly large
549 number of them, and we list them here.
554 These two files are used by the automatic de-ANSI-fication support
558 This is a wrapper for compilers which don't accept both @samp{-c} and
559 @samp{-o} at the same time. It is only used when absolutely required.
560 Such compilers are rare.
564 These programs compute the canonical triplets for the given build, host,
565 or target architecture. These programs are updated regulary to support
566 new architectures and fix probes broken by changes in new kernel
567 versions. You are encouraged to fetch the latest versions of these
568 files from @url{ftp://ftp.gnu.org/gnu/config/} before making a release.
571 This program understands how to run a compiler so that it will generate
572 not only the desired output but also dependency information which is
573 then used by the automatic dependency tracking feature.
576 This program is used to byte-compile Emacs Lisp code.
579 This is a replacement for the @code{install} program which works on
580 platforms where @code{install} is unavailable or unusable.
583 This script is used to generate a @file{version.texi} file. It examines
584 a file and prints some date information about it.
587 This wraps a number of programs which are typically only required by
588 maintainers. If the program in question doesn't exist, @code{missing}
589 prints an informative warning and attempts to fix things so that the
593 This works around the fact that @code{mkdir -p} is not portable.
596 This is used to byte-compile Python scripts.
599 Not a program, this file is required for @code{make dvi} to work when
600 Texinfo sources are in the package.
603 This program wraps @code{lex} and @code{yacc} and ensures that, for
604 instance, multiple @code{yacc} instances can be invoked in a single
605 directory in parallel.
610 @node Examples, Invoking Automake, Generalities, Top
611 @chapter Some example packages
614 * Complete:: A simple example, start to finish
615 * Hello:: A classic program
616 * etags:: Building etags and ctags
620 @node Complete, Hello, Examples, Examples
621 @section A simple example, start to finish
623 @cindex Complete example
625 Let's suppose you just finished writing @code{zardoz}, a program to make
626 your head float from vortex to vortex. You've been using Autoconf to
627 provide a portability framework, but your @file{Makefile.in}s have been
628 ad-hoc. You want to make them bulletproof, so you turn to Automake.
630 @cindex AM_INIT_AUTOMAKE, example use
632 The first step is to update your @file{configure.in} to include the
633 commands that @code{automake} needs. The way to do this is to add an
634 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
642 Since your program doesn't have any complicating factors (e.g., it
643 doesn't use @code{gettext}, it doesn't want to build a shared library),
644 you're done with this part. That was easy!
646 @cindex aclocal program, introduction
647 @cindex aclocal.m4, preexisting
648 @cindex acinclude.m4, defined
650 Now you must regenerate @file{configure}. But to do that, you'll need
651 to tell @code{autoconf} how to find the new macro you've used. The
652 easiest way to do this is to use the @code{aclocal} program to generate
653 your @file{aclocal.m4} for you. But wait... maybe you already have an
654 @file{aclocal.m4}, because you had to write some hairy macros for your
655 program. The @code{aclocal} program lets you put your own macros into
656 @file{acinclude.m4}, so simply rename and then run:
659 mv aclocal.m4 acinclude.m4
664 @cindex zardoz example
666 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
667 Since @code{zardoz} is a user program, you want to install it where the
668 rest of the user programs go: @code{bindir}. Additionally,
669 @code{zardoz} has some Texinfo documentation. Your @file{configure.in}
670 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
671 @samp{@@LIBOBJS@@}. So here's what you'd write:
674 bin_PROGRAMS = zardoz
675 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
676 zardoz_LDADD = @@LIBOBJS@@
678 info_TEXINFOS = zardoz.texi
681 Now you can run @code{automake --add-missing} to generate your
682 @file{Makefile.in} and grab any auxiliary files you might need, and
686 @node Hello, etags, Complete, Examples
687 @section A classic program
689 @cindex Example, GNU Hello
690 @cindex Hello example
691 @cindex GNU Hello, example
693 @uref{ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz, GNU hello} is
694 renowned for its classic simplicity and versatility. This section shows
695 how Automake could be used with the GNU Hello package. The examples
696 below are from the latest beta version of GNU Hello, but with all of the
697 maintainer-only code stripped out, as well as all copyright comments.
699 Of course, GNU Hello is somewhat more featureful than your traditional
700 two-liner. GNU Hello is internationalized, does option processing, and
701 has a manual and a test suite.
703 @cindex configure.in, from GNU Hello
704 @cindex GNU Hello, configure.in
705 @cindex Hello, configure.in
707 Here is the @file{configure.in} from GNU Hello:
708 @c FIXME: This definitively requires an update.
711 dnl Process this file with autoconf to produce a configure script.
713 AM_INIT_AUTOMAKE(hello, 1.3.11)
714 AM_CONFIG_HEADER(config.h)
716 dnl Set of available languages.
717 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
719 dnl Checks for programs.
723 dnl Checks for libraries.
725 dnl Checks for header files.
727 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
729 dnl Checks for library functions.
732 dnl Check for st_blksize in struct stat
735 dnl internationalization macros
737 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
738 src/Makefile tests/Makefile tests/hello],
739 [chmod +x tests/hello])
742 The @samp{AM_} macros are provided by Automake (or the Gettext library);
743 the rest are standard Autoconf macros.
746 The top-level @file{Makefile.am}:
749 EXTRA_DIST = BUGS ChangeLog.O
750 SUBDIRS = doc intl po src tests
753 As you can see, all the work here is really done in subdirectories.
755 The @file{po} and @file{intl} directories are automatically generated
756 using @code{gettextize}; they will not be discussed here.
758 @cindex Texinfo file handling example
759 @cindex Example, handling Texinfo files
761 In @file{doc/Makefile.am} we see:
764 info_TEXINFOS = hello.texi
765 hello_TEXINFOS = gpl.texi
768 This is sufficient to build, install, and distribute the GNU Hello
771 @cindex Regression test example
772 @cindex Example, regression test
774 Here is @file{tests/Makefile.am}:
778 EXTRA_DIST = hello.in testdata
781 The script @file{hello} is generated by @code{configure}, and is the
782 only test case. @code{make check} will run this test.
784 @cindex INCLUDES, example usage
786 Last we have @file{src/Makefile.am}, where all the real work is done:
787 @c FIXME: As all the Hello World excerpts in this manual, this
788 @c shows deprecated features (here: $(INCLUDES)).
792 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
793 hello_LDADD = @@INTLLIBS@@ @@ALLOCA@@
794 localedir = $(datadir)/locale
795 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
799 @node etags, , Hello, Examples
800 @section Building etags and ctags
802 @cindex Example, ctags and etags
803 @cindex ctags Example
804 @cindex etags Example
806 Here is another, trickier example. It shows how to generate two
807 programs (@code{ctags} and @code{etags}) from the same source file
808 (@file{etags.c}). The difficult part is that each compilation of
809 @file{etags.c} requires different @code{cpp} flags.
812 bin_PROGRAMS = etags ctags
814 ctags_LDADD = ctags.o
817 $(COMPILE) -DETAGS_REGEXPS -c etags.c
820 $(COMPILE) -DCTAGS -o ctags.o -c etags.c
823 Note that there is no @code{etags_SOURCES} definition. Automake will
824 implicitly assume that there is a source file named @file{etags.c}, and
825 define rules to compile @file{etags.o} and link @file{etags}. The
826 @code{etags.o: etags.c} rule supplied by the above @file{Makefile.am},
827 will override the Automake generated rule to build @file{etags.o}.
829 @code{ctags_SOURCES} is defined to be empty---that way no implicit value
830 is substituted. Because we have not listed the source of
831 @file{ctags}, we have to tell Automake how to link the program. This is
832 the purpose of the @code{ctags_LDADD} line. A @code{ctags_DEPENDENCIES}
833 variable, holding the dependencies of the @file{ctags} target will be
834 automatically generated by Automake from the contant of
837 The above rules won't work if your compiler doesn't accept both
838 @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
839 bogus dependency (to avoid problems with a parallel @code{make}):
842 etags.o: etags.c ctags.o
843 $(COMPILE) -DETAGS_REGEXPS -c etags.c
846 $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
849 Also, these explicit rules do not work if the de-ANSI-fication feature
850 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
854 etags._o: etags._c ctags.o
855 $(COMPILE) -DETAGS_REGEXPS -c etags.c
858 $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
861 As it turns out, there is also a much easier way to do this same task.
862 Some of the above techniques are useful enough that we've kept the
863 example in the manual. However if you were to build @code{etags} and
864 @code{ctags} in real life, you would probably use per-program
865 compilation flags, like so:
868 bin_PROGRAMS = ctags etags
870 ctags_SOURCES = etags.c
871 ctags_CFLAGS = -DCTAGS
873 etags_SOURCES = etags.c
874 etags_CFLAGS = -DETAGS_REGEXPS
877 In this case Automake will cause @file{etags.c} to be compiled twice,
878 with different flags. De-ANSI-fication will work automatically. In
879 this instance, the names of the object files would be chosen by
880 automake; they would be @file{ctags-etags.o} and @file{etags-etags.o}.
881 (The name of the object files rarely matters.)
884 @node Invoking Automake, configure, Examples, Top
885 @chapter Creating a @file{Makefile.in}
887 @cindex Multiple configure.in files
888 @cindex Invoking Automake
889 @cindex Automake, invoking
891 To create all the @file{Makefile.in}s for a package, run the
892 @code{automake} program in the top level directory, with no arguments.
893 @code{automake} will automatically find each appropriate
894 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
895 and generate the corresponding @file{Makefile.in}. Note that
896 @code{automake} has a rather simplistic view of what constitutes a
897 package; it assumes that a package has only one @file{configure.in}, at
898 the top. If your package has multiple @file{configure.in}s, then you
899 must run @code{automake} in each directory holding a
900 @file{configure.in}. (Alteratively, you may rely on Autoconf's
901 @code{autoreconf}, which is able to recurse your package tree and run
902 @code{automake} where appropriate.)
904 You can optionally give @code{automake} an argument; @file{.am} is
905 appended to the argument and the result is used as the name of the input
906 file. This feature is generally only used to automatically rebuild an
907 out-of-date @file{Makefile.in}. Note that @code{automake} must always
908 be run from the topmost directory of a project, even if being used to
909 regenerate the @file{Makefile.in} in some subdirectory. This is
910 necessary because @code{automake} must scan @file{configure.in}, and
911 because @code{automake} uses the knowledge that a @file{Makefile.in} is
912 in a subdirectory to change its behavior in some cases.
915 Automake will run @code{autoconf} to scan @file{configure.in} and its
916 dependencies (@file{aclocal.m4}), therefore @code{autoconf} must be in
917 your @code{PATH}. If there is an @code{AUTOCONF} variable in your
918 environment it will be used instead of @code{autoconf}, this allows you
919 to select a particular version of Autoconf. By the way, don't
920 misunderstand this paragraph: Automake runs @code{autoconf} to
921 @strong{scan} your @file{configure.in}, this won't build
922 @file{configure} and you still have to run @code{autoconf} yourself for
925 @cindex Automake options
926 @cindex Options, Automake
927 @cindex Strictness, command line
929 @code{automake} accepts the following options:
931 @cindex Extra files distributed with Automake
932 @cindex Files distributed with Automake
939 @opindex --add-missing
940 Automake requires certain common files to exist in certain situations;
941 for instance @file{config.guess} is required if @file{configure.in} runs
942 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
943 files (@pxref{Auxiliary Programs}); this option will cause the missing
944 ones to be automatically added to the package, whenever possible. In
945 general if Automake tells you a file is missing, try using this option.
946 By default Automake tries to make a symbolic link pointing to its own
947 copy of the missing file; this can be changed with @code{--copy}.
949 @item --libdir=@var{dir}
951 Look for Automake data files in directory @var{dir} instead of in the
952 installation directory. This is typically used for debugging.
958 When used with @code{--add-missing}, causes installed files to be
959 copied. The default is to make a symbolic link.
963 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
964 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
968 @itemx --force-missing
969 @opindex --force-missing
970 When used with @code{--add-missing}, causes standard files to be reinstalled
971 even if they already exist in the source tree. This involves removing
972 the file from the source tree before creating the new symlink (or, with
973 @code{--copy}, copying the new file).
977 Set the global strictness to @samp{foreign}. For more information, see
982 Set the global strictness to @samp{gnits}. For more information, see
987 Set the global strictness to @samp{gnu}. For more information, see
988 @ref{Gnits}. This is the default strictness.
992 Print a summary of the command line options and exit.
997 This disables the dependency tracking feature in generated
998 @file{Makefile}s; see @ref{Dependencies}.
1000 @item --include-deps
1001 @opindex --include-deps
1002 This enables the dependency tracking feature. This feature is enabled
1003 by default. This option is provided for historical reasons only and
1004 probably should not be used.
1008 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
1009 @file{configure.in}. This option causes it to only update those
1010 @file{Makefile.in}s which are out of date with respect to one of their
1014 @itemx --output-dir=@var{dir}
1016 @opindex --output-dir
1017 Put the generated @file{Makefile.in} in the directory @var{dir}.
1018 Ordinarily each @file{Makefile.in} is created in the directory of the
1019 corresponding @file{Makefile.am}. This option is deprecated and will be
1020 removed in a future release.
1026 Cause Automake to print information about which files are being read or
1031 Print the version number of Automake and exit.
1036 @opindex --Wno-error
1037 @samp{--Werror} will cause all warnings issued by @code{automake} to
1038 become errors. Errors affect the exit status of @code{automake}, while
1039 warnings do not. @samp{--Wno-error}, the default, causes warnings to be
1040 treated as warnings only.
1044 @node configure, Top level, Invoking Automake, Top
1045 @chapter Scanning @file{configure.in}
1047 @cindex configure.in, scanning
1048 @cindex Scanning configure.in
1050 Automake scans the package's @file{configure.in} to determine certain
1051 information about the package. Some @code{autoconf} macros are required
1052 and some variables must be defined in @file{configure.in}. Automake
1053 will also use information from @file{configure.in} to further tailor its
1056 Automake also supplies some Autoconf macros to make the maintenance
1057 easier. These macros can automatically be put into your
1058 @file{aclocal.m4} using the @code{aclocal} program.
1061 * Requirements:: Configuration requirements
1062 * Optional:: Other things Automake recognizes
1063 * Invoking aclocal:: Auto-generating aclocal.m4
1064 * Macros:: Autoconf macros supplied with Automake
1065 * Extending aclocal:: Writing your own aclocal macros
1069 @node Requirements, Optional, configure, configure
1070 @section Configuration requirements
1072 @cindex Automake requirements
1073 @cindex Requirements of Automake
1075 The one real requirement of Automake is that your @file{configure.in}
1076 call @code{AM_INIT_AUTOMAKE}. This macro does several things which are
1077 required for proper Automake operation (@pxref{Macros}).
1078 @cvindex AM_INIT_AUTOMAKE
1080 Here are the other macros which Automake requires but which are not run
1081 by @code{AM_INIT_AUTOMAKE}:
1083 @cindex AC_OUTPUT, scanning
1086 @item AC_CONFIG_FILES
1088 Automake uses these to determine which files to create (@pxref{Output, ,
1089 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
1090 is considered to be an Automake generated @file{Makefile} if there
1091 exists a file with the same name and the @file{.am} extension appended.
1092 Typically, @code{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
1093 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
1095 Other listed files are treated differently. Currently the only
1096 difference is that an Automake @file{Makefile} is removed by @code{make
1097 distclean}, while other files are removed by @code{make clean}.
1098 @c FIXME: this is in violation of standards!
1103 @node Optional, Invoking aclocal, Requirements, configure
1104 @section Other things Automake recognizes
1106 @cindex Macros Automake recognizes
1107 @cindex Recognized macros by Automake
1109 Automake will also recognize the use of certain macros and tailor the
1110 generated @file{Makefile.in} appropriately. Currently recognized macros
1111 and their effects are:
1114 @item AC_CONFIG_HEADERS
1115 Automake will generate rules to rebuild these headers. Older versions
1116 of Automake required the use of @code{AM_CONFIG_HEADER}
1117 (@pxref{Macros}); this no longuer the case today.
1118 @cvindex AC_CONFIG_HEADERS
1120 @item AC_CONFIG_AUX_DIR
1121 Automake will look for various helper scripts, such as
1122 @file{mkinstalldirs}, in the directory named in this macro invocation.
1123 If not seen, the scripts are looked for in their @samp{standard}
1124 locations (either the top source directory, or in the source directory
1125 corresponding to the current @file{Makefile.am}, whichever is
1126 appropriate). @xref{Input, , Finding `configure' Input, autoconf, The
1128 @cvindex AC_CONFIG_AUX_DIR
1129 FIXME: give complete list of things looked for in this directory
1132 Automake will insert definitions for the variables defined by
1133 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
1134 or library. @xref{System Services, , System Services, autoconf, The
1136 @cvindex AC_PATH_XTRA
1138 @item AC_CANONICAL_HOST
1139 Automake will ensure that @file{config.guess} and @file{config.sub}
1140 exist. Also, the @file{Makefile} variables @samp{host_alias} and
1141 @samp{host_triplet} are introduced. See @ref{Canonicalizing, ,
1142 Getting the Canonical System Type, autoconf, The Autoconf Manual}.
1143 @cvindex AC_CANONICAL_HOST
1145 @vindex host_triplet
1147 @item AC_CANONICAL_SYSTEM
1148 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
1149 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
1150 @xref{Canonicalizing, , Getting the Canonical System Type, autoconf, The
1152 @cvindex AC_CANONICAL_SYSTEM
1154 @vindex target_alias
1156 @item AC_FUNC_ALLOCA
1157 @itemx AC_FUNC_ERROR_AT_LINE
1158 @itemx AC_FUNC_FNMATCH
1159 @itemx AC_FUNC_GETLOADAVG
1160 @itemx AC_FUNC_MEMCMP
1161 @itemx AC_FUNC_MKTIME
1162 @itemx AC_FUNC_OBSTACK
1163 @itemx AC_FUNC_STRTOD
1164 @itemx AC_REPLACE_FUNCS
1165 @itemx AC_REPLACE_GNU_GETOPT
1166 @itemx AC_STRUCT_ST_BLOCKS
1167 @itemx AM_WITH_REGEX
1168 Automake will ensure that the appropriate dependencies are generated for
1169 the objects corresponding to these macros. Also, Automake will verify
1170 that the appropriate source files are part of the distribution. Note
1171 that Automake does not come with any of the C sources required to use
1172 these macros, so @code{automake -a} will not install the sources.
1173 @xref{A Library}, for more information. Also, see @ref{Particular
1174 Functions, , Particular Function Checks, autoconf, The Autoconf Manual}.
1175 @cvindex AC_FUNC_ALLOCA
1176 @cvindex AC_FUNC_ERROR_AT_LINE
1177 @cvindex AC_FUNC_FNMATCH
1178 @cvindex AC_FUNC_GETLOADAVG
1179 @cvindex AC_FUNC_MEMCMP
1180 @cvindex AC_FUNC_MKTIME
1181 @cvindex AC_FUNC_OBSTACK
1182 @cvindex AC_FUNC_STRTOD
1183 @cvindex AC_REPLACE_FUNCS
1184 @cvindex AC_REPLACE_GNU_GETOPT
1185 @cvindex AC_STRUCT_ST_BLOCKS
1186 @cvindex AM_WITH_REGEX
1191 @itemx AC_LIBSOURCES
1192 Automake will detect statements which put @file{.o} files into
1193 @code{LIBOBJS}, or pass @file{.o} files to @code{AC_LIBOBJ}, and will
1194 treat these additional files as if they were discovered via
1195 @code{AC_REPLACE_FUNCS}. Similarly, Automake will also distribute file
1196 listed in @code{AC_LIBSOURCE} and @code{AC_LIBSOURCES}.
1198 Note that assignments to @code{LIBOBJS} is a construct which is being
1199 phased out; they will be ignored in a future release of Automake. You
1200 should call the @code{AC_LIBOBJ} macro instead. @xref{Generic
1201 Functions, , Generic Function Checks, autoconf, The Autoconf Manual}.
1204 @cvindex AC_LIBSOURCE
1205 @cvindex AC_LIBSOURCES
1208 @item AC_PROG_RANLIB
1209 This is required if any libraries are built in the package.
1210 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1212 @cvindex AC_PROG_RANLIB
1215 This is required if any C++ source is included. @xref{Particular
1216 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1217 @cvindex AC_PROG_CXX
1220 This is required if any Fortran 77 source is included. This macro is
1221 distributed with Autoconf version 2.13 and later. @xref{Particular
1222 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1223 @cvindex AC_PROG_F77
1225 @item AC_F77_LIBRARY_LDFLAGS
1226 This is required for programs and shared libraries that are a mixture of
1227 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
1228 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
1229 @cvindex AC_F77_LIBRARY_LDFLAGS
1231 @item AC_PROG_LIBTOOL
1232 Automake will turn on processing for @code{libtool} (@pxref{Top, ,
1233 Introduction, libtool, The Libtool Manual}).
1234 @cvindex AC_PROG_LIBTOOL
1237 If a Yacc source file is seen, then you must either use this macro or
1238 define the variable @samp{YACC} in @file{configure.in}. The former is
1239 preferred (@pxref{Particular Programs, , Particular Program Checks,
1240 autoconf, The Autoconf Manual}).
1241 @cvindex AC_PROG_YACC
1245 If a Lex source file is seen, then this macro must be used.
1246 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1248 @cvindex AC_PROG_LEX
1250 @item AM_C_PROTOTYPES
1251 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
1252 @cvindex AM_C_PROTOTYPES
1254 @item AM_GNU_GETTEXT
1255 This macro is required for packages which use GNU gettext
1256 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1257 this macro it ensures that the package meets some of gettext's
1259 @cvindex AM_GNU_GETTEXT
1261 @item AM_MAINTAINER_MODE
1262 @opindex --enable-maintainer-mode
1263 This macro adds a @samp{--enable-maintainer-mode} option to
1264 @code{configure}. If this is used, @code{automake} will cause
1265 @samp{maintainer-only} rules to be turned off by default in the
1266 generated @file{Makefile.in}s. This macro is disallowed in @samp{Gnits}
1267 mode (@pxref{Gnits}). This macro defines the @samp{MAINTAINER_MODE}
1268 conditional, which you can use in your own @file{Makefile.am}.
1269 @cvindex AM_MAINTAINER_MODE
1272 @itemx AC_CHECK_TOOL
1273 @itemx AC_CHECK_PROG
1274 @itemx AC_CHECK_PROGS
1276 @itemx AC_PATH_PROGS
1277 For each of these macros, the first argument is automatically defined as
1278 a variable in each generated @file{Makefile.in}. @xref{Setting Output
1279 Variables, , Setting Output Variables, autoconf, The Autoconf Manual},
1280 and @ref{Generic Programs, , Generic Program Checks, autoconf, The
1283 @cvindex AC_CHECK_TOOL
1284 @cvindex AC_CHECK_PROG
1285 @cvindex AC_CHECK_PROGS
1286 @cvindex AC_PATH_PROG
1287 @cvindex AC_PATH_PROGS
1292 @node Invoking aclocal, Macros, Optional, configure
1293 @section Auto-generating aclocal.m4
1295 @cindex Invoking aclocal
1296 @cindex aclocal, Invoking
1298 Automake includes a number of Autoconf macros which can be used in your
1299 package; some of them are actually required by Automake in certain
1300 situations. These macros must be defined in your @file{aclocal.m4};
1301 otherwise they will not be seen by @code{autoconf}.
1303 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1304 files based on the contents of @file{configure.in}. This provides a
1305 convenient way to get Automake-provided macros, without having to
1306 search around. Also, the @code{aclocal} mechanism allows other packages
1307 to supply their own macros.
1309 At startup, @code{aclocal} scans all the @file{.m4} files it can find,
1310 looking for macro definitions. Then it scans @file{configure.in}. Any
1311 mention of one of the macros found in the first step causes that macro,
1312 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1314 The contents of @file{acinclude.m4}, if it exists, are also
1315 automatically included in @file{aclocal.m4}. This is useful for
1316 incorporating local macros into @file{configure}.
1318 @code{aclocal} tries to be smart about looking for new @code{AC_DEFUN}s
1319 in the files it scans. It also
1320 tries to copy the full text of the scanned file into @file{aclocal.m4},
1321 including both @samp{#} and @samp{dnl} comments. If you want to make a
1322 comment which will be completely ignored by @code{aclocal}, use
1323 @samp{##} as the comment leader.
1325 @code{aclocal} accepts the following options:
1328 @item --acdir=@var{dir}
1330 Look for the macro files in @var{dir} instead of the installation
1331 directory. This is typically used for debugging.
1335 Print a summary of the command line options and exit.
1339 Add the directory @var{dir} to the list of directories searched for
1342 @item --output=@var{file}
1344 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1346 @item --print-ac-dir
1347 @opindex --print-ac-dir
1348 Prints the name of the directory which @code{aclocal} will search to
1349 find third-party @file{.m4} files. When this option is given, normal
1350 processing is suppressed. This option can be used by a package to
1351 determine where to install a macro file.
1355 Print the names of the files it examines.
1359 Print the version number of Automake and exit.
1363 @node Macros, Extending aclocal, Invoking aclocal, configure
1364 @section Autoconf macros supplied with Automake
1366 Automake ships with several Autoconf macros that you can use from your
1367 @file{configure.in}. When you use one of them it will be included by
1368 @code{aclocal} in @file{aclocal.m4}.
1371 * Public macros:: Macros that you can use.
1372 * Private macros:: Macros that you should not use.
1375 @c consider generating the following subsections automatically from m4 files.
1377 @node Public macros, Private macros, Macros, Macros
1378 @subsection Public macros
1381 @item AM_CONFIG_HEADER
1382 Automake will generate rules to automatically regenerate the config
1383 header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
1384 today (@pxref{Optional}).
1385 @cvindex AM_CONFIG_HEADER
1387 @item AM_ENABLE_MULTILIB
1388 This is used when a ``multilib'' library is being built. The first
1389 optional argument is the name of the @file{Makefile} being generated; it
1390 defaults to @samp{Makefile}. The second option argument is used to find
1391 the top source directory; it defaults to the empty string (generally
1392 this should not be used unless you are familiar with the internals).
1395 @item AM_C_PROTOTYPES
1396 Check to see if function prototypes are understood by the compiler. If
1397 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1398 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1399 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1400 values to implement automatic de-ANSI-fication.
1401 @cvindex AM_C_PROTOTYPES
1403 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1404 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1405 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1406 found in @file{<termios.h>}.
1407 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1409 @item AM_INIT_AUTOMAKE([OPTIONS])
1410 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
1411 Runs many macros required for proper operation of the generated Makefiles.
1413 This macro has two forms, the second of which has two required
1414 arguments: the package and the version number. This latter form is
1415 obsolete because the @var{package} and @var{version} can be obtained
1416 from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
1419 If your @file{configure.in} has:
1422 AM_INIT_AUTOMAKE(mumble, 1.5)
1424 you can modernize it as follow:
1426 AC_INIT(mumble, 1.5)
1427 AC_CONFIG_SRCDIR(src/foo.c)
1431 Note that if you're upgrading your @file{configure.in} from an earlier
1432 version of Automake, it is not always correct to simply move the package
1433 and version arguments from @code{AM_INIT_AUTOMAKE} directly to
1434 @code{AC_INIT}, as in the example above. The first argument of
1435 @code{AC_INIT} is the name of your package (e.g. @samp{GNU Automake}),
1436 not the tarball name (e.g. @samp{automake}) you used to pass to
1437 @code{AM_INIT_AUTOMAKE}. Autoconf's rule to derive a tarball name from
1438 the package name should work for most but not all packages. Especially,
1439 if your tarball name is not all lower case, you will have to use the
1440 four-argument form of @code{AC_INIT} (supported in Autoconf versions
1441 greater than 2.52g).
1443 When @code{AM_INIT_AUTOMAKE} is called with a single argument, it is
1444 interpreted as a space-separated list of Automake options which should
1445 be applied to every @file{Makefile.am} in the tree. The effect is as if
1446 each option were listed in @code{AUTOMAKE_OPTIONS}.
1448 By default this macro @code{AC_DEFINE}'s @samp{PACKAGE} and
1449 @samp{VERSION}. This can be avoided by passing the @samp{no-define}
1452 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
1454 or by passing a third non-empty argument to the obsolete form.
1456 @cvindex PACKAGE, prevent definition
1457 @cvindex VERSION, prevent definition
1460 @item AM_PATH_LISPDIR
1461 Searches for the program @code{emacs}, and, if found, sets the output
1462 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1464 Note that this test assumes the @code{emacs} found to be a version that
1465 supports Emacs Lisp (such as @sc{gnu} Emacs or XEmacs). Other emacsen
1466 can cause this test to hang (some, like old versions of MicroEmacs,
1467 start up in interactive mode, requiring @samp{C-x C-c} to exit, which
1468 is hardly obvious for a non-emacs user). In most cases, however, you
1469 should be able to use @samp{C-c} to kill the test. In order to avoid
1470 problems, you can set @code{EMACS} to ``no'' in the environment, or
1471 use the @samp{--with-lispdir} option to @command{configure} to
1472 explictly set the correct path (if you're sure you have an @code{emacs}
1473 that supports Emacs Lisp.
1474 @cvindex AM_PATH_LISPDIR
1477 Use this macro when you have assembly code in your project. This will
1478 choose the assembler for you (by default the C compiler) and set
1479 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
1481 @item AM_PROG_CC_C_O
1482 This is like @code{AC_PROG_CC_C_O}, but it generates its results in the
1483 manner required by automake. You must use this instead of
1484 @code{AC_PROG_CC_C_O} when you need this functionality.
1486 @item AM_PROG_CC_STDC
1487 If the C compiler is not in ANSI C mode by default, try to add an option
1488 to output variable @code{CC} to make it so. This macro tries various
1489 options that select ANSI C on some system or another. It considers the
1490 compiler to be in ANSI C mode if it handles function prototypes correctly.
1492 If you use this macro, you should check after calling it whether the C
1493 compiler has been set to accept ANSI C; if not, the shell variable
1494 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1495 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1496 @code{ansi2knr} option (@pxref{ANSI}).
1499 @cindex HP-UX 10, lex problems
1500 @cindex lex problems with HP-UX 10
1501 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
1502 Program Checks, autoconf, The Autoconf Manual}), but uses the
1503 @code{missing} script on systems that do not have @code{lex}.
1504 @samp{HP-UX 10} is one such system.
1507 This macro finds the @code{gcj} program or causes an error. It sets
1508 @samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
1509 GNU Compiler Collection.
1510 @cvindex AM_PROG_GCJ
1512 @item AM_SYS_POSIX_TERMIOS
1513 @cvindex am_cv_sys_posix_termios
1514 @cindex POSIX termios headers
1515 @cindex termios POSIX headers
1516 Check to see if POSIX termios headers and functions are available on the
1517 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1518 @samp{yes}. If not, set the variable to @samp{no}.
1520 @item AM_WITH_DMALLOC
1521 @cvindex WITH_DMALLOC
1522 @cindex dmalloc, support for
1523 @opindex --with-dmalloc
1525 @uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
1526 package. If the user configures with @samp{--with-dmalloc}, then define
1527 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
1531 @opindex --with-regex
1532 @cindex regex package
1534 Adds @samp{--with-regex} to the @code{configure} command line. If
1535 specified (the default), then the @samp{regex} regular expression
1536 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1537 @samp{WITH_REGEX} is defined. If @samp{--without-regex} is given, then
1538 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1539 into @samp{LIBOBJS}.
1543 @node Private macros, , Public macros, Macros
1544 @subsection Private macros
1546 The following macros are private macros you should not call directly.
1547 They are called by the other public macros when appropriate. Do not
1548 rely on them, as they might be changed in a future version. Consider
1549 them as implementation details; or better, do not consider them at all:
1553 @item _AM_DEPENDENCIES
1554 @itemx AM_SET_DEPDIR
1556 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
1557 These macros are used to implement automake's automatic dependency
1558 tracking scheme. They are called automatically by automake when
1559 required, and there should be no need to invoke them manually.
1561 @item AM_MAKE_INCLUDE
1562 This macro is used to discover how the user's @code{make} handles
1563 @code{include} statements. This macro is automatically invoked when
1564 needed; there should be no need to invoke it manually.
1566 @item AM_PROG_INSTALL_STRIP
1567 This is used to find a version of @code{install} which can be used to
1568 @code{strip} a program at installation time. This macro is
1569 automatically included when required.
1571 @item AM_SANITY_CHECK
1572 This checks to make sure that a file created in the build directory is
1573 newer than a file in the source directory. This can fail on systems
1574 where the clock is set incorrectly. This macro is automatically run
1575 from @code{AM_INIT_AUTOMAKE}.
1581 @node Extending aclocal, , Macros, configure
1582 @section Writing your own aclocal macros
1584 @cindex aclocal, extending
1585 @cindex Extending aclocal
1587 The @code{aclocal} program doesn't have any built-in knowledge of any
1588 macros, so it is easy to extend it with your own macros.
1590 This is mostly used for libraries which want to supply their own
1591 Autoconf macros for use by other programs. For instance the
1592 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1593 should be used by any package using @code{gettext}. When the library is
1594 installed, it installs this macro so that @code{aclocal} will find it.
1596 A file of macros should be a series of @code{AC_DEFUN}'s. The
1597 @code{aclocal} programs also understands @code{AC_REQUIRE}, so it is
1598 safe to put each macro in a separate file. @xref{Prerequisite Macros, ,
1599 , autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
1600 autoconf, The Autoconf Manual}.
1602 A macro file's name should end in @file{.m4}. Such files should be
1603 installed in @code{`aclocal --print-ac-dir`} (which usually happens to
1604 be @file{$(datadir)/aclocal}).
1607 @node Top level, Alternative, configure, Top
1608 @chapter The top-level @file{Makefile.am}
1610 @cindex SUBDIRS, explained
1612 In packages with subdirectories, the top level @file{Makefile.am} must
1613 tell Automake which subdirectories are to be built. This is done via
1614 the @code{SUBDIRS} variable.
1617 The @code{SUBDIRS} macro holds a list of subdirectories in which
1618 building of various sorts can occur. Many targets (e.g. @code{all}) in
1619 the generated @file{Makefile} will run both locally and in all specified
1620 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1621 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1622 (after configuration). This allows inclusion of libraries from packages
1623 which do not use Automake (such as @code{gettext}). The directories
1624 mentioned in @code{SUBDIRS} must be direct children of the current
1625 directory. For instance, you cannot put @samp{src/subdir} into
1628 In packages that use subdirectories, the top-level @file{Makefile.am} is
1629 often very short. For instance, here is the @file{Makefile.am} from the
1630 GNU Hello distribution:
1633 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1634 SUBDIRS = doc intl po src tests
1637 @cindex SUBDIRS, overriding
1638 @cindex Overriding SUBDIRS
1640 It is possible to override the @code{SUBDIRS} variable if, like in the
1641 case of GNU @code{Inetutils}, you want to only build a subset of the
1642 entire package. In your @file{Makefile.am} include:
1645 SUBDIRS = @@MY_SUBDIRS@@
1648 Then in your @file{configure.in} you can specify:
1651 MY_SUBDIRS="src doc lib po"
1652 AC_SUBST(MY_SUBDIRS)
1655 (Note that we don't use the variable name @code{SUBDIRS} in our
1656 @file{configure.in}; that would cause Automake to believe that every
1657 @file{Makefile.in} should recurse into the listed subdirectories.)
1659 The upshot of this is that Automake is tricked into building the package
1660 to take the subdirs, but doesn't actually bind that list until
1661 @code{configure} is run.
1663 Although the @code{SUBDIRS} macro can contain configure substitutions
1664 (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
1665 contents of this variable.
1667 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1668 @code{AC_PROG_MAKE_SET}. When Automake invokes @code{make} in a
1669 subdirectory, it uses the value of the @code{MAKE} variable. It passes
1670 the value of the variable @code{AM_MAKEFLAGS} to the @code{make}
1671 invocation; this can be set in @file{Makefile.am} if there are flags you
1672 must always pass to @code{make}.
1676 The use of @code{SUBDIRS} is not restricted to just the top-level
1677 @file{Makefile.am}. Automake can be used to construct packages of
1680 By default, Automake generates @file{Makefiles} which work depth-first
1681 (@samp{postfix}). However, it is possible to change this ordering. You
1682 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
1683 putting @samp{.} first will cause a @samp{prefix} ordering of
1684 directories. All @samp{clean} targets are run in reverse order of build
1687 Sometimes, such as when running @code{make dist}, you want all possible
1688 subdirectories to be examined. In this case Automake will use
1689 @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to
1690 recurse. This variable will also be used when the user runs
1691 @code{distclean} or @code{maintainer-clean}. It should be set to the
1692 full list of subdirectories in the project. If this macro is not set,
1693 Automake will attempt to set it for you.
1696 @node Alternative, Rebuilding, Top level, Top
1697 @chapter An Alternative Approach to Subdirectories
1699 If you've ever read Peter Miller's excellent paper,
1700 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
1701 Recursive Make Considered Harmful}, the preceding section on the use of
1702 subdirectories will probably come as unwelcome advice. For those who
1703 haven't read the paper, Miller's main thesis is that recursive
1704 @code{make} invocations are both slow and error-prone.
1706 Automake provides sufficient cross-directory support @footnote{We
1707 believe. This work is new and there are probably warts.
1708 @xref{Introduction}, for information on reporting bugs.} to enable you
1709 to write a single @file{Makefile.am} for a complex multi-directory
1713 By default an installable file specified in a subdirectory will have its
1714 directory name stripped before installation. For instance, in this
1715 example, the header file will be installed as
1716 @file{$(includedir)/stdio.h}:
1719 include_HEADERS = inc/stdio.h
1723 @cindex Path stripping, avoiding
1724 @cindex Avoiding path stripping
1726 However, the @samp{nobase_} prefix can be used to circumvent this path
1727 stripping. In this example, the header file will be installed as
1728 @file{$(includedir)/sys/types.h}:
1731 nobase_include_HEADERS = sys/types.h
1734 @cindex nobase_ and dist_ or nodist_
1735 @cindex dist_ and nobase_
1736 @cindex nodist_ and nobase_
1738 @samp{nobase_} should be specified first when used in conjonction with
1739 either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
1742 nobase_dist_pkgdata_DATA = images/vortex.pgm
1745 @node Rebuilding, Programs, Alternative, Top
1746 @chapter Rebuilding Makefiles
1748 Automake generates rules to automatically rebuild @file{Makefile}s,
1749 @file{configure}, and other derived files like @file{Makefile.in}.
1751 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.in}, then
1752 these automatic rebuilding rules are only enabled in maintainer mode.
1754 Sometimes you need to run @code{aclocal} with an argument like @code{-I}
1755 to tell it where to find @file{.m4} files. Since sometimes @code{make}
1756 will automatically run @code{aclocal}, you need a way to specify these
1757 arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this
1758 holds arguments which are passed verbatim to @code{aclocal}. This macro
1759 is only useful in the top-level @file{Makefile.am}.
1760 @vindex ACLOCAL_AMFLAGS
1763 @node Programs, Other objects, Rebuilding, Top
1764 @chapter Building Programs and Libraries
1766 A large part of Automake's functionality is dedicated to making it easy
1767 to build programs and libraries.
1770 * A Program:: Building a program
1771 * A Library:: Building a library
1772 * A Shared Library:: Building a Libtool library
1773 * Program and Library Variables:: Variables controlling program and
1775 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1776 * Program variables:: Variables used when building a program
1777 * Yacc and Lex:: Yacc and Lex support
1779 * Assembly Support::
1780 * Fortran 77 Support::
1782 * Support for Other Languages::
1783 * ANSI:: Automatic de-ANSI-fication
1784 * Dependencies:: Automatic dependency tracking
1785 * EXEEXT:: Support for executable extensions
1789 @node A Program, A Library, Programs, Programs
1790 @section Building a program
1792 In order to build a program, you need to tell Automake which sources
1793 are part of it, and which libraries it should be linked with.
1795 This section also covers conditional compilation of sources or
1796 programs. Most of the comments about these also apply to libraries
1797 (@pxref{A Library}) and Libtool libraries (@pxref{A Shared Library}).
1800 * Program Sources:: Defining program sources
1801 * Linking:: Linking with libraries or extra objects
1802 * Conditional Sources:: Handling conditional sources
1803 * Conditional Programs:: Building program conditionally
1806 @node Program Sources, Linking, A Program, A Program
1807 @subsection Defining program sources
1809 @cindex PROGRAMS, bindir
1810 @vindex bin_PROGRAMS
1811 @vindex sbin_PROGRAMS
1812 @vindex libexec_PROGRAMS
1813 @vindex pkglib_PROGRAMS
1814 @vindex noinst_PROGRAMS
1815 @vindex check_PROGRAMS
1817 In a directory containing source that gets built into a program (as
1818 opposed to a library or a script), the @samp{PROGRAMS} primary is used.
1819 Programs can be installed in @code{bindir}, @code{sbindir},
1820 @code{libexecdir}, @code{pkglibdir}, or not at all (@samp{noinst}).
1821 They can also be built only for @code{make check}, in which case the
1822 prefix is @samp{check}.
1827 bin_PROGRAMS = hello
1830 In this simple case, the resulting @file{Makefile.in} will contain code
1831 to generate a program named @code{hello}.
1833 Associated with each program are several assisting variables which are
1834 named after the program. These variables are all optional, and have
1835 reasonable defaults. Each variable, its use, and default is spelled out
1836 below; we use the ``hello'' example throughout.
1838 The variable @code{hello_SOURCES} is used to specify which source files
1839 get built into an executable:
1842 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1845 This causes each mentioned @samp{.c} file to be compiled into the
1846 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1848 @cindex _SOURCES primary, defined
1849 @cindex SOURCES primary, defined
1850 @cindex Primary variable, SOURCES
1852 If @samp{hello_SOURCES} is not specified, then it defaults to the single
1853 file @file{hello.c}; that is, the default is to compile a single C file
1854 whose base name is the name of the program itself. (This is a terrible
1855 default but we are stuck with it for historical reasons.)
1859 Multiple programs can be built in a single directory. Multiple programs
1860 can share a single source file, which must be listed in each
1861 @samp{_SOURCES} definition.
1863 @cindex Header files in _SOURCES
1864 @cindex _SOURCES and header files
1866 Header files listed in a @samp{_SOURCES} definition will be included in
1867 the distribution but otherwise ignored. In case it isn't obvious, you
1868 should not include the header file generated by @file{configure} in a
1869 @samp{_SOURCES} variable; this file should not be distributed. Lex
1870 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1874 @node Linking, Conditional Sources, Program Sources, A Program
1875 @subsection Linking the program
1877 If you need to link against libraries that are not found by
1878 @code{configure}, you can use @code{LDADD} to do so. This variable is
1879 used to specify additional objects or libraries to link with; it is
1880 inappropriate for specifying specific linker flags, you should use
1881 @code{AM_LDFLAGS} for this purpose.
1885 @cindex prog_LDADD, defined
1887 Sometimes, multiple programs are built in one directory but do not share
1888 the same link-time requirements. In this case, you can use the
1889 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1890 program as it appears in some @samp{_PROGRAMS} variable, and usually
1891 written in lowercase) to override the global @code{LDADD}. If this
1892 variable exists for a given program, then that program is not linked
1896 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
1897 linked against the library @file{libcpio.a}. However, @code{rmt} is
1898 built in the same directory, and has no such link requirement. Also,
1899 @code{mt} and @code{rmt} are only built on certain architectures. Here
1900 is what cpio's @file{src/Makefile.am} looks like (abridged):
1903 bin_PROGRAMS = cpio pax @@MT@@
1904 libexec_PROGRAMS = @@RMT@@
1905 EXTRA_PROGRAMS = mt rmt
1907 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1910 cpio_SOURCES = @dots{}
1911 pax_SOURCES = @dots{}
1912 mt_SOURCES = @dots{}
1913 rmt_SOURCES = @dots{}
1916 @cindex _LDFLAGS, defined
1918 @samp{@var{prog}_LDADD} is inappropriate for passing program-specific
1919 linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
1920 @samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
1924 @cindex _DEPENDENCIES, defined
1926 It is also occasionally useful to have a program depend on some other
1927 target which is not actually part of that program. This can be done
1928 using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
1929 on the contents of such a variable, but no further interpretation is
1932 If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
1933 Automake. The automatically-assigned value is the contents of
1934 @samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
1935 @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
1936 configure substitutions that are left in are only @samp{@@LIBOBJS@@} and
1937 @samp{@@ALLOCA@@}; these are left because it is known that they will not
1938 cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
1942 @node Conditional Sources, Conditional Programs, Linking, A Program
1943 @subsection Conditional compilation of sources
1945 You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
1946 @samp{_SOURCES} variable. The reason for this is a bit hard to explain,
1947 but suffice to say that it simply won't work. Automake will give an
1948 error if you try to do this.
1950 Fortunatly there are two other ways to achieve the same result. One is
1951 to use configure substitutions in @code{_LDADD} variables, the other is
1952 to use an Automake conditional.
1954 @subsubsection Conditional compilation using @code{_LDADD} substitutions
1956 @cindex EXTRA_prog_SOURCES, defined
1958 Automake must know all the source files that could possibly go into a
1959 program, even if not all the files are built in every circumstance. Any
1960 files which are only conditionally built should be listed in the
1961 appropriate @samp{EXTRA_} variable. For instance, if
1962 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
1963 in @code{hello}, the @file{Makefile.am} would contain:
1966 bin_PROGRAMS = hello
1967 hello_SOURCES = hello-common.c
1968 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
1969 hello_LDADD = @@HELLO_SYSTEM@@
1970 hello_DEPENDENCIES = @@HELLO_SYSTEM@@
1974 You can then setup the @code{@@HELLO_SYSTEM@@} substitution from
1975 @file{configure.in}:
1980 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
1981 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
1983 AC_SUBST([HELLO_SYSTEM])
1987 In this case, @code{HELLO_SYSTEM} should be replaced by
1988 @file{hello-linux.o} or @file{hello-bsd.o}, and added to
1989 @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be built
1992 @subsubsection Conditional compilation using Automake conditionals
1994 An often simpler way to compile source files conditionally is to use
1995 Automake conditionals. For instance, you could use this
1996 @file{Makefile.am} construct to build the same @file{hello} example:
1999 bin_PROGRAMS = hello
2001 hello_SOURCES = hello-linux.c hello-common.c
2003 hello_SOURCES = hello-generic.c hello-common.c
2007 In this case, your @file{configure.in} should setup the @code{LINUX}
2008 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
2010 When using conditionals like this you don't need to use the
2011 @samp{EXTRA_} variable, because Automake will examine the contents of
2012 each variable to construct the complete list of source files.
2014 If your program uses a lot of files, you will probably prefer a
2015 conditional @code{+=}.
2018 bin_PROGRAMS = hello
2019 hello_SOURCES = hello-common.c
2021 hello_cond += hello-linux.c
2023 hello_cond += hello-generic.c
2027 @node Conditional Programs, , Conditional Sources, A Program
2028 @subsection Conditional compilation of programs
2030 Sometimes it is useful to determine the programs that are to be built at
2031 configure time. For instance, GNU @code{cpio} only builds @code{mt} and
2032 @code{rmt} under special circumstances.
2034 @cindex EXTRA_PROGRAMS, defined
2036 In this case, you must notify Automake of all the programs that can
2037 possibly be built, but at the same time cause the generated
2038 @file{Makefile.in} to use the programs specified by @code{configure}.
2039 This is done by having @code{configure} substitute values into each
2040 @samp{_PROGRAMS} definition, while listing all optionally built programs
2041 in @code{EXTRA_PROGRAMS}.
2042 @vindex EXTRA_PROGRAMS
2044 Of course you can use Automake conditionals to determine the programs to
2048 @node A Library, A Shared Library, A Program, Programs
2049 @section Building a library
2051 @cindex _LIBRARIES primary, defined
2052 @cindex LIBRARIES primary, defined
2053 @cindex Primary variable, LIBRARIES
2055 @vindex lib_LIBRARIES
2056 @vindex pkglib_LIBRARIES
2057 @vindex noinst_LIBRARIES
2059 Building a library is much like building a program. In this case, the
2060 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
2061 @code{libdir} or @code{pkglibdir}.
2063 @xref{A Shared Library}, for information on how to build shared
2064 libraries using Libtool and the @samp{LTLIBRARIES} primary.
2066 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
2067 For instance to create a library named @file{libcpio.a}, but not install
2068 it, you would write:
2071 noinst_LIBRARIES = libcpio.a
2074 The sources that go into a library are determined exactly as they are
2075 for programs, via the @samp{_SOURCES} variables. Note that the library
2076 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
2077 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
2078 not @samp{liblob.a_SOURCES}.
2080 @cindex _LIBADD primary, defined
2081 @cindex LIBADD primary, defined
2082 @cindex Primary variable, LIBADD
2084 Extra objects can be added to a library using the
2085 @samp{@var{library}_LIBADD} variable. This should be used for objects
2086 determined by @code{configure}. Again from @code{cpio}:
2091 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
2094 In addition, sources for extra objects that will not exist until
2095 configure-time must be added to the @code{BUILT_SOURCES} variable
2099 @node A Shared Library, Program and Library Variables, A Library, Programs
2100 @section Building a Shared Library
2102 @cindex Shared libraries, support for
2104 Building shared libraries is a relatively complex matter. For this
2105 reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
2106 Libtool Manual}) was created to help build shared libraries in a
2107 platform-independent way.
2109 @cindex _LTLIBRARIES primary, defined
2110 @cindex LTLIBRARIES primary, defined
2111 @cindex Primary variable, LTLIBRARIES
2112 @cindex Example of shared libraries
2114 @cindex suffix .la, defined
2116 Automake uses Libtool to build libraries declared with the
2117 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
2118 of shared libraries to build. For instance, to create a library named
2119 @file{libgettext.a} and its corresponding shared libraries, and install
2120 them in @samp{libdir}, write:
2123 lib_LTLIBRARIES = libgettext.la
2126 @vindex lib_LTLIBRARIES
2127 @vindex pkglib_LTLIBRARIES
2128 @vindex noinst_LTLIBRARIES
2129 @vindex check_LTLIBRARIES
2131 @cindex check_LTLIBRARIES, not allowed
2133 Note that shared libraries @emph{must} be installed in order to work
2134 properly, so @code{check_LTLIBRARIES} is not allowed. However,
2135 @code{noinst_LTLIBRARIES} is allowed. This feature should be used for
2136 libtool ``convenience libraries''.
2138 @cindex suffix .lo, defined
2140 For each library, the @samp{@var{library}_LIBADD} variable contains the
2141 names of extra libtool objects (@file{.lo} files) to add to the shared
2142 library. The @samp{@var{library}_LDFLAGS} variable contains any
2143 additional libtool flags, such as @samp{-version-info} or
2146 @cindex @@LTLIBOBJS@@, special handling
2148 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
2149 library must use @code{@@LTLIBOBJS@@}. This is required because the
2150 object files that libtool operates on do not necessarily end in
2151 @file{.o}. The libtool manual contains more details on this topic.
2153 For libraries installed in some directory, Automake will automatically
2154 supply the appropriate @samp{-rpath} option. However, for libraries
2155 determined at configure time (and thus mentioned in
2156 @code{EXTRA_LTLIBRARIES}), Automake does not know the eventual
2157 installation directory; for such libraries you must add the
2158 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
2161 Ordinarily, Automake requires that a shared library's name start with
2162 @samp{lib}. However, if you are building a dynamically loadable module
2163 then you might wish to use a "nonstandard" name. In this case, put
2164 @code{-module} into the @samp{_LDFLAGS} variable.
2166 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
2167 libtool, The Libtool Manual}, for more information.
2170 @node Program and Library Variables, LIBOBJS, A Shared Library, Programs
2171 @section Program and Library Variables
2173 Associated with each program are a collection of variables which can be
2174 used to modify how that program is built. There is a similar list of
2175 such variables for each library. The canonical name of the program (or
2176 library) is used as a base for naming these variables.
2178 In the list below, we use the name ``maude'' to refer to the program or
2179 library. In your @file{Makefile.am} you would replace this with the
2180 canonical name of your program. This list also refers to ``maude'' as a
2181 program, but in general the same rules apply for both static and dynamic
2182 libraries; the documentation below notes situations where programs and
2187 This variable, if it exists, lists all the source files which are
2188 compiled to build the program. These files are added to the
2189 distribution by default. When building the program, Automake will cause
2190 each source file to be compiled to a single @file{.o} file (or
2191 @file{.lo} when using libtool). Normally these object files are named
2192 after the source file, but other factors can change this. If a file in
2193 the @samp{_SOURCES} variable has an unrecognized extension, Automake
2194 will do one of two things with it. If a suffix rule exists for turning
2195 files with the unrecognized extension into @file{.o} files, then
2196 automake will treat this file as it will any other source file
2197 (@pxref{Support for Other Languages}). Otherwise, the file will be
2198 ignored as though it were a header file.
2200 The prefixes @samp{dist_} and @samp{nodist_} can be used to control
2201 whether files listed in a @samp{_SOURCES} variable are distributed.
2202 @samp{dist_} is redundant, as sources are distributed by default, but it
2203 can be specified for clarity if desired.
2205 It is possible to have both @samp{dist_} and @samp{nodist_} variants of
2206 a given @samp{_SOURCES} variable at once; this lets you easily
2207 distribute some files and not others, for instance:
2210 nodist_maude_SOURCES = nodist.c
2211 dist_maude_SOURCES = dist-me.c
2214 By default the output file (on Unix systems, the @file{.o} file) will be
2215 put into the current build directory. However, if the option
2216 @code{subdir-objects} is in effect in the current directory then the
2217 @file{.o} file will be put into the subdirectory named after the source
2218 file. For instance, with @code{subdir-objects} enabled,
2219 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
2220 people prefer this mode of operation. You can specify
2221 @code{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
2222 @cindex Subdirectory, objects in
2223 @cindex Objects in subdirectory
2226 @item EXTRA_maude_SOURCES
2227 Automake needs to know the list of files you intend to compile
2228 @emph{statically}. For one thing, this is the only way Automake has of
2229 knowing what sort of language support a given @file{Makefile.in}
2230 requires. @footnote{There are other, more obscure reasons reasons for
2231 this limitation as well.} This means that, for example, you can't put a
2232 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
2233 variable. If you intend to conditionally compile source files and use
2234 @file{configure} to substitute the appropriate object names into, e.g.,
2235 @samp{_LDADD} (see below), then you should list the corresponding source
2236 files in the @samp{EXTRA_} variable.
2238 This variable also supports @samp{dist_} and @samp{nodist_} prefixes,
2239 e.g., @samp{nodist_EXTRA_maude_SOURCES}.
2242 A static library is created by default by invoking @code{$(AR) cru}
2243 followed by the name of the library and then the objects being put into
2244 the library. You can override this by setting the @samp{_AR} variable.
2245 This is usually used with C++; some C++ compilers require a special
2246 invocation in order to instantiate all the templates which should go
2247 into a library. For instance, the SGI C++ compiler likes this macro set
2250 libmaude_a_AR = $(CXX) -ar -o
2254 Extra objects can be added to a static library using the @samp{_LIBADD}
2255 variable. This should be used for objects determined by
2256 @code{configure}. Note that @samp{_LIBADD} is not used for shared
2257 libraries; there you must use @samp{_LDADD}.
2260 Extra objects can be added to a shared library or a program by listing
2261 them in the @samp{_LDADD} variable. This should be used for objects
2262 determined by @code{configure}.
2264 @samp{_LDADD} and @samp{_LIBADD} are inappropriate for passing
2265 program-specific linker flags (except for @samp{-l}, @samp{-L},
2266 @samp{-dlopen} and @samp{-dlpreopen}). Use the @samp{_LDFLAGS} variable
2269 For instance, if your @file{configure.in} uses @code{AC_PATH_XTRA}, you
2270 could link your program against the X libraries like so:
2273 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
2277 This variable is used to pass extra flags to the link step of a program
2278 or a shared library.
2281 You can override the linker on a per-program basis. By default the
2282 linker is chosen according to the languages used by the program. For
2283 instance, a program that includes C++ source code would use the C++
2284 compiler to link. The @samp{_LINK} variable must hold the name of a
2285 command which can be passed all the @file{.o} file names as arguments.
2286 Note that the name of the underlying program is @emph{not} passed to
2287 @samp{_LINK}; typically one uses @samp{$@@}:
2290 maude_LINK = $(CCLD) -magic -o $@@
2294 Automake allows you to set compilation flags on a per-program (or
2295 per-library) basis. A single source file can be included in several
2296 programs, and it will potentially be compiled with different flags for
2297 each program. This works for any language directly supported by
2298 Automake. The flags are @samp{_CFLAGS}, @samp{_CXXFLAGS},
2299 @samp{_OBJCFLAGS}, @samp{_LFLAGS}, @samp{_YFLAGS}, @samp{_CCASFLAGS},
2300 @samp{_FFLAGS}, @samp{_RFLAGS}, and @samp{_GCJFLAGS}.
2302 When using a per-program compilation flag, Automake will choose a
2303 different name for the intermediate object files. Ordinarily a file
2304 like @file{sample.c} will be compiled to produce @file{sample.o}.
2305 However, if the program's @samp{_CFLAGS} variable is set, then the
2306 object file will be named, for instance, @file{maude-sample.o}.
2308 In compilations with per-program flags, the ordinary @samp{AM_} form of
2309 the flags variable is @emph{not} automatically included in the
2310 compilation (however, the user form of the variable @emph{is} included).
2311 So for instance, if you want the hypothetical @file{maude} compilations
2312 to also use the value of @samp{AM_CFLAGS}, you would need to write:
2315 maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
2318 @item maude_DEPENDENCIES
2319 It is also occasionally useful to have a program depend on some other
2320 target which is not actually part of that program. This can be done
2321 using the @samp{_DEPENDENCIES} variable. Each program depends on the
2322 contents of such a variable, but no further interpretation is done.
2324 If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake.
2325 The automatically-assigned value is the contents of @samp{_LDADD} or
2326 @samp{_LIBADD}, with most configure substitutions, @samp{-l}, @samp{-L},
2327 @samp{-dlopen} and @samp{-dlpreopen} options removed. The configure
2328 substitutions that are left in are only @samp{@@LIBOBJS@@} and
2329 @samp{@@ALLOCA@@}; these are left because it is known that they will not
2330 cause an invalid value for @samp{_DEPENDENCIES} to be generated.
2332 @item maude_SHORTNAME
2333 On some platforms the allowable file names are very short. In order to
2334 support these systems and per-program compilation flags at the same
2335 time, Automake allows you to set a ``short name'' which will influence
2336 how intermediate object files are named. For instance, if you set
2337 @samp{maude_SHORTNAME} to @samp{m}, then in the above per-program
2338 compilation flag example the object file would be named
2339 @file{m-sample.o} rather than @file{maude-sample.o}. This facility is
2340 rarely needed in practice, and we recommend avoiding it until you find
2345 @node LIBOBJS, Program variables, Program and Library Variables, Programs
2346 @section Special handling for LIBOBJS and ALLOCA
2348 @cindex @@LIBOBJS@@, special handling
2349 @cindex @@ALLOCA@@, special handling
2351 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
2352 @code{@@ALLOCA@@}, and uses this information, plus the list of
2353 @code{LIBOBJS} files derived from @file{configure.in} to automatically
2354 include the appropriate source files in the distribution (@pxref{Dist}).
2355 These source files are also automatically handled in the
2356 dependency-tracking scheme; see @xref{Dependencies}.
2358 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
2359 @samp{_LDADD} or @samp{_LIBADD} variable.
2362 @node Program variables, Yacc and Lex, LIBOBJS, Programs
2363 @section Variables used when building a program
2365 Occasionally it is useful to know which @file{Makefile} variables
2366 Automake uses for compilations; for instance you might need to do your
2367 own compilation in some special cases.
2369 Some variables are inherited from Autoconf; these are @code{CC},
2370 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
2379 There are some additional variables which Automake itself defines:
2383 The contents of this macro are passed to every compilation which invokes
2384 the C preprocessor; it is a list of arguments to the preprocessor. For
2385 instance, @samp{-I} and @samp{-D} options should be listed here.
2387 Automake already provides some @samp{-I} options automatically. In
2388 particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I}
2389 pointing to the directory holding @file{config.h} (if you've used
2390 @code{AC_CONFIG_HEADERS} or @code{AM_CONFIG_HEADER}). You can disable
2391 the default @samp{-I} options using the @samp{nostdinc} option.
2394 This does the same job as @samp{AM_CPPFLAGS}. It is an older name for
2395 the same functionality. This macro is deprecated; we suggest using
2396 @samp{AM_CPPFLAGS} instead.
2399 This is the variable which the @file{Makefile.am} author can use to pass
2400 in additional C compiler flags. It is more fully documented elsewhere.
2401 In some situations, this is not used, in preference to the
2402 per-executable (or per-library) @code{_CFLAGS}.
2405 This is the command used to actually compile a C source file. The
2406 filename is appended to form the complete command line.
2409 This is the variable which the @file{Makefile.am} author can use to pass
2410 in additional linker flags. In some situations, this is not used, in
2411 preference to the per-executable (or per-library) @code{_LDFLAGS}.
2414 This is the command used to actually link a C program. It already
2415 includes @samp{-o $@@} and the usual variable references (for instance,
2416 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
2417 and libraries to link in.
2421 @node Yacc and Lex, C++ Support, Program variables, Programs
2422 @section Yacc and Lex support
2424 Automake has somewhat idiosyncratic support for Yacc and Lex.
2426 Automake assumes that the @file{.c} file generated by @code{yacc} (or
2427 @code{lex}) should be named using the basename of the input file. That
2428 is, for a yacc source file @file{foo.y}, Automake will cause the
2429 intermediate file to be named @file{foo.c} (as opposed to
2430 @file{y.tab.c}, which is more traditional).
2432 The extension of a yacc source file is used to determine the extension
2433 of the resulting @samp{C} or @samp{C++} file. Files with the extension
2434 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
2435 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
2438 Likewise, lex source files can be used to generate @samp{C} or
2439 @samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
2440 @samp{.lxx} are recognized.
2442 You should never explicitly mention the intermediate (@samp{C} or
2443 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
2446 The intermediate files generated by @code{yacc} (or @code{lex}) will be
2447 included in any distribution that is made. That way the user doesn't
2448 need to have @code{yacc} or @code{lex}.
2450 If a @code{yacc} source file is seen, then your @file{configure.in} must
2451 define the variable @samp{YACC}. This is most easily done by invoking
2452 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
2453 Program Checks, autoconf, The Autoconf Manual}).
2455 When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
2456 @samp{AM_YFLAGS}. The former is a user variable and the latter is
2457 intended for the @file{Makefile.am} author.
2459 Similarly, if a @code{lex} source file is seen, then your
2460 @file{configure.in} must define the variable @samp{LEX}. You can use
2461 @samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
2462 Program Checks, autoconf, The Autoconf Manual}), but using
2463 @code{AM_PROG_LEX} macro (@pxref{Macros}) is recommended.
2465 When @code{lex} is invoked, it is passed @samp{LFLAGS} and
2466 @samp{AM_LFLAGS}. The former is a user variable and the latter is
2467 intended for the @file{Makefile.am} author.
2472 @cindex yacc, multiple parsers
2473 @cindex Multiple yacc parsers
2474 @cindex Multiple lex lexers
2475 @cindex lex, multiple lexers
2478 Automake makes it possible to include multiple @code{yacc} (or
2479 @code{lex}) source files in a single program. Automake uses a small
2480 program called @code{ylwrap} to run @code{yacc} (or @code{lex}) in a
2481 subdirectory. This is necessary because yacc's output filename is
2482 fixed, and a parallel make could conceivably invoke more than one
2483 instance of @code{yacc} simultaneously. The @code{ylwrap} program is
2484 distributed with Automake. It should appear in the directory specified
2485 by @samp{AC_CONFIG_AUX_DIR} (@pxref{Input, , Finding `configure' Input,
2486 autoconf, The Autoconf Manual}), or the current directory if that macro
2487 is not used in @file{configure.in}.
2489 For @code{yacc}, simply managing locking is insufficient. The output of
2490 @code{yacc} always uses the same symbol names internally, so it isn't
2491 possible to link two @code{yacc} parsers into the same executable.
2493 We recommend using the following renaming hack used in @code{gdb}:
2495 #define yymaxdepth c_maxdepth
2496 #define yyparse c_parse
2498 #define yyerror c_error
2499 #define yylval c_lval
2500 #define yychar c_char
2501 #define yydebug c_debug
2502 #define yypact c_pact
2509 #define yyexca c_exca
2510 #define yyerrflag c_errflag
2511 #define yynerrs c_nerrs
2515 #define yy_yys c_yys
2516 #define yystate c_state
2519 #define yy_yyv c_yyv
2521 #define yylloc c_lloc
2522 #define yyreds c_reds
2523 #define yytoks c_toks
2524 #define yylhs c_yylhs
2525 #define yylen c_yylen
2526 #define yydefred c_yydefred
2527 #define yydgoto c_yydgoto
2528 #define yysindex c_yysindex
2529 #define yyrindex c_yyrindex
2530 #define yygindex c_yygindex
2531 #define yytable c_yytable
2532 #define yycheck c_yycheck
2533 #define yyname c_yyname
2534 #define yyrule c_yyrule
2537 For each define, replace the @samp{c_} prefix with whatever you like.
2538 These defines work for @code{bison}, @code{byacc}, and traditional
2539 @code{yacc}s. If you find a parser generator that uses a symbol not
2540 covered here, please report the new name so it can be added to the list.
2543 @node C++ Support, Assembly Support, Yacc and Lex, Programs
2544 @section C++ Support
2547 @cindex Support for C++
2549 Automake includes full support for C++.
2551 Any package including C++ code must define the output variable
2552 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
2553 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
2554 Program Checks, autoconf, The Autoconf Manual}).
2556 A few additional variables are defined when a C++ source file is seen:
2560 The name of the C++ compiler.
2563 Any flags to pass to the C++ compiler.
2566 The maintainer's variant of @code{CXXFLAGS}.
2569 The command used to actually compile a C++ source file. The file name
2570 is appended to form the complete command line.
2573 The command used to actually link a C++ program.
2577 @node Assembly Support, Fortran 77 Support, C++ Support, Programs
2578 @section Assembly Support
2580 Automake includes some support for assembly code.
2582 The variable @code{CCAS} holds the name of the compiler used to build
2583 assembly code. This compiler must work a bit like a C compiler; in
2584 particular it must accept @samp{-c} and @samp{-o}. The value of
2585 @code{CCASFLAGS} is passed to the compilation.
2589 You are required to set @code{CCAS} and @code{CCASFLAGS} via
2590 @file{configure.in}. The autoconf macro @code{AM_PROG_AS} will do this
2591 for you. Unless they are already set, it simply sets @code{CCAS} to the
2592 C compiler and @code{CCASFLAGS} to the C compiler flags.
2594 Only the suffixes @samp{.s} and @samp{.S} are recognized by
2595 @code{automake} as being files containing assembly code.
2598 @node Fortran 77 Support, Java Support, Assembly Support, Programs
2599 @comment node-name, next, previous, up
2600 @section Fortran 77 Support
2602 @cindex Fortran 77 support
2603 @cindex Support for Fortran 77
2605 Automake includes full support for Fortran 77.
2607 Any package including Fortran 77 code must define the output variable
2608 @samp{F77} in @file{configure.in}; the simplest way to do this is to use
2609 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
2610 Program Checks, autoconf, The Autoconf Manual}). @xref{Fortran 77 and
2613 A few additional variables are defined when a Fortran 77 source file is
2619 The name of the Fortran 77 compiler.
2622 Any flags to pass to the Fortran 77 compiler.
2625 The maintainer's variant of @code{FFLAGS}.
2628 Any flags to pass to the Ratfor compiler.
2631 The maintainer's variant of @code{RFLAGS}.
2634 The command used to actually compile a Fortran 77 source file. The file
2635 name is appended to form the complete command line.
2638 The command used to actually link a pure Fortran 77 program or shared
2643 Automake can handle preprocessing Fortran 77 and Ratfor source files in
2644 addition to compiling them@footnote{Much, if not most, of the
2645 information in the following sections pertaining to preprocessing
2646 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
2647 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
2648 also contains some support for creating programs and shared libraries
2649 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
2650 Fortran 77 With C and C++}).
2652 These issues are covered in the following sections.
2655 * Preprocessing Fortran 77::
2656 * Compiling Fortran 77 Files::
2657 * Mixing Fortran 77 With C and C++::
2658 * Fortran 77 and Autoconf::
2662 @node Preprocessing Fortran 77, Compiling Fortran 77 Files, Fortran 77 Support, Fortran 77 Support
2663 @comment node-name, next, previous, up
2664 @subsection Preprocessing Fortran 77
2666 @cindex Preprocessing Fortran 77
2667 @cindex Fortran 77, Preprocessing
2668 @cindex Ratfor programs
2670 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
2671 rule runs just the preprocessor to convert a preprocessable Fortran 77
2672 or Ratfor source file into a strict Fortran 77 source file. The precise
2673 command used is as follows:
2678 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2681 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2686 @node Compiling Fortran 77 Files, Mixing Fortran 77 With C and C++, Preprocessing Fortran 77, Fortran 77 Support
2687 @comment node-name, next, previous, up
2688 @subsection Compiling Fortran 77 Files
2690 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
2691 @file{N.r} by running the Fortran 77 compiler. The precise command used
2697 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
2700 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2703 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2708 @node Mixing Fortran 77 With C and C++, Fortran 77 and Autoconf, Compiling Fortran 77 Files, Fortran 77 Support
2709 @comment node-name, next, previous, up
2710 @subsection Mixing Fortran 77 With C and C++
2712 @cindex Fortran 77, mixing with C and C++
2713 @cindex Mixing Fortran 77 with C and C++
2714 @cindex Linking Fortran 77 with C and C++
2716 @cindex Mixing Fortran 77 with C and/or C++
2718 Automake currently provides @emph{limited} support for creating programs
2719 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
2720 However, there are many other issues related to mixing Fortran 77 with
2721 other languages that are @emph{not} (currently) handled by Automake, but
2722 that are handled by other packages@footnote{For example,
2723 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
2724 addresses all of these inter-language issues, and runs under nearly all
2725 Fortran 77, C and C++ compilers on nearly all platforms. However,
2726 @code{cfortran} is not yet Free Software, but it will be in the next
2730 Automake can help in two ways:
2734 Automatic selection of the linker depending on which combinations of
2738 Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
2739 @samp{-l}) to pass to the automatically selected linker in order to link
2740 in the appropriate Fortran 77 intrinsic and run-time libraries.
2742 @cindex FLIBS, defined
2743 These extra Fortran 77 linker flags are supplied in the output variable
2744 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
2745 supplied with newer versions of Autoconf (Autoconf version 2.13 and
2746 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
2750 If Automake detects that a program or shared library (as mentioned in
2751 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
2752 code that is a mixture of Fortran 77 and C and/or C++, then it requires
2753 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
2754 @file{configure.in}, and that either @code{$(FLIBS)} or @code{@@FLIBS@@}
2755 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
2756 (for shared libraries) variables. It is the responsibility of the
2757 person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
2758 or @code{@@FLIBS@@} appears in the appropriate @code{_LDADD} or
2759 @code{_LIBADD} variable.
2761 @cindex Mixed language example
2762 @cindex Example, mixed language
2764 For example, consider the following @file{Makefile.am}:
2768 foo_SOURCES = main.cc foo.f
2769 foo_LDADD = libfoo.la @@FLIBS@@
2771 pkglib_LTLIBRARIES = libfoo.la
2772 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
2773 libfoo_la_LIBADD = $(FLIBS)
2776 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
2777 is mentioned in @file{configure.in}. Also, if @code{@@FLIBS@@} hadn't
2778 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
2779 Automake would have issued a warning.
2784 * How the Linker is Chosen::
2787 @node How the Linker is Chosen, , Mixing Fortran 77 With C and C++, Mixing Fortran 77 With C and C++
2788 @comment node-name, next, previous, up
2789 @subsubsection How the Linker is Chosen
2791 @cindex Automatic linker selection
2792 @cindex Selecting the linker automatically
2794 The following diagram demonstrates under what conditions a particular
2795 linker is chosen by Automake.
2797 For example, if Fortran 77, C and C++ source code were to be compiled
2798 into a program, then the C++ linker will be used. In this case, if the
2799 C or Fortran 77 linkers required any special libraries that weren't
2800 included by the C++ linker, then they must be manually added to an
2801 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
2807 code \ C C++ Fortran
2808 ----------------- +---------+---------+---------+
2812 +---------+---------+---------+
2816 +---------+---------+---------+
2820 +---------+---------+---------+
2824 +---------+---------+---------+
2826 C + Fortran | | | x |
2828 +---------+---------+---------+
2830 C++ + Fortran | | x | |
2832 +---------+---------+---------+
2834 C + C++ + Fortran | | x | |
2836 +---------+---------+---------+
2840 @node Fortran 77 and Autoconf, , Mixing Fortran 77 With C and C++, Fortran 77 Support
2841 @comment node-name, next, previous, up
2842 @subsection Fortran 77 and Autoconf
2844 The current Automake support for Fortran 77 requires a recent enough
2845 version of Autoconf that also includes support for Fortran 77. Full
2846 Fortran 77 support was added to Autoconf 2.13, so you will want to use
2847 that version of Autoconf or later.
2850 @node Java Support, Support for Other Languages, Fortran 77 Support, Programs
2851 @comment node-name, next, previous, up
2852 @section Java Support
2854 @cindex Java support
2855 @cindex Support for Java
2857 Automake includes support for compiled Java, using @code{gcj}, the Java
2858 front end to the GNU Compiler Collection.
2860 Any package including Java code to be compiled must define the output
2861 variable @samp{GCJ} in @file{configure.in}; the variable @samp{GCJFLAGS}
2862 must also be defined somehow (either in @file{configure.in} or
2863 @file{Makefile.am}). The simplest way to do this is to use the
2864 @code{AM_PROG_GCJ} macro.
2868 By default, programs including Java source files are linked with
2871 As always, the contents of @samp{AM_GCJFLAGS} are passed to every
2872 compilation invoking @code{gcj} (in its role as an ahead-of-time
2873 compiler -- when invoking it to create @file{.class} files,
2874 @samp{AM_JAVACFLAGS} is used instead). If it is necessary to pass
2875 options to @code{gcj} from @file{Makefile.am}, this macro, and not the
2876 user macro @samp{GCJFLAGS}, should be used.
2880 @code{gcj} can be used to compile @file{.java}, @file{.class},
2881 @file{.zip}, or @file{.jar} files.
2884 @node Support for Other Languages, ANSI, Java Support, Programs
2885 @comment node-name, next, previous, up
2886 @section Support for Other Languages
2888 Automake currently only includes full support for C, C++ (@pxref{C++
2889 Support}), Fortran 77 (@pxref{Fortran 77 Support}), and Java
2890 (@pxref{Java Support}). There is only rudimentary support for other
2891 languages, support for which will be improved based on user demand.
2893 Some limited support for adding your own languages is available via the
2894 suffix rule handling; see @ref{Suffixes}.
2897 @node ANSI, Dependencies, Support for Other Languages, Programs
2898 @section Automatic de-ANSI-fication
2900 @cindex de-ANSI-fication, defined
2902 Although the GNU standards allow the use of ANSI C, this can have the
2903 effect of limiting portability of a package to some older compilers
2904 (notably the SunOS C compiler).
2906 Automake allows you to work around this problem on such machines by
2907 @dfn{de-ANSI-fying} each source file before the actual compilation takes
2910 @vindex AUTOMAKE_OPTIONS
2913 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
2914 (@pxref{Options}) contains the option @code{ansi2knr} then code to
2915 handle de-ANSI-fication is inserted into the generated
2918 This causes each C source file in the directory to be treated as ANSI C.
2919 If an ANSI C compiler is available, it is used. If no ANSI C compiler
2920 is available, the @code{ansi2knr} program is used to convert the source
2921 files into K&R C, which is then compiled.
2923 The @code{ansi2knr} program is simple-minded. It assumes the source
2924 code will be formatted in a particular way; see the @code{ansi2knr} man
2927 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
2928 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
2929 these files are distributed with Automake. Also, the package
2930 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}
2932 @cvindex AM_C_PROTOTYPES
2934 Automake also handles finding the @code{ansi2knr} support files in some
2935 other directory in the current package. This is done by prepending the
2936 relative path to the appropriate directory to the @code{ansi2knr}
2937 option. For instance, suppose the package has ANSI C code in the
2938 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
2939 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
2940 @file{src/Makefile.am}:
2943 AUTOMAKE_OPTIONS = ../lib/ansi2knr
2946 If no directory prefix is given, the files are assumed to be in the
2949 Files mentioned in @code{LIBOBJS} which need de-ANSI-fication will not
2950 be automatically handled. That's because @code{configure} will generate
2951 an object name like @file{regex.o}, while @code{make} will be looking
2952 for @file{regex_.o} (when de-ANSI-fying). Eventually this problem will
2953 be fixed via @code{autoconf} magic, but for now you must put this code
2954 into your @file{configure.in}, just before the @code{AC_OUTPUT} call:
2957 # This is necessary so that .o files in LIBOBJS are also built via
2958 # the ANSI2KNR-filtering rules.
2959 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
2961 @c FIXME: Ask Akim how this should be handled in the upcoming Autoconf.
2963 Note that automatic de-ANSI-fication will not work when the package is
2964 being built for a different host architecture. That is because automake
2965 currently has no way to build @code{ansi2knr} for the build machine.
2968 @node Dependencies, EXEEXT, ANSI, Programs
2969 @section Automatic dependency tracking
2971 As a developer it is often painful to continually update the
2972 @file{Makefile.in} whenever the include-file dependencies change in a
2973 project. Automake supplies a way to automatically track dependency
2976 @cindex Dependency tracking
2977 @cindex Automatic dependency tracking
2979 Automake always uses complete dependencies for a compilation, including
2980 system headers. Automake's model is that dependency computation should
2981 be a side effect of the build. To this end, dependencies are computed
2982 by running all compilations through a special wrapper program called
2983 @code{depcomp}. @code{depcomp} understands how to coax many different C
2984 and C++ compilers into generating dependency information in the format
2985 it requires. @code{automake -a} will install @code{depcomp} into your
2986 source tree for you. If @code{depcomp} can't figure out how to properly
2987 invoke your compiler, dependency tracking will simply be disabled for
2992 Experience with earlier versions of Automake @footnote{See
2993 @uref{http://sources.redhat.com/automake/dependencies.html} for more
2994 information on the history and experiences with automatic dependency
2995 tracking in Automake} taught us that it is not reliable to generate
2996 dependencies only on the maintainer's system, as configurations vary too
2997 much. So instead Automake implements dependency tracking at build time.
2999 Automatic dependency tracking can be suppressed by putting
3000 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
3001 passing @code{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
3002 (this should be the prefered way). Or, you can invoke @code{automake}
3003 with the @code{-i} option. Dependency tracking is enabled by default.
3005 @vindex AUTOMAKE_OPTIONS
3006 @opindex no-dependencies
3008 The person building your package also can choose to disable dependency
3009 tracking by configuring with @code{--disable-dependency-tracking}.
3011 @cindex Disabling dependency tracking
3012 @cindex Dependency tracking, disabling
3015 @node EXEEXT, , Dependencies, Programs
3016 @section Support for executable extensions
3018 @cindex Executable extension
3019 @cindex Extension, executable
3022 On some platforms, such as Windows, executables are expected to have an
3023 extension such as @samp{.exe}. On these platforms, some compilers (GCC
3024 among them) will automatically generate @file{foo.exe} when asked to
3025 generate @file{foo}.
3027 Automake provides mostly-transparent support for this. Unfortunately
3028 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
3029 dictionary is revised, you will have to assist Automake if your package
3030 must support those platforms.
3032 One thing you must be aware of is that, internally, Automake rewrites
3033 something like this:
3036 bin_PROGRAMS = liver
3042 bin_PROGRAMS = liver$(EXEEXT)
3045 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
3046 extension. @code{EXEEXT}
3048 However, Automake cannot apply this rewriting to @code{configure}
3049 substitutions. This means that if you are conditionally building a
3050 program using such a substitution, then your @file{configure.in} must
3051 take care to add @samp{$(EXEEXT)} when constructing the output variable.
3053 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
3054 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
3055 automatically if you configure a compiler (say, through
3058 Sometimes maintainers like to write an explicit link rule for their
3059 program. Without executable extension support, this is easy---you
3060 simply write a target with the same name as the program. However, when
3061 executable extension support is enabled, you must instead add the
3062 @samp{$(EXEEXT)} suffix.
3064 Unfortunately, due to the change in Autoconf 2.50, this means you must
3065 always add this extension. However, this is a problem for maintainers
3066 who know their package will never run on a platform that has executable
3067 extensions. For those maintainers, the @code{no-exeext} option
3068 (@pxref{Options}) will disable this feature. This works in a fairly
3069 ugly way; if @code{no-exeext} is seen, then the presence of a target
3070 named @code{foo} in @file{Makefile.am} will override an
3071 automake-generated target of the form @code{foo$(EXEEXT)}. Without the
3072 @code{no-exeext} option, this use will give an error.
3075 @node Other objects, Other GNU Tools, Programs, Top
3076 @chapter Other Derived Objects
3078 Automake can handle derived objects which are not C programs. Sometimes
3079 the support for actually building such objects must be explicitly
3080 supplied, but Automake will still automatically handle installation and
3084 * Scripts:: Executable scripts
3085 * Headers:: Header files
3086 * Data:: Architecture-independent data files
3087 * Sources:: Derived sources
3091 @node Scripts, Headers, Other objects, Other objects
3092 @section Executable Scripts
3094 @cindex _SCRIPTS primary, defined
3095 @cindex SCRIPTS primary, defined
3096 @cindex Primary variable, SCRIPTS
3098 It is possible to define and install programs which are scripts. Such
3099 programs are listed using the @samp{SCRIPTS} primary name. Automake
3100 doesn't define any dependencies for scripts; the @file{Makefile.am}
3101 should include the appropriate rules.
3104 Automake does not assume that scripts are derived objects; such objects
3105 must be deleted by hand (@pxref{Clean}).
3107 The @code{automake} program itself is a Perl script that is generated at
3108 configure time from @file{automake.in}. Here is how this is handled:
3111 bin_SCRIPTS = automake
3114 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
3115 for it is automatically generated, and it is also automatically cleaned
3116 (despite the fact it's a script).
3118 @cindex SCRIPTS, installation directories
3119 @cindex Installing scripts
3122 @vindex sbin_SCRIPTS
3123 @vindex libexec_SCRIPTS
3124 @vindex pkgdata_SCRIPTS
3125 @vindex noinst_SCRIPTS
3126 @vindex check_SCRIPTS
3128 Script objects can be installed in @code{bindir}, @code{sbindir},
3129 @code{libexecdir}, or @code{pkgdatadir}.
3131 Scripts that need not being installed can be listed in
3132 @code{noinst_SCRIPTS}, and among them, those which are needed only by
3133 @code{make check} should go in @code{check_SCRIPTS}.
3136 @node Headers, Data, Scripts, Other objects
3137 @section Header files
3139 @cindex _HEADERS primary, defined
3140 @cindex HEADERS primary, defined
3141 @cindex Primary variable, HEADERS
3143 @vindex noinst_HEADERS
3145 Header files are specified by the @samp{HEADERS} family of variables.
3146 Generally header files are not installed, so the @code{noinst_HEADERS}
3147 variable will be the most used. @footnote{However, for the case of a
3148 non-installed header file that is actually used by a particular program,
3149 we recommend listing it in the program's @samp{_SOURCES} variable
3150 instead of in @code{noinst_HEADERS}. We believe this is more clear.}
3153 All header files must be listed somewhere; missing ones will not appear
3154 in the distribution. Often it is clearest to list uninstalled headers
3155 with the rest of the sources for a program. @xref{A Program}. Headers
3156 listed in a @samp{_SOURCES} variable need not be listed in any
3157 @samp{_HEADERS} variable.
3159 @cindex HEADERS, installation directories
3160 @cindex Installing headers
3162 @vindex include_HEADERS
3163 @vindex oldinclude_HEADERS
3164 @vindex pkginclude_HEADERS
3166 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
3167 @code{pkgincludedir}.
3170 @node Data, Sources, Headers, Other objects
3171 @section Architecture-independent data files
3173 @cindex _DATA primary, defined
3174 @cindex DATA primary, defined
3175 @cindex Primary variable, DATA
3177 Automake supports the installation of miscellaneous data files using the
3178 @samp{DATA} family of variables.
3182 @vindex sysconf_DATA
3183 @vindex sharedstate_DATA
3184 @vindex localstate_DATA
3185 @vindex pkgdata_DATA
3187 Such data can be installed in the directories @code{datadir},
3188 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
3191 By default, data files are @emph{not} included in a distribution. Of
3192 course, you can use the @samp{dist_} prefix to change this on a
3195 Here is how Automake declares its auxiliary data files:
3198 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
3202 @node Sources, , Data, Other objects
3203 @section Built sources
3205 @cindex BUILT_SOURCES, defined
3207 Occasionally a file which would otherwise be called @samp{source}
3208 (e.g. a C @samp{.h} file) is actually derived from some other file.
3209 Such files should be listed in the @code{BUILT_SOURCES} variable.
3210 @vindex BUILT_SOURCES
3212 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
3213 must be created early in the build process can be listed in this
3216 A source file listed in @code{BUILT_SOURCES} is created before the other
3217 @code{all} targets are made. However, such a source file is not
3218 compiled unless explicitly requested by mentioning it in some other
3219 @samp{_SOURCES} variable.
3221 So, for instance, if you had header files which were created by a script
3222 run at build time, then you would list these headers in
3223 @code{BUILT_SOURCES}, to ensure that they would be built before any
3224 other compilations (perhaps ones using these headers) were started.
3227 @node Other GNU Tools, Documentation, Other objects, Top
3228 @chapter Other GNU Tools
3230 Since Automake is primarily intended to generate @file{Makefile.in}s for
3231 use in GNU programs, it tries hard to interoperate with other GNU tools.
3234 * Emacs Lisp:: Emacs Lisp
3242 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
3245 @cindex _LISP primary, defined
3246 @cindex LISP primary, defined
3247 @cindex Primary variable, LISP
3253 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
3254 is used to hold a list of @file{.el} files. Possible prefixes for this
3255 primary are @samp{lisp_} and @samp{noinst_}. Note that if
3256 @code{lisp_LISP} is defined, then @file{configure.in} must run
3257 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
3261 By default Automake will byte-compile all Emacs Lisp source files using
3262 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
3263 byte-compiling, simply define the variable @code{ELCFILES} to be empty.
3264 Byte-compiled Emacs Lisp files are not portable among all versions of
3265 Emacs, so it makes sense to turn this off if you expect sites to have
3266 more than one version of Emacs installed. Furthermore, many packages
3267 don't actually benefit from byte-compilation. Still, we recommend that
3268 you leave it enabled by default. It is probably better for sites with
3269 strange setups to cope for themselves than to make the installation less
3270 nice for everybody else.
3273 @node gettext, Libtool, Emacs Lisp, Other GNU Tools
3276 @cindex GNU Gettext support
3277 @cindex Gettext support
3278 @cindex Support for GNU Gettext
3280 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
3281 turns on support for GNU gettext, a message catalog system for
3282 internationalization
3283 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
3285 The @code{gettext} support in Automake requires the addition of two
3286 subdirectories to the package, @file{intl} and @file{po}. Automake
3287 insures that these directories exist and are mentioned in
3291 @node Libtool, Java, gettext, Other GNU Tools
3294 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
3295 libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
3296 @xref{A Shared Library}.
3299 @node Java, Python, Libtool, Other GNU Tools
3302 @cindex _JAVA primary, defined
3303 @cindex JAVA primary, defined
3304 @cindex Primary variable, JAVA
3306 Automake provides some minimal support for Java compilation with the
3307 @samp{JAVA} primary.
3309 Any @file{.java} files listed in a @samp{_JAVA} variable will be
3310 compiled with @code{JAVAC} at build time. By default, @file{.class}
3311 files are not included in the distribution.
3313 @cindex JAVA restrictions
3314 @cindex Restrictions for JAVA
3316 Currently Automake enforces the restriction that only one @samp{_JAVA}
3317 primary can be used in a given @file{Makefile.am}. The reason for this
3318 restriction is that, in general, it isn't possible to know which
3319 @file{.class} files were generated from which @file{.java} files -- so
3320 it would be impossible to know which files to install where. For
3321 instance, a @file{.java} file can define multiple classes; the resulting
3322 @file{.class} file names cannot be predicted without parsing the
3325 There are a few variables which are used when compiling Java sources:
3329 The name of the Java compiler. This defaults to @samp{javac}.
3332 The flags to pass to the compiler. This is considered to be a user
3333 variable (@pxref{User Variables}).
3336 More flags to pass to the Java compiler. This, and not
3337 @code{JAVACFLAGS}, should be used when it is necessary to put Java
3338 compiler flags into @file{Makefile.am}.
3341 The value of this variable is passed to the @samp{-d} option to
3342 @code{javac}. It defaults to @samp{$(top_builddir)}.
3345 This variable is an @code{sh} expression which is used to set the
3346 @code{CLASSPATH} environment variable on the @code{javac} command line.
3347 (In the future we will probably handle class path setting differently.)
3351 @node Python, , Java, Other GNU Tools
3354 @cindex _PYTHON primary, defined
3355 @cindex PYTHON primary, defined
3356 @cindex Primary variable, PYTHON
3359 Automake provides support for Python compilation with the @samp{PYTHON}
3362 Any files listed in a @samp{_PYTHON} variable will be byte-compiled with
3363 @code{py-compile} at install time. @code{py-compile} actually creates
3364 both standard (@file{.pyc}) and byte-compiled (@file{.pyo}) versions of
3365 the source files. Note that because byte-compilation occurs at install
3366 time, any files listed in @samp{noinst_PYTHON} will not be compiled.
3367 Python source files are included in the distribution by default.
3369 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} which
3370 will determine some Python-related directory variables (see below). If
3371 have called @code{AM_PATH_PYTHON} from you @file{configure.in}, then you
3372 may use the following variables to list you Python source files in your
3373 variables: @samp{python_PYTHON}, @samp{pkgpython_PYTHON},
3374 @samp{pkgpython_PYTHON}, @samp{pyexecdir_PYTHON},
3375 @samp{pkgpyexecdir_PYTHON}, depending where you want your files
3378 @code{AM_PATH_PYTHON} takes a single optional argument. This argument,
3379 if present, is the minimum version of Python which can be used for this
3380 package. If the version of Python found on the system is older than the
3381 required version, then @code{AM_PATH_PYTHON} will cause an error.
3383 @code{AM_PATH_PYTHON} creates several output variables based on the
3384 Python installation found during configuration.
3388 The name of the Python executable.
3390 @item PYTHON_VERSION
3391 The Python version number, in the form @var{major}.@var{minor}
3392 (e.g. @samp{1.5}). This is currently the value of
3393 @code{sys.version[:3]}.
3396 The string @code{$prefix}. This term may be used in future work
3397 which needs the contents of Python's @code{sys.prefix}, but general
3398 consensus is to always use the value from configure.
3400 @item PYTHON_EXEC_PREFIX
3401 The string @code{$exec_prefix}. This term may be used in future work
3402 which needs the contents of Python's @code{sys.exec_prefix}, but general
3403 consensus is to always use the value from configure.
3405 @item PYTHON_PLATFORM
3406 The canonical name used by Python to describe the operating system, as
3407 given by @code{sys.platform}. This value is sometimes needed when
3408 building Python extensions.
3411 The directory name for the @file{site-packages} subdirectory of the
3412 standard Python install tree.
3415 This is is the directory under @code{pythondir} which is named after the
3416 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
3420 This is the directory where Python extension modules (shared libraries)
3421 should be installed.
3424 This is a convenience variable which is defined as
3425 @samp{$(pyexecdir)/$(PACKAGE)}.
3429 @node Documentation, Install, Other GNU Tools, Top
3430 @chapter Building documentation
3432 Currently Automake provides support for Texinfo and man pages.
3436 * Man pages:: Man pages
3440 @node Texinfo, Man pages, Documentation, Documentation
3443 @cindex _TEXINFOS primary, defined
3444 @cindex TEXINFOS primary, defined
3445 @cindex Primary variable, TEXINFOS
3447 If the current directory contains Texinfo source, you must declare it
3448 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
3449 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
3450 here. Any Texinfo source file must end in the @file{.texi},
3451 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
3454 @vindex info_TEXINFOS
3456 @cindex Texinfo macro, VERSION
3457 @cindex Texinfo macro, UPDATED
3458 @cindex Texinfo macro, EDITION
3459 @cindex Texinfo macro, UPDATED-MONTH
3461 @cindex VERSION Texinfo macro
3462 @cindex UPDATED Texinfo macro
3463 @cindex EDITION Texinfo macro
3464 @cindex UPDATED-MONTH Texinfo macro
3468 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
3469 that file will be automatically generated. The file @file{version.texi}
3470 defines four Texinfo macros you can reference:
3475 Both of these macros hold the version number of your program. They are
3476 kept separate for clarity.
3479 This holds the date the primary @file{.texi} file was last modified.
3482 This holds the name of the month in which the primary @file{.texi} file
3486 The @file{version.texi} support requires the @code{mdate-sh} program;
3487 this program is supplied with Automake and automatically included when
3488 @code{automake} is invoked with the @code{--add-missing} option.
3490 If you have multiple Texinfo files, and you want to use the
3491 @file{version.texi} feature, then you have to have a separate version
3492 file for each Texinfo file. Automake will treat any include in a
3493 Texinfo file that matches @samp{vers*.texi} just as an automatically
3494 generated version file.
3496 When an info file is rebuilt, the program named by the @code{MAKEINFO}
3497 variable is used to invoke it. If the @code{makeinfo} program is found
3498 on the system then it will be used by default; otherwise @code{missing}
3499 will be used instead. The flags in the variables @code{MAKEINFOFLAGS}
3500 and @code{AM_MAKEINFOFLAGS} will be passed to the @code{makeinfo}
3501 invocation; the first of these is intended for use by the user
3502 (@pxref{User Variables}) and the second by the @file{Makefile.am}
3505 @vindex MAKEINFOFLAGS
3506 @vindex AM_MAKEINFOFLAGS
3508 Sometimes an info file actually depends on more than one @file{.texi}
3509 file. For instance, in GNU Hello, @file{hello.texi} includes the file
3510 @file{gpl.texi}. You can tell Automake about these dependencies using
3511 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
3516 info_TEXINFOS = hello.texi
3517 hello_TEXINFOS = gpl.texi
3522 By default, Automake requires the file @file{texinfo.tex} to appear in
3523 the same directory as the Texinfo source. However, if you used
3524 @code{AC_CONFIG_AUX_DIR} in @file{configure.in} (@pxref{Input, , Finding
3525 `configure' Input, autoconf, The Autoconf Manual}), then
3526 @file{texinfo.tex} is looked for there. Automake supplies
3527 @file{texinfo.tex} if @samp{--add-missing} is given.
3531 If your package has Texinfo files in many directories, you can use the
3532 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
3533 @file{texinfo.tex} for your package. The value of this variable should
3534 be the relative path from the current @file{Makefile.am} to
3538 TEXINFO_TEX = ../doc/texinfo.tex
3541 @opindex no-texinfo.tex
3543 The option @samp{no-texinfo.tex} can be used to eliminate the
3544 requirement for @file{texinfo.tex}. Use of the variable
3545 @code{TEXINFO_TEX} is preferable, however, because that allows the
3546 @code{dvi} target to still work.
3548 @cindex Target, install-info
3549 @cindex Target, noinstall-info
3550 @cindex install-info target
3551 @cindex noinstall-info target
3553 @opindex no-installinfo
3554 @trindex install-info
3556 Automake generates an @code{install-info} target; some people apparently
3557 use this. By default, info pages are installed by @samp{make install}.
3558 This can be prevented via the @code{no-installinfo} option.
3561 @node Man pages, , Texinfo, Documentation
3564 @cindex _MANS primary, defined
3565 @cindex MANS primary, defined
3566 @cindex Primary variable, MANS
3568 A package can also include man pages (but see the GNU standards on this
3569 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
3570 pages are declared using the @samp{MANS} primary. Generally the
3571 @code{man_MANS} macro is used. Man pages are automatically installed in
3572 the correct subdirectory of @code{mandir}, based on the file extension.
3576 File extensions such as @samp{.1c} are handled by looking for the valid
3577 part of the extension and using that to determine the correct
3578 subdirectory of @code{mandir}. Valid section names are the digits
3579 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
3581 Sometimes developers prefer to name a man page something like
3582 @file{foo.man} in the source, and then rename it to have the correct
3583 suffix, e.g. @file{foo.1}, when installing the file. Automake also
3584 supports this mode. For a valid section named @var{SECTION}, there is a
3585 corresponding directory named @samp{man@var{SECTION}dir}, and a
3586 corresponding @samp{_MANS} variable. Files listed in such a variable
3587 are installed in the indicated section. If the file already has a
3588 valid suffix, then it is installed as-is; otherwise the file suffix is
3589 changed to match the section.
3591 For instance, consider this example:
3593 man1_MANS = rename.man thesame.1 alsothesame.1c
3596 In this case, @file{rename.man} will be renamed to @file{rename.1} when
3597 installed, but the other files will keep their names.
3599 @cindex Target, install-man
3600 @cindex Target, noinstall-man
3601 @cindex install-man target
3602 @cindex noinstall-man target
3604 @c Use @samp{make install} per documentation: (texi)code.
3605 By default, man pages are installed by @samp{make install}. However,
3606 since the GNU project does not require man pages, many maintainers do
3607 not expend effort to keep the man pages up to date. In these cases, the
3608 @code{no-installman} option will prevent the man pages from being
3609 installed by default. The user can still explicitly install them via
3610 @samp{make install-man}.
3611 @opindex no-installman
3612 @trindex install-man
3614 Here is how the man pages are handled in GNU @code{cpio} (which includes
3615 both Texinfo documentation and man pages):
3618 man_MANS = cpio.1 mt.1
3619 EXTRA_DIST = $(man_MANS)
3622 Man pages are not currently considered to be source, because it is not
3623 uncommon for man pages to be automatically generated. Therefore they
3624 are not automatically included in the distribution. However, this can
3625 be changed by use of the @samp{dist_} prefix.
3627 The @samp{nobase_} prefix is meaningless for man pages and is
3631 @node Install, Clean, Documentation, Top
3632 @chapter What Gets Installed
3634 @cindex Installation support
3635 @cindex make install support
3637 @section Basics of installation
3639 Naturally, Automake handles the details of actually installing your
3640 program once it has been built. All files named by the various
3641 primaries are automatically installed in the appropriate places when the
3642 user runs @code{make install}.
3644 A file named in a primary is installed by copying the built file into
3645 the appropriate directory. The base name of the file is used when
3649 bin_PROGRAMS = hello subdir/goodbye
3652 In this example, both @samp{hello} and @samp{goodbye} will be installed
3653 in @code{$(bindir)}.
3655 Sometimes it is useful to avoid the basename step at install time. For
3656 instance, you might have a number of header files in subdirectories of
3657 the source tree which are laid out precisely how you want to install
3658 them. In this situation you can use the @samp{nobase_} prefix to
3659 suppress the base name step. For example:
3662 nobase_include_HEADERS = stdio.h sys/types.h
3665 Will install @file{stdio.h} in @code{$(includedir)} and @file{types.h}
3666 in @code{$(includedir)/sys}.
3668 @section The two parts of install
3670 Automake generates separate @code{install-data} and @code{install-exec}
3671 targets, in case the installer is installing on multiple machines which
3672 share directory structure---these targets allow the machine-independent
3673 parts to be installed only once. @code{install-exec} installs
3674 platform-dependent files, and @code{install-data} installs
3675 platform-independent files. The @code{install} target depends on both
3676 of these targets. While Automake tries to automatically segregate
3677 objects into the correct category, the @file{Makefile.am} author is, in
3678 the end, responsible for making sure this is done correctly.
3679 @trindex install-data
3680 @trindex install-exec
3682 @cindex Install, two parts of
3684 Variables using the standard directory prefixes @samp{data},
3685 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
3686 @samp{pkgdata}, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
3687 installed by @samp{install-data}.
3689 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
3690 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
3691 @samp{pkglib} (e.g. @samp{bin_PROGRAMS}) are installed by
3692 @samp{install-exec}.
3694 Any variable using a user-defined directory prefix with @samp{exec} in
3695 the name (e.g. @samp{myexecbin_PROGRAMS} is installed by
3696 @samp{install-exec}. All other user-defined prefixes are installed by
3697 @samp{install-data}.
3699 @section Extending installation
3701 It is possible to extend this mechanism by defining an
3702 @code{install-exec-local} or @code{install-data-local} target. If these
3703 targets exist, they will be run at @samp{make install} time. These
3704 rules can do almost anything; care is required.
3705 @trindex install-exec-local
3706 @trindex install-data-local
3708 Automake also supports two install hooks, @code{install-exec-hook} and
3709 @code{install-data-hook}. These hooks are run after all other install
3710 rules of the appropriate type, exec or data, have completed. So, for
3711 instance, it is possible to perform post-installation modifications
3712 using an install hook.
3713 @cindex Install hook
3715 @section Staged installs
3718 Automake generates support for the @samp{DESTDIR} variable in all
3719 install rules. @samp{DESTDIR} is used during the @samp{make install}
3720 step to relocate install objects into a staging area. Each object and
3721 path is prefixed with the value of @samp{DESTDIR} before being copied
3722 into the install area. Here is an example of typical DESTDIR usage:
3725 make DESTDIR=/tmp/staging install
3728 This places install objects in a directory tree built under
3729 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
3730 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
3731 would install @file{/tmp/staging/gnu/bin/foo} and
3732 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
3734 This feature is commonly used to build install images and packages. For
3735 more information, see @ref{Makefile Conventions, , , standards, The GNU
3738 Support for @samp{DESTDIR} is implemented by coding it directly into the
3739 install rules. If your @file{Makefile.am} uses a local install rule
3740 (e.g., @code{install-exec-local}) or an install hook, then you must
3741 write that code to respect @samp{DESTDIR}.
3743 @section Rules for the user
3745 Automake also generates an @code{uninstall} target, an
3746 @code{installdirs} target, and an @code{install-strip} target.
3748 @trindex installdirs
3749 @trindex install-strip
3751 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
3752 There is no notion of separate uninstalls for ``exec'' and ``data'', as
3753 these features would not provide additional functionality.
3755 Note that @code{uninstall} is not meant as a replacement for a real
3759 @node Clean, Dist, Install, Top
3760 @chapter What Gets Cleaned
3762 @cindex make clean support
3764 The GNU Makefile Standards specify a number of different clean rules.
3765 See @xref{Standard Targets, , Standard Targets for Users, standards,
3766 The GNU Coding Standards}.
3768 Generally the files that can be cleaned are determined automatically by
3769 Automake. Of course, Automake also recognizes some variables that can
3770 be defined to specify additional files to clean. These variables are
3771 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
3772 @code{MAINTAINERCLEANFILES}.
3773 @vindex MOSTLYCLEANFILES
3775 @vindex DISTCLEANFILES
3776 @vindex MAINTAINERCLEANFILES
3778 As the GNU Standards aren't always explicit as to which files should be
3779 removed by which target, we've adopted a heuristic which we believe was
3780 first formulated by Fran@,{c}ois Pinard:
3784 If @code{make} built it, and it is commonly something that one would
3785 want to rebuild (for instance, a @file{.o} file), then
3786 @code{mostlyclean} should delete it.
3789 Otherwise, if @code{make} built it, then @code{clean} should delete it.
3792 If @code{configure} built it, then @code{distclean} should delete it
3795 If the maintainer built it, then @code{maintainer-clean} should
3799 We recommend that you follow this same set of heuristics in your
3803 @node Dist, Tests, Clean, Top
3804 @chapter What Goes in a Distribution
3806 @section Basics of distribution
3810 The @code{dist} target in the generated @file{Makefile.in} can be used
3811 to generate a gzip'd @code{tar} file and other flavors of archive for
3812 distribution. The files is named based on the @samp{PACKAGE} and
3813 @samp{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
3814 (@pxref{Macros}); more precisely the gzip'd @code{tar} file is named
3815 @samp{@var{package}-@var{version}.tar.gz}.
3819 You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
3820 is run. The default setting is @samp{--best}.
3822 For the most part, the files to distribute are automatically found by
3823 Automake: all source files are automatically included in a distribution,
3824 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
3825 has a built-in list of commonly used files which are automatically
3826 included if they are found in the current directory (either physically,
3827 or as the target of a @file{Makefile.am} rule). This list is printed by
3828 @samp{automake --help}. Also, files which are read by @code{configure}
3829 (i.e. the source files corresponding to the files specified in various
3830 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
3831 automatically distributed.
3833 Still, sometimes there are files which must be distributed, but which
3834 are not covered in the automatic rules. These files should be listed in
3835 the @code{EXTRA_DIST} variable. You can mention files from
3836 subdirectories in @code{EXTRA_DIST}.
3838 You can also mention a directory in @code{EXTRA_DIST}; in this case the
3839 entire directory will be recursively copied into the distribution.
3840 Please note that this will also copy @emph{everything} in the directory,
3841 including CVS/RCS version control files. We recommend against using
3846 @section Fine-grained distribution control
3848 Sometimes you need tighter control over what does @emph{not} go into the
3849 distribution; for instance you might have source files which are
3850 generated and which you do not want to distribute. In this case
3851 Automake gives fine-grained control using the @samp{dist} and
3852 @samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
3853 prefixed with @samp{dist_} to add the listed files to the distribution.
3854 Similarly, @samp{nodist_} can be used to omit the files from the
3859 As an example, here is how you would cause some data to be distributed
3860 while leaving some source code out of the distribution:
3863 dist_data_DATA = distribute-this
3865 nodist_foo_SOURCES = do-not-distribute.c
3868 @section The dist hook
3870 Another way to to use this is for removing unnecessary files that get
3871 recursively included by specifying a directory in EXTRA_DIST:
3877 rm -rf `find $(distdir)/doc -name CVS`
3880 If you define @code{SUBDIRS}, Automake will recursively include the
3881 subdirectories in the distribution. If @code{SUBDIRS} is defined
3882 conditionally (@pxref{Conditionals}), Automake will normally include all
3883 directories that could possibly appear in @code{SUBDIRS} in the
3884 distribution. If you need to specify the set of directories
3885 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
3886 list of subdirectories to include in the distribution.
3887 @vindex DIST_SUBDIRS
3891 Occasionally it is useful to be able to change the distribution before
3892 it is packaged up. If the @code{dist-hook} target exists, it is run
3893 after the distribution directory is filled, but before the actual tar
3894 (or shar) file is created. One way to use this is for distributing
3895 files in subdirectories for which a new @file{Makefile.am} is overkill:
3899 mkdir $(distdir)/random
3900 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
3903 @section Checking the distribution
3905 @cindex make distcheck
3906 @cindex make distcleancheck
3907 @vindex distcleancheck_listfiles
3909 Automake also generates a @code{distcheck} target which can be of help
3910 to ensure that a given distribution will actually work.
3911 @code{distcheck} makes a distribution, then tries to do a @code{VPATH}
3912 build, run the testsuite, and finally make another tarfile to ensure the
3913 distribution is self-contained.
3916 Building the package involves running @code{./configure}. If you need
3917 to supply additional flags to @code{configure}, define them in the
3918 @code{DISTCHECK_CONFIGURE_FLAGS} variable, either in your top-level
3919 @file{Makefile.am}, or on the commande line when invoking @code{make}.
3920 @vindex DISTCHECK_CONFIGURE_FLAGS
3922 If the target @code{distcheck-hook} is defined in your
3923 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
3924 the new distribution has been unpacked, but before the unpacked copy is
3925 configured and built. Your @code{distcheck-hook} can do almost
3926 anything, though as always caution is advised. Generally this hook is
3927 used to check for potential distribution errors not caught by the
3930 Speaking about potential distribution errors, @code{distcheck} will also
3931 ensure that the @code{distclean} target actually removes all built
3932 files. This is done by running @code{make distcleancheck} at the end of
3933 the @code{VPATH} build. By default, @code{distcleancheck} will run
3934 @code{distclean} and then make sure the build tree has been emptied by
3935 running @code{$(distcleancheck_listfiles)}. Usually this check will
3936 find generated files that you forgot to add to the @code{DISTCLEANFILES}
3937 variable (@pxref{Clean}).
3938 @trindex distcleancheck
3940 The @code{distcleancheck} behaviour should be ok for most packages,
3941 otherwise you have the possibility to override the definitition of
3942 either the @code{distcleancheck} target, or the
3943 @code{$(distcleancheck_listfiles)} variable. For instance to disable
3944 @code{distcleancheck} completely, add the following rule to your
3945 top-level @file{Makefile.am}:
3946 @vindex distcleancheck_listfiles
3953 If you want @code{distcleancheck} to ignore built files which have not
3954 been cleaned because they are also part of the distribution, add the
3955 following definition instead:
3958 distcleancheck_listfiles = \
3959 find -type f -exec sh -c 'test -f $(scrdir)/@{@} || echo @{@}'
3962 The above definition is not the default because it's usually an error if
3963 your Makefiles cause some distributed files to be rebuilt when the user
3964 build the package. (Think about the user missing the tool required to
3965 build the file; or if the required tool is built by your package,
3966 consider the cross-compilation case where it can't be run.)
3968 @section The types of distributions
3971 Automake generates a @samp{.tar.gz} file when asked to create a
3972 distribution and other archives formats, @ref{Options}. The target
3973 @code{dist-gzip} generates the @samp{.tar.gz} file only.
3976 @node Tests, Options, Dist, Top
3977 @chapter Support for test suites
3982 Automake supports two forms of test suites.
3984 @section Simple Tests
3986 If the variable @code{TESTS} is defined, its value is taken to be a list
3987 of programs to run in order to do the testing. The programs can either
3988 be derived objects or source objects; the generated rule will look both
3989 in @code{srcdir} and @file{.}. Programs needing data files should look
3990 for them in @code{srcdir} (which is both an environment variable and a
3991 make variable) so they work when building in a separate directory
3992 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
3993 Manual}), and in particular for the @code{distcheck} target
3996 @cindex Exit status 77, special interpretation
3998 The number of failures will be printed at the end of the run. If a
3999 given test program exits with a status of 77, then its result is ignored
4000 in the final count. This feature allows non-portable tests to be
4001 ignored in environments where they don't make sense.
4003 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
4004 variables for the test run; the environment variable @code{srcdir} is
4005 set in the rule. If all your test programs are scripts, you can also
4006 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
4007 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
4009 @vindex TESTS_ENVIRONMENT
4011 @cindex Tests, expected failure
4012 @cindex Expected test failure
4014 You may define the variable @code{XFAIL_TESTS} to a list of tests
4015 (usually a subset of @code{TESTS}) that are expected to fail. This will
4016 reverse the result of those tests.
4019 Automake ensures that each program listed in @code{TESTS} is built
4020 before any tests are run; you can list both source and derived programs
4021 in @code{TESTS}. For instance, you might want to run a C program as a
4022 test. To do this you would list its name in @code{TESTS} and also in
4023 @code{check_PROGRAMS}, and then specify it as you would any other
4026 @section DejaGNU Tests
4028 If @uref{ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz,
4029 @samp{dejagnu}} appears in @code{AUTOMAKE_OPTIONS}, then a
4030 @code{dejagnu}-based test suite is assumed. The variable
4031 @code{DEJATOOL} is a list of names which are passed, one at a time, as
4032 the @code{--tool} argument to @code{runtest} invocations; it defaults to
4033 the name of the package.
4035 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
4036 @code{--srcdir} flags that are passed to dejagnu by default; this can be
4037 overridden if necessary.
4038 @vindex RUNTESTDEFAULTFLAGS
4040 The variables @code{EXPECT} and @code{RUNTEST} can
4041 also be overridden to provide project-specific values. For instance,
4042 you will need to do this if you are testing a compiler toolchain,
4043 because the default values do not take into account host and target
4050 The contents of the variable @code{RUNTESTFLAGS} are passed to the
4051 @code{runtest} invocation. This is considered a ``user variable''
4052 (@pxref{User Variables}). If you need to set @code{runtest} flags in
4053 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
4054 @vindex RUNTESTFLAGS
4055 @vindex AM_RUNTESTFLAGS
4056 @c FIXME xref dejagnu
4058 In either case, the testing is done via @samp{make check}.
4060 @section Install Tests
4062 The @code{installcheck} target is available to the user as a way to run
4063 any tests after the package has been installed. You can add tests to
4064 this by writing an @code{installcheck-local} target.
4067 @node Options, Miscellaneous, Tests, Top
4068 @chapter Changing Automake's Behavior
4070 Various features of Automake can be controlled by options in the
4071 @file{Makefile.am}. Such options are applied on a per-@file{Makefile}
4072 basis when listed in a special @file{Makefile} variable named
4073 @code{AUTOMAKE_OPTIONS}. They are applied globally to all processed
4074 @file{Makefiles} when listed in the first argument of
4075 @code{AM_INIT_AUTOMAKE} in @file{configure.in}. Currently understood
4077 @vindex AUTOMAKE_OPTIONS
4082 @itemx @code{foreign}
4083 @itemx @code{cygnus}
4084 @cindex Option, gnits
4086 @cindex Option, foreign
4087 @cindex Option, cygnus
4089 Set the strictness as appropriate. The @code{gnits} option also implies
4090 @code{readme-alpha} and @code{check-news}.
4092 @item @code{ansi2knr}
4093 @itemx @code{@var{path}/ansi2knr}
4094 @cindex Option, ansi2knr
4095 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
4096 path, the generated @file{Makefile.in} will look in the specified
4097 directory to find the @file{ansi2knr} program. The path should be a
4098 relative path to another directory in the same distribution (Automake
4099 currently does not check this).
4101 @item @code{check-news}
4102 @cindex Option, check-news
4103 Cause @code{make dist} to fail unless the current version number appears
4104 in the first few lines of the @file{NEWS} file.
4106 @item @code{dejagnu}
4107 @cindex Option, dejagnu
4108 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
4110 @item @code{dist-bzip2}
4111 @cindex Option, dist-bzip2
4112 Generate a @code{dist-bzip2} target, creating a bzip2 tar archive of the
4113 distribution. @code{dist} will create it in addition to the other
4114 formats. bzip2 archives are frequently smaller than gzipped archives.
4117 @item @code{dist-shar}
4118 @cindex Option, dist-shar
4119 Generate a @code{dist-shar} target, creating a shar archive of the
4120 distribution. @code{dist} will create it in addition to the other
4124 @item @code{dist-zip}
4125 @cindex Option, dist-zip
4126 Generate a @code{dist-zip} target, creating a zip archive of the
4127 distribution. @code{dist} will create it in addition to the other
4131 @item @code{dist-tarZ}
4132 @cindex Option, dist-tarZ
4133 Generate a @code{dist-tarZ} target, creating a compressed tar archive of
4134 the distribution. @code{dist} will create it in addition to the other
4138 @item @code{no-define}
4139 @cindex Option, no-define
4140 This options is meaningful only when passed as an argument to
4141 AM_INIT_AUTOMAKE. It will prevent the @code{PACKAGE} and @code{VERSION}
4142 variable to be @code{AC_DEFINE}d.
4144 @item @code{no-dependencies}
4145 @cindex Option, no-dependencies
4146 This is similar to using @samp{--include-deps} on the command line, but
4147 is useful for those situations where you don't have the necessary bits
4148 to make automatic dependency tracking work @xref{Dependencies}. In this
4149 case the effect is to effectively disable automatic dependency tracking.
4151 @item @code{no-exeext}
4152 @cindex Option, no-exeext
4153 If your @file{Makefile.am} defines a target @samp{foo}, it will override
4154 a target named @samp{foo$(EXEEXT)}. This is necessary when
4155 @code{EXEEXT} is found to be empty. However, by default automake will
4156 generate an error for this use. The @code{no-exeext} option will
4157 disable this error. This is intended for use only where it is known in
4158 advance that the package will not be ported to Windows, or any other
4159 operating system using extensions on executables.
4161 @item @code{no-installinfo}
4162 @cindex Option, no-installinfo
4163 The generated @file{Makefile.in} will not cause info pages to be built
4164 or installed by default. However, @code{info} and @code{install-info}
4165 targets will still be available. This option is disallowed at
4166 @samp{GNU} strictness and above.
4168 @trindex install-info
4170 @item @code{no-installman}
4171 @cindex Option, no-installman
4172 The generated @file{Makefile.in} will not cause man pages to be
4173 installed by default. However, an @code{install-man} target will still
4174 be available for optional installation. This option is disallowed at
4175 @samp{GNU} strictness and above.
4176 @trindex install-man
4178 @item @code{nostdinc}
4179 @cindex Option, nostdinc
4180 This option can be used to disable the standard @samp{-I} options which
4181 are ordinarily automatically provided by Automake.
4183 @item @code{no-texinfo.tex}
4184 @cindex Option, no-texinfo
4185 Don't require @file{texinfo.tex}, even if there are texinfo files in
4188 @item @code{readme-alpha}
4189 @cindex Option, readme-alpha
4190 If this release is an alpha release, and the file @file{README-alpha}
4191 exists, then it will be added to the distribution. If this option is
4192 given, version numbers are expected to follow one of two forms. The
4193 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
4194 element is a number; the final period and number should be left off for
4195 non-alpha releases. The second form is
4196 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
4197 letter; it should be omitted for non-alpha releases.
4199 @item @code{subdir-objects}
4200 If this option is specified, then objects are placed into the
4201 subdirectory of the build directory corresponding to the subdirectory of
4202 the source file. For instance if the source file is
4203 @file{subdir/file.cxx}, then the output file would be
4204 @file{subdir/file.o}.
4207 @cindex Option, version
4208 A version number (e.g. @samp{0.30}) can be specified. If Automake is not
4209 newer than the version specified, creation of the @file{Makefile.in}
4213 Unrecognized options are diagnosed by @code{automake}.
4215 If you want an option to apply to all the files in the tree, you can use
4216 the @code{AM_AUTOMAKE_OPTIONS} macro in @file{configure.in}.
4220 @node Miscellaneous, Include, Options, Top
4221 @chapter Miscellaneous Rules
4223 There are a few rules and variables that didn't fit anywhere else.
4226 * Tags:: Interfacing to etags and mkid
4227 * Suffixes:: Handling new file extensions
4228 * Multilibs:: Support for multilibbing.
4232 @node Tags, Suffixes, Miscellaneous, Miscellaneous
4233 @section Interfacing to @code{etags}
4235 @cindex TAGS support
4237 Automake will generate rules to generate @file{TAGS} files for use with
4238 GNU Emacs under some circumstances.
4240 If any C, C++ or Fortran 77 source code or headers are present, then
4241 @code{tags} and @code{TAGS} targets will be generated for the directory.
4244 At the topmost directory of a multi-directory package, a @code{tags}
4245 target file will be generated which, when run, will generate a
4246 @file{TAGS} file that includes by reference all @file{TAGS} files from
4249 The @code{tags} target will also be generated if the variable
4250 @code{ETAGS_ARGS} is defined. This variable is intended for use in
4251 directories which contain taggable source that @code{etags} does not
4252 understand. The user can use the @code{ETAGSFLAGS} to pass additional
4253 flags to @code{etags}; @code{AM_ETAGSFLAGS} is also available for use in
4257 @vindex AM_ETAGSFLAGS
4259 Here is how Automake generates tags for its source, and for nodes in its
4263 ETAGS_ARGS = automake.in --lang=none \
4264 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
4267 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
4268 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
4269 are added directly to the dependencies for the @code{tags} target.
4270 @vindex TAGS_DEPENDENCIES
4272 Automake will also generate an @code{ID} target which will run
4273 @code{mkid} on the source. This is only supported on a
4274 directory-by-directory basis.
4277 Automake also supports the @uref{http://www.gnu.org/software/global/,
4278 GNU Global Tags program}. The @code{GTAGS} target runs Global Tags
4279 automatically and puts the result in the top build directory. The
4280 variable @code{GTAGS_ARGS} holds arguments which are passed to
4285 @node Suffixes, Multilibs, Tags, Miscellaneous
4286 @section Handling new file extensions
4288 @cindex Adding new SUFFIXES
4289 @cindex SUFFIXES, adding
4292 It is sometimes useful to introduce a new implicit rule to handle a file
4293 type that Automake does not know about.
4295 For instance, suppose you had a compiler which could compile @samp{.foo}
4296 files to @samp{.o} files. You would simply define an suffix rule for
4304 Then you could directly use a @samp{.foo} file in a @samp{_SOURCES}
4305 variable and expect the correct results:
4309 doit_SOURCES = doit.foo
4312 This was the simpler and more common case. In other cases, you will
4313 have to help Automake to figure which extensions you are defining your
4314 suffix rule for. This usually happens when your extensions does not
4315 start with a dot. Then, all you have to do is to put a list of new
4316 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
4319 For instance the following definition prevents Automake to misinterpret
4320 @samp{.idlC.cpp:} as an attemp to transform @samp{.idlC} into
4324 SUFFIXES = .idl C.cpp
4329 As you may have noted, the @code{SUFFIXES} macro behaves like the
4330 @code{.SUFFIXES} special target of @code{make}. You should not touch
4331 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
4332 Automake generate the suffix list for @code{.SUFFIXES}. Any given
4333 @code{SUFFIXES} go at the start of the generated suffixes list, followed
4334 by Automake generated suffixes not already in the list.
4336 @node Multilibs, , Suffixes, Miscellaneous
4337 @section Support for Multilibs
4339 Automake has support for an obscure feature called multilibs. A
4340 @dfn{multilib} is a library which is built for multiple different ABIs
4341 at a single time; each time the library is built with a different target
4342 flag combination. This is only useful when the library is intended to
4343 be cross-compiled, and it is almost exclusively used for compiler
4346 The multilib support is still experimental. Only use it if you are
4347 familiar with multilibs and can debug problems you might encounter.
4350 @node Include, Conditionals, Miscellaneous, Top
4354 @cindex Including Makefile fragment
4355 @cindex Makefile fragment, including
4357 Automake supports an @code{include} directive which can be used to
4358 include other @file{Makefile} fragments when @code{automake} is run.
4359 Note that these fragments are read and interpreted by @code{automake},
4360 not by @code{make}. As with conditionals, @code{make} has no idea that
4361 @code{include} is in use.
4363 There are two forms of @code{include}:
4366 @item include $(srcdir)/file
4367 Include a fragment which is found relative to the current source
4370 @item include $(top_srcdir)/file
4371 Include a fragment which is found relative to the top source directory.
4374 Note that if a fragment is included inside a conditional, then the
4375 condition applies to the entire contents of that fragment.
4378 @node Conditionals, Gnits, Include, Top
4379 @chapter Conditionals
4381 @cindex Conditionals
4383 Automake supports a simple type of conditionals.
4385 @cvindex AM_CONDITIONAL
4386 Before using a conditional, you must define it by using
4387 @code{AM_CONDITIONAL} in the @code{configure.in} file (@pxref{Macros}).
4389 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
4390 The conditional name, @var{conditional}, should be a simple string
4391 starting with a letter and containing only letters, digits, and
4392 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
4393 which are reserved by Automake.
4395 The shell @var{condition} (suitable for use in a shell @code{if}
4396 statement) is evaluated when @code{configure} is run. Note that you
4397 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
4398 time @code{configure} is run -- if @code{AM_CONDITIONAL} is run
4399 conditionally (e.g., in a shell @code{if} statement), then the result
4400 will confuse automake.
4403 @cindex --enable-debug, example
4404 @cindex Example conditional --enable-debug
4405 @cindex Conditional example, --enable-debug
4407 Conditionals typically depend upon options which the user provides to
4408 the @code{configure} script. Here is an example of how to write a
4409 conditional which is true if the user uses the @samp{--enable-debug}
4413 AC_ARG_ENABLE(debug,
4414 [ --enable-debug Turn on debugging],
4415 [case "$@{enableval@}" in
4418 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
4419 esac],[debug=false])
4420 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
4423 Here is an example of how to use that conditional in @file{Makefile.am}:
4435 noinst_PROGRAMS = $(DBG)
4438 This trivial example could also be handled using EXTRA_PROGRAMS
4439 (@pxref{Conditional Programs}).
4441 You may only test a single variable in an @code{if} statement, possibly
4442 negated using @samp{!}. The @code{else} statement may be omitted.
4443 Conditionals may be nested to any depth. You may specify an argument to
4444 @code{else} in which case it must be the negation of the condition used
4445 for the current @code{if}. Similarly you may specify the condition
4446 which is closed by an @code{end}:
4457 Unbalanced conditions are errors.
4459 Note that conditionals in Automake are not the same as conditionals in
4460 GNU Make. Automake conditionals are checked at configure time by the
4461 @file{configure} script, and affect the translation from
4462 @file{Makefile.in} to @file{Makefile}. They are based on options passed
4463 to @file{configure} and on results that @file{configure} has discovered
4464 about the host system. GNU Make conditionals are checked at @code{make}
4465 time, and are based on variables passed to the make program or defined
4466 in the @file{Makefile}.
4468 Automake conditionals will work with any make program.
4471 @node Gnits, Cygnus, Conditionals, Top
4472 @chapter The effect of @code{--gnu} and @code{--gnits}
4474 @cindex --gnu, required files
4475 @cindex --gnu, complete description
4477 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
4478 variable) causes @code{automake} to check the following:
4482 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
4483 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
4484 directory of the package.
4487 The options @samp{no-installman} and @samp{no-installinfo} are
4491 Note that this option will be extended in the future to do even more
4492 checking; it is advisable to be familiar with the precise requirements
4493 of the GNU standards. Also, @samp{--gnu} can require certain
4494 non-standard GNU programs to exist for use by various maintainer-only
4495 targets; for instance in the future @code{pathchk} might be required for
4498 @cindex --gnits, complete description
4500 The @samp{--gnits} option does everything that @samp{--gnu} does, and
4501 checks the following as well:
4505 @samp{make dist} will check to make sure the @file{NEWS} file has been
4506 updated to the current version.
4509 @samp{VERSION} is checked to make sure its format complies with Gnits
4511 @c FIXME xref when standards are finished
4514 @cindex README-alpha
4515 If @samp{VERSION} indicates that this is an alpha release, and the file
4516 @file{README-alpha} appears in the topmost directory of a package, then
4517 it is included in the distribution. This is done in @samp{--gnits}
4518 mode, and no other, because this mode is the only one where version
4519 number formats are constrained, and hence the only mode where Automake
4520 can automatically determine whether @file{README-alpha} should be
4524 The file @file{THANKS} is required.
4528 @node Cygnus, Extending, Gnits, Top
4529 @chapter The effect of @code{--cygnus}
4531 @cindex Cygnus strictness
4533 Some packages, notably GNU GCC and GNU gdb, have a build environment
4534 originally written at Cygnus Support (subsequently renamed Cygnus
4535 Solutions, and then later purchased by Red Hat). Packages with this
4536 ancestry are sometimes referred to as ``Cygnus'' trees.
4538 A Cygnus tree has slightly different rules for how a @file{Makefile.in}
4539 is to be constructed. Passing @samp{--cygnus} to @code{automake} will
4540 cause any generated @file{Makefile.in} to comply with Cygnus rules.
4542 Here are the precise effects of @samp{--cygnus}:
4546 Info files are always created in the build directory, and not in the
4550 @file{texinfo.tex} is not required if a Texinfo source file is
4551 specified. The assumption is that the file will be supplied, but in a
4552 place that Automake cannot find. This assumption is an artifact of how
4553 Cygnus packages are typically bundled.
4556 @samp{make dist} is not supported, and the rules for it are not
4557 generated. Cygnus-style trees use their own distribution mechanism.
4560 Certain tools will be searched for in the build tree as well as in the
4561 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
4562 @code{makeinfo} and @code{texi2dvi}.
4565 @code{--foreign} is implied.
4568 The options @samp{no-installinfo} and @samp{no-dependencies} are
4572 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
4576 The @code{check} target doesn't depend on @code{all}.
4579 GNU maintainers are advised to use @samp{gnu} strictness in preference
4580 to the special Cygnus mode. Some day, perhaps, the differences between
4581 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
4582 more standards compliant). At that time the special Cygnus mode will be
4586 @node Extending, Distributing, Cygnus, Top
4587 @chapter When Automake Isn't Enough
4589 Automake's implicit copying semantics means that many problems can be
4590 worked around by simply adding some @code{make} targets and rules to
4591 @file{Makefile.in}. Automake will ignore these additions.
4593 @cindex -local targets
4594 @cindex local targets
4596 There are some caveats to doing this. Although you can overload a
4597 target already used by Automake, it is often inadvisable, particularly
4598 in the topmost directory of a package with subdirectories. However,
4599 various useful targets have a @samp{-local} version you can specify in
4600 your @file{Makefile.in}. Automake will supplement the standard target
4601 with these user-supplied targets.
4606 @trindex check-local
4607 @trindex install-data-local
4608 @trindex install-exec-local
4609 @trindex uninstall-local
4610 @trindex mostlyclean-local
4611 @trindex clean-local
4612 @trindex distclean-local
4613 @trindex installdirs-local
4614 @trindex installcheck-local
4616 The targets that support a local version are @code{all}, @code{info},
4617 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
4618 @code{uninstall}, @code{installdirs}, @code{installcheck} and the
4619 various @code{clean} targets (@code{mostlyclean}, @code{clean},
4620 @code{distclean}, and @code{maintainer-clean}). Note that there are no
4621 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
4622 use @code{uninstall-local}. It doesn't make sense to uninstall just
4623 data or just executables.
4628 @trindex install-data
4629 @trindex install-exec
4632 For instance, here is one way to install a file in @file{/etc}:
4636 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
4639 @cindex -hook targets
4640 @cindex hook targets
4642 Some targets also have a way to run another target, called a @dfn{hook},
4643 after their work is done. The hook is named after the principal target,
4644 with @samp{-hook} appended. The targets allowing hooks are
4645 @code{install-data}, @code{install-exec}, @code{uninstall}, @code{dist},
4646 and @code{distcheck}.
4647 @trindex install-data-hook
4648 @trindex install-exec-hook
4649 @trindex uninstall-hook
4652 For instance, here is how to create a hard link to an installed program:
4656 ln $(DESTDIR)$(bindir)/program $(DESTDIR)$(bindir)/proglink
4659 @c FIXME should include discussion of variables you can use in these
4662 @node Distributing, API versioning, Extending, Top
4663 @chapter Distributing @file{Makefile.in}s
4665 Automake places no restrictions on the distribution of the resulting
4666 @file{Makefile.in}s. We still encourage software authors to distribute
4667 their work under terms like those of the GPL, but doing so is not
4668 required to use Automake.
4670 Some of the files that can be automatically installed via the
4671 @code{--add-missing} switch do fall under the GPL. However, these also
4672 have a special exception allowing you to distribute them with your
4673 package, regardless of the licensing you choose.
4676 @node API versioning, Macro and Variable Index, Distributing, Top
4677 @chapter Automake API versioning
4679 New Automake releases usually include bug fixes and new features.
4680 Unfortunately they may also introduce new bugs and incompatibilities.
4681 This make four reasons why a package may require a particular Automake
4684 Things get worse when maintaining a large tree of packages, each one
4685 requiring a different version of Automake. In the past, this meant that
4686 any developer (and sometime users) had to install several versions of
4687 Automake in different places, and switch @samp{$PATH} appropriately for
4690 Starting with version 1.6, Automake installs versioned binaries. This
4691 means you can install several versions of Automake in the same
4692 @samp{$prefix}, and can select an arbitrary Automake version by running
4693 @samp{automake-1.6} or @samp{automake-1.7} without juggling with
4694 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
4695 will use @samp{automake-1.6} explicitely in their rebuild rules.
4697 Note that @samp{1.6} in @samp{automake-1.6} is Automake's API version,
4698 not Automake's version. If a bug fix release is made, for instance
4699 Automake 1.6.1, the API version will remain 1.6. This means that a
4700 package which work with Automake 1.6 should also work with 1.6.1; after
4701 all, this is what people expect from bug fix releases.
4703 Note that if your package relies on a feature or a bug fix introduced in
4704 a release, you can pass this version as an option to Automake to ensure
4705 older releases will not be used. For instance, use this in your
4706 @file{configure.in}:
4709 AM_INIT_AUTOMAKE(1.6.1) dnl Require Automake 1.6.1 or better.
4712 or, in a particular @file{Makefile.am}:
4715 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
4718 Automake will print an error message if its version is
4719 older than the requested version.
4722 @heading What is in the API
4724 Automake's programing interface is not easy to define. Basically it
4725 should include at least all @strong{documented} variables and targets
4726 that a @samp{Makefile.am} authors can use, the behaviours associated to
4727 them (e.g. the places where @samp{-hook}'s are run), the command line
4728 interface of @samp{automake} and @samp{aclocal}, ...
4730 @heading What is not in the API
4732 Every undocumented variable, target, or command line option, is not part
4733 of the API. You should avoid using them, as they could change from one
4734 version to the other (even in bug fix releases, if this helps to fix a
4737 If it turns out you need to use such a undocumented feature, contact
4738 @email{automake@@gnu.org} and try to get it documented and exercised by
4742 @node Macro and Variable Index, General Index, API versioning, Top
4743 @unnumbered Macro and Variable Index
4749 @node General Index, , Macro and Variable Index, Top
4750 @unnumbered General Index