Next Up Previous Contents
Next: 2.5 Preprocessable Fortran
Up: 2 Tools
Previous: 2.3 Version numbers
[ID index][Keyword index]

2.4 A few remarks on state

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.


Next Up Previous Contents
Next: 2.5 Preprocessable Fortran
Up: 2 Tools
Previous: 2.3 Version numbers
[ID index][Keyword index]
The Starlink Build System
Starlink System Note 78
Norman Gray, Peter W Draper, Mark B Taylor, Steven E Rankin
11 April 2005. Release snapshot: $Revision: 1.116 $. Last updated 28 May 2006