build_dir_option.txt

C++的一个好库。。。现在很流行

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 V2 and V1 build results.

The --build-dir option has no effect if Jamroot does not define any project
id. Dowing 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