[Boost-build] Miscellaneous patches.

From: Jurko Gospodnetiæ (jurko.gospodnetic_at_[hidden])
Date: 2007-12-23 12:33:14

   Hi.

   Attached to this post are miscellaneous patches for different Boost 
Build files. Just a collection of tiny changes made while researching 
Boost Build testing the last two days.

     * util/doc.jam - Updated Boost.Jam command line option texts. Minor 
stylistic changes.

     * notes/build_dir_options.txt - Minor stylistic changes.

     * build/project.jam - Typo correction. Minor stylistic changes.

     * kernel/bootstrap.jam - Typo correction. Minor stylistic changes.

     * build/targets.jam - Typo correction. Corrected an invalid 
command-line option name.

     * tools/testing.jam - Corrected an invalid command-line option name.

     * options/help.jam - Corrected an out-of-date comment listing all 
command-line options.

     * doc/src/extending.xml - Corrected the used file suffix for the 
VERBATIM file type. Now the documentation is in sync with the 
'customization' example. This also closes the Trac ticket 134. Minor 
stylistic changes.

   Hope this helps.

   Best regards,
     Jurko Gospodnetiæ


--- X:\Boost_Build\20071222_nightly_build\Original\boost-build\doc\src\extending.xml	2007-12-21 15:33:44.000000000 +-0100
+++ X:\Boost_Build\20071222_nightly_build\Modified\boost-build\doc\src\extending.xml	2007-12-23 18:19:36.000000000 +-0100
@@ -34,36 +34,34 @@
 
     <listitem>
       <simpara>Write the result.</simpara>
     </listitem>
   </orderedlist>
 
-  <para>It's quite easy to achieve. You write special verbatim files
-  that are just C++, except that the very first line of the file
-  contains the name of a variable that should be generated. A simple tool
-  is created that takes a verbatim file and creates a cpp file with
-  a single <code>char*</code> variable whose name is taken from the first line
-  of the verbatim file and whose value is the file's properly quoted content.</para>
+  <para>It's quite easy to achieve. You write special verbatim files that are
+  just C++, except that the very first line of the file contains the name of a
+  variable that should be generated. A simple tool is created that takes a
+  verbatim file and creates a cpp file with a single <code>char*</code> variable
+  whose name is taken from the first line of the verbatim file and whose value
+  is the file's properly quoted content.</para>
 
   <para>Let's see what Boost.Build can do.</para>
 
-  <para>First off, Boost.Build has no idea about "verbatim files". So,
-  you must register a new target type. The following code does
-  it:</para>
+  <para>First off, Boost.Build has no idea about "verbatim files". So, you must
+  register a new target type. The following code does it:</para>
 
 <programlisting>
 import type ;
-type.register VERBATIM : vrb ;
+type.register VERBATIM : verbatim ;
 </programlisting>
 
-  <para>The first parameter to
-  <functionname>type.register</functionname> gives the name of the
-  declared type. By convention, it's uppercase. The second parameter
-  is the suffix for files of this type. So, if Boost.Build sees
-  <filename>code.vrb</filename> in a list of sources, it knows that it's of type
-  <code>VERBATIM</code>.</para>
+  <para>The first parameter to <functionname>type.register</functionname> gives
+  the name of the declared type. By convention, it's uppercase. The second
+  parameter is the suffix for files of this type. So, if Boost.Build sees
+  <filename>code.verbatim</filename> in a list of sources, it knows that it's of
+  type <code>VERBATIM</code>.</para>
 
   <para>Next, you tell Boost.Build that the verbatim files can be
   transformed into C++ files in one build step.  A
   <firstterm>generator</firstterm> is a template for a build step that
   transforms targets of one type (or set of types) into another.  Our
   generator will be called <code>verbatim.inline-file</code>; it
@@ -93,32 +91,32 @@
 
 <!-- We use verbatim.inline-file in one place and just inline-file in
              another. Is this confusing for user?
         -->
 </para>
 
