5.3 State FAQs

This is only a summary of the various ways that state is held within the Starlink build system. The details are in Section 2.4.

How do I get rid of state in a checked-out directory?

One of make clean, make distclean or make maintainer-clean should do what you want. The first gets rid of compiled files, the second everything but distributed files, and the third returns the directory to an almost pristine state, though without deleting ./configure or the files it needs to run.

The nuclear option for clearing state from a directory ping is to delete it and check it out afresh:

% cd ..
% cvs release -d ping      # or: mv ping ping-old
% cvs update -d ping

The CVS `release' command tells CVS you have finished with a particular checkout. With the -d option, it is basically rm -rf except that it checks you have no modified but uncommited files left within ping.

How do I start again?

As mentioned above, make maintainer-clean in the top level should recurse and make maintainer-clean in each of the children. That unmakes and unconfigures everything, but doesn't undo the bootstrapping. The bootstrapping done by ./bootstrap doesn't depend on any state except the contents of the manifest files, and to undo that, you need only delete the manifest.

For maintainer-clean to work, one sometimes needs to make extra declarations in Makefile.am. There could well be components where maintainer-clean doesn't work as fully as it ought. Do mention those if you spot them.

How do I control where a component is installed?

In a variety of ways. In the list below, each mechanism effectively supplies the default for the mechanism before it.

1. You can specify an installation prefix at install time:

   % make prefix=/odd/place install
   

   This might break your installation if there was a prefix baked in to your component at build time. Do this only if you have a particular reason for doing so, and know what you're doing.
2. At make time:

   % make prefix=/odd/place
   

   This builds your component with the Makefile variable ${prefix} set to the given value. The component will be installed into this location at install time, unless you override the location as described above. See the discussion of `installation directory variables' in Section 2.1.2.
3. At configure time:

   % ./configure --prefix=/odd/place
   

   This is usually the most appropriate way to do this.
4. By setting a `sticky variable':

   % ./starconf.status STARCONF_DEFAULT_PREFIX=/odd/place
   

   This sets the default for the ./configure script's --prefix option.
5. By configuring starconf:

   % pwd
   .../buildsupport/starconf
   % ./configure STARCONF_DEFAULT_PREFIX=/odd/place
   ...
   % make; make install
   

   This sets the default for all directories configured using this starconf application. This is effectively what you do when you set the environment variable STARCONF_DEFAULT_PREFIX before you run the top-level ./bootstrap script, as described in Section 3.2.

OK, now I've changed my mind about where I want components to be installed -- the `prefix'. How do I tell the build system?

Easy. Set the STARCONF_... variables as you want them, as described in Section 3.2, and in the top level of the checkout, do

% ./bootstrap --buildsupport
% rm config.cache

The --buildsupport option forces the bootstrap to remake and reinstall the buildsupport components, taking the current values of the STARCONF_... variables into account.

You should also remove any config.cache files, both in the top-level directory and elsewhere, since these often store paths to applications and libraries which are probably not appropriate for your new prefix.

For more details, see the notes on state in Section 2.4.

What does this mean?: required file `./install-sh' not found

It means that you need to run autoreconf with different options.

You have just run autoreconf by hand (haven't you?) and it is complaining that it cannot find the ./install-sh file which automake requires (in fact autoreconf has spotted a Makefile.am in your directory, and so has invoked automake, and it is this which is reporting the error). Give autoreconf the --install --symlink options, which installs required files, and does so by symlinking rather than copying them.

What does this mean?: configure: error: `<env-var>' has changed since the previous run

The message might say:

% ./configure -C
configure: loading cache config.cache
configure: error: `STARLINK' has changed since the previous run:
configure:   former value:  /somewhere/else
configure:   current value: /export3/sun
configure: error: changes in the environment can compromise the build
configure: error: run `make distclean' and/or `rm config.cache' and start over

You have changed an `influential environment variable'. See Section 2.1.5.