automake-1.16: Basics of Distribution
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 variable ‘TAR’ to override the tar
program used; it defaults to ‘tar’. ⇒The Types of Distributions,
for how to generate other kinds of archives.
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; ⇒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; ⇒The
dist Hook.
If you define ‘SUBDIRS’, Automake will recursively include the
subdirectories in the distribution. If ‘SUBDIRS’ is defined
conditionally (⇒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 (⇒Conditional Subdirectories).
Info Catalog
automake-1.16: Dist
automake-1.16: Fine-grained Distribution Control