"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/automake.texi" between
automake-1.16.2.tar.xz and automake-1.16.3.tar.xz

About: GNU Automake is a Makefile generator (input Makefile.am, output Makefile.in; intended for use with autoconf).

automake.texi  (automake-1.16.2.tar.xz)	:	automake.texi  (automake-1.16.3.tar.xz)
skipping to change at line 121		skipping to change at line 121
* Install:: What gets installed		* Install:: What gets installed
* Clean:: What gets cleaned		* Clean:: What gets cleaned
* Dist:: What goes in a distribution		* Dist:: What goes in a distribution
* Tests:: Support for test suites		* Tests:: Support for test suites
* Rebuilding:: Automatic rebuilding of Makefile		* Rebuilding:: Automatic rebuilding of Makefile
* Options:: Changing Automake's behavior		* Options:: Changing Automake's behavior
* Miscellaneous:: Miscellaneous rules		* Miscellaneous:: Miscellaneous rules
* Include:: Including extra files in an Automake template		* Include:: Including extra files in an Automake template
* Conditionals:: Conditionals		* Conditionals:: Conditionals
* Silencing Make:: Obtain less verbose output from @command{make}		* Silencing Make:: Obtain less verbose output from @command{make}
* Gnits:: The effect of @option{--gnu} and @option{--gnits }
* Not Enough:: When Automake is not Enough		* Not Enough:: When Automake is not Enough
* Distributing:: Distributing the Makefile.in		* 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		* Upgrading:: Upgrading to a Newer Automake Version
* FAQ:: Frequently Asked Questions		* FAQ:: Frequently Asked Questions
* Copying This Manual:: How to make copies of this manual		* Copying This Manual:: How to make copies of this manual
* Indices:: Indices of variables, macros, and concepts		* Indices:: Indices of variables, macros, and concepts
@detailmenu		@detailmenu
--- The Detailed Node Listing ---		--- The Detailed Node Listing ---
skipping to change at line 467		skipping to change at line 466
some of them claiming to be @emph{generated by} Autoconf or Automake.		some of them claiming to be @emph{generated by} Autoconf or Automake.
But the exact purpose of these files and their relations is probably		But the exact purpose of these files and their relations is probably
fuzzy. The goal of this chapter is to introduce you to this machinery,		fuzzy. The goal of this chapter is to introduce you to this machinery,
to show you how it works and how powerful it is. If you've never		to show you how it works and how powerful it is. If you've never
installed or seen such a package, do not worry: this chapter will walk		installed or seen such a package, do not worry: this chapter will walk
you through it.		you through it.
If you need some teaching material, more illustrations, or a less		If you need some teaching material, more illustrations, or a less
@command{automake}-centered continuation, some slides for this		@command{automake}-centered continuation, some slides for this
introduction are available in Alexandre Duret-Lutz's		introduction are available in Alexandre Duret-Lutz's
@uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,		@uref{https://www.lrde.epita.fr/@/~adl/@/autotools.html,
Autotools Tutorial}.		Autotools Tutorial}.
This chapter is the written version of the first part of his tutorial.		This chapter is the written version of the first part of his tutorial.
@menu		@menu
* GNU Build System:: Introducing the GNU Build System		* GNU Build System:: Introducing the GNU Build System
* Use Cases:: Use Cases for the GNU Build System		* Use Cases:: Use Cases for the GNU Build System
* Why Autotools:: How Autotools Help		* Why Autotools:: How Autotools Help
* Hello World:: A Small Hello World Package		* Hello World:: A Small Hello World Package
@end menu		@end menu
skipping to change at line 1232		skipping to change at line 1231
Another, more useful command is @code{make distcheck}. The		Another, more useful command is @code{make distcheck}. The
@code{distcheck} target constructs		@code{distcheck} target constructs
@file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},		@file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
but it additionally ensures most of the use cases presented so far		but it additionally ensures most of the use cases presented so far
work:		work:
@itemize @bullet		@itemize @bullet
@item		@item
It attempts a full compilation of the package (@pxref{Basic		It attempts a full compilation of the package (@pxref{Basic
Installation}), unpacking the newly constructed tarball, running		Installation}): unpacking the newly constructed tarball, running
@code{make}, @code{make check}, @code{make install}, as well as		@code{make}, @code{make dvi}, @code{make check}, @code{make install},
@code{make installcheck}, and even @code{make dist},		as well as @code{make installcheck}, and even @code{make dist},
@item		@item
it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),		it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
@item		@item
it makes sure @code{make clean}, @code{make distclean}, and @code{make		it makes sure @code{make clean}, @code{make distclean}, and @code{make
uninstall} do not omit any file (@pxref{Standard Targets}),		uninstall} do not omit any file (@pxref{Standard Targets}),
@item		@item
and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).		and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
@end itemize		@end itemize
All of these actions are performed in a temporary directory, so that no		All of these actions are performed in a temporary directory, so that
root privileges are required. Please note that the exact location and the		no root privileges are required. The exact location and the exact
exact structure of such a subdirectory (where the extracted sources are		structure of such a subdirectory (where the extracted sources are
placed, how the temporary build and install directories are named and how		placed, how the temporary build and install directories are named and
deeply they are nested, etc.) is to be considered an implementation detail,		how deeply they are nested, etc.) is to be considered an
which can change at any time; so do not rely on it.		implementation detail, which can change at any time; so do not rely on
		it.
