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 Free Software Foundation, Inc.
25 Permission is granted to make and distribute verbatim copies of
26 this manual provided the copyright notice and this permission notice
27 are preserved on all copies.
30 Permission is granted to process this file through TeX and print the
31 results, provided the printed document carries copying permission
32 notice identical to this one except for the removal of this paragraph
36 Permission is granted to copy and distribute modified versions of this
37 manual under the conditions for verbatim copying, provided that the entire
38 resulting derived work is distributed under the terms of a permission
39 notice identical to this one.
41 Permission is granted to copy and distribute translations of this manual
42 into another language, under the above conditions for modified versions,
43 except that this permission notice may be stated in a translation approved
50 @subtitle For version @value{VERSION}, @value{UPDATED}
51 @author David MacKenzie and Tom Tromey
54 @vskip 0pt plus 1filll
55 Copyright @copyright{} 1995, 1996, 2000, 2001 Free Software Foundation, Inc.
57 This is the first edition of the GNU Automake documentation,@*
58 and is consistent with GNU Automake @value{VERSION}.@*
60 Published by the Free Software Foundation @*
61 59 Temple Place - Suite 330, @*
62 Boston, MA 02111-1307 USA @*
64 Permission is granted to make and distribute verbatim copies of
65 this manual provided the copyright notice and this permission notice
66 are preserved on all copies.
68 Permission is granted to copy and distribute modified versions of this
69 manual under the conditions for verbatim copying, provided that the entire
70 resulting derived work is distributed under the terms of a permission
71 notice identical to this one.
73 Permission is granted to copy and distribute translations of this manual
74 into another language, under the above conditions for modified versions,
75 except that this permission notice may be stated in a translation
76 approved by the Free Software Foundation.
79 @c Define an index of configure output variables.
81 @c Define an index of configure variables.
83 @c Define an index of options.
85 @c Define an index of targets.
87 @c Define an index of commands.
90 @c Put the macros and variables into their own index.
91 @c @syncodeindex fn cp
96 @c Put everything else into one index (arbitrarily chosen to be the concept index).
102 @node Top, Introduction, (dir), (dir)
103 @comment node-name, next, previous, up
106 This file documents the GNU Automake package. Automake is a program
107 which creates GNU standards-compliant Makefiles from template files.
108 This edition documents version @value{VERSION}.
111 * Introduction:: Automake's purpose
112 * Generalities:: General ideas
113 * Examples:: Some example packages
114 * Invoking Automake:: Creating a Makefile.in
115 * configure:: Scanning configure.ac or configure.in
116 * Top level:: The top-level Makefile.am
117 * Alternative:: An alternative approach to subdirectories
118 * Rebuilding:: Automatic rebuilding of Makefile
119 * Programs:: Building programs and libraries
120 * Other objects:: Other derived objects
121 * Other GNU Tools:: Other GNU Tools
122 * Documentation:: Building documentation
123 * Install:: What gets installed
124 * Clean:: What gets cleaned
125 * Dist:: What goes in a distribution
126 * Tests:: Support for test suites
127 * Options:: Changing Automake's behavior
128 * Miscellaneous:: Miscellaneous rules
129 * Include:: Including extra files in an Automake template.
130 * Conditionals:: Conditionals
131 * Gnits:: The effect of @code{--gnu} and @code{--gnits}
132 * Cygnus:: The effect of @code{--cygnus}
133 * Extending:: Extending Automake
134 * Distributing:: Distributing the Makefile.in
135 * Macro and Variable Index::
142 @node Introduction, Generalities, Top, Top
143 @chapter Introduction
145 Automake is a tool for automatically generating @file{Makefile.in}s from
146 files called @file{Makefile.am}. Each @file{Makefile.am} is basically a
147 series of @code{make} macro definitions (with rules being thrown in
148 occasionally). The generated @file{Makefile.in}s are compliant with the
149 GNU Makefile standards.
151 @cindex GNU Makefile standards
153 The GNU Makefile Standards Document
154 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
155 is long, complicated, and subject to change. The goal of Automake is to
156 remove the burden of Makefile maintenance from the back of the
157 individual GNU maintainer (and put it on the back of the Automake
160 The typical Automake input file is simply a series of macro definitions.
161 Each such file is processed to create a @file{Makefile.in}. There
162 should generally be one @file{Makefile.am} per directory of a project.
164 @cindex Constraints of Automake
165 @cindex Automake constraints
167 Automake does constrain a project in certain ways; for instance it
168 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
169 autoconf, The Autoconf Manual}), and enforces certain restrictions on
170 the @file{configure.in} contents@footnote{Autoconf 2.50 promotes
171 @file{configure.ac} over @file{configure.in}. The rest of this
172 documentation will refer to @file{configure.in} as this use is not yet
173 spread, but Automake supports @file{configure.ac} too.}.
175 @cindex Automake requirements
176 @cindex Requirements, Automake
178 Automake requires @code{perl} in order to generate the
179 @file{Makefile.in}s. However, the distributions created by Automake are
180 fully GNU standards-compliant, and do not require @code{perl} in order
183 @cindex BUGS, reporting
184 @cindex Reporting BUGS
185 @cindex E-mail, bug reports
187 Mail suggestions and bug reports for Automake to
188 @email{bug-automake@@gnu.org}.
191 @node Generalities, Examples, Introduction, Top
192 @chapter General ideas
194 The following sections cover a few basic ideas that will help you
195 understand how Automake works.
198 * General Operation:: General operation of Automake
199 * Strictness:: Standards conformance checking
200 * Uniform:: The Uniform Naming Scheme
201 * Canonicalization:: How derived variables are named
202 * User Variables:: Variables reserved for the user
203 * Auxiliary Programs:: Programs automake might require
207 @node General Operation, Strictness, Generalities, Generalities
208 @section General Operation
210 Automake works by reading a @file{Makefile.am} and generating a
211 @file{Makefile.in}. Certain macros and targets defined in the
212 @file{Makefile.am} instruct Automake to generate more specialized code;
213 for instance, a @samp{bin_PROGRAMS} macro definition will cause targets
214 for compiling and linking programs to be generated.
216 @cindex Non-standard targets
217 @cindex cvs-dist, non-standard example
220 The macro definitions and targets in the @file{Makefile.am} are copied
221 verbatim into the generated file. This allows you to add arbitrary code
222 into the generated @file{Makefile.in}. For instance the Automake
223 distribution includes a non-standard @code{cvs-dist} target, which the
224 Automake maintainer uses to make distributions from his source control
227 @cindex GNU make extensions
229 Note that GNU make extensions are not recognized by Automake. Using
230 such extensions in a @file{Makefile.am} will lead to errors or confusing
233 Automake tries to group comments with adjoining targets and macro
234 definitions in an intelligent way.
236 @cindex Make targets, overriding
237 @cindex Overriding make targets
239 A target defined in @file{Makefile.am} generally overrides any such
240 target of a similar name that would be automatically generated by
241 @code{automake}. Although this is a supported feature, it is generally
242 best to avoid making use of it, as sometimes the generated rules are
245 @cindex Macros, overriding
246 @cindex Overriding make macros
248 Similarly, a macro defined in @file{Makefile.am} will override any
249 definition of the macro that @code{automake} would ordinarily create.
250 This feature is more often useful than the ability to override a target
251 definition. Be warned that many of the macros generated by
252 @code{automake} are considered to be for internal use only, and their
253 names might change in future releases.
255 @cindex Recursive operation of Automake
256 @cindex Automake, recursive operation
257 @cindex Example of recursive operation
259 When examining a macro definition, Automake will recursively examine
260 macros referenced in the definition. For example, if Automake is
261 looking at the content of @code{foo_SOURCES} in this snippet
265 foo_SOURCES = c.c $(xs)
268 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
269 contents of @code{foo_SOURCES}.
271 @cindex ## (special Automake comment)
272 @cindex Special Automake comment
273 @cindex Comment, special to Automake
275 Automake also allows a form of comment which is @emph{not} copied into
276 the output; all lines beginning with @samp{##} (leading spaces allowed)
277 are completely ignored by Automake.
279 It is customary to make the first line of @file{Makefile.am} read:
281 @cindex Makefile.am, first line
282 @cindex First line of Makefile.am
285 ## Process this file with automake to produce Makefile.in
288 @c FIXME discuss putting a copyright into Makefile.am here? I would but
289 @c I don't know quite what to say.
291 @c FIXME document customary ordering of Makefile.am here!
294 @node Strictness, Uniform, General Operation, Generalities
297 @cindex Non-GNU packages
299 While Automake is intended to be used by maintainers of GNU packages, it
300 does make some effort to accommodate those who wish to use it, but do
301 not want to use all the GNU conventions.
303 @cindex Strictness, defined
304 @cindex Strictness, foreign
305 @cindex foreign strictness
306 @cindex Strictness, gnu
307 @cindex gnits strictness
308 @cindex Strictness, gnits
309 @cindex gnits strictness
311 To this end, Automake supports three levels of @dfn{strictness}---the
312 strictness indicating how stringently Automake should check standards
315 The valid strictness levels are:
319 Automake will check for only those things which are absolutely
320 required for proper operations. For instance, whereas GNU standards
321 dictate the existence of a @file{NEWS} file, it will not be required in
322 this mode. The name comes from the fact that Automake is intended to be
323 used for GNU programs; these relaxed rules are not the standard mode of
327 Automake will check---as much as possible---for compliance to the GNU
328 standards for packages. This is the default.
331 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
332 standards}. These are based on the GNU standards, but are even more
333 detailed. Unless you are a Gnits standards contributor, it is
334 recommended that you avoid this option until such time as the Gnits
335 standard is actually published (which may never happen).
338 For more information on the precise implications of the strictness
339 level, see @ref{Gnits}.
341 Automake also has a special ``cygnus'' mode which is similar to
342 strictness but handled differently. This mode is useful for packages
343 which are put into a ``Cygnus'' style tree (e.g., the GCC tree). For
344 more information on this mode, see @ref{Cygnus}.
347 @node Uniform, Canonicalization, Strictness, Generalities
348 @section The Uniform Naming Scheme
350 @cindex Uniform naming scheme
352 Automake macros (from here on referred to as @emph{variables}) generally
353 follow a @dfn{uniform naming scheme} that makes it easy to decide how
354 programs (and other derived objects) are built, and how they are
355 installed. This scheme also supports @code{configure} time
356 determination of what should be built.
358 @cindex _PROGRAMS primary variable
359 @cindex PROGRAMS primary variable
360 @cindex Primary variable, PROGRAMS
362 @cindex Primary variable, defined
364 At @code{make} time, certain variables are used to determine which
365 objects are to be built. The variable names are made of several pieces
366 which are concatenated together.
368 The piece which tells automake what is being built is commonly called
369 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
370 list of programs which are to be compiled and linked.
373 @cindex pkglibdir, defined
374 @cindex pkgincludedir, defined
375 @cindex pkgdatadir, defined
378 @vindex pkgincludedir
381 A different set of names is used to decide where the built objects
382 should be installed. These names are prefixes to the primary which
383 indicate which standard directory should be used as the installation
384 directory. The standard directory names are given in the GNU standards
385 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
386 Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
387 and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
388 versions, but with @samp{@@PACKAGE@@} appended. For instance,
389 @code{pkglibdir} is defined as @code{$(libdir)/@@PACKAGE@@}.
392 @cindex EXTRA_, prepending
394 For each primary, there is one additional variable named by prepending
395 @samp{EXTRA_} to the primary name. This variable is used to list
396 objects which may or may not be built, depending on what
397 @code{configure} decides. This variable is required because Automake
398 must statically know the entire list of objects that may be built in
399 order to generate a @file{Makefile.in} that will work in all cases.
401 @cindex EXTRA_PROGRAMS, defined
402 @cindex Example, EXTRA_PROGRAMS
405 For instance, @code{cpio} decides at configure time which programs are
406 built. Some of the programs are installed in @code{bindir}, and some
407 are installed in @code{sbindir}:
410 EXTRA_PROGRAMS = mt rmt
411 bin_PROGRAMS = cpio pax
412 sbin_PROGRAMS = @@MORE_PROGRAMS@@
415 Defining a primary without a prefix as a variable, e.g.,
416 @code{PROGRAMS}, is an error.
418 Note that the common @samp{dir} suffix is left off when constructing the
419 variable names; thus one writes @samp{bin_PROGRAMS} and not
420 @samp{bindir_PROGRAMS}.
422 Not every sort of object can be installed in every directory. Automake
423 will flag those attempts it finds in error. Automake will also diagnose
424 obvious misspellings in directory names.
426 @cindex Extending list of installation directories
427 @cindex Installation directories, extending list
429 Sometimes the standard directories---even as augmented by Automake---
430 are not enough. In particular it is sometimes useful, for clarity, to
431 install objects in a subdirectory of some predefined directory. To this
432 end, Automake allows you to extend the list of possible installation
433 directories. A given prefix (e.g. @samp{zar}) is valid if a variable of
434 the same name with @samp{dir} appended is defined (e.g. @code{zardir}).
436 @cindex HTML support, example
438 For instance, until HTML support is part of Automake, you could use this
439 to install raw HTML documentation:
442 htmldir = $(prefix)/html
443 html_DATA = automake.html
446 @cindex noinst primary prefix, definition
448 The special prefix @samp{noinst} indicates that the objects in question
449 should not be installed at all.
451 @cindex check primary prefix, definition
453 The special prefix @samp{check} indicates that the objects in question
454 should not be built until the @code{make check} command is run.
456 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
457 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
458 @samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
470 Some primaries also allow additional prefixes which control other
471 aspects of @code{automake}'s behavior. The currently defined prefixes
472 are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes
476 @node Canonicalization, User Variables, Uniform, Generalities
477 @section How derived variables are named
479 @cindex canonicalizing Automake macros
481 Sometimes a Makefile variable name is derived from some text the
482 maintainer supplies. For instance, a program name listed in
483 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
484 variable. In cases like this, Automake canonicalizes the text, so that
485 program names and the like do not have to follow Makefile macro naming
486 rules. All characters in the name except for letters, numbers, the
487 strudel (@@), and the underscore are turned into underscores when making
490 For example, if your program is named @code{sniff-glue}, the derived
491 variable name would be @code{sniff_glue_SOURCES}, not
492 @code{sniff-glue_SOURCES}.
494 The strudel is an addition, to make the use of Autoconf substitutions in
495 macro names less obfuscating.
498 @node User Variables, Auxiliary Programs, Canonicalization, Generalities
499 @section Variables reserved for the user
501 @cindex variables, reserved for the user
502 @cindex user variables
504 Some @code{Makefile} variables are reserved by the GNU Coding Standards
505 for the use of the ``user'' -- the person building the package. For
506 instance, @code{CFLAGS} is one such variable.
508 Sometimes package developers are tempted to set user variables such as
509 @code{CFLAGS} because it appears to make their job easier -- they don't
510 have to introduce a second variable into every target.
512 However, the package itself should never set a user variable,
513 particularly not to include switches which are required for proper
514 compilation of the package. Since these variables are documented as
515 being for the package builder, that person rightfully expects to be able
516 to override any of these variables at build time.
518 To get around this problem, automake introduces an automake-specific
519 shadow variable for each user flag variable. (Shadow variables are not
520 introduced for variables like @code{CC}, where they would make no
521 sense.) The shadow variable is named by prepending @samp{AM_} to the
522 user variable's name. For instance, the shadow variable for
523 @code{YFLAGS} is @code{AM_YFLAGS}.
526 @node Auxiliary Programs, , User Variables, Generalities
527 @section Programs automake might require
529 @cindex Programs, auxiliary
530 @cindex Auxiliary programs
532 Automake sometimes requires helper programs so that the generated
533 @file{Makefile} can do its work properly. There are a fairly large
534 number of them, and we list them here.
539 These two files are used by the automatic de-ANSI-fication support
543 This is a wrapper for compilers which don't accept both @samp{-c} and
544 @samp{-o} at the same time. It is only used when absolutely required.
545 Such compilers are rare.
549 These programs compute the canonical triplets for the given build, host,
550 or target architecture.
553 This program understands how to run a compiler so that it will generate
554 not only the desired output but also dependency information which is
555 then used by the automatic dependency tracking feature.
558 This program is used to byte-compile Emacs Lisp code.
561 This is a replacement for the @code{install} program which works on
562 platforms where @code{install} is unavailable or unusable.
565 This script is used to generate a @file{version.texi} file. It examines
566 a file and prints some date information about it.
569 This wraps a number of programs which are typically only required by
570 maintainers. If the program in question doesn't exist, @code{missing}
571 prints an informative warning and attempts to fix things so that the
575 This works around the fact that @code{mkdir -p} is not portable.
578 This is used to byte-compile Python scripts.
581 Not a program, this file is required for @code{make dvi} to work when
582 Texinfo sources are in the package.
585 This program wraps @code{lex} and @code{yacc} and ensures that, for
586 instance, multiple @code{yacc} instances can be invoked in a single
587 directory in parallel.
592 @node Examples, Invoking Automake, Generalities, Top
593 @chapter Some example packages
596 * Complete:: A simple example, start to finish
597 * Hello:: A classic program
598 * etags:: Building etags and ctags
602 @node Complete, Hello, Examples, Examples
603 @section A simple example, start to finish
605 @cindex Complete example
607 Let's suppose you just finished writing @code{zardoz}, a program to make
608 your head float from vortex to vortex. You've been using Autoconf to
609 provide a portability framework, but your @file{Makefile.in}s have been
610 ad-hoc. You want to make them bulletproof, so you turn to Automake.
612 @cindex AM_INIT_AUTOMAKE, example use
614 The first step is to update your @file{configure.in} to include the
615 commands that @code{automake} needs. The way to do this is to add an
616 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
619 AM_INIT_AUTOMAKE(zardoz, 1.0)
622 Since your program doesn't have any complicating factors (e.g., it
623 doesn't use @code{gettext}, it doesn't want to build a shared library),
624 you're done with this part. That was easy!
626 @cindex aclocal program, introduction
627 @cindex aclocal.m4, preexisting
628 @cindex acinclude.m4, defined
630 Now you must regenerate @file{configure}. But to do that, you'll need
631 to tell @code{autoconf} how to find the new macro you've used. The
632 easiest way to do this is to use the @code{aclocal} program to generate
633 your @file{aclocal.m4} for you. But wait... you already have an
634 @file{aclocal.m4}, because you had to write some hairy macros for your
635 program. The @code{aclocal} program lets you put your own macros into
636 @file{acinclude.m4}, so simply rename and then run:
639 mv aclocal.m4 acinclude.m4
644 @cindex zardoz example
646 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
647 Since @code{zardoz} is a user program, you want to install it where the
648 rest of the user programs go. Additionally, @code{zardoz} has some
649 Texinfo documentation. Your @file{configure.in} script uses
650 @code{AC_REPLACE_FUNCS}, so you need to link against @samp{@@LIBOBJS@@}.
651 So here's what you'd write:
654 bin_PROGRAMS = zardoz
655 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
656 zardoz_LDADD = @@LIBOBJS@@
658 info_TEXINFOS = zardoz.texi
661 Now you can run @code{automake --add-missing} to generate your
662 @file{Makefile.in} and grab any auxiliary files you might need, and
666 @node Hello, etags, Complete, Examples
667 @section A classic program
669 @cindex Example, GNU Hello
670 @cindex Hello example
671 @cindex GNU Hello, example
673 @uref{ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz, GNU hello} is
674 renowned for its classic simplicity and versatility. This section shows
675 how Automake could be used with the GNU Hello package. The examples
676 below are from the latest beta version of GNU Hello, but with all of the
677 maintainer-only code stripped out, as well as all copyright comments.
679 Of course, GNU Hello is somewhat more featureful than your traditional
680 two-liner. GNU Hello is internationalized, does option processing, and
681 has a manual and a test suite.
683 @cindex configure.in, from GNU Hello
684 @cindex GNU Hello, configure.in
685 @cindex Hello, configure.in
687 Here is the @file{configure.in} from GNU Hello:
690 dnl Process this file with autoconf to produce a configure script.
692 AM_INIT_AUTOMAKE(hello, 1.3.11)
693 AM_CONFIG_HEADER(config.h)
695 dnl Set of available languages.
696 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
698 dnl Checks for programs.
702 dnl Checks for libraries.
704 dnl Checks for header files.
706 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
708 dnl Checks for library functions.
711 dnl Check for st_blksize in struct stat
714 dnl internationalization macros
716 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
717 src/Makefile tests/Makefile tests/hello],
718 [chmod +x tests/hello])
721 The @samp{AM_} macros are provided by Automake (or the Gettext library);
722 the rest are standard Autoconf macros.
725 The top-level @file{Makefile.am}:
728 EXTRA_DIST = BUGS ChangeLog.O
729 SUBDIRS = doc intl po src tests
732 As you can see, all the work here is really done in subdirectories.
734 The @file{po} and @file{intl} directories are automatically generated
735 using @code{gettextize}; they will not be discussed here.
737 @cindex Texinfo file handling example
738 @cindex Example, handling Texinfo files
740 In @file{doc/Makefile.am} we see:
743 info_TEXINFOS = hello.texi
744 hello_TEXINFOS = gpl.texi
747 This is sufficient to build, install, and distribute the GNU Hello
750 @cindex Regression test example
751 @cindex Example, regression test
753 Here is @file{tests/Makefile.am}:
757 EXTRA_DIST = hello.in testdata
760 The script @file{hello} is generated by @code{configure}, and is the
761 only test case. @code{make check} will run this test.
763 @cindex INCLUDES, example usage
765 Last we have @file{src/Makefile.am}, where all the real work is done:
769 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
770 hello_LDADD = @@INTLLIBS@@ @@ALLOCA@@
771 localedir = $(datadir)/locale
772 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
776 @node etags, , Hello, Examples
777 @section Building etags and ctags
779 @cindex Example, ctags and etags
780 @cindex ctags Example
781 @cindex etags Example
783 Here is another, trickier example. It shows how to generate two
784 programs (@code{ctags} and @code{etags}) from the same source file
785 (@file{etags.c}). The difficult part is that each compilation of
786 @file{etags.c} requires different @code{cpp} flags.
789 bin_PROGRAMS = etags ctags
791 ctags_LDADD = ctags.o
794 $(COMPILE) -DETAGS_REGEXPS -c etags.c
797 $(COMPILE) -DCTAGS -o ctags.o -c etags.c
800 Note that @code{ctags_SOURCES} is defined to be empty---that way no
801 implicit value is substituted. The implicit value, however, is used to
802 generate @code{etags} from @file{etags.o}.
804 @code{ctags_LDADD} is used to get @file{ctags.o} into the link line.
805 @code{ctags_DEPENDENCIES} is generated by Automake.
807 The above rules won't work if your compiler doesn't accept both
808 @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
809 bogus dependency (to avoid problems with a parallel @code{make}):
812 etags.o: etags.c ctags.o
813 $(COMPILE) -DETAGS_REGEXPS -c etags.c
816 $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
819 Also, these explicit rules do not work if the de-ANSI-fication feature
820 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
824 etags._o: etags._c ctags.o
825 $(COMPILE) -DETAGS_REGEXPS -c etags.c
828 $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
831 As it turns out, there is also a much easier way to do this same task.
832 Some of the above techniques are useful enough that we've kept the
833 example in the manual. However if you were to build @code{etags} and
834 @code{ctags} in real life, you would probably use per-program
835 compilation flags, like so:
838 bin_PROGRAMS = ctags etags
840 ctags_SOURCES = etags.c
841 ctags_CFLAGS = -DCTAGS
843 etags_SOURCES = etags.c
844 etags_CFLAGS = -DETAGS_REGEXPS
847 In this case Automake will cause @file{etags.c} to be compiled twice,
848 with different flags. De-ANSI-fication will work automatically. In
849 this instance, the names of the object files would be chosen by
850 automake; they would be @file{ctags-etags.c} and @file{etags-etags.o}.
851 (The name of the object files rarely matters.)
854 @node Invoking Automake, configure, Examples, Top
855 @chapter Creating a @file{Makefile.in}
857 @cindex Multiple configure.in files
858 @cindex Invoking Automake
859 @cindex Automake, invoking
861 To create all the @file{Makefile.in}s for a package, run the
862 @code{automake} program in the top level directory, with no arguments.
863 @code{automake} will automatically find each appropriate
864 @file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
865 and generate the corresponding @file{Makefile.in}. Note that
866 @code{automake} has a rather simplistic view of what constitutes a
867 package; it assumes that a package has only one @file{configure.in}, at
868 the top. If your package has multiple @file{configure.in}s, then you
869 must run @code{automake} in each directory holding a
872 You can optionally give @code{automake} an argument; @file{.am} is
873 appended to the argument and the result is used as the name of the input
874 file. This feature is generally only used to automatically rebuild an
875 out-of-date @file{Makefile.in}. Note that @code{automake} must always
876 be run from the topmost directory of a project, even if being used to
877 regenerate the @file{Makefile.in} in some subdirectory. This is
878 necessary because @code{automake} must scan @file{configure.in}, and
879 because @code{automake} uses the knowledge that a @file{Makefile.in} is
880 in a subdirectory to change its behavior in some cases.
882 @cindex Automake options
883 @cindex Options, Automake
885 @code{automake} accepts the following options:
887 @cindex Extra files distributed with Automake
888 @cindex Files distributed with Automake
895 @opindex --add-missing
896 Automake requires certain common files to exist in certain situations;
897 for instance @file{config.guess} is required if @file{configure.in} runs
898 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
899 files; this option will cause the missing ones to be automatically added
900 to the package, whenever possible. In general if Automake tells you a
901 file is missing, try using this option. By default Automake tries to
902 make a symbolic link pointing to its own copy of the missing file; this
903 can be changed with @code{--copy}.
905 @item --libdir=@var{dir}
907 Look for Automake data files in directory @var{dir} instead of in the
908 installation directory. This is typically used for debugging.
914 When used with @code{--add-missing}, causes installed files to be
915 copied. The default is to make a symbolic link.
919 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
920 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
924 @itemx --force-missing
925 @opindex --force-missing
926 When used with @code{--add-missing}, causes standard files to be rebuilt
927 even if they already exist in the source tree. This involves removing
928 the file from the source tree before creating the new symlink (or, with
929 @code{--copy}, copying the new file).
933 Set the global strictness to @samp{foreign}. For more information, see
938 Set the global strictness to @samp{gnits}. For more information, see
943 Set the global strictness to @samp{gnu}. For more information, see
944 @ref{Gnits}. This is the default strictness.
948 Print a summary of the command line options and exit.
953 This disables the dependency tracking feature; see @ref{Dependencies}.
956 @opindex --include-deps
957 This enables the dependency tracking feature. This feature is enabled
958 by default. This option is provided for historical reasons only and
959 probably should not be used.
963 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
964 @file{configure.in}. This option causes it to only update those
965 @file{Makefile.in}s which are out of date with respect to one of their
969 @itemx --output-dir=@var{dir}
971 @opindex --output-dir
972 Put the generated @file{Makefile.in} in the directory @var{dir}.
973 Ordinarily each @file{Makefile.in} is created in the directory of the
974 corresponding @file{Makefile.am}. This option is used when making
981 Cause Automake to print information about which files are being read or
986 Print the version number of Automake and exit.
992 @samp{--Werror} will cause all warnings issued by @code{automake} to
993 become errors. Errors affect the exit status of @code{automake}, while
994 warnings do not. @samp{--Wno-error}, the default, causes warnings to be
995 treated as warnings only.
999 @node configure, Top level, Invoking Automake, Top
1000 @chapter Scanning @file{configure.in}
1002 @cindex configure.in, scanning
1003 @cindex Scanning configure.in
1005 Automake scans the package's @file{configure.in} to determine certain
1006 information about the package. Some @code{autoconf} macros are required
1007 and some variables must be defined in @file{configure.in}. Automake
1008 will also use information from @file{configure.in} to further tailor its
1011 Automake also supplies some Autoconf macros to make the maintenance
1012 easier. These macros can automatically be put into your
1013 @file{aclocal.m4} using the @code{aclocal} program.
1016 * Requirements:: Configuration requirements
1017 * Optional:: Other things Automake recognizes
1018 * Invoking aclocal:: Auto-generating aclocal.m4
1019 * Macros:: Autoconf macros supplied with Automake
1020 * Extending aclocal:: Writing your own aclocal macros
1024 @node Requirements, Optional, configure, configure
1025 @section Configuration requirements
1027 @cindex Automake requirements
1028 @cindex Requirements of Automake
1030 The one real requirement of Automake is that your @file{configure.in}
1031 call @code{AM_INIT_AUTOMAKE}. This macro does several things which are
1032 required for proper Automake operation.
1033 @cvindex AM_INIT_AUTOMAKE
1035 Here are the other macros which Automake requires but which are not run
1036 by @code{AM_INIT_AUTOMAKE}:
1038 @cindex AC_OUTPUT, scanning
1042 Automake uses this to determine which files to create (@pxref{Output, ,
1043 Creating Output Files, autoconf, The Autoconf Manual}). Listed files
1044 named @code{Makefile} are treated as @file{Makefile}s. Other listed
1045 files are treated differently. Currently the only difference is that a
1046 @file{Makefile} is removed by @code{make distclean}, while other files
1047 are removed by @code{make clean}.
1048 @c FIXME: this is in violation of standards!
1052 You may need the following macros in some conditions, even though they
1056 @item AC_CHECK_TOOL([STRIP],[strip])
1057 @cindex STRIP, how to setup
1058 @cindex install-strip and STRIP
1059 @cvindex AC_CHECK_TOOL([STRIP],[strip])
1060 Installed binaries are usually stripped using @code{strip} when you run
1061 @code{make install-strip}. However @code{strip} might not be the
1062 right tool to use in cross-compilation environments, therefore
1063 Automake will honor the @code{STRIP} environment variable to overrule
1064 the program used to perform stripping. Automake will not set @code{STRIP}
1065 itself. If your package is not setup for cross-compilation you do not
1066 have to care (@code{strip} is ok), otherwise you can set @code{STRIP}
1067 automatically by calling @code{AC_CHECK_TOOL([STRIP],[strip])} from
1068 your @file{configure.in}.
1072 @node Optional, Invoking aclocal, Requirements, configure
1073 @section Other things Automake recognizes
1075 @cindex Macros Automake recognizes
1076 @cindex Recognized macros by Automake
1078 Automake will also recognize the use of certain macros and tailor the
1079 generated @file{Makefile.in} appropriately. Currently recognized macros
1080 and their effects are:
1083 @item AC_CONFIG_HEADER
1084 Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar
1085 to @code{AC_CONFIG_HEADER} (@pxref{Configuration Headers, ,
1086 Configuration Header Files, autoconf, The Autoconf Manual}), but does
1087 some useful Automake-specific work.
1088 @cvindex AC_CONFIG_HEADER
1090 @item AC_CONFIG_AUX_DIR
1091 Automake will look for various helper scripts, such as
1092 @file{mkinstalldirs}, in the directory named in this macro invocation.
1093 If not seen, the scripts are looked for in their @samp{standard}
1094 locations (either the top source directory, or in the source directory
1095 corresponding to the current @file{Makefile.am}, whichever is
1096 appropriate). @xref{Input, , Finding `configure' Input, autoconf, The
1098 @cvindex AC_CONFIG_AUX_DIR
1099 FIXME: give complete list of things looked for in this directory
1102 Automake will insert definitions for the variables defined by
1103 @code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
1104 or library. @xref{System Services, , System Services, autoconf, The
1106 @cvindex AC_PATH_XTRA
1108 @item AC_CANONICAL_HOST
1109 @itemx AC_CHECK_TOOL
1110 Automake will ensure that @file{config.guess} and @file{config.sub}
1111 exist. Also, the @file{Makefile} variables @samp{host_alias} and
1112 @samp{host_triplet} are introduced. See both @ref{Canonicalizing, ,
1113 Getting the Canonical System Type, autoconf, The Autoconf Manual}, and
1114 @ref{Generic Programs, , Generic Program Checks, autoconf, The Autoconf
1116 @c fixme xref autoconf docs.
1117 @cvindex AC_CANONICAL_HOST
1118 @cvindex AC_CHECK_TOOL
1120 @vindex host_triplet
1122 @item AC_CANONICAL_SYSTEM
1123 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
1124 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
1125 @xref{Canonicalizing, , Getting the Canonical System Type, autoconf, The
1127 @cvindex AC_CANONICAL_SYSTEM
1129 @vindex target_alias
1131 @item AC_FUNC_ALLOCA
1132 @itemx AC_FUNC_GETLOADAVG
1133 @itemx AC_FUNC_MEMCMP
1134 @itemx AC_STRUCT_ST_BLOCKS
1135 @itemx AC_FUNC_FNMATCH
1136 @itemx AC_FUNC_MKTIME
1137 @itemx AM_FUNC_STRTOD
1138 @itemx AC_REPLACE_FUNCS
1139 @itemx AC_REPLACE_GNU_GETOPT
1140 @itemx AM_WITH_REGEX
1141 Automake will ensure that the appropriate dependencies are generated for
1142 the objects corresponding to these macros. Also, Automake will verify
1143 that the appropriate source files are part of the distribution. Note
1144 that Automake does not come with any of the C sources required to use
1145 these macros, so @code{automake -a} will not install the sources.
1146 @xref{A Library}, for more information. Also, see @ref{Particular
1147 Functions, , Particular Function Checks, autoconf, The Autoconf Manual}.
1148 @cvindex AC_FUNC_ALLOCA
1149 @cvindex AC_FUNC_GETLOADAVG
1150 @cvindex AC_FUNC_MEMCMP
1151 @cvindex AC_STRUCT_ST_BLOCKS
1152 @cvindex AC_FUNC_FNMATCH
1153 @cvindex AC_FUNC_FNMATCH
1154 @cvindex AC_REPLACE_FUNCS
1155 @cvindex AC_REPLACE_GNU_GETOPT
1156 @cvindex AM_FUNC_STRTOD
1157 @cvindex AM_WITH_REGEX
1158 @cvindex AC_FUNC_MKTIME
1161 Automake will detect statements which put @file{.o} files into
1162 @code{LIBOBJS}, and will treat these additional files as if they were
1163 discovered via @code{AC_REPLACE_FUNCS}. @xref{Generic Functions, ,
1164 Generic Function Checks, autoconf, The Autoconf Manual}.
1167 @item AC_PROG_RANLIB
1168 This is required if any libraries are built in the package.
1169 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1171 @cvindex AC_PROG_RANLIB
1174 This is required if any C++ source is included. @xref{Particular
1175 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1176 @cvindex AC_PROG_CXX
1179 This is required if any Fortran 77 source is included. This macro is
1180 distributed with Autoconf version 2.13 and later. @xref{Particular
1181 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1182 @cvindex AC_PROG_F77
1184 @item AC_F77_LIBRARY_LDFLAGS
1185 This is required for programs and shared libraries that are a mixture of
1186 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
1187 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
1188 @cvindex AC_F77_LIBRARY_LDFLAGS
1190 @item AC_PROG_LIBTOOL
1191 Automake will turn on processing for @code{libtool} (@pxref{Top, ,
1192 Introduction, libtool, The Libtool Manual}).
1193 @cvindex AC_PROG_LIBTOOL
1196 If a Yacc source file is seen, then you must either use this macro or
1197 define the variable @samp{YACC} in @file{configure.in}. The former is
1198 preferred (@pxref{Particular Programs, , Particular Program Checks,
1199 autoconf, The Autoconf Manual}).
1200 @cvindex AC_PROG_YACC
1203 @item AC_DECL_YYTEXT
1204 This macro is required if there is Lex source in the package.
1205 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1207 @cvindex AC_DECL_YYTEXT
1210 If a Lex source file is seen, then this macro must be used.
1211 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1213 @cvindex AC_PROG_LEX
1215 @item AM_C_PROTOTYPES
1216 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
1217 @cvindex AM_C_PROTOTYPES
1219 @item AM_GNU_GETTEXT
1220 This macro is required for packages which use GNU gettext
1221 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1222 this macro it ensures that the package meets some of gettext's
1224 @cvindex AM_GNU_GETTEXT
1226 @item AM_MAINTAINER_MODE
1227 @opindex --enable-maintainer-mode
1228 This macro adds a @samp{--enable-maintainer-mode} option to
1229 @code{configure}. If this is used, @code{automake} will cause
1230 @samp{maintainer-only} rules to be turned off by default in the
1231 generated @file{Makefile.in}s. This macro is disallowed in @samp{Gnits}
1232 mode (@pxref{Gnits}). This macro defines the @samp{MAINTAINER_MODE}
1233 conditional, which you can use in your own @file{Makefile.am}.
1234 @cvindex AM_MAINTAINER_MODE
1237 @itemx AC_CHECK_TOOL
1238 @itemx AC_CHECK_PROG
1239 @itemx AC_CHECK_PROGS
1241 @itemx AC_PATH_PROGS
1242 For each of these macros, the first argument is automatically defined as
1243 a variable in each generated @file{Makefile.in}. @xref{Setting Output
1244 Variables, , Setting Output Variables, autoconf, The Autoconf Manual},
1245 and @ref{Generic Programs, , Generic Program Checks, autoconf, The
1248 @cvindex AC_CHECK_TOOL
1249 @cvindex AC_CHECK_PROG
1250 @cvindex AC_CHECK_PROGS
1251 @cvindex AC_PATH_PROG
1252 @cvindex AC_PATH_PROGS
1257 @node Invoking aclocal, Macros, Optional, configure
1258 @section Auto-generating aclocal.m4
1260 @cindex Invoking aclocal
1261 @cindex aclocal, Invoking
1263 Automake includes a number of Autoconf macros which can be used in your
1264 package; some of them are actually required by Automake in certain
1265 situations. These macros must be defined in your @file{aclocal.m4};
1266 otherwise they will not be seen by @code{autoconf}.
1268 The @code{aclocal} program will automatically generate @file{aclocal.m4}
1269 files based on the contents of @file{configure.in}. This provides a
1270 convenient way to get Automake-provided macros, without having to
1271 search around. Also, the @code{aclocal} mechanism is extensible for use
1274 At startup, @code{aclocal} scans all the @file{.m4} files it can find,
1275 looking for macro definitions. Then it scans @file{configure.in}. Any
1276 mention of one of the macros found in the first step causes that macro,
1277 and any macros it in turn requires, to be put into @file{aclocal.m4}.
1279 The contents of @file{acinclude.m4}, if it exists, are also
1280 automatically included in @file{aclocal.m4}. This is useful for
1281 incorporating local macros into @file{configure}.
1283 @code{aclocal} tries to be smart about looking for new @code{AC_DEFUN}s
1284 in the files it scans. It will warn if it finds duplicates. It also
1285 tries to copy the full text of the scanned file into @file{aclocal.m4},
1286 including both @samp{#} and @samp{dnl} comments. If you want to make a
1287 comment which will be completely ignored by @code{aclocal}, use
1288 @samp{##} as the comment leader.
1290 @code{aclocal} accepts the following options:
1293 @item --acdir=@var{dir}
1295 Look for the macro files in @var{dir} instead of the installation
1296 directory. This is typically used for debugging.
1300 Print a summary of the command line options and exit.
1304 Add the directory @var{dir} to the list of directories searched for
1307 @item --output=@var{file}
1309 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1311 @item --print-ac-dir
1312 @opindex --print-ac-dir
1313 Prints the name of the directory which @code{aclocal} will search to
1314 find the @file{.m4} files. When this option is given, normal processing
1315 is suppressed. This option can be used by a package to determine where
1316 to install a macro file.
1320 Print the names of the files it examines.
1324 Print the version number of Automake and exit.
1328 @node Macros, Extending aclocal, Invoking aclocal, configure
1329 @section Autoconf macros supplied with Automake
1331 @c consider generating this node automatically from m4 files.
1334 @item AM_CONFIG_HEADER
1335 Automake will generate rules to automatically regenerate the config
1336 header. If you do use this macro, you must create the file
1337 @file{stamp-h.in} in your source directory. It can be empty.
1338 @cvindex AM_CONFIG_HEADER
1340 @item AM_ENABLE_MULTILIB
1341 This is used when a ``multilib'' library is being built. The first
1342 optional argument is the name of the @file{Makefile} being generated; it
1343 defaults to @samp{Makefile}. The second option argument is used to find
1344 the top source directory; it defaults to the empty string (generally
1345 this should not be used unless you are familiar with the internals).
1348 @item _AM_DEPENDENCIES
1349 @itemx AM_SET_DEPDIR
1351 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
1352 These macros are used to implement automake's automatic dependency
1353 tracking scheme. They are called automatically by automake when
1354 required, and there should be no need to invoke them manually.
1356 @item AM_FUNC_STRTOD
1357 If the @code{strtod} function is not available, or does not work
1358 correctly (like the one on SunOS 5.4), add @file{strtod.o} to output
1359 variable @code{LIBOBJS}.
1360 @cvindex AM_FUNC_STRTOD
1362 @item AM_FUNC_ERROR_AT_LINE
1363 If the function @code{error_at_line} is not found, then add
1364 @file{error.o} to @code{LIBOBJS}.
1365 @cvindex AM_FUNC_ERROR_AT_LINE
1367 @item AM_FUNC_OBSTACK
1368 Check for the GNU obstacks code; if not found, add @file{obstack.o} to
1370 @cvindex AM_FUNC_OBSTACK
1372 @item AM_C_PROTOTYPES
1373 Check to see if function prototypes are understood by the compiler. If
1374 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1375 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1376 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1377 values to implement automatic de-ANSI-fication.
1378 @cvindex AM_C_PROTOTYPES
1380 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1381 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1382 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1383 found in @file{<termios.h>}.
1384 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1386 @item AM_INIT_AUTOMAKE
1387 Runs many macros that most @file{configure.in}'s need. This macro has
1388 two required arguments, the package and the version number. By default
1389 this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}. This
1390 can be avoided by passing in a non-empty third argument.
1392 @item AM_MAKE_INCLUDE
1393 This macro is used to discover how the user's @code{make} handles
1394 @code{include} statements. This macro is automatically invoked when
1395 needed; there should be no need to invoke it manually.
1397 @item AM_PATH_LISPDIR
1398 Searches for the program @code{emacs}, and, if found, sets the output
1399 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1400 @cvindex AM_PATH_LISPDIR
1403 Use this macro when you have assembly code in your project. This will
1404 choose the assembler for you (by default the C compiler), and will set
1405 @code{ASFLAGS} if required.
1407 @item AM_PROG_CC_C_O
1408 This is like @code{AC_PROG_CC_C_O}, but it generates its results in the
1409 manner required by automake. You must use this instead of
1410 @code{AC_PROG_CC_C_O} when you need this functionality.
1412 @item AM_PROG_CC_STDC
1413 If the C compiler in not in ANSI C mode by default, try to add an option
1414 to output variable @code{CC} to make it so. This macro tries various
1415 options that select ANSI C on some system or another. It considers the
1416 compiler to be in ANSI C mode if it handles function prototypes correctly.
1418 If you use this macro, you should check after calling it whether the C
1419 compiler has been set to accept ANSI C; if not, the shell variable
1420 @code{am_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
1421 code in ANSI C, you can make an un-ANSIfied copy of it by using the
1422 @code{ansi2knr} option (@pxref{ANSI}).
1425 @cindex HP-UX 10, lex problems
1426 @cindex lex problems with HP-UX 10
1427 Like @code{AC_PROG_LEX} with @code{AC_DECL_YYTEXT} (@pxref{Particular
1428 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}),
1429 but uses the @code{missing} script on systems that do not have
1430 @code{lex}. @samp{HP-UX 10} is one such system.
1432 Autoconf 2.50 and higher, in order to simplify the interface, includes
1433 the body of @code{AC_DECL_YYTEXT} in @code{AC_PROG_LEX}. To ensure
1434 backward compatibility, @code{AC_DECL_YYTEXT} is nevertheless defined as
1435 an invocation of @code{AC_PROG_LEX}. Since @code{AM_PROG_LEX} invokes
1436 both, it causes an annoying but benign warning (@code{AC_PROG_LEX}
1437 invoked multiple times) which you should just ignore. In the future,
1438 once Automake requires Autoconf 2.50, this issue will be fixed, but the
1439 current compatibility with Autoconf 2.13 prevents this.
1442 This macro finds the @code{gcj} program or causes an error. It sets
1443 @samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
1444 GNU Compiler Collection.
1445 @cvindex AM_PROG_GCJ
1447 @item AM_PROG_INSTALL_STRIP
1448 This is used to find a version of @code{install} which can be used to
1449 @code{strip} a program at installation time. This macro is
1450 automatically included when required.
1452 @item AM_SANITY_CHECK
1453 This checks to make sure that a file created in the build directory is
1454 newer than a file in the source directory. This can fail on systems
1455 where the clock is set incorrectly. This macro is automatically run
1456 from @code{AM_INIT_AUTOMAKE}.
1458 @item AM_SYS_POSIX_TERMIOS
1459 @cvindex am_cv_sys_posix_termios
1460 @cindex POSIX termios headers
1461 @cindex termios POSIX headers
1462 Check to see if POSIX termios headers and functions are available on the
1463 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1464 @samp{yes}. If not, set the variable to @samp{no}.
1466 @item AM_TYPE_PTRDIFF_T
1467 @cvindex HAVE_PTRDIFF_T
1469 Define @samp{HAVE_PTRDIFF_T} if the type @samp{ptrdiff_t} is defined in
1472 @item AM_WITH_DMALLOC
1473 @cvindex WITH_DMALLOC
1474 @cindex dmalloc, support for
1475 @opindex --with-dmalloc
1477 @uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
1478 package. If the user configures with @samp{--with-dmalloc}, then define
1479 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
1483 @opindex --with-regex
1484 @cindex regex package
1486 Adds @samp{--with-regex} to the @code{configure} command line. If
1487 specified (the default), then the @samp{regex} regular expression
1488 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1489 @samp{WITH_REGEX} is defined.. If @samp{--without-regex} is given, then
1490 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1491 into @samp{LIBOBJS}.
1496 @node Extending aclocal, , Macros, configure
1497 @section Writing your own aclocal macros
1499 @cindex aclocal, extending
1500 @cindex Extending aclocal
1502 The @code{aclocal} program doesn't have any built-in knowledge of any
1503 macros, so it is easy to extend it with your own macros.
1505 This is mostly used for libraries which want to supply their own
1506 Autoconf macros for use by other programs. For instance the
1507 @code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
1508 should be used by any package using @code{gettext}. When the library is
1509 installed, it installs this macro so that @code{aclocal} will find it.
1511 A file of macros should be a series of @code{AC_DEFUN}'s. The
1512 @code{aclocal} programs also understands @code{AC_REQUIRE}, so it is
1513 safe to put each macro in a separate file. @xref{Prerequisite Macros, ,
1514 , autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
1515 autoconf, The Autoconf Manual}.
1517 A macro file's name should end in @file{.m4}. Such files should be
1518 installed in @file{$(datadir)/aclocal}.
1521 @node Top level, Alternative, configure, Top
1522 @chapter The top-level @file{Makefile.am}
1524 @cindex SUBDIRS, explained
1526 In packages with subdirectories, the top level @file{Makefile.am} must
1527 tell Automake which subdirectories are to be built. This is done via
1528 the @code{SUBDIRS} variable.
1531 The @code{SUBDIRS} macro holds a list of subdirectories in which
1532 building of various sorts can occur. Many targets (e.g. @code{all}) in
1533 the generated @file{Makefile} will run both locally and in all specified
1534 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1535 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1536 (after configuration). This allows inclusion of libraries from packages
1537 which do not use Automake (such as @code{gettext}). The directories
1538 mentioned in @code{SUBDIRS} must be direct children of the current
1539 directory. For instance, you cannot put @samp{src/subdir} into
1542 In packages that use subdirectories, the top-level @file{Makefile.am} is
1543 often very short. For instance, here is the @file{Makefile.am} from the
1544 GNU Hello distribution:
1547 EXTRA_DIST = BUGS ChangeLog.O README-alpha
1548 SUBDIRS = doc intl po src tests
1551 @cindex SUBDIRS, overriding
1552 @cindex Overriding SUBDIRS
1554 It is possible to override the @code{SUBDIRS} variable if, like in the
1555 case of GNU @code{Inetutils}, you want to only build a subset of the
1556 entire package. In your @file{Makefile.am} include:
1559 SUBDIRS = @@MY_SUBDIRS@@
1562 Then in your @file{configure.in} you can specify:
1565 MY_SUBDIRS="src doc lib po"
1566 AC_SUBST(MY_SUBDIRS)
1569 (Note that we don't use the variable name @code{SUBDIRS} in our
1570 @file{configure.in}; that would cause Automake to believe that every
1571 @file{Makefile.in} should recurse into the listed subdirectories.)
1573 The upshot of this is that Automake is tricked into building the package
1574 to take the subdirs, but doesn't actually bind that list until
1575 @code{configure} is run.
1577 Although the @code{SUBDIRS} macro can contain configure substitutions
1578 (e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
1579 contents of this variable.
1581 If @code{SUBDIRS} is defined, then your @file{configure.in} must include
1582 @code{AC_PROG_MAKE_SET}. When Automake invokes @code{make} in a
1583 subdirectory, it uses the value of the @code{MAKE} variable. It passes
1584 the value of the variable @code{AM_MAKEFLAGS} to the @code{make}
1585 invocation; this can be set in @file{Makefile.am} if there are flags you
1586 must always pass to @code{make}.
1590 The use of @code{SUBDIRS} is not restricted to just the top-level
1591 @file{Makefile.am}. Automake can be used to construct packages of
1594 By default, Automake generates @file{Makefiles} which work depth-first
1595 (@samp{postfix}). However, it is possible to change this ordering. You
1596 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
1597 putting @samp{.} first will cause a @samp{prefix} ordering of
1598 directories. All @samp{clean} targets are run in reverse order of build
1601 Sometimes, such as when running @code{make dist}, you want all possible
1602 subdirectories to be examined. In this case Automake will use
1603 @code{DIST_SUBDIRS}, instead of @code{SUBDIRS}, to determine where to
1604 recurse. This variable will also be used when the user runs
1605 @code{distclean} or @code{maintainer-clean}. It should be set to the
1606 full list of subdirectories in the project. If this macro is not set,
1607 Automake will attempt to set it for you.
1610 @node Alternative, Rebuilding, Top level, Top
1611 @chapter An Alternative Approach to Subdirectories
1613 If you've ever read Peter Miller's excellent paper,
1614 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
1615 Recursive Make Considered Harmful}, the preceding section on the use of
1616 subdirectories will probably come as unwelcome advice. For those who
1617 haven't read the paper, Miller's main thesis is that recursive
1618 @code{make} invocations are both slow and error-prone.
1620 Automake provides sufficient cross-directory support @footnote{We
1621 believe. This work is new and there are probably warts.
1622 @xref{Introduction}, for information on reporting bugs.} to enable you
1623 to write a single @file{Makefile.am} for a complex multi-directory
1627 By default an installable file specified in a subdirectory will have its
1628 directory name stripped before installation. For instance, in this
1629 example, the header file will be installed as
1630 @file{$(includedir)/stdio.h}:
1633 include_HEADERS = inc/stdio.h
1637 @cindex Path stripping, avoiding
1638 @cindex Avoiding path stripping
1640 However, the @samp{nobase_} prefix can be used to circumvent this path
1641 stripping. In this example, the header file will be installed as
1642 @file{$(includedir)/sys/types.h}:
1645 nobase_include_HEADERS = sys/types.h
1649 @node Rebuilding, Programs, Alternative, Top
1650 @chapter Rebuilding Makefiles
1652 Automake generates rules to automatically rebuild @file{Makefile}s,
1653 @file{configure}, and other derived files like @file{Makefile.in}.
1655 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.in}, then
1656 these automatic rebuilding rules are only enabled in maintainer mode.
1658 Sometimes you need to run @code{aclocal} with an argument like @code{-I}
1659 to tell it where to find @file{.m4} files. Since sometimes @code{make}
1660 will automatically run @code{aclocal}, you need a way to specify these
1661 arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this
1662 holds arguments which are passed verbatim to @code{aclocal}. This macro
1663 is only useful in the top-level @file{Makefile.am}.
1664 @cindex ACLOCAL_AMFLAGS
1667 @node Programs, Other objects, Rebuilding, Top
1668 @chapter Building Programs and Libraries
1670 A large part of Automake's functionality is dedicated to making it easy
1671 to build programs and libraries.
1674 * A Program:: Building a program
1675 * A Library:: Building a library
1676 * Program and Library Variables::
1677 Variables controlling program and
1679 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
1680 * A Shared Library:: Building a Libtool library
1681 * Program variables:: Variables used when building a program
1682 * Yacc and Lex:: Yacc and Lex support
1684 * Assembly Support::
1685 * Fortran 77 Support::
1687 * Support for Other Languages::
1688 * ANSI:: Automatic de-ANSI-fication
1689 * Dependencies:: Automatic dependency tracking
1693 @node A Program, A Library, Programs, Programs
1694 @section Building a program
1696 @cindex PROGRAMS, bindir
1697 @vindex bin_PROGRAMS
1698 @vindex sbin_PROGRAMS
1699 @vindex libexec_PROGRAMS
1700 @vindex pkglib_PROGRAMS
1701 @vindex noinst_PROGRAMS
1703 In a directory containing source that gets built into a program (as
1704 opposed to a library), the @samp{PROGRAMS} primary is used. Programs
1705 can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
1706 @code{pkglibdir}, or not at all (@samp{noinst}). They can also be built
1707 only for @code{make check}, in which case the prefix is @samp{check}.
1712 bin_PROGRAMS = hello
1715 In this simple case, the resulting @file{Makefile.in} will contain code
1716 to generate a program named @code{hello}.
1718 Associated with each program are several assisting variables which are
1719 named after the program. These variables are all optional, and have
1720 reasonable defaults. Each variable, its use, and default is spelled out
1721 below; we use the ``hello'' example throughout.
1723 The variable @code{hello_SOURCES} is used to specify which source files
1724 get built into an executable:
1727 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
1730 This causes each mentioned @samp{.c} file to be compiled into the
1731 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
1733 @cindex _SOURCES primary, defined
1734 @cindex SOURCES primary, defined
1735 @cindex Primary variable, SOURCES
1737 If @samp{hello_SOURCES} is not specified, then it defaults to the single
1738 file @file{hello.c}; that is, the default is to compile a single C file
1739 whose base name is the name of the program itself. (This is a terrible
1740 default but we are stuck with it for historical reasons.)
1744 Multiple programs can be built in a single directory. Multiple programs
1745 can share a single source file, which must be listed in each
1746 @samp{_SOURCES} definition.
1748 @cindex Header files in _SOURCES
1749 @cindex _SOURCES and header files
1751 Header files listed in a @samp{_SOURCES} definition will be included in
1752 the distribution but otherwise ignored. In case it isn't obvious, you
1753 should not include the header file generated by @file{configure} in an
1754 @samp{_SOURCES} variable; this file should not be distributed. Lex
1755 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
1758 You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
1759 @samp{_SOURCES} variable. The reason for this is a bit hard to explain,
1760 but suffice to say that it simply won't work. Automake will give an
1761 error if you try to do this.
1763 @cindex EXTRA_prog_SOURCES, defined
1765 Automake must know all the source files that could possibly go into a
1766 program, even if not all the files are built in every circumstance.
1767 Any files which are only conditionally built should be listed in the
1768 appropriate @samp{EXTRA_} variable. For instance, if
1769 @file{hello-linux.c} were conditionally included in @code{hello}, the
1770 @file{Makefile.am} would contain:
1773 EXTRA_hello_SOURCES = hello-linux.c
1776 Similarly, sometimes it is useful to determine the programs that are to
1777 be built at configure time. For instance, GNU @code{cpio} only builds
1778 @code{mt} and @code{rmt} under special circumstances.
1780 @cindex EXTRA_PROGRAMS, defined
1782 In this case, you must notify Automake of all the programs that can
1783 possibly be built, but at the same time cause the generated
1784 @file{Makefile.in} to use the programs specified by @code{configure}.
1785 This is done by having @code{configure} substitute values into each
1786 @samp{_PROGRAMS} definition, while listing all optionally built programs
1787 in @code{EXTRA_PROGRAMS}.
1788 @vindex EXTRA_PROGRAMS
1790 If you need to link against libraries that are not found by
1791 @code{configure}, you can use @code{LDADD} to do so. This variable
1792 actually can be used to add any options to the linker command line.
1795 @cindex prog_LDADD, defined
1797 Sometimes, multiple programs are built in one directory but do not share
1798 the same link-time requirements. In this case, you can use the
1799 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
1800 program as it appears in some @samp{_PROGRAMS} variable, and usually
1801 written in lowercase) to override the global @code{LDADD}. If this
1802 variable exists for a given program, then that program is not linked
1806 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
1807 linked against the library @file{libcpio.a}. However, @code{rmt} is
1808 built in the same directory, and has no such link requirement. Also,
1809 @code{mt} and @code{rmt} are only built on certain architectures. Here
1810 is what cpio's @file{src/Makefile.am} looks like (abridged):
1813 bin_PROGRAMS = cpio pax @@MT@@
1814 libexec_PROGRAMS = @@RMT@@
1815 EXTRA_PROGRAMS = mt rmt
1817 LDADD = ../lib/libcpio.a @@INTLLIBS@@
1820 cpio_SOURCES = @dots{}
1821 pax_SOURCES = @dots{}
1822 mt_SOURCES = @dots{}
1823 rmt_SOURCES = @dots{}
1826 @cindex _LDFLAGS, defined
1828 @samp{@var{prog}_LDADD} is inappropriate for passing program-specific
1829 linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
1830 @samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
1834 @cindex _DEPENDENCIES, defined
1836 It is also occasionally useful to have a program depend on some other
1837 target which is not actually part of that program. This can be done
1838 using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
1839 on the contents of such a variable, but no further interpretation is
1842 If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
1843 Automake. The automatically-assigned value is the contents of
1844 @samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
1845 @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
1846 configure substitutions that are left in are only @samp{@@LIBOBJS@@} and
1847 @samp{@@ALLOCA@@}; these are left because it is known that they will not
1848 cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
1852 @node A Library, Program and Library Variables, A Program, Programs
1853 @section Building a library
1855 @cindex _LIBRARIES primary, defined
1856 @cindex LIBRARIES primary, defined
1857 @cindex Primary variable, LIBRARIES
1859 @vindex lib_LIBRARIES
1860 @vindex pkglib_LIBRARIES
1861 @vindex noinst_LIBRARIES
1863 Building a library is much like building a program. In this case, the
1864 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
1865 @code{libdir} or @code{pkglibdir}.
1867 @xref{A Shared Library}, for information on how to build shared
1868 libraries using Libtool and the @samp{LTLIBRARIES} primary.
1870 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
1871 For instance to create a library named @file{libcpio.a}, but not install
1872 it, you would write:
1875 noinst_LIBRARIES = libcpio.a
1878 The sources that go into a library are determined exactly as they are
1879 for programs, via the @samp{_SOURCES} variables. Note that the library
1880 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
1881 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
1882 not @samp{liblob.a_SOURCES}.
1884 @cindex _LIBADD primary, defined
1885 @cindex LIBADD primary, defined
1886 @cindex Primary variable, LIBADD
1888 Extra objects can be added to a library using the
1889 @samp{@var{library}_LIBADD} variable. This should be used for objects
1890 determined by @code{configure}. Again from @code{cpio}:
1895 libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
1898 In addition, sources for extra objects that will not exist until
1899 configure-time must be added to the @code{BUILT_SOURCES} variable
1903 @node Program and Library Variables, LIBOBJS, A Library, Programs
1904 @section Program and Library Variables
1906 Associated with each program are a collection of variables which can be
1907 used to modify how that program is built. There is a similar list of
1908 such variables for each library. The canonical name of the program (or
1909 library) is used as a base for naming these variables.
1911 In the list below, we use the name ``maude'' to refer to the program or
1912 library. In your @file{Makefile.am} you would replace this with the
1913 canonical name of your program. This list also refers to ``maude'' as a
1914 program, but in general the same rules apply for both static and dynamic
1915 libraries; the documentation below notes situations where programs and
1920 This variable, if it exists, lists all the source files which are
1921 compiled to build the program. These files are added to the
1922 distribution by default. When building the program, Automake will cause
1923 each source file to be compiled to a single @file{.o} file (or
1924 @file{.lo} when using libtool). Normally these object files are named
1925 after the source file, but other factors can change this. If a file in
1926 the @samp{_SOURCES} variable has an unrecognized extension, Automake
1927 will do one of two things with it. If a suffix rule exists for turning
1928 files with the unrecognized extension into @file{.o} files, then
1929 automake will treat this file as it will any other source file
1930 (@pxref{Support for Other Languages}). Otherwise, the file will be
1931 ignored as though it were a header file.
1933 The prefixes @samp{dist_} and @samp{nodist_} can be used to control
1934 whether files listed in a @samp{_SOURCES} variable are distributed.
1935 @samp{dist_} is redundant, as sources are distributed by default, but it
1936 can be specified for clarity if desired.
1938 It is possible to have both @samp{dist_} and @samp{nodist_} variants of
1939 a given @samp{_SOURCES} variable at once; this lets you easily
1940 distribute some files and not others, for instance:
1943 nodist_maude_SOURCES = nodist.c
1944 dist_maude_SOURCES = dist-me.c
1947 By default the output file (on Unix systems, the @file{.o} file) will be
1948 put into the current build directory. However, if the option
1949 @code{subdir-objects} is in effect in the current directory then the
1950 @file{.o} file will be put into the subdirectory named after the source
1951 file. For instance, with @code{subdir-objects} enabled,
1952 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
1953 people prefer this mode of operation. You can specify
1954 @code{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
1955 @cindex Subdirectory, objects in
1956 @cindex Objects in subdirectory
1959 @item EXTRA_maude_SOURCES
1960 Automake needs to know the list of files you intend to compile
1961 @emph{statically}. For one thing, this is the only way Automake has of
1962 knowing what sort of language support a given @file{Makefile.in}
1963 requires. @footnote{There are other, more obscure reasons reasons for
1964 this limitation as well.} This means that, for example, you can't put a
1965 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
1966 variable. If you intend to conditionally compile source files and use
1967 @file{configure} to substitute the appropriate object names into, e.g.,
1968 @samp{_LDADD} (see below), then you should list the corresponding source
1969 files in the @samp{EXTRA_} variable.
1971 This variable also supports @samp{dist_} and @samp{nodist_} prefixes,
1972 e.g., @samp{nodist_EXTRA_maude_SOURCES}.
1975 A static library is created by default by invoking @code{$(AR) cru}
1976 followed by the name of the library and then the objects being put into
1977 the library. You can override this by setting the @samp{_AR} variable.
1978 This is usually used with C++; some C++ compilers require a special
1979 invocation in order to instantiate all the templates which should go
1980 into a library. For instance, the SGI C++ compiler likes this macro set
1983 libmaude_a_AR = $(CXX) -ar -o
1987 Extra objects can be added to a static library using the @samp{_LIBADD}
1988 variable. This should be used for objects determined by
1989 @code{configure}. Note that @samp{_LIBADD} is not used for shared
1990 libraries; there you must use @samp{_LDADD}.
1993 Extra objects can be added to a shared library or a program by listing
1994 them in the @samp{_LDADD} variable. This should be used for objects
1995 determined by @code{configure}.
1997 @samp{_LDADD} is inappropriate for passing program-specific linker flags
1998 (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen}).
1999 Use the @samp{_LDFLAGS} variable for this purpose.
2001 For instance, if your @file{configure.in} uses @code{AC_PATH_XTRA}, you
2002 could link your program against the X libraries like so:
2005 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
2009 This variable is used to pass extra flags to the link step of a program
2010 or a shared library.
2013 You can override the linker on a per-program basis. By default the
2014 linker is chosen according to the languages used by the program. For
2015 instance, a program that includes C++ source code would use the C++
2016 compiler to link. The @samp{_LINK} variable must hold the name of a
2017 command which can be passed all the @file{.o} file names as arguments.
2018 Note that the name of the underlying program is @emph{not} passed to
2019 @samp{_LINK}; typically one uses @samp{$@@}:
2022 maude_LINK = $(CCLD) -magic -o $@@
2026 Automake allows you to set compilation flags on a per-program (or
2027 per-library) basis. A single source file can be included in several
2028 programs, and it will potentially be compiled with different flags for
2029 each program. This works for any language directly supported by
2030 Automake. The flags are @samp{_CFLAGS}, @samp{_CXXFLAGS},
2031 @samp{_OBJCFLAGS}, @samp{_YFLAGS}, @samp{_ASFLAGS}, @samp{_FFLAGS},
2032 @samp{_RFLAGS}, and @samp{_GCJFLAGS}.
2034 When using a per-program compilation flag, Automake will choose a
2035 different name for the intermediate object files. Ordinarily a file
2036 like @file{sample.c} will be compiled to produce @file{sample.o}.
2037 However, if the program's @samp{_CFLAGS} variable is set, then the
2038 object file will be named, for instance, @file{maude-sample.o}.
2040 In compilations with per-program flags, the ordinary @samp{AM_} form of
2041 the flags variable is @emph{not} automatically included in the
2042 compilation (however, the user form of the variable @emph{is} included).
2043 So for instance, if you want the hypothetical @file{maude} compilations
2044 to also use the value of @samp{AM_CFLAGS}, you would need to write:
2047 maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
2050 @item maude_DEPENDENCIES
2051 It is also occasionally useful to have a program depend on some other
2052 target which is not actually part of that program. This can be done
2053 using the @samp{_DEPENDENCIES} variable. Each program depends on the
2054 contents of such a variable, but no further interpretation is done.
2056 If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake.
2057 The automatically-assigned value is the contents of @samp{_LDADD}, with
2058 most configure substitutions, @samp{-l}, @samp{-L}, @samp{-dlopen} and
2059 @samp{-dlpreopen} options removed. The configure substitutions that are
2060 left in are only @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are
2061 left because it is known that they will not cause an invalid value for
2062 @samp{_DEPENDENCIES} to be generated.
2064 @item maude_SHORTNAME
2065 On some platforms the allowable file names are very short. In order to
2066 support these systems and per-program compilation flags at the same
2067 time, Automake allows you to set a ``short name'' which will influence
2068 how intermediate object files are named. For instance, if you set
2069 @samp{maude_SHORTNAME} to @samp{m}, then in the above per-program
2070 compilation flag example the object file would be named
2071 @file{m-sample.o} rather than @file{maude-sample.o}. This facility is
2072 rarely needed in practice, and we recommend avoiding it until you find
2077 @node LIBOBJS, A Shared Library, Program and Library Variables, Programs
2078 @section Special handling for LIBOBJS and ALLOCA
2080 @cindex @@LIBOBJS@@, special handling
2081 @cindex @@ALLOCA@@, special handling
2083 Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
2084 @code{@@ALLOCA@@}, and uses this information, plus the list of
2085 @code{LIBOBJS} files derived from @file{configure.in} to automatically
2086 include the appropriate source files in the distribution (@pxref{Dist}).
2087 These source files are also automatically handled in the
2088 dependency-tracking scheme; see @xref{Dependencies}.
2090 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
2091 @samp{_LDADD} or @samp{_LIBADD} variable.
2094 @node A Shared Library, Program variables, LIBOBJS, Programs
2095 @section Building a Shared Library
2097 @cindex Shared libraries, support for
2099 Building shared libraries is a relatively complex matter. For this
2100 reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
2101 Libtool Manual}) was created to help build shared libraries in a
2102 platform-independent way.
2104 @cindex _LTLIBRARIES primary, defined
2105 @cindex LTLIBRARIES primary, defined
2106 @cindex Primary variable, LTLIBRARIES
2107 @cindex Example of shared libraries
2109 @cindex suffix .la, defined
2111 Automake uses Libtool to build libraries declared with the
2112 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a list
2113 of shared libraries to build. For instance, to create a library named
2114 @file{libgettext.a} and its corresponding shared libraries, and install
2115 them in @samp{libdir}, write:
2118 lib_LTLIBRARIES = libgettext.la
2121 @vindex lib_LTLIBRARIES
2122 @vindex pkglib_LTLIBRARIES
2123 @vindex noinst_LTLIBRARIES
2124 @vindex check_LTLIBRARIES
2126 @cindex check_LTLIBRARIES, not allowed
2128 Note that shared libraries @emph{must} be installed, so
2129 @code{check_LTLIBRARIES} is not allowed. However,
2130 @code{noinst_LTLIBRARIES} is allowed. This feature should be used for
2131 libtool ``convenience libraries''.
2133 @cindex suffix .lo, defined
2135 For each library, the @samp{@var{library}_LIBADD} variable contains the
2136 names of extra libtool objects (@file{.lo} files) to add to the shared
2137 library. The @samp{@var{library}_LDFLAGS} variable contains any
2138 additional libtool flags, such as @samp{-version-info} or
2141 @cindex @@LTLIBOBJS@@, special handling
2143 Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
2144 library must use @code{@@LTLIBOBJS@@}. This is required because the
2145 object files that libtool operates on do not necessarily end in
2146 @file{.o}. The libtool manual contains more details on this topic.
2148 For libraries installed in some directory, Automake will automatically
2149 supply the appropriate @samp{-rpath} option. However, for libraries
2150 determined at configure time (and thus mentioned in
2151 @code{EXTRA_LTLIBRARIES}), Automake does not know the eventual
2152 installation directory; for such libraries you must add the
2153 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
2156 Ordinarily, Automake requires that a shared library's name start with
2157 @samp{lib}. However, if you are building a dynamically loadable module
2158 then you might wish to use a "nonstandard" name. In this case, put
2159 @code{-module} into the @samp{_LDFLAGS} variable.
2161 @xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
2162 libtool, The Libtool Manual}, for more information.
2165 @node Program variables, Yacc and Lex, A Shared Library, Programs
2166 @section Variables used when building a program
2168 Occasionally it is useful to know which @file{Makefile} variables
2169 Automake uses for compilations; for instance you might need to do your
2170 own compilation in some special cases.
2172 Some variables are inherited from Autoconf; these are @code{CC},
2173 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
2177 There are some additional variables which Automake itself defines:
2181 The contents of this macro are passed to every compilation which invokes
2182 the C preprocessor; it is a list of arguments to the preprocessor. For
2183 instance, @samp{-I} and @samp{-D} options should be listed here.
2185 Automake already provides some @samp{-I} options automatically. In
2186 particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I}
2187 pointing to the directory holding @file{config.h} (if you've used
2188 @code{AC_CONFIG_HEADER} or @code{AM_CONFIG_HEADER}). You can disable
2189 the default @samp{-I} options using the @samp{nostdinc} option.
2192 This does the same job as @samp{AM_CPPFLAGS}. It is an older name for
2193 the same functionality. This macro is deprecated; we suggest using
2194 @samp{AM_CPPFLAGS} instead.
2197 This is the command used to actually compile a C source file. The
2198 filename is appended to form the complete command line.
2201 This is the command used to actually link a C program.
2205 @node Yacc and Lex, C++ Support, Program variables, Programs
2206 @section Yacc and Lex support
2208 Automake has somewhat idiosyncratic support for Yacc and Lex.
2210 Automake assumes that the @file{.c} file generated by @code{yacc} (or
2211 @code{lex}) should be named using the basename of the input file. That
2212 is, for a yacc source file @file{foo.y}, Automake will cause the
2213 intermediate file to be named @file{foo.c} (as opposed to
2214 @file{y.tab.c}, which is more traditional).
2216 The extension of a yacc source file is used to determine the extension
2217 of the resulting @samp{C} or @samp{C++} file. Files with the extension
2218 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
2219 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
2222 Likewise, lex source files can be used to generate @samp{C} or
2223 @samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
2224 @samp{.lxx} are recognized.
2226 You should never explicitly mention the intermediate (@samp{C} or
2227 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
2230 The intermediate files generated by @code{yacc} (or @code{lex}) will be
2231 included in any distribution that is made. That way the user doesn't
2232 need to have @code{yacc} or @code{lex}.
2234 If a @code{yacc} source file is seen, then your @file{configure.in} must
2235 define the variable @samp{YACC}. This is most easily done by invoking
2236 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
2237 Program Checks, autoconf, The Autoconf Manual}).
2239 When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
2240 @samp{AM_YFLAGS}. The former is a user variable and the latter is
2241 intended for the @file{Makefile.am} author.
2243 Similarly, if a @code{lex} source file is seen, then your
2244 @file{configure.in} must define the variable @samp{LEX}. You can use
2245 @samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
2246 Program Checks, autoconf, The Autoconf Manual}). Automake's @code{lex}
2247 support also requires that you use the @samp{AC_DECL_YYTEXT}
2248 macro---automake needs to know the value of @samp{LEX_OUTPUT_ROOT}.
2249 This is all handled for you if you use the @code{AM_PROG_LEX} macro
2252 When @code{yacc} is invoked, it is passed @samp{LFLAGS} and
2253 @samp{AM_LFLAGS}. The former is a user variable and the latter is
2254 intended for the @file{Makefile.am} author.
2259 @cindex yacc, multiple parsers
2260 @cindex Multiple yacc parsers
2261 @cindex Multiple lex lexers
2262 @cindex lex, multiple lexers
2265 Automake makes it possible to include multiple @code{yacc} (or
2266 @code{lex}) source files in a single program. Automake uses a small
2267 program called @code{ylwrap} to run @code{yacc} (or @code{lex}) in a
2268 subdirectory. This is necessary because yacc's output filename is
2269 fixed, and a parallel make could conceivably invoke more than one
2270 instance of @code{yacc} simultaneously. The @code{ylwrap} program is
2271 distributed with Automake. It should appear in the directory specified
2272 by @samp{AC_CONFIG_AUX_DIR} (@pxref{Input, , Finding `configure' Input,
2273 autoconf, The Autoconf Manual}), or the current directory if that macro
2274 is not used in @file{configure.in}.
2276 For @code{yacc}, simply managing locking is insufficient. The output of
2277 @code{yacc} always uses the same symbol names internally, so it isn't
2278 possible to link two @code{yacc} parsers into the same executable.
2280 We recommend using the following renaming hack used in @code{gdb}:
2282 #define yymaxdepth c_maxdepth
2283 #define yyparse c_parse
2285 #define yyerror c_error
2286 #define yylval c_lval
2287 #define yychar c_char
2288 #define yydebug c_debug
2289 #define yypact c_pact
2296 #define yyexca c_exca
2297 #define yyerrflag c_errflag
2298 #define yynerrs c_nerrs
2302 #define yy_yys c_yys
2303 #define yystate c_state
2306 #define yy_yyv c_yyv
2308 #define yylloc c_lloc
2309 #define yyreds c_reds
2310 #define yytoks c_toks
2311 #define yylhs c_yylhs
2312 #define yylen c_yylen
2313 #define yydefred c_yydefred
2314 #define yydgoto c_yydgoto
2315 #define yysindex c_yysindex
2316 #define yyrindex c_yyrindex
2317 #define yygindex c_yygindex
2318 #define yytable c_yytable
2319 #define yycheck c_yycheck
2320 #define yyname c_yyname
2321 #define yyrule c_yyrule
2324 For each define, replace the @samp{c_} prefix with whatever you like.
2325 These defines work for @code{bison}, @code{byacc}, and traditional
2326 @code{yacc}s. If you find a parser generator that uses a symbol not
2327 covered here, please report the new name so it can be added to the list.
2330 @node C++ Support, Assembly Support, Yacc and Lex, Programs
2331 @section C++ Support
2334 @cindex Support for C++
2336 Automake includes full support for C++.
2338 Any package including C++ code must define the output variable
2339 @samp{CXX} in @file{configure.in}; the simplest way to do this is to use
2340 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
2341 Program Checks, autoconf, The Autoconf Manual}).
2343 A few additional variables are defined when a C++ source file is seen:
2347 The name of the C++ compiler.
2350 Any flags to pass to the C++ compiler.
2353 The command used to actually compile a C++ source file. The file name
2354 is appended to form the complete command line.
2357 The command used to actually link a C++ program.
2361 @node Assembly Support, Fortran 77 Support, C++ Support, Programs
2362 @section Assembly Support
2364 Automake includes some support for assembly code.
2366 The variable @code{AS} holds the name of the compiler used to build
2367 assembly code. This compiler must work a bit like a C compiler; in
2368 particular it must accept @samp{-c} and @samp{-o}. The value of
2369 @code{ASFLAGS} is passed to the compilation.
2373 You are required to set @code{AS} and @code{ASFLAGS} via
2374 @file{configure.in}. The autoconf macro @code{AM_PROG_AS} will do this
2375 for you. Unless they are already set, it simply sets @code{AS} to the C
2376 compiler and @code{ASFLAGS} to the C compiler flags.
2379 @node Fortran 77 Support, Java Support, Assembly Support, Programs
2380 @comment node-name, next, previous, up
2381 @section Fortran 77 Support
2383 @cindex Fortran 77 support
2384 @cindex Support for Fortran 77
2386 Automake includes full support for Fortran 77.
2388 Any package including Fortran 77 code must define the output variable
2389 @samp{F77} in @file{configure.in}; the simplest way to do this is to use
2390 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
2391 Program Checks, autoconf, The Autoconf Manual}). @xref{Fortran 77 and
2394 A few additional variables are defined when a Fortran 77 source file is
2400 The name of the Fortran 77 compiler.
2403 Any flags to pass to the Fortran 77 compiler.
2406 Any flags to pass to the Ratfor compiler.
2409 The command used to actually compile a Fortran 77 source file. The file
2410 name is appended to form the complete command line.
2413 The command used to actually link a pure Fortran 77 program or shared
2418 Automake can handle preprocessing Fortran 77 and Ratfor source files in
2419 addition to compiling them@footnote{Much, if not most, of the
2420 information in the following sections pertaining to preprocessing
2421 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
2422 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
2423 also contains some support for creating programs and shared libraries
2424 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
2425 Fortran 77 With C and C++}).
2427 These issues are covered in the following sections.
2430 * Preprocessing Fortran 77::
2431 * Compiling Fortran 77 Files::
2432 * Mixing Fortran 77 With C and C++::
2433 * Fortran 77 and Autoconf::
2437 @node Preprocessing Fortran 77, Compiling Fortran 77 Files, Fortran 77 Support, Fortran 77 Support
2438 @comment node-name, next, previous, up
2439 @subsection Preprocessing Fortran 77
2441 @cindex Preprocessing Fortran 77
2442 @cindex Fortran 77, Preprocessing
2443 @cindex Ratfor programs
2445 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
2446 rule runs just the preprocessor to convert a preprocessable Fortran 77
2447 or Ratfor source file into a strict Fortran 77 source file. The precise
2448 command used is as follows:
2453 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2456 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2461 @node Compiling Fortran 77 Files, Mixing Fortran 77 With C and C++, Preprocessing Fortran 77, Fortran 77 Support
2462 @comment node-name, next, previous, up
2463 @subsection Compiling Fortran 77 Files
2465 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
2466 @file{N.r} by running the Fortran 77 compiler. The precise command used
2472 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
2475 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
2478 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
2483 @node Mixing Fortran 77 With C and C++, Fortran 77 and Autoconf, Compiling Fortran 77 Files, Fortran 77 Support
2484 @comment node-name, next, previous, up
2485 @subsection Mixing Fortran 77 With C and C++
2487 @cindex Fortran 77, mixing with C and C++
2488 @cindex Mixing Fortran 77 with C and C++
2489 @cindex Linking Fortran 77 with C and C++
2491 @cindex Mixing Fortran 77 with C and/or C++
2493 Automake currently provides @emph{limited} support for creating programs
2494 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
2495 However, there are many other issues related to mixing Fortran 77 with
2496 other languages that are @emph{not} (currently) handled by Automake, but
2497 that are handled by other packages@footnote{For example,
2498 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
2499 addresses all of these inter-language issues, and runs under nearly all
2500 Fortran 77, C and C++ compilers on nearly all platforms. However,
2501 @code{cfortran} is not yet Free Software, but it will be in the next
2505 Automake can help in two ways:
2509 Automatic selection of the linker depending on which combinations of
2513 Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
2514 @samp{-l}) to pass to the automatically selected linker in order to link
2515 in the appropriate Fortran 77 intrinsic and run-time libraries.
2517 @cindex FLIBS, defined
2518 These extra Fortran 77 linker flags are supplied in the output variable
2519 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
2520 supplied with newer versions of Autoconf (Autoconf version 2.13 and
2521 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
2525 If Automake detects that a program or shared library (as mentioned in
2526 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
2527 code that is a mixture of Fortran 77 and C and/or C++, then it requires
2528 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
2529 @file{configure.in}, and that either @code{$(FLIBS)} or @code{@@FLIBS@@}
2530 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
2531 (for shared libraries) variables. It is the responsibility of the
2532 person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
2533 or @code{@@FLIBS@@} appears in the appropriate @code{_LDADD} or
2534 @code{_LIBADD} variable.
2536 @cindex Mixed language example
2537 @cindex Example, mixed language
2539 For example, consider the following @file{Makefile.am}:
2543 foo_SOURCES = main.cc foo.f
2544 foo_LDADD = libfoo.la @@FLIBS@@
2546 pkglib_LTLIBRARIES = libfoo.la
2547 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
2548 libfoo_la_LIBADD = $(FLIBS)
2551 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
2552 is mentioned in @file{configure.in}. Also, if @code{@@FLIBS@@} hadn't
2553 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
2554 Automake would have issued a warning.
2559 * How the Linker is Chosen::
2562 @node How the Linker is Chosen, , Mixing Fortran 77 With C and C++, Mixing Fortran 77 With C and C++
2563 @comment node-name, next, previous, up
2564 @subsubsection How the Linker is Chosen
2566 @cindex Automatic linker selection
2567 @cindex Selecting the linker automatically
2569 The following diagram demonstrates under what conditions a particular
2570 linker is chosen by Automake.
2572 For example, if Fortran 77, C and C++ source code were to be compiled
2573 into a program, then the C++ linker will be used. In this case, if the
2574 C or Fortran 77 linkers required any special libraries that weren't
2575 included by the C++ linker, then they must be manually added to an
2576 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
2582 code \ C C++ Fortran
2583 ----------------- +---------+---------+---------+
2587 +---------+---------+---------+
2591 +---------+---------+---------+
2595 +---------+---------+---------+
2599 +---------+---------+---------+
2601 C + Fortran | | | x |
2603 +---------+---------+---------+
2605 C++ + Fortran | | x | |
2607 +---------+---------+---------+
2609 C + C++ + Fortran | | x | |
2611 +---------+---------+---------+
2615 @node Fortran 77 and Autoconf, , Mixing Fortran 77 With C and C++, Fortran 77 Support
2616 @comment node-name, next, previous, up
2617 @subsection Fortran 77 and Autoconf
2619 The current Automake support for Fortran 77 requires a recent enough
2620 version Autoconf that also includes support for Fortran 77. Full
2621 Fortran 77 support was added to Autoconf 2.13, so you will want to use
2622 that version of Autoconf or later.
2625 @node Java Support, Support for Other Languages, Fortran 77 Support, Programs
2626 @comment node-name, next, previous, up
2627 @section Java Support
2629 @cindex Java support
2630 @cindex Support for Java
2632 Automake includes support for compiled Java, using @code{gcj}, the Java
2633 front end to the GNU Compiler Collection.
2635 Any package including Java code to be compiled must define the output
2636 variable @samp{GCJ} in @file{configure.in}; the variable @samp{GCJFLAGS}
2637 must also be defined somehow (either in @file{configure.in} or
2638 @file{Makefile.am}). The simplest way to do this is to use the
2639 @code{AM_PROG_GCJ} macro.
2643 By default, programs including Java source files are linked with
2646 As always, the contents of @samp{AM_GCJFLAGS} are passed to every
2647 compilation invoking @code{gcj} (in its role as an ahead-of-time
2648 compiler -- when invoking it to create @file{.class} files,
2649 @samp{AM_JAVACFLAGS} is used instead). If it is necessary to pass
2650 options to @code{gcj} from @file{Makefile.am}, this macro, and not the
2651 user macro @samp{GCJFLAGS}, should be used.
2655 @code{gcj} can be used to compile @file{.java}, @file{.class},
2656 @file{.zip}, or @file{.jar} files.
2659 @node Support for Other Languages, ANSI, Java Support, Programs
2660 @comment node-name, next, previous, up
2661 @section Support for Other Languages
2663 Automake currently only includes full support for C, C++ (@pxref{C++
2664 Support}), Fortran 77 (@pxref{Fortran 77 Support}), and Java
2665 (@pxref{Java Support}). There is only rudimentary support for other
2666 languages, support for which will be improved based on user demand.
2668 Some limited support for adding your own languages is available via the
2669 suffix rule handling; see @ref{Suffixes}.
2672 @node ANSI, Dependencies, Support for Other Languages, Programs
2673 @section Automatic de-ANSI-fication
2675 @cindex de-ANSI-fication, defined
2677 Although the GNU standards allow the use of ANSI C, this can have the
2678 effect of limiting portability of a package to some older compilers
2679 (notably the SunOS C compiler).
2681 Automake allows you to work around this problem on such machines by
2682 @dfn{de-ANSI-fying} each source file before the actual compilation takes
2685 @vindex AUTOMAKE_OPTIONS
2688 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
2689 (@pxref{Options}) contains the option @code{ansi2knr} then code to
2690 handle de-ANSI-fication is inserted into the generated
2693 This causes each C source file in the directory to be treated as ANSI C.
2694 If an ANSI C compiler is available, it is used. If no ANSI C compiler
2695 is available, the @code{ansi2knr} program is used to convert the source
2696 files into K&R C, which is then compiled.
2698 The @code{ansi2knr} program is simple-minded. It assumes the source
2699 code will be formatted in a particular way; see the @code{ansi2knr} man
2702 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
2703 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
2704 these files are distributed with Automake. Also, the package
2705 @file{configure.in} must call the macro @code{AM_C_PROTOTYPES}
2707 @cvindex AM_C_PROTOTYPES
2709 Automake also handles finding the @code{ansi2knr} support files in some
2710 other directory in the current package. This is done by prepending the
2711 relative path to the appropriate directory to the @code{ansi2knr}
2712 option. For instance, suppose the package has ANSI C code in the
2713 @file{src} and @file{lib} subdirs. The files @file{ansi2knr.c} and
2714 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
2715 @file{src/Makefile.am}:
2718 AUTOMAKE_OPTIONS = ../lib/ansi2knr
2721 If no directory prefix is given, the files are assumed to be in the
2724 Files mentioned in @code{LIBOBJS} which need de-ANSI-fication will not
2725 be automatically handled. That's because @code{configure} will generate
2726 an object name like @file{regex.o}, while @code{make} will be looking
2727 for @file{regex_.o} (when de-ANSI-fying). Eventually this problem will
2728 be fixed via @code{autoconf} magic, but for now you must put this code
2729 into your @file{configure.in}, just before the @code{AC_OUTPUT} call:
2732 # This is necessary so that .o files in LIBOBJS are also built via
2733 # the ANSI2KNR-filtering rules.
2734 LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
2737 Note that automatic de-ANSI-fication will not work when the package is
2738 being built for a different host architecture. That is because automake
2739 currently has no way to build @code{ansi2knr} for the build machine.
2742 @node Dependencies, , ANSI, Programs
2743 @section Automatic dependency tracking
2745 As a developer it is often painful to continually update the
2746 @file{Makefile.in} whenever the include-file dependencies change in a
2747 project. Automake supplies a way to automatically track dependency
2750 @cindex Dependency tracking
2751 @cindex Automatic dependency tracking
2753 Automake always uses complete dependencies for a compilation, including
2754 system headers. Automake's model is that dependency computation should
2755 be a side effect of the build. To this end, dependencies are computed
2756 by running all compilations through a special wrapper program called
2757 @code{depcomp}. @code{depcomp} understands how to coax many different C
2758 and C++ compilers into generating dependency information in the format
2759 it requires. @code{automake -a} will install @code{depcomp} into your
2760 source tree for you. If @code{depcomp} can't figure out how to properly
2761 invoke your compiler, dependency tracking will simply be disabled for
2766 Experience with earlier versions of Automake @footnote{See
2767 @uref{http://sources.redhat.com/automake/dependencies.html} for more
2768 information on the history and experiences with automatic dependency
2769 tracking in Automake} taught us that it is not reliable to generate
2770 dependencies only on the maintainer's system, as configurations vary too
2771 much. So instead Automake implements dependency tracking at build time.
2773 Automatic dependency tracking can be suppressed by putting
2774 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}. Or, you
2775 can invoke @code{automake} with the @code{-i} option. Dependency
2776 tracking is enabled by default.
2778 @vindex AUTOMAKE_OPTIONS
2779 @opindex no-dependencies
2781 The person building your package also can choose to disable dependency
2782 tracking by configuring with @code{--disable-dependency-tracking}.
2784 @cindex Disabling dependency tracking
2785 @cindex Dependency tracking, disabling
2788 @node Other objects, Other GNU Tools, Programs, Top
2789 @chapter Other Derived Objects
2791 Automake can handle derived objects which are not C programs. Sometimes
2792 the support for actually building such objects must be explicitly
2793 supplied, but Automake will still automatically handle installation and
2797 * Scripts:: Executable scripts
2798 * Headers:: Header files
2799 * Data:: Architecture-independent data files
2800 * Sources:: Derived sources
2804 @node Scripts, Headers, Other objects, Other objects
2805 @section Executable Scripts
2807 @cindex _SCRIPTS primary, defined
2808 @cindex SCRIPTS primary, defined
2809 @cindex Primary variable, SCRIPTS
2811 It is possible to define and install programs which are scripts. Such
2812 programs are listed using the @samp{SCRIPTS} primary name. Automake
2813 doesn't define any dependencies for scripts; the @file{Makefile.am}
2814 should include the appropriate rules.
2817 Automake does not assume that scripts are derived objects; such objects
2818 must be deleted by hand (@pxref{Clean}).
2820 The @code{automake} program itself is a Perl script that is generated at
2821 configure time from @file{automake.in}. Here is how this is handled:
2824 bin_SCRIPTS = automake
2827 Since @code{automake} appears in the @code{AC_OUTPUT} macro, a target
2828 for it is automatically generated.
2830 @cindex SCRIPTS, installation directories
2831 @cindex Installing scripts
2834 @vindex sbin_SCRIPTS
2835 @vindex libexec_SCRIPTS
2836 @vindex pkgdata_SCRIPTS
2837 @vindex noinst_SCRIPTS
2839 Script objects can be installed in @code{bindir}, @code{sbindir},
2840 @code{libexecdir}, or @code{pkgdatadir}.
2843 @node Headers, Data, Scripts, Other objects
2844 @section Header files
2846 @cindex _HEADERS primary, defined
2847 @cindex HEADERS primary, defined
2848 @cindex Primary variable, HEADERS
2850 @vindex noinst_HEADERS
2852 Header files are specified by the @samp{HEADERS} family of variables.
2853 Generally header files are not installed, so the @code{noinst_HEADERS}
2854 variable will be the most used. @footnote{However, for the case of a
2855 non-installed header file that is actually used by a particular program,
2856 we recommend listing it in the program's @samp{_SOURCES} variable
2857 instead of in @code{noinst_HEADERS}. We believe this is more clear.}
2860 All header files must be listed somewhere; missing ones will not appear
2861 in the distribution. Often it is clearest to list uninstalled headers
2862 with the rest of the sources for a program. @xref{A Program}. Headers
2863 listed in a @samp{_SOURCES} variable need not be listed in any
2864 @samp{_HEADERS} variable.
2866 @cindex HEADERS, installation directories
2867 @cindex Installing headers
2869 @vindex include_HEADERS
2870 @vindex oldinclude_HEADERS
2871 @vindex pkginclude_HEADERS
2873 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
2874 @code{pkgincludedir}.
2877 @node Data, Sources, Headers, Other objects
2878 @section Architecture-independent data files
2880 @cindex _DATA primary, defined
2881 @cindex DATA primary, defined
2882 @cindex Primary variable, DATA
2884 Automake supports the installation of miscellaneous data files using the
2885 @samp{DATA} family of variables.
2889 @vindex sysconf_DATA
2890 @vindex sharedstate_DATA
2891 @vindex localstate_DATA
2892 @vindex pkgdata_DATA
2894 Such data can be installed in the directories @code{datadir},
2895 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
2898 By default, data files are @emph{not} included in a distribution. Of
2899 course, you can use the @samp{dist_} prefix to change this on a
2902 Here is how Automake installs its auxiliary data files:
2905 pkgdata_DATA = clean-kr.am clean.am @dots{}
2909 @node Sources, , Data, Other objects
2910 @section Built sources
2912 @cindex BUILT_SOURCES, defined
2914 Occasionally a file which would otherwise be called @samp{source}
2915 (e.g. a C @samp{.h} file) is actually derived from some other file.
2916 Such files should be listed in the @code{BUILT_SOURCES} variable.
2917 @vindex BUILT_SOURCES
2919 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
2920 must be created early in the build process can be listed in this
2923 A source file listed in @code{BUILT_SOURCES} is created before the other
2924 @code{all} targets are made. However, such a source file is not
2925 compiled unless explicitly requested by mentioning it in some other
2926 @samp{_SOURCES} variable.
2928 So, for instance, if you had header files which were created by a script
2929 run at build time, then you would list these headers in
2930 @code{BUILT_SOURCES}, to ensure that they would be built before any
2931 other compilations (perhaps ones using these headers) were started.
2934 @node Other GNU Tools, Documentation, Other objects, Top
2935 @chapter Other GNU Tools
2937 Since Automake is primarily intended to generate @file{Makefile.in}s for
2938 use in GNU programs, it tries hard to interoperate with other GNU tools.
2941 * Emacs Lisp:: Emacs Lisp
2949 @node Emacs Lisp, gettext, Other GNU Tools, Other GNU Tools
2952 @cindex _LISP primary, defined
2953 @cindex LISP primary, defined
2954 @cindex Primary variable, LISP
2960 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
2961 is used to hold a list of @file{.el} files. Possible prefixes for this
2962 primary are @samp{lisp_} and @samp{noinst_}. Note that if
2963 @code{lisp_LISP} is defined, then @file{configure.in} must run
2964 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
2968 By default Automake will byte-compile all Emacs Lisp source files using
2969 the Emacs found by @code{AM_PATH_LISPDIR}. If you wish to avoid
2970 byte-compiling, simply define the variable @code{ELCFILES} to be empty.
2971 Byte-compiled Emacs Lisp files are not portable among all versions of
2972 Emacs, so it makes sense to turn this off if you expect sites to have
2973 more than one version of Emacs installed. Furthermore, many packages
2974 don't actually benefit from byte-compilation. Still, we recommend that
2975 you leave it enabled by default. It is probably better for sites with
2976 strange setups to cope for themselves than to make the installation less
2977 nice for everybody else.
2980 @node gettext, Libtool, Emacs Lisp, Other GNU Tools
2983 @cindex GNU Gettext support
2984 @cindex Gettext support
2985 @cindex Support for GNU Gettext
2987 If @code{AM_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
2988 turns on support for GNU gettext, a message catalog system for
2989 internationalization
2990 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
2992 The @code{gettext} support in Automake requires the addition of two
2993 subdirectories to the package, @file{intl} and @file{po}. Automake
2994 insures that these directories exist and are mentioned in
2998 @node Libtool, Java, gettext, Other GNU Tools
3001 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
3002 libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
3003 @xref{A Shared Library}.
3006 @node Java, Python, Libtool, Other GNU Tools
3009 @cindex _JAVA primary, defined
3010 @cindex JAVA primary, defined
3011 @cindex Primary variable, JAVA
3013 Automake provides some minimal support for Java compilation with the
3014 @samp{JAVA} primary.
3016 Any @file{.java} files listed in a @samp{_JAVA} variable will be
3017 compiled with @code{JAVAC} at build time. By default, @file{.class}
3018 files are not included in the distribution.
3020 @cindex JAVA restrictions
3021 @cindex Restrictions for JAVA
3023 Currently Automake enforces the restriction that only one @samp{_JAVA}
3024 primary can be used in a given @file{Makefile.am}. The reason for this
3025 restriction is that, in general, it isn't possible to know which
3026 @file{.class} files were generated from which @file{.java} files -- so
3027 it would be impossible to know which files to install where. For
3028 instance, a @file{.java} file can define multiple classes; the resulting
3029 @file{.class} file names cannot be predicted without parsing the
3032 There are a few variables which are used when compiling Java sources:
3036 The name of the Java compiler. This defaults to @samp{javac}.
3039 The flags to pass to the compiler. This is considered to be a user
3040 variable (@pxref{User Variables}).
3043 More flags to pass to the Java compiler. This, and not
3044 @code{JAVACFLAGS}, should be used when it is necessary to put Java
3045 compiler flags into @file{Makefile.am}.
3048 The value of this variable is passed to the @samp{-d} option to
3049 @code{javac}. It defaults to @samp{$(top_builddir)}.
3052 This variable is an @code{sh} expression which is used to set the
3053 @code{CLASSPATH} environment variable on the @code{javac} command line.
3054 (In the future we will probably handle class path setting differently.)
3058 @node Python, , Java, Other GNU Tools
3061 @cindex _PYTHON primary, defined
3062 @cindex PYTHON primary, defined
3063 @cindex Primary variable, PYTHON
3066 Automake provides support for Python modules. Automake will turn on
3067 Python support if the @code{AM_PATH_PYTHON} macro is used in
3068 @file{configure.in}. The @samp{PYTHON} primary is used to hold a list
3069 of @file{.py} files. Possible prefixes for this primary are
3070 @samp{python_} and @samp{noinst_}. Note that if @code{python_PYTHON} is
3071 defined, then @file{configure.in} must run @code{AM_PATH_PYTHON}.
3072 Python source files are included in the distribution by default.
3074 @code{AM_PATH_PYTHON} takes a single optional argument. This argument,
3075 if present, is the minimum version of Python which can be used for this
3076 package. If the version of Python found on the system is older than the
3077 required version, then @code{AM_PATH_PYTHON} will cause an error.
3079 @code{AM_PATH_PYTHON} creates several output variables based on the
3080 Python installation found during configuration.
3084 The name of the Python executable.
3086 @item PYTHON_VERSION
3087 The Python version number, in the form @var{major}.@var{minor}
3088 (e.g. @samp{1.5}). This is currently the value of
3089 @code{sys.version[:3]}.
3092 The string @code{$prefix}. This term may be used in future work
3093 which needs the contents of Python's @code{sys.prefix}, but general
3094 consensus is to always use the value from configure.
3096 @item PYTHON_EXEC_PREFIX
3097 The string @code{$exec_prefix}. This term may be used in future work
3098 which needs the contents of Python's @code{sys.exec_prefix}, but general
3099 consensus is to always use the value from configure.
3101 @item PYTHON_PLATFORM
3102 The canonical name used by Python to describe the operating system, as
3103 given by @code{sys.platform}. This value is sometimes needed when
3104 building Python extensions.
3107 The directory name for the @file{site-packages} subdirectory of the
3108 standard Python install tree.
3111 This is is the directory under @code{pythondir} which is named after the
3112 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
3116 This is the directory where Python extension modules (shared libraries)
3117 should be installed.
3120 This is a convenience variable which is defined as
3121 @samp{$(pyexecdir)/$(PACKAGE)}.
3127 By default Automake will byte-compile all Python source files to both
3128 @file{.pyc} and @file{.pyo} forms. If you wish to avoid generating the
3129 optimized byte-code files, simply define the variable @code{PYOFILES} to
3130 be empty. Similarly, if you don't wish to generate the standard
3131 byte-compiled files, define the variable @code{PYCFILES} to be empty.
3134 @node Documentation, Install, Other GNU Tools, Top
3135 @chapter Building documentation
3137 Currently Automake provides support for Texinfo and man pages.
3141 * Man pages:: Man pages
3145 @node Texinfo, Man pages, Documentation, Documentation
3148 @cindex _TEXINFOS primary, defined
3149 @cindex TEXINFOS primary, defined
3150 @cindex Primary variable, TEXINFOS
3152 If the current directory contains Texinfo source, you must declare it
3153 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
3154 into info, and thus the @code{info_TEXINFOS} macro is most commonly used
3155 here. Any Texinfo source file must end in the @file{.texi},
3156 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
3159 @vindex info_TEXINFOS
3161 @cindex Texinfo macro, VERSION
3162 @cindex Texinfo macro, UPDATED
3163 @cindex Texinfo macro, EDITION
3164 @cindex Texinfo macro, UPDATED-MONTH
3166 @cindex VERSION Texinfo macro
3167 @cindex UPDATED Texinfo macro
3168 @cindex EDITION Texinfo macro
3169 @cindex UPDATED-MONTH Texinfo macro
3173 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
3174 that file will be automatically generated. The file @file{version.texi}
3175 defines four Texinfo macros you can reference:
3180 Both of these macros hold the version number of your program. They are
3181 kept separate for clarity.
3184 This holds the date the primary @file{.texi} file was last modified.
3187 This holds the name of the month in which the primary @file{.texi} file
3191 The @file{version.texi} support requires the @code{mdate-sh} program;
3192 this program is supplied with Automake and automatically included when
3193 @code{automake} is invoked with the @code{--add-missing} option.
3195 If you have multiple Texinfo files, and you want to use the
3196 @file{version.texi} feature, then you have to have a separate version
3197 file for each Texinfo file. Automake will treat any include in a
3198 Texinfo file that matches @samp{vers*.texi} just as an automatically
3199 generated version file.
3201 When an info file is rebuilt, the program named by the @code{MAKEINFO}
3202 variable is used to invoke it. If the @code{makeinfo} program is found
3203 on the system then it will be used by default; otherwise @code{missing}
3204 will be used instead. The flags in the variables @code{MAKEINFOFLAGS}
3205 and @code{AM_MAKEINFOFLAGS} will be passed to the @code{makeinfo}
3206 invocation; the first of these is intended for use by the user
3207 (@pxref{User Variables}) and the second by the @file{Makefile.am}
3210 @vindex MAKEINFOFLAGS
3211 @vindex AM_MAKEINFOFLAGS
3213 Sometimes an info file actually depends on more than one @file{.texi}
3214 file. For instance, in GNU Hello, @file{hello.texi} includes the file
3215 @file{gpl.texi}. You can tell Automake about these dependencies using
3216 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
3221 info_TEXINFOS = hello.texi
3222 hello_TEXINFOS = gpl.texi
3227 By default, Automake requires the file @file{texinfo.tex} to appear in
3228 the same directory as the Texinfo source. However, if you used
3229 @code{AC_CONFIG_AUX_DIR} in @file{configure.in} (@pxref{Input, , Finding
3230 `configure' Input, autoconf, The Autoconf Manual}), then
3231 @file{texinfo.tex} is looked for there. Automake supplies
3232 @file{texinfo.tex} if @samp{--add-missing} is given.
3236 If your package has Texinfo files in many directories, you can use the
3237 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
3238 @file{texinfo.tex} for your package. The value of this variable should
3239 be the relative path from the current @file{Makefile.am} to
3243 TEXINFO_TEX = ../doc/texinfo.tex
3246 @opindex no-texinfo.tex
3248 The option @samp{no-texinfo.tex} can be used to eliminate the
3249 requirement for @file{texinfo.tex}. Use of the variable
3250 @code{TEXINFO_TEX} is preferable, however, because that allows the
3251 @code{dvi} target to still work.
3253 @cindex Target, install-info
3254 @cindex Target, noinstall-info
3255 @cindex install-info target
3256 @cindex noinstall-info target
3258 @opindex no-installinfo
3259 @trindex install-info
3261 Automake generates an @code{install-info} target; some people apparently
3262 use this. By default, info pages are installed by @samp{make install}.
3263 This can be prevented via the @code{no-installinfo} option.
3266 @node Man pages, , Texinfo, Documentation
3269 @cindex _MANS primary, defined
3270 @cindex MANS primary, defined
3271 @cindex Primary variable, MANS
3273 A package can also include man pages (but see the GNU standards on this
3274 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
3275 pages are declared using the @samp{MANS} primary. Generally the
3276 @code{man_MANS} macro is used. Man pages are automatically installed in
3277 the correct subdirectory of @code{mandir}, based on the file extension.
3281 File extensions such as @samp{.1c} are handled by looking for the valid
3282 part of the extension and using that to determine the correct
3283 subdirectory of @code{mandir}. Valid section names are the digits
3284 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
3286 Sometimes developers prefer to name a man page something like
3287 @file{foo.man} in the source, and then rename it to have the correct
3288 suffix, e.g. @file{foo.1}, when installing the file. Automake also
3289 supports this mode. For a valid section named @var{SECTION}, there is a
3290 corresponding directory named @samp{man@var{SECTION}dir}, and a
3291 corresponding @samp{_MANS} variable. Files listed in such a variable
3292 are installed in the indicated section. If the file already has a
3293 valid suffix, then it is installed as-is; otherwise the file suffix is
3294 changed to match the section.
3296 For instance, consider this example:
3298 man1_MANS = rename.man thesame.1 alsothesame.1c
3301 In this case, @file{rename.man} will be renamed to @file{rename.1} when
3302 installed, but the other files will keep their names.
3304 @cindex Target, install-man
3305 @cindex Target, noinstall-man
3306 @cindex install-man target
3307 @cindex noinstall-man target
3309 @c Use @samp{make install} per documentation: (texi)code.
3310 By default, man pages are installed by @samp{make install}. However,
3311 since the GNU project does not require man pages, many maintainers do
3312 not expend effort to keep the man pages up to date. In these cases, the
3313 @code{no-installman} option will prevent the man pages from being
3314 installed by default. The user can still explicitly install them via
3315 @samp{make install-man}.
3316 @opindex no-installman
3317 @trindex install-man
3319 Here is how the man pages are handled in GNU @code{cpio} (which includes
3320 both Texinfo documentation and man pages):
3323 man_MANS = cpio.1 mt.1
3324 EXTRA_DIST = $(man_MANS)
3327 Man pages are not currently considered to be source, because it is not
3328 uncommon for man pages to be automatically generated. Therefore they
3329 are not automatically included in the distribution. However, this can
3330 be changed by use of the @samp{dist_} prefix.
3332 The @samp{nobase_} prefix is meaningless for man pages and is
3336 @node Install, Clean, Documentation, Top
3337 @chapter What Gets Installed
3339 @cindex Installation support
3340 @cindex make install support
3342 Naturally, Automake handles the details of actually installing your
3343 program once it has been built. All files named by the various
3344 primaries are automatically installed in the appropriate places when the
3345 user runs @code{make install}.
3347 A file named in a primary is installed by copying the built file into
3348 the appropriate directory. The base name of the file is used when
3352 bin_PROGRAMS = hello subdir/goodbye
3355 In this example, both @samp{hello} and @samp{goodbye} will be installed
3356 in @code{$(bindir)}.
3358 Sometimes it is useful to avoid the basename step at install time. For
3359 instance, you might have a number of header files in subdirectories of
3360 the source tree which are laid out precisely how you want to install
3361 them. In this situation you can use the @samp{nobase_} prefix to
3362 suppress the base name step. For example:
3365 nobase_include_HEADERS = stdio.h sys/types.h
3368 Will install @file{stdio.h} in @code{$(includedir)} and @file{types.h}
3369 in @code{$(includedir)/sys}.
3371 Automake generates separate @code{install-data} and @code{install-exec}
3372 targets, in case the installer is installing on multiple machines which
3373 share directory structure---these targets allow the machine-independent
3374 parts to be installed only once. The @code{install} target depends on
3375 both of these targets.
3376 @trindex install-data
3377 @trindex install-exec
3380 Automake also generates an @code{uninstall} target, an
3381 @code{installdirs} target, and an @code{install-strip} target.
3383 @trindex installdirs
3384 @trindex install-strip
3386 It is possible to extend this mechanism by defining an
3387 @code{install-exec-local} or @code{install-data-local} target. If these
3388 targets exist, they will be run at @samp{make install} time.
3389 @trindex install-exec-local
3390 @trindex install-data-local
3392 Variables using the standard directory prefixes @samp{data},
3393 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
3394 @samp{pkgdata}, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
3395 installed by @samp{install-data}.
3397 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
3398 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
3399 @samp{pkglib} (e.g. @samp{bin_PROGRAMS}) are installed by
3400 @samp{install-exec}.
3402 Any variable using a user-defined directory prefix with @samp{exec} in
3403 the name (e.g. @samp{myexecbin_PROGRAMS} is installed by
3404 @samp{install-exec}. All other user-defined prefixes are installed by
3405 @samp{install-data}.
3408 Automake generates support for the @samp{DESTDIR} variable in all
3409 install rules. @samp{DESTDIR} is used during the @samp{make install}
3410 step to relocate install objects into a staging area. Each object and
3411 path is prefixed with the value of @samp{DESTDIR} before being copied
3412 into the install area. Here is an example of typical DESTDIR usage:
3415 make DESTDIR=/tmp/staging install
3418 This places install objects in a directory tree built under
3419 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
3420 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
3421 would install @file{/tmp/staging/gnu/bin/foo} and
3422 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
3424 This feature is commonly used to build install images and packages. For
3425 more information, see @ref{Makefile Conventions, , , standards, The GNU
3429 @node Clean, Dist, Install, Top
3430 @chapter What Gets Cleaned
3432 @cindex make clean support
3434 The GNU Makefile Standards specify a number of different clean rules.
3436 Generally the files that can be cleaned are determined automatically by
3437 Automake. Of course, Automake also recognizes some variables that can
3438 be defined to specify additional files to clean. These variables are
3439 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
3440 @code{MAINTAINERCLEANFILES}.
3441 @vindex MOSTLYCLEANFILES
3443 @vindex DISTCLEANFILES
3444 @vindex MAINTAINERCLEANFILES
3446 As the GNU Standards aren't always explicit as to which files should be
3447 removed by which target, we've adopted a heuristic which we believe was
3448 first formulated by Fran@,{c}ois Pinard:
3452 If @code{make} built it, and it is commonly something that one would
3453 want to rebuild (for instance, a @file{.o} file), then
3454 @code{mostlyclean} should delete it.
3457 Otherwise, if @code{make} built it, then @code{clean} should delete it.
3460 If @code{configure} built it, then @code{distclean} should delete it
3463 If the maintainer built it, then @code{maintainer-clean} should
3467 We recommend that you follow this same set of heuristics in your
3471 @node Dist, Tests, Clean, Top
3472 @chapter What Goes in a Distribution
3474 @section Basics of distribution
3477 @cindex make distcheck
3479 The @code{dist} target in the generated @file{Makefile.in} can be used
3480 to generate a gzip'd @code{tar} file for distribution. The tar file is
3481 named based on the @samp{PACKAGE} and @samp{VERSION} variables; more
3482 precisely it is named @samp{@var{package}-@var{version}.tar.gz}.
3486 You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
3487 is run. The default setting is @samp{--best}.
3489 For the most part, the files to distribute are automatically found by
3490 Automake: all source files are automatically included in a distribution,
3491 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
3492 has a built-in list of commonly used files which, if present in the
3493 current directory, are automatically included. This list is printed by
3494 @samp{automake --help}. Also, files which are read by @code{configure}
3495 (i.e. the source files corresponding to the files specified in the
3496 @code{AC_OUTPUT} invocation) are automatically distributed.
3498 Still, sometimes there are files which must be distributed, but which
3499 are not covered in the automatic rules. These files should be listed in
3500 the @code{EXTRA_DIST} variable. You can mention files from
3501 subdirectories in @code{EXTRA_DIST}.
3503 You can also mention a directory in @code{EXTRA_DIST}; in this case the
3504 entire directory will be recursively copied into the distribution.
3505 Please note that this will also copy @emph{everything} in the directory,
3506 including CVS/RCS version control files. We recommend against using
3511 @section Fine-grained distribution control
3513 Sometimes you need tighter control over what does @emph{not} go into the
3514 distribution; for instance you might have source files which are
3515 generated and which you do not want to distribute. In this case
3516 Automake gives fine-grained control using the @samp{dist} and
3517 @samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
3518 prefixed with @samp{dist_} to add the listed files to the distribution.
3519 Similarly, @samp{nodist_} can be used to omit the files from the
3524 As an example, here is how you would cause some data to be distributed
3525 while leaving some source code out of the distribution:
3528 dist_data_DATA = distribute-this
3530 nodist_foo_SOURCES = do-not-distribute.c
3533 @section The dist hook
3535 Another way to to use this is for removing unnecessary files that get
3536 recursively included by specifying a directory in EXTRA_DIST:
3542 rm -rf `find $(distdir)/doc -name CVS`
3545 If you define @code{SUBDIRS}, Automake will recursively include the
3546 subdirectories in the distribution. If @code{SUBDIRS} is defined
3547 conditionally (@pxref{Conditionals}), Automake will normally include all
3548 directories that could possibly appear in @code{SUBDIRS} in the
3549 distribution. If you need to specify the set of directories
3550 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
3551 list of subdirectories to include in the distribution.
3552 @vindex DIST_SUBDIRS
3556 Occasionally it is useful to be able to change the distribution before
3557 it is packaged up. If the @code{dist-hook} target exists, it is run
3558 after the distribution directory is filled, but before the actual tar
3559 (or shar) file is created. One way to use this is for distributing
3560 files in subdirectories for which a new @file{Makefile.am} is overkill:
3564 mkdir $(distdir)/random
3565 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
3568 @section Checking the distribution
3570 Automake also generates a @code{distcheck} target which can be of help
3571 to ensure that a given distribution will actually work.
3572 @code{distcheck} makes a distribution, and then tries to do a
3576 If the target @code{distcheck-hook} is defined in your
3577 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
3578 the new distribution has been unpacked, but before the unpacked copy is
3579 configured and built. Your @code{distcheck-hook} can do almost
3580 anything, though as always caution is advised. Generally this hook is
3581 used to check for potential distribution errors not caught by the
3585 @node Tests, Options, Dist, Top
3586 @chapter Support for test suites
3591 Automake supports two forms of test suites.
3593 @section Simple Tests
3595 If the variable @code{TESTS} is defined, its value is taken to be a list
3596 of programs to run in order to do the testing. The programs can either
3597 be derived objects or source objects; the generated rule will look both
3598 in @code{srcdir} and @file{.}. Programs needing data files should look
3599 for them in @code{srcdir} (which is both an environment variable and a
3600 make variable) so they work when building in a separate directory
3601 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
3602 Manual}), and in particular for the @code{distcheck} target
3605 @cindex Exit status 77, special interpretation
3607 The number of failures will be printed at the end of the run. If a
3608 given test program exits with a status of 77, then its result is ignored
3609 in the final count. This feature allows non-portable tests to be
3610 ignored in environments where they don't make sense.
3612 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
3613 variables for the test run; the environment variable @code{srcdir} is
3614 set in the rule. If all your test programs are scripts, you can also
3615 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
3616 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
3618 @vindex TESTS_ENVIRONMENT
3620 @cindex Tests, expected failure
3621 @cindex Expected test failure
3623 You may define the variable @code{XFAIL_TESTS} to a list of tests
3624 (usually a subset of @code{TESTS}) that are expected to fail. This will
3625 reverse the result of those tests.
3628 Automake ensures that each program listed in @code{TESTS} is built
3629 before any tests are run; you can list both source and derived programs
3630 in @code{TESTS}. For instance, you might want to run a C program as a
3631 test. To do this you would list its name in @code{TESTS} and also in
3632 @code{check_PROGRAMS}, and then specify it as you would any other
3635 @section DejaGNU Tests
3637 If @uref{ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz,
3638 @samp{dejagnu}} appears in @code{AUTOMAKE_OPTIONS}, then a
3639 @code{dejagnu}-based test suite is assumed. The variable
3640 @code{DEJATOOL} is a list of names which are passed, one at a time, as
3641 the @code{--tool} argument to @code{runtest} invocations; it defaults to
3642 the name of the package.
3644 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
3645 @code{--srcdir} flags that are passed to dejagnu by default; this can be
3646 overridden if necessary.
3647 @vindex RUNTESTDEFAULTFLAGS
3649 The variables @code{EXPECT} and @code{RUNTEST} can
3650 also be overridden to provide project-specific values. For instance,
3651 you will need to do this if you are testing a compiler toolchain,
3652 because the default values do not take into account host and target
3659 The contents of the variable @code{RUNTESTFLAGS} are passed to the
3660 @code{runtest} invocation. This is considered a ``user variable''
3661 (@pxref{User Variables}). If you need to set @code{runtest} flags in
3662 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
3663 @vindex RUNTESTFLAGS
3664 @vindex AM_RUNTESTFLAGS
3665 @c FIXME xref dejagnu
3667 In either case, the testing is done via @samp{make check}.
3670 @node Options, Miscellaneous, Tests, Top
3671 @chapter Changing Automake's Behavior
3673 Various features of Automake can be controlled by options in the
3674 @file{Makefile.am}. Such options are listed in a special variable named
3675 @code{AUTOMAKE_OPTIONS}. Currently understood options are:
3676 @vindex AUTOMAKE_OPTIONS
3681 @itemx @code{foreign}
3682 @itemx @code{cygnus}
3683 @cindex Option, gnits
3685 @cindex Option, foreign
3686 @cindex Option, cygnus
3688 Set the strictness as appropriate. The @code{gnits} option also implies
3689 @code{readme-alpha} and @code{check-news}.
3691 @item @code{ansi2knr}
3692 @itemx @code{@var{path}/ansi2knr}
3693 @cindex Option, ansi2knr
3694 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
3695 path, the generated @file{Makefile.in} will look in the specified
3696 directory to find the @file{ansi2knr} program. The path should be a
3697 relative path to another directory in the same distribution (Automake
3698 currently does not check this).
3700 @item @code{check-news}
3701 @cindex Option, check-news
3702 Cause @code{make dist} to fail unless the current version number appears
3703 in the first few lines of the @file{NEWS} file.
3705 @item @code{dejagnu}
3706 @cindex Option, dejagnu
3707 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
3709 @item @code{dist-bzip2}
3710 @cindex Option, dist-bzip2
3711 Generate a @code{dist-bzip2} target as well as the ordinary @code{dist}
3712 target. This new target will create a bzip2 tar archive of the
3713 distribution. bzip2 archives are frequently smaller than even gzipped
3717 @item @code{dist-shar}
3718 @cindex Option, dist-shar
3719 Generate a @code{dist-shar} target as well as the ordinary @code{dist}
3720 target. This new target will create a shar archive of the
3724 @item @code{dist-zip}
3725 @cindex Option, dist-zip
3726 Generate a @code{dist-zip} target as well as the ordinary @code{dist}
3727 target. This new target will create a zip archive of the distribution.
3730 @item @code{dist-tarZ}
3731 @cindex Option, dist-tarZ
3732 Generate a @code{dist-tarZ} target as well as the ordinary @code{dist}
3733 target. This new target will create a compressed tar archive of the
3737 @item @code{no-dependencies}
3738 @cindex Option, no-dependencies
3739 This is similar to using @samp{--include-deps} on the command line, but
3740 is useful for those situations where you don't have the necessary bits
3741 to make automatic dependency tracking work @xref{Dependencies}. In this
3742 case the effect is to effectively disable automatic dependency tracking.
3744 @item @code{no-exeext}
3745 @cindex Option, no-exeext
3746 If your @file{Makefile.am} defines a target @samp{foo}, it will override
3747 a target named @samp{foo$(EXEEXT)}. This is necessary when
3748 @code{EXEEXT} is found to be empty. However, by default automake will
3749 generate an error for this use. The @code{no-exeext} option will
3750 disable this error. This is intended for use only where it is known in
3751 advance that the package will not be ported to Windows, or any other
3752 operating system using extensions on executables.
3754 @item @code{no-installinfo}
3755 @cindex Option, no-installinfo
3756 The generated @file{Makefile.in} will not cause info pages to be built
3757 or installed by default. However, @code{info} and @code{install-info}
3758 targets will still be available. This option is disallowed at
3759 @samp{GNU} strictness and above.
3761 @trindex install-info
3763 @item @code{no-installman}
3764 @cindex Option, no-installman
3765 The generated @file{Makefile.in} will not cause man pages to be
3766 installed by default. However, an @code{install-man} target will still
3767 be available for optional installation. This option is disallowed at
3768 @samp{GNU} strictness and above.
3769 @trindex install-man
3771 @item @code{nostdinc}
3772 @cindex Option, nostdinc
3773 This option can be used to disable the standard @samp{-I} options which
3774 are ordinarily automatically provided by Automake.
3776 @item @code{no-texinfo.tex}
3777 @cindex Option, no-texinfo
3778 Don't require @file{texinfo.tex}, even if there are texinfo files in
3781 @item @code{readme-alpha}
3782 @cindex Option, readme-alpha
3783 If this release is an alpha release, and the file @file{README-alpha}
3784 exists, then it will be added to the distribution. If this option is
3785 given, version numbers are expected to follow one of two forms. The
3786 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
3787 element is a number; the final period and number should be left off for
3788 non-alpha releases. The second form is
3789 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
3790 letter; it should be omitted for non-alpha releases.
3792 @item @code{subdir-objects}
3793 If this option is specified, then objects are placed into the
3794 subdirectory of the build directory corresponding to the subdirectory of
3795 the source file. For instance if the source file is
3796 @file{subdir/file.cxx}, then the output file would be
3797 @file{subdir/file.o}.
3800 @cindex Option, version
3801 A version number (e.g. @samp{0.30}) can be specified. If Automake is not
3802 newer than the version specified, creation of the @file{Makefile.in}
3806 Unrecognized options are diagnosed by @code{automake}.
3809 @node Miscellaneous, Include, Options, Top
3810 @chapter Miscellaneous Rules
3812 There are a few rules and variables that didn't fit anywhere else.
3815 * Tags:: Interfacing to etags and mkid
3816 * Suffixes:: Handling new file extensions
3817 * Multilibs:: Support for multilibbing.
3821 @node Tags, Suffixes, Miscellaneous, Miscellaneous
3822 @section Interfacing to @code{etags}
3824 @cindex TAGS support
3826 Automake will generate rules to generate @file{TAGS} files for use with
3827 GNU Emacs under some circumstances.
3829 If any C, C++ or Fortran 77 source code or headers are present, then
3830 @code{tags} and @code{TAGS} targets will be generated for the directory.
3833 At the topmost directory of a multi-directory package, a @code{tags}
3834 target file will be generated which, when run, will generate a
3835 @file{TAGS} file that includes by reference all @file{TAGS} files from
3838 The @code{tags} target will also be generated if the variable
3839 @code{ETAGS_ARGS} is defined. This variable is intended for use in
3840 directories which contain taggable source that @code{etags} does not
3844 Here is how Automake generates tags for its source, and for nodes in its
3848 ETAGS_ARGS = automake.in --lang=none \
3849 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
3852 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
3853 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
3854 are added directly to the dependencies for the @code{tags} target.
3855 @vindex TAGS_DEPENDENCIES
3857 Automake will also generate an @code{ID} target which will run
3858 @code{mkid} on the source. This is only supported on a
3859 directory-by-directory basis.
3862 Automake also supports the @uref{http://www.gnu.org/software/global/,
3863 GNU Global Tags program}. The @code{GTAGS} target runs Global Tags
3864 automatically and puts the result in the top build directory. The
3865 variable @code{GTAGS_ARGS} holds arguments which are passed to
3870 @node Suffixes, Multilibs, Tags, Miscellaneous
3871 @section Handling new file extensions
3873 @cindex Adding new SUFFIXES
3874 @cindex SUFFIXES, adding
3876 It is sometimes useful to introduce a new implicit rule to handle a file
3877 type that Automake does not know about. If this is done, you must
3878 notify GNU Make of the new suffixes. This can be done by putting a list
3879 of new suffixes in the @code{SUFFIXES} variable.
3882 For instance, suppose you had a compiler which could compile @samp{.foo}
3883 files to @samp{.o} files. Then you would add @samp{.foo} to your suffix
3890 Then you could directly use a @samp{.foo} file in a @samp{_SOURCES}
3891 variable and expect the correct results:
3895 doit_SOURCES = doit.foo
3898 Any given @code{SUFFIXES} go at the start of the generated suffixes
3899 list, followed by automake generated suffixes not already in the list.
3902 @node Multilibs, , Suffixes, Miscellaneous
3903 @section Support for Multilibs
3905 Automake has support for an obscure feature called multilibs. A
3906 @dfn{multilib} is a library which is built for multiple different ABIs
3907 at a single time; each time the library is built with a different target
3908 flag combination. This is only useful when the library is intended to
3909 be cross-compiled, and it is almost exclusively used for compiler
3912 The multilib support is still experimental. Only use it if you are
3913 familiar with multilibs and can debug problems you might encounter.
3916 @node Include, Conditionals, Miscellaneous, Top
3920 @cindex Including Makefile fragment
3921 @cindex Makefile fragment, including
3923 Automake supports an @code{include} directive which can be used to
3924 include other @file{Makefile} fragments when @code{automake} is run.
3925 Note that these fragments are read and interpreted by @code{automake},
3926 not by @code{make}. As with conditionals, @code{make} has no idea that
3927 @code{include} is in use.
3929 There are two forms of @code{include}:
3932 @item include $(srcdir)/file
3933 Include a fragment which is found relative to the current source
3936 @item include $(top_srcdir)/file
3937 Include a fragment which is found relative to the top source directory.
3940 Note that if a fragment is included inside a conditional, then the
3941 condition applies to the entire contents of that fragment.
3944 @node Conditionals, Gnits, Include, Top
3945 @chapter Conditionals
3947 @cindex Conditionals
3949 Automake supports a simple type of conditionals.
3951 @cvindex AM_CONDITIONAL
3952 Before using a conditional, you must define it by using
3953 @code{AM_CONDITIONAL} in the @code{configure.in} file (@pxref{Macros}).
3955 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
3956 The conditional name, @var{conditional}, should be a simple string
3957 starting with a letter and containing only letters, digits, and
3958 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
3959 which are reserved by Automake.
3961 The shell @var{condition} (suitable for use in a shell @code{if}
3962 statement) is evaluated when @code{configure} is run.
3965 @cindex --enable-debug, example
3966 @cindex Example conditional --enable-debug
3967 @cindex Conditional example, --enable-debug
3969 Conditionals typically depend upon options which the user provides to
3970 the @code{configure} script. Here is an example of how to write a
3971 conditional which is true if the user uses the @samp{--enable-debug}
3975 AC_ARG_ENABLE(debug,
3976 [ --enable-debug Turn on debugging],
3977 [case "$@{enableval@}" in
3980 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
3981 esac],[debug=false])
3982 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
3985 Here is an example of how to use that conditional in @file{Makefile.am}:
3997 noinst_PROGRAMS = $(DBG)
4000 This trivial example could also be handled using EXTRA_PROGRAMS
4001 (@pxref{A Program}).
4003 You may only test a single variable in an @code{if} statement, possibly
4004 negated using @samp{!}. The @code{else} statement may be omitted.
4005 Conditionals may be nested to any depth. You may specify an argument to
4006 @code{else} in which case it must be the negation of the condition used
4007 for the current @code{if}. Similarly you may specify the condition
4008 which is closed by an @code{end}:
4019 Unbalanced conditions are errors.
4021 Note that conditionals in Automake are not the same as conditionals in
4022 GNU Make. Automake conditionals are checked at configure time by the
4023 @file{configure} script, and affect the translation from
4024 @file{Makefile.in} to @file{Makefile}. They are based on options passed
4025 to @file{configure} and on results that @file{configure} has discovered
4026 about the host system. GNU Make conditionals are checked at @code{make}
4027 time, and are based on variables passed to the make program or defined
4028 in the @file{Makefile}.
4030 Automake conditionals will work with any make program.
4033 @node Gnits, Cygnus, Conditionals, Top
4034 @chapter The effect of @code{--gnu} and @code{--gnits}
4036 @cindex --gnu, required files
4037 @cindex --gnu, complete description
4039 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
4040 variable) causes @code{automake} to check the following:
4044 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
4045 @file{AUTHORS}, and @file{ChangeLog} are required at the topmost
4046 directory of the package.
4049 The options @samp{no-installman} and @samp{no-installinfo} are
4053 Note that this option will be extended in the future to do even more
4054 checking; it is advisable to be familiar with the precise requirements
4055 of the GNU standards. Also, @samp{--gnu} can require certain
4056 non-standard GNU programs to exist for use by various maintainer-only
4057 targets; for instance in the future @code{pathchk} might be required for
4060 @cindex --gnits, complete description
4062 The @samp{--gnits} option does everything that @samp{--gnu} does, and
4063 checks the following as well:
4067 @samp{make dist} will check to make sure the @file{NEWS} file has been
4068 updated to the current version.
4071 @samp{VERSION} is checked to make sure its format complies with Gnits
4073 @c FIXME xref when standards are finished
4076 @cindex README-alpha
4077 If @samp{VERSION} indicates that this is an alpha release, and the file
4078 @file{README-alpha} appears in the topmost directory of a package, then
4079 it is included in the distribution. This is done in @samp{--gnits}
4080 mode, and no other, because this mode is the only one where version
4081 number formats are constrained, and hence the only mode where Automake
4082 can automatically determine whether @file{README-alpha} should be
4086 The file @file{THANKS} is required.
4090 @node Cygnus, Extending, Gnits, Top
4091 @chapter The effect of @code{--cygnus}
4093 @cindex Cygnus strictness
4095 Some packages, notably GNU GCC and GNU gdb, have a build environment
4096 originally written at Cygnus Support (subsequently renamed Cygnus
4097 Solutions, and then later purchased by Red Hat). Packages with this
4098 ancestry are sometimes referred to as ``Cygnus'' trees.
4100 A Cygnus tree has slightly different rules for how a @file{Makefile.in}
4101 is to be constructed. Passing @samp{--cygnus} to @code{automake} will
4102 cause any generated @file{Makefile.in} to comply with Cygnus rules.
4104 Here are the precise effects of @samp{--cygnus}:
4108 Info files are always created in the build directory, and not in the
4112 @file{texinfo.tex} is not required if a Texinfo source file is
4113 specified. The assumption is that the file will be supplied, but in a
4114 place that Automake cannot find. This assumption is an artifact of how
4115 Cygnus packages are typically bundled.
4118 @samp{make dist} is not supported, and the rules for it are not
4119 generated. Cygnus-style trees use their own distribution mechanism.
4122 Certain tools will be searched for in the build tree as well as in the
4123 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
4124 @code{makeinfo} and @code{texi2dvi}.
4127 @code{--foreign} is implied.
4130 The options @samp{no-installinfo} and @samp{no-dependencies} are
4134 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
4138 The @code{check} target doesn't depend on @code{all}.
4141 GNU maintainers are advised to use @samp{gnu} strictness in preference
4142 to the special Cygnus mode. Some day, perhaps, the differences between
4143 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
4144 more standards compliant). At that time the special Cygnus mode will be
4148 @node Extending, Distributing, Cygnus, Top
4149 @chapter When Automake Isn't Enough
4151 Automake's implicit copying semantics means that many problems can be
4152 worked around by simply adding some @code{make} targets and rules to
4153 @file{Makefile.in}. Automake will ignore these additions.
4155 @cindex -local targets
4156 @cindex local targets
4158 There are some caveats to doing this. Although you can overload a
4159 target already used by Automake, it is often inadvisable, particularly
4160 in the topmost directory of a package with subdirectories. However,
4161 various useful targets have a @samp{-local} version you can specify in
4162 your @file{Makefile.in}. Automake will supplement the standard target
4163 with these user-supplied targets.
4168 @trindex check-local
4169 @trindex install-data-local
4170 @trindex install-exec-local
4171 @trindex uninstall-local
4172 @trindex mostlyclean-local
4173 @trindex clean-local
4174 @trindex distclean-local
4176 The targets that support a local version are @code{all}, @code{info},
4177 @code{dvi}, @code{check}, @code{install-data}, @code{install-exec},
4178 @code{uninstall}, and the various @code{clean} targets
4179 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
4180 @code{maintainer-clean}). Note that there are no
4181 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
4182 use @code{uninstall-local}. It doesn't make sense to uninstall just
4183 data or just executables.
4188 @trindex install-data
4189 @trindex install-exec
4192 For instance, here is one way to install a file in @file{/etc}:
4196 $(INSTALL_DATA) $(srcdir)/afile /etc/afile
4199 @cindex -hook targets
4200 @cindex hook targets
4202 Some targets also have a way to run another target, called a @dfn{hook},
4203 after their work is done. The hook is named after the principal target,
4204 with @samp{-hook} appended. The targets allowing hooks are
4205 @code{install-data}, @code{install-exec}, @code{dist}, and
4207 @trindex install-data-hook
4208 @trindex install-exec-hook
4211 For instance, here is how to create a hard link to an installed program:
4215 ln $(bindir)/program $(bindir)/proglink
4218 @c FIXME should include discussion of variables you can use in these
4222 @node Distributing, Macro and Variable Index, Extending, Top
4223 @chapter Distributing @file{Makefile.in}s
4225 Automake places no restrictions on the distribution of the resulting
4226 @file{Makefile.in}s. We still encourage software authors to distribute
4227 their work under terms like those of the GPL, but doing so is not
4228 required to use Automake.
4230 Some of the files that can be automatically installed via the
4231 @code{--add-missing} switch do fall under the GPL. However, these also
4232 have a special exception allowing you to distribute them with your
4233 package, regardless of the licensing you choose.
4237 @node Macro and Variable Index, General Index, Distributing, Top
4238 @unnumbered Macro and Variable Index
4244 @node General Index, , Macro and Variable Index, Top
4245 @unnumbered General Index