13.1 Basics of distribution

The dist rule 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 (see Autoconf macros supplied with Automake); 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.ams and Makefile.ins. 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. 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 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.

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).

13.2 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

13.3 The dist hook

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 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 Nesting Packages), then $(distdir) and $(top_distdir) are relative to the package where make dist was run, not to any sub-packages involved.

13.4 Checking the distribution

Automake also generates a distcheck rule 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 test suite, 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 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 about potential distribution errors, distcheck will also ensure 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 What Gets Cleaned).

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 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.) There is a FAQ entry about this (see Files left in build directory after distclean), 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:
        @:

13.5 The types of distributions

Automake generates rules to provide archives of the project for distributions in various formats. Their targets are:

dist-bzip2

Generate a bzip2 tar archive of the distribution. bzip2 archives are frequently smaller than gzipped archives.

dist-gzip

Generate a gzip tar archive of the distribution.

dist-shar

Generate a shar archive of the distribution.

dist-zip

Generate a zip archive of the distribution.

dist-tarZ

Generate a compressed tar archive of the distribution.

The rule dist (and its historical synonym dist-all) will create archives in all the enabled formats, Changing Automake’s Behavior. By default, only the dist-gzip target is hooked to dist.