* 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
* Cygnus:: The effect of @option{--cygnus}
* Not Enough:: When Automake is not Enough
* Distributing:: Distributing the Makefile.in
-* API versioning:: About compatibility between Automake versions
+* API Versioning:: About compatibility between Automake versions
* Upgrading:: Upgrading to a Newer Automake Version
* FAQ:: Frequently Asked Questions
* History:: Notes about the history of Automake
* 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
* Fortran 77 Support:: Compiling Fortran 77 sources
* Fortran 9x Support:: Compiling Fortran 9x sources
* Java Support:: Compiling Java sources
+* Vala Support:: Compiling Vala sources
* Support for Other Languages:: Compiling other languages
* ANSI:: Automatic de-ANSI-fication (obsolete)
* Dependencies:: Automatic dependency tracking
* 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
+* Wildcards:: Why doesn't Automake support wildcards?
+* 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
The categories output by default are @samp{syntax} and
@samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
are enabled in @option{--gnu} and @option{--gnits} strictness.
+On the other hand, the @option{silent-rules} options (@pxref{Options})
+turns off portability warnings about recursive variable expansions.
@vindex WARNINGS
The environment variable @env{WARNINGS} can contain a comma separated
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
This macro will abort @command{configure} if no Unified Parallel C
compiler is found.
+@item AM_SILENT_RULES
+@acindex AM_SILENT_RULES
+Enable the machinery for less verbose build output (@pxref{Options}).
+
@item AM_WITH_DMALLOC
@acindex AM_WITH_DMALLOC
@cindex @command{dmalloc}, support for
@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
* Fortran 77 Support:: Compiling Fortran 77 sources
* Fortran 9x Support:: Compiling Fortran 9x sources
* Java Support:: Compiling Java sources
+* Vala Support:: Compiling Vala sources
* Support for Other Languages:: Compiling other languages
* ANSI:: Automatic de-ANSI-fication (obsolete)
* Dependencies:: Automatic dependency tracking
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
The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
Variables Ordering}. It allows users to run @samp{make
-LIBTOOLFLAGS=--silent}, for instance.
+LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
+@command{libtool} can also be influenced with the Automake
+@option{silent-rules} option (@pxref{Options}).
@node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
@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 @code{_LDFLAGS} variable for the program.
+@node Vala Support
+@comment node-name, next, previous, up
+@section Vala Support
+
+@cindex Vala Support
+@cindex Support for Vala
+
+Automake provides initial support for Vala
+(@uref{http://www.vala-project.org/}).
+This requires valac version 0.7.0 or later.
+
+@example
+foo_SOURCES = foo.vala bar.vala zardoc.c
+@end example
+
+Any @file{.vala} file listed in a @code{_SOURCES} variable will be
+compiled into C code by the Vala compiler. The generated @file{.c} files are
+distributed. The end user does not need to have a Vala compiler installed.
+
+Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
+that will locate the Vala compiler and optionally check its version
+number.
+
+@defmac AM_PROG_VALAC (@ovar{MINIMUM-VERSION})
+Try to find a Vala compiler in @env{PATH}. If it is found, the variable
+@code{VALAC} is set. Optionally a minimum release number of the compiler
+can be requested:
+
+@example
+AM_PROG_VALAC([0.7.0])
+@end example
+@end defmac
+
+There are a few variables that are used when compiling Vala sources:
+
+@vtable @code
+@item VALAC
+Path to the the Vala compiler.
+
+@item VALAFLAGS
+Additional arguments for the Vala compiler.
+
+@item AM_VALAFLAGS
+The maintainer's variant of @code{VALAFLAGS}.
+
+@example
+lib_LTLIBRARIES = libfoo.la
+libfoo_la_SOURCES = foo.vala
+@end example
+@end vtable
+
+
@node Support for Other Languages
@comment node-name, next, previous, up
@section Support for Other Languages
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:
@cindex @code{make check}
@trindex check
-Automake supports two forms of test suites.
+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,
@vindex TESTS
@vindex TESTS_ENVIRONMENT
The variable @code{TESTS_ENVIRONMENT} can be used to set environment
-variables for the test run; the environment variable @code{srcdir} is
+variables for the test run; the environment variable @env{srcdir} is
set in the rule. If all your test programs are scripts, you can also
set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
@samp{$(SHELL) -x} can be useful for debugging the tests), or any other
by the tests, not the tests themselves. Of course you can set
@code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
+
+@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
+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
+@samp{RST} (reStructuredText) and @samp{HTML} format, and hard errors
+for exceptional failures. Similar to the simple test driver,
+@code{TESTS_ENVIRONMENT}, @code{AM_COLOR_TESTS}, @code{XFAIL_TESTS}, and
+the @code{check_*} variables are honored, and the environment variable
+@env{srcdir} is set during test execution.
+
+This test driver is still experimental and may undergo changes in order
+to satisfy additional portability requirements.
+
+@vindex TEST_SUITE_LOG
+@vindex TESTS
+The driver operates by defining a set of @command{make} rules to create
+a summary log file, @code{TEST_SUITE_LOG}, which defaults to
+@file{test-suite.log} and requires a @file{.log} suffix. This file
+depends upon log files created for each single test program listed in
+@code{TESTS}, which in turn contain all output produced by the
+corresponding tests.
+
+@vindex TEST_EXTENSIONS
+@vindex TEST_LOGS
+Each log file is created when the corresponding test has completed.
+The set of log files is listed in the read-only variable
+@code{TEST_LOGS}, and defaults to @code{TESTS}, with the executable
+extension if any (@pxref{EXEEXT}), as well as any suffix listed in
+@code{TEST_EXTENSIONS} removed, and @file{.log} appended.
+@code{TEST_EXTENSIONS} defaults to @file{.test}. Results are undefined
+if a test file name ends in several concatenated suffixes.
+
+@vindex _LOG_COMPILE
+@vindex _LOG_COMPILER
+@vindex _LOG_FLAGS
+@vindex LOG_COMPILE
+@vindex LOG_COMPILER
+@vindex LOG_FLAGS
+@vindex @var{EXT}_LOG_COMPILE
+@vindex @var{EXT}_LOG_COMPILER
+@vindex @var{EXT}_LOG_FLAGS
+@vindex AM_@var{EXT}_LOG_FLAGS
+@vindex AM_LOG_FLAGS
+For tests that match an extension @code{.@var{ext}} listed in
+@code{TEST_EXTENSIONS}, you can provide a test driver using the variable
+@code{@var{ext}_LOG_COMPILER} (note the upper-case extension) and pass
+options in @code{AM_@var{ext}_LOG_FLAGS} and allow the user to pass
+options in @code{@var{ext}_LOG_FLAGS}. It will cause all tests with
+this extension to be called with this driver. For all tests without a
+registered extension, the variables @code{LOG_COMPILER},
+@code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
+
+@example
+TESTS = foo.pl bar.py baz
+TEST_EXTENSIONS = .pl .py
+PL_LOG_COMPILER = $(PERL)
+AM_PL_LOG_FLAGS = -w
+PY_LOG_COMPILER = $(PYTHON)
+AM_PY_LOG_FLAGS = -v
+LOG_COMPILER = ./wrapper-script
+AM_LOG_FLAGS = -d
+@end example
+
+@noindent
+will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
+and @samp{./wrapper-script -d baz} to produce @file{foo.log},
+@file{bar.log}, and @file{baz.log}, respectively. The
+@samp{TESTS_ENVIRONMENT} variable is still expanded before the driver,
+but should be reserved for the user.
+
+@vindex VERBOSE
+As with the simple driver above, by default one status line is printed
+per completed test, and a short summary after the suite has completed.
+However, standard output and standard error of the test are redirected
+to a per-test log file, so that parallel execution does not produce
+intermingled output. The output from failed tests is collected in the
+@file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
+file is output after the summary. For best results, the tests should be
+verbose by default now.
+
+@trindex mostlyclean
+@trindex check-html
+@vindex RST2HTML
+@vindex TEST_SUITE_HTML
+With @code{make check-html}, the log files may be converted from RST
+(reStructuredText, see @uref{http://docutils.sourceforge.net/@/rst.html})
+to HTML using @samp{RST2HTML}, which defaults to @command{rst2html} or
+@command{rst2html.py}. The variable @samp{TEST_SUITE_HTML} contains the
+set of converted log files. The log and HTML files are removed upon
+@code{make mostlyclean}.
+
+@vindex DISABLE_HARD_ERRORS
+@cindex Exit status 99, special interpretation
+@cindex hard error
+Even in the presence of expected failures (see @code{XFAIL_TESTS}, there
+may be conditions under which a test outcome needs attention. For
+example, with test-driven development, you may write tests for features
+that you have not implemented yet, and thus mark these tests as expected
+to fail. However, you may still be interested in exceptional conditions,
+for example, tests that fail due to a segmentation violation or another
+error that is independent of the feature awaiting implementation.
+Tests can exit with an exit status of 99 to signal such a @emph{hard
+error}. Unless the variable @code{DISABLE_HARD_ERRORS} is set to a
+nonempty value, such tests will be counted as failed.
+
+By default, the test suite driver will run all tests, but there are
+several ways to limit the set of tests that are run:
+
+@itemize @bullet
+@item
+You can set the @code{TESTS} variable, similarly to how you can with
+the simple test driver from the previous section. For example, you can
+use a command like this to run only a subset of the tests:
+
+@example
+env TESTS="foo.test bar.test" make -e check
+@end example
+
+@item
+You can set the @code{TEST_LOGS} variable. By default, this variable is
+computed at @command{make} run time from the value of @code{TESTS} as
+described above. For example, you can use the following:
+
+@example
+set x subset*.log; shift
+env TEST_LOGS="foo.log $*" make -e check
+@end example
+
+@item
+@vindex RECHECK_LOGS
+@cindex lazy test execution
+By default, the test driver removes all old per-test log files before it
+starts running tests to regenerate them. The variable
+@code{RECHECK_LOGS} contains the set of log files which are removed.
+@code{RECHECK_LOGS} defaults to @code{TEST_LOGS}, which means all tests
+need to be rechecked. By overriding this variable, you can choose which
+tests need to be reconsidered. For example, you can lazily rerun only
+those tests which are outdated, i.e., older than their prerequisite test
+files, by setting this variable to the empty value:
+
+@example
+env RECHECK_LOGS= make -e check
+@end example
+
+@item
+@trindex recheck
+@trindex recheck-html
+You can ensure that all tests are rerun which have failed or passed
+unexpectedly, by running @code{make recheck} in the test directory.
+This convenience target will set @code{RECHECK_LOGS} appropriately
+before invoking the main test driver. The @code{recheck-html} target
+does the same as @code{recheck} but again converts the resulting log
+file in HTML format, like the @code{check-html} target.
+@end itemize
+
+In order to guarantee an ordering between tests even with @code{make
+-j@var{N}}, dependencies between the corresponding log files may be
+specified through usual @command{make} dependencies. For example, the
+following snippet lets the test named @file{foo-execute.test} depend
+upon completion of the test @file{foo-compile.test}:
+
+@example
+TESTS = foo-compile.test foo-execute.test
+foo-execute.log: foo-compile.log
+@end example
+
+@noindent
+Please note that this ordering ignores the @emph{results} of required
+tests, thus the test @file{foo-execute.test} is run even if the test
+@file{foo-compile.test} failed or was skipped beforehand. Further,
+please note that specifying such dependencies currently works only for
+tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
+
+Tests without such specified dependencies may be run concurrently with
+parallel @command{make -j@var{N}}, so be sure they are prepared for
+concurrent execution.
+
+@cindex Unit tests
+The combination of lazy test execution and correct dependencies between
+tests and their sources may be exploited for efficient unit testing
+during development. To further speed up the edit-compile-test cycle, it
+may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
+instead of with @code{check_PROGRAMS}, as the former allows intertwined
+compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
+not cleaned automatically, @pxref{Uniform}).
+
+The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
+conditional parts as well as configure substitutions. In the latter
+case, however, certain restrictions apply: substituted test names
+must end with a nonempty test suffix like @file{.test}, so that one of
+the inference rules generated by @command{automake} can apply. For
+literal test names, @command{automake} can generate per-target rules
+to avoid this limitation.
+
+Please note that it is currently not possible to use @code{$(srcdir)/}
+or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
+limitation is necessary to avoid generating test logs in the source tree
+and has the unfortunate consequence that it is not possible to specify
+distributed tests that are themselves generated by means of explicit
+rules, in a way that is portable to all @command{make} implementations
+(@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
+semantics of FreeBSD and OpenBSD @command{make} conflict with this).
+In case of doubt you may want to require to use GNU @command{make},
+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}
Don't require @file{texinfo.tex}, even if there are texinfo files in
this directory.
+@item @option{parallel-tests}
+@cindex Option, @option{parallel-tests}
+@opindex parallel-tests
+Enable test suite driver for @code{TESTS} that can run tests in parallel
+(@pxref{Simple Tests using parallel-tests}, for more information).
+
@item @option{readme-alpha}
@cindex Option, @option{readme-alpha}
@opindex readme-alpha
@samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
letter; it should be omitted for non-alpha releases.
+@item @option{silent-rules}
+@cindex Option, @option{silent-rules}
+@opindex silent-rules
+Enable less verbose build rules. This can be used to let build rules
+output a status line of the form
+
+@example
+ GEN @var{output-file}
+@end example
+
+@noindent
+instead of printing the command that will be executed to update
+@var{output-file}. It can also silence @command{libtool} output.
+
+To enable less verbose build rules, both the developer and the user
+of the package have to take a number of steps. The developer needs
+to do either of the following:
+
+@itemize @bullet
+@item
+Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
+@item
+Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
+file.
+@end itemize
+
+@cindex default verbosity for silent-rules
+If the developer has done either of the above, then the user of the
+package may influence the verbosity at @command{configure} run time as
+well as at @command{make} run time:
+
+@itemize @bullet
+@item
+@opindex --enable-silent-rules
+@opindex --disable-silent-rules
+Passing @option{--enable-silent-rules} to @command{configure} will cause
+build rules to be less verbose; the option @option{--disable-silent-rules}
+is the default and will cause normal verbose output.
+@item
+@vindex @code{V}
+At @command{make} run time, the default chosen at @command{configure}
+time may be overridden: @code{make V=1} will produce verbose output,
+@code{make V=0} less verbose output.
+@end itemize
+
+For portability to different @command{make} implementations, package authors
+are advised to not set the variable @code{V} inside the @file{Makefile.am}
+file, to allow the user to override the value for subdirectories as well.
+
+The current implementation of this feature relies on a non-POSIX, but in
+practice rather widely supported @file{Makefile} construct of nested
+variable expansion @samp{$(@var{var1}$(V))}. Do not use the
+@option{silent-rules} option if your package needs to build with
+@command{make} implementations that do not support it. The
+@option{silent-rules} option turns off warnings about recursive variable
+expansion, which are in turn enabled by @option{-Wportability}
+(@pxref{Invoking Automake}).
+
+@vindex @code{AM_V_GEN}
+@vindex @code{AM_V_at}
+@vindex @code{AM_DEFAULT_VERBOSITY}
+To extend the silent mode to your own rules, you have two choices:
+
+@itemize @bullet
+@item
+You can use the predefined variable @code{AM_V_GEN} as a prefix to
+commands that should output a status line in silent mode, and
+@code{AM_V_at} as a prefix to commands that should not output anything
+in silent mode. When output is to be verbose, both of these variables
+will expand to the empty string.
+@item
+You can add your own variables, so strings of your own choice are shown.
+The following snippet shows how you would define your own equivalent of
+@code{AM_V_GEN}:
+
+@example
+pkg_verbose = $(pkg_verbose_$(V))
+pkg_verbose_ = $(pkg_verbose_$(AM_DEFAULT_VERBOSITY))
+pkg_verbose_0 = @@echo GEN $@@;
+
+foo: foo.in
+ $(pkg_verbose)cp $(srcdir)/foo.in $@@
+@end example
+@end itemize
+
+
@item @option{std-options}
@cindex Options, @option{std-options}
@cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
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.
package, regardless of the licensing you choose.
-@node API versioning
-@chapter Automake API versioning
+@node API Versioning
+@chapter Automake API Versioning
New Automake releases usually include bug fixes and new features.
Unfortunately they may also introduce new bugs and incompatibilities.
@menu
* 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
+* Wildcards:: Why doesn't Automake support wildcards?
+* 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
version of the tools.
-@node wildcards
+@node Wildcards
@section Why doesn't Automake support wildcards?
@cindex wildcards
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
@item 2002-03-05 Automake 1.6
This release introduced versioned installation (@pxref{API
-versioning}). This was mainly pushed by Havoc Pennington, taking the
+Versioning}). This was mainly pushed by Havoc Pennington, taking the
GNOME source tree as motive: due to incompatibilities between the
autotools it's impossible for the GNOME packages to switch to Autoconf
2.53 and Automake 1.5 all at once, so they are currently stuck with
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
@item 2005-07-10 @tab 1.9.6 @tab 7539 @tab 699 @tab 7867 @tab 3400 (40) @tab 1453 (32) @tab 144 @tab 570
@item 2006-10-15 @tab 1.10 @tab 7859 @tab 1072 @tab 8024 @tab 3512 (40) @tab 1496 (34) @tab 172 @tab 604
@item 2008-01-19 @tab 1.10.1 @tab 7870 @tab 1089 @tab 8025 @tab 3520 (40) @tab 1499 (34) @tab 173 @tab 617
+@item 2009-03-29 @tab 1.10b @tab 8556 @tab 1092 @tab 8281 @tab 4106 (41) @tab 1608 (35) @tab 178 @tab 720 (20)
@end multitable
@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 / blobdiff