15. What Goes in a Distribution

15.1 Basics of distribution

The dist target in the generated `Makefile.in' can be used to generate a gzip'd tar file for distribution. The tar file is named based on the `PACKAGE' and `VERSION' variables; more precisely it 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, if present in the current directory, are automatically included. 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 the AC_OUTPUT invocation) 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.

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

15.3 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 (see section 20. 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

15.4 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, and then tries to do a VPATH build.

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.

15.5 The types of distributions

By default Automake generates a `.tar.gz' file when asked to create a distribution. However, some projects prefer different packaging formats. Automake accomodates most of these using options; 17. Changing Automake's Behavior.

Automake also generates a dist-all target which can be used to make all the requested packaged distributions at once.