There is quite a lot of state held within the starconf build tree. This section contains a few notes on where this state is, and how to handle it.
Since most of the details here are rather intricate, you might save time by looking at the list of FAQs on state in Section 5.3.
Autotool state: The most obvious state within the
tree is the existence of the configure
and
Makefile.in
files which are the generated by
autoconf and automake. Files config.h.in
and
aclocal.m4
, are also part of this process,
inasmuch as they are generated by autoreconf:
config.h.in
is
based on the declarations
within configure.ac
;
aclocal.m4
is a
local cache of m4 macros, drawn from the starconf,
autoconf, automake
and libtool installations. Other objects
generated by the autotools are the cache directory
autom4te.cache
and the tool links
config.guess
, config.sub
,
depcomp
, install-sh
,
ltmain.sh
, missing
and
stamp-h1
. All of this can be happily blown away
by hand, and a lot of it is removed by make
maintainer-clean
, though this doesn't
remove things like
config.h.in
which are required for
./configure
to run. Most of this state is
maintained reliably by the dependencies within
Makefile.in
-- for example if you update
Makefile.am
, then a simple make
will
remake Makefile.in
and regenerate
Makefile
before using the new
Makefile
to do the build. If you have removed
this state or suspect that it may be out of date, then
autoreconf will always regenerate it -- it's always safe to
rerun autoreconf.
Configuration state: When ./configure
runs, its most obvious effect is to transform the
.in
files into their corresponding configured
results. However at the same time, it creates a log file in
config.log
(which can be handy to examine if a
configure script fails or appears to give wrong answers), a
cache in
config.cache
if
you ran
./configure
with the -C
option, it
creates the directory-specific ./libtool
script,
and it creates a file config.status
. This last
file holds most of ./configure
's state, and can
be used to either regenerate a particular file
(./config.status Makefile
) or else to update itself
(./config.status --recheck
has the effect of
rerunning ./configure
with the same options such
as --prefix
which were given to the
./configure
script last time). You won't often
have to run
./config.status
yourself, but it's
reassuring to know what it's doing when the makefile runs it
for you. It is always regenerated afresh by running
./configure
.
Build state: The compiled files are obviously part
of the build state, and can be removed by make
clean
and
regenerated with plain make
. Less
obviously part of this state are the directory
.libs
, which is
libtool's' workspace and holds
different types of objects and libraries, and
.deps
, which holds dependency information gleaned
as part of the last build. Less obviously still are those
(few) .in
files which are configured as part of
the build. As mentioned in Section 2.1.2,
so-called `installation directory variables' should be
substituted at make time rather than build time, with a
hand-written makefile rule in
Makefile.am
.
Starconf state: There
is essentially no starconf
state, since the starconf system's only role is to manage
the bootstrap
file and provide the extra
autoconf macros (installed in the buildsupport part
of the tree when starconf itself is installed). The
starconf.status
file is purely a cache of
starconf variables, and allows you to locate the starconf
installation which was used most recently. At one time, the
starconf.status
file did hold state, and
allowed you to manipulate it, and was even checked in; this
is no longer the case.
Build tree and installation state: The last
noteworthy state is that in the build tree as a whole. The
top-level makefile requires some state in order to manage its
bootstrapping `make world' build. This build is organised by
representing the build and link dependencies between
components by makefile dependencies between the components'
installed manifests, which are installed in the
.../manifests
directory alongside, and at the
same time, as the component is installed by the
install
Makefile target. Thus this is state held
outside of the build tree. If the `make
world' build
sees that a manifest file is up-to-date with respect to the
dependencies expressed in
Makefile.dependencies
,
it makes no attempt to build it, even if the
component itself has been updated and itself needs rebuilding
and reinstalling. A slight wrinkle here is that the
`buildsupport' tools -- namely starconf and the autotools --
are not explicitly listed as being a dependency of anything,
since they are in fact a dependency of everything. Since they
are rather a special case, these are built within the
top-level bootstrap script, and the best way to run that `by
hand' is via the command ./bootstrap
--buildsupport
, noting that the remarks about
dependencies above apply to this process also. Thus, if you
update a component -- including one of the buildsupport
components -- and wish the top-level `make world' build to
notice this, the best way to do this is to first delete that
component's manifest file from the installation tree. This
process might change slightly with starconf developments
(see Appendix C).
CVS state: This isn't really part of the build system as such, but this seems a good place to point out, or reassure you, that all the state for a CVS checkout directory is in the files in the CVS subdirectory, and that all the repository state for the directory is in the files in the corresponding directory within the repository.