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:

• All source files are automatically included in a distribution, as are all Makefile.am and Makefile.in files.
• Files that are read by configure are automatically distributed. These are the source files as specified in various Autoconf macros such as AC_CONFIG_FILES and siblings.
• Files included in a Makefile.am (using include) or in configure.ac (using m4_include).
• Automake has a built-in list of commonly used files automatically included in the distribution if they are found in the current directory (either physically, or as the target of a Makefile.am rule). Some common examples: ABOUT-GNU, COPYING, TODO.

  This list also includes helper scripts installed with ‘automake --add-missing’. Some common examples: compile, config.guess, config.rpath, config.sub, texinfo.tex.

• Automake has another built-in list of files automatically distributed if they are found either with the plain name, or with extension .md (presumably MarkDown, though this not checked). They are checked for in that order, so the plain name is preferred. These are: AUTHORS ChangeLog INSTALL NEWS README README-alpha THANKS.
• A final built-in list of files are those distributed only if other certain conditions hold. For example, the files config.h.top and config.h.bot are automatically distributed only if, e.g., ‘AC_CONFIG_HEADERS([config.h])’ is used in configure.ac). README-alpha is another such file, with README-alpha.md distributed if that is what is available; see Strictness, for its conditions for distribution.

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