The dist rule in the generated Makefile.in can be used
to generate a gzipped 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
(see Macros); more precisely the gzipped 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.ams and Makefile.ins. Automake also
has a built-in list of commonly used files that 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 that 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. Files included in Makefile.ams (using
include) or in configure.ac (using m4_include), and
helper scripts installed with ‘automake --add-missing’ are also
distributed.
Still, sometimes there are files that 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.
If you define SUBDIRS, Automake will recursively include the
subdirectories in the distribution. If SUBDIRS is defined
conditionally (see 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
(see Conditional Subdirectories).
Sometimes you need tighter control over what does not go into the
distribution; for instance, you might have source files that are
generated and that 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
Occasionally it is useful to be able to change the distribution before
it is packaged up. If the dist-hook rule 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
Another way 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`
Two variables that come handy when writing dist-hook rules are
‘$(distdir)’ and ‘$(top_distdir)’.
‘$(distdir)’ points to the directory where the dist rule
will copy files from the current directory before creating the
tarball. If you are at the top-level directory, then ‘distdir =
$(PACKAGE)-$(VERSION)’. When used from subdirectory named
foo/, then ‘distdir = ../$(PACKAGE)-$(VERSION)/foo’.
‘$(distdir)’ can be a relative or absolute path, do not assume
any form.
‘$(top_distdir)’ always points to the root directory of the distributed tree. At the top-level it's equal to ‘$(distdir)’. In the foo/ subdirectory ‘top_distdir = ../$(PACKAGE)-$(VERSION)’. ‘$(top_distdir)’ too can be a relative or absolute path.
Note that when packages are nested using AC_CONFIG_SUBDIRS
(see Subpackages), then ‘$(distdir)’ and
‘$(top_distdir)’ are relative to the package where ‘make
dist’ was run, not to any sub-packages involved.
Automake also generates a distcheck rule that can be of help to
ensure that a given distribution will actually work. distcheck
makes a distribution, then tries to do a VPATH build
(see VPATH Builds), run the test suite, and finally make another
tarball 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 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
DISTCHECK_CONFIGURE_FLAGS are not honored in a subpackage
Makefile.am, but the DISTCHECK_CONFIGURE_FLAGS are
passed down to the configure script of the subpackage.
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:
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.) There is
a FAQ entry about this (see distcleancheck), make sure you read it
before playing with distcleancheck_listfiles.
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:
distuninstallcheck:
@:
Automake generates rules to provide archives of the project for distributions in various formats. Their targets are:
dist-bzip2dist-gzipdist-lzmadist-shardist-zipdist-tarZThe rule dist (and its historical synonym dist-all) will
create archives in all the enabled formats, Options. By
default, only the dist-gzip target is hooked to dist.