-  <para>Now, we're ready to tie it all together. Put all the code
-  above in file <filename>verbatim.jam</filename>, add <code>import verbatim ;</code> 
-  to <filename>project-root.jam</filename>, and it's possible to write
-  the following in Jamfile:</para>
+  <para>Now, we're ready to tie it all together. Put all the code above in file
+    <filename>verbatim.jam</filename>, add <code>import verbatim ;</code> to
+    <filename>project-root.jam</filename>, and it's possible to write the
+    following in Jamfile:
+  </para>
 
 <programlisting>
 exe codegen : codegen.cpp class_template.verbatim usage.verbatim ;
 </programlisting>
 
-  <para>
-The verbatim files will be automatically converted into C++
-and linked it.
+  <para>The listed verbatim files will be automatically converted into C++,
+    compiled and then linked to the codegen executable.
   </para>
 
-      <para>In the subsequent sections, we will extend this example, and review
-        all the mechanisms in detail. The complete code is available in <filename>example/customization</filename>
-        directory.
-      </para>
-
+  <para>In subsequent sections, we will extend this example, and review all the
+    mechanisms in detail. The complete code is available in the
+    <filename>example/customization</filename> directory.
+  </para>
   </section>
+
   <section id="bbv2.extending.targets">
     <title>Target types</title>
       <para>The first thing we did in the <link
           linkend="bbv2.extender.intro">intruduction</link> was declaring a
       new target type:
 <programlisting>


--- X:\Boost_Build\20071222_nightly_build\Original\boost-build\util\doc.jam	2007-12-21 15:33:44.000000000 +-0100
+++ X:\Boost_Build\20071222_nightly_build\Modified\boost-build\util\doc.jam	2007-12-23 18:04:19.000000000 +-0100
@@ -276,44 +276,45 @@
         "bjam [ options... ] targets..."
         ;
     print.list-start ;
     print.list-item -a;
         Build all targets, even if they are current. ;
     print.list-item -fx;
-        Read '"x"' as the Jamfile for building instead of searching
-        for the Boost.Build system. ;
+        Read '"x"' as the Jamfile for building instead of searching for the
+        Boost.Build system. ;
     print.list-item -jx;
         Run up to '"x"' commands concurrently. ;
     print.list-item -n;
-        Do not execute build commands. Instead print out the commands
-        as they would be executed if building. ;
+        Do not execute build commands. Instead print out the commands as they
+        would be executed if building. ;
     print.list-item -ox;
-        Write the build commands to the file '"x"'. ;
+        Output the used build commands to file '"x"'. ;
     print.list-item -q;
-        Quit as soon as the build of a target fails. Specifying this prevents the
-        attempt of building as many targets as possible regardless of failures. ;
+        Quit as soon as a build failure is encountered. Without this option
+        Boost.Jam will continue building as many targets as it can.
     print.list-item -sx=y;
         Sets a Jam variable '"x"' to the value '"y"', overriding any value that
         variable would have from the environment. ;
     print.list-item -tx;
         Rebuild the target '"x"', even if it is up-to-date. ;
     print.list-item -v;
         Display the version of bjam. ;
     print.list-item --x;
-        Option '"x"' is ignored but considered and option. The option is then
-        available from the '"ARGV"' variable. ;
+        Any option not explicitly handled by Boost.Jam remains available to
+        build scripts using the '"ARGV"' variable. ;
     print.list-item -dn;
         Enables output of diagnostic messages. The debug level '"n"' and all
         below it are enabled by this option. ;
     print.list-item -d+n;
-        Enables output of diagnostic messages. Only the output for debug level '"n"'
-        is enabled. ;
+        Enables output of diagnostic messages. Only the output for debug level
+        '"n"' is enabled. ;
     print.list-end ;
     print.section "Debug Levels"
-        Each debug level shows a different set of information. Usually with the higher
-        levels producing more verbose information. The following levels are supported:
+        Each debug level shows a different set of information. Usually with
+        higher levels producing more verbose information. The following levels
+        are supported:
         ;
     print.list-start ;
     print.list-item 0;
         Turn off all diagnostic output. Only errors are reported. ;
     print.list-item 1;
         Show the actions taken for building targets, as they are executed. ;
