boost_1_45_0/tools/build/v2/notes/build_dir_option.txt

Copyright 2005 Vladimir Prus
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)


Summary
-------

We need a --build-dir option that users building from read-only
medium can use to force building to some other location. Pretty much
every project need this functionality, so it's desirable to have it
out-of-the box, without explicit setup.

Design
------

We can achieve the desired effect manually by adding something like this
to Jamroot:

  project .... : build-dir [ my-rule-to-compute-build-dir ] ;

Where 'my-rule-to-compute-build-dir' would look at the --build-dir option.

We need to automate this, but essentially, --build-dir will only affect
the 'build-dir' attribute of Jamroots.

If Jamroot contains:

   project foo ;

and --build-dir options' value if /tmp/build, then we'll act as if Jamroot
contained:

   project foo : build-dir /tmp/build/foo ;

If the 'project' rule has explicit 'build-dir':

   project foo : build-dir bin.v2 ;

then with the same value of --build-dir we'd act as if Jamroot contained:

   project foo : build-dir /tmp/build/foo/bin.v2 ;

We can't drop "bin.v2" because it's quite possible that the name of build dir
have specific meaning. For example, it can be used to separate Boost.Build V1
and V2 build results.

The --build-dir option has no effect if Jamroot does not define any project id.
Doing otherwise can lead to nasty problems if we're building two distinct
projects (that is with two different Jamroot). They'll get the same build
directory. Most likely, user will see the "duplicate target" error, which is
generally confusing.

It is expected that any non-trivial project will have top-level "project"
invocation with non empty id, so the above limitation is not so drastic.
We'll emit a warning if Jamroot does not define project id, and --build-dir
is specified.

Here's the exact behavior of the --build-dir option. If we're loading a
Jamfile (either root or non-root), that declare some project id and some
build-dir attribute, the following table gives the value of build-dir
that will actually be used.

-------------------------------------------------------------------------------
Root?    Id      Build-dir attribute   Resulting build dir
-------------------------------------------------------------------------------
yes      none    *                     --build-dir is ignored, with warning
yes      'foo'   none                  /tmp/build/foo
yes      'foo'   'bin.v2'              /tmp/build/foo/bin.v2
yes      'foo'   '/tmp/bar'            Error [1]
no       *       none                  --build-dir has no effect, inherited
                                       build dir is used
no       *       non-empty             Error [2]
-------------------------------------------------------------------------------
[1] -- not clear what to do
[2] -- can be made to work, but non-empty build-dir
attribute in non-root Jamfile does not make much sense even without --build-dir