Subject: [Boost-commit] svn:boost r86745 - trunk/tools/build/v2/doc/src
Date: 2013-11-18 01:05:56
Date: 2013-11-18 01:05:56 EST (Mon, 18 Nov 2013)
New Revision: 86745
Update docs to use 'b2' everywhere.
Patch from Mateusz Loskot, with extra tweaks.
Text files modified:
trunk/tools/build/v2/doc/src/architecture.xml | 40 ++++++++++++++++++++--------------------
trunk/tools/build/v2/doc/src/extending.xml | 11 +++++------
trunk/tools/build/v2/doc/src/faq.xml | 31 +++++++++++++++++++++++++++++++
trunk/tools/build/v2/doc/src/install.xml | 4 ++--
trunk/tools/build/v2/doc/src/overview.xml | 4 ++--
trunk/tools/build/v2/doc/src/reference.xml | 5 +++--
trunk/tools/build/v2/doc/src/tasks.xml | 4 ++--
7 files changed, 65 insertions(+), 34 deletions(-)
--- trunk/tools/build/v2/doc/src/architecture.xml Sun Nov 17 18:44:45 2013 (r86744)
+++ trunk/tools/build/v2/doc/src/architecture.xml 2013-11-18 01:05:56 EST (Mon, 18 Nov 2013) (r86745)
@@ -14,6 +14,9 @@
+ <!-- FIXME: the below does not mention engine at all, making rest of the
+ text confusing. Things like 'kernel' and 'util' don't have to be
+ mentioned at all. -->
Boost.Build implementation is structured in four different components:
"kernel", "util", "build" and "tools". The first two are relatively
@@ -58,6 +61,7 @@
@@ -78,13 +82,14 @@
A generator appropriate for the build properties is selected and its
<code>run</code> method is called. The method returns a list of virtual
- The targets are returned to the top level code. They are converted
- into bjam targets (via <code>virtual-target.actualize</code>) and passed
- to bjam for building.
+ The virtual targets are returned to the top level code, and for each instance,
+ the <literal>actualize</literal> method is called to setup nodes and updating
+ actions in the depenendency graph kepts inside Boost.Build engine. This dependency
+ graph is then updated, which runs necessary commands.
@@ -163,11 +168,11 @@
- Virtual targets correspond to atomic updatable entities. Each virtual
+ Virtual targets are atomic updatable entities. Each virtual
target can be assigned an updating action -- instance of the
<code>action</code> class. The action class, in turn, contains a list of
- source targets, properties, and a name of an bjam action which should be
+ source targets, properties, and a name of an action which
+ should be executed.
@@ -178,12 +183,13 @@
already been created. In that case, the preexisting target is returned.
+ <!-- FIXME: the below 2 para are rubbish, must be totally rewritten. -->
When all virtual targets are produced, they are "actualized". This means
that the real file names are computed, and the commands that should be run
are generated. This is done by the <code>virtual-target.actualize</code>
and <code>action.actualize</code> methods. The first is conceptually
- simple, while the second needs additional explanation. Commands in bjam
+ simple, while the second needs additional explanation. Commands in Boost.Build
are generated in a two-stage process. First, a rule with an appropriate
name (for example "gcc.compile") is called and is given a list of target
names. The rule sets some variables, like "OPTIONS". After that, the
@@ -308,20 +314,14 @@
As stated above, it is possible to compile a C++ file multiple times,
using different include paths. Therefore, include dependencies for those
- compilations can be different. The problem is that bjam does not allow
- multiple scans of the same target.
- The solution in Boost.Build is straightforward. When a virtual target is
- converted to a bjam target (via the
- <literal>virtual-target.actualize</literal> method), we specify the
- scanner object to be used. The actualize method will create different bjam
- targets for different scanners.
+ compilations can be different. The problem is that Boost.Build engine does
+ not allow multiple scans of the same target. To solve that, we pass the
+ scanner object when calling <literal>virtual-target.actualize</literal>
+ and it creates different engine targets for different scanners.
- For each Boost Jam target created with a scanner is created, a
+ For each engine target created with a specified scanner, a
corresponding one is created without it. The updating action is
associated with the scanner-less target, and the target with the scanner
is made to depend on it. That way if sources for that action are touched,
@@ -355,7 +355,7 @@
If when compiling "a.cpp" there is an include of "a.h", the "dir"
directory is on the include path, and a target called "a.h" will be
- generated in "dir", then bjam should discover the include, and create
+ generated in "dir", then Boost.Build should discover the include, and create
"a.h" before compiling "a.cpp".
--- trunk/tools/build/v2/doc/src/extending.xml Sun Nov 17 18:44:45 2013 (r86744)
+++ trunk/tools/build/v2/doc/src/extending.xml 2013-11-18 01:05:56 EST (Mon, 18 Nov 2013) (r86745)
@@ -613,7 +613,7 @@
and the target type. When invoked, the generator will create a target
of type <literal>CPP</literal> with a source target of
type <literal>VERBATIM</literal> as the only source. But what command
- will be used to actually generate the file? In bjam, actions are
+ will be used to actually generate the file? In Boost.Build, actions are
specified using named "actions" blocks and the name of the action
block should be specified when creating targets. By convention,
generators use the same name of the action block as their own id. So,
@@ -970,7 +970,7 @@
<para> Note the <code>bind DEF_FILE</code> part. It tells
- bjam to translate the internal target name in
+ Boost.Build to translate the internal target name in
<varname>DEF_FILE</varname> to a corresponding filename in
the <code>link</code> action. Without it the expansion of
<code>$(DEF_FILE)</code> would be a strange symbol that is
@@ -981,8 +981,7 @@
targets in general, only source files." I'm not sure
what I meant by that; maybe you can figure it out. -->
- We are almost done, but we should stop for a small workaround. Add the following
- code to msvc.jam
+ We are almost done, except for adding the follwing code to <filename>msvc.jam</filename>:
@@ -992,8 +991,8 @@
<!-- You *must* explain the part in [...] above. It's completely opaque to the casual reader -->
- This is needed to accomodate some bug in bjam, which hopefully
- will be fixed one day.
+ This is a workaround for a bug in Boost.Build engine, which will hopefully
+ be fixed one day.
<!-- This is *NOT* a bug!! Anyway, BBv2 shouild handle this automatically. Why doesn't it? -->
--- trunk/tools/build/v2/doc/src/faq.xml Sun Nov 17 18:44:45 2013 (r86744)
+++ trunk/tools/build/v2/doc/src/faq.xml 2013-11-18 01:05:56 EST (Mon, 18 Nov 2013) (r86745)
@@ -446,6 +446,37 @@
+ <section id="bbv2.faq.names">
+ What is the difference between Boost.Build,
+ <filename>b2</filename>, <filename>bjam</filename> and Perforce Jam?
+ Boost.Build is the name of the complete build system. The executable that runs
+ it is <filename>b2</filename>. That executable is written in C and implements
+ performance-critical algorithms, like traversal of dependency graph and executing
+ commands. It also implements an interpreted language used to implement the rest of
+ Boost.Build. This executable is formally called "Boost.Build engine".
+ The Boost.Build engine is derived from an earlier build tool called Perforce Jam. Originally,
+ there were just minor changes, and the filename was <filename>bjam</filename>. Later on,
+ with more and more changes, the similarity of names because a disservice to users, and as of
+ Boost 1.47.0, the official name of the executable was changed to <filename>b2</filename>.
+ A copy named <filename>bjam</filename> is still created for compatibility,
+ but you are encouraged to use the new name in all cases.
+ Perforce Jam was an important foundation, and we gratefully acknowledge its influence,
+ but for users today, these tools share only some basics of the interpreted language.
--- trunk/tools/build/v2/doc/src/install.xml Sun Nov 17 18:44:45 2013 (r86744)
+++ trunk/tools/build/v2/doc/src/install.xml 2013-11-18 01:05:56 EST (Mon, 18 Nov 2013) (r86745)
@@ -103,7 +103,7 @@
<para>Placing Boost.Build into <filename>/usr/share/boost-build</filename>
- will make sure that <command>bjam</command> will find Boost.Build
+ will make sure that <command>b2</command> will find Boost.Build
without any additional setup.</para>
@@ -120,7 +120,7 @@
<para>If those guidelines are met, users will be able to invoke
- <command>bjam</command> without any explicit configuration.
+ <command>b2/command> without any explicit configuration.
--- trunk/tools/build/v2/doc/src/overview.xml Sun Nov 17 18:44:45 2013 (r86744)
+++ trunk/tools/build/v2/doc/src/overview.xml 2013-11-18 01:05:56 EST (Mon, 18 Nov 2013) (r86745)
@@ -14,9 +14,9 @@
- Boost.Build actually consists of two parts - Boost.Jam, a build engine
+ Boost.Build has two parts&emdash;a build engine
with its own interpreted language, and Boost.Build itself, implemented in
- Boost.Jam's language. The chain of events when you type
+ that language. The chain of events when you type
<command>b2</command> on the command line is as follows:
--- trunk/tools/build/v2/doc/src/reference.xml Sun Nov 17 18:44:45 2013 (r86744)
+++ trunk/tools/build/v2/doc/src/reference.xml 2013-11-18 01:05:56 EST (Mon, 18 Nov 2013) (r86745)
@@ -17,8 +17,9 @@
- <para>bjam's first job upon startup is to load the Jam code that
- implements the build system. To do this, it searches for a file
+ Immediately upon starting, the Boost.Build engine (<command>b2</command>)
+ loads the Jam code that implements the build system. To do this, it searches for a file
called <filename>boost-build.jam</filename>, first in the invocation directory, then
in its parent and so forth up to the filesystem root, and finally
in the directories specified by the environment variable
--- trunk/tools/build/v2/doc/src/tasks.xml Sun Nov 17 18:44:45 2013 (r86744)
+++ trunk/tools/build/v2/doc/src/tasks.xml 2013-11-18 01:05:56 EST (Mon, 18 Nov 2013) (r86745)
@@ -447,8 +447,8 @@
<varname>args</varname> and <varname>input-files</varname> as command-line
arguments. The <varname>args</varname> parameter is passed verbatim and
the values of the <varname>input-files</varname> parameter are treated as
- paths relative to containing Jamfile, and are adjusted if <command>bjam
- </command> is invoked from a different directory. The
+ paths relative to containing Jamfile, and are adjusted if <command>b2</command>
+ is invoked from a different directory. The
<code>run-fail</code> rule is identical to the <code>run</code> rule,
except that it expects that the run fails.
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk