]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | Copyright 2005 Vladimir Prus |
2 | Distributed under the Boost Software License, Version 1.0. | |
3 | (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt) | |
4 | ||
5 | ||
6 | Summary | |
7 | ------- | |
8 | ||
9 | We need a --build-dir option that users building from read-only | |
10 | medium can use to force building to some other location. Pretty much | |
11 | every project need this functionality, so it's desirable to have it | |
12 | out-of-the box, without explicit setup. | |
13 | ||
14 | Design | |
15 | ------ | |
16 | ||
17 | We can achieve the desired effect manually by adding something like this | |
18 | to Jamroot: | |
19 | ||
20 | project .... : build-dir [ my-rule-to-compute-build-dir ] ; | |
21 | ||
22 | Where 'my-rule-to-compute-build-dir' would look at the --build-dir option. | |
23 | ||
24 | We need to automate this, but essentially, --build-dir will only affect | |
25 | the 'build-dir' attribute of Jamroots. | |
26 | ||
27 | If Jamroot contains: | |
28 | ||
29 | project foo ; | |
30 | ||
31 | and --build-dir options' value if /tmp/build, then we'll act as if Jamroot | |
32 | contained: | |
33 | ||
34 | project foo : build-dir /tmp/build/foo ; | |
35 | ||
36 | If the 'project' rule has explicit 'build-dir': | |
37 | ||
38 | project foo : build-dir bin.v2 ; | |
39 | ||
40 | then with the same value of --build-dir we'd act as if Jamroot contained: | |
41 | ||
42 | project foo : build-dir /tmp/build/foo/bin.v2 ; | |
43 | ||
44 | We can't drop "bin.v2" because it's quite possible that the name of build dir | |
45 | have specific meaning. For example, it can be used to separate Boost.Build V1 | |
46 | and V2 build results. | |
47 | ||
48 | The --build-dir option has no effect if Jamroot does not define any project id. | |
49 | Doing otherwise can lead to nasty problems if we're building two distinct | |
50 | projects (that is with two different Jamroot). They'll get the same build | |
51 | directory. Most likely, user will see the "duplicate target" error, which is | |
52 | generally confusing. | |
53 | ||
54 | It is expected that any non-trivial project will have top-level "project" | |
55 | invocation with non empty id, so the above limitation is not so drastic. | |
56 | We'll emit a warning if Jamroot does not define project id, and --build-dir | |
57 | is specified. | |
58 | ||
59 | Here's the exact behavior of the --build-dir option. If we're loading a | |
60 | Jamfile (either root or non-root), that declare some project id and some | |
61 | build-dir attribute, the following table gives the value of build-dir | |
62 | that will actually be used. | |
63 | ||
64 | ------------------------------------------------------------------------------- | |
65 | Root? Id Build-dir attribute Resulting build dir | |
66 | ------------------------------------------------------------------------------- | |
67 | yes none * --build-dir is ignored, with warning | |
68 | yes 'foo' none /tmp/build/foo | |
69 | yes 'foo' 'bin.v2' /tmp/build/foo/bin.v2 | |
70 | yes 'foo' '/tmp/bar' Error [1] | |
71 | no * none --build-dir has no effect, inherited | |
72 | build dir is used | |
73 | no * non-empty Error [2] | |
74 | ------------------------------------------------------------------------------- | |
75 | [1] -- not clear what to do | |
76 | [2] -- can be made to work, but non-empty build-dir | |
77 | attribute in non-root Jamfile does not make much sense even without --build-dir |