diff options
Diffstat (limited to 'src/boost/tools/build/notes/build_dir_option.txt')
-rw-r--r-- | src/boost/tools/build/notes/build_dir_option.txt | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/src/boost/tools/build/notes/build_dir_option.txt b/src/boost/tools/build/notes/build_dir_option.txt new file mode 100644 index 000000000..0ebd3bef7 --- /dev/null +++ b/src/boost/tools/build/notes/build_dir_option.txt @@ -0,0 +1,77 @@ +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 B2 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 |