Subject: [Boost-commit] svn:boost r77629 - trunk/tools/build/v2/doc/src
From: steven_at_[hidden]
Date: 2012-03-29 13:09:32
Author: steven_watanabe
Date: 2012-03-29 13:09:30 EDT (Thu, 29 Mar 2012)
New Revision: 77629
URL: http://svn.boost.org/trac/boost/changeset/77629
Log:
Describe how the target path is computed.
Text files modified:
trunk/tools/build/v2/doc/src/reference.xml | 43 ++++++++++++++++++++++++++++++++++++++-
1 files changed, 41 insertions(+), 2 deletions(-)
Modified: trunk/tools/build/v2/doc/src/reference.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/reference.xml (original)
+++ trunk/tools/build/v2/doc/src/reference.xml 2012-03-29 13:09:30 EDT (Thu, 29 Mar 2012)
@@ -2023,7 +2023,46 @@
</programlisting>
</para>
- </section>
+ </section>
+
+ <section id="bbv2.reference.buildprocess.targetpath">
+ <title>Target Paths</title>
+
+ <para>Several factors determine the location of a concrete
+ file target. All files in a project are built under
+ the directory bin unless this is overriden by the build-dir project
+ attribute. Under bin is a path that depends on the properties
+ used to build each target. This path is uniquely determined by
+ all non-free, non-incidental properties. For example,
+ given a property set containing:
+ <code><toolset>gcc <toolset-gcc:version>4.6.1 <variant>debug
+ <warnings>all <define>_DEBUG <include>/usr/local/include
+ <link>static</code>,
+ the path will be gcc-4.6.1/debug/link-static. <warnings> is an
+ incidental feature and <define> and <include> are
+ free features, so they do not affect the path.</para>
+
+ <para>Sometimes the paths produced by Boost.Build can become excessively
+ long. There are a couple of command line options that can help with this.
+ --abbreviate-paths reduces each element to no more than five characters.
+ For example, link-static becomes lnk-sttc. The --hash option reduces the
+ path to a single directory using an MD5 hash.</para>
+
+ <para>There are two features that affect the build
+ directory. The <location> feature completely
+ overrides the default build directory. For example,
+ <programlisting>exe a : a.cpp : <location>. ;</programlisting>
+ builds all the files produced by <code>a</code>
+ in the directory of the Jamfile. This is generally
+ discouraged, as it precludes variant builds.</para>
+
+ <para>The <location-prefix> feature adds a
+ prefix to the path, under the project's build
+ directory. For example,
+ <programlisting>exe a : a.cpp : <location-prefix>subdir ;</programlisting>
+ will create the files for <code>a</code> in bin/subdir/gcc-4.6.1/debug</para>
+
+ </section>
</section>
@@ -2125,7 +2164,7 @@
<para>Non-incidental features are assumed to affect build
products, so the files for targets whose build specification
differs in non-incidental features are placed in different
- directories as described in "target paths" below. [ where? ]
+ directories as described in <xref linkend="bbv2.reference.buildprocess.targetpath"/>.
</para>
</listitem>