ceph/src/boost/tools/build/notes/build_dir_option.txt

   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