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