6.4.4 Checking the Distribution

Automake also generates a distcheck rule that can be of help
to ensure that a given distribution will actually work. Simplifying
a bit, we can say this rule first makes a distribution, and then,
operating from it, takes the following steps:

tries to do a VPATH build (see VPATH Builds), with the
srcdir and all its content made read-only;

runs the test suite (with make check) on this fresh build;

installs the package in a temporary directory (with make
install), and tries runs the test suite on the resulting installation
(with make installcheck);

checks that the package can be correctly uninstalled (by make
uninstall) and cleaned (by make distclean);

finally, makes another tarball to ensure the distribution is
self-contained.

All of these actions are performed in a temporary directory. Please
note that the exact location and the exact structure of such a directory
(where the read-only sources are placed, how the temporary build and
install directories are named and how deeply they are nested, etc.) is
to be considered an implementation detail, which can change at any time;
so do not rely on it.

DISTCHECK_CONFIGURE_FLAGS

Building the package involves running ‘./configure’. If you need
to supply additional flags to configure, define them in the
AM_DISTCHECK_CONFIGURE_FLAGS variable in your top-level
Makefile.am. The user can still extend or override the flags
provided there by defining the DISTCHECK_CONFIGURE_FLAGS variable,
on the command line when invoking make.
It’s worth nothing that make distcheck needs complete control
over the configure options --srcdir and
--prefix, so those options cannot be overridden by
AM_DISTCHECK_CONFIGURE_FLAGS nor by
DISTCHECK_CONFIGURE_FLAGS.

Also note that developers are encouraged to strive to make their code
buildable without requiring any special configure option; thus, in
general, you shouldn’t define AM_DISTCHECK_CONFIGURE_FLAGS.
However, there might be few scenarios in which the use of this variable
is justified.
GNU m4 offers an example. GNU m4 configures by
default with its experimental and seldom used "changeword" feature
disabled; so in its case it is useful to have make distcheck
run configure with the --with-changeword option, to ensure that
the code for changeword support still compiles correctly.
GNU m4 also employs the AM_DISTCHECK_CONFIGURE_FLAGS
variable to stress-test the use of --program-prefix=g, since at
one point the m4 build system had a bug where make
installcheck was wrongly assuming it could blindly test "m4",
rather than the just-installed "gm4".

distcheck-hook

If the distcheck-hook rule is defined in your top-level
Makefile.am, then it will be invoked by distcheck after
the new distribution has been unpacked, but before the unpacked copy
is configured and built. Your distcheck-hook can do almost
anything, though as always caution is advised. Generally this hook is
used to check for potential distribution errors not caught by the
standard mechanism. Note that distcheck-hook as well as
AM_DISTCHECK_CONFIGURE_FLAGS and DISTCHECK_CONFIGURE_FLAGS
are not honored in a subpackage Makefile.am, but the flags from
AM_DISTCHECK_CONFIGURE_FLAGS and DISTCHECK_CONFIGURE_FLAGS
are passed down to the configure script of the subpackage.

distcleancheck

Speaking of potential distribution errors, distcheck also
ensures that the distclean rule actually removes all built
files. This is done by running ‘make distcleancheck’ at the end of
the VPATH build. By default, distcleancheck will run
distclean and then make sure the build tree has been emptied by
running ‘$(distcleancheck_listfiles)’. Usually this check will
find generated files that you forgot to add to the DISTCLEANFILES
variable (see Clean).

The distcleancheck behavior should be OK for most packages,
otherwise you have the possibility to override the definition of
either the distcleancheck rule, or the
‘$(distcleancheck_listfiles)’ variable. For instance, to disable
distcleancheck completely, add the following rule to your
top-level Makefile.am:

distcleancheck:
@:

If you want distcleancheck to ignore built files that have not
been cleaned because they are also part of the distribution, add the
following definition instead:

The above definition is not the default because it’s usually an error if
your Makefiles cause some distributed files to be rebuilt when the user
build the package. (Think about the user missing the tool required to
build the file; or if the required tool is built by your package,
consider the cross-compilation case where it can’t be run.) There is
an entry in the FAQ about this (see Errors with distclean), make
sure you read it before playing with distcleancheck_listfiles.

distuninstallcheck

distcheck also checks that the uninstall rule works
properly, both for ordinary and DESTDIR builds. It does this
by invoking ‘make uninstall’, and then it checks the install tree
to see if any files are left over. This check will make sure that you
correctly coded your uninstall-related rules.

By default, the checking is done by the distuninstallcheck rule,
and the list of files in the install tree is generated by
‘$(distuninstallcheck_listfiles)’ (this is a variable whose value is
a shell command to run that prints the list of files to stdout).

Either of these can be overridden to modify the behavior of
distcheck. For instance, to disable this check completely, you
would write: