>From 5f132d00e1f9cbd03432d834204d12cd8f638529 Mon Sep 17 00:00:00 2001 Message-Id: From: Stefano Lattarini Date: Sat, 25 Feb 2012 11:11:33 +0100 Subject: [PATCH] docs: improve "make distcheck" documentation * doc/automake.texi (Checking the Distribution): The fact that "make distcheck" uses a read-only srcdir wasn't documented clearly enough here. Fix that. Since we are at it, be more explicit about the steps undertaken by "make distcheck", and re-organize this section a bit. Motivated by the discussion on automake bug#10878. (distcleancheck): Rename this node (in the "FAQ" section) ... (Errors with distclean): ... to this. Add a proper "FIXME" comment. --- doc/automake.texi | 56 ++++++++++++++++++++++++++++++++++++---------------- 1 files changed, 39 insertions(+), 17 deletions(-) diff --git a/doc/automake.texi b/doc/automake.texi index 8dcbc18..c2c2a21 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -374,7 +374,7 @@ Frequently Asked Questions about Automake * maintainer-mode:: missing and AM_MAINTAINER_MODE * Wildcards:: Why doesn't Automake support wildcards? * Limitations on File Names:: Limitations on source and installed file names -* distcleancheck:: Files left in build directory after distclean +* Errors with distclean:: Files left in build directory after distclean * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS * Renamed Objects:: Why are object files sometimes renamed? * Per-Object Flags:: How to simulate per-object flags? @@ -8468,20 +8468,32 @@ dist} was run, not to any sub-packages involved. @section Checking the Distribution @cindex @samp{make distcheck} address@hidden @samp{make distcleancheck} address@hidden distcleancheck_listfiles address@hidden @samp{make distuninstallcheck} address@hidden distuninstallcheck_listfiles - @trindex distcheck -Automake also generates a @code{distcheck} rule that can be of help to -ensure that a given distribution will actually work. @code{distcheck} -makes a distribution, then tries to do a @code{VPATH} build -(@pxref{VPATH Builds}), run the test suite, and finally make another -tarball to ensure the distribution is self-contained. +Automake also generates a @code{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, address@hidden from it}, takes the following steps: address@hidden address@hidden +tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the address@hidden and all its content made @emph{read-only}; address@hidden +runs the test suite (with @command{make check}) on this fresh build; address@hidden +installs the package in a temporary directory (with @command{make +install}), and tries runs the test suite on the resulting installation +(with @command{make installcheck}); address@hidden +checks that the package can be correctly uninstalled (by @command{make +uninstall}) and cleaned (by @code{make distclean}); address@hidden +finally, makes another tarball to ensure the distribution is +self-contained. address@hidden itemize @vindex AM_DISTCHECK_CONFIGURE_FLAGS @vindex DISTCHECK_CONFIGURE_FLAGS address@hidden DISTCHECK_CONFIGURE_FLAGS Building the package involves running @samp{./configure}. If you need to supply additional flags to @command{configure}, define them in the @code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level @@ -8505,6 +8517,7 @@ installcheck} was wrongly assuming it could blindly test "@command{m4}", rather than the just-installed "@command{gm4}". @trindex distcheck-hook address@hidden distcheck-hook If the @code{distcheck-hook} rule is defined in your top-level @file{Makefile.am}, then it will be invoked by @code{distcheck} after the new distribution has been unpacked, but before the unpacked copy @@ -8517,9 +8530,12 @@ are not honored in a subpackage @file{Makefile.am}, but the flags from @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS} are passed down to the @command{configure} script of the subpackage. address@hidden @samp{make distcleancheck} @trindex distcleancheck @vindex DISTCLEANFILES @vindex distcleancheck_listfiles + address@hidden distcleancheck Speaking of potential distribution errors, @code{distcheck} also ensures that the @code{distclean} rule actually removes all built files. This is done by running @samp{make distcleancheck} at the end of @@ -8557,9 +8573,14 @@ 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 (@pxref{distcleancheck}), make sure you -read it before playing with @code{distcleancheck_listfiles}. +an entry in the FAQ about this (@pxref{Errors with distclean}), make +sure you read it before playing with @code{distcleancheck_listfiles}. address@hidden @samp{make distuninstallcheck} address@hidden distuninstallcheck address@hidden distuninstallcheck_listfiles + address@hidden distuninstallcheck @code{distcheck} also checks that the @code{uninstall} rule works properly, both for ordinary and @code{DESTDIR} builds. It does this by invoking @samp{make uninstall}, and then it checks the install tree @@ -11586,7 +11607,7 @@ lists. * maintainer-mode:: missing and AM_MAINTAINER_MODE * Wildcards:: Why doesn't Automake support wildcards? * Limitations on File Names:: Limitations on source and installed file names -* distcleancheck:: Files left in build directory after distclean +* Errors with distclean:: Files left in build directory after distclean * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS * Renamed Objects:: Why are object files sometimes renamed? * Per-Object Flags:: How to simulate per-object flags? @@ -11981,13 +12002,14 @@ differ only in case (e.g., @file{makefile} and @file{Makefile}). Nowadays it is no longer worth worrying about the 8.3 limits of DOS file systems. address@hidden distcleancheck address@hidden Files left in build directory after distclean address@hidden FIXME This should probably be moved in the "Checking the Distribution" address@hidden FIXME section... address@hidden Errors with distclean address@hidden Errors with distclean @cindex @code{distclean}, diagnostic @cindex @samp{make distclean}, diagnostic @cindex dependencies and distributed files @trindex distclean address@hidden distcleancheck This is a diagnostic you might encounter while running @samp{make distcheck}. -- 1.7.9