The Makefile.in files which automake generates
generally handles distribution pretty successfully, and the
command make dist will usually do almost all the
work of packing your files into a distribution which can be
built portably. In some cases, however, you have to give it
a little help.
There are two potential problems. Firstly, automake may not be able to accurately work out the set of files which ought to be distributed. Consider the following makefile fragment (this, along with the other examples in this section, is from the AST distribution, which presents a variety of distribution problems):
noinst_PROGRAMS = astbad
astbad_SOURCES = astbad.c pointset.h
AST_PAR: ast_par.source astbad
sed -e 's/<AST__BAD>/'`./astbad | tr 'E' 'D'`'/' ast_par.source >$@
_SOURCES variable, so astbad.c and
pointset.h are included in the distribution
automatically. However it does not attempt to work out
every consequence of the makefile rules, and so fails to
spot that ast_par.source is going to be needed
on the build host. In general, a file which is mentioned
only in a makefile dependency will not be automatically
distributed by automake. Files such as this should be
included by the distribution by listing them in the value of
the
EXTRA_DIST
variable:
EXTRA_DIST = ast_par.source
Automake also supports the dist_ and
nodist_ prefixes to automake
variables. These
can be used to adjust automake's defaults for certain
primaries. Automake does not distribute
_SCRIPTS by default (this is since they are
sometimes generated, but I for one find this
counter-intuitive), so if you want a script to be
distributed, you must use a prefix:
We see all four common possibilities here:bin_SCRIPTS = ast_link dist_bin_SCRIPTS = ast_link_adam noinst_SCRIPTS = ast_cpp dist_noinst_SCRIPTS = makeh
ast_link_adam and makeh are needed
in the distribution but need no configuration, and so should
be distributed as they stand; ast_link and
ast_cpp are configured, so these files should
not be distributed, since the corresponding .in
files are (as a result of being mentioned in
AC_CONFIG_FILES). Also ast_cpp
and makeh are used only to build the library,
and are not installed. You could get the same effect by
listing ast_link_adam and makeh in
EXTRA_DIST, but it is probably a little less
opaque if all the information about particular files is kept
in one place.Incidentally, the other occasionally important `prefix-prefix' like
dist is
nobase. See item `Automake flattens paths when it
installs things. Why?'.
On the other hand, files in _SOURCES variables
are distributed by default, so you must turn this off if one
of these files is generated at configure time:
libast_la_SOURCES = \
$(GRP_C_ROUTINES) \
$(GRP_C_INCLUDE_FILES) \
$(GRP_F_INCLUDE_FILES) \
ast_err.h
nodist_libast_la_SOURCES = \
ast.h \
AST_PAR
Though the set of included files is deterministic, I find
it is not terribly predictable, and the best way to do this
sort of tidyup is by making a distribution, trying to build
it, and thus discovering which files were left out or
included by accident. There is no harm in listing a file in
EXTRA_DIST which would be included
automatically.
For fuller detail on automake's distribution calculations, see section What Goes in a Distribution of the automake manual.
The second distribution problem is that some Starlink components do quite a lot of work at distribution time, building documentation or generating sources, generally using programs or scripts which are not reasonably available on the eventual build host. This is in principle out of scope for automake and autoconf, but since it is common and fairly standardised in Starlink applications, Starlink automake and autoconf provide some support for pre-distribution configuration.
All configuration tests in configure.ac should
be done unconditionally, even if they are only meaningful
prior to a distribution -- they are redundant afterwards,
but cause no problems. Any files which should be present
only prior to the distribution should be listed in
configure.ac inside macro STAR_PREDIST_SOURCES.
The ./configure script expects to find either
all of these files or none of them, and if it finds some
other number, it will warn you. If it finds these files, it
concludes that you are in a pre-distribution checkout, and
sets the substitution variable @PREDIST@ to be
empty; if it finds none, it concludes that you are in a
distributed package, and defines @PREDIST@ to
be the comment character #. This means that
makefile fragments which are only usable prior to
distribution should all be prefixed with the string
@PREDIST@, and they will thus be enabled or
disabled as appropriate. The distribution rules mentioned
above mean that any configuration of such undistributed
files must be done by hand in the Makefile.am,
and not by AC_CONFIG_FILES, since this macro
automatically distributes the files implied by its
arguments.
For example, the AST configure.ac has:
TheSTAR_LATEX_DOCUMENTATION([sun210 sun211], [sun210.htx_tar sun211.htx_tar]) STAR_PREDIST_SOURCES(sun_master.tex) STAR_CHECK_PROGS(star2html) STAR_CHECK_PROGS(prolat, sst) # prolat is part of SST
sun_master.tex file is used when the
SUN/210 and SUN/211 files are being generated, and should
not be distributed. Since the process of generating the
documentation uses application star2html, we
check for this and for prolat (and thus do this
redundantly even after distribution). Most components can
get away with the one-argument version of
STAR_LATEX_DOCUMENTATION which avoids these
complications, and does the equivalent of the
star2html check internally.This AST configure script also has
and carefully avoids callingSTAR_PREDIST_SOURCES(error.h.in version.h.in)
AC_CONFIG_FILES(error.h
version.h). It still has to configure these files
prior to distribution, so this has to be done in the
Makefile.am:
(this is the same technique that was illustrated in passing in the discussion of `installation locations' in Section 2.1.2). The leading@PREDIST@predist_subs = sed \ @PREDIST@ -e 's,@star_facilitycode\@,$(star_facilitycode),' \ @PREDIST@ -e 's,@PACKAGE_VERSION\@,$(PACKAGE_VERSION),' \ @PREDIST@ -e 's,@PACKAGE_VERSION_MAJOR\@,$(PACKAGE_VERSION_MAJOR),' \ @PREDIST@ -e 's,@PACKAGE_VERSION_MINOR\@,$(PACKAGE_VERSION_MINOR),' \ @PREDIST@ -e 's,@PACKAGE_VERSION_RELEASE\@,$(PACKAGE_VERSION_RELEASE),' \ @PREDIST@ -e 's,@PERL\@,$(PERL),' @PREDIST@error.h: error.h.in @PREDIST@ rm -f $@; $(predist_subs) $< >$@ @PREDIST@version.h: version.h.in @PREDIST@ rm -f $@; $(predist_subs) $< >$@
@PREDIST@ strings mean that this stanza causes
no problems after distribution, when the
error.h.in files are not present. See Appendix A.26 for more details.This is admittedly a rather crude technique, but it is a lot less fragile than the more elegant alternatives.