automake: Checking the Distribution
1
1 14.4 Checking the Distribution
1 ==============================
1
1 Automake also generates a ‘distcheck’ rule that can be of help to ensure
1 that a given distribution will actually work. Simplifying a bit, we can
1 say this rule first makes a distribution, and then, _operating from it_,
1 takes the following steps:
1 • tries to do a ‘VPATH’ build (⇒VPATH Builds), with the
1 ‘srcdir’ and all its content made _read-only_;
1 • runs the test suite (with ‘make check’) on this fresh build;
1 • installs the package in a temporary directory (with ‘make
1 install’), and tries runs the test suite on the resulting
1 installation (with ‘make installcheck’);
1 • checks that the package can be correctly uninstalled (by ‘make
1 uninstall’) and cleaned (by ‘make distclean’);
1 • finally, makes another tarball to ensure the distribution is
1 self-contained.
1
1 All of these actions are performed in a temporary directory. Please
1 note that the exact location and the exact structure of such a directory
1 (where the read-only sources are placed, how the temporary build and
1 install directories are named and how deeply they are nested, etc.) is
1 to be considered an implementation detail, which can change at any time;
1 so do not reply on it.
1
1 DISTCHECK_CONFIGURE_FLAGS
1 -------------------------
1
1 Building the package involves running ‘./configure’. If you need to
1 supply additional flags to ‘configure’, define them in the
1 ‘AM_DISTCHECK_CONFIGURE_FLAGS’ variable in your top-level ‘Makefile.am’.
1 The user can still extend or override the flags provided there by
1 defining the ‘DISTCHECK_CONFIGURE_FLAGS’ variable, on the command line
1 when invoking ‘make’. It’s worth noting that ‘make distcheck’ needs
1 complete control over the ‘configure’ options ‘--srcdir’ and ‘--prefix’,
1 so those options cannot be overridden by ‘AM_DISTCHECK_CONFIGURE_FLAGS’
1 nor by ‘DISTCHECK_CONFIGURE_FLAGS’.
1
1 Also note that developers are encouraged to strive to make their code
1 buildable without requiring any special configure option; thus, in
1 general, you shouldn’t define ‘AM_DISTCHECK_CONFIGURE_FLAGS’. However,
1 there might be few scenarios in which the use of this variable is
1 justified. GNU ‘m4’ offers an example. GNU ‘m4’ configures by default
1 with its experimental and seldom used "changeword" feature disabled; so
1 in its case it is useful to have ‘make distcheck’ run configure with the
1 ‘--with-changeword’ option, to ensure that the code for changeword
1 support still compiles correctly. GNU ‘m4’ also employs the
1 ‘AM_DISTCHECK_CONFIGURE_FLAGS’ variable to stress-test the use of
1 ‘--program-prefix=g’, since at one point the ‘m4’ build system had a bug
1 where ‘make installcheck’ was wrongly assuming it could blindly test
1 "‘m4’", rather than the just-installed "‘gm4’".
1
1 distcheck-hook
1 --------------
1
1 If the ‘distcheck-hook’ rule is defined in your top-level ‘Makefile.am’,
1 then it will be invoked by ‘distcheck’ after the new distribution has
1 been unpacked, but before the unpacked copy is configured and built.
1 Your ‘distcheck-hook’ can do almost anything, though as always caution
1 is advised. Generally this hook is used to check for potential
1 distribution errors not caught by the standard mechanism. Note that
1 ‘distcheck-hook’ as well as ‘AM_DISTCHECK_CONFIGURE_FLAGS’ and
1 ‘DISTCHECK_CONFIGURE_FLAGS’ are not honored in a subpackage
1 ‘Makefile.am’, but the flags from ‘AM_DISTCHECK_CONFIGURE_FLAGS’ and
1 ‘DISTCHECK_CONFIGURE_FLAGS’ are passed down to the ‘configure’ script of
1 the subpackage.
1
1 distcleancheck
1 --------------
1
1 Speaking of potential distribution errors, ‘distcheck’ also ensures that
1 the ‘distclean’ rule actually removes all built files. This is done by
1 running ‘make distcleancheck’ at the end of the ‘VPATH’ build. By
1 default, ‘distcleancheck’ will run ‘distclean’ and then make sure the
1 build tree has been emptied by running ‘$(distcleancheck_listfiles)’.
1 Usually this check will find generated files that you forgot to add to
1 the ‘DISTCLEANFILES’ variable (⇒Clean).
1
1 The ‘distcleancheck’ behavior should be OK for most packages,
1 otherwise you have the possibility to override the definition of either
1 the ‘distcleancheck’ rule, or the ‘$(distcleancheck_listfiles)’
1 variable. For instance, to disable ‘distcleancheck’ completely, add the
1 following rule to your top-level ‘Makefile.am’:
1
1 distcleancheck:
1 @:
1
1 If you want ‘distcleancheck’ to ignore built files that have not been
1 cleaned because they are also part of the distribution, add the
1 following definition instead:
1
1 distcleancheck_listfiles = \
1 find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
1 sh '{}' ';'
1
1 The above definition is not the default because it’s usually an error
1 if your Makefiles cause some distributed files to be rebuilt when the
1 user build the package. (Think about the user missing the tool required
1 to build the file; or if the required tool is built by your package,
1 consider the cross-compilation case where it can’t be run.) There is an
1 entry in the FAQ about this (⇒Errors with distclean), make sure
1 you read it before playing with ‘distcleancheck_listfiles’.
1
1 distuninstallcheck
1 ------------------
1
1 ‘distcheck’ also checks that the ‘uninstall’ rule works properly, both
1 for ordinary and ‘DESTDIR’ builds. It does this by invoking ‘make
1 uninstall’, and then it checks the install tree to see if any files are
1 left over. This check will make sure that you correctly coded your
1 ‘uninstall’-related rules.
1
1 By default, the checking is done by the ‘distuninstallcheck’ rule,
1 and the list of files in the install tree is generated by
1 ‘$(distuninstallcheck_listfiles)’ (this is a variable whose value is a
1 shell command to run that prints the list of files to stdout).
1
1 Either of these can be overridden to modify the behavior of
1 ‘distcheck’. For instance, to disable this check completely, you would
1 write:
1
1 distuninstallcheck:
1 @:
1