[Boost-commit] svn:boost r86745 - trunk/tools/build/v2/doc/src

Subject: [Boost-commit] svn:boost r86745 - trunk/tools/build/v2/doc/src
From: ghost_at_[hidden]
Date: 2013-11-18 01:05:56

Author: vladimir_prus
Date: 2013-11-18 01:05:56 EST (Mon, 18 Nov 2013)
New Revision: 86745
URL: http://svn.boost.org/trac/boost/changeset/86745

Log:
Update docs to use 'b2' everywhere.

Patch from Mateusz  Loskot, with extra tweaks.
Fixes #9304.

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(-)

Modified: trunk/tools/build/v2/doc/src/architecture.xml
==============================================================================
--- 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 @@
   <section id="bbv2.arch.overview">
     <title>Overview</title>
 
+    <!-- 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. -->
     <para>
       Boost.Build implementation is structured in four different components:
     "kernel", "util", "build" and "tools". The first two are relatively
@@ -58,6 +61,7 @@
         from them.
         </para></listitem>
       </itemizedlist>
+
     </para>
 
     <para>
@@ -78,13 +82,14 @@
         <listitem><para>
           A generator appropriate for the build properties is selected and its
         <code>run</code> method is called. The method returns a list of virtual
-        targets
+        targets.
         </para></listitem>
 
         <listitem><para>
-          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.
         </para></listitem>
       </orderedlist>
     </para>
@@ -163,11 +168,11 @@
       <title>Virtual targets</title>
 
       <para>
-        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
-      executed.
+      source targets, properties, and a name of an action which 
+      should be executed.
       </para>
 
       <para>
@@ -178,12 +183,13 @@
       already been created. In that case, the preexisting target is returned.
       </para>
 
+      <!-- FIXME: the below 2 para are rubbish, must be totally rewritten. -->
       <para>
         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 @@
       <para>
         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.
-      </para>
-
-      <para>
-        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.
       </para>
 
       <para>
-        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 @@
         <listitem><simpara>
           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".
         </simpara></listitem>
 

Modified: trunk/tools/build/v2/doc/src/extending.xml
==============================================================================
--- 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. -->
           <para>
-            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>:
 
 <programlisting>
 rule link
@@ -992,8 +991,8 @@
 </programlisting>
 <!-- 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? -->
 </para></listitem>
 

Modified: trunk/tools/build/v2/doc/src/faq.xml
==============================================================================
--- 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 @@
 </programlisting>
     </para>
   </section>
+
+  <section id="bbv2.faq.names">
+      <title>
+        What is the difference between Boost.Build, 
+        <filename>b2</filename>, <filename>bjam</filename> and Perforce Jam?
+      </title>
+      
+      <para>
+        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".
+      </para>
+
+      <para>
+        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.
+      </para>
+
+      <para>
+        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.
+      </para>
+            
+  </section>
+
 </chapter>
 
 <!--

Modified: trunk/tools/build/v2/doc/src/install.xml
==============================================================================
--- 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>
 
               <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>
             </listitem>
 
@@ -120,7 +120,7 @@
         </para>
 
         <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.
         </para>
 
     

Modified: trunk/tools/build/v2/doc/src/overview.xml
==============================================================================
--- 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 @@
     </para>
 
     <para>
-      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:
       <orderedlist>
         <listitem>

Modified: trunk/tools/build/v2/doc/src/reference.xml
==============================================================================
--- 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 @@
     <section id="bbv2.reference.init">
       <title>Initialization</title>
 
-      <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
+      <para>
+        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

Modified: trunk/tools/build/v2/doc/src/tasks.xml
==============================================================================
--- 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.
     </para>