@@ -350,15 +351,15 @@
 #
 local rule print-help-options (
     module-name # The doc module.
     )
 {
     print.section "Help Options"
-        These are all the options available for enabling or disabling
-        to control the help system in various ways. Options can be enabled
-        or disabled with '"--help-enable-<option>"', and "'--help-disable-<option>'"
+        These are all the options available for enabling or disabling to control
+        the help system in various ways. Options can be enabled or disabled with
+        '"--help-enable-<option>"', and "'--help-disable-<option>'"
         respectively.
         ;
     local options-to-list = [ MATCH ^[.]option[.](.*) : $($(module-name).variables) ] ;
     if $(options-to-list)
     {
         print.list-start ;


--- X:\Boost_Build\20071222_nightly_build\Original\boost-build\notes\build_dir_option.txt	2007-12-21 15:33:44.000000000 +-0100
+++ X:\Boost_Build\20071222_nightly_build\Modified\boost-build\notes\build_dir_option.txt	2007-12-23 14:43:34.000000000 +-0100
@@ -1,9 +1,9 @@
-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) 
+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
@@ -38,43 +38,40 @@
    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 Boost.Build V2 and V1 build results.
+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 Boost.Build V1
+and V2 build results.
 
-The --build-dir option has no effect if Jamroot does not define any project
-id. Dowing otherwise can lead to nasty problems if we're building two distinct
+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.
+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
+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]
-
+-------------------------------------------------------------------------------
+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 
+[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
-
-
-
-
-


--- X:\Boost_Build\20071222_nightly_build\Original\boost-build\build\project.jam	2007-12-21 15:33:44.000000000 +-0100
+++ X:\Boost_Build\20071222_nightly_build\Modified\boost-build\build\project.jam	2007-12-23 14:40:54.000000000 +-0100
@@ -286,14 +286,13 @@
     #
     local jamfile-to-load = [ path.glob $(dir) : $(JAMROOT) ] ;
     if ! $(jamfile-to-load)
     {
         jamfile-to-load = [ find-jamfile $(dir) ] ;
     }
-    
-    
+
     # The module of the jamfile.
     #
     local jamfile-module = [ module-name  [ path.parent $(jamfile-to-load) ] ] ;
 
     # Initialize the jamfile module before loading.
     #    
@@ -321,41 +320,37 @@
     }
     # Now do some checks
     if $(.current-project) != $(saved-project)
     {
         errors.error "The value of the .current-project variable"
           : "has magically changed after loading a Jamfile."
-          : "This means some of the targets might be defined a the wrong project."
+          : "This means some of the targets might be defined in the wrong project."
           : "after loading " $(jamfile-module) 
           : "expected value " $(saved-project)  
           : "actual value " $(.current-project)
           ;
     }
 
     if $(.global-build-dir)
     {        
         local id = [ attribute $(jamfile-module) id ] ;
-        local project-root  = [ attribute $(jamfile-module) project-root ] ;
+        local project-root = [ attribute $(jamfile-module) project-root ] ;
         local location = [ attribute $(jamfile-module) location ] ;
-    
+
         if $(location) && $(project-root) = $(dir)
         {
             # This is Jamroot
             if ! $(id)
             {
                 ECHO "warning: the --build-dir option was specified" ;
                 ECHO "warning: but Jamroot at '$(dir)'" ;
                 ECHO "warning: specified no project id" ;
                 ECHO "warning: the --build-dir option will be ignored" ;
             }            
         }        
     }        