Releasing a package that fails @code{make distcheck} means that one of		Releasing a package that fails @code{make distcheck} means that one of
the scenarios we presented will not work and some users will be		the scenarios we presented will not work and some users will be
disappointed. Therefore it is a good practice to release a package		disappointed. Therefore it is a good practice to release a package
only after a successful @code{make distcheck}. This of course does		only after a successful @code{make distcheck}. This of course does
not imply that the package will be flawless, but at least it will		not imply that the package will be flawless, but at least it will
prevent some of the embarrassing errors you may find in packages		prevent some of the embarrassing errors you may find in packages
released by people who have never heard about @code{distcheck} (like		released by people who have never heard about @code{distcheck} (like
@code{DESTDIR} not working because of a typo, or a distributed file		@code{DESTDIR} not working because of a typo, or a distributed file
being erased by @code{make clean}, or even @code{VPATH} builds not		being erased by @code{make clean}, or even @code{VPATH} builds not
skipping to change at line 1908		skipping to change at line 1908
@cindex First line of Makefile.am		@cindex First line of Makefile.am
@example		@example
## Process this file with automake to produce Makefile.in		## Process this file with automake to produce Makefile.in
@end example		@end example
@c FIXME document customary ordering of Makefile.am here!		@c FIXME document customary ordering of Makefile.am here!
@node Strictness		@node Strictness
@section Strictness		@section Strictness
		@c "Gnits" used to be a separate section.
		@c This @anchor allows old links to still work.
		@anchor{Gnits}
@cindex Non-GNU packages		@cindex Non-GNU packages
While Automake is intended to be used by maintainers of GNU packages, it		While Automake is intended to be used by maintainers of GNU packages, it
does make some effort to accommodate those who wish to use it, but do		does make some effort to accommodate those who wish to use it, but do
not want to use all the GNU conventions.		not want to use all the GNU conventions.
@cindex Strictness, defined		@cindex Strictness, defined
@cindex Strictness, @option{foreign}		To this end, Automake supports three levels of @dfn{strictness}---how
@cindex @option{foreign} strictness		stringently Automake should enforce conformance with GNU conventions.
		Each strictness level can be selected using an option of the same name;
		see @ref{Options}.
		The strictness levels are:
		@table @option
		@item gnu
@cindex Strictness, @option{gnu}		@cindex Strictness, @option{gnu}
@cindex @option{gnu} strictness		@cindex @option{gnu} strictness
@cindex Strictness, @option{gnits}		@opindex --gnu
@cindex @option{gnits} strictness		This is the default level of strictness. Automake will check for
		basic compliance with the GNU standards for software packaging.
		@xref{Top,,, standards, The GNU Coding Standards} for full details
		of these standards. Currently the following checks are made:
To this end, Automake supports three levels of @dfn{strictness}---the		@itemize @bullet
strictness indicating how stringently Automake should check standards		@item
conformance.		The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
		and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
		or @file{COPYING}, are required at the topmost directory of the package.
The valid strictness levels are:		If the @option{--add-missing} option is given, @command{automake} will
		add a generic version of the @file{INSTALL} file as well as the
		@file{COPYING} file containing the text of the current version of the
		GNU General Public License existing at the time of this Automake release
		(version 3 as this is written,
		@uref{https://www.gnu.org/@/copyleft/@/gpl.html}).
		However, an existing @file{COPYING} file will never be overwritten by
		@command{automake}.
		@item
		The options @option{no-installman} and @option{no-installinfo} are
		prohibited.
		@end itemize
		Future versions of Automake will add more checks at this level of
		strictness; it is advisable to be familiar with the precise requirements
		of the GNU standards.
		Future versions of Automake may, at this level of strictness, require
		certain non-standard GNU tools to be available to maintainer-only
		Makefile rules. For instance, in the future @command{pathchk}
		(@pxref{pathchk invocation,,, coreutils, GNU Coreutils})
		may be required to run @samp{make dist}.
@table @option
@item foreign		@item foreign
		@cindex Strictness, @option{foreign}
		@cindex @option{foreign} strictness
		@opindex --foreign
Automake will check for only those things that are absolutely		Automake will check for only those things that are absolutely
required for proper operation. For instance, whereas GNU standards		required for proper operation. For instance, whereas GNU standards
dictate the existence of a @file{NEWS} file, it will not be required in		dictate the existence of a @file{NEWS} file, it will not be required in
this mode. This strictness will also turn off some warnings by default		this mode. This strictness will also turn off some warnings by default
(among them, portability warnings).		(among them, portability warnings).
The name comes from the fact that Automake is intended to be
used for GNU programs; these relaxed rules are not the standard mode of
operation.
@item gnu
Automake will check---as much as possible---for compliance to the GNU
standards for packages. This is the default.
@item gnits		@item gnits
		@cindex Strictness, @option{gnits}
		@cindex @option{gnits} strictness
		@opindex --gnits
Automake will check for compliance to the as-yet-unwritten @dfn{Gnits		Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
standards}. These are based on the GNU standards, but are even more		standards}. These are based on the GNU standards, but are even more
detailed. Unless you are a Gnits standards contributor, it is		detailed. Unless you are a Gnits standards contributor, it is
recommended that you avoid this option until such time as the Gnits		recommended that you avoid this option until such time as the Gnits
standard is actually published (which may never happen).		standard is actually published (which may never happen).
@end table
@xref{Gnits}, for more information on the precise implications of the		Currently, @option{--gnits} does all the checks that
strictness level.		@option{--gnu} does, and checks the following as well:
		@itemize @bullet
		@item
		@samp{make installcheck} will check to make sure that the @option{--help}
		and @option{--version} really print a usage message and a version string,
		respectively. This is the @option{std-options} option (@pxref{Options}).
		@item
		@samp{make dist} will check to make sure the @file{NEWS} file has been
		updated to the current version.
		@item
		@code{VERSION} is checked to make sure its format complies with Gnits
		standards.
		@c FIXME xref when standards are finished
		@item
		@cindex @file{README-alpha}
		If @code{VERSION} indicates that this is an alpha release, and the file
		@file{README-alpha} appears in the topmost directory of a package, then
		it is included in the distribution. This is done in @option{--gnits}
		mode, and no other, because this mode is the only one where version
		number formats are constrained, and hence the only mode where Automake
		can automatically determine whether @file{README-alpha} should be
		included.
		@item
		The file @file{THANKS} is required.
		@end itemize
		@end table
@node Uniform		@node Uniform
@section The Uniform Naming Scheme		@section The Uniform Naming Scheme
@cindex Uniform naming scheme		@cindex Uniform naming scheme
Automake variables generally follow a @dfn{uniform naming scheme} that		Automake variables generally follow a @dfn{uniform naming scheme} that
makes it easy to decide how programs (and other derived objects) are		makes it easy to decide how programs (and other derived objects) are
built, and how they are installed. This scheme also supports		built, and how they are installed. This scheme also supports
@command{configure} time determination of what should be built.		@command{configure} time determination of what should be built.
skipping to change at line 2130		skipping to change at line 2194
@node Length Limitations		@node Length Limitations
@section Staying below the command line length limit		@section Staying below the command line length limit
@cindex command line length limit		@cindex command line length limit
@cindex ARG_MAX		@cindex ARG_MAX
Traditionally, most unix-like systems have a length limitation for the		Traditionally, most unix-like systems have a length limitation for the
command line arguments and environment contents when creating new		command line arguments and environment contents when creating new
processes (see for example		processes (see for example
@uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an		@uref{https://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an
overview on this issue),		overview on this issue),
which of course also applies to commands spawned by @command{make}.		which of course also applies to commands spawned by @command{make}.
POSIX requires this limit to be at least 4096 bytes, and most modern		POSIX requires this limit to be at least 4096 bytes, and most modern
systems have quite high limits (or are unlimited).		systems have quite high limits (or are unlimited).
In order to create portable Makefiles that do not trip over these		In order to create portable Makefiles that do not trip over these
limits, it is necessary to keep the length of file lists bounded.		limits, it is necessary to keep the length of file lists bounded.
Unfortunately, it is not possible to do so fully transparently within		Unfortunately, it is not possible to do so fully transparently within
Automake, so your help may be needed. Typically, you can split long		Automake, so your help may be needed. Typically, you can split long
file lists manually and use different installation directory names for		file lists manually and use different installation directory names for
skipping to change at line 2250		skipping to change at line 2314
@file{Makefile} can do its work properly. There are a fairly large		@file{Makefile} can do its work properly. There are a fairly large
number of them, and we list them here.		number of them, and we list them here.
Although all of these files are distributed and installed with		Although all of these files are distributed and installed with
Automake, a couple of them are maintained separately. The Automake		Automake, a couple of them are maintained separately. The Automake
copies are updated before each release, but we mention the original		copies are updated before each release, but we mention the original
source in case you need more recent versions.		source in case you need more recent versions.
@table @code		@table @code
@item ar-lib		@item ar-lib
		@cmindex ar-lib
This is a wrapper primarily for the Microsoft lib archiver, to make		This is a wrapper primarily for the Microsoft lib archiver, to make
it more POSIX-like.		it more POSIX-like.
@item compile		@item compile
		@cmindex compile
This is a wrapper for compilers that do not accept options @option{-c}		This is a wrapper for compilers that do not accept options @option{-c}
and @option{-o} at the same time. It is only used when absolutely		and @option{-o} at the same time. It is only used when absolutely
required. Such compilers are rare, with the Microsoft C/C++ Compiler		required. Such compilers are rare, with the Microsoft C/C++ Compiler
as the most notable exception. This wrapper also makes the following		as the most notable exception. This wrapper also makes the following
common options available for that compiler, while performing file name		common options available for that compiler, while performing file name
translation where needed: @option{-I}, @option{-L}, @option{-l},		translation where needed: @option{-I}, @option{-L}, @option{-l},
@option{-Wl,} and @option{-Xlinker}.		@option{-Wl,} and @option{-Xlinker}.
@item config.guess		@item config.guess
@itemx config.sub		@itemx config.sub
		@cmindex config.guess
		@cmindex config.sub
These two programs compute the canonical triplets for the given build,		These two programs compute the canonical triplets for the given build,
host, or target architecture. These programs are updated regularly to		host, or target architecture. These programs are updated regularly to
support new architectures and fix probes broken by changes in new		support new architectures and fix probes broken by changes in new
kernel versions. Each new release of Automake comes with up-to-date		kernel versions. Each new release of Automake comes with up-to-date
copies of these programs. If your copy of Automake is getting old,		copies of these programs. If your copy of Automake is getting old,
you are encouraged to fetch the latest versions of these files from		you are encouraged to fetch the latest versions of these files from
@url{https://savannah.gnu.org/git/?group=config} before making a		@url{https://savannah.gnu.org/git/?group=config} before making a
release.		release.
@item depcomp		@item depcomp
		@cmindex depcomp
This program understands how to run a compiler so that it will		This program understands how to run a compiler so that it will
generate not only the desired output but also dependency information		generate not only the desired output but also dependency information
that is then used by the automatic dependency tracking feature		that is then used by the automatic dependency tracking feature
(@pxref{Dependencies}).		(@pxref{Dependencies}).
@item install-sh		@item install-sh
		@cmindex install-sh
This is a replacement for the @command{install} program that works on		This is a replacement for the @command{install} program that works on
platforms where @command{install} is unavailable or unusable.		platforms where @command{install} is unavailable or unusable.
@item mdate-sh		@item mdate-sh
		@cmindex mdate-sh
This script is used to generate a @file{version.texi} file. It examines		This script is used to generate a @file{version.texi} file. It examines
a file and prints some date information about it.		a file and prints some date information about it.
@item missing		@item missing
		@cmindex missing @r{program}
This wraps a number of programs that are typically only required by		This wraps a number of programs that are typically only required by
maintainers. If the program in question doesn't exist, or seems too old,		maintainers. If the program in question doesn't exist, or seems too old,
@command{missing} will print an informative warning before failing out,		@command{missing} will print an informative warning before failing out,
to provide the user with more context and information.		to provide the user with more context and information.
@item mkinstalldirs		@item mkinstalldirs
		@cmindex mkinstalldirs
This script used to be a wrapper around @samp{mkdir -p}, which is not		This script used to be a wrapper around @samp{mkdir -p}, which is not
portable. Now we prefer to use @samp{install-sh -d} when @command{configure}		portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
finds that @samp{mkdir -p} does not work, this makes one less script to		finds that @samp{mkdir -p} does not work, this makes one less script to
distribute.		distribute.
For backward compatibility @file{mkinstalldirs} is still used and		For backward compatibility @file{mkinstalldirs} is still used and
distributed when @command{automake} finds it in a package. But it is no		distributed when @command{automake} finds it in a package. But it is no
longer installed automatically, and it should be safe to remove it.		longer installed automatically, and it should be safe to remove it.
@item py-compile		@item py-compile
		@cmindex py-compile
This is used to byte-compile Python scripts.		This is used to byte-compile Python scripts.
@item test-driver		@item test-driver
		@cmindex test-driver
This implements the default test driver offered by the parallel		This implements the default test driver offered by the parallel
testsuite harness.		testsuite harness.
@item texinfo.tex		@item texinfo.tex
Not a program, this file is required for @samp{make dvi}, @samp{make		@cmindex texinfo.tex
ps} and @samp{make pdf} to work when Texinfo sources are in the		When Texinfo sources are in the package, this file is required for
package. The latest version can be downloaded from		@samp{make dvi}, @samp{make ps} and @samp{make pdf}. The latest
@url{https://www.gnu.org/software/texinfo/}.		version can be downloaded from
		@url{https://www.gnu.org/software/texinfo/}. A working @TeX{}
		distribution, or at least a @file{tex} program, is also required.
		Furthermore, @samp{make dist} invokes @samp{make dvi}, so these become
		requirements for making a distribution with Texinfo sources.
@item ylwrap		@item ylwrap
		@cmindex ylwrap
This program wraps @command{lex} and @command{yacc} to rename their		This program wraps @command{lex} and @command{yacc} to rename their
output files. It also ensures that, for instance, multiple		output files. It also ensures that, for instance, multiple
@command{yacc} instances can be invoked in a single directory in		@command{yacc} instances can be invoked in a single directory in
parallel.		parallel.
@end table		@end table
@node Examples		@node Examples
@chapter Some example packages		@chapter Some example packages
skipping to change at line 2604		skipping to change at line 2684
@option{--copy}, copying the new file).		@option{--copy}, copying the new file).
@item --foreign		@item --foreign
@opindex --foreign		@opindex --foreign
Set the global strictness to @option{foreign}. For more information, see		Set the global strictness to @option{foreign}. For more information, see
@ref{Strictness}.		@ref{Strictness}.
@item --gnits		@item --gnits
@opindex --gnits		@opindex --gnits
Set the global strictness to @option{gnits}. For more information, see		Set the global strictness to @option{gnits}. For more information, see
@ref{Gnits}.		@ref{Strictness}.
@item --gnu		@item --gnu
@opindex --gnu		@opindex --gnu
Set the global strictness to @option{gnu}. For more information, see		Set the global strictness to @option{gnu}. For more information, see
@ref{Gnits}. This is the default strictness.		@ref{Strictness}. This is the default strictness.
@item --help		@item --help
@opindex --help		@opindex --help
Print a summary of the command line options and exit.		Print a summary of the command line options and exit.
@item -i		@item -i
@itemx --ignore-deps		@itemx --ignore-deps
@opindex -i		@opindex -i
This disables the dependency tracking feature in generated		This disables the dependency tracking feature in generated
@file{Makefile}s; see @ref{Dependencies}.		@file{Makefile}s; see @ref{Dependencies}.
skipping to change at line 2654		skipping to change at line 2734
@itemx --verbose		@itemx --verbose
@opindex -v		@opindex -v
@opindex --verbose		@opindex --verbose
Cause Automake to print information about which files are being read or		Cause Automake to print information about which files are being read or
created.		created.
@item --version		@item --version
@opindex --version		@opindex --version
Print the version number of Automake and exit.		Print the version number of Automake and exit.
@item -W CATEGORY		@item -W @var{category}[,@var{category}...]
@itemx --warnings=@var{category}		@itemx --warnings=@var{category}[,@var{category}...]
@opindex -W		@opindex -W
@opindex --warnings		@opindex --warnings
Output warnings falling in @var{category}. @var{category} can be		Output warnings about a @var{category} of potential problems with the
one of:		package. @var{category} can be any of:
@table @code		@table @code
		@item cross
		Constructs compromising the ability to cross-compile the package.
@item gnu		@item gnu
warnings related to the GNU Coding Standards		Minor deviations from the GNU Coding Standards
(@pxref{Top, , , standards, The GNU Coding Standards}).		(@pxref{Top, , , standards, The GNU Coding Standards}).
@item obsolete		@item obsolete
obsolete features or constructions		Obsolete features or constructions.
@item override		@item override
user redefinitions of Automake rules or variables		Redefinitions of Automake rules or variables.
@item portability		@item portability
portability issues (e.g., use of @command{make} features that are		Portability issues (e.g., use of @command{make} features that are
known to be not portable)		known to be not portable).
		@item portability-recursive
		Recursive, or nested, Make variable expansions (@code{$(foo$(x))}).
		These are not universally supported, but are more portable than the
		other non-portable constructs diagnosed by @option{-Wportability}.
		These warnings are turned on by @option{-Wportability} but can then be
		turned off specifically by @option{-Wno-portability-recursive}.
@item extra-portability		@item extra-portability
extra portability issues related to obscure tools. One example of such		Extra portability issues, related to rarely-used tools such as
a tool is the Microsoft @command{lib} archiver.		the Microsoft @command{lib} archiver.
@item syntax		@item syntax
weird syntax, unused variables, typos		Questionable syntax, unused variables, typos, etc.
@item unsupported		@item unsupported
unsupported or incomplete features		Unsupported or incomplete features.
@item all		@item all
all the warnings		Turn on all the above categories of warnings.
@item none		@item none
turn off all the warnings		Turn off all the above categories of warnings.
@item error		@item error
treat warnings as errors		Treat warnings as errors.
@end table		@end table
A category can be turned off by prefixing its name with @samp{no-}. For		A category can be turned off by prefixing its name with @samp{no-}. For
instance, @option{-Wno-syntax} will hide the warnings about unused		instance, @option{-Wno-syntax} will hide the warnings about unused
variables.		variables.
The categories output by default are @samp{obsolete}, @samp{syntax} and		Warnings in the @samp{gnu}, @samp{obsolete}, @samp{portability},
@samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}		@samp{syntax}, and @samp{unsupported} categories are turned on by
are enabled in @option{--gnu} and @option{--gnits} strictness.		default. The @samp{gnu} and @samp{portability} categories are turned
		off in @option{--foreign} strictness.
@c Checked by extra-portability.sh		@c Checked by extra-portability.sh
Turning off @samp{portability} will also turn off @samp{extra-portability},		Turning off @samp{portability} will also turn off @samp{extra-portability},
and similarly turning on @samp{extra-portability} will also turn on		and similarly turning on @samp{extra-portability} will also turn on
@samp{portability}. However, turning on @samp{portability} or turning		@samp{portability}. However, turning on @samp{portability} or turning
off @samp{extra-portability} will not affect the other category.		off @samp{extra-portability} will not affect the other category.
		Unknown warning categories supplied as an argument to @option{-W} will
		themselves produce a warning, in the @samp{unsupported} category. This
		warning is never treated as an error.
@vindex WARNINGS		@vindex WARNINGS
The environment variable @env{WARNINGS} can contain a comma separated		The environment variable @env{WARNINGS} can contain a comma separated
list of categories to enable. It will be taken into account before the		list of categories to enable. @option{-W} settings on the command line
command-line switches, this way @option{-Wnone} will also ignore any		take precedence; for instance, @option{-Wnone} also turns off any
warning category enabled by @env{WARNINGS}. This variable is also used		warning categories enabled by @env{WARNINGS}.
by other tools like @command{autoconf}; unknown categories are ignored
for this reason.		Unknown warning categories named in @env{WARNINGS} are silently ignored.
@end table		@end table
@vindex AUTOMAKE_JOBS		@vindex AUTOMAKE_JOBS
If the environment variable @env{AUTOMAKE_JOBS} contains a positive		If the environment variable @env{AUTOMAKE_JOBS} contains a positive
number, it is taken as the maximum number of Perl threads to use in		number, it is taken as the maximum number of Perl threads to use in
@command{automake} for generating multiple @file{Makefile.in} files		@command{automake} for generating multiple @file{Makefile.in} files
concurrently. This is an experimental feature.		concurrently. This is an experimental feature.
@node configure		@node configure
skipping to change at line 4048		skipping to change at line 4142
@item AM_SILENT_RULES		@item AM_SILENT_RULES
@acindex AM_SILENT_RULES		@acindex AM_SILENT_RULES
Control the machinery for less verbose build output		Control the machinery for less verbose build output
(@pxref{Automake Silent Rules}).		(@pxref{Automake Silent Rules}).
@item AM_WITH_DMALLOC		@item AM_WITH_DMALLOC
@acindex AM_WITH_DMALLOC		@acindex AM_WITH_DMALLOC
@cindex @command{dmalloc}, support for		@cindex @command{dmalloc}, support for
@vindex WITH_DMALLOC		@vindex WITH_DMALLOC
@opindex --with-dmalloc		@opindex --with-dmalloc
Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If		Add support for the @uref{https://dmalloc.com/, Dmalloc package}. If
the user runs @command{configure} with @option{--with-dmalloc}, then		the user runs @command{configure} with @option{--with-dmalloc}, then
define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.		define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
@end table		@end table
@node Obsolete Macros		@node Obsolete Macros
@subsection Obsolete Macros		@subsection Obsolete Macros
@cindex obsolete macros		@cindex obsolete macros
@cindex autoupdate		@cindex autoupdate
skipping to change at line 4473		skipping to change at line 4567
@command{automake} will make sure the directory exists. Consequently		@command{automake} will make sure the directory exists. Consequently
@command{automake} cannot be run on such a distribution when one		@command{automake} cannot be run on such a distribution when one
directory has been omitted. One way to avoid this check is to use the		directory has been omitted. One way to avoid this check is to use the
@code{AC_SUBST} method to declare conditional directories; since		@code{AC_SUBST} method to declare conditional directories; since
@command{automake} does not know the values of @code{AC_SUBST}		@command{automake} does not know the values of @code{AC_SUBST}
variables it cannot ensure the corresponding directory exists.		variables it cannot ensure the corresponding directory exists.
@node Alternative		@node Alternative
@section An Alternative Approach to Subdirectories		@section An Alternative Approach to Subdirectories
If you've ever read Peter Miller's excellent paper,		If you've ever read Peter Miller's excellent paper, @cite{Recursive
@uref{http://miller.emu.id.au/pmiller/books/rmch/,		Make Considered Harmful}, the preceding sections on the use of make
Recursive Make Considered Harmful}, the preceding sections on the use of		recursion will probably come as unwelcome advice. For those who
make recursion will probably come as unwelcome advice. For those who
haven't read the paper, Miller's main thesis is that recursive		haven't read the paper, Miller's main thesis is that recursive
@command{make} invocations are both slow and error-prone.		@command{make} invocations are both slow and error-prone.
Automake provides sufficient cross-directory support @footnote{We		Automake provides sufficient cross-directory support @footnote{We
believe. This work is new and there are probably warts.		believe. This work is new and there are probably warts.
@xref{Introduction}, for information on reporting bugs.} to enable you		@xref{Introduction}, for information on reporting bugs.} to enable you
to write a single @file{Makefile.am} for a complex multi-directory		to write a single @file{Makefile.am} for a complex multi-directory
package.		package.
By default an installable file specified in a subdirectory will have its		By default an installable file specified in a subdirectory will have its
skipping to change at line 5108		skipping to change at line 5201
@cindex suffix @file{.la}, defined		@cindex suffix @file{.la}, defined
@cindex @file{.la} suffix, defined		@cindex @file{.la} suffix, defined
Libtool abstracts shared and static libraries into a unified concept		Libtool abstracts shared and static libraries into a unified concept
henceforth called @dfn{libtool libraries}. Libtool libraries are		henceforth called @dfn{libtool libraries}. Libtool libraries are
files using the @file{.la} suffix, and can designate a static library,		files using the @file{.la} suffix, and can designate a static library,
a shared library, or maybe both. Their exact nature cannot be		a shared library, or maybe both. Their exact nature cannot be
determined until @file{./configure} is run: not all platforms support		determined until @file{./configure} is run: not all platforms support
all kinds of libraries, and users can explicitly select which		all kinds of libraries, and users can explicitly select which
libraries should be built. (However the package's maintainers can		libraries should be built. (However the package's maintainers can
tune the default; @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}		tune the default; @pxref{LT_INIT, , The @code{LT_INIT}
macro, libtool, The Libtool Manual}.)		macro, libtool, The Libtool Manual}.)
@cindex suffix @file{.lo}, defined		@cindex suffix @file{.lo}, defined
Because object files for shared and static libraries must be compiled		Because object files for shared and static libraries must be compiled
differently, libtool is also used during compilation. Object files		differently, libtool is also used during compilation. Object files
built by libtool are called @dfn{libtool objects}: these are files		built by libtool are called @dfn{libtool objects}: these are files
using the @file{.lo} suffix. Libtool libraries are built from these		using the @file{.lo} suffix. Libtool libraries are built from these
libtool objects.		libtool objects.
You should not assume anything about the structure of @file{.la} or		You should not assume anything about the structure of @file{.la} or
skipping to change at line 6578		skipping to change at line 6671
@cindex Mixing Fortran 77 with C and C++		@cindex Mixing Fortran 77 with C and C++
@cindex Linking Fortran 77 with C and C++		@cindex Linking Fortran 77 with C and C++
@cindex cfortran		@cindex cfortran
@cindex Mixing Fortran 77 with C and/or C++		@cindex Mixing Fortran 77 with C and/or C++
Automake currently provides @emph{limited} support for creating programs		Automake currently provides @emph{limited} support for creating programs
and shared libraries that are a mixture of Fortran 77 and C and/or C++.		and shared libraries that are a mixture of Fortran 77 and C and/or C++.
However, there are many other issues related to mixing Fortran 77 with		However, there are many other issues related to mixing Fortran 77 with
other languages that are @emph{not} (currently) handled by Automake, but		other languages that are @emph{not} (currently) handled by Automake, but
that are handled by other packages@footnote{For example,		that are handled by other packages@footnote{For example,
@uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}		@uref{https://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
addresses all of these inter-language issues, and runs under nearly all		addresses all of these inter-language issues, and runs under nearly all
Fortran 77, C and C++ compilers on nearly all platforms. However,		Fortran 77, C and C++ compilers on nearly all platforms. However,
@command{cfortran} is not yet Free Software, but it will be in the next		@command{cfortran} is not yet Free Software, but it will be in the next
major release.}.		major release.}.
Automake can help in two ways:		Automake can help in two ways:
@enumerate		@enumerate
@item		@item
Automatic selection of the linker depending on which combinations of		Automatic selection of the linker depending on which combinations of
skipping to change at line 6811		skipping to change at line 6904
the @code{_LDFLAGS} variable for the program.		the @code{_LDFLAGS} variable for the program.
@node Vala Support		@node Vala Support
@comment node-name, next, previous, up		@comment node-name, next, previous, up
@section Vala Support		@section Vala Support
@cindex Vala Support		@cindex Vala Support
@cindex Support for Vala		@cindex Support for Vala
Automake provides initial support for Vala		Automake provides initial support for Vala
(@uref{http://www.vala-project.org/}).		(@uref{https://www.vala-project.org/}).
This requires valac version 0.7.0 or later, and currently requires		This requires valac version 0.7.0 or later, and currently requires
the user to use GNU @command{make}.		the user to use GNU @command{make}.
@example		@example
foo_SOURCES = foo.vala bar.vala zardoc.c		foo_SOURCES = foo.vala bar.vala zardoc.c
@end example		@end example
Any @file{.vala} file listed in a @code{_SOURCES} variable will be		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		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.		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}		Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
that will locate the Vala compiler and optionally check its version		that will locate the Vala compiler and optionally check its version
number.		number.
@defmac AM_PROG_VALAC (@ovar{minimum-version}, @ovar{action-if-found},		@defmac AM_PROG_VALAC (@ovar{minimum-version}, @ovar{action-if-found},
@ovar{action-if-not-found})		@ovar{action-if-not-found})
Search for a Vala compiler in @env{PATH}. If it is found, the variable		Search for a Vala compiler in @env{PATH}. If it is found, the variable
@code{VALAC} is set to point to it (see below for more details). This		@code{VALAC} is set to point to it (see below for more details). This
macro takes three optional arguments. The first argument, if present,		macro takes three optional arguments. The first argument, if present,
is the minimum version of the Vala compiler required to compile this		is the minimum version of the Vala API required to compile this package.
package. If a compiler is found and satisfies @var{minimum-version},		For Vala releases, this is the same as the major and minor release
then @var{action-if-found} is run (this defaults to do nothing).		number; e.g., when @code{valac --version} reports @code{0.48.7},
Otherwise, @var{action-if-not-found} is run. If @var{action-if-not-found}		@code{valac --api-version} reports @code{0.48}. If a compiler is found
is not specified, the default value is to print a warning in case no		and satisfies @var{minimum-version}, then @var{action-if-found} is run
compiler is found, or if a too-old version of the compiler is found.		(this defaults to do nothing). Otherwise, @var{action-if-not-found} is
		run. If @var{action-if-not-found} is not specified, the default value
		is to print a warning in case no compiler is found, or if a too-old
		version of the compiler is found.
@end defmac		@end defmac
There are a few variables that are used when compiling Vala sources:		There are a few variables that are used when compiling Vala sources:
@vtable @code		@vtable @code
@item VALAC		@item VALAC
Absolute path to the Vala compiler, or simply @samp{valac} if no		Absolute path to the Vala compiler, or simply @samp{valac} if no
suitable Vala compiler could be found at configure runtime.		suitable Vala compiler could be found at configure runtime.
@item VALAFLAGS		@item VALAFLAGS
skipping to change at line 7217		skipping to change at line 7313
It's a different story if @file{foo.h} doesn't exist by the first		It's a different story if @file{foo.h} doesn't exist by the first
@command{make} run. For instance, there might be a rule to build		@command{make} run. For instance, there might be a rule to build
@file{foo.h}. This time @file{file.o}'s build will fail because the		@file{foo.h}. This time @file{file.o}'s build will fail because the
compiler can't find @file{foo.h}. @command{make} failed to trigger the		compiler can't find @file{foo.h}. @command{make} failed to trigger the
rule to build @file{foo.h} first by lack of dependency information.		rule to build @file{foo.h} first by lack of dependency information.
@vindex BUILT_SOURCES		@vindex BUILT_SOURCES
@cindex @code{BUILT_SOURCES}, defined		@cindex @code{BUILT_SOURCES}, defined
The @code{BUILT_SOURCES} variable is a workaround for this problem. A		The @code{BUILT_SOURCES} variable is a workaround for this problem. A
source file listed in @code{BUILT_SOURCES} is made on @samp{make all}		source file listed in @code{BUILT_SOURCES} is made when @samp{make
or @samp{make check} (or even @samp{make install}) before other		all}, @samp{make check}, @samp{make install}, @samp{make install-exec}
targets are processed. However, such a source file is not		(or @code{make dist}) is run, before other targets are processed.
@emph{compiled} unless explicitly requested by mentioning it in some		However, such a source file is not @emph{compiled} unless explicitly
other @code{_SOURCES} variable.		requested by mentioning it in some other @code{_SOURCES} variable.
So, to conclude our introductory example, we could use		So, to conclude our introductory example, we could use
@samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before		@samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
any other target (including @file{foo.o}) during @samp{make all} or		any other target (including @file{foo.o}) during @samp{make all} or
@samp{make check}.		@samp{make check}.
@code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which		@code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
must be created early in the build process can be listed in this		must be created early in the build process can be listed in this
variable. Moreover, all built sources do not necessarily have to be		variable. Moreover, all built sources do not necessarily have to be
listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file		listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by		doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
another source), because it's a known dependency of the associated		another source), because it's a known dependency of the associated
object.		object.
It might be important to emphasize that @code{BUILT_SOURCES} is		To emphasize, @code{BUILT_SOURCES} is honored only by @samp{make all},
honored only by @samp{make all}, @samp{make check} and @samp{make		@samp{make check}, @samp{make install}, and @code{make install-exec}
install}. This means you cannot build a specific target (e.g.,		(and @samp{make dist}). This means you cannot build an arbitrary
@samp{make foo}) in a clean tree if it depends on a built source.		target (e.g., @samp{make foo}) in a clean tree if it depends on a
However it will succeed if you have run @samp{make all} earlier,		built source. However it will succeed if you have run @samp{make all}
because accurate dependencies are already available.		earlier, because accurate dependencies are already available.
The next section illustrates and discusses the handling of built sources		The next section illustrates and discusses the handling of built sources
on a toy example.		on a toy example.
@menu		@menu
* Built Sources Example:: Several ways to handle built sources.		* Built Sources Example:: Several ways to handle built sources.
@end menu		@end menu
@node Built Sources Example		@node Built Sources Example
@subsection Built Sources Example		@subsection Built Sources Example
skipping to change at line 7710		skipping to change at line 7806
as follows.		as follows.
@example		@example
AM_PATH_PYTHON(,, [:])		AM_PATH_PYTHON(,, [:])
AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])		AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
@end example		@end example
@item PYTHON_VERSION		@item PYTHON_VERSION
The Python version number, in the form @var{major}.@var{minor}		The Python version number, in the form @var{major}.@var{minor}
(e.g., @samp{2.5}). This is currently the value of		(e.g., @samp{2.5}). This is currently the value of
@samp{sys.version[:3]}.		@samp{'%u.%u' % sys.version_info[:2]}.
@item PYTHON_PREFIX		@item PYTHON_PREFIX
The string @samp{$@{prefix@}}. This term may be used in future work		The string @samp{$@{prefix@}}. This term may be used in future work
that needs the contents of Python's @samp{sys.prefix}, but general		that needs the contents of Python's @samp{sys.prefix}, but general
consensus is to always use the value from @command{configure}.		consensus is to always use the value from @command{configure}.
@item PYTHON_EXEC_PREFIX		@item PYTHON_EXEC_PREFIX
The string @samp{$@{exec_prefix@}}. This term may be used in future work		The string @samp{$@{exec_prefix@}}. This term may be used in future work
that needs the contents of Python's @samp{sys.exec_prefix}, but general		that needs the contents of Python's @samp{sys.exec_prefix}, but general
consensus is to always use the value from @command{configure}.		consensus is to always use the value from @command{configure}.
skipping to change at line 7974		skipping to change at line 8070
@item TEXI2PDF		@item TEXI2PDF
The name of the command that translates a @file{.texi} file into a		The name of the command that translates a @file{.texi} file into a
@file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.		@file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
@item DVIPS		@item DVIPS
The name of the command that builds a @file{.ps} file out of a		The name of the command that builds a @file{.ps} file out of a
@file{.dvi} file. This defaults to @samp{dvips}.		@file{.dvi} file. This defaults to @samp{dvips}.
@item TEXINFO_TEX		@item TEXINFO_TEX
If your package has Texinfo files in many directories, you can use the		If your package has Texinfo files in many directories, you can use the
variable @code{TEXINFO_TEX} to tell Automake where to find the canonical		variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
@file{texinfo.tex} for your package. The value of this variable should		@file{texinfo.tex} for your package. The value of this variable should
be the relative path from the current @file{Makefile.am} to		be the relative path from the current @file{Makefile.am} to
@file{texinfo.tex}:		@file{texinfo.tex}:
@example		@example
TEXINFO_TEX = ../doc/texinfo.tex		TEXINFO_TEX = ../doc/texinfo.tex
@end example		@end example
@end vtable		@end vtable
skipping to change at line 8344		skipping to change at line 8439
@vindex PACKAGE		@vindex PACKAGE
@vindex VERSION		@vindex VERSION
@trindex dist		@trindex dist
The @code{dist} rule in the generated @file{Makefile.in} can be used		The @code{dist} rule in the generated @file{Makefile.in} can be used
to generate a gzipped @code{tar} file and other flavors of archive for		to generate a gzipped @code{tar} file and other flavors of archive for
distribution. The file is named based on the @code{PACKAGE} and		distribution. The file is named based on the @code{PACKAGE} and
@code{VERSION} variables automatically defined by either the		@code{VERSION} variables automatically defined by either the
@code{AC_INIT} invocation or by a @emph{deprecated} two-arguments		@code{AC_INIT} invocation or by a @emph{deprecated} two-arguments
invocation of the @code{AM_INIT_AUTOMAKE} macro (see @ref{Public Macros}		invocation of the @code{AM_INIT_AUTOMAKE} macro (see @ref{Public Macros}
for how these variables get their values, from either defaults or explicit		for how these variables get their values, from either defaults or explicit
values -- it's slightly trickier than one would expect).		values---it's slightly trickier than one would expect).
More precisely the gzipped @code{tar} file is named		More precisely the gzipped @code{tar} file is named
@samp{$@{PACKAGE@}-$@{VERSION@}.tar.gz}.		@samp{$@{PACKAGE@}-$@{VERSION@}.tar.gz}.
@vindex GZIP_ENV		@vindex GZIP_ENV
You can use the @command{make} variable @code{GZIP_ENV} to control how gzip		You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
is run. The default setting is @option{--best}.		is run. The default setting is @option{--best}.
		@c See automake #9822.
		@vindex TAR
		You can set the environment variable @code{TAR} to override the tar
		program used; it defaults to @code{tar}.
@cindex @code{m4_include}, distribution		@cindex @code{m4_include}, distribution
@cindex @code{include}, distribution		@cindex @code{include}, distribution
@acindex m4_include		@acindex m4_include
@cmindex include		@cmindex include
For the most part, the files to distribute are automatically found by		For the most part, the files to distribute are automatically found by
Automake: all source files are automatically included in a distribution,		Automake: all source files are automatically included in a distribution,
as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also		as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
has a built-in list of commonly used files that are automatically		has a built-in list of commonly used files that are automatically
included if they are found in the current directory (either physically,		included if they are found in the current directory (either physically,
or as the target of a @file{Makefile.am} rule); this list is printed by		or as the target of a @file{Makefile.am} rule); this list is printed by
skipping to change at line 8437		skipping to change at line 8538
Occasionally it is useful to be able to change the distribution before		Occasionally it is useful to be able to change the distribution before
it is packaged up. If the @code{dist-hook} rule exists, it is run		it is packaged up. If the @code{dist-hook} rule exists, it is run
after the distribution directory is filled, but before the actual		after the distribution directory is filled, but before the actual
distribution archives are created. One way to use this is for		distribution archives are created. One way to use this is for
removing unnecessary files that get recursively included by specifying		removing unnecessary files that get recursively included by specifying
a directory in @code{EXTRA_DIST}:		a directory in @code{EXTRA_DIST}:
@example		@example
EXTRA_DIST = doc		EXTRA_DIST = doc
dist-hook:		dist-hook:
		chmod -R u+w $(distdir)/doc
rm -rf `find $(distdir)/doc -type d -name .svn`		rm -rf `find $(distdir)/doc -type d -name .svn`
@end example		@end example
@c The caveats described here should be documented in 'disthook.sh'.		@c The caveats described here should be documented in 'disthook.sh'.
@noindent		@noindent
Note that the @code{dist-hook} recipe shouldn't assume that the regular		Note that the @code{dist-hook} recipe shouldn't assume that the regular
files in the distribution directory are writable; this might not be the		files in the distribution directory are writable; this might not be the
case if one is packaging from a read-only source tree, or when a		case if one is packaging from a read-only source tree, or when a
@code{make distcheck} is being done. For similar reasons, the recipe		@code{make distcheck} is being done. For similar reasons, the recipe
shouldn't assume that the subdirectories put into the distribution		shouldn't assume that the subdirectories put into the distribution
directory as an effect of having them listed in @code{EXTRA_DIST} are		directory as an effect of having them listed in @code{EXTRA_DIST} are
writable. So, if the @code{dist-hook} recipe wants to modify the		writable. So, if the @code{dist-hook} recipe wants to modify the
content of an existing file (or @code{EXTRA_DIST} subdirectory) in the		content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
distribution directory, it should explicitly to make it writable first:		distribution directory, it should explicitly to make it writable first:
@example		@example
EXTRA_DIST = README doc		EXTRA_DIST = README doc
dist-hook:		dist-hook:
chmod u+w $(distdir)/README $(distdir)/doc		chmod u+w $(distdir)/README $(distdir)/doc
echo "Distribution date: `date`" >> README		echo "Distribution date: `date`" >> $(distdir)/README
rm -f $(distdir)/doc/HACKING		rm -f $(distdir)/doc/HACKING
@end example		@end example
@vindex distdir		@vindex distdir
@vindex top_distdir		@vindex top_distdir
Two variables that come handy when writing @code{dist-hook} rules are		Two variables that come handy when writing @code{dist-hook} rules are
@samp{$(distdir)} and @samp{$(top_distdir)}.		@samp{$(distdir)} and @samp{$(top_distdir)}.
@samp{$(distdir)} points to the directory where the @code{dist} rule		@samp{$(distdir)} points to the directory where the @code{dist} rule
will copy files from the current directory before creating the		will copy files from the current directory before creating the
skipping to change at line 8492		skipping to change at line 8594
dist} was run, not to any sub-packages involved.		dist} was run, not to any sub-packages involved.
@node Checking the Distribution		@node Checking the Distribution
@section Checking the Distribution		@section Checking the Distribution
@cindex @samp{make distcheck}		@cindex @samp{make distcheck}
@trindex distcheck		@trindex distcheck
Automake also generates a @code{distcheck} rule that can be of help		Automake also generates a @code{distcheck} rule that can be of help
to ensure that a given distribution will actually work. Simplifying		to ensure that a given distribution will actually work. Simplifying
a bit, we can say this rule first makes a distribution, and then,		a bit, we can say this rule first makes a distribution, and then,
@emph{operating from it}, takes the following steps:		@emph{operating from it}, takes the following steps (in this order):
@itemize		@itemize
@item		@item
tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the		tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
@code{srcdir} and all its content made @emph{read-only};		@code{srcdir} and all its content made @emph{read-only};
@item		@item
		tries to make the printable documentation, if any (with @command{make dvi}),
		@item
