14.1 Basics of Distribution

The dist rule in the generated Makefile.in can be used to generate a gzipped tar file and/or other flavors of archives for distribution. The file is named based on the PACKAGE and VERSION variables automatically defined by either the AC_INIT invocation or by a deprecated two-arguments invocation of the AM_INIT_AUTOMAKE macro (see Public Macros for how these variables get their values, from either defaults or explicit values—it’s slightly trickier than one would expect). More precisely, the gzipped tar file is named ‘${PACKAGE}-${VERSION}.tar.gz’.

You can set the environment (or Makefile.am) variable TAR to override the tar program used; it defaults to tar. See The Types of Distributions, for how to generate other kinds of archives.

With GNU tar, you can also set the environment (or Makefile.am) variable TAR_OPTIONS to pass options to tar. One common case for this is wanting to avoid using the local user’s uid and gid in the tar file, or the uid being larger than is supported by the tar format (not uncommon nowadays). This can be done with, for example>

TAR_OPTIONS = --owner=0 --group=0
export TAR_OPTIONS

The export (a GNU make feature) is necessary to pass the variable in the environment to the tar invocation. (For more discussion, see https://bugs.gnu.org/19615.)

For the most part, the files to distribute are automatically found by Automake:

These three lists of files are given in their entirety in the output from automake --help.

Despite all this automatic inclusion, it is still common to have files to be distributed which are not found by the automatic rules. You should listed these files in the EXTRA_DIST variable. You can mention files in 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. To emphasize, this copies everything in the directory, including temporary editor files, intermediate build files, version control files, etc.; thus we recommend against using this feature as-is. However, you can use the dist-hook feature to ameliorate the problem; see The dist Hook.

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