-    
-
-    
-    
 }
 
 rule mark-as-user ( module-name )
 {
     if USER_MODULE in [ RULENAMES ]
     {            
@@ -880,16 +875,16 @@
         local global-build-dir = 
           [ modules.peek project : .global-build-dir ] ;
         
         if $(global-build-dir)
         {                
             local location = [ $(attributes).get location ] ;
-            # Project with empty location is 'standalone' project, like
-            # user-config, or qt.  It has no build dir.
+            # Project with an empty location is a 'standalone' project such as
+            # user-config or qt.  It has no build dir.
             # If we try to set build dir for user-config, we'll then
-            # try to inherit it, with either weird, or wrong consequences.
+            # try to inherit it, with either weird or wrong consequences.
             if $(location) && $(location) = [ $(attributes).get project-root ]
             {
                 # This is Jamroot.
                 if $(id)
                 {                    
                     if $(explicit-build-dir) 


--- X:\Boost_Build\20071222_nightly_build\Original\boost-build\kernel\bootstrap.jam	2007-12-21 15:33:44.000000000 +-0100
+++ X:\Boost_Build\20071222_nightly_build\Modified\boost-build\kernel\bootstrap.jam	2007-12-23 14:46:48.000000000 +-0100
@@ -115,20 +115,19 @@
 # Process option plugins first to alow them to prevent loading
 # the rest of the build system.
 #
 import option ;
 local dont-build = [ option.process ] ;
 
-# Should we skip building, i.e. loding the build system, according
+# Should we skip building, i.e. loading the build system, according
 # to the options processed?
 #
 if ! $(dont-build)
 {
     # Allow users to override the build system file from the
     # command-line (mostly for testing)
     local build-system = [ MATCH --build-system=(.*) : $(ARGV) ] ;
     build-system ?= build-system ;
 
     # Use last element in case of multiple command-line options
     import $(build-system[-1]) ;
 }
-


--- X:\Boost_Build\20071222_nightly_build\Original\boost-build\build\targets.jam	2007-12-21 15:33:44.000000000 +-0100
+++ X:\Boost_Build\20071222_nightly_build\Modified\boost-build\build\targets.jam	2007-12-23 16:16:09.000000000 +-0100
@@ -1065,13 +1065,13 @@
             errors.user-error "properties found in the 'sources' parameter for" [ full-name ] ;
         }
     }
     
     # Returns the list of abstract-targets which are used as sources.
     # The extra properties specified for sources are not represented.
-    # The only used of this rule at the moment is the "--dump-test"
+    # The only user of this rule at the moment is the "--dump-tests"
     # feature of the test system.
     rule sources ( )
     {
         if ! $(self.source-targets) {
             for local s in $(self.sources)
             {


--- X:\Boost_Build\20071222_nightly_build\Original\boost-build\tools\testing.jam	2007-12-21 15:33:44.000000000 +-0100
+++ X:\Boost_Build\20071222_nightly_build\Modified\boost-build\tools\testing.jam	2007-12-23 16:16:38.000000000 +-0100
@@ -87,13 +87,13 @@
     local t = 
       [ targets.create-typed-target 
           [ type.type-from-rule-name $(target-type) ] : $(project)
             : $(target-name) : $(sources) 
             : $(requirements) <location-prefix>$(target-name).test ] ;
     
-    # Remember the test (for --dump-test). 
+    # Remember the test (for --dump-tests). 
     # A good way would be to collect all given a project.
     # This has some technical problems: e.g. we can't call this dump from
     # Jamfile since projects referred by 'build-project' are not available until
     # whole Jamfile is loaded.
     .all-tests += $(t) ;
     return $(t) ;    


--- X:\Boost_Build\20071222_nightly_build\Original\boost-build\options\help.jam	2007-12-21 15:33:44.000000000 +-0100
+++ X:\Boost_Build\20071222_nightly_build\Modified\boost-build\options\help.jam	2007-12-23 16:35:30.000000000 +-0100
@@ -22,21 +22,22 @@
 .not-modules =
     boost-build bootstrap site-config test user-config
     -tools allyourbase boost-base features python stlport testing unit-tests ;
 
 # The help system options are parsed here and handed off to the doc
 # module to translate into documentation requests and actions. The
-# understood options are::
+# understood options are:
 #
-#    --help-all
+#    --help-disable-<option>
+#    --help-doc-options
 #    --help-enable-<option>
-#    --help-disable-<option>
+#    --help-internal
+#    --help-options
+#    --help-usage
 #    --help-output <type>
 #    --help-output-file <file>
-#    --help-options
-#    --help-usage
 #    --help [<module-or-class>]
 #
 rule process (
     command # The option.
     : values * # The values, starting after the "=".
     )