Some Recent Thoughts on Boost Installation

From: William E. Kempf (williamkempf_at_[hidden])
Date: 2002-09-24 10:16:09

I've been thinking about the installation issues recently, and about how to
at least start getting something concrete out of what we've talked about.
Here's my thoughts...

We need to start with Boost.Build. This provides a central location for
specifying how to build individual libraries. With some careful thought and
extention, I believe it can be made to be the central location for
describing everything that's needed for installing a library. In fact,
there's a starting point for this already, with the "stage" target. A few
things need fixed and a few extensions need to be added, but this concept
*by itself* provides enough functionality to resolve 90+% of the issues
brought up in the past.

We've identified several key components that need to be installed: binaries
(i.e. library files), include files (i.e. headers) and documentation (i.e.
HTML files). These components generally get installed into different
locations on the target machine, so staging should do this as well. I'm not
(necessarily) advocating that the stage target be used for installing, but
if the stage target put the necessary files into a logical and consistent
tree structure it would then be trivial to provide more traditional
installation mechanisms for the various platforms. So, the first thing to
do is to modify the stage target to create this structure for us. Here's my
suggested syntax:

stage <category> : <sources> : <requirements> : <default-BUILD> ;

* Category (probably needs a better name) specifies what category of file
(doc,bin,include) is being staged. The files will be moved to the build
directory (which can be set with ALL_LOCATE_TARGET) in a subdirectory named
stage and in a further subdirectory from category. (For instance,
builddir/stage/bin and builddir/stage/doc). Alternately we can also provide
a new Jam variable, something like STAGE_PREFIX, that could entirely change
the root directory (from builddir/stage) for staging, which would allow
Boost.Build to actually be used as a crude form of installation script.

* Sources is the same as main targets and one can list both generated
targets like <exe>test_exe and individual files, but not template targets.

* Requirements specifies the build properties used as with main targets.
The <tag> requirement won't be used (see below), but <tag> requirements of
the target (see below) will be used to insure copying of the correct file.

* default-BUILD acts in the same manner as a main target.

One of the nice things about this idea is that header only libraries can
provide Jamfiles that do nothing but stage their files for installation,
providing a centralized and common location to specify this information. We
can extend this idea further by adding another variable to the stage rule
that specifies other libraries that we're dependent on. This would cause
the other libraries to be built and staged first, and if they fail then the
current library won't be staged. Extend this further and you can require
that a library pass it's regression tests before being staged (which is
something that you may want to make overridable). This would allow all of
Boost to be quickly and easily staged, insuring that only those libraries
that truly work for the given platform are included. This idea should make
it trivial to insure that anything installed on a platform will work on that
platform, and would even make it rather simple to install only a portion of
Boost with out having to manually evaluate dependencies. For instance,
Boost.Threads is dependent on Boost.Function, so the stage target would
indicate this and by staging only Boost.Threads you'd get all of the files
necessary for installing both Boost.Threads and Boost.Function, and only if
both libraries actually build and pass regression tests for your platform.

In the above description I glossed over <tag>. There's a reason for that.
<tag> is meant to be used to create library files with specific names for
the variuous incompatible features and variants. For instance, (on the
Win32 platform at least) debug and release builds are not compatible and the
developer has to have a way to use both forms of libraries during
development. On the Win32 platform this is generally done by naming the
variant files differently, such as foo.lib for a release and food.lib for a
debug library. Specifying <tag> in the stage target, as it's done today,
doesn't work. Today this simply causes the library to be renamed, but with
Win32 DLL files you can't simply rename the file and expect the associated
import library to still work. So either you have to fix this in the stage
target, making it regenerate import libraries, which is something that's
going to be compiler specific on how it's done, or you move <tag> from the
stage target to the target that builds the libraries. This has been
discussed on the bjam mailing list, so I won't rehash the discussion, and I
don't really care how the problem is resolved. The reason to bring it up
here, however, is to generate some discussion about the various ways the
<tag> concept would need to be used on the various platforms. I want to
insure we know all of the corner cases where it would be used, and what it
has to do to work, for all of the platforms we know of, so we can specify
the requirements well enough for the Boost.Build folks to make it work.

I think that once we flesh out some of the above ideas and the Boost.Build
folks integrate these ideas into bjam we'll have the basis for an
installation process for Boost. Immediately we'll have something that makes
it easy for users to "hand install" the libraries they're interested in (and
only those they are interested in, which is an interesting and desirable
bonus). Additionally, with a STAGE_PREFIX variable they may actually be
able to use Jam to do the full installation in an automated way. After
that, we've got a structure that should make it extremely trivial for us to
use for generating more platform specific and binary only type of
installations. For instance, I'd think it would be trivial to add AAM
support based on this, and it should be very easy to create Win32 "Windows
Installer" applications from the output of staging.

Thoughts/comments/additions/ideas to flesh out the vague or incomplete
parts?

Bill Kempf

P.S. I CCed the jamboost list, as this discussion directly involves the
readers there as well.