runs the test suite (with @command{make check}) on this fresh build;		runs the test suite (with @command{make check}) on this fresh build;
@item		@item
installs the package in a temporary directory (with @command{make		installs the package in a temporary directory (with @command{make
install}), and runs the test suite on the resulting installation		install}), and runs the test suite on the resulting installation
(with @command{make installcheck});		(with @command{make installcheck});
@item		@item
checks that the package can be correctly uninstalled (by @command{make		checks that the package can be correctly uninstalled (by @command{make
uninstall}) and cleaned (by @code{make distclean});		uninstall}) and cleaned (by @code{make distclean});
@item		@item
finally, makes another tarball to ensure the distribution is		finally, makes another tarball to ensure the distribution is
self-contained.		self-contained.
@end itemize		@end itemize
All of these actions are performed in a temporary directory. Please		All of these actions are performed in a temporary directory. The
note that the exact location and the exact structure of such a directory		exact location and the exact structure of such a directory (where the
(where the read-only sources are placed, how the temporary build and		read-only sources are placed, how the temporary build and install
install directories are named and how deeply they are nested, etc.) is		directories are named and how deeply they are nested, etc.) is to be
to be considered an implementation detail, which can change at any time;		considered an implementation detail, which can change at any time; so
so do not rely on it.		do not rely on it.
@vindex AM_DISTCHECK_CONFIGURE_FLAGS		@vindex AM_DISTCHECK_CONFIGURE_FLAGS
@vindex DISTCHECK_CONFIGURE_FLAGS		@vindex DISTCHECK_CONFIGURE_FLAGS
@subheading DISTCHECK_CONFIGURE_FLAGS		@subheading DISTCHECK_CONFIGURE_FLAGS
Building the package involves running @samp{./configure}. If you need		Building the package involves running @samp{./configure}. If you need
to supply additional flags to @command{configure}, define them in the		to supply additional flags to @command{configure}, define them in the
@code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level		@code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
@file{Makefile.am}. The user can still extend or override the flags		@file{Makefile.am}. The user can still extend or override the flags
provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,		provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
on the command line when invoking @command{make}.		on the command line when invoking @command{make}.
skipping to change at line 8550		skipping to change at line 8654
default with its experimental and seldom used "changeword" feature		default with its experimental and seldom used "changeword" feature
disabled; so in this case it is useful to have @command{make distcheck}		disabled; so in this case it is useful to have @command{make distcheck}
run configure with the @option{--with-changeword} option, to ensure that		run configure with the @option{--with-changeword} option, to ensure that
the code for changeword support still compiles correctly.		the code for changeword support still compiles correctly.
GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}		GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
variable to stress-test the use of @option{--program-prefix=g}, since at		variable to stress-test the use of @option{--program-prefix=g}, since at
one point the @command{m4} build system had a bug where @command{make		one point the @command{m4} build system had a bug where @command{make
installcheck} was wrongly assuming it could blindly test "@command{m4}",		installcheck} was wrongly assuming it could blindly test "@command{m4}",
rather than the just-installed "@command{gm4}".		rather than the just-installed "@command{gm4}".
		@trindex dvi
		@subheading dvi and distcheck
		@cindex @code{eps} images
		Ordinarily, @command{make distcheck} runs @command{make dvi}. It does
		nothing if the distribution contains no Texinfo sources. If the
		distribution does contain a Texinfo manual, by default the @code{dvi}
		target will run @TeX{} to make sure it can be successfully processed
		(@pxref{Texinfo}).
		However, you may wish to test the manual by producing @code{pdf}
		(e.g., if your manual uses images in formats other than @code{eps}),
		@code{html} (if you don't have @TeX{} at all), some other format, or
		just skip the test entirely (not recommended). You can change the
		target that is run by setting the variable
		@code{AM_DISTCHECK_DVI_TARGET} in your @code{Makefile.am}; for
		example,
		@example
		AM_DISTCHECK_DVI_TARGET = pdf
		@end example
		To make @code{dvi} into a do-nothing target, see the example for
		@code{EMPTY_AUTOMAKE_TARGETS} in @ref{Third-Party Makefiles}.
@trindex distcheck-hook		@trindex distcheck-hook
@subheading distcheck-hook		@subheading distcheck-hook
If the @code{distcheck-hook} rule is defined in your top-level		If the @code{distcheck-hook} rule is defined in your top-level
@file{Makefile.am}, then it will be invoked by @code{distcheck} after		@file{Makefile.am}, then it will be invoked by @code{distcheck} after
the new distribution has been unpacked, but before the unpacked copy		the new distribution has been unpacked, but before the unpacked copy
is configured and built. Your @code{distcheck-hook} can do almost		is configured and built. Your @code{distcheck-hook} can do almost
anything, though as always caution is advised. Generally this hook is		anything, though as always caution is advised. Generally this hook is
used to check for potential distribution errors not caught by the		used to check for potential distribution errors not caught by the
standard mechanism. Note that @code{distcheck-hook} as well as		standard mechanism. Note that @code{distcheck-hook} as well as
@code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}		@code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
skipping to change at line 8772		skipping to change at line 8900
@cindex test failure		@cindex test failure
A test is said to @emph{pass} when it can determine that the condition or		A test is said to @emph{pass} when it can determine that the condition or
behaviour it means to verify holds, and is said to @emph{fail} when it can		behaviour it means to verify holds, and is said to @emph{fail} when it can
determine that such condition of behaviour does @emph{not} hold.		determine that such condition of behaviour does @emph{not} hold.
@cindex test skip		@cindex test skip
Sometimes, tests can rely on non-portable tools or prerequisites, or		Sometimes, tests can rely on non-portable tools or prerequisites, or
simply make no sense on a given system (for example, a test checking a		simply make no sense on a given system (for example, a test checking a
Windows-specific feature makes no sense on a GNU/Linux system). In this		Windows-specific feature makes no sense on a GNU/Linux system). In this
case, accordingly to the definition above, the tests can neither be		case, accordingly to the definition above, the tests can neither be
considered passed nor failed; instead, they are @emph{skipped} -- i.e.,		considered passed nor failed; instead, they are @emph{skipped}- --i.e.,
they are not run, or their result is anyway ignored for what concerns		they are not run, or their result is anyway ignored for what concerns
the count of failures and successes. Skips are usually explicitly		the count of failures and successes. Skips are usually explicitly
reported though, so that the user will be aware that not all of the		reported though, so that the user will be aware that not all of the
testsuite has really run.		testsuite has really run.
@cindex xfail		@cindex xfail
@cindex expected failure		@cindex expected failure
@cindex expected test failure		@cindex expected test failure
@cindex xpass		@cindex xpass
@cindex unexpected pass		@cindex unexpected pass
skipping to change at line 8830		skipping to change at line 8958
Test scripts can be executed serially or concurrently. Automake supports		Test scripts can be executed serially or concurrently. Automake supports
both these kinds of test execution, with the parallel test harness being		both these kinds of test execution, with the parallel test harness being
the default. The concurrent test harness relies on the concurrence		the default. The concurrent test harness relies on the concurrence
capabilities (if any) offered by the underlying @command{make}		capabilities (if any) offered by the underlying @command{make}
implementation, and can thus only be as good as those are.		implementation, and can thus only be as good as those are.
By default, only the exit statuses of the test scripts are considered when		By default, only the exit statuses of the test scripts are considered when
determining the testsuite outcome. But Automake allows also the use of		determining the testsuite outcome. But Automake allows also the use of
more complex test protocols, either standard (@pxref{Using the TAP test		more complex test protocols, either standard (@pxref{Using the TAP test
protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can't		protocol}) or custom (@pxref{Custom Test Drivers}). You can't
enable such protocols when the serial harness is used, though.		enable such protocols when the serial harness is used, though.
In the rest of this section we are going to concentrate mostly on		In the rest of this section we are going to concentrate mostly on
protocol-less tests, since we cover test protocols in a later section		protocol-less tests, since we cover test protocols in a later section
(again, @pxref{Custom Test Drivers}).		(again, @pxref{Custom Test Drivers}).
@cindex Exit status 77, special interpretation		@cindex Exit status 77, special interpretation
@cindex Exit status 99, special interpretation		@cindex Exit status 99, special interpretation
When no test protocol is in use, an exit status of 0 from a test script will		When no test protocol is in use, an exit status of 0 from a test script will
denote a success, an exit status of 77 a skipped test, an exit status of 99		denote a success, an exit status of 77 a skipped test, an exit status of 99
a hard error, and any other exit status will denote a failure.		a hard error, and any other exit status will denote a failure.
skipping to change at line 8888		skipping to change at line 9016
SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted		SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
PASS: zardoz.tap 4 - Daemon stopped		PASS: zardoz.tap 4 - Daemon stopped
SKIP: bar.sh		SKIP: bar.sh
PASS: mu.tap 1		PASS: mu.tap 1
XFAIL: mu.tap 2 # TODO frobnication not yet implemented		XFAIL: mu.tap 2 # TODO frobnication not yet implemented
@end example		@end example
@noindent		@noindent
A testsuite summary (expected to report at least the number of run,		A testsuite summary (expected to report at least the number of run,
skipped and failed tests) will be printed at the end of the testsuite		skipped and failed tests) will be printed at the end of the testsuite
run.		run. By default, the first line of the summary has the form:
		@example
		Testsuite summary for @var{package-string}
		@end example
		@c See automake bug#11745.
		@vindex AM_TESTSUITE_SUMMARY_HEADER
		@noindent
		where @var{package-string} is the name and version of the package. If
		you have several independent test suites for different parts of the
		package, though, it can be misleading for each suite to imply it is
		for the whole package. Or, in complex projects, you may wish to add
		the current directory or other information to the testsuite header
		line. So you can override the @samp{ for @var{package-string}} suffix
		on that line by setting the @code{AM_TESTSUITE_SUMMARY_HEADER}
		variable. The value of this variable is used unquoted in a shell echo
		command, so you must include any necessary quotes. For example, the
		default value is
		@example
		AM_TESTSUITE_SUMMARY_HEADER = ' for $(PACKAGE_STRING)'
		@end example
		@noindent
		including the double quotes (interpreted by the shell) and the leading
		space (since the value is output directly after the @samp{Testsuite
		summary}). The @code{$(PACKAGE_STRING)} is substituted by @code{make}.
@anchor{Simple tests and color-tests}		@anchor{Simple tests and color-tests}
@vindex AM_COLOR_TESTS		@vindex AM_COLOR_TESTS
@cindex Colorized testsuite output		@cindex Colorized testsuite output
If the standard output is connected to a capable terminal, then the test		If the standard output is connected to a capable terminal, then the test
results and the summary are colored appropriately. The developer and the		results and the summary are colored appropriately. The developer and the
user can disable colored output by setting the @command{make} variable		user can disable colored output by setting the @command{make} variable
@samp{AM_COLOR_TESTS=no}; the user can in addition force colored output		@samp{AM_COLOR_TESTS=no}; the user can in addition force colored output
even without a connecting terminal with @samp{AM_COLOR_TESTS=always}.		even without a connecting terminal with @samp{AM_COLOR_TESTS=always}.
It's also worth noting that some @command{make} implementations,		It's also worth noting that some @command{make} implementations,
skipping to change at line 9594		skipping to change at line 9749
``TAP producers'' in this context) write test results in a simple format		``TAP producers'' in this context) write test results in a simple format
on standard output; a test harness (also called ``TAP consumer'') will		on standard output; a test harness (also called ``TAP consumer'') will
parse and interpret these results, and properly present them to the user,		parse and interpret these results, and properly present them to the user,
and/or register them for later analysis. The exact details of how this		and/or register them for later analysis. The exact details of how this
is accomplished can vary among different test harnesses. The Automake		is accomplished can vary among different test harnesses. The Automake
harness will present the results on the console in the usual		harness will present the results on the console in the usual
fashion (@pxref{Testsuite progress on console}), and will use the		fashion (@pxref{Testsuite progress on console}), and will use the
@file{.trs} files (@pxref{Basics of test metadata}) to store the test		@file{.trs} files (@pxref{Basics of test metadata}) to store the test
results and related metadata. Apart from that, it will try to remain		results and related metadata. Apart from that, it will try to remain
as compatible as possible with pre-existing and widespread utilities,		as compatible as possible with pre-existing and widespread utilities,
such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,		such as the
		@uref{https://metacpan.org/pod/distribution/Test-Harness/bin/prove,
@command{prove} utility}, at least for the simpler usages.		@command{prove} utility}, at least for the simpler usages.
TAP started its life as part of the test harness for Perl, but today		TAP started its life as part of the test harness for Perl, but today
it has been (mostly) standardized, and has various independent		it has been (mostly) standardized, and has various independent
implementations in different languages; among them, C, C++, Perl,		implementations in different languages; among them, C, C++, Perl,
Python, PHP, and Java. For a semi-official specification of the		Python, PHP, and Java. For a semi-official specification of the
TAP protocol, please refer to the documentation of		TAP protocol, please refer to the documentation of
@uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,		@uref{https://metacpan.org/pod/Test::Harness, @samp{Test::Harness}}.
@samp{Test::Harness::TAP}}.
The most relevant real-world usages of TAP are obviously in the testsuites		The most relevant real-world usages of TAP are obviously in the testsuites
of @command{perl} and of many perl modules. Still, other important		of @command{perl} and of many Perl modules. Still, other important
third-party packages, such as @uref{http://git-scm.com/, @command{git}},		third-party packages, such as @uref{https://git-scm.com/, @command{git}},
also use TAP in their testsuite.		also use TAP in their testsuite.
@node Use TAP with the Automake test harness		@node Use TAP with the Automake test harness
@subsection Use TAP with the Automake test harness		@subsection Use TAP with the Automake test harness
Currently, the TAP driver that comes with Automake requires some by-hand		Currently, the TAP driver that comes with Automake requires some by-hand
steps on the developer's part (this situation should hopefully be improved		steps on the developer's part (this situation should hopefully be improved
in future Automake versions). You'll have to grab the @file{tap-driver.sh}		in future Automake versions). You'll have to grab the @file{tap-driver.sh}
script from the Automake distribution by hand, copy it in your source tree,		script from the Automake distribution by hand, copy it in your source tree,
and use the Automake support for third-party test drivers to instruct the		and use the Automake support for third-party test drivers to instruct the
skipping to change at line 9775		skipping to change at line 9930
@node Links and external resources on TAP		@node Links and external resources on TAP
@subsection Links and external resources on TAP		@subsection Links and external resources on TAP
@noindent		@noindent
Here are some links to more extensive official or third-party		Here are some links to more extensive official or third-party
documentation and resources about the TAP protocol and related		documentation and resources about the TAP protocol and related
tools and libraries.		tools and libraries.
@itemize @bullet		@itemize @bullet
@item		@item
@uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,		@uref{https://metacpan.org/pod/Test::Harness, @samp{Test::Harness}},
@samp{Test::Harness::TAP}},
the (mostly) official documentation about the TAP format and protocol.		the (mostly) official documentation about the TAP format and protocol.
@item		@item
@uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,		@uref{https://metacpan.org/pod/distribution/Test-Harness/bin/prove,
@command{prove}},		@command{prove}},
the most famous command-line TAP test driver, included in the distribution		the most famous command-line TAP test driver, included in the distribution
of @command{perl} and		of @command{perl} and
@uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,		@uref{https://metacpan.org/pod/distribution/Test-Harness/lib/Test/Harness.pm,
@samp{Test::Harness}}.		@samp{Test::Harness}}.
@item		@item
The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.		The @uref{https://testanything.org/,TAP wiki}.
@item		@item
A ``gentle introduction'' to testing for perl coders:		A ``gentle introduction'' to testing for Perl coders:
@uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,		@uref{https://metacpan.org/pod/distribution/Test-Simple/lib/Test/Tutorial.pod,
@samp{Test::Tutorial}}.		@samp{Test::Tutorial}}.
@item		@item
@uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,		@uref{https://metacpan.org/pod/distribution/Test-Simple/lib/Test/Simple.pm,
@samp{Test::Simple}}		@samp{Test::Simple}}
and		and
@uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,		@uref{https://metacpan.org/pod/distribution/Test-Simple/lib/Test/More.pm,
@samp{Test::More}},		@samp{Test::More}},
the standard perl testing libraries, which are based on TAP.		the standard Perl testing libraries, which are based on TAP.
@item		@item
@uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},		@uref{https://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
a C-based project implementing both a TAP producer and a TAP consumer.		a C-based project implementing both a TAP producer and a TAP consumer.
@item		@item
@uref{http://www.tap4j.org/,tap4j},		@uref{https://tap4j.org/,tap4j},
a Java-based project implementing both a TAP producer and a TAP consumer.		a Java-based project implementing both a TAP producer and a TAP consumer.
@end itemize		@end itemize
@node DejaGnu Tests		@node DejaGnu Tests
@section DejaGnu Tests		@section DejaGnu Tests
If @uref{https://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in		If @command{dejagnu} (@pxref{Top, , Introduction, dejagnu, DejaGnu})
@code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is		appears in @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based
assumed. The variable @code{DEJATOOL} is a list of names that are		test suite is assumed. The variable @code{DEJATOOL} is a list of
passed, one at a time, as the @option{--tool} argument to		names that are passed, one at a time, as the @option{--tool} argument
@command{runtest} invocations; it defaults to the name of the package.		to @command{runtest} invocations; it defaults to the name of the
		package.
The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and		The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
@option{--srcdir} flags that are passed to dejagnu by default; this can be		@option{--srcdir} flags that are passed to dejagnu by default; this can be
overridden if necessary.		overridden if necessary.
@vindex RUNTESTDEFAULTFLAGS		@vindex RUNTESTDEFAULTFLAGS
The variables @code{EXPECT} and @code{RUNTEST} can		The variables @code{EXPECT} and @code{RUNTEST} can
also be overridden to provide project-specific values. For instance,		also be overridden to provide project-specific values. For instance,
you will need to do this if you are testing a compiler toolchain,		you will need to do this if you are testing a compiler toolchain,
because the default values do not take into account host and target		because the default values do not take into account host and target
skipping to change at line 10033		skipping to change at line 10188
@item @option{gnits}		@item @option{gnits}
@itemx @option{gnu}		@itemx @option{gnu}
@itemx @option{foreign}		@itemx @option{foreign}
@cindex Option, @option{gnits}		@cindex Option, @option{gnits}
@cindex Option, @option{gnu}		@cindex Option, @option{gnu}
@cindex Option, @option{foreign}		@cindex Option, @option{foreign}
@opindex gnits		@opindex gnits
@opindex gnu		@opindex gnu
@opindex foreign		@opindex foreign
Set the strictness as appropriate. The @option{gnits} option also		Set the strictness as appropriate. @xref{Strictness}.
implies options @option{readme-alpha} and @option{check-news}.		The @option{gnits} option also implies options @option{readme-alpha} and
		@option{check-news}.
@item @option{check-news}		@item @option{check-news}
@cindex Option, @option{check-news}		@cindex Option, @option{check-news}
@opindex check-news		@opindex check-news
Cause @samp{make dist} to fail unless the current version number appears		Cause @samp{make dist} to fail unless the current version number appears
in the first few lines of the @file{NEWS} file.		in the first few lines of the @file{NEWS} file.
@item @option{dejagnu}		@item @option{dejagnu}
@cindex Option, @option{dejagnu}		@cindex Option, @option{dejagnu}
@opindex dejagnu		@opindex dejagnu
skipping to change at line 10987		skipping to change at line 11143
$(pkg_verbose)cp $(srcdir)/foo.in $@@		$(pkg_verbose)cp $(srcdir)/foo.in $@@
@end example		@end example
@end itemize		@end itemize
As a final note, observe that, even when silent rules are enabled,		As a final note, observe that, even when silent rules are enabled,
the @option{--no-print-directory} option is still required with GNU		the @option{--no-print-directory} option is still required with GNU
@command{make} if the ``@i{Entering/Leaving directory ...}'' messages		@command{make} if the ``@i{Entering/Leaving directory ...}'' messages
are to be disabled.		are to be disabled.
@node Gnits
@chapter The effect of @option{--gnu} and @option{--gnits}
@cindex @option{--gnu}, required files
@cindex @option{--gnu}, complete description
The @option{--gnu} option (or @option{gnu} in the
@code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
the following:
@itemize @bullet
@item
The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
or @file{COPYING}, are required at the topmost directory of the package.
If the @option{--add-missing} option is given, @command{automake} will
add a generic version of the @file{INSTALL} file as well as the
@file{COPYING} file containing the text of the current version of the
GNU General Public License existing at the time of this Automake release
(version 3 as this is written, @uref{https://www.gnu.org/@/copyleft/@/gpl.html})
.
However, an existing @file{COPYING} file will never be overwritten by
@command{automake}.
@item
The options @option{no-installman} and @option{no-installinfo} are
prohibited.
@end itemize
Note that this option will be extended in the future to do even more
checking; it is advisable to be familiar with the precise requirements
of the GNU standards. Also, @option{--gnu} can require certain
non-standard GNU programs to exist for use by various maintainer-only
rules; for instance, in the future @command{pathchk} might be required for
@samp{make dist}.
@cindex @option{--gnits}, complete description
The @option{--gnits} option does everything that @option{--gnu} does, and
checks the following as well:
@itemize @bullet
@item
@samp{make installcheck} will check to make sure that the @option{--help}
and @option{--version} really print a usage message and a version string,
respectively. This is the @option{std-options} option (@pxref{Options}).
@item
@samp{make dist} will check to make sure the @file{NEWS} file has been
updated to the current version.
@item
@code{VERSION} is checked to make sure its format complies with Gnits
standards.
@c FIXME xref when standards are finished
@item
@cindex @file{README-alpha}
If @code{VERSION} indicates that this is an alpha release, and the file
@file{README-alpha} appears in the topmost directory of a package, then
it is included in the distribution. This is done in @option{--gnits}
mode, and no other, because this mode is the only one where version
number formats are constrained, and hence the only mode where Automake
can automatically determine whether @file{README-alpha} should be
included.
@item
The file @file{THANKS} is required.
@end itemize
@node Not Enough		@node Not Enough
@chapter When Automake Isn't Enough		@chapter When Automake Isn't Enough
In some situations, where Automake is not up to one task, one has to		In some situations, where Automake is not up to one task, one has to
resort to handwritten rules or even handwritten @file{Makefile}s.		resort to handwritten rules or even handwritten @file{Makefile}s.
@menu		@menu
* Extending:: Adding new rules or overriding existing ones.		* Extending:: Adding new rules or overriding existing ones.
* Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.		* Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
@end menu		@end menu
skipping to change at line 11356		skipping to change at line 11442
@code{SUBDIRS} need only the @code{distclean},		@code{SUBDIRS} need only the @code{distclean},
@code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional		@code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
Subdirectories}).		Subdirectories}).
Usually, many of these rules are irrelevant to the third-party		Usually, many of these rules are irrelevant to the third-party
subproject, but they are required for the whole package to work. It's		subproject, but they are required for the whole package to work. It's
OK to have a rule that does nothing, so if you are integrating a		OK to have a rule that does nothing, so if you are integrating a
third-party project with no documentation or tag support, you could		third-party project with no documentation or tag support, you could
simply augment its @file{Makefile} as follows:		simply augment its @file{Makefile} as follows:
		@vindex EMPTY_AUTOMAKE_TARGETS
		@cindex Automake targets, no-op
		@cindex do-nothing Automake targets
		@cindex empty Automake targets
		@cindex no-op Automake targets
		@cindex targets, making into no-op
@example		@example
EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags		EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
.PHONY: $(EMPTY_AUTOMAKE_TARGETS)		.PHONY: $(EMPTY_AUTOMAKE_TARGETS)
$(EMPTY_AUTOMAKE_TARGETS):		$(EMPTY_AUTOMAKE_TARGETS):
@end example		@end example
		To be clear, there is nothing special about the variable name
		@code{EMPTY_AUTOMAKE_TARGETS}; the name could be anything.
Another aspect of integrating third-party build systems is whether		Another aspect of integrating third-party build systems is whether
they support VPATH builds (@pxref{VPATH Builds}). Obviously if the		they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
subpackage does not support VPATH builds the whole package will not		subpackage does not support VPATH builds the whole package will not
support VPATH builds. This in turns means that @samp{make distcheck}		support VPATH builds. This in turns means that @samp{make distcheck}
will not work, because it relies on VPATH builds. Some people can		will not work, because it relies on VPATH builds. Some people can
live without this (actually, many Automake users have never heard of		live without this (actually, many Automake users have never heard of
@samp{make distcheck}). Other people may prefer to revamp the		@samp{make distcheck}). Other people may prefer to revamp the
existing @file{Makefile}s to support VPATH@. Doing so does not		existing @file{Makefile}s to support VPATH@. Doing so does not
necessarily require Automake; only Autoconf is needed (@pxref{Build		necessarily require Automake; only Autoconf is needed (@pxref{Build
Directories, , Build Directories, autoconf, The Autoconf Manual}).		Directories, , Build Directories, autoconf, The Autoconf Manual}).
skipping to change at line 11790		skipping to change at line 11885
@cindex third-party files and CVS		@cindex third-party files and CVS
Another class of files not discussed here (because they do not cause		Another class of files not discussed here (because they do not cause
timestamp issues) are files that are shipped with a package, but		timestamp issues) are files that are shipped with a package, but
maintained elsewhere. For instance, tools like @command{gettextize}		maintained elsewhere. For instance, tools like @command{gettextize}
and @command{autopoint} (from Gettext) or @command{libtoolize} (from		and @command{autopoint} (from Gettext) or @command{libtoolize} (from
Libtool), will install or update files in your package.		Libtool), will install or update files in your package.
These files, whether they are kept under CVS or not, raise similar		These files, whether they are kept under CVS or not, raise similar
concerns about version mismatch between developers' tools. The		concerns about version mismatch between developers' tools. The
Gettext manual has a section about this; see @ref{CVS Issues, CVS		Gettext manual has a section about this; see @ref{Version Control Issues,,
Issues, Integrating with CVS, gettext, GNU gettext tools}.		Integrating with Version Control Systems, gettext, GNU gettext tools}.
@node maintainer-mode		@node maintainer-mode
@section @command{missing} and @code{AM_MAINTAINER_MODE}		@section @command{missing} and @code{AM_MAINTAINER_MODE}
@subheading @command{missing}		@subheading @command{missing}
@cindex @command{missing}, purpose		@cindex @command{missing}, purpose
The @command{missing} script is a wrapper around several maintainer		The @command{missing} script is a wrapper around several maintainer
tools, designed to warn users if a maintainer tool is required but		tools, designed to warn users if a maintainer tool is required but
missing. Typical maintainer tools are @command{autoconf},		missing. Typical maintainer tools are @command{autoconf},
skipping to change at line 12015		skipping to change at line 12110
files should not contain these characters.		files should not contain these characters.
Source and installation file names like @file{main.c} are limited even		Source and installation file names like @file{main.c} are limited even
further: they should conform to the POSIX/XOPEN		further: they should conform to the POSIX/XOPEN
rules described above. In addition, if you plan to port to		rules described above. In addition, if you plan to port to
non-POSIX environments, you should avoid file names that		non-POSIX environments, you should avoid file names that
differ only in case (e.g., @file{makefile} and @file{Makefile}).		differ only in case (e.g., @file{makefile} and @file{Makefile}).
Nowadays it is no longer worth worrying about the 8.3 limits of		Nowadays it is no longer worth worrying about the 8.3 limits of
DOS file systems.		DOS file systems.
@c FIXME This should probably be moved in the "Checking the Distribution"		@c FIXME This should probably be moved to the "Checking the Distribution"
@c FIXME section...		@c FIXME section...
@node Errors with distclean		@node Errors with distclean
@section Errors with distclean		@section Errors with distclean
@cindex @code{distclean}, diagnostic		@cindex @code{distclean}, diagnostic
@cindex @samp{make distclean}, diagnostic		@cindex @samp{make distclean}, diagnostic
@cindex dependencies and distributed files		@cindex dependencies and distributed files
@trindex distclean		@trindex distclean
This is a diagnostic you might encounter while running @samp{make		This is a diagnostic you might encounter while running @samp{make
distcheck}.		distcheck}.
skipping to change at line 12620		skipping to change at line 12715
@file{data.foo}, and this is already the case.		@file{data.foo}, and this is already the case.
What we need is a rule that forces a rebuild when @file{data.h} is		What we need is a rule that forces a rebuild when @file{data.h} is
missing. Here it is:		missing. Here it is:
@example		@example
data.c: data.foo		data.c: data.foo
foo data.foo		foo data.foo
data.h: data.c		data.h: data.c
## Recover from the removal of $@@		## Recover from the removal of $@@
		@@test -f $@@ || rm -f data.c
		@@test -f $@@ || $(MAKE) $(AM_MAKEFLAGS) data.c
		@end example
		It is tempting to use a single test as follows:
		@example
		data.h: data.c
		## Recover from the removal of $@@
@@if test -f $@@; then :; else \		@@if test -f $@@; then :; else \
rm -f data.c; \		rm -f data.c; \
$(MAKE) $(AM_MAKEFLAGS) data.c; \		$(MAKE) $(AM_MAKEFLAGS) data.c; \
fi		fi
@end example		@end example
		@noindent
		but that would break @samp{make -n}: at least GNU @command{make} and
		Solaris @command{make} execute recipes containing the @samp{$(MAKE)}
		string even when they are running in dry mode. So if we didn't break
		the recipe above in two invocations, the file @file{data.c} would be
		removed even upon @samp{make -n}. Not nice.
The above scheme can be extended to handle more outputs and more		The above scheme can be extended to handle more outputs and more
inputs. One of the outputs is selected to serve as a witness to the		inputs. One of the outputs is selected to serve as a witness to the
successful completion of the command, it depends upon all inputs, and		successful completion of the command, it depends upon all inputs, and
all other outputs depend upon it. For instance, if @command{foo}		all other outputs depend upon it. For instance, if @command{foo}
should additionally read @file{data.bar} and also produce		should additionally read @file{data.bar} and also produce
@file{data.w} and @file{data.x}, we would write:		@file{data.w} and @file{data.x}, we would write:
@example		@example
data.c: data.foo data.bar		data.c: data.foo data.bar
foo data.foo data.bar		foo data.foo data.bar
data.h data.w data.x: data.c		data.h data.w data.x: data.c
## Recover from the removal of $@@		## Recover from the removal of $@@
@@if test -f $@@; then :; else \		@@test -f $@@ || rm -f data.c
rm -f data.c; \		@@test -f $@@ || $(MAKE) $(AM_MAKEFLAGS) data.c
$(MAKE) $(AM_MAKEFLAGS) data.c; \
fi
@end example		@end example
However there are now three minor problems in this setup. One is related		However there are now three minor problems in this setup. One is related
to the timestamp ordering of @file{data.h}, @file{data.w},		to the timestamp ordering of @file{data.h}, @file{data.w},
@file{data.x}, and @file{data.c}. Another one is a race condition		@file{data.x}, and @file{data.c}. Another one is a race condition
if a parallel @command{make} attempts to run multiple instances of the		if a parallel @command{make} attempts to run multiple instances of the
recover block at once. Finally, the recursive rule breaks @samp{make -n}		recover block at once. Finally, the recursive rule breaks @samp{make -n}
when run with GNU @command{make} (as well as some other @command{make}		when run with GNU @command{make} (as well as some other @command{make}
implementations), as it may remove @file{data.h} even when it should not		implementations), as it may remove @file{data.h} even when it should not
(@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,		(@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
skipping to change at line 12671		skipping to change at line 12780
that is: nothing. In other words, because the witness we selected is		that is: nothing. In other words, because the witness we selected is
not the first file created by @command{foo}, @command{make} will start		not the first file created by @command{foo}, @command{make} will start
a shell to do nothing each time it is run.		a shell to do nothing each time it is run.
A simple riposte is to fix the timestamps when this happens.		A simple riposte is to fix the timestamps when this happens.
@example		@example
data.c: data.foo data.bar		data.c: data.foo data.bar
foo data.foo data.bar		foo data.foo data.bar
data.h data.w data.x: data.c		data.h data.w data.x: data.c
@@if test -f $@@; then \		@@test ! -f $@@ || touch $@@
touch $@@; \
else \
## Recover from the removal of $@@		## Recover from the removal of $@@
rm -f data.c; \		@@test -f $@@ || rm -f data.c
$(MAKE) $(AM_MAKEFLAGS) data.c; \		@@test -f $@@ || $(MAKE) $(AM_MAKEFLAGS) data.c
fi
@end example		@end example
Another solution is to use a different and dedicated file as witness,		Another solution is to use a different and dedicated file as witness,
rather than using any of @command{foo}'s outputs.		rather than using any of @command{foo}'s outputs.
@example		@example
data.stamp: data.foo data.bar		data.stamp: data.foo data.bar
@@rm -f data.tmp		@@rm -f data.tmp
@@touch data.tmp		@@touch data.tmp
foo data.foo data.bar		foo data.foo data.bar
@@mv -f data.tmp $@@		@@mv -f data.tmp $@@
data.c data.h data.w data.x: data.stamp		data.c data.h data.w data.x: data.stamp
## Recover from the removal of $@@		## Recover from the removal of $@@
@@if test -f $@@; then :; else \		@@test -f $@@ || rm -f data.stamp
rm -f data.stamp; \		@@test -f $@@ || $(MAKE) $(AM_MAKEFLAGS) data.stamp
$(MAKE) $(AM_MAKEFLAGS) data.stamp; \
fi
@end example		@end example
@file{data.tmp} is created before @command{foo} is run, so it has a		@file{data.tmp} is created before @command{foo} is run, so it has a
timestamp older than output files output by @command{foo}. It is then		timestamp older than output files output by @command{foo}. It is then
renamed to @file{data.stamp} after @command{foo} has run, because we		renamed to @file{data.stamp} after @command{foo} has run, because we
do not want to update @file{data.stamp} if @command{foo} fails.		do not want to update @file{data.stamp} if @command{foo} fails.
This solution still suffers from the second problem: the race		This solution still suffers from the second problem: the race
condition in the recover rule. If, after a successful build, a user		condition in the recover rule. If, after a successful build, a user
erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then		erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
skipping to change at line 13028		skipping to change at line 13132
that it is a bug, we want to hear about problems you encounter. Often we		that it is a bug, we want to hear about problems you encounter. Often we
agree they are bugs and want to fix them.		agree they are bugs and want to fix them.
To make it possible for us to fix a bug, please report it. In order to		To make it possible for us to fix a bug, please report it. In order to
do so effectively, it helps to know when and how to do it.		do so effectively, it helps to know when and how to do it.
Before reporting a bug, it is a good idea to see if it is already known.		Before reporting a bug, it is a good idea to see if it is already known.
You can look at the @uref{https://debbugs.gnu.org/, GNU Bug Tracker}		You can look at the @uref{https://debbugs.gnu.org/, GNU Bug Tracker}
and the @uref{https://lists.gnu.org/@/archive/@/html/@/bug-automake/,		and the @uref{https://lists.gnu.org/@/archive/@/html/@/bug-automake/,
bug-automake mailing list archives} for previous bug reports. We		bug-automake mailing list archives} for previous bug reports. We
previously used a		previously used a Gnats database for bug tracking, but it is no longer
@uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,		online.
Gnats database} for bug tracking, so some bugs might have been reported
there already. Please do not use it for new bug reports, however.
If the bug is not already known, it should be reported. It is very		If the bug is not already known, it should be reported. It is very
important to report bugs in a way that is useful and efficient. For		important to report bugs in a way that is useful and efficient. For
this, please familiarize yourself with		this, please familiarize yourself with
@uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to		@uref{https://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
Report Bugs Effectively} and		Report Bugs Effectively} and
@uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask		@uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
Questions the Smart Way}. This helps you and developers to save time,		Questions the Smart Way}. This helps you and developers to save time,
which can then be spent on fixing more bugs and implementing more		which can then be spent on fixing more bugs and implementing more
features.		features.
For a bug report, a feature request or other suggestions, please send		For a bug report, a feature request or other suggestions, please send
email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new		email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
bug in the @uref{https://debbugs.gnu.org/@/automake, bug tracker}. Be		bug in the @uref{https://debbugs.gnu.org/@/automake, bug tracker}. Be
sure to include the versions of Autoconf and Automake that you use.		sure to include the versions of Autoconf and Automake that you use.
End of changes. 96 change blocks.
218 lines changed or deleted		319 lines changed or added

---