automake.info: Dist

Go forward to Tests
Go backward to Clean
Go up to Top
Go to the top op automake

What Goes in a Distribution

Basics of distribution

   The `dist' target in the generated `Makefile.in' can be used to
generate a gzip'd `tar' file and other flavors of archive for
distribution.  The files is named based on the `PACKAGE' and `VERSION'
variables defined by `AM_INIT_AUTOMAKE' (*note Macros::); more
precisely the gzip'd `tar' file is named `PACKAGE-VERSION.tar.gz'.  You
can use the `make' variable `GZIP_ENV' to control how gzip is run.  The
default setting is `--best'.
   For the most part, the files to distribute are automatically found by
Automake: all source files are automatically included in a distribution,
as are all `Makefile.am's and `Makefile.in's.  Automake also has a
built-in list of commonly used files which are automatically included
if they are found in the current directory (either physically, or as
the target of a `Makefile.am' rule).  This list is printed by `automake
--help'.  Also, files which are read by `configure' (i.e. the source
files corresponding to the files specified in various Autoconf macros
such as `AC_CONFIG_FILES' and siblings) are automatically distributed.
   Still, sometimes there are files which must be distributed, but which
are not covered in the automatic rules.  These files should be listed in
the `EXTRA_DIST' variable.  You can mention files from subdirectories
in `EXTRA_DIST'.
   You can also mention a directory in `EXTRA_DIST'; in this case the
entire directory will be recursively copied into the distribution.
Please note that this will also copy _everything_ in the directory,
including CVS/RCS version control files.  We recommend against using
this feature.

Fine-grained distribution control

   Sometimes you need tighter control over what does _not_ go into the
distribution; for instance you might have source files which are
generated and which you do not want to distribute.  In this case
Automake gives fine-grained control using the `dist' and `nodist'
prefixes.  Any primary or `_SOURCES' variable can be prefixed with
`dist_' to add the listed files to the distribution.  Similarly,
`nodist_' can be used to omit the files from the distribution.
   As an example, here is how you would cause some data to be
distributed while leaving some source code out of the distribution:
     dist_data_DATA = distribute-this
     bin_PROGRAMS = foo
     nodist_foo_SOURCES = do-not-distribute.c

The dist hook

   Another way to to use this is for removing unnecessary files that get
recursively included by specifying a directory in EXTRA_DIST:
     EXTRA_DIST = doc
     dist-hook:
     	rm -rf `find $(distdir)/doc -name CVS`
   If you define `SUBDIRS', Automake will recursively include the
subdirectories in the distribution.  If `SUBDIRS' is defined
conditionally (*note Conditionals::), Automake will normally include all
directories that could possibly appear in `SUBDIRS' in the
distribution.  If you need to specify the set of directories
conditionally, you can set the variable `DIST_SUBDIRS' to the exact
list of subdirectories to include in the distribution.
   Occasionally it is useful to be able to change the distribution
before it is packaged up.  If the `dist-hook' target exists, it is run
after the distribution directory is filled, but before the actual tar
(or shar) file is created.  One way to use this is for distributing
files in subdirectories for which a new `Makefile.am' is overkill:
     dist-hook:
             mkdir $(distdir)/random
             cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random

Checking the distribution

   Automake also generates a `distcheck' target which can be of help to
ensure that a given distribution will actually work.  `distcheck' makes
a distribution, then tries to do a `VPATH' build, run the testsuite,
and finally make another tarfile to ensure the distribution is
self-contained.
   Building the package involves running `./configure'.  If you need to
supply additional flags to `configure', define them in the
`DISTCHECK_CONFIGURE_FLAGS' variable, either in your top-level
`Makefile.am', or on the command line when invoking `make'.
   If the target `distcheck-hook' is defined in your `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.
   Speaking about potential distribution errors, `distcheck' will also
ensure that the `distclean' target 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 (*note
Clean::).
   The `distcleancheck' behaviour should be ok for most packages,
otherwise you have the possibility to override the definitition of
either the `distcleancheck' target, 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 which have not
been cleaned because they are also part of the distribution, add the
following definition instead:
     distcleancheck_listfiles = \
       find -type f -exec sh -c 'test -f $(srcdir)/{} || echo {}' ';'
   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.)
   `distcheck' also checks that the `uninstall' target 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 targets.
   By default, the checking is done by the `distuninstallcheck' target,
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:
     distuninstallcheck:
             @:

The types of distributions

   Automake generates a `.tar.gz' file when asked to create a
distribution and other archives formats, *Note Options::.  The target
`dist-gzip' generates the `.tar.gz' file only.