* configure:: Scanning configure.ac or configure.in
* Directories:: Declaring subdirectories
* Programs:: Building programs and libraries
-* Other objects:: Other derived objects
+* Other Objects:: Other derived objects
* Other GNU Tools:: Other GNU Tools
* Documentation:: Building documentation
* Install:: What gets installed
* Strictness:: Standards conformance checking
* Uniform:: The Uniform Naming Scheme
* Canonicalization:: How derived variables are named
-* Length limitations:: Staying below the command line length limit
+* Length Limitations:: Staying below the command line length limit
* User Variables:: Variables reserved for the user
* Auxiliary Programs:: Programs automake might require
Auto-generating aclocal.m4
-* aclocal options:: Options supported by aclocal
-* Macro search path:: How aclocal finds .m4 files
+* aclocal Options:: Options supported by aclocal
+* Macro Search Path:: How aclocal finds .m4 files
* Extending aclocal:: Writing your own aclocal macros
* Local Macros:: Organizing local macros
* Serials:: Serial lines in Autoconf macros
Autoconf macros supplied with Automake
-* Public macros:: Macros that you can use.
-* Obsolete macros:: Macros that you should stop using.
-* Private macros:: Macros that you should not use.
+* Public Macros:: Macros that you can use.
+* Obsolete Macros:: Macros that you should stop using.
+* Private Macros:: Macros that you should not use.
Directories
* Alternative:: Subdirectories without recursion
* Subpackages:: Nesting packages
+Conditional Subdirectories
+
+* SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
+* Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
+* Subdirectories with AC_SUBST:: Another way for conditional recursion
+* Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
+
Building Programs and Libraries
* A Program:: Building a program
library builds
* Default _SOURCES:: Default source files
* LIBOBJS:: Special handling for LIBOBJS and ALLOCA
-* Program variables:: Variables used when building a program
+* Program Variables:: Variables used when building a program
* Yacc and Lex:: Yacc and Lex support
* C++ Support:: Compiling C++ sources
* Objective C Support:: Compiling Objective C sources
* Data:: Architecture-independent data files
* Sources:: Derived sources
-Built sources
+Built Sources
-* Built sources example:: Several ways to handle built sources.
+* Built Sources Example:: Several ways to handle built sources.
Other GNU Tools
Building documentation
* Texinfo:: Texinfo
-* Man pages:: Man pages
+* Man Pages:: Man pages
+
+Installation
+
+* Basics of Installation:: What gets installed where
+* The Two Parts of Install:: Installing data and programs separately
+* Extending Installation:: Adding your own rules for installation
+* Staged Installs:: Installation in a temporary location
+* Install Rules for the User:: Useful additional rules
+
+Distribution
+
+* Basics of Distribution:: Files distributed by default
+* Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
+* The dist Hook:: A target for last-minute distribution changes
+* Checking the Distribution:: @samp{make distcheck} explained
+* The Types of Distributions:: A variety of formats and compression methods
+
+Support for Test Suites
+
+* Simple Tests:: Listing programs and scripts in @code{TESTS}
+* Simple Tests using parallel-tests:: More powerful test driver
+* DejaGnu Tests:: Interfacing with the external testing framework
+* Install Tests:: Running tests on installed packages
Miscellaneous Rules
* Suffixes:: Handling new file extensions
* Multilibs:: Support for multilibs.
+Conditionals
+
+* Usage of Conditionals:: Declaring conditional content
+* Limits of Conditionals:: Enclosing complete statements
+
When Automake Isn't Enough
* Extending:: Adding new rules or overriding existing ones.
* CVS:: CVS and generated files
* maintainer-mode:: missing and AM_MAINTAINER_MODE
* wildcards:: Why doesn't Automake support wildcards?
-* limitations on file names:: Limitations on source and installed file names
+* Limitations on File Names:: Limitations on source and installed file names
* distcleancheck:: Files left in build directory after distclean
* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
-* renamed objects:: Why are object files sometimes renamed?
+* Renamed Objects:: Why are object files sometimes renamed?
* Per-Object Flags:: How to simulate per-object flags?
* Multiple Outputs:: Writing rules for tools with many output files
* Hard-Coded Install Paths:: Installing to Hard-Coded Locations
* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
* Releases:: Statistics about Automake Releases
+Dependency Tracking Evolution
+
+* First Take on Dependencies:: Precomputed dependency tracking
+* Dependencies As Side Effects:: Update at developer compile time
+* Dependencies for the User:: Update at user compile time
+* Techniques for Dependencies:: Alternative approaches
+* Recommendations for Tool Writers:: What tool writers can do to help
+* Future Directions for Dependencies:: Languages Automake does not know
+
Copying This Manual
* GNU Free Documentation License:: License for copying this manual
variables based on @var{exec-prefix} designate architecture-dependent
directories whose files will be installed by @code{make install-exec}.
The others designate architecture-independent directories and will
-serve files installed by @code{make install-data}. @xref{Install},
-for more details.
+serve files installed by @code{make install-data}. @xref{The Two Parts
+of Install}, for more details.
Here is how we could revisit our two-host installation example,
assuming that (1) we want to install the package directly in
@cindex Programs, renaming during installation
The GNU Build System provides means to automatically rename
-executables and manpages before they are installed (@pxref{Man pages}).
+executables and manpages before they are installed (@pxref{Man Pages}).
This is especially convenient
when installing a GNU package on a system that already has a
proprietary implementation you do not want to overwrite. For instance,
working).
@xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
-@code{make distcheck}. @xref{Dist}, for more information about
-@code{distcheck}.
+@code{make distcheck}. @xref{Checking the Distribution}, for more
+information about @code{distcheck}.
@node Dependency Tracking
@subsection Automatic Dependency Tracking
* Strictness:: Standards conformance checking
* Uniform:: The Uniform Naming Scheme
* Canonicalization:: How derived variables are named
-* Length limitations:: Staying below the command line length limit
+* Length Limitations:: Staying below the command line length limit
* User Variables:: Variables reserved for the user
* Auxiliary Programs:: Programs automake might require
@end menu
aspects of @command{automake}'s behavior. The currently defined prefixes
are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
These prefixes are explained later (@pxref{Program and Library Variables})
-(@pxref{Man pages}).
+(@pxref{Man Pages}).
-@node Length limitations
+@node Length Limitations
@section Staying below the command line length limit
@cindex command line length limit
@noindent
and will cause Automake to treat the two lists separately during
-@code{make install}. See @ref{Install} for choosing directory names
-that will keep the ordering of the two parts of installation
-(@pxref{Two-Part Install}). Note that @code{make dist} may still
-only work on a host with a higher length limit in this example.
+@code{make install}. See @ref{The Two Parts of Install} for choosing
+directory names that will keep the ordering of the two parts of
+installation Note that @code{make dist} may still only work on a host
+with a higher length limit in this example.
Automake itself employs a couple of strategies to avoid long command
lines. For example, when @samp{$@{srcdir@}/} is prepended to file
This macro allows @code{automake} to detect subsequent access within
@file{configure.ac} to a conditional previously introduced with
@code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
-(@pxref{Conditionals}).
+(@pxref{Usage of Conditionals}).
@item AM_GNU_GETTEXT
This macro is required for packages that use GNU gettext
macros (@pxref{Local Macros}).
At startup, @command{aclocal} scans all the @file{.m4} files it can
-find, looking for macro definitions (@pxref{Macro search path}). Then
+find, looking for macro definitions (@pxref{Macro Search Path}). Then
it scans @file{configure.ac}. Any mention of one of the macros found
in the first step causes that macro, and any macros it in turn
requires, to be put into @file{aclocal.m4}.
overridden using the @env{AUTOM4TE} environment variable.
@menu
-* aclocal options:: Options supported by aclocal
-* Macro search path:: How aclocal finds .m4 files
+* aclocal Options:: Options supported by aclocal
+* Macro Search Path:: How aclocal finds .m4 files
* Extending aclocal:: Writing your own aclocal macros
* Local Macros:: Organizing local macros
* Serials:: Serial lines in Autoconf macros
* Future of aclocal:: aclocal's scheduled death
@end menu
-@node aclocal options
-@subsection aclocal options
+@node aclocal Options
+@subsection aclocal Options
@cindex @command{aclocal}, Options
@cindex Options, @command{aclocal}
@end table
-@node Macro search path
-@subsection Macro search path
+@node Macro Search Path
+@subsection Macro Search Path
@cindex Macro search path
@cindex @command{aclocal} search path
@file{@@datadir@@/aclocal/}, which typically
expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
value of @var{acdir}, use the @option{--print-ac-dir} option
-(@pxref{aclocal options}).
+(@pxref{aclocal Options}).
@end table
As an example, suppose that @command{automake-1.6.2} was configured with
@item @file{/usr/local/share/aclocal/}
@end enumerate
-As explained in (@pxref{aclocal options}), there are several options that
+As explained in (@pxref{aclocal Options}), there are several options that
can be used to change or extend this search path.
-@subsubsection Modifying the macro search path: @option{--acdir}
+@subsubheading Modifying the Macro Search Path: @option{--acdir}
The most erroneous option to modify the search path is
@option{--acdir=@var{dir}}, which changes default directory and
This option, @option{--acdir}, is intended for use by the internal
Automake test suite only; it is not ordinarily needed by end-users.
-@subsubsection Modifying the macro search path: @samp{-I @var{dir}}
+@subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
Any extra directories specified using @option{-I} options
-(@pxref{aclocal options}) are @emph{prepended} to this search list. Thus,
+(@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
@samp{aclocal -I /foo -I /bar} results in the following search path:
@enumerate
@item @var{acdir}
@end enumerate
-@subsubsection Modifying the macro search path: @file{dirlist}
+@subsubheading Modifying the Macro Search Path: @file{dirlist}
@cindex @file{dirlist}
There is a third mechanism for customizing the search path. If a
When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
that @code{m4_include}s any file from @file{m4/} that defines a
required macro. Macros not found locally will still be searched in
-system-wide directories, as explained in @ref{Macro search path}.
+system-wide directories, as explained in @ref{Macro Search Path}.
Custom macros should be distributed for the same reason that
@file{configure.ac} is: so that other people have all the sources of
@noindent
Because both files have the same serial number, @command{aclocal} uses
-the first it found in its search path order (@pxref{Macro search
-path}). @command{aclocal} therefore ignores
+the first it found in its search path order (@pxref{Macro Search
+Path}). @command{aclocal} therefore ignores
@file{/usr/share/aclocal/thirdparty.m4} and outputs an
@file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
@command{aclocal} in @file{aclocal.m4}.
@menu
-* Public macros:: Macros that you can use.
-* Obsolete macros:: Macros that you should stop using.
-* Private macros:: Macros that you should not use.
+* Public Macros:: Macros that you can use.
+* Obsolete Macros:: Macros that you should stop using.
+* Private Macros:: Macros that you should not use.
@end menu
@c consider generating the following subsections automatically from m4 files.
-@node Public macros
-@subsection Public macros
+@node Public Macros
+@subsection Public Macros
@table @code
@end table
-@node Obsolete macros
-@subsection Obsolete macros
+@node Obsolete Macros
+@subsection Obsolete Macros
@cindex obsolete macros
@cindex autoupdate
@end table
-@node Private macros
-@subsection Private macros
+@node Private Macros
+@subsection Private Macros
The following macros are private macros you should not call directly.
They are called by the other public macros when appropriate. Do not
conditionals is the preferred solution. Before we illustrate these
two possibilities, let's introduce @code{DIST_SUBDIRS}.
+@menu
+* SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
+* Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
+* Subdirectories with AC_SUBST:: Another way for conditional recursion
+* Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
+@end menu
+
+@node SUBDIRS vs DIST_SUBDIRS
@subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
@cindex @code{DIST_SUBDIRS}, explained
does not know the possible values of these variables. In this case
@code{DIST_SUBDIRS} needs to be defined manually.
-@subsection Conditional subdirectories with @code{AM_CONDITIONAL}
+@node Subdirectories with AM_CONDITIONAL
+@subsection Subdirectories with @code{AM_CONDITIONAL}
@cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
@cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
automatically because it knows that @code{MAYBE_OPT} can contain
@samp{opt} in some condition.
-@subsection Conditional Subdirectories with @code{AC_SUBST}
+@node Subdirectories with AC_SUBST
+@subsection Subdirectories with @code{AC_SUBST}
@cindex @code{SUBDIRS} and @code{AC_SUBST}
@cindex @code{AC_SUBST} and @code{SUBDIRS}
values of @code{MAYBE_OPT} are, it is necessary to define
@code{DIST_SUBDIRS}.
-@subsection Non-configured Subdirectories
+@node Unconfigured Subdirectories
+@subsection Unconfigured Subdirectories
@cindex Subdirectories, configured conditionally
The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
@end itemize
@end cartouche
-In order to prevent recursion in some non-configured directory you
+In order to prevent recursion in some unconfigured directory you
must therefore ensure that this directory does not appear in
@code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
@code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
distribute these directories).
@cindex Subdirectories, not distributed
-In few packages, non-configured directories are not even expected to
+In few packages, unconfigured directories are not even expected to
be distributed. Although these packages do not require the
aforementioned extra arrangements, there is another pitfall. If the
name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
@vindex nodist_
@samp{nobase_} should be specified first when used in conjunction with
-either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
+either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
+Control}). For instance:
@example
nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
library builds
* Default _SOURCES:: Default source files
* LIBOBJS:: Special handling for LIBOBJS and ALLOCA
-* Program variables:: Variables used when building a program
+* Program Variables:: Variables used when building a program
* Yacc and Lex:: Yacc and Lex support
* C++ Support:: Compiling C++ sources
* Objective C Support:: Compiling Objective C sources
to use configure substitutions in @code{_LDADD} variables, the other is
to use an Automake conditional.
-@subsubsection Conditional compilation using @code{_LDADD} substitutions
+@subsubheading Conditional Compilation using @code{_LDADD} Substitutions
@cindex @code{EXTRA_prog_SOURCES}, defined
both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
built and linked in.
-@subsubsection Conditional compilation using Automake conditionals
+@subsubheading Conditional Compilation using Automake Conditionals
An often simpler way to compile source files conditionally is to use
Automake conditionals. For instance, you could use this
achieve conditional compilation of programs are the same you can use
to compile source files conditionally: substitutions or conditionals.
-@subsubsection Conditional programs using @command{configure} substitutions
+@subsubheading Conditional Programs using @command{configure} Substitutions
@vindex EXTRA_PROGRAMS
@cindex @code{EXTRA_PROGRAMS}, defined
appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
['mt$@{EXEEXT@}'])}.
-@subsubsection Conditional programs using Automake conditionals
+@subsubheading Conditional Programs using Automake Conditionals
You can also use Automake conditionals (@pxref{Conditionals}) to
select programs to be built. In this case you don't have to worry
@node Libtool Issues
@subsection Common Issues Related to Libtool's Use
-@subsubsection @samp{required file `./ltmain.sh' not found}
+@menu
+* Error required file ltmain.sh not found:: The need to run libtoolize
+* Objects created both with libtool and without:: Avoid a specific build race
+@end menu
+
+@node Error required file ltmain.sh not found
+@subsubsection Error: @samp{required file `./ltmain.sh' not found}
@cindex @file{ltmain.sh} not found
@cindex @command{libtoolize}, no longer run by @command{automake}
@cindex @command{libtoolize} and @command{autoreconf}
a call to @command{autoreconf} should also free you from any similar
incompatible change in the future.
+@node Objects created both with libtool and without
@subsubsection Objects @samp{created with both libtool and without}
Sometimes, the same source file is used both to build a libtool
@end example
A workaround for this issue is to ensure that these two objects get
-different basenames. As explained in @ref{renamed objects}, this
+different basenames. As explained in @ref{Renamed Objects}, this
happens automatically when per-targets flags are used.
@example
like @file{sample.c} will be compiled to produce @file{sample.o}.
However, if the program's @code{_CFLAGS} variable is set, then the
object file will be named, for instance, @file{maude-sample.o}. (See
-also @ref{renamed objects}.) The use of per-target compilation flags
+also @ref{Renamed Objects}.) The use of per-target compilation flags
with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
from @file{configure.ac}.
autoconf, The Autoconf Manual}.
-@node Program variables
+@node Program Variables
@section Variables used when building a program
Occasionally it is useful to know which @file{Makefile} variables
Any package including Unified Parallel C code must define the output
variable @code{UPC} in @file{configure.ac}; the simplest way to do
-this is to use the @code{AM_PROG_UPC} macro (@pxref{Public macros}).
+this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
A few additional variables are defined when a Unified Parallel C
source file is seen:
The targets Automake generates are likewise given the @samp{$(EXEEXT)}
extension.
-The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Tests}) are also
+The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests}) are also
rewritten if they contain filenames that have been declared as programs
in the same @file{Makefile}. (This is mostly useful when some programs
from @code{check_PROGRAMS} are listed in @code{TESTS}.)
the @option{no-exeext} option, this use will give a diagnostic.
-@node Other objects
+@node Other Objects
@chapter Other Derived Objects
Automake can handle derived objects that are not C programs. Sometimes
Such scripts for which a build rule has been supplied need to be
deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
sources have to be distributed, usually with @code{EXTRA_DIST}
-(@pxref{Dist}).
+(@pxref{Basics of Distribution}).
Another common way to build scripts is to process them from
@file{configure} with @code{AC_CONFIG_FILES}. In this situation
@node Sources
-@section Built sources
+@section Built Sources
Because Automake's automatic dependency tracking works as a side-effect
of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
on a toy example.
@menu
-* Built sources example:: Several ways to handle built sources.
+* Built Sources Example:: Several ways to handle built sources.
@end menu
-@node Built sources example
-@subsection Built sources example
+@node Built Sources Example
+@subsection Built Sources Example
Suppose that @file{foo.c} includes @file{bindir.h}, which is
installation-dependent and not distributed: it needs to be built. Here
exhaustive listing of all ways to handle built sources, but it will give
you a few ideas if you encounter this issue.
-@unnumberedsubsec First try
+@subsubheading First Try
This first implementation will illustrate the bootstrap issue mentioned
in the previous section (@pxref{Sources}).
(@pxref{Tags}). In other words, it does not help our present problem,
and the build would fail identically without it.
-@unnumberedsubsec Using @code{BUILT_SOURCES}
+@subsubheading Using @code{BUILT_SOURCES}
A solution is to require @file{bindir.h} to be built before anything
else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
make: *** [foo.o] Error 1
@end example
-@unnumberedsubsec Recording dependencies manually
+@subsubheading Recording Dependencies manually
Usually people are happy enough with @code{BUILT_SOURCES} because they
never build targets such as @samp{make foo} before @samp{make all}, as
target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
Always check the generated @file{Makefile.in} if you do this.
-@unnumberedsubsec Build @file{bindir.h} from @file{configure}
+@subsubheading Build @file{bindir.h} from @file{configure}
It's possible to define this preprocessor macro from @file{configure},
either in @file{config.h} (@pxref{Defining Directories, , Defining
@file{configure}, especially when these sources are generated by a tool
that needs to be built first.
-@unnumberedsubsec Build @file{bindir.c}, not @file{bindir.h}.
+@subsubheading Build @file{bindir.c}, not @file{bindir.h}.
Another attractive idea is to define @code{bindir} as a variable or
function exported from @file{bindir.o}, and build @file{bindir.c}
always dependent on @file{bindir.c}, so @file{bindir.c} will get built
first.
-@unnumberedsubsec Which is best?
+@subsubheading Which is best?
There is no panacea, of course. Each solution has its merits and
drawbacks.
@menu
* Texinfo:: Texinfo
-* Man pages:: Man pages
+* Man Pages:: Man pages
@end menu
@end vtable
-@node Man pages
-@section Man pages
+@node Man Pages
+@section Man Pages
@cindex @code{_MANS} primary, defined
@cindex @code{MANS} primary, defined
@cindex @code{nodist_} and @code{notrans_}
@samp{notrans_} must be specified first when used in conjunction with
-either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
+either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
+Control}). For instance:
@example
notrans_dist_man3_MANS = bar.3
@cindex Installation support
@cindex @samp{make install} support
-@section Basics of installation
-
Naturally, Automake handles the details of actually installing your
program once it has been built. All files named by the various
primaries are automatically installed in the appropriate places when the
user runs @samp{make install}.
+@menu
+* Basics of Installation:: What gets installed where
+* The Two Parts of Install:: Installing data and programs separately
+* Extending Installation:: Adding your own rules for installation
+* Staged Installs:: Installation in a temporary location
+* Install Rules for the User:: Useful additional rules
+@end menu
+
+@node Basics of Installation
+@section Basics of Installation
+
A file named in a primary is installed by copying the built file into
the appropriate directory. The base name of the file is used when
installing.
in @samp{$(includedir)/sys}.
For most file types, Automake will install multiple files at once, while
-avoiding command line length issues (@pxref{Length limitations}). Since
+avoiding command line length issues (@pxref{Length Limitations}). Since
some @command{install} programs will not install the same file twice in
one invocation, you may need to ensure that file lists are unique within
one variable such as @samp{nobase_include_HEADERS} above.
file types (library dependencies are an exception here).
-@section The two parts of install
+@node The Two Parts of Install
+@section The Two Parts of Install
Automake generates separate @code{install-data} and @code{install-exec}
rules, in case the installer is installing on multiple machines that
@code{install-exec}. All other user-defined prefixes are installed by
@code{install-data}.
-@section Extending installation
+@node Extending Installation
+@section Extending Installation
It is possible to extend this mechanism by defining an
@code{install-exec-local} or @code{install-data-local} rule. If these
using an install hook. @xref{Extending}, for some examples.
@cindex Install hook
-@section Staged installs
+@node Staged Installs
+@section Staged Installs
@vindex DESTDIR
Automake generates support for the @code{DESTDIR} variable in all
@xref{Makefile Conventions, , , standards, The GNU Coding Standards},
for another usage example.
-@section Rules for the user
+@node Install Rules for the User
+@section Install Rules for the User
Automake also generates rules for targets @code{uninstall},
@code{installdirs}, and @code{install-strip}.
@node Dist
@chapter What Goes in a Distribution
-@section Basics of distribution
+@menu
+* Basics of Distribution:: Files distributed by default
+* Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
+* The dist Hook:: A target for last-minute distribution changes
+* Checking the Distribution:: @samp{make distcheck} explained
+* The Types of Distributions:: A variety of formats and compression methods
+@end menu
+
+@node Basics of Distribution
+@section Basics of Distribution
@cindex @samp{make dist}
(@pxref{Conditional Subdirectories}).
-@section Fine-grained distribution control
+@node Fine-grained Distribution Control
+@section Fine-grained Distribution Control
@vindex dist_
@vindex nodist_
nodist_foo_SOURCES = do-not-distribute.c
@end example
-@section The dist hook
+@node The dist Hook
+@section The dist Hook
@trindex dist-hook
@samp{$(top_distdir)} are relative to the package where @samp{make
dist} was run, not to any sub-packages involved.
-@section Checking the distribution
+@node Checking the Distribution
+@section Checking the Distribution
@cindex @samp{make distcheck}
@cindex @samp{make distcleancheck}
@@:
@end example
-@section The types of distributions
+@node The Types of Distributions
+@section The Types of Distributions
Automake generates rules to provide archives of the project for
distributions in various formats. Their targets are:
Automake supports three forms of test suites, the first two of which
are very similar.
+@menu
+* Simple Tests:: Listing programs and scripts in @code{TESTS}
+* Simple Tests using parallel-tests:: More powerful test driver
+* DejaGnu Tests:: Interfacing with the external testing framework
+* Install Tests:: Running tests on installed packages
+@end menu
+
+@node Simple Tests
@section Simple Tests
If the variable @code{TESTS} is defined, its value is taken to be a
(which is both an environment variable and a make variable) so they
work when building in a separate directory (@pxref{Build Directories,
, Build Directories , autoconf, The Autoconf Manual}), and in
-particular for the @code{distcheck} rule (@pxref{Dist}).
+particular for the @code{distcheck} rule (@pxref{Checking the
+Distribution}).
For each of the @code{TESTS}, the result of execution is printed along
with the test name, where @code{PASS} denotes a successful test,
@code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
-@section Simple tests using @samp{parallel-tests}
+@node Simple Tests using parallel-tests
+@section Simple Tests using @samp{parallel-tests}
@cindex @option{parallel-tests}, Using
The option @option{parallel-tests} (@pxref{Options}) enables a test
-suite driver that is mostly compatible to the simple test driver
-described above, but provides a few more features and slightly different
+suite driver that is mostly compatible to the simple test driver described
+in the previous section, but provides a few more features and slightly different
semantics. It features concurrent execution of tests with @code{make -j},
allows to specify inter-test dependencies, lazy reruns of tests that
have not completed in a prior run, summary and verbose output in
or work around the issue with inference rules to generate the tests.
+@node DejaGnu Tests
@section DejaGnu Tests
If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
In either case, the testing is done via @samp{make check}.
+@node Install Tests
@section Install Tests
The @code{installcheck} target is available to the user as a way to
@item @option{color-tests}
@cindex Option, @option{color-tests}
@opindex color-tests
-Cause output of the simple test suite (@pxref{Tests}) to be
+Cause output of the simple test suite (@pxref{Simple Tests}) to be
colorized on capable terminals.
@item @option{dejagnu}
@cindex Option, @option{dejagnu}
@opindex dejagnu
-Cause @command{dejagnu}-specific rules to be generated. @xref{Tests}.
+Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
@item @option{dist-bzip2}
@cindex Option, @option{dist-bzip2}
@cindex Option, @option{parallel-tests}
@opindex parallel-tests
Enable test suite driver for @code{TESTS} that can run tests in parallel
-(@pxref{Tests}, for more information).
+(@pxref{Simple Tests using parallel-tests}, for more information).
@item @option{readme-alpha}
@cindex Option, @option{readme-alpha}
Automake supports a simple type of conditionals.
-@unnumberedsec Usage
+These conditionals are not the same as conditionals in
+GNU Make. Automake conditionals are checked at configure time by the
+@file{configure} script, and affect the translation from
+@file{Makefile.in} to @file{Makefile}. They are based on options passed
+to @file{configure} and on results that @file{configure} has discovered
+about the host system. GNU Make conditionals are checked at @command{make}
+time, and are based on variables passed to the make program or defined
+in the @file{Makefile}.
+
+Automake conditionals will work with any make program.
+
+@menu
+* Usage of Conditionals:: Declaring conditional content
+* Limits of Conditionals:: Enclosing complete statements
+@end menu
+
+@node Usage of Conditionals
+@section Usage of Conditionals
@acindex AM_CONDITIONAL
Before using a conditional, you must define it by using
[AC_CONFIG_FILES([wrapper:wrapper.in])])
@end example
-@unnumberedsec Portability
-
-Note that conditionals in Automake are not the same as conditionals in
-GNU Make. Automake conditionals are checked at configure time by the
-@file{configure} script, and affect the translation from
-@file{Makefile.in} to @file{Makefile}. They are based on options passed
-to @file{configure} and on results that @file{configure} has discovered
-about the host system. GNU Make conditionals are checked at @command{make}
-time, and are based on variables passed to the make program or defined
-in the @file{Makefile}.
-
-Automake conditionals will work with any make program.
-
-@unnumberedsec Limits
+@node Limits of Conditionals
+@section Limits of Conditionals
Conditionals should enclose complete statements like variables or
rules definitions. Automake cannot deal with conditionals used inside
AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
@end example
-@noindent or
+@noindent
+or
@example
AM_CPPFLAGS = -DFEATURE_A
AM_CPPFLAGS += -DFEATURE_B
@end example
+More details and examples of conditionals are described alongside
+various Automake features in this manual (@pxref{Conditional
+Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
+Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
+Libtool Sources}).
+
@node Gnits
@chapter The effect of @option{--gnu} and @option{--gnits}
When writing @code{install-exec-hook} or @code{install-data-hook},
please bear in mind that the exec/data distinction is based on the
-installation directory, not on the primary used (@pxref{Install}). So
-a @code{foo_SCRIPTS} will be installed by @code{install-data}, and a
-@code{barexec_SCRIPTS} will be installed by @code{install-exec}. You
-should define your hooks consequently.
+installation directory, not on the primary used (@pxref{The Two Parts of
+Install}). So a @code{foo_SCRIPTS} will be installed by
+@code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
+@code{install-exec}. You should define your hooks consequently.
@c FIXME should include discussion of variables you can use in these
@c rules
@option{no-dist} option (@pxref{Options}) is used.
The variables @samp{$(top_distdir)} and @samp{$(distdir)}
-(@pxref{Dist}) will be passed from the outer package to the subpackage
+(@pxref{The dist Hook}) will be passed from the outer package to the subpackage
when the @code{distdir} target is invoked. These two variables have
been adjusted for the directory that is being recursed into, so they
are ready to use.
* CVS:: CVS and generated files
* maintainer-mode:: missing and AM_MAINTAINER_MODE
* wildcards:: Why doesn't Automake support wildcards?
-* limitations on file names:: Limitations on source and installed file names
+* Limitations on File Names:: Limitations on source and installed file names
* distcleancheck:: Files left in build directory after distclean
* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
-* renamed objects:: Why are object files sometimes renamed?
+* Renamed Objects:: Why are object files sometimes renamed?
* Per-Object Flags:: How to simulate per-object flags?
* Multiple Outputs:: Writing rules for tools with many output files
* Hard-Coded Install Paths:: Installing to Hard-Coded Locations
@node CVS
@section CVS and generated files
-@subsection Background: distributed generated files
+@subheading Background: distributed generated Files
@cindex generated files, distributed
@cindex rebuild rules
@command{tar} preserves times-tamps, these rebuild rules are not
triggered when a user unpacks and builds a package.
-@subsection Background: CVS and timestamps
+@subheading Background: CVS and Timestamps
@cindex timestamps and CVS
@cindex CVS and timestamps
checked in. Calling @command{make} will then trigger a spurious rebuild
of @file{configure}.
-@subsection Living with CVS in Autoconfiscated projects
+@subheading Living with CVS in Autoconfiscated Projects
@cindex CVS and generated files
@cindex generated files and CVS
distributed files under CVS, including generated files, and those who
keep generated files @emph{out} of CVS.
-@subsubheading All files in CVS
+@subsubheading All Files in CVS
@itemize @bullet
@item
@end itemize
-@subsubheading Generated files out of CVS
+@subsubheading Generated Files out of CVS
One way to get CVS and @command{make} working peacefully is to never
store generated files in CVS, i.e., do not CVS-control files that
other developers could have noticed if they weren't using their own
versions of this tool.
-@subsection Third-party files
+@subheading Third-party Files
@cindex CVS and third-party files
@cindex third-party files and CVS
@node maintainer-mode
@section @command{missing} and @code{AM_MAINTAINER_MODE}
-@subsection @command{missing}
+@subheading @command{missing}
@cindex @command{missing}, purpose
The @command{missing} script is a wrapper around several maintainer
the build continue is one of the arguments of the
@code{AM_MAINTAINER_MODE} advocates.
-@subsection @code{AM_MAINTAINER_MODE}
+@subheading @code{AM_MAINTAINER_MODE}
@cindex @code{AM_MAINTAINER_MODE}, purpose
@acindex AM_MAINTAINER_MODE
You can get warnings about @samp{$(wildcard ...}) constructs using the
@option{-Wportability} flag.
-@node limitations on file names
-@section Limitations on file names
+@node Limitations on File Names
+@section Limitations on File Names
@cindex file names, limitations on
Automake attempts to support all kinds of file names, even those that
This is a diagnostic you might encounter while running @samp{make
distcheck}.
-As explained in @ref{Dist}, @samp{make distcheck} attempts to build
-and check your package for errors like this one.
+As explained in @ref{Checking the Distribution}, @samp{make distcheck}
+attempts to build and check your package for errors like this one.
@samp{make distcheck} will perform a @code{VPATH} build of your
package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
@vrindex distcleancheck_listfiles
For desperate cases, it's always possible to disable this check by
-setting @code{distcleancheck_listfiles} as documented in @ref{Dist}.
+setting @code{distcleancheck_listfiles} as documented in @ref{Checking
+the Distribution}.
Make sure you do understand the reason why @samp{make distcheck}
complains before you do this. @code{distcleancheck_listfiles} is a
way to @emph{hide} errors, not to fix them. You can always do better.
flags, not appended.
@end display
-@subsection Compile Flag Variables
+@subheading Compile Flag Variables
@cindex Flag Variables, Ordering
@cindex Compile Flag Variables
@cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
Automake to think that this is actually a per-target variable (like
@code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
-@subsection Other Variables
+@subheading Other Variables
There are other variables in Automake that follow similar principles
to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
-DejaGnu tests (@pxref{Tests}) use @code{RUNTESTDEFAULTFLAGS} and
+DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
@code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
(@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
@code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
However you should not think that all variables ending with
@code{FLAGS} follow this convention. For instance,
-@code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Dist}) and
+@code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Checking the Distribution}) and
@code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
are two variables that are only useful to the maintainer and have no
user counterpart.
variable. @xref{Program and Library Variables}.
-@node renamed objects
+@node Renamed Objects
@section Why are object files sometimes renamed?
This happens when per-target compilation flags are used. Object
@noindent
@file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
compiled with @samp{-some -flags}. (If you wonder about the names of
-these object files, see @ref{renamed objects}.) Note that
+these object files, see @ref{Renamed Objects}.) Note that
@code{foo_CFLAGS} gives the flags to use when compiling all the C
sources of the @emph{program} @code{foo}, it has nothing to do with
@file{foo.c} or @file{foo-foo.o} specifically.
We recommend against this, because this is error prone. For instance,
if you add such a rule to the first example, it will break the day you
decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
-compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{renamed
-objects}). Also in order to support dependency tracking, the two
+compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
+Objects}). Also in order to support dependency tracking, the two
@file{.o}/@file{.obj} extensions, and all the other flags variables
involved in a compilation, you will end up modifying a copy of the
rule previously output by @command{automake} for this file. If a new
recommendations for tool writers, and by indicating future directions
for dependency tracking work in Automake.
-@subsection First Take
+@menu
+* First Take on Dependencies:: Precomputed dependency tracking
+* Dependencies As Side Effects:: Update at developer compile time
+* Dependencies for the User:: Update at user compile time
+* Techniques for Dependencies:: Alternative approaches
+* Recommendations for Tool Writers:: What tool writers can do to help
+* Future Directions for Dependencies:: Languages Automake does not know
+@end menu
+
+@node First Take on Dependencies
+@subsection First Take on Dependency Tracking
@unnumberedsubsubsec Description
Our first attempt at automatic dependency tracking was based on the
inspiration was Jim Meyering. (I could be mistaken. If you know
otherwise feel free to correct me.)
+@node Dependencies As Side Effects
@subsection Dependencies As Side Effects
@unnumberedsubsubsec Description
file.
@end itemize
+@node Dependencies for the User
@subsection Dependencies for the User
@unnumberedsubsubsec Description
(with or without @command{depcomp}), the produced @file{Makefile}s are
larger.
+@node Techniques for Dependencies
@subsection Techniques for Computing Dependencies
There are actually several ways for a build tool like Automake to
@command{automake}.
@end table
+@node Recommendations for Tool Writers
@subsection Recommendations for Tool Writers
We think that every compilation tool ought to be able to generate
instead of each successful file open, in order to avoid the duplicated
new header bug.
-@subsection Future Directions for Automake's Dependency Tracking
+@node Future Directions for Dependencies
+@subsection Future Directions for Dependencies
Currently, only languages and compilers understood by Automake can
have dependency tracking enabled. We would like to see if it is
@c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
@c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
@c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
-@c LocalWords: unnumberedsubsec depfile tmpdepfile depmode const interoperate
+@c LocalWords: depfile tmpdepfile depmode const interoperate
@c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
@c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
@c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
projects / platform / upstream / automake.git / commitdiff