| 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 |