diff --git a/build_system.htm b/build_system.htm index 9546f3596..2b2d967e6 100644 --- a/build_system.htm +++ b/build_system.htm @@ -1,100 +1,103 @@ - + + - + + Boost Build System - + - - - c++boost.gif (8819 bytes) + + c++boost.gif (8819 bytes)

Boost Build System

Synopsis

-

Boost.Build is a system for large project software construction built on - Boost.Jam, a descendant of "Perforce Jam", an - open-source make replacement[1]. Key features are: +

Boost.Build is a system for large project software construction built + on Boost.Jam, a descendant of "Perforce Jam", an open-source + make replacement[1]. Key features are:

Status

- Boost.Build v1 is a useful, mature system. However, its design and - structure are not easily adapted to support some of the features - we'd like to see in the future. To this end, the Boost.Build - developers have begun work on v2 of Boost.Build, which will be - based around this - design document. If you are - interested in contributing to this effort or you wish to discuss - the design of Boost.Build, please post inquiries to the jamboost - mailing list at yahoogroups. + structure are not easily adapted to support some of the features we'd + like to see in the future. To this end, the Boost.Build developers have + begun work on v2 of Boost.Build, which will be based around this design document. If you are interested in + contributing to this effort or you wish to discuss the design of + Boost.Build, please post inquiries to the jamboost mailing list at + yahoogroups. -

Here are some of the design criteria that - led to these features. +

Here are some of the design criteria + that led to these features.

Table of Contents

+
  • Internals +
    • -
  • Target Names +
  • Target Names
    • -
  • Global Variables +
  • Global Variables
    • +
  • Design Criteria +
    • -
  • Footnotes +
  • Footnotes

    • Getting Started

    Installing Boost.Jam

    - - Follow these instructions to acquire - a bjam executable for your platform. Install it somewhere in your - path. + Follow these instructions to acquire a bjam + executable for your platform. Install it somewhere in your path.

    Initiating a Build

    -

    Boost.Build responds to several global variable settings. The - easiest way to get going is usually to use environment variables, - though you can also set them on the command-line, using - -sVARIABLE_NAME=value. In - addition to the toolset - configuration variables, you can use the TOOLS - variable to indicate which toolset(s) to build with, and the - BUILD variable to describe how you want things built. In - many cases it should be sufficient to invoke bjam - with no variable settings. +

    Boost.Build responds to several global variable settings. The easiest + way to get going is usually to use environment variables, though you can + also set them on the command-line, using + -sVARIABLE_NAME=value. In addition to the + toolset configuration variables, you + can use the TOOLS variable to indicate which toolset(s) to build + with, and the BUILD variable to describe how you want things + built. In many cases it should be sufficient to invoke bjam + with no variable settings.

    -

    Some example Boost.Jam invocations: +

    Some example Boost.Jam invocations:

    - - + + - + + - + - - + - + bjam -sBUILD="<cxxflags>/G6"
    +   + + + + +
    Command Line(s) + Command Line(s)Effects + Effects
    -
    bjam -sTOOLS=gcc my_target
+
    +bjam -sTOOLS=gcc my_target
 
    
+
    		default (debug) BUILD of - my_targetwith GCC + my_targetwith GCC
    - 
    bjam -sTOOLS="msvc gcc"
    +
    +bjam -sTOOLS="msvc gcc"
+
    +     		default-build all with msvc and gcc + default-build all with msvc and gcc
    -
    set TOOLS=msvc
+
    +set TOOLS=msvc
 bjam
 
    
+
    		Set an NT environment variable to always build with MSVC
    - default-build all. + default-build all.
    -
    bjam "-sBUILD=release <debug-symbols>on"
+
    +bjam "-sBUILD=release <debug-symbols>on"
 
    
+
    		release build with debug symbols of all using - default TOOLS - + release build with debug symbols of all using default + TOOLS
    bjam -sBUILD="debug release"
    +     		+
    +bjam -sBUILD="debug release"
+
    +     		debug and release build all. - + debug and release build all.
    set TOOLS=msvc
    - bjam -sBUILD="<cxxflags>/G6"
    -     		Set an NT environment variable to always build with MSVC
    - default-build all, adding a compiler command line switch
    Set an NT environment variable to always build with MSVC
    + default-build all, adding a compiler command line + switch
    set TOOLS=msvc gcc
    - bjam -sBUILD="<msvc><*><cxxflags>/G6"
    -     		Set an NT environment variable to always build with MSVC and + bjam -sBUILD="<msvc><*><cxxflags>/G6"
    +      		Set an NT environment variable to always build with MSVC and GCC
    - default-build all, adding a MSVC-specific compiler command line switch
    + default-build all, adding a MSVC-specific compiler command + line switch + +

    Setting Jam Variables

    -

    The "-s" options in the command lines above are - passing variable settings to the build system. There are actually three ways to do - that: +

    The "-s" options in the command lines above are passing + variable settings to the build system. There are actually three ways to + do that:

    -

    An Example Jamfile

    Here is an example of a simple subproject Jamfile. In this example, it is - assumed that the user has set BOOST_ROOT, either as an environment - variable, on the command-line or in the project's Jamrules file: + assumed that the user has set BOOST_ROOT, either as an + environment variable, on the command-line or in the project's Jamrules file:
    -
    subproject foo/bar/baz ; # path to here from project root
+
    +subproject foo/bar/baz ; # path to here from project root
 
 # A static library called 'baz'
 lib baz : baz1.cpp baz2.cpp # C++ sources
@@ -326,174 +400,184 @@ exe test : <lib>baz # use the 'baz' library
 
     
    That's it! The build system takes care of the rest. If the you want to
     be able to build all subprojects from the project root directory, you can
-    add a Jamfile at the root:
+    add a Jamfile at the root:
    
 
     
    
-
    project-root ; # declare this to be the project root directory
+
    +project-root ; # declare this to be the project root directory
 # Read subproject Jamfiles
-subinclude foo/bar/baz foo/bar/... ;
-subinclude a/b/c ... ; # more subincludes
+subinclude foo/bar/baz foo/bar/... ;
+subinclude a/b/c ... ; # more subincludes
 
    
     
    
 
     
    Support Files
    
 
-    
-
    To use the build system, the following must be located in your project's root 
-    directory, or in a directory specified in the BOOST_BUILD_PATH variable. 
-    It is usually convenient to specify the BOOST_BUILD_PATH in your 
-    project's Jamrules file. The Boost Jamrules 
-    file shows an example. 
-
-      
-        
+    
    Filename(s)
+    
    To use the build system, the following must be located in your
+    project's root directory, or in a directory specified in the
+    BOOST_BUILD_PATH variable. It is usually convenient to specify
+    the BOOST_BUILD_PATH in your project's Jamrules file. The Boost
+    Jamrules file shows an example.
    
 
-            		Meaning
+    
+      
+        
+
+        
+      
-        
 
-        
+      
-        
 
-        
+      
-        
 
-        
+      
-        
 
-        
+      
    Filename(s)Meaning
    
 
       
    toolset-tools.jam 
+        toolset-tools.jamFeature-to-command-line mapping for toolset.
+        Feature-to-command-line mapping for toolset.
    
 
       
    features.jam 
+        features.jamAbstract toolset feature descriptions.
+        Abstract toolset feature descriptions.
    
 
       
    boost-base.jam 
+        boost-base.jamBoost build system-specific rule definitions.
+        Boost build system-specific rule definitions.
    
 
       
    unit-tests.jam 
+        unit-tests.jamUnit tests and assertions for boost Jam code.
+        Unit tests and assertions for boost Jam code.
    
     
    
     The boost-base.jam file is temporary, and will eventually be
     compiled into our Jam executable. 
 
     
    Basic Design and Terminology
    
-    This section gives an overview of the way that the system works, outlining 
-the system's capabilities and overall design. It also introduces the terminology 
-and concepts necessary to understand the sections on writing Jamfiles and command-line 
-invocations. 
+    This section gives an overview of the way that the system works,
+    outlining the system's capabilities and overall design. It also
+    introduces the terminology and concepts necessary to understand the
+    sections on writing Jamfiles and command-line invocations. 
 
-
    Projects and Subprojects
    
+    
    Projects and Subprojects
    
 
     
    A project is a source directory tree containing at least one
     Jamfile. The root directory of the project is known as the
-    project root. The root directory of a project
-    may contain a Jamrules file, which contains project-specific Jam
-    code. If the Jamrules file is not present when Jam is invoked, a
-    warning will be issued.
+    project root. The root directory of a
+    project may contain a Jamrules file, which contains
+    project-specific Jam code. If the Jamrules file is not present
+    when Jam is invoked, a warning will be issued.
    
 
     
    Subdirectories containing Jamfiles are called subproject
-    directories. Each such Jamfile describes a subproject.
+    directories. Each such Jamfile describes a
+    subproject.
    
 
-    
-
    The build system installation directory is a directory containing Jam 
-    files describing compilers and build variants. The installation directory 
-    can be specified implicitly by setting the variable BOOST_BUILD_PATH. 
-    This lists a set of directories to search for the files comprising the build 
-    system. If the installation directory is not specified, it is the same as 
-    the project root, and BOOST_BUILD_PATH is set to include that directory. 
-
    Targets
    
+    
    The build system installation directory is a directory
+    containing Jam files describing compilers and build variants. The
+    installation directory can be specified implicitly by setting the
+    variable BOOST_BUILD_PATH. This lists a set of directories to
+    search for the files comprising the build system. If the installation
+    directory is not specified, it is the same as the project root, and
+    BOOST_BUILD_PATH is set to include that directory.
    
 
-    
    Each Jamfile describes one or more main targets.
+    
    Targets
    
+
+    
    Each Jamfile describes one or more main targets.
    
 
     
    Each main target is an abstract description of one or more built
     targets which are expressions of the corresponding main target under
     particular compilers and build variants. Intermediate files such as
-    .o/.obj files generated by compiling .cpp files
-    as a consequence of building a main target are also referred to as built
-    targets. The term build directory tree refers to the location of
-    built target files.
+    .o/.obj files generated by compiling .cpp
+    files as a consequence of building a main target are also referred to as
+    built targets. The term build directory tree refers to the
+    location of built target files.
    
 
     
      
       
    • By default, the build directory tree is overlaid with the project
       directory tree, with targets generated into a subtree rooted at the
-      bin subdirectory of each subproject directory (the name of this
-      directory can be customized by changing the BIN_DIRECTORY
-      variable.
+      bin subdirectory of each subproject directory (the name of
+      this directory can be customized by changing the BIN_DIRECTORY
+      variable.
      • 
 
       
    • If the variable
       ALL_LOCATE_TARGET is set, it specifies an alternate build
-      directory tree whose structure mirrors that of the project. In this case,
-      built targets of a subproject are generated into the corresponding
-      directory of the build directory tree.
+      directory tree whose structure mirrors that of the project. In this
+      case, built targets of a subproject are generated into the
+      corresponding directory of the build directory tree.
      • 
     
    
     For each main target, there is a corresponding location in the build
     directory tree known as the target's build root, where all
-    intermediate and final targets resulting from that main target are located.
-    
+    intermediate and final targets resulting from that main target are
+    located. 
 
     
    Features and Properties
    
 
-    
    A feature is a normalized (toolset-independent) description of an
-    individual build parameter, such as whether inlining is enabled. Each
+    
    A feature is a normalized (toolset-independent) description of
+    an individual build parameter, such as whether inlining is enabled. Each
     feature usually corresponds to a command-line option of one or more build
-    tools. Features come in four varieties:
+    tools. Features come in four varieties:
    
 
     
      
       
    1. Simple features can take on any of several predetermined
-      values. For example, the feature optimization might take one of
-      the values off, speed, or space. Simple
-      features have a default value. The key aspect of simple features is that
-      they are assumed to affect link compatibility: object files generated
-      with different values for a simple feature are generated into a separate
-      directories, and (with a few exceptions) main targets generated with
-      different values won't be linked together.
+      values. For example, the feature optimization might take one
+      of the values off, speed, or space. Simple
+      features have a default value. The key aspect of simple features is
+      that they are assumed to affect link compatibility: object files
+      generated with different values for a simple feature are generated into
+      a separate directories, and (with a few exceptions) main targets
+      generated with different values won't be linked together.
      2. 
 
       
    2. Free features can either be single-valued, as above, or may
-      take on any number of user-specified values simultaneously. For example,
-      the define feature for a release build might have the values
-      NDEBUG and BOOST_RELEASE_BUILD. Free features are
-      assumed not to affect link compatibility.
+      take on any number of user-specified values simultaneously. For
+      example, the define feature for a release build might have the
+      values NDEBUG and BOOST_RELEASE_BUILD. Free features
+      are assumed not to affect link compatibility.
      3. 
 
       
    3. Path features are free features whose values describe paths
       which may be relative to the subproject (such as linked libraries or
-      #include search directories). The build system treats the values
-      of these features specially to ensure that they are interpreted relative
-      to the subproject directory regardless of the directory where Jam was
-      invoked.
+      #include search directories). The build system treats the
+      values of these features specially to ensure that they are interpreted
+      relative to the subproject directory regardless of the directory where
+      Jam was invoked.
      4. 
 
-      
    4. Dependency features are path features whose values describe a
-      dependency of built targets. For example, an external library might be
-      specified with a dependency-feature: if the library is updated, the
+      
    5. Dependency features are path features whose values describe
+      a dependency of built targets. For example, an external library might
+      be specified with a dependency-feature: if the library is updated, the
       target will be updated also. The <library-file> feature
-      works this way [2].
+      works this way [2].
      6. 
     
    
 
     
    A feature-value pair is known as a build property, or simply
-    property. The prefixes simple, free, path, and
-    dependency apply to properties in an analogous way to features.
+    property. The prefixes simple, free, path,
+    and dependency apply to properties in an analogous way to
+    features.
    
 
     
    Build Variants
    
 
     
    A build variant, or simply variant is a named set of build
-    properties describing how targets should be built. Typically you'll want at
-    least two separate variants: one for debugging, and one for your release
-    code.
+    properties describing how targets should be built. Typically you'll want
+    at least two separate variants: one for debugging, and one for your
+    release code.
    
 
-    
    Built targets for distinct build variants and toolsets are generated in
-    separate parts of the build directory tree, known as the variant
-    directories. For example, a (sub)project with main targets foo
-    and bar, compiled with both GCC and KAI for debug and
-    release variants might generate the following structure (target
-    directories in bold).
+    
    Built targets for distinct build variants and toolsets are generated
+    in separate parts of the build directory tree, known as the variant
+    directories. For example, a (sub)project with main targets
+    foo and bar, compiled with both GCC and KAI for
+    debug and release variants might generate the following
+    structure (target directories in bold).
    
 
     
    
-
     bin
- +-foo  <--- foo's build root
+
    + bin
+ +-foo  <--- foo's build root
  | +-gcc
  | | +-debug
  | | `-release
  | `-kai
  |   +-debug
  |   `-release
- `-bar  <--- bar's build root
+ `-bar  <--- bar's build root
    +-gcc
    | +-debug
    | `-release
@@ -505,15 +589,15 @@ invocations.
 
     
    The properties constituting a variant may differ according to toolset,
     so debug may mean a slightly different set of properties for two
-    different compilers.
+    different compilers.
    
 
     
    Subvariants
    
 
-    
    When a target is built with simple properties that don't exactly
-    match those specified in a build variant, the non-matching features are
-    called subvariant features and the target is located in a
-    subvariant directory beneath the directory of the base variant. This
-    can occur for two reasons:
+    
    When a target is built with simple properties that don't
+    exactly match those specified in a build variant, the non-matching
+    features are called subvariant features and the target is located
+    in a subvariant directory beneath the directory of the base
+    variant. This can occur for two reasons:
    
 
     
      
       
    1. 
@@ -521,34 +605,37 @@ invocations.
         simple features have no value specified in the build variant, a value
         must be chosen. Even when the default value is used, the target is
         generated into a subvariant directory. For example, the
-        runtime-link feature may be unspecified in the debug
-        variant, but relevant to MSVC. In that case, a fragment of the target
-        tree might look like: 
+        runtime-link feature may be unspecified in the
+        debug variant, but relevant to MSVC. In that case, a
+        fragment of the target tree might look like: 
 
         
      
-
       bin
- +-foo  <--- foo's build root
+
      + bin
+ +-foo  <--- foo's build root
  | +-msvc
  | | +-debug
  . . . `-runtime-link-dynamic
  . . .
 
      
         
      
-        Because the default value of runtime-link is dynamic,
-        when the debug variant is requested, the
+        Because the default value of runtime-link is
+        dynamic, when the debug variant is requested, the
         runtime-link-dynamic subvariant of foo is built.
      
         
      
+      
      2. 
 
       
    2. 
-        It is possible to request (either on the command-line, or as part of a
-        main target description) that particular subvariants be built. For
+        It is possible to request (either on the command-line, or as part of
+        a main target description) that particular subvariants be built. For
         example, it may be desirable to generate builds that link to the
         runtime both statically and dynamically. In that case, both
         subvariant directories in the example above would be generated: 
 
         
      
-
       bin
- +-foo  <--- foo's build root
+
      + bin
+ +-foo  <--- foo's build root
  | +-msvc
  | | +-debug
  . . . +-runtime-link-dynamic
@@ -556,21 +643,23 @@ invocations.
  . . .
 
      
         
      
+      
      3. 
     
    
-    In no case will targets be built directly into bin/foo/msvc/debug,
-    since the debug variant doesn't include the runtime-link
-    feature, which is relevant to MSVC. 
+    In no case will targets be built directly into
+    bin/foo/msvc/debug, since the debug variant doesn't
+    include the runtime-link feature, which is relevant to MSVC. 
 
     
    When a subvariant includes multiple subvariant features, targets are
-    built into a subvariant directory whose path is determined by concatenating
-    the properties sorted in order of their feature names. For example, the
-    borland compiler, which uses different libraries depending on whether the
-    target is a console or GUI program, might create the following structure
-    for a DLL:
+    built into a subvariant directory whose path is determined by
+    concatenating the properties sorted in order of their feature names. For
+    example, the borland compiler, which uses different libraries depending
+    on whether the target is a console or GUI program, might create the
+    following structure for a DLL:
    
 
     
    
-    
     bin
- +-foo  <--- foo's build root
+
    + bin
+ +-foo  <--- foo's build root
  | +-msvc
  | | +-debug
  | | | +-runtime-link-dynamic
@@ -578,141 +667,156 @@ invocations.
  | | | | `-user-interface-gui
  . . . `-runtime-link-static
  . . .   +-user-interface-console
- . . .   `user-interface-gui
+ . . .   `user-interface-gui
 
    
     
    
 
     
    Any configuration of properties for which a target is built, whether
     base variant or subvariant, is known as a build configuration, or
-    simply a build.
+    simply a build.
    
 
     
    Dependent Targets
    
 
     
    When a main target depends on the product of a second main target (as
     when an executable depends on and links to a static library), each build
     configuration of the dependent target is depends on the
-    corresponding build of the dependency. Because only simple features
-    participate in build identity, the dependent and dependency targets may
-    have completely different free features. This puts the onus on the user for
-    ensuring link-compatibility when certain free properties are used. For
-    example, when assert() is used in header files, the preprocessor
-    symbol NDEBUG can impact link-compatibility of separate
-    compilation units. This danger can be minimized by encapsulating such
-    feature differences inside of build variants.
+    corresponding build of the dependency. Because only simple
+    features participate in build identity, the dependent and dependency
+    targets may have completely different free features. This puts the onus
+    on the user for ensuring link-compatibility when certain free properties
+    are used. For example, when assert() is used in header files,
+    the preprocessor symbol NDEBUG can impact link-compatibility of
+    separate compilation units. This danger can be minimized by encapsulating
+    such feature differences inside of build variants.
    
 
     
    Usage
    
 
     
    This section describes how to start a build from the command-line and
     how to write project and subproject Jamfiles. It also describes the other
-    files written in the Jam language: build-tool specification files, feature
-    descriptions files.
+    files written in the Jam language: build-tool specification files,
+    feature descriptions files.
    
 
     
    The Command Line
    
 
-    
    This section describes in detail how the build system can be invoked.
+    
    This section describes in detail how the build system can be
+    invoked.
    
 
     
    User Targets
    
 
     
    The Jam command line ends with an optional list of target names; if no
-    target names are supplied, the built-in pseudotarget all is built.
-    In a large project, naming targets can be dicey because of collisions. Jam
-    uses a mechanism called grist to distinguish targets
-    that would otherwise have the same name. Fortunately, you won't often have
-    to supply grist at the command-line. When you declare a main target, a Jam
-    pseudotarget of the same name is created which depends on all of the
-    subvariants requested for your invocation of the build system. For example,
-    if your subproject declares:
+    target names are supplied, the built-in pseudotarget all is
+    built. In a large project, naming targets can be dicey because of
+    collisions. Jam uses a mechanism called grist to
+    distinguish targets that would otherwise have the same name. Fortunately,
+    you won't often have to supply grist at the command-line. When you
+    declare a main target, a Jam pseudotarget of the same name is created
+    which depends on all of the subvariants requested for your
+    invocation of the build system. For example, if your subproject
+    declares:
    
 
     
    
-
    exe my_target : my_source1.cpp my_source2.c ;
+
    +exe my_target : my_source1.cpp my_source2.c ;
 
    
     
    
-    and you invoke Jam with -sBUILD="debug release" my_target, you
-    will build both the debug and release versions of my_target. 
-
+    and you invoke Jam with -sBUILD="debug release" my_target,
+    you will build both the debug and release versions of my_target.
     
-
    These simple, ungristed names are called user targets, and are only 
-    available for the subproject where Jam is invoked. That way, builds from the 
-    top level (which may include many Jamfiles through the subinclude rule) and 
-    builds of library dependencies (which may live in other subprojects), don't 
-    collide. If it is necessary to refer more explicitly to a particular target 
-    from the command-line, you will have to add ``grist''. Please see this 
-    section for a more complete description of how to name particular targets 
-    in a build. 
-
    Global Variables
    
+
+    
    These simple, ungristed names are called user targets, and are
+    only available for the subproject where Jam is invoked. That way, builds
+    from the top level (which may include many Jamfiles through the
+    subinclude rule) and builds of library dependencies (which may live in
+    other subprojects), don't collide. If it is necessary to refer more
+    explicitly to a particular target from the command-line, you will have to
+    add ``grist''. Please see this section for a
+    more complete description of how to name particular targets in a
+    build.
    
+
+    
    Global Variables
    
 
     
    This is a partial list of global variables that can be set on the
     command-line. Of course you are free to write your own Jam rules which
     interpret other variables from the command-line. This list just details
     some of the variables used by the build system itself. Note also that if
     you don't like the default values you can override them in your project's
-    Jamrules file.
+    Jamrules file.
    
 
     
-        
 
-        
 
-        
 
-        
+      
 
-        
 
-        
+
+        
+      
-        
+
+        
+      
 
-        
 
-        
 
-        
+      
-        
 
-        
+      
-        
+      
-        
+      
 
-        
 
-        
 
-        
+      
    
       
    Variable  
+        Variable Default
+        DefaultExample
+        ExampleNotes
+        Notes
    
 
       
    
         TOOLS 
-         
+        Platform-dependent
+        Platform-dependent"-sTOOLS=gcc msvc" 
-        build with gcc and msvc
+        "-sTOOLS=gcc msvc"build with gcc and msvc
    
 
       
    -sTOOLS=gcc 
-        build with gcc
+        -sTOOLS=gccbuild with gcc
    
 
       
    
         BUILD 
         
          
-         
+        debug 
+        debug-sBUILD=release 
+        -sBUILD=releasebuild the release variant
+        build the release variant
    
 
       
    "-sBUILD=debug release" 
+        "-sBUILD=debug release"build both debug and release variants
+        build both debug and release variants
    
 
       
    "-sBUILD=<optimization>speed" 
+        "-sBUILD=<optimization>speed"
 
         build a subvariant of the default variant (debug) with
-        optimization for speed.
+        optimization for speed.
    
 
       
    "-sBUILD=debug release <runtime-link>static/dynamic"
-        
+        "-sBUILD=debug release
+        <runtime-link>static/dynamic"
 
         build subvariants of the debug and release variants that link to
-        the runtime both statically and dynamically.
+        the runtime both statically and dynamically.
    
 
       
    
         ALL_LOCATE_TARGET 
         
          
-         
+        empty 
+        empty-sALL_LOCATE_TARGET=~/build 
+        -sALL_LOCATE_TARGET=~/buildGenerate all build results in the build subdirectory of the 
-            user's home directory (UNIX). 
+        Generate all build results in the build subdirectory of
+        the user's home directory (UNIX).
    
     
    
 
     
    SubProject Jamfiles
    
@@ -721,189 +825,233 @@ invocations.
     
    The subproject rule
    
 
     
    A subproject's Jamfile begins with an invocation of the
-    subproject rule that specifies the subproject's location relative
-    to the top of the project tree:
+    subproject rule that specifies the subproject's location
+    relative to the top of the project tree:
    
 
     
    
-
    subproject path-from-top ;
+
    +subproject path-from-top ;
 
    
     
    
 
-    
    The subproject rule tells the build system where to place built
-    targets from the subproject in case ALL_LOCATE_TARGET is used to
-    specify the build directory tree. If there is a Jamfile in the project root
-    directory, you should use the project-root rule instead:
+    
    The subproject rule tells the build system where to place
+    built targets from the subproject in case ALL_LOCATE_TARGET is
+    used to specify the build directory tree. If there is a Jamfile in the
+    project root directory, you should use the project-root rule
+    instead:
    
 
     
    
-
    project-root ;
+
    +project-root ;
 
    
     
    
 
     
    Describing Main Targets
    
 
-    
    A main target is described using the following syntax:
+    
    A main target is described using the following syntax:
    
 
     
    
-
    target-type name : sources
+
    +target-type name : sources
     [ : requirements [ : default-BUILD ] ] ;
 
    
     
    
 
-    
-
      
-    
    • target-type may be one of exe, lib, dll, 
-        stage or template. These are actually names of Jam rules.
-        Additional main target rules are possible; see status/Jamfile or libs/python/build/Jamfile for 
-        examples.
      
-        
      
-    
    • name specifies the name of the main target, multiple targets with 
-        the same name are allowed but only if they are of different types. Normally 
-        this is not the name of the final target file generated. The target file 
-        name depends on the type of target which controls how the base target 
-        name is renamed to conform to platform conventions. For exes 
-        the name might be the same or *.exe. For libs the name 
-        might be *.lib or lib*.a. And for dlls the 
-        name might be *.dll or lib*.so. For platform specific 
-        naming consult the allyourbase.jam 
-        file in the build system.
      
-        
      
-    
    • sources is a list of paths to source files and dependency targets. 
-        A dependency target path is preceded by <template>,
-        <lib>, <dll>, or <exe>,
-        and the final path component specifies the name of a main target in a Jamfile located
-        in the directory given by the initial path components. Paths may be absolute or
-        relative. The type of dependency is also used to decide how to link to it when needed. 
-        Specifying a <lib> indicates the use of static linking, 
-        as opposed to specifying a <dll> which uses dynamic linking. 
-        For example in Unix static linking will be done directly, and dynamic 
-        linking with the common "-l" liker flag and use of 
-        LD_LIBRARY_PATH.
      
-        
      
-        NOTE: It is important to match up the type of source dependency 
-        with the same type the dependency is built as. Trying to specify a source 
-        dependency of <lib> when the target is defined as a <dll> 
-        will cause an error.
      
-        
      
-    
    •  requirements specifies the build 
-        properties intrinsic to the target. Requirements are given as sets of 
-        optionally-qualified build properties: 
-        
       
-
      [[<compiler>]<variant>]<feature>value
+    
        
+      
      • target-type may be one of exe, lib,
+      dll, stage or template. These are actually
+      names of Jam rules. Additional main target rules are possible; see
+      status/Jamfile or libs/python/build/Jamfile
+      for examples.
        
+      
        
+      
        • 
+
+      
      • name specifies the name of the main target, multiple targets
+      with the same name are allowed but only if they are of different types.
+      Normally this is not the name of the final target file generated. The
+      target file name depends on the type of target which controls how the
+      base target name is renamed to conform to platform conventions. For
+      exes the name might be the same or *.exe. For
+      libs the name might be *.lib or lib*.a. And
+      for dlls the name might be *.dll or lib*.so.
+      For platform specific naming consult the allyourbase.jam file in the build
+      system.
        
+      
        
+      
        • 
+
+      
      • sources is a list of paths to source files and dependency
+      targets. A dependency target path is preceded by
+      <template>, <lib>, <dll>,
+      or <exe>, and the final path component specifies the
+      name of a main target in a Jamfile located in the directory given by
+      the initial path components. Paths may be absolute or relative. The
+      type of dependency is also used to decide how to link to it when
+      needed. Specifying a <lib> indicates the use of static
+      linking, as opposed to specifying a <dll> which uses
+      dynamic linking. For example in Unix static linking will be done
+      directly, and dynamic linking with the common "-l" liker flag
+      and use of LD_LIBRARY_PATH.
        
+      
        
+       NOTE: It is important to match up the type of source dependency
+      with the same type the dependency is built as. Trying to specify a
+      source dependency of <lib> when the target is defined as
+      a <dll> will cause an error.
        
+      
        
+      
        • 
+
+      
      • 
+        requirements specifies the
+        build properties intrinsic to the target. Requirements are given as
+        sets of optionally-qualified build properties: 
+
+        
        
+
        +[[<compiler>]<variant>]<feature>value
 
        
         
        
-        <compiler> and <variant>, 
-        if supplied, can be used to restrict the applicability of the requirement. 
-        Either one may be replaced by <*>, which is the same as 
-        omitting it. 
-        
        The system checks that simple feature requirements are not violated 
-            by explicit subvariant build requests, and will issue a warning otherwise. 
-            Free features specified as requirements are simply added to each corresponding 
-            build configuration.
        
-            
        
-    
      •  default-BUILD specifies the configurations 
-        that should be built if the BUILD variable is not otherwise specified. Any elements 
-        not beginning with ``<...>'' refer to build variants. 
-        Other elements use the same syntax as the requirements described above, except that multiple 
-        values may be specified for a simple feature by separating them with a 
-        slash, forming (qualified) multi-valued properties: 
-        
         
-
        [[<compiler>]<variant>]<feature>value1[/value2...]
+        <compiler> and <variant>,
+        if supplied, can be used to restrict the applicability of the
+        requirement. Either one may be replaced by <*>, which
+        is the same as omitting it. 
+
+        
        The system checks that simple feature requirements are not
+        violated by explicit subvariant build requests, and will issue a
+        warning otherwise. Free features specified as requirements are simply
+        added to each corresponding build configuration.
        
+        
        
+        
        
+      
        • 
+
+      
      • 
+        default-BUILD specifies the
+        configurations that should be built if the BUILD variable is not otherwise specified. Any
+        elements not beginning with ``<...>'' refer
+        to build variants. Other elements use the same syntax as the requirements described above, except that
+        multiple values may be specified for a simple feature by separating
+        them with a slash, forming (qualified) multi-valued
+        properties: 
+
+        
        
+
        +[[<compiler>]<variant>]<feature>value1[/value2...]
 
        
         
        
-        When multiple values are specified, it causes all the implied configurations 
-        to be built by default. It is also possible to prevent any default builds 
-        from occurring on this target by using <suppress>true 
-        . This suppresses any local targets, either implicit or explicit, from 
-        building. But, this does not prevent implied targets as required by a 
-        dependency by another target to this one from being built. This is useful, 
-        for example, for defining a set of libraries generically and having them 
-        built only when another target like an exe is built. Such use might look 
-        like: 
-        
         
-
        lib basic : basic.cpp : : <suppress>true ;

        exe test : test.cpp <lib>basic ;
        
+        When multiple values are specified, it causes all the implied
+        configurations to be built by default. It is also possible to prevent
+        any default builds from occurring on this target by using
+        <suppress>true . This suppresses any local
+        targets, either implicit or explicit, from building. But, this does
+        not prevent implied targets as required by a dependency by another
+        target to this one from being built. This is useful, for example, for
+        defining a set of libraries generically and having them built only
+        when another target like an exe is built. Such use might look like: 
+
+        
        
+
        +lib basic : basic.cpp : : <suppress>true ;
        
+
        
+exe test : test.cpp <lib>basic ;
        
 
        
         
        
-        With that the basic library will only be built when the test 
-        executable is built, and only the variations required by the executable 
-        will be built.
        
-    
        • 
-
      
+        With that the basic library will only be built when the
+        test executable is built, and only the variations required
+        by the executable will be built.
      
+      
      • 
+    
    
 
     
    NOTE: for simple features in both requirements and default-BUILD, more-specific qualification
-    overrides less-specific.
+    overrides less-specific.
    
 
     
    Describing Template Targets
    
 
-    
    Template targets provide a way to handle commonalities between projects targets.
-    They have the same form as main targets but do not
-    initiate build requests. A target that lists a template as a dependency inherits
-    all the settings from the template, i.e. the templates sources, requirements and
-    default build settings will be added to the targets settings. Paths mentioned in a
-    template definition are always relative to the subdirectory of the Jamfile
-    containing the templates definition, regardless of the subdirectory of the dependent
-    main target. Typically a project will have at least one template target that handles
-    defines, include paths and additional compiler flags common to all targets in the project.
+    
    Template targets provide a way to handle commonalities between
+    projects targets. They have the same form as main
+    targets but do not initiate build requests. A target that lists a
+    template as a dependency inherits all the settings from the template,
+    i.e. the templates sources, requirements and default build settings will
+    be added to the targets settings. Paths mentioned in a template
+    definition are always relative to the subdirectory of the Jamfile
+    containing the templates definition, regardless of the subdirectory of
+    the dependent main target. Typically a project will have at least one
+    template target that handles defines, include paths and additional
+    compiler flags common to all targets in the project.
    
 
     
    Describing Stage Targets
    
 
-    
    Stage targets are a special kind of target that don't build a single file but 
-    to a collection of files. The goal is to create a directory which is composed 
-    of the various files that other targets generate, or individual files. When 
-    built a stage target creates a directory with the same name as the target, 
-    and copies the dependent files to it. The form of the target is the same as 
-    that of main targets with some differences...
+    
    Stage targets are a special kind of target that don't build a single
+    file but to a collection of files. The goal is to create a directory
+    which is composed of the various files that other targets generate, or
+    individual files. When built a stage target creates a directory with the
+    same name as the target, and copies the dependent files to it. The form
+    of the target is the same as that of main
+    targets with some differences...
    
 
-
      
-    
    • target-type is stage. See libs/regex/build/Jamfile for an 
-        example.
      
-        
      
-    
    • Name specifies the name of the stage and is the name of the directory 
-        created. 
      
-        
      
-    
    • sources is the same as main targets and one can list both generated 
-        targets like <exe>test_exe and individual files, but not
-        template targets.
      
-        
      
-    
    • Requirements the build properties specified are used as with main 
-        targets. But one additional type of requirement is possible: <tag>... 
-        A tag specifies how to "augment" the names of the copied files. 
-        This is needed to distinguish the various files if your collecting different 
-        builds of the same targets. The syntax is: 
-        
       
-
      <tag><feature|variant>value
+    
        
+      
      • target-type is stage. See libs/regex/build/Jamfile for
+      an example.
        
+      
        
+      
        • 
+
+      
      • Name specifies the name of the stage and is the name of the
+      directory created.
        
+      
        
+      
        • 
+
+      
      • sources is the same as main targets and one can list both
+      generated targets like <exe>test_exe and individual
+      files, but not template targets.
        
+      
        
+      
        • 
+
+      
      • 
+        Requirements the build properties specified are used as with
+        main targets. But one additional type of requirement is possible:
+        <tag>... A tag specifies how to "augment" the names of
+        the copied files. This is needed to distinguish the various files if
+        your collecting different builds of the same targets. The syntax is: 
+
+        
        
+
        +<tag><feature|variant>value
 
        
         
        
         
        
-        If the feature or variant is present for 
-        the a target the file for that target is renamed to include the given 
-        value between the basename and the suffix. Two special 
-        tags, <tag><prefix> and <tag><postfix>, 
-        let one prepend and append a value to the "augmentation" respectively.
        
+         If the feature or variant is present
+        for the a target the file for that target is renamed to include the
+        given value between the basename and the suffix. Two
+        special tags, <tag><prefix> and
+        <tag><postfix>, let one prepend and append a
+        value to the "augmentation" respectively.
        
         
        
-    
      •  default-BUILD acts in the same manner as a main target.
        
-    
        • 
-
      
+      
      • 
+
+      
    • default-BUILD acts in the same manner as a main target.
      
+      
      • 
+    
    
 
     
    Example
    
 
-    
    This artificially complex example shows how two executables called "foo"
-    and "fop" might be described in a Jamfile. All common settings are factored out
-    in the templates "base" and "executable". Foo is composed of the sources
-    ./foo.cpp and ./src/bar.cpp (specified relative to the
-    directory in which the Jamfile resides). Fop only has one sourcefile ./fop.cpp.
-    Both executables link against the built target which results from building the target 
-    baz as described in ../bazlib/Jamfile.
+    
    This artificially complex example shows how two executables called
+    "foo" and "fop" might be described in a Jamfile. All common settings are
+    factored out in the templates "base" and "executable". Foo is composed of
+    the sources ./foo.cpp and ./src/bar.cpp (specified
+    relative to the directory in which the Jamfile resides). Fop only has one
+    sourcefile ./fop.cpp. Both executables link against the built
+    target which results from building the target baz as described
+    in ../bazlib/Jamfile.
    
 
     
    
-
    template base : 
+
    +template base : 
     ## Requirements ##
     : <include>../bazlib/include 
       <define>BUILDING_FOO=1
@@ -928,65 +1076,73 @@ exe fop : <template>executable fop.cpp ;
 
    
     
    
 
-    
    The requirements section:
+    
    The requirements section:
    
 
     
      
-      
    • Adds ../bazlib/include to the #include path
+      
    • Adds ../bazlib/include to the #include path
      • 
 
-      
    • Sets the preprocessor symbol BUILDING_FOO to 1
+      
    • Sets the preprocessor symbol BUILDING_FOO to
+      1
      • 
 
       
    • In the release builds, #defines
-      FOO_RELEASE.
+      FOO_RELEASE.
      • 
 
-      
    • When built with MSVC, #defines FOO_MSVC.
+      
    • When built with MSVC, #defines FOO_MSVC.
      • 
 
       
    • In release variants built with MSVC, #defines
-      FOO_MSVC_RELEASE.
+      FOO_MSVC_RELEASE.
      • 
 
-      
    • Most builds under GCC have optimization turned off, but...
+      
    • Most builds under GCC have optimization turned off, but...
      • 
 
-      
    • ...GCC release builds require optimization for space.
+      
    • ...GCC release builds require optimization for space.
      • 
 
-      
    • Requires multithread support on compilers where it's relevant.
+      
    • Requires multithread support on compilers where it's relevant.
      • 
 
-      
    • Adds /usr/local/foolib/include to the #include <*> path
+      
    • Adds /usr/local/foolib/include to the #include
+      <*> path
      • 
     
    
 
-    
    The default-BUILD section:
+    
    The default-BUILD section:
    
 
     
      
-      
    • specifies that debug and release base variants are
-      built by default.
+      
    • specifies that debug and release base variants
+      are built by default.
      • 
 
-      
    • on compilers where the feature is relevant, requests both statically-
-      and dynamically-linked subvariants of the debug variant.
+      
    • on compilers where the feature is relevant, requests both
+      statically- and dynamically-linked subvariants of the debug
+      variant.
      • 
     
    
 
     
    Feature Descriptions
    
 
-    
     Features are described by stating the feature type (simple features are
-    specified with "feature"), followed by the feature
-    name. An optional second argument can be used to list the permissible values
-    of the feature. Examples can be found in features.jam.
-    
+    
    Features are described by stating the feature type (simple features
+    are specified with "feature"), followed by the feature name. An
+    optional second argument can be used to list the permissible values of
+    the feature. Examples can be found in features.jam.
    
+
     
    Variant Descriptions
    
 
-    
    Variants are described with the following syntax:
+    
    Variants are described with the following syntax:
    
 
     
    
-
    variant name : [<toolset-name>]<feature>value... ;
+
    +variant name : [<toolset-name>]<feature>value... ;
 
    
     
    
     The variant rule specifies the list of properties comprising a
-    variant. Properties may be optionally qualified with a toolset name, which
-    specifies that the property applies only to that toolset. One or
-    more parent variants may be specified to inherit the properties  from those
-    parent(s). For inherited properties precedence is given on a left to right
-    order, making the immediate properties override those in the parent(s). This
-    can be used to great effect for describing global properties that are shared
-    amongst various variants, and therefore targets. For example:
+    variant. Properties may be optionally qualified with a toolset name,
+    which specifies that the property applies only to that toolset. One or
+    more parent variants may be specified to inherit the properties
+     from those parent(s). For inherited properties precedence is given
+    on a left to right order, making the immediate properties override those
+    in the parent(s). This can be used to great effect for describing global
+    properties that are shared amongst various variants, and therefore
+    targets. For example: 
+
     
    
-    
    variant my-globals : <rtti>off ;
+
    +variant my-globals : <rtti>off ;
 
 variant my-debug : my-globals debug ;
 
@@ -998,11 +1154,11 @@ variant my-release : my-globals release ;
     
    Toolset Description Files
    
 
     
    Toolset descriptions are located in the project's root directory, or a
-    directory specified by BOOST_BUILD_INSTALLATION, which may be set
-    in a Jamfile or the project's BOOST_BUILD_INSTALLATION, which may be
+    set in a Jamfile or the project's Jamrules file. Each file is called
     toolset-name-tools.jam, where toolset-name is the
-    name of the toolset. The toolset description file has two main jobs:
+    name of the toolset. The toolset description file has two main jobs:
    
 
     
      
       
    1. 
@@ -1010,20 +1166,23 @@ variant my-release : my-globals release ;
 
         
        
           
      • Link-action - links an executable from objects and
-          libraries
+          libraries
        • 
 
           
      • Archive-action - links a static library from object
-          files
+          files
        • 
 
-          
      • C++-action - compiles a 'C++' file into an object file
+          
      • C++-action - compiles a 'C++' file into an object
+          file
        • 
 
-          
      • Cc-action - compiles a 'C' file into an object file
+          
      • Cc-action - compiles a 'C' file into an object
+          file
        • 
         
      
         These rules should simply invoke the action part of a rule whose name
         is uniquely defined for the toolset. For example, 
 
         
      
-
      rule C++-action
+
      +rule C++-action
 {
     msvc-C++-action $(<) : $(>) ;
 }
@@ -1035,162 +1194,152 @@ actions msvc-C++-action
 
 
      
         
      
-        Note that Link-action may require special care: on platforms 
-        where the global variable gEXPORT_SUFFIX(DLL) is defined (e.g. 
-        Windows), the first argument may have two elements when linking a shared 
-        library. The first is the shared library target, and the second is the 
-        import library target, with suffix given by $(gEXPORT_SUFFIX(DLL)). 
-        It will always have a third argument which is either ``EXE'' 
-        or ``DLL''. This can be used to dispatch to different actions 
-        for linking DLLs and EXEs if necessary, but usually it will be easier 
-        to take advantage of the special <target-type> feature, 
-        which will have the same value using the flags rule described 
-        below. 
-
-        
      
+        Note that Link-action may require special care: on platforms
+        where the global variable gEXPORT_SUFFIX(DLL) is defined
+        (e.g. Windows), the first argument may have two elements when linking
+        a shared library. The first is the shared library target, and the
+        second is the import library target, with suffix given by
+        $(gEXPORT_SUFFIX(DLL)). It will always have a third argument
+        which is either ``EXE'' or ``DLL''. This can be
+        used to dispatch to different actions for linking DLLs and EXEs if
+        necessary, but usually it will be easier to take advantage of the
+        special <target-type> feature, which will have the
+        same value using the flags rule described below.
+      
      2. 
 
       
    2. 
-        Translate build settings given in the global gBUILD_PROPERTIES
-        variable into something that can be used by the toolset. The build
-        system provides the flags rule to help translate build
-        properties into elements of global variables which are later attached
-        to targets so that they can affect the build actions. The
-        flags rule is used as follows: 
+        Translate build settings given in the global
+        gBUILD_PROPERTIES variable into something that can be used
+        by the toolset. The build system provides the flags rule to
+        help translate build properties into elements of global variables
+        which are later attached to targets so that they can affect the build
+        actions. The flags rule is used as follows: 
 
         
      
-
      flags toolset variable condition [: value...]
+
      +flags toolset variable condition [: value...]
 
      
         
      
         The parameters are: 
 
         
        
-          
      • toolset - the name of the toolset
+          
      • toolset - the name of the toolset
        • 
 
-          
      • variable - the name of a global variable which can be used
-          to carry information to a command-line
+          
      • variable - the name of a global variable which can be
+          used to carry information to a command-line
        • 
 
           
      • 
-            condition - one one or more elements in the following forms:
-            
+            condition - one one or more elements in the following
+            forms: 
 
             
          
               
        1. a property-set of the form:
               <feature>value[/<feature>
-              value...]
+              value...]
          2. 
 
-              
        2. <feature>
+              
        3. <feature>
          4. 
             
        
+          
        • 
 
-          
      • values - anything
+          
      • values - anything
        • 
         
      
 
-        
      Semantics only affect targets built with the specified toolset, and
-        depend on the target's build configuration:
+        
      Semantics only affect targets built with the specified toolset,
+        and depend on the target's build configuration:
      
 
         
        
           
      1. if any specified property-set is a subset of the target's build
           properties, the values specified in $(3) will be
-          appended once to variable.
+          appended once to variable.
        2. 
 
-            
      2. The value of each specified feature that participates in the target's 
-                build properties is appended to variable. In either case, 
-                the variable will be set "on" the target so it may be used in 
-                the build actions. 
+          
      3. The value of each specified feature that participates in the
+          target's build properties is appended to variable. In either
+          case, the variable will be set "on" the target so it may be used in
+          the build actions.
        4. 
         
      
+      
      3. 
     
    
 
     
    Example
    
 
     
    The description of the flags rule above is actually more
     complicated than it sounds. For example, the following line might be used
-    to specify how optimization can be turned off for MSVC:
+    to specify how optimization can be turned off for MSVC:
    
 
     
    
-
    flags msvc CFLAGS <optimization>off : /Od ;
+
    +flags msvc CFLAGS <optimization>off : /Od ;
 
    
     
    
-    It says that the string /Od should be added to the global CFLAGS 
-variable whenever a build configuration includes the property <optimization>off. 
+    It says that the string /Od should be added to the global
+    CFLAGS variable whenever a build configuration includes the
+    property <optimization>off. 
 
-
    Similarly, in the following example,
+    
    Similarly, in the following example,
    
 
     
    
-
    flags msvc CFLAGS <runtime-build>release/<runtime-link>dynamic : /MD ;
+
    +flags msvc CFLAGS <runtime-build>release/<runtime-link>dynamic : /MD ;
 
    
     
    
     we add /MD to the CFLAGS variable when both of the specified
     conditions are satisfied. We could grab all of the values of the free
-    feature <include> in the HDRS variable as follows: 
+    feature <include> in the HDRS variable as
+    follows: 
 
     
    
-
    flags msvc HDRS <include> ;
+
    +flags msvc HDRS <include> ;
 
    
     
    
 
     
    The use of these variables should be apparent from the declaration of
-    actions msvc-C++-action in the previous section.
+    actions msvc-C++-action in the previous section.
    
 
     
    Internals
    
 
     
    Jam Fundamentals
    
 
-    
    This section is derived from the official Jam documentation and from my
-    experience using it and reading the Jambase rules. I repeat the information
-    here mostly because it is essential to understanding and using Jam, but is
-    not consolidated in a single place. Some of it is missing from the official
-    documentation altogether. I hope it will be useful to anyone wishing to
-    become familiar with Jam and the Boost build system.
-
-    
    
+    
    This section is derived from the official Jam documentation and from
+    my experience using it and reading the Jambase rules. I repeat the
+    information here mostly because it is essential to understanding and
+    using Jam, but is not consolidated in a single place. Some of it is
+    missing from the official documentation altogether. I hope it will be
+    useful to anyone wishing to become familiar with Jam and the Boost build
+    system.
    
 
     
      
+      
    • Jam ``rules'' are actually simple procedural entities. Think
+      of them as functions. Arguments are separated by colons.
      • 
 
-      
    • 
-        Jam ``rules'' are actually simple procedural entities. Think of
-        them as functions. Arguments are separated by colons. 
+      
    • A Jam target is an abstract entity identified by an
+      arbitrary string. The build-in DEPENDS rule creates a link in
+      the dependency graph between the named targets.
      • 
 
-        
      
+      
    • Note that the documentation for the built-in INCLUDES rule
+      is incorrect: INCLUDES targets1 : targets2
+      causes everything that depends on a member of targets1 to depend
+      on all members of targets2. It does this in an odd way, by
+      tacking targets2 onto a special tail section in the dependency
+      list of everything in targets1. It seems to be OK to create
+      circular dependencies this way; in fact, it appears to be the ``right
+      thing to do'' when a single build action produces both targets1
+      and targets2.
      • 
 
-      
    • 
-        A Jam target is an abstract entity identified by an arbitrary
-        string. The build-in DEPENDS rule creates a link in the
-        dependency graph between the named targets. 
+      
    • When a rule is invoked, if there are actions
+      declared with the same name as the rule, the actions are added
+      to the updating actions for the target identified by the rule's first
+      argument. It is actually possible to invoke an undeclared rule if
+      corresponding actions are declared: the rule is treated as empty.
      • 
 
-        
      
-
-      
    • 
-        Note that the documentation for the built-in INCLUDES rule is
-        incorrect: INCLUDES targets1 : targets2 causes
-        everything that depends on a member of targets1 to depend on all
-        members of targets2. It does this in an odd way, by tacking
-        targets2 onto a special tail section in the dependency list of
-        everything in targets1. It seems to be OK to create circular
-        dependencies this way; in fact, it appears to be the ``right thing to
-        do'' when a single build action produces both targets1 and
-        targets2.
-
-        
      
-
-      
    • 
-        When a rule is invoked, if there are actions declared
-        with the same name as the rule, the actions are added to the
-        updating actions for the target identified by the rule's first
-        argument. It is actually possible to invoke an undeclared rule if
-        corresponding actions are declared: the rule is treated as empty. 
-
-        
      
-
-      
    • 
-        Targets (other than NOTFILE targets) are
-        associated with paths in the file system through a process called binding.
-        Binding is a process of searching for a file with the same name as the
-        target (sans grist), based on the settings of the
-        target-specific SEARCH and
-        LOCATE variables. 
-
-        
      
+      
    • Targets (other than NOTFILE targets)
+      are associated with paths in the file system through a process called
+      binding.
+      Binding is a process of searching for a file with the same name as the
+      target (sans grist), based on the settings of the
+      target-specific SEARCH and
+      LOCATE variables.
      • 
 
       
    • 
         In addition to local and global
@@ -1198,52 +1347,43 @@ variable whenever a build configuration includes the property <optimizati
         target. Target-specific variable values can usually not be read, and
         take effect only in the following contexts: 
 
-        
      
-
         
        
-          
      • In updating actions, variable values are first looked up
-          on the target named by the first argument (the target
-          being updated). Because Jam builds its entire dependency tree before
-          executing actions, Jam rules make target-specific variable
-          settings as a way of supplying parameters to the corresponding
-          actions.
+          
      • In updating actions, variable values are first looked
+          up on the target named by the first argument (the
+          target being updated). Because Jam builds its entire dependency
+          tree before executing actions, Jam rules make
+          target-specific variable settings as a way of supplying parameters
+          to the corresponding actions.
        • 
 
           
      • Binding is controlled entirely by the target-specific
           setting of the SEARCH and LOCATE variables, as
           described here.
+          "http://public.perforce.com/public/jam/src/Jam.html#search">here.
        • 
 
           
      • In the special rule used for header
           file scanning, variable values are first looked up
-          on the target named by the rule's first argument (the
-          source file being scanned).
+          on the target named by the rule's first argument
+          (the source file being scanned).
        • 
         
      
+      
      • 
 
-        
      
+      
    • The ``bound value'' of a variable is the path associated
+      with the target named by the variable. In build actions, the
+      first two arguments are automatically replaced with their bound values.
+      Target-specific variables can be selectively replaced by their bound
+      values using the bind
+      action modifier.
      • 
 
-      
    • 
-        The ``bound value'' of a variable is the path associated with
-        the target named by the variable. In build actions, the first
-        two arguments are automatically replaced with their bound values.
-        Target-specific variables can be selectively replaced by their bound
-        values using the bind
-        action modifier. 
-
-        
      
-
-      
    • 
-        Note that the term ``binding'' as used in the Jam documentation
-        indicates a phase of processing that includes three sub-phases:
-        binding (yes!), update determination, and header file scanning.
-        The repetition of the term ``binding'' can lead to some confusion. In
-        particular, the Modifying
-        Binding section in the Jam documentation should probably be titled
-        ``Modifying Update Determination''. 
-
-        
      
+      
    • Note that the term ``binding'' as used in the Jam documentation
+      indicates a phase of processing that includes three sub-phases:
+      binding (yes!), update determination, and header file scanning.
+      The repetition of the term ``binding'' can lead to some confusion. In
+      particular, the Modifying
+      Binding section in the Jam documentation should probably be titled
+      ``Modifying Update Determination''.
      • 
 
       
    • 
         
      ``Grist'' is just a string prefix of the form
@@ -1252,150 +1392,166 @@ variable whenever a build configuration includes the property <optimizati
         file name ``test.exe'' may be used by targets in separate
         subprojects, or for the debug and release variants of the ``same''
         abstract target. Each distinct target bound to a file called
-        ``test.exe'' has its own unique grist prefix. The Boost build
-        system also takes full advantage of Jam's ability to divide strings on
-        grist boundaries, sometimes concatenating multiple gristed elements at
-        the beginning of a string. Grist is used instead of identifying targets
-        with absolute paths for two reasons:
+        ``test.exe'' has its own unique grist prefix. The Boost
+        build system also takes full advantage of Jam's ability to divide
+        strings on grist boundaries, sometimes concatenating multiple gristed
+        elements at the beginning of a string. Grist is used instead of
+        identifying targets with absolute paths for two reasons:
      
 
         
        
-          
      1. The location of targets cannot always be derived solely from what
-          the user puts in a Jamfile, but sometimes depends also on the binding process. Some mechanism to distinctly
-          identify targets with the same name is still needed.
+          
      2. The location of targets cannot always be derived solely from
+          what the user puts in a Jamfile, but sometimes depends also on the
+          binding process. Some mechanism to
+          distinctly identify targets with the same name is still
+          needed.
        3. 
 
           
      3. Grist allows us to use a uniform abstract identifier for each
           built target, regardless of target file location (as allowed by
-          setting ALL_LOCATE_TARGET.
+          setting ALL_LOCATE_TARGET.
        4. 
         
      
-        When grist is extracted from a name with $(var:G), 
-        the result includes the leading and trailing angle brackets. When grist 
-        is added to a name with $(var:G=expr), 
-        existing grist is first stripped. Then, if expr is non-empty, leading 
-        <s and trailing >s are added if necessary to form 
-        an expression of the form <expr2>; <expr2> 
-        is then prepended. 
+        When grist is extracted from a name with
+        $(var:G), the result includes the leading
+        and trailing angle brackets. When grist is added to a name with
+        $(var:G=expr), existing
+        grist is first stripped. Then, if expr is non-empty, leading
+        <s and trailing >s are added if necessary to
+        form an expression of the form
+        <expr2>;
+        <expr2> is then prepended.
+      
      • 
 
-        
      
-
-      
-    
    •  When Jam is invoked it imports all environment 
-        variable settings into corresponding Jam variables, followed by all command-line 
-        (-s...) variable settings. Variables whose name ends in PATH, 
-        Path, or path are split into string lists on OS-specific 
-        path-list separator boundaries (e.g. ":" for UNIX and 
-        ";" for Windows). All other variables are split on 
-        space (" ") boundaries. Boost Jam modifies that 
-        behavior by allowing variables to be quoted. 
-
-        
      
+      
    • When Jam is invoked it imports all
+      environment variable settings into corresponding Jam variables,
+      followed by all command-line (-s...) variable settings.
+      Variables whose name ends in PATH, Path, or
+      path are split into string lists on OS-specific path-list
+      separator boundaries (e.g. ":" for UNIX and ";" for
+      Windows). All other variables are split on space (" ")
+      boundaries. Boost Jam modifies that behavior by allowing variables to
+      be quoted.
      • 
 
       
    • 
         A variable whose value is an empty list or which consists
         entirely of empty strings has a negative logical value. Thus, for
         example, code like the following allows a sensible non-empty default
-        which can easily be overridden by the user:
-
      MESSAGE ?= starting jam... ;
+        which can easily be overridden by the user: 
+
+        
      
+
      +MESSAGE ?= starting jam... ;
 if $(MESSAGE) { ECHO The message is: $(MESSAGE) ; }
-
      
+
      
+        
      
         If the user wants a specific message, he invokes jam with
-        "-sMESSAGE=message text". If he
-        wants no message, he invokes jam with -sMESSAGE= and nothing at
+        "-sMESSAGE=message text". If he wants
+        no message, he invokes jam with -sMESSAGE= and nothing at
         all is printed.
-
-        
      
-
+      
      • 
     
    
 
     
    Please also read The Jam language
     reference for the additional details, and the Jam release notes
-    for a brief description of recent, but fundamental changes to the Jam
-    language without which you will probably not understand any of the
-    build system code. In particular, note that the return statement
-    does not affect control flow.
+    "http://public.perforce.com/public/jam/src/RELNOTES">Jam release
+    notes for a brief description of recent, but fundamental changes
+    to the Jam language without which you will probably not understand
+    any of the build system code. In particular, note that the
+    return statement does not affect control flow.
    
 
     
    Core Jam Extensions
    
 
-    
    A number of enhancements have been made to the core language of Classic
-    Jam. These changes were aimed primarily at making it easier to manage the
-    complexity of a large system such as Boost.Build.
+    
    A number of enhancements have been made to the core language of
+    Classic Jam. These changes were aimed primarily at making it easier to
+    manage the complexity of a large system such as Boost.Build.
    
 
     
    
+      
    Command-line and Environment
+      Variable Quoting
    
 
-      
    Command-line and Environment Variable Quoting
    
+      
    Classic Jam had an odd behavior
+      with respect to command-line variable ( -s...) and environment
+      variable settings which made it impossible to define an arbitrary
+      variable with spaces in the value. Boost Jam remedies that by treating
+      all such settings as a single string if they are surrounded by
+      double-quotes. Uses of this feature can look interesting, since shells
+      require quotes to keep characters separated by whitespace from being
+      treated as separate arguments:
    
 
-      
    Classic Jam had an odd behavior with
-      respect to command-line variable ( -s...) and environment
-      variable settings which made it impossible to define an arbitrary variable
-      with spaces in the value. Boost Jam remedies that by treating all such
-      settings as a single string if they are surrounded by double-quotes. Uses
-      of this feature can look interesting, since shells require quotes to keep
-      characters separated by whitespace from being treated as separate
-      arguments:
-
    jam -sMSVCNT="\"\"C:\Program Files\Microsoft Visual C++\VC98\"\"" ...
-
    
+      
    
+
    +jam -sMSVCNT="\"\"C:\Program Files\Microsoft Visual C++\VC98\"\"" ...
+
    
+      
    
+      The outer quote is for the shell. The middle quote is for Jam, to tell
+      it to take everything within those quotes literally, and the inner
+      quotes are for the shell again when paths are passed as arguments to
+      build actions. Under NT, it looks a lot more sane to use environment
+      variables before invoking jam when you have to do this sort of quoting:
+      
 
-      The outer quote is for the shell. The middle quote is for Jam,
-      to tell it to take everything within those quotes literally, and
-      the inner quotes are for the shell again when paths are passed
-      as arguments to build actions. Under NT, it looks a lot more
-      sane to use environment variables before invoking jam when you
-      have to do this sort of quoting:
-
-
    set MSVCNT=""C:\Program Files\Microsoft Visual C++\VC98\""
-
    
+      
    
+
    +set MSVCNT=""C:\Program Files\Microsoft Visual C++\VC98\""
+
    
+      
    
 
       
    Startup Behavior
    
 
-      
    The Boost.Build v2 initialization behavior has been
-      implemented. This behavior only applies when the executable
-      being invoked is called "bjam" or, for
-      backward-compatibility, when the BOOST_ROOT
-      variable is set.
+      
    The Boost.Build v2 initialization behavior has been implemented.
+      This behavior only applies when the executable being invoked is called
+      "bjam" or, for backward-compatibility, when the
+      BOOST_ROOT variable is set.
    
 
-   
      
-   
    1.  We attempt to load "boost-build.jam" by searching from the
-        current invocation directory up to the root of the
-        file-system. This file is expected to invoke the
-        boost-build rule to indicate where the Boost.Build
-        system files are, and to load them.
-   
    2.  If boost-build.jam is not found we error and exit, giving
-        brief instructions on possible errors. 
-
      
-As a backward-compatibility measure for older versions of Boost.Build,
-when the BOOST_ROOT variable is set, we first search for
-boost-build.jam in $(BOOST_ROOT)/tools/build
-and $(BOOST_BUILD_PATH). If found, it is loaded and
-initialization is complete.
-
      
-   
    3.  The boost-build rule adds its (optional) argument
-        to the front of BOOST_BUILD_PATH, and attempts to
-        load bootstrap.jam from those directories. If a
-        relative path is specified as an argument, it is treated as
-        though it was relative to the boost-build.jam
-        file.
-   
    4.  If the bootstrap.jam file was not found, we print a likely
-           error message and exit.
-
    
+      
      
+        
    1. We attempt to load "boost-build.jam" by searching from the
+        current invocation directory up to the root of the file-system. This
+        file is expected to invoke the boost-build rule to indicate
+        where the Boost.Build system files are, and to load them.
      2. 
+
+        
    2. 
+          If boost-build.jam is not found we error and exit, giving brief
+          instructions on possible errors. 
+
+          
      
+            As a backward-compatibility measure for older versions of
+            Boost.Build, when the BOOST_ROOT variable is set, we
+            first search for boost-build.jam in
+            $(BOOST_ROOT)/tools/build and
+            $(BOOST_BUILD_PATH). If found, it is loaded and
+            initialization is complete.
+          
      
+        
      3. 
+
+        
    3. The boost-build rule adds its (optional) argument to
+        the front of BOOST_BUILD_PATH, and attempts to load
+        bootstrap.jam from those directories. If a relative path
+        is specified as an argument, it is treated as though it was relative
+        to the boost-build.jam file.
      4. 
+
+        
    4. If the bootstrap.jam file was not found, we print a likely error
+        message and exit.
      5. 
+      
    
 
       
    Rule Indirection
    
 
-      
    Boost Jam allows you to call a rule whose name is held in a variable or
-      computed as the result of an expression:
-
    x = foo ;
+      
    Boost Jam allows you to call a rule whose name is held in a variable
+      or computed as the result of an expression:
    
+
+      
    
+
    +x = foo ;
 rule foobar { ECHO foobar ; }   # a trivial rule
 $(x)bar ;                       # invokes foobar
 
-
    
-      
-      Furthermore, if the first expression expands to more than one
-      list item, everything after the first item becomes part of the
-      first argument. This allows a crude form of argument binding:
+
    
+      
    
+      Furthermore, if the first expression expands to more than one list
+      item, everything after the first item becomes part of the first
+      argument. This allows a crude form of argument binding: 
 
-
    # return the elements of sequence for which predicate returns non-nil
+      
    
+
    +# return the elements of sequence for which predicate returns non-nil
 rule filter ( sequence * : predicate + )
 {
     local result ;
@@ -1415,16 +1571,18 @@ rule equal ( x y )
 # bind 3 to the first argument of equal
 ECHO [ filter 1 2 3 4 5 4 3 : equal 3 ] ; # prints "3 3"
 
-
    
+
    
+      
    
 
-
    Argument lists
    
+      
    Argument lists
    
 
       
    You can now describe the arguments accepted by a rule, and refer to
       them by name within the rule. For example, the following prints ``I'm
-      sorry, Dave'' to the console:
+      sorry, Dave'' to the console:
    
 
       
    
-
    rule report ( pronoun index ? : state : names + )
+
    +rule report ( pronoun index ? : state : names + )
 {
     local he.suffix she.suffix it.suffix = s ;
     local I.suffix = m ;
@@ -1441,35 +1599,40 @@ report I 2 : sorry : Joe Dave Pete ;
 
       
-          
 
-          
+        
-          
 
-          
+        
-          
 
-          
+        
-          
 
-          
+        
    
         
    Symbol
+          SymbolSemantics of preceding symbol
+          Semantics of preceding symbol
    
 
         
    ? 
+          ?optional
+          optional
    
 
         
    * 
+          *Bind to zero or more unbound elements of the actual
-          argument. When ``*'' appears where an argument name
-          is expected, any number of additional arguments are
-          accepted. This feature can be used to implement
-          "varargs" rules.
+          Bind to zero or more unbound elements of the actual argument.
+          When ``*'' appears where an argument name is expected, any
+          number of additional arguments are accepted. This feature can be
+          used to implement "varargs" rules.
    
 
         
    + 
+          +Bind to one or more unbound elements of the actual argument.
+          Bind to one or more unbound elements of the actual
+          argument.
    
       
    
 
-      
    The actual and formal arguments are checked for inconsistencies, which
-      cause Jam to exit with an error code:
+      
    The actual and formal arguments are checked for inconsistencies,
+      which cause Jam to exit with an error code:
    
 
       
    
-
    ### argument error
+
    +### argument error
 # rule report ( pronoun index ?  : state  : names + )
 # called with: ( I 2 foo  : sorry  : Joe Dave Pete )
 # extra argument foo
@@ -1480,36 +1643,38 @@ report I 2 : sorry : Joe Dave Pete ;
 # missing argument names
 
    
       
    
-      
    If you omit the list of formal arguments, all checking is
-      bypassed as in ``classic'' Jam. Argument lists drastically improve the
+
+      
    If you omit the list of formal arguments, all checking is bypassed
+      as in ``classic'' Jam. Argument lists drastically improve the
       reliability and readability of your rules, however, and are strongly
-      recommended for any new Jam code you write.
+      recommended for any new Jam code you write.
    
 
       
    Module Support
    
 
       
    Boost Jam introduces support for modules, which provide some
       rudimentary namespace protection for rules and variables. A new
       keyword, ``module'' was also introduced. The features
-      described in this section are primitives, meaning that
-      they are meant to provide the operations needed to write Jam
-      rules which provide a more elegant module interface.
-
-      
    
+      described in this section are primitives, meaning that they are
+      meant to provide the operations needed to write Jam rules which provide
+      a more elegant module interface.
    
 
       
    
-        
    Declaration
    
-         module 
-        expression {  ... }  
+        
    Declaration
    
+        module 
+        expression {  ... } 
+        
 
-        
    Code within the {  ... } executes within the
-        module named by evaluating expression. Rule definitions can be
-        found in the module's own namespace, and in the namespace of the global
-        module as module-name.rule-name, so within a
-        module, other rules in that module may always be invoked without
-        qualification:
+        
    Code within the {  ... } executes
+        within the module named by evaluating expression. Rule
+        definitions can be found in the module's own namespace, and in the
+        namespace of the global module as
+        module-name.rule-name, so within a module,
+        other rules in that module may always be invoked without
+        qualification:
    
 
         
    
-
    module my_module
+
    +module my_module
 {
     rule salute ( x ) { ECHO $(x), world ; }
     rule greet ( ) { salute hello ; }
@@ -1518,28 +1683,29 @@ report I 2 : sorry : Joe Dave Pete ;
 my_module.salute goodbye ;
 
    
         
    
-        When an invoked rule is not found in the current module's namespace, it
-        is looked up in the namespace of the global module, so qualified calls
-        work across modules: 
+        When an invoked rule is not found in the current module's namespace,
+        it is looked up in the namespace of the global module, so qualified
+        calls work across modules: 
 
         
    
-
    module your_module
+
    +module your_module
 {
     rule bedtime ( ) { my_module.salute goodnight ; }
 }
 
    
         
    
 
-        
    
-
         
    Variable Scope
    
 
-        
    Each module has its own set of dynamically nested variable
-        scopes. When execution passes from module A to module B, all
-        the variable bindings from A become unavailable, and are
-        replaced by the bindings that belong to B. This applies
-        equally to local and global variables:
-
    
+        
    Each module has its own set of dynamically nested variable scopes.
+        When execution passes from module A to module B, all the variable
+        bindings from A become unavailable, and are replaced by the bindings
+        that belong to B. This applies equally to local and global
+        variables:
    
+
+        
    
+
     module A
 {
     x = 1 ;
@@ -1550,7 +1716,7 @@ module A
     }
     rule g ( )
     {
-        ECHO $(y) ;     # prints "999"
+        ECHO $(y) ;     # prints "999"
     }
 }
 
@@ -1559,18 +1725,18 @@ module B
     y = 2 ;
     rule f ( )
     {
-        ECHO $(y) ; # always prints "2"
+        ECHO $(y) ; # always prints "2"
         A.g ;
     }
 }
-
    
 
    
-
-        The only way to access another module's variables is by
-        entering that module:
+        
    
+        The only way to access another module's variables is by entering that
+        module: 
 
         
    
-
    rule peek ( module-name ? : variables + )
+
    +rule peek ( module-name ? : variables + )
 {
     module $(module-name)
     {
@@ -1579,55 +1745,59 @@ module B
 }
 
    
         
    
-
-        Note that because existing variable bindings change whenever a
-        new module scope is entered, argument bindings become
-        unavailable. That explains the use of
-        "$(>)" in the peek rule
-        above.
+        Note that because existing variable bindings change whenever a new
+        module scope is entered, argument bindings become unavailable. That
+        explains the use of "$(>)" in the peek
+        rule above. 
 
         
    Local Rules
    
 
         
    
-              local rule rulename...
+          local rule rulename...
         
    
 
-        
    The rule is declared locally to the current module. It is
-        not entered in the global module with qualification, and its
-        name will not appear in the result of
+        
    The rule is declared locally to the current module. It is not
+        entered in the global module with qualification, and its name will
+        not appear in the result of
    
+
         
    
-        [ RULENAMES module-name ].
+          [ RULENAMES module-name ].
         
    
-                
+
         
    The RULENAMES Rule
    
-        
+
         
    
-
    rule RULENAMES ( module ? )
+
    +rule RULENAMES ( module ? )
 
    
         
    
-        Returns a list of the names of all non-local rules in the given module. 
-        If module is omitted, the names of all non-local rules in the 
-        global module are returned. 
+        Returns a list of the names of all non-local rules in the given
+        module. If module is omitted, the names of all non-local
+        rules in the global module are returned. 
+
         
    The IMPORT Rule
    
-        
-        IMPORT allows rule name aliasing across modules:
+        IMPORT allows rule name aliasing across modules: 
 
         
    
-
    rule IMPORT (  source_module ? : source_rules *
+
    +rule IMPORT (  source_module ? : source_rules *
                 : target_module ? : target_rules * )
 
    
         
    
- The IMPORT rule copies rules from the source_module into the
- target_module as local rules. If either source_module or
- target_module is not supplied, it refers to the global
- module. source_rules specifies which rules from the source_module to
- import; TARGET_RULES specifies the names to give those rules in
- target_module. If source_rules contains a name which doesn't
- correspond to a rule in source_module, or if it contains a different
- number of items than target_rules, an error is issued. For example,
+        The IMPORT rule copies rules from the source_module
+        into the target_module as local rules. If either
+        source_module or target_module is not supplied, it
+        refers to the global module. source_rules specifies which
+        rules from the source_module to import;
+        TARGET_RULES specifies the names to give those rules in
+        target_module. If source_rules contains a name
+        which doesn't correspond to a rule in source_module, or if
+        it contains a different number of items than target_rules,
+        an error is issued. For example, 
 
         
    
-
    # import m1.rule1 into m2 as local rule m1-rule1.
+
    +# import m1.rule1 into m2 as local rule m1-rule1.
 IMPORT m1 : rule1 : m2 : m1-rule1 ;
 
 # import all non-local rules from m1 into m2
@@ -1636,18 +1806,21 @@ IMPORT m1 : [ RULENAMES m1 ] : m2 : [ RULENAMES m1 ] ;
         
    
 
         
    The EXPORT Rule
    
-        
-        EXPORT allows rule name aliasing across modules:
+        EXPORT allows rule name aliasing across modules: 
 
         
    
-
    rule EXPORT ( module ? : rules * )
+
    +rule EXPORT ( module ? : rules * )
 
    
         
    
- The EXPORT rule marks rules from the source_module as non-local
- (and thus exportable). If an element of rules does not name a
- rule in module, an error is issued. For example,
+        The EXPORT rule marks rules from the
+        source_module as non-local (and thus exportable). If an
+        element of rules does not name a rule in module, an
+        error is issued. For example, 
+
         
    
-
    module X {
+
    +module X {
   local rule r { ECHO X.r ; }
 }
 IMPORT X : r : : r ; # error - r is local in X
@@ -1656,21 +1829,24 @@ IMPORT X : r : : r ; # OK.
 
    
         
    
 
-        
    The CALLER_MODULE Rule
    
-        
-        
    
-
    rule CALLER_MODULE ( levels ? )
-
    
-        
    
-        CALLER_MODULE returns the name of the module scope
-        enclosing the call to its caller (if levels is supplied, it is
-        interpreted as an integer number of additional levels of call stack to
-        traverse to locate the module). If the scope belongs to the global
-        module, or if no such module exists, returns the empty list. For
-        example, the following prints "{Y} {X}":
+        
    The CALLER_MODULE
+        Rule
    
 
         
    
-
    module X {
+
    +rule CALLER_MODULE ( levels ? )
+
    
+        
    
+        CALLER_MODULE returns the name of the module scope enclosing
+        the call to its caller (if levels is supplied, it is interpreted as
+        an integer number of additional levels of call stack to traverse to
+        locate the module). If the scope belongs to the global module, or if
+        no such module exists, returns the empty list. For example, the
+        following prints "{Y} {X}": 
+
+        
    
+
    +module X {
     rule get-caller { return [ CALLER_MODULE ] ; }
     rule get-caller's-caller { return [ CALLER_MODULE 1 ] ; }
 
@@ -1687,106 +1863,114 @@ ECHO {$(callers)} ;
 
 
    
         
    
-
       
    
 
       
    Local For Loop Variables
    
 
       
    Boost Jam allows you to declare a local for loop control
-      variable right in the loop:
-
    x = 1 2 3 ;
+      variable right in the loop:
    
+
+      
    
+
    +x = 1 2 3 ;
 y = 4 5 6 ;
 for local y in $(x)
 {
-    ECHO $(y) ; # prints "1", "2", or "3"
+    ECHO $(y) ; # prints "1", "2", or "3"
 }
-ECHO $(y) ;     # prints "4 5 6"
-
    
+ECHO $(y) ;     # prints "4 5 6"
+
    
+      
    
 
       
    Negative Indexing
    
-      
       Classic Jam supplies 1-based list indexing, and slicing on a closed
-      (inclusive) range:
-
    x = 1 2 3 4 5 ;
-ECHO $(x[3]) ;   # prints "3"
-ECHO $(x[2-4]) ; # prints "2 3 4"
-ECHO $(x[2-]) ;  # prints "2 3 4 5"
-
    
+      (inclusive) range: 
 
-      Boost Jam adds Python-style negative indexing to access locations relative
-      to the end of the list.
+      
    
+
    +x = 1 2 3 4 5 ;
+ECHO $(x[3]) ;   # prints "3"
+ECHO $(x[2-4]) ; # prints "2 3 4"
+ECHO $(x[2-]) ;  # prints "2 3 4 5"
+
    
+      
    
+      Boost Jam adds Python-style negative indexing to access locations
+      relative to the end of the list. 
 
-
    ECHO $(x[-1]) $(x[-3]) ; # prints "5 3"
-ECHO $(x[-3--1]) ;       # prints "3 4 5"
-ECHO $(x[-3-4]) ;        # prints "3 4"
-ECHO $(x[2--2]) ;        # prints "2 3 4"       
-
    
-
-      Consistency with the 1-based, inclusive
-      indexing of Classic Jam and the use of ``-'' as the
-      range separator make this feature a bit clumsier than it would otherwise
-      need to be, but it does work.
+      
    
+
    +ECHO $(x[-1]) $(x[-3]) ; # prints "5 3"
+ECHO $(x[-3--1]) ;       # prints "3 4 5"
+ECHO $(x[-3-4]) ;        # prints "3 4"
+ECHO $(x[2--2]) ;        # prints "2 3 4"       
+
    
+      
    
+      Consistency with the 1-based, inclusive indexing of Classic Jam and the
+      use of ``-'' as the range separator make this feature a bit
+      clumsier than it would otherwise need to be, but it does work. 
 
       
    Target Binding Detection
    
 
-      
    Whenever a target is bound to a location in the
-      filesystem, Boost Jam will look for a variable called BINDRULE (first
-      ``on'' the target being bound, then in the global module). If
-      non-empty, $(BINDRULE[1]) names a rule which is called with the
-      name of the target and the path it is being bound to. The signature of the
-      rule named by $(BINDRULE[1]) should match the following:
-
-
    rule bind-rule ( target : path )
-
    
+      
    Whenever a target is bound to a location in
+      the filesystem, Boost Jam will look for a variable called
+      BINDRULE (first ``on'' the target being bound, then
+      in the global module). If non-empty, $(BINDRULE[1]) names a
+      rule which is called with the name of the target and the path it is
+      being bound to. The signature of the rule named by
+      $(BINDRULE[1]) should match the following:
    
 
+      
    
+
    +rule bind-rule ( target : path )
+
    
+      
    
       This facility is useful for correct header file scanning, since many
-      compilers will search for #included files first in the directory
-      containing the file doing the #include
-      directive. $(BINDRULE) can be used to make a record of that
-      directory.
-      
+      compilers will search for #included files first in the
+      directory containing the file doing the #include directive.
+      $(BINDRULE) can be used to make a record of that directory. 
+
       
    Return Code Inversion
    
 
-      
    For handling targets whose build actions are expected to fail
-      (e.g. when testing that assertions or compile-time type checkin work
+      
    For handling targets whose build actions are expected to fail (e.g.
+      when testing that assertions or compile-time type checkin work
       properly), Boost Jam supplies a FAIL_EXPECTED rule in the same
-      style as NOCARE, et. al. During target updating, the return code
-      of the build actions for arguments to FAIL_EXPECTED is inverted:
-      if it fails, building of dependent targets continues as though it
-      succeeded. If it succeeds, dependent targets are skipped.
+      style as NOCARE, et. al. During target updating, the return
+      code of the build actions for arguments to FAIL_EXPECTED is
+      inverted: if it fails, building of dependent targets continues as
+      though it succeeded. If it succeeds, dependent targets are skipped.
    
 
       
    Ignoring Return Codes
    
 
-      
-    
    Perforce Jam supplied a NOCARE rule which is typically used for 
-        header files to indicate that if they are not found, the dependent targets 
-        should be built anyway. Boost Jam extends NOCARE to apply to 
-        targets with build actions: if their build actions exit with a nonzero 
-        return code, dependent targets will still be built. 
+      
    Perforce Jam supplied a NOCARE rule which is typically used
+      for header files to indicate that if they are not found, the dependent
+      targets should be built anyway. Boost Jam extends NOCARE to
+      apply to targets with build actions: if their build actions exit with a
+      nonzero return code, dependent targets will still be built.
    
 
       
    Removing Outdated Targets
    
-
    
-
    rule RMOLD ( targets * )
+
+      
    
+
    +rule RMOLD ( targets * )
 
    
-
    
+      
    
 
-      
    Perforce Jam removes any target files that may exist on disk
-      when the rule used to build those targets fails. However,
-      targets whose dependencies fail to build are not removed by
-      default. The RMOLD rule causes its arguments to be
-      removed if any of their dependencies fail to build.
+      
    Perforce Jam removes any target files that may exist on disk when
+      the rule used to build those targets fails. However, targets whose
+      dependencies fail to build are not removed by default. The
+      RMOLD rule causes its arguments to be removed if any of
+      their dependencies fail to build.
    
 
-      
-    
    The SUBST Rule
    
+      
    The SUBST Rule
    
 
-    
    Note: the SUBST rule is deprecated in favor
-    of Perforce Jam's built-in MATCH rule, which has been
-    rolled into Boost.Jam.
+      
    Note: the SUBST rule is deprecated in favor of
+      Perforce Jam's built-in MATCH rule, which has been rolled
+      into Boost.Jam.
    
 
-      
    The behavior of the SUBST rule for regular-expression matching
-      and replacement (originally added in The behavior of the SUBST rule for regular-expression
+      matching and replacement (originally added in FTJam) has been
-      modified:
+      modified:
    
 
       
      
         
    • 
@@ -1794,238 +1978,250 @@ ECHO $(x[2--2]) ;        # prints "2 3 4"
           for SUBST is: 
 
           
      
-
      SUBST ( source pattern replacements + )
+
      +SUBST ( source pattern replacements + )
 
      
           
      
-          The return value is the concatenated results of applying each element
-          of replacements in turn. For example, the following will
-          print ``[x] (y) {z}'': 
+          The return value is the concatenated results of applying each
+          element of replacements in turn. For example, the
+          following will print ``[x] (y) {z}'': 
 
           
      
-
      ECHO [ SUBST xyz (.)(.)(.) [$1] ($2) {$3} ] ;
+
      +ECHO [ SUBST xyz (.)(.)(.) [$1] ($2) {$3} ] ;
 
      
           
      
+        
      • 
 
-        
    • 
-          If there is no match, SUBST now returns an empty list. In
-          FTJam, the original source string was returned, making it
-          awkward to check whether a pattern was matched. 
-
-          
      
+        
    • If there is no match, SUBST now returns an empty list.
+        In FTJam, the original source string was returned, making it
+        awkward to check whether a pattern was matched.
      • 
 
         
    • Compiled regular expressions are now internally cached, making it
-        much faster to use SUBST multiple times with the same string.
+        much faster to use SUBST multiple times with the same
+        string.
      • 
       
    
 
-    
    The JAM_VERSION global variable
    
+      
    The JAM_VERSION global
+      variable
    
 
-    
    A predefined global variable with two elements indicates the version
-    number of Boost Jam. Boost Jam versions start at "03" "00". Earlier
-    versions of Jam do not automatically define JAM_VERSION.
+      
    A predefined global variable with two elements indicates the version
+      number of Boost Jam. Boost Jam versions start at "03" "00".
+      Earlier versions of Jam do not automatically define
+      JAM_VERSION.
    
 
+      
    Debugging Support
    
 
-    
    Debugging Support
    
+      
    The BACKTRACE rule
    
 
-    
    The BACKTRACE rule
    
+      
    
+
    +rule BACKTRACE ( )
+
    
+      
    
+      Returns a list of quadruples: filename line module rulename...,
+      describing each shallower level of the call stack. This rule can be
+      used to generate useful diagnostic messages from Jam rules. 
 
-
    rule BACKTRACE ( )
-
    
+      
    The -d command-line option admits new arguments:
    
 
-        Returns a list of quadruples: filename line module
-        rulename..., describing each shallower level of the call
-        stack. This rule can be used to generate useful diagnostic
-        messages from Jam rules.
+      
      
+        
    • -d+10 - enables profiling
+        of rule invocations. When Jam exits, it dumps all rules invoked,
+        their gross and net times in platform-dependent units, and the number
+        of times the rule was invoked.
      • 
 
-    
      The -d command-line option admits new arguments:
-
-    
        
-         
      •  -d+10 - enables profiling of rule
-         invocations. When Jam exits, it dumps all rules invoked, their gross
-         and net times in platform-dependent units, and the number of times the
-         rule was invoked.
-
-         
      •  -d+11 - enables parser
-        debugging, if Jam has been compiled with the "--debug"
-        option to the parser generator named by $(YACC).
-
-         
      •  -d+12 - enables dependency graph output
-        . This feature was ``stolen'' from a version of Jam
-        modified by Craig
-        McPheeters.
-
-    
      
+        
    • -d+11 - enables parser
+        debugging, if Jam has been compiled with the "--debug" option
+        to the parser generator named by $(YACC).
      • 
 
+        
    • -d+12 - enables dependency
+        graph output . This feature was ``stolen'' from a version of
+        Jam modified by Craig
+        McPheeters.
      • 
+      
    
     
    
 
     
    Target Names
    
 
     
    In addition to user targets, which
-    correspond directly to the names the user writes in her subproject Jamfile,
-    several additional targets are generated, regardless of the directory from
-    which Jam was invoked:
+    correspond directly to the names the user writes in her subproject
+    Jamfile, several additional targets are generated, regardless of the
+    directory from which Jam was invoked:
    
 
     
      
       
    • A main target has all the same dependencies as a user target
       (i.e. building it updates all requested subvariants). Its name is the
       same except for the addition of $(SOURCE_GRIST), which
-      identifies the subproject. The identification looks like the names of the
-      path components from the project root to the subproject, separated by
-      exclamation points. Thus, if the project is rooted at foo, in
-      the subproject at foo/bar/baz the target my_target is
-      identified by <bar!baz>my_target.
+      identifies the subproject. The identification looks like the names of
+      the path components from the project root to the subproject, separated
+      by exclamation points. Thus, if the project is rooted at foo,
+      in the subproject at foo/bar/baz the target my_target
+      is identified by <bar!baz>my_target.
      • 
 
-      
-    
    • A subvariant target has additional grist identifying its main target 
-        and subvariant. This grist is joined to $(SOURCE_GRIST) with 
-        the platform's directory separator. Thus, on UNIX, a subvariant target 
-        of my_target above might be identified as
-        <bar!baz/my_target/optimization-space/runtime-link-static>my_source.o. 
-        Note that the part of the grist following the first slash, known as the 
-        subvariant id, also corresponds to a fragment of the subvariant 
-        directory path where the corresponding target is generated. Most built 
-        targets will be identified this way. 
-
    
+      
  • A subvariant target has additional grist identifying its
+      main target and subvariant. This grist is joined to
+      $(SOURCE_GRIST) with the platform's directory separator. Thus,
+      on UNIX, a subvariant target of my_target above might be
+      identified as
+      <bar!baz/my_target/optimization-space/runtime-link-static>my_source.o.
+      Note that the part of the grist following the first slash, known as the
+      subvariant id, also corresponds to a fragment of the subvariant
+      directory path where the corresponding target is generated. Most built
+      targets will be identified this way.
    • 
+    
 
     
    Global Variables
    
 
     
    This section describes some of the global variables used by the build
     system. Please note that some parts of the system (particularly those in
     allyourbase.jam) are heavily based on the Jambase file supplied
-    with Jam, and as such do not follow the conventions described below.
+    with Jam, and as such do not follow the conventions described below.
    
 
-    
    Global variables used in the build system fall into three categories:
+    
    Global variables used in the build system fall into three
+    categories:
    
 
     
      
-    
    •  Global variables intended to
-    be set by the user on the command-line or in the environment use
-    ALL_UPPER_CASE names.
+      
    • Global variables intended to be set by the user on the command-line
+      or in the environment use ALL_UPPER_CASE names.
      • 
 
-    
    •  Internal global variables begin with a lower-case "g" and
-    continue in upper-case: gSOME_GLOBAL
+      
    • Internal global variables begin with a lower-case "g" and continue
+      in upper-case: gSOME_GLOBAL
      • 
 
-    
    •  Global variables of the form:
-    gBASE_NAME(arguments), where arguments is a
-    comma-separated argument list, are used internally to achieve a kind of
-    indirection by concatenating variable values:
-    
-
          ECHO $(gFUBAR($(x),$(y))) ;
+      
    • 
+        Global variables of the form:
+        gBASE_NAME(arguments), where
+        arguments is a comma-separated argument list, are used
+        internally to achieve a kind of indirection by concatenating variable
+        values: 
+
+        
      
+
      +    ECHO $(gFUBAR($(x),$(y))) ;
 
      
         
      
+      
      • 
     
    
 
-    
    Please note that the build system commonly takes advantage of Jam's
-    Dynamic Scoping feature (see the local command in the
-    "Flow of Control" section below the link target) to temporarily
-    "change" a global variable by declaring a local of the
-    same name.
+    
    Please note that the build system commonly takes advantage of Jam's
+    Dynamic Scoping feature (see the local command in the "Flow
+    of Control" section below the link target) to temporarily "change" a
+    global variable by declaring a local of the same name.
    
 
     
    Many of the variables that are used to configure how Boost.Build works
-    internally are listed here with brief descriptions.
+    internally are listed here with brief
+    descriptions.
    
 
     
    Variables Associated with SubProject Identity
    
 
     
      
-      
    • SUBDIR_TOKENS - a list of the path elements relative to the
-      project root of the current subproject.
+      
    • SUBDIR_TOKENS - a list of the path elements relative to
+      the project root of the current subproject.
      • 
 
       
    • SUBDIR - the path from the invocation directory to the
-      current subproject directory.
+      current subproject directory.
      • 
     
    
 
     
    Grist Variables
    
 
     
      
       
    • TARGET_GRIST takes the form
-      subproject!id/target/toolset/variant/subvariant-path.
+      subproject!id/target/toolset/variant/subvariant-path.
      • 
     
    
 
     
    Design Criteria
    
 
     
    Assumptions
    
 
-    
    The requirements are driven by several basic assumptions:
+    
    The requirements are driven by several basic assumptions:
    
 
     
      
-      
    • There is no single Boost developer or test facility with access to or
-      knowledge of all the platforms and compilers Boost libraries are used
-      with.
+      
    • There is no single Boost developer or test facility with access to
+      or knowledge of all the platforms and compilers Boost libraries are
+      used with.
      • 
 
       
    • Boost libraries are used across such a wide range of platforms and
-      compilers that almost no other assumptions can be made.
+      compilers that almost no other assumptions can be made.
      • 
     
    
 
     
    Requirements
    
 
-    
    This build system was designed to satisfy the following requirements:
+    
    This build system was designed to satisfy the following
+    requirements:
    
 
     
      
       
    • A developer adding a new library or test program must only have to
       add simple entries naming the source files to a text file, and not have
-      to know anything about platform specific files. The developer should not
-      have to supply header dependency information.
+      to know anything about platform specific files. The developer should
+      not have to supply header dependency information.
      • 
 
       
    • There should be a very high likelihood of builds succeeding on all
       platforms if a build succeeds on any platform. In other words, a
       developer must not be required to have access to many platforms or
-      compilers to ensure correct builds
+      compilers to ensure correct builds
      • 
 
       
    • A user or developer adding support for a new platform or compiler
       should only have to add to a single file describing how to do the build
       for that platform or compiler, and shouldn't have to identify the files
-      that will need to be built.
+      that will need to be built.
      • 
 
       
    • The build should rely only on tools native to the platform and
-      compiler, or supplied via the boost download.
+      compiler, or supplied via the boost download.
      • 
 
       
    • The details of how the build is done for a particular platform or
-      compiler should be appropriate for that platform.
+      compiler should be appropriate for that platform.
      • 
 
-      
    • It should be possible to build multiple variants (e.g. debug/release)
-      of a single target.
+      
    • It should be possible to build multiple variants (e.g.
+      debug/release) of a single target.
      • 
 
-      
    • It should be possible to build multiple variants of multiple targets
-      with multiple compilers from a single build command.
+      
    • It should be possible to build multiple variants of multiple
+      targets with multiple compilers from a single build command.
      • 
 
       
    • The build tools must be able to handle Boost growth issues such as
-      identified in Directory Structure proposals and discussion.
+      identified in Directory Structure proposals and discussion.
      • 
 
-      
    • Support for dynamic and static linking should be included.
+      
    • Support for dynamic and static linking should be included.
      • 
 
       
    • It should be relatively straightforward to add support for a new
       compiler. In most cases, no modification of files used to describe
-      existing targets should be required.
+      existing targets should be required.
      • 
 
       
    • Support for compiler- and variant-specific configuration for each
-      target
+      target
      • 
 
-      
    • It should be possible to build targets into a directory unrelated to
-      the source directories (they may be read-only)
+      
    • It should be possible to build targets into a directory unrelated
+      to the source directories (they may be read-only)
      • 
     
    
 
-    
    Footnotes
     
-[1] Boost Jam is actually descended directly from FTJam, which was 
-itself a variant of Jam/MR. It is hoped that crucial 
-features we rely on will eventually be incorporated back into the Jam/MR release. 
+    
    Footnotes
    
+    [1] Boost Jam is actually descended directly from FTJam, which
+    was itself a variant of Jam/MR. It is hoped that
+    crucial features we rely on will eventually be incorporated back into the
+    Jam/MR release. 
 
-
    [2] Note: right now, a dependency feature of a main
+    
    [2] Note: right now, a dependency feature of a main
     target makes all resulting built targets dependent, including
     intermediate targets. That means that if an executable is dependent on an
-    external library, and that library changes, all the sources comprising the
-    executable will be recompiled as well. This behavior should probably be
-    fixed.
+    external library, and that library changes, all the sources comprising
+    the executable will be recompiled as well. This behavior should probably
+    be fixed.
    
     
    
 
     
    © Copyright David Abrahams 2001. Permission to copy, use, modify,
-    sell and distribute this document is granted provided this copyright notice
-    appears in all copies. This document is provided "as is" without express or
-    implied warranty, and with no claim as to its suitability for any purpose.
+    sell and distribute this document is granted provided this copyright
+    notice appears in all copies. This document is provided "as is" without
+    express or implied warranty, and with no claim as to its suitability for
+    any purpose.
    
 
     
    Revised 
     24 May, 2002
-
\ No newline at end of file
+                                -->24 May, 2002 
+    
+    
    
+  
+
+
diff --git a/v1/build_system.htm b/v1/build_system.htm
index 9546f3596..2b2d967e6 100644
--- a/v1/build_system.htm
+++ b/v1/build_system.htm
@@ -1,100 +1,103 @@
 
-
 
+
+  
     
-    
+    
+    
 
     Boost Build System
-
+  
 
-
-
-    c++boost.gif (8819 bytes)  
+  
+    c++boost.gif (8819 bytes) 
 
     
    Boost Build System
    
 
     
    Synopsis
    
 
-    
    Boost.Build is a system for large project software construction built on
-        Boost.Jam, a descendant of "Perforce Jam", an
-        open-source make replacement[1]. Key features are:
+    
    Boost.Build is a system for large project software construction built
+    on Boost.Jam, a descendant of "Perforce Jam", an open-source
+    make replacement[1]. Key features are:
    
 
     
      
-      
    • A simple target description language
+      
    • A simple target description language
      • 
 
       
    • Build with your choice (or multiple) toolsets from a single command
-      invocation
+      invocation
      • 
 
-      
    • Build your choice of basic variants (e.g. debug, release, profile...)
-      and subvariant modifications (e.g. inlining off) from a single command
-      invocation
+      
    • Build your choice of basic variants (e.g. debug, release,
+      profile...) and subvariant modifications (e.g. inlining off) from a
+      single command invocation
      • 
 
       
    • ``Feature Normalization'' allows target configurations to be
-      described independently from the toolset used
+      described independently from the toolset used
      • 
 
       
    • Modular toolset description files allow build instructions for
-      different toolsets to be described independently
+      different toolsets to be described independently
      • 
 
-      
    • Multiple subproject support
+      
    • Multiple subproject support
      • 
 
-      
    • Automatic building of subproject dependencies
+      
    • Automatic building of subproject dependencies
      • 
     
    
 
     
    Status
    
-
     Boost.Build v1 is a useful, mature system. However, its design and
-    structure are not easily adapted to support some of the features
-    we'd like to see in the future. To this end, the Boost.Build
-    developers have begun work on v2 of Boost.Build, which will be
-    based around this
-    design document. If you are
-    interested in contributing to this effort or you wish to discuss
-    the design of Boost.Build, please post inquiries to the jamboost
-    mailing list at yahoogroups.
+    structure are not easily adapted to support some of the features we'd
+    like to see in the future. To this end, the Boost.Build developers have
+    begun work on v2 of Boost.Build, which will be based around this design document. If you are interested in
+    contributing to this effort or you wish to discuss the design of
+    Boost.Build, please post inquiries to the jamboost mailing list at
+    yahoogroups. 
 
-    
    Here are some of the design criteria that
-    led to these features.
+    
    Here are some of the design criteria
+    that led to these features.
    
 
     
    Table of Contents
    
 
     
+      
 
       
  • 
         Internals 
 
         
+          
    • 
 
-          
  • Target Names
+          
  • Target Names
    • 
 
-          
  • Global Variables
+          
  • Global Variables
    • 
         
+      
 
       
  • 
         Design Criteria 
 
         
+      
    • 
 
-      
  • Footnotes
+      
  • Footnotes
    • 
     
 
     
    Getting Started
    
 
     
    Installing Boost.Jam
    
-    
-    Follow these instructions to acquire
-    a bjam executable for your platform. Install it somewhere in your
-    path.
+    Follow these instructions to acquire a bjam
+    executable for your platform. Install it somewhere in your path. 
 
     
    Initiating a Build
    
 
-    
    Boost.Build responds to several global variable settings. The
-    easiest way to get going is usually to use environment variables,
-    though you can also set them on the command-line, using
-    -sVARIABLE_NAME=value.  In
-    addition to the toolset
-    configuration variables, you can use the TOOLS
-    variable to indicate which toolset(s) to build with, and the
-    BUILD variable to describe how you want things built. In
-    many cases it should be sufficient to invoke bjam
-    with no variable settings.
+    
    Boost.Build responds to several global variable settings. The easiest
+    way to get going is usually to use environment variables, though you can
+    also set them on the command-line, using
+    -sVARIABLE_NAME=value. In addition to the
+    toolset configuration variables, you
+    can use the TOOLS variable to indicate which toolset(s) to build
+    with, and the BUILD variable to describe how you want things
+    built. In many cases it should be sufficient to invoke bjam
+    with no variable settings.
    
 
-    
    Some example Boost.Jam invocations:
+    
    Some example Boost.Jam invocations:
    
 
     
-        
 
-        
+      
+      
 
-        
+      
+      
 
-        
+      
-        
 
-        
+      
-             
+         bjam -sBUILD="<cxxflags>/G6"
    
+          
+
+        
+      
+
+        
    
       
    Command Line(s)
+        Command Line(s)Effects
+        Effects
    
 
       
    
         
-
    bjam -sTOOLS=gcc my_target
+
    +bjam -sTOOLS=gcc my_target
 
    
+        
    		
 
         default (debug) BUILD of
-        my_targetwith GCC
+        my_targetwith GCC
    
 
       
    
         
-            
    bjam -sTOOLS="msvc gcc"
     
+
    +bjam -sTOOLS="msvc gcc"
+
    
+            		default-build all with msvc and gcc
+        default-build all with msvc and gcc
    
 
       
    
         
-
    set TOOLS=msvc
+
    +set TOOLS=msvc
 bjam
 
    
+        
    		
 
         Set an NT environment variable to always build with MSVC
    
-         default-build all.
+         default-build all.
    
 
       
    
         
-
    bjam "-sBUILD=release <debug-symbols>on"
+
    +bjam "-sBUILD=release <debug-symbols>on"
 
    
+        
    		release build with debug symbols of all using
-        default TOOLS
-         
+        release build with debug symbols of all using default
+        TOOLS
    
 
       
    bjam -sBUILD="debug release"
     
+            		
+
    +bjam -sBUILD="debug release"
+
    
+            		debug and release build all.
-             
+        debug and release build all.
    
 
       
    
         set TOOLS=msvc
    
-        bjam -sBUILD="<cxxflags>/G6"
    
-     		Set an NT environment variable to always build with MSVC
    
-         default-build all, adding a compiler command line switch
    Set an NT environment variable to always build with MSVC
    
+         default-build all, adding a compiler command line
+        switch
    
 
       
    
         set TOOLS=msvc gcc
    
-        bjam -sBUILD="<msvc><*><cxxflags>/G6"
    
-     		Set an NT environment variable to always build with MSVC and 
+         bjam -sBUILD="<msvc><*><cxxflags>/G6"
    
+              		Set an NT environment variable to always build with MSVC and
         GCC
    
-         default-build all, adding a MSVC-specific compiler command line switch
    
+         default-build all, adding a MSVC-specific compiler command
+        line switch
+      
    
 
     
    Setting Jam Variables
    
 
-      
    The "-s" options in the command lines above are
-      passing variable settings to the build system. There are actually three ways to do
-      that:
+    
    The "-s" options in the command lines above are passing
+    variable settings to the build system. There are actually three ways to
+    do that:
    
 
-      
      
-      
    • Jam picks up variable settings from your environment by default, so
-      you can set them there:
-
      > BUILD="debug release"  # assuming Unix
+    
        
+      
      • 
+        Jam picks up variable settings from your environment by default, so
+        you can set them there: 
+
+        
        
+
        +> BUILD="debug release"  # assuming Unix
 > export BUILD
 > bjam ...
-
        
-        This approach can be OK for quick-and-dirty tests, but environment variable
-      settings tend to be unstable and non-uniform across users and machines, so
-      it's best not to rely on the environment much.
-      
      • Explicitly on the command-line, with the "-s"
-      option.
-      
      • Directly in Jam code. A project's Jamrules file is a convenient place
-      to make global settings.
-      
      
+
      
+        
      
+        This approach can be OK for quick-and-dirty tests, but environment
+        variable settings tend to be unstable and non-uniform across users
+        and machines, so it's best not to rely on the environment much.
+      
      • 
+
+      
    • Explicitly on the command-line, with the "-s" option.
      • 
+
+      
    • Directly in Jam code. A project's Jamrules
+      file is a convenient place to make global settings.
      • 
+    
    
 
     
    An Example Jamfile
    
     Here is an example of a simple subproject Jamfile. In this example, it is
-    assumed that the user has set BOOST_ROOT, either as an environment
-    variable, on the command-line or in the project's Jamrules file: 
+    assumed that the user has set BOOST_ROOT, either as an
+    environment variable, on the command-line or in the project's Jamrules file: 
 
     
    
-
    subproject foo/bar/baz ; # path to here from project root
+
    +subproject foo/bar/baz ; # path to here from project root
 
 # A static library called 'baz'
 lib baz : baz1.cpp baz2.cpp # C++ sources
@@ -326,174 +400,184 @@ exe test : <lib>baz # use the 'baz' library
 
     
    That's it! The build system takes care of the rest. If the you want to
     be able to build all subprojects from the project root directory, you can
-    add a Jamfile at the root:
+    add a Jamfile at the root:
    
 
     
    
-
    project-root ; # declare this to be the project root directory
+
    +project-root ; # declare this to be the project root directory
 # Read subproject Jamfiles
-subinclude foo/bar/baz foo/bar/... ;
-subinclude a/b/c ... ; # more subincludes
+subinclude foo/bar/baz foo/bar/... ;
+subinclude a/b/c ... ; # more subincludes
 
    
     
    
 
     
    Support Files
    
 
-    
-
    To use the build system, the following must be located in your project's root 
-    directory, or in a directory specified in the BOOST_BUILD_PATH variable. 
-    It is usually convenient to specify the BOOST_BUILD_PATH in your 
-    project's Jamrules file. The Boost Jamrules 
-    file shows an example. 
-
-      
-        
    Filename(s)
+    
    To use the build system, the following must be located in your
+    project's root directory, or in a directory specified in the
+    BOOST_BUILD_PATH variable. It is usually convenient to specify
+    the BOOST_BUILD_PATH in your project's Jamrules file. The Boost
+    Jamrules file shows an example.
    
 
-            		Meaning
+    
+      
+        
+
+        
+      
-        
 
-        
+      
-        
 
-        
+      
-        
 
-        
+      
-        
 
-        
+      
    Filename(s)Meaning
    
 
       
    toolset-tools.jam 
+        toolset-tools.jamFeature-to-command-line mapping for toolset.
+        Feature-to-command-line mapping for toolset.
    
 
       
    features.jam 
+        features.jamAbstract toolset feature descriptions.
+        Abstract toolset feature descriptions.
    
 
       
    boost-base.jam 
+        boost-base.jamBoost build system-specific rule definitions.
+        Boost build system-specific rule definitions.
    
 
       
    unit-tests.jam 
+        unit-tests.jamUnit tests and assertions for boost Jam code.
+        Unit tests and assertions for boost Jam code.
    
     
    
     The boost-base.jam file is temporary, and will eventually be
     compiled into our Jam executable. 
 
     
    Basic Design and Terminology
    
-    This section gives an overview of the way that the system works, outlining 
-the system's capabilities and overall design. It also introduces the terminology 
-and concepts necessary to understand the sections on writing Jamfiles and command-line 
-invocations. 
+    This section gives an overview of the way that the system works,
+    outlining the system's capabilities and overall design. It also
+    introduces the terminology and concepts necessary to understand the
+    sections on writing Jamfiles and command-line invocations. 
 
-
    Projects and Subprojects
    
+    
    Projects and Subprojects
    
 
     
    A project is a source directory tree containing at least one
     Jamfile. The root directory of the project is known as the
-    project root. The root directory of a project
-    may contain a Jamrules file, which contains project-specific Jam
-    code. If the Jamrules file is not present when Jam is invoked, a
-    warning will be issued.
+    project root. The root directory of a
+    project may contain a Jamrules file, which contains
+    project-specific Jam code. If the Jamrules file is not present
+    when Jam is invoked, a warning will be issued.
    
 
     
    Subdirectories containing Jamfiles are called subproject
-    directories. Each such Jamfile describes a subproject.
+    directories. Each such Jamfile describes a
+    subproject.
    
 
-    
-
    The build system installation directory is a directory containing Jam 
-    files describing compilers and build variants. The installation directory 
-    can be specified implicitly by setting the variable BOOST_BUILD_PATH. 
-    This lists a set of directories to search for the files comprising the build 
-    system. If the installation directory is not specified, it is the same as 
-    the project root, and BOOST_BUILD_PATH is set to include that directory. 
-
    Targets
    
+    
    The build system installation directory is a directory
+    containing Jam files describing compilers and build variants. The
+    installation directory can be specified implicitly by setting the
+    variable BOOST_BUILD_PATH. This lists a set of directories to
+    search for the files comprising the build system. If the installation
+    directory is not specified, it is the same as the project root, and
+    BOOST_BUILD_PATH is set to include that directory.
    
 
-    
    Each Jamfile describes one or more main targets.
+    
    Targets
    
+
+    
    Each Jamfile describes one or more main targets.
    
 
     
    Each main target is an abstract description of one or more built
     targets which are expressions of the corresponding main target under
     particular compilers and build variants. Intermediate files such as
-    .o/.obj files generated by compiling .cpp files
-    as a consequence of building a main target are also referred to as built
-    targets. The term build directory tree refers to the location of
-    built target files.
+    .o/.obj files generated by compiling .cpp
+    files as a consequence of building a main target are also referred to as
+    built targets. The term build directory tree refers to the
+    location of built target files.
    
 
     
      
       
    • By default, the build directory tree is overlaid with the project
       directory tree, with targets generated into a subtree rooted at the
-      bin subdirectory of each subproject directory (the name of this
-      directory can be customized by changing the BIN_DIRECTORY
-      variable.
+      bin subdirectory of each subproject directory (the name of
+      this directory can be customized by changing the BIN_DIRECTORY
+      variable.
      • 
 
       
    • If the variable
       ALL_LOCATE_TARGET is set, it specifies an alternate build
-      directory tree whose structure mirrors that of the project. In this case,
-      built targets of a subproject are generated into the corresponding
-      directory of the build directory tree.
+      directory tree whose structure mirrors that of the project. In this
+      case, built targets of a subproject are generated into the
+      corresponding directory of the build directory tree.
      • 
     
    
     For each main target, there is a corresponding location in the build
     directory tree known as the target's build root, where all
-    intermediate and final targets resulting from that main target are located.
-    
+    intermediate and final targets resulting from that main target are
+    located. 
 
     
    Features and Properties
    
 
-    
    A feature is a normalized (toolset-independent) description of an
-    individual build parameter, such as whether inlining is enabled. Each
+    
    A feature is a normalized (toolset-independent) description of
+    an individual build parameter, such as whether inlining is enabled. Each
     feature usually corresponds to a command-line option of one or more build
-    tools. Features come in four varieties:
+    tools. Features come in four varieties:
    
 
     
      
       
    1. Simple features can take on any of several predetermined
-      values. For example, the feature optimization might take one of
-      the values off, speed, or space. Simple
-      features have a default value. The key aspect of simple features is that
-      they are assumed to affect link compatibility: object files generated
-      with different values for a simple feature are generated into a separate
-      directories, and (with a few exceptions) main targets generated with
-      different values won't be linked together.
+      values. For example, the feature optimization might take one
+      of the values off, speed, or space. Simple
+      features have a default value. The key aspect of simple features is
+      that they are assumed to affect link compatibility: object files
+      generated with different values for a simple feature are generated into
+      a separate directories, and (with a few exceptions) main targets
+      generated with different values won't be linked together.
      2. 
 
       
    2. Free features can either be single-valued, as above, or may
-      take on any number of user-specified values simultaneously. For example,
-      the define feature for a release build might have the values
-      NDEBUG and BOOST_RELEASE_BUILD. Free features are
-      assumed not to affect link compatibility.
+      take on any number of user-specified values simultaneously. For
+      example, the define feature for a release build might have the
+      values NDEBUG and BOOST_RELEASE_BUILD. Free features
+      are assumed not to affect link compatibility.
      3. 
 
       
    3. Path features are free features whose values describe paths
       which may be relative to the subproject (such as linked libraries or
-      #include search directories). The build system treats the values
-      of these features specially to ensure that they are interpreted relative
-      to the subproject directory regardless of the directory where Jam was
-      invoked.
+      #include search directories). The build system treats the
+      values of these features specially to ensure that they are interpreted
+      relative to the subproject directory regardless of the directory where
+      Jam was invoked.
      4. 
 
-      
    4. Dependency features are path features whose values describe a
-      dependency of built targets. For example, an external library might be
-      specified with a dependency-feature: if the library is updated, the
+      
    5. Dependency features are path features whose values describe
+      a dependency of built targets. For example, an external library might
+      be specified with a dependency-feature: if the library is updated, the
       target will be updated also. The <library-file> feature
-      works this way [2].
+      works this way [2].
      6. 
     
    
 
     
    A feature-value pair is known as a build property, or simply
-    property. The prefixes simple, free, path, and
-    dependency apply to properties in an analogous way to features.
+    property. The prefixes simple, free, path,
+    and dependency apply to properties in an analogous way to
+    features.
    
 
     
    Build Variants
    
 
     
    A build variant, or simply variant is a named set of build
-    properties describing how targets should be built. Typically you'll want at
-    least two separate variants: one for debugging, and one for your release
-    code.
+    properties describing how targets should be built. Typically you'll want
+    at least two separate variants: one for debugging, and one for your
+    release code.
    
 
-    
    Built targets for distinct build variants and toolsets are generated in
-    separate parts of the build directory tree, known as the variant
-    directories. For example, a (sub)project with main targets foo
-    and bar, compiled with both GCC and KAI for debug and
-    release variants might generate the following structure (target
-    directories in bold).
+    
    Built targets for distinct build variants and toolsets are generated
+    in separate parts of the build directory tree, known as the variant
+    directories. For example, a (sub)project with main targets
+    foo and bar, compiled with both GCC and KAI for
+    debug and release variants might generate the following
+    structure (target directories in bold).
    
 
     
    
-
     bin
- +-foo  <--- foo's build root
+
    + bin
+ +-foo  <--- foo's build root
  | +-gcc
  | | +-debug
  | | `-release
  | `-kai
  |   +-debug
  |   `-release
- `-bar  <--- bar's build root
+ `-bar  <--- bar's build root
    +-gcc
    | +-debug
    | `-release
@@ -505,15 +589,15 @@ invocations.
 
     
    The properties constituting a variant may differ according to toolset,
     so debug may mean a slightly different set of properties for two
-    different compilers.
+    different compilers.
    
 
     
    Subvariants
    
 
-    
    When a target is built with simple properties that don't exactly
-    match those specified in a build variant, the non-matching features are
-    called subvariant features and the target is located in a
-    subvariant directory beneath the directory of the base variant. This
-    can occur for two reasons:
+    
    When a target is built with simple properties that don't
+    exactly match those specified in a build variant, the non-matching
+    features are called subvariant features and the target is located
+    in a subvariant directory beneath the directory of the base
+    variant. This can occur for two reasons:
    
 
     
      
       
    1. 
@@ -521,34 +605,37 @@ invocations.
         simple features have no value specified in the build variant, a value
         must be chosen. Even when the default value is used, the target is
         generated into a subvariant directory. For example, the
-        runtime-link feature may be unspecified in the debug
-        variant, but relevant to MSVC. In that case, a fragment of the target
-        tree might look like: 
+        runtime-link feature may be unspecified in the
+        debug variant, but relevant to MSVC. In that case, a
+        fragment of the target tree might look like: 
 
         
      
-
       bin
- +-foo  <--- foo's build root
+
      + bin
+ +-foo  <--- foo's build root
  | +-msvc
  | | +-debug
  . . . `-runtime-link-dynamic
  . . .
 
      
         
      
-        Because the default value of runtime-link is dynamic,
-        when the debug variant is requested, the
+        Because the default value of runtime-link is
+        dynamic, when the debug variant is requested, the
         runtime-link-dynamic subvariant of foo is built.
      
         
      
+      
      2. 
 
       
    2. 
-        It is possible to request (either on the command-line, or as part of a
-        main target description) that particular subvariants be built. For
+        It is possible to request (either on the command-line, or as part of
+        a main target description) that particular subvariants be built. For
         example, it may be desirable to generate builds that link to the
         runtime both statically and dynamically. In that case, both
         subvariant directories in the example above would be generated: 
 
         
      
-
       bin
- +-foo  <--- foo's build root
+
      + bin
+ +-foo  <--- foo's build root
  | +-msvc
  | | +-debug
  . . . +-runtime-link-dynamic
@@ -556,21 +643,23 @@ invocations.
  . . .
 
      
         
      
+      
      3. 
     
    
-    In no case will targets be built directly into bin/foo/msvc/debug,
-    since the debug variant doesn't include the runtime-link
-    feature, which is relevant to MSVC. 
+    In no case will targets be built directly into
+    bin/foo/msvc/debug, since the debug variant doesn't
+    include the runtime-link feature, which is relevant to MSVC. 
 
     
    When a subvariant includes multiple subvariant features, targets are
-    built into a subvariant directory whose path is determined by concatenating
-    the properties sorted in order of their feature names. For example, the
-    borland compiler, which uses different libraries depending on whether the
-    target is a console or GUI program, might create the following structure
-    for a DLL:
+    built into a subvariant directory whose path is determined by
+    concatenating the properties sorted in order of their feature names. For
+    example, the borland compiler, which uses different libraries depending
+    on whether the target is a console or GUI program, might create the
+    following structure for a DLL:
    
 
     
    
-    
     bin
- +-foo  <--- foo's build root
+
    + bin
+ +-foo  <--- foo's build root
  | +-msvc
  | | +-debug
  | | | +-runtime-link-dynamic
@@ -578,141 +667,156 @@ invocations.
  | | | | `-user-interface-gui
  . . . `-runtime-link-static
  . . .   +-user-interface-console
- . . .   `user-interface-gui
+ . . .   `user-interface-gui
 
    
     
    
 
     
    Any configuration of properties for which a target is built, whether
     base variant or subvariant, is known as a build configuration, or
-    simply a build.
+    simply a build.
    
 
     
    Dependent Targets
    
 
     
    When a main target depends on the product of a second main target (as
     when an executable depends on and links to a static library), each build
     configuration of the dependent target is depends on the
-    corresponding build of the dependency. Because only simple features
-    participate in build identity, the dependent and dependency targets may
-    have completely different free features. This puts the onus on the user for
-    ensuring link-compatibility when certain free properties are used. For
-    example, when assert() is used in header files, the preprocessor
-    symbol NDEBUG can impact link-compatibility of separate
-    compilation units. This danger can be minimized by encapsulating such
-    feature differences inside of build variants.
+    corresponding build of the dependency. Because only simple
+    features participate in build identity, the dependent and dependency
+    targets may have completely different free features. This puts the onus
+    on the user for ensuring link-compatibility when certain free properties
+    are used. For example, when assert() is used in header files,
+    the preprocessor symbol NDEBUG can impact link-compatibility of
+    separate compilation units. This danger can be minimized by encapsulating
+    such feature differences inside of build variants.
    
 
     
    Usage
    
 
     
    This section describes how to start a build from the command-line and
     how to write project and subproject Jamfiles. It also describes the other
-    files written in the Jam language: build-tool specification files, feature
-    descriptions files.
+    files written in the Jam language: build-tool specification files,
+    feature descriptions files.
    
 
     
    The Command Line
    
 
-    
    This section describes in detail how the build system can be invoked.
+    
    This section describes in detail how the build system can be
+    invoked.
    
 
     
    User Targets
    
 
     
    The Jam command line ends with an optional list of target names; if no
-    target names are supplied, the built-in pseudotarget all is built.
-    In a large project, naming targets can be dicey because of collisions. Jam
-    uses a mechanism called grist to distinguish targets
-    that would otherwise have the same name. Fortunately, you won't often have
-    to supply grist at the command-line. When you declare a main target, a Jam
-    pseudotarget of the same name is created which depends on all of the
-    subvariants requested for your invocation of the build system. For example,
-    if your subproject declares:
+    target names are supplied, the built-in pseudotarget all is
+    built. In a large project, naming targets can be dicey because of
+    collisions. Jam uses a mechanism called grist to
+    distinguish targets that would otherwise have the same name. Fortunately,
+    you won't often have to supply grist at the command-line. When you
+    declare a main target, a Jam pseudotarget of the same name is created
+    which depends on all of the subvariants requested for your
+    invocation of the build system. For example, if your subproject
+    declares:
    
 
     
    
-
    exe my_target : my_source1.cpp my_source2.c ;
+
    +exe my_target : my_source1.cpp my_source2.c ;
 
    
     
    
-    and you invoke Jam with -sBUILD="debug release" my_target, you
-    will build both the debug and release versions of my_target. 
-
+    and you invoke Jam with -sBUILD="debug release" my_target,
+    you will build both the debug and release versions of my_target.
     
-
    These simple, ungristed names are called user targets, and are only 
-    available for the subproject where Jam is invoked. That way, builds from the 
-    top level (which may include many Jamfiles through the subinclude rule) and 
-    builds of library dependencies (which may live in other subprojects), don't 
-    collide. If it is necessary to refer more explicitly to a particular target 
-    from the command-line, you will have to add ``grist''. Please see this 
-    section for a more complete description of how to name particular targets 
-    in a build. 
-
    Global Variables
    
+
+    
    These simple, ungristed names are called user targets, and are
+    only available for the subproject where Jam is invoked. That way, builds
+    from the top level (which may include many Jamfiles through the
+    subinclude rule) and builds of library dependencies (which may live in
+    other subprojects), don't collide. If it is necessary to refer more
+    explicitly to a particular target from the command-line, you will have to
+    add ``grist''. Please see this section for a
+    more complete description of how to name particular targets in a
+    build.
    
+
+    
    Global Variables
    
 
     
    This is a partial list of global variables that can be set on the
     command-line. Of course you are free to write your own Jam rules which
     interpret other variables from the command-line. This list just details
     some of the variables used by the build system itself. Note also that if
     you don't like the default values you can override them in your project's
-    Jamrules file.
+    Jamrules file.
    
 
     
-        
 
-        
 
-        
 
-        
+      
 
-        
 
-        
+
+        
+      
-        
+
+        
+      
 
-        
 
-        
 
-        
+      
-        
 
-        
+      
-        
+      
-        
+      
 
-        
 
-        
 
-        
+      
    
       
    Variable  
+        Variable Default
+        DefaultExample
+        ExampleNotes
+        Notes
    
 
       
    
         TOOLS 
-         
+        Platform-dependent
+        Platform-dependent"-sTOOLS=gcc msvc" 
-        build with gcc and msvc
+        "-sTOOLS=gcc msvc"build with gcc and msvc
    
 
       
    -sTOOLS=gcc 
-        build with gcc
+        -sTOOLS=gccbuild with gcc
    
 
       
    
         BUILD 
         
          
-         
+        debug 
+        debug-sBUILD=release 
+        -sBUILD=releasebuild the release variant
+        build the release variant
    
 
       
    "-sBUILD=debug release" 
+        "-sBUILD=debug release"build both debug and release variants
+        build both debug and release variants
    
 
       
    "-sBUILD=<optimization>speed" 
+        "-sBUILD=<optimization>speed"
 
         build a subvariant of the default variant (debug) with
-        optimization for speed.
+        optimization for speed.
    
 
       
    "-sBUILD=debug release <runtime-link>static/dynamic"
-        
+        "-sBUILD=debug release
+        <runtime-link>static/dynamic"
 
         build subvariants of the debug and release variants that link to
-        the runtime both statically and dynamically.
+        the runtime both statically and dynamically.
    
 
       
    
         ALL_LOCATE_TARGET 
         
          
-         
+        empty 
+        empty-sALL_LOCATE_TARGET=~/build 
+        -sALL_LOCATE_TARGET=~/buildGenerate all build results in the build subdirectory of the 
-            user's home directory (UNIX). 
+        Generate all build results in the build subdirectory of
+        the user's home directory (UNIX).
    
     
    
 
     
    SubProject Jamfiles
    
@@ -721,189 +825,233 @@ invocations.
     
    The subproject rule
    
 
     
    A subproject's Jamfile begins with an invocation of the
-    subproject rule that specifies the subproject's location relative
-    to the top of the project tree:
+    subproject rule that specifies the subproject's location
+    relative to the top of the project tree:
    
 
     
    
-
    subproject path-from-top ;
+
    +subproject path-from-top ;
 
    
     
    
 
-    
    The subproject rule tells the build system where to place built
-    targets from the subproject in case ALL_LOCATE_TARGET is used to
-    specify the build directory tree. If there is a Jamfile in the project root
-    directory, you should use the project-root rule instead:
+    
    The subproject rule tells the build system where to place
+    built targets from the subproject in case ALL_LOCATE_TARGET is
+    used to specify the build directory tree. If there is a Jamfile in the
+    project root directory, you should use the project-root rule
+    instead:
    
 
     
    
-
    project-root ;
+
    +project-root ;
 
    
     
    
 
     
    Describing Main Targets
    
 
-    
    A main target is described using the following syntax:
+    
    A main target is described using the following syntax:
    
 
     
    
-
    target-type name : sources
+
    +target-type name : sources
     [ : requirements [ : default-BUILD ] ] ;
 
    
     
    
 
-    
-
      
-    
    • target-type may be one of exe, lib, dll, 
-        stage or template. These are actually names of Jam rules.
-        Additional main target rules are possible; see status/Jamfile or libs/python/build/Jamfile for 
-        examples.
      
-        
      
-    
    • name specifies the name of the main target, multiple targets with 
-        the same name are allowed but only if they are of different types. Normally 
-        this is not the name of the final target file generated. The target file 
-        name depends on the type of target which controls how the base target 
-        name is renamed to conform to platform conventions. For exes 
-        the name might be the same or *.exe. For libs the name 
-        might be *.lib or lib*.a. And for dlls the 
-        name might be *.dll or lib*.so. For platform specific 
-        naming consult the allyourbase.jam 
-        file in the build system.
      
-        
      
-    
    • sources is a list of paths to source files and dependency targets. 
-        A dependency target path is preceded by <template>,
-        <lib>, <dll>, or <exe>,
-        and the final path component specifies the name of a main target in a Jamfile located
-        in the directory given by the initial path components. Paths may be absolute or
-        relative. The type of dependency is also used to decide how to link to it when needed. 
-        Specifying a <lib> indicates the use of static linking, 
-        as opposed to specifying a <dll> which uses dynamic linking. 
-        For example in Unix static linking will be done directly, and dynamic 
-        linking with the common "-l" liker flag and use of 
-        LD_LIBRARY_PATH.
      
-        
      
-        NOTE: It is important to match up the type of source dependency 
-        with the same type the dependency is built as. Trying to specify a source 
-        dependency of <lib> when the target is defined as a <dll> 
-        will cause an error.
      
-        
      
-    
    •  requirements specifies the build 
-        properties intrinsic to the target. Requirements are given as sets of 
-        optionally-qualified build properties: 
-        
       
-
      [[<compiler>]<variant>]<feature>value
+    
        
+      
      • target-type may be one of exe, lib,
+      dll, stage or template. These are actually
+      names of Jam rules. Additional main target rules are possible; see
+      status/Jamfile or libs/python/build/Jamfile
+      for examples.
        
+      
        
+      
        • 
+
+      
      • name specifies the name of the main target, multiple targets
+      with the same name are allowed but only if they are of different types.
+      Normally this is not the name of the final target file generated. The
+      target file name depends on the type of target which controls how the
+      base target name is renamed to conform to platform conventions. For
+      exes the name might be the same or *.exe. For
+      libs the name might be *.lib or lib*.a. And
+      for dlls the name might be *.dll or lib*.so.
+      For platform specific naming consult the allyourbase.jam file in the build
+      system.
        
+      
        
+      
        • 
+
+      
      • sources is a list of paths to source files and dependency
+      targets. A dependency target path is preceded by
+      <template>, <lib>, <dll>,
+      or <exe>, and the final path component specifies the
+      name of a main target in a Jamfile located in the directory given by
+      the initial path components. Paths may be absolute or relative. The
+      type of dependency is also used to decide how to link to it when
+      needed. Specifying a <lib> indicates the use of static
+      linking, as opposed to specifying a <dll> which uses
+      dynamic linking. For example in Unix static linking will be done
+      directly, and dynamic linking with the common "-l" liker flag
+      and use of LD_LIBRARY_PATH.
        
+      
        
+       NOTE: It is important to match up the type of source dependency
+      with the same type the dependency is built as. Trying to specify a
+      source dependency of <lib> when the target is defined as
+      a <dll> will cause an error.
        
+      
        
+      
        • 
+
+      
      • 
+        requirements specifies the
+        build properties intrinsic to the target. Requirements are given as
+        sets of optionally-qualified build properties: 
+
+        
        
+
        +[[<compiler>]<variant>]<feature>value
 
        
         
        
-        <compiler> and <variant>, 
-        if supplied, can be used to restrict the applicability of the requirement. 
-        Either one may be replaced by <*>, which is the same as 
-        omitting it. 
-        
        The system checks that simple feature requirements are not violated 
-            by explicit subvariant build requests, and will issue a warning otherwise. 
-            Free features specified as requirements are simply added to each corresponding 
-            build configuration.
        
-            
        
-    
      •  default-BUILD specifies the configurations 
-        that should be built if the BUILD variable is not otherwise specified. Any elements 
-        not beginning with ``<...>'' refer to build variants. 
-        Other elements use the same syntax as the requirements described above, except that multiple 
-        values may be specified for a simple feature by separating them with a 
-        slash, forming (qualified) multi-valued properties: 
-        
         
-
        [[<compiler>]<variant>]<feature>value1[/value2...]
+        <compiler> and <variant>,
+        if supplied, can be used to restrict the applicability of the
+        requirement. Either one may be replaced by <*>, which
+        is the same as omitting it. 
+
+        
        The system checks that simple feature requirements are not
+        violated by explicit subvariant build requests, and will issue a
+        warning otherwise. Free features specified as requirements are simply
+        added to each corresponding build configuration.
        
+        
        
+        
        
+      
        • 
+
+      
      • 
+        default-BUILD specifies the
+        configurations that should be built if the BUILD variable is not otherwise specified. Any
+        elements not beginning with ``<...>'' refer
+        to build variants. Other elements use the same syntax as the requirements described above, except that
+        multiple values may be specified for a simple feature by separating
+        them with a slash, forming (qualified) multi-valued
+        properties: 
+
+        
        
+
        +[[<compiler>]<variant>]<feature>value1[/value2...]
 
        
         
        
-        When multiple values are specified, it causes all the implied configurations 
-        to be built by default. It is also possible to prevent any default builds 
-        from occurring on this target by using <suppress>true 
-        . This suppresses any local targets, either implicit or explicit, from 
-        building. But, this does not prevent implied targets as required by a 
-        dependency by another target to this one from being built. This is useful, 
-        for example, for defining a set of libraries generically and having them 
-        built only when another target like an exe is built. Such use might look 
-        like: 
-        
         
-
        lib basic : basic.cpp : : <suppress>true ;

        exe test : test.cpp <lib>basic ;
        
+        When multiple values are specified, it causes all the implied
+        configurations to be built by default. It is also possible to prevent
+        any default builds from occurring on this target by using
+        <suppress>true . This suppresses any local
+        targets, either implicit or explicit, from building. But, this does
+        not prevent implied targets as required by a dependency by another
+        target to this one from being built. This is useful, for example, for
+        defining a set of libraries generically and having them built only
+        when another target like an exe is built. Such use might look like: 
+
+        
        
+
        +lib basic : basic.cpp : : <suppress>true ;
        
+
        
+exe test : test.cpp <lib>basic ;
        
 
        
         
        
-        With that the basic library will only be built when the test 
-        executable is built, and only the variations required by the executable 
-        will be built.
        
-    
        • 
-
      
+        With that the basic library will only be built when the
+        test executable is built, and only the variations required
+        by the executable will be built.
      
+      
      • 
+    
    
 
     
    NOTE: for simple features in both requirements and default-BUILD, more-specific qualification
-    overrides less-specific.
+    overrides less-specific.
    
 
     
    Describing Template Targets
    
 
-    
    Template targets provide a way to handle commonalities between projects targets.
-    They have the same form as main targets but do not
-    initiate build requests. A target that lists a template as a dependency inherits
-    all the settings from the template, i.e. the templates sources, requirements and
-    default build settings will be added to the targets settings. Paths mentioned in a
-    template definition are always relative to the subdirectory of the Jamfile
-    containing the templates definition, regardless of the subdirectory of the dependent
-    main target. Typically a project will have at least one template target that handles
-    defines, include paths and additional compiler flags common to all targets in the project.
+    
    Template targets provide a way to handle commonalities between
+    projects targets. They have the same form as main
+    targets but do not initiate build requests. A target that lists a
+    template as a dependency inherits all the settings from the template,
+    i.e. the templates sources, requirements and default build settings will
+    be added to the targets settings. Paths mentioned in a template
+    definition are always relative to the subdirectory of the Jamfile
+    containing the templates definition, regardless of the subdirectory of
+    the dependent main target. Typically a project will have at least one
+    template target that handles defines, include paths and additional
+    compiler flags common to all targets in the project.
    
 
     
    Describing Stage Targets
    
 
-    
    Stage targets are a special kind of target that don't build a single file but 
-    to a collection of files. The goal is to create a directory which is composed 
-    of the various files that other targets generate, or individual files. When 
-    built a stage target creates a directory with the same name as the target, 
-    and copies the dependent files to it. The form of the target is the same as 
-    that of main targets with some differences...
+    
    Stage targets are a special kind of target that don't build a single
+    file but to a collection of files. The goal is to create a directory
+    which is composed of the various files that other targets generate, or
+    individual files. When built a stage target creates a directory with the
+    same name as the target, and copies the dependent files to it. The form
+    of the target is the same as that of main
+    targets with some differences...
    
 
-
      
-    
    • target-type is stage. See libs/regex/build/Jamfile for an 
-        example.
      
-        
      
-    
    • Name specifies the name of the stage and is the name of the directory 
-        created. 
      
-        
      
-    
    • sources is the same as main targets and one can list both generated 
-        targets like <exe>test_exe and individual files, but not
-        template targets.
      
-        
      
-    
    • Requirements the build properties specified are used as with main 
-        targets. But one additional type of requirement is possible: <tag>... 
-        A tag specifies how to "augment" the names of the copied files. 
-        This is needed to distinguish the various files if your collecting different 
-        builds of the same targets. The syntax is: 
-        
       
-
      <tag><feature|variant>value
+    
        
+      
      • target-type is stage. See libs/regex/build/Jamfile for
+      an example.
        
+      
        
+      
        • 
+
+      
      • Name specifies the name of the stage and is the name of the
+      directory created.
        
+      
        
+      
        • 
+
+      
      • sources is the same as main targets and one can list both
+      generated targets like <exe>test_exe and individual
+      files, but not template targets.
        
+      
        
+      
        • 
+
+      
      • 
+        Requirements the build properties specified are used as with
+        main targets. But one additional type of requirement is possible:
+        <tag>... A tag specifies how to "augment" the names of
+        the copied files. This is needed to distinguish the various files if
+        your collecting different builds of the same targets. The syntax is: 
+
+        
        
+
        +<tag><feature|variant>value
 
        
         
        
         
        
-        If the feature or variant is present for 
-        the a target the file for that target is renamed to include the given 
-        value between the basename and the suffix. Two special 
-        tags, <tag><prefix> and <tag><postfix>, 
-        let one prepend and append a value to the "augmentation" respectively.
        
+         If the feature or variant is present
+        for the a target the file for that target is renamed to include the
+        given value between the basename and the suffix. Two
+        special tags, <tag><prefix> and
+        <tag><postfix>, let one prepend and append a
+        value to the "augmentation" respectively.
        
         
        
-    
      •  default-BUILD acts in the same manner as a main target.
        
-    
        • 
-
      
+      
      • 
+
+      
    • default-BUILD acts in the same manner as a main target.
      
+      
      • 
+    
    
 
     
    Example
    
 
-    
    This artificially complex example shows how two executables called "foo"
-    and "fop" might be described in a Jamfile. All common settings are factored out
-    in the templates "base" and "executable". Foo is composed of the sources
-    ./foo.cpp and ./src/bar.cpp (specified relative to the
-    directory in which the Jamfile resides). Fop only has one sourcefile ./fop.cpp.
-    Both executables link against the built target which results from building the target 
-    baz as described in ../bazlib/Jamfile.
+    
    This artificially complex example shows how two executables called
+    "foo" and "fop" might be described in a Jamfile. All common settings are
+    factored out in the templates "base" and "executable". Foo is composed of
+    the sources ./foo.cpp and ./src/bar.cpp (specified
+    relative to the directory in which the Jamfile resides). Fop only has one
+    sourcefile ./fop.cpp. Both executables link against the built
+    target which results from building the target baz as described
+    in ../bazlib/Jamfile.
    
 
     
    
-
    template base : 
+
    +template base : 
     ## Requirements ##
     : <include>../bazlib/include 
       <define>BUILDING_FOO=1
@@ -928,65 +1076,73 @@ exe fop : <template>executable fop.cpp ;
 
    
     
    
 
-    
    The requirements section:
+    
    The requirements section:
    
 
     
      
-      
    • Adds ../bazlib/include to the #include path
+      
    • Adds ../bazlib/include to the #include path
      • 
 
-      
    • Sets the preprocessor symbol BUILDING_FOO to 1
+      
    • Sets the preprocessor symbol BUILDING_FOO to
+      1
      • 
 
       
    • In the release builds, #defines
-      FOO_RELEASE.
+      FOO_RELEASE.
      • 
 
-      
    • When built with MSVC, #defines FOO_MSVC.
+      
    • When built with MSVC, #defines FOO_MSVC.
      • 
 
       
    • In release variants built with MSVC, #defines
-      FOO_MSVC_RELEASE.
+      FOO_MSVC_RELEASE.
      • 
 
-      
    • Most builds under GCC have optimization turned off, but...
+      
    • Most builds under GCC have optimization turned off, but...
      • 
 
-      
    • ...GCC release builds require optimization for space.
+      
    • ...GCC release builds require optimization for space.
      • 
 
-      
    • Requires multithread support on compilers where it's relevant.
+      
    • Requires multithread support on compilers where it's relevant.
      • 
 
-      
    • Adds /usr/local/foolib/include to the #include <*> path
+      
    • Adds /usr/local/foolib/include to the #include
+      <*> path
      • 
     
    
 
-    
    The default-BUILD section:
+    
    The default-BUILD section:
    
 
     
      
-      
    • specifies that debug and release base variants are
-      built by default.
+      
    • specifies that debug and release base variants
+      are built by default.
      • 
 
-      
    • on compilers where the feature is relevant, requests both statically-
-      and dynamically-linked subvariants of the debug variant.
+      
    • on compilers where the feature is relevant, requests both
+      statically- and dynamically-linked subvariants of the debug
+      variant.
      • 
     
    
 
     
    Feature Descriptions
    
 
-    
     Features are described by stating the feature type (simple features are
-    specified with "feature"), followed by the feature
-    name. An optional second argument can be used to list the permissible values
-    of the feature. Examples can be found in features.jam.
-    
+    
    Features are described by stating the feature type (simple features
+    are specified with "feature"), followed by the feature name. An
+    optional second argument can be used to list the permissible values of
+    the feature. Examples can be found in features.jam.
    
+
     
    Variant Descriptions
    
 
-    
    Variants are described with the following syntax:
+    
    Variants are described with the following syntax:
    
 
     
    
-
    variant name : [<toolset-name>]<feature>value... ;
+
    +variant name : [<toolset-name>]<feature>value... ;
 
    
     
    
     The variant rule specifies the list of properties comprising a
-    variant. Properties may be optionally qualified with a toolset name, which
-    specifies that the property applies only to that toolset. One or
-    more parent variants may be specified to inherit the properties  from those
-    parent(s). For inherited properties precedence is given on a left to right
-    order, making the immediate properties override those in the parent(s). This
-    can be used to great effect for describing global properties that are shared
-    amongst various variants, and therefore targets. For example:
+    variant. Properties may be optionally qualified with a toolset name,
+    which specifies that the property applies only to that toolset. One or
+    more parent variants may be specified to inherit the properties
+     from those parent(s). For inherited properties precedence is given
+    on a left to right order, making the immediate properties override those
+    in the parent(s). This can be used to great effect for describing global
+    properties that are shared amongst various variants, and therefore
+    targets. For example: 
+
     
    
-    
    variant my-globals : <rtti>off ;
+
    +variant my-globals : <rtti>off ;
 
 variant my-debug : my-globals debug ;
 
@@ -998,11 +1154,11 @@ variant my-release : my-globals release ;
     
    Toolset Description Files
    
 
     
    Toolset descriptions are located in the project's root directory, or a
-    directory specified by BOOST_BUILD_INSTALLATION, which may be set
-    in a Jamfile or the project's BOOST_BUILD_INSTALLATION, which may be
+    set in a Jamfile or the project's Jamrules file. Each file is called
     toolset-name-tools.jam, where toolset-name is the
-    name of the toolset. The toolset description file has two main jobs:
+    name of the toolset. The toolset description file has two main jobs:
    
 
     
      
       
    1. 
@@ -1010,20 +1166,23 @@ variant my-release : my-globals release ;
 
         
        
           
      • Link-action - links an executable from objects and
-          libraries
+          libraries
        • 
 
           
      • Archive-action - links a static library from object
-          files
+          files
        • 
 
-          
      • C++-action - compiles a 'C++' file into an object file
+          
      • C++-action - compiles a 'C++' file into an object
+          file
        • 
 
-          
      • Cc-action - compiles a 'C' file into an object file
+          
      • Cc-action - compiles a 'C' file into an object
+          file
        • 
         
      
         These rules should simply invoke the action part of a rule whose name
         is uniquely defined for the toolset. For example, 
 
         
      
-
      rule C++-action
+
      +rule C++-action
 {
     msvc-C++-action $(<) : $(>) ;
 }
@@ -1035,162 +1194,152 @@ actions msvc-C++-action
 
 
      
         
      
-        Note that Link-action may require special care: on platforms 
-        where the global variable gEXPORT_SUFFIX(DLL) is defined (e.g. 
-        Windows), the first argument may have two elements when linking a shared 
-        library. The first is the shared library target, and the second is the 
-        import library target, with suffix given by $(gEXPORT_SUFFIX(DLL)). 
-        It will always have a third argument which is either ``EXE'' 
-        or ``DLL''. This can be used to dispatch to different actions 
-        for linking DLLs and EXEs if necessary, but usually it will be easier 
-        to take advantage of the special <target-type> feature, 
-        which will have the same value using the flags rule described 
-        below. 
-
-        
      
+        Note that Link-action may require special care: on platforms
+        where the global variable gEXPORT_SUFFIX(DLL) is defined
+        (e.g. Windows), the first argument may have two elements when linking
+        a shared library. The first is the shared library target, and the
+        second is the import library target, with suffix given by
+        $(gEXPORT_SUFFIX(DLL)). It will always have a third argument
+        which is either ``EXE'' or ``DLL''. This can be
+        used to dispatch to different actions for linking DLLs and EXEs if
+        necessary, but usually it will be easier to take advantage of the
+        special <target-type> feature, which will have the
+        same value using the flags rule described below.
+      
      2. 
 
       
    2. 
-        Translate build settings given in the global gBUILD_PROPERTIES
-        variable into something that can be used by the toolset. The build
-        system provides the flags rule to help translate build
-        properties into elements of global variables which are later attached
-        to targets so that they can affect the build actions. The
-        flags rule is used as follows: 
+        Translate build settings given in the global
+        gBUILD_PROPERTIES variable into something that can be used
+        by the toolset. The build system provides the flags rule to
+        help translate build properties into elements of global variables
+        which are later attached to targets so that they can affect the build
+        actions. The flags rule is used as follows: 
 
         
      
-
      flags toolset variable condition [: value...]
+
      +flags toolset variable condition [: value...]
 
      
         
      
         The parameters are: 
 
         
        
-          
      • toolset - the name of the toolset
+          
      • toolset - the name of the toolset
        • 
 
-          
      • variable - the name of a global variable which can be used
-          to carry information to a command-line
+          
      • variable - the name of a global variable which can be
+          used to carry information to a command-line
        • 
 
           
      • 
-            condition - one one or more elements in the following forms:
-            
+            condition - one one or more elements in the following
+            forms: 
 
             
          
               
        1. a property-set of the form:
               <feature>value[/<feature>
-              value...]
+              value...]
          2. 
 
-              
        2. <feature>
+              
        3. <feature>
          4. 
             
        
+          
        • 
 
-          
      • values - anything
+          
      • values - anything
        • 
         
      
 
-        
      Semantics only affect targets built with the specified toolset, and
-        depend on the target's build configuration:
+        
      Semantics only affect targets built with the specified toolset,
+        and depend on the target's build configuration:
      
 
         
        
           
      1. if any specified property-set is a subset of the target's build
           properties, the values specified in $(3) will be
-          appended once to variable.
+          appended once to variable.
        2. 
 
-            
      2. The value of each specified feature that participates in the target's 
-                build properties is appended to variable. In either case, 
-                the variable will be set "on" the target so it may be used in 
-                the build actions. 
+          
      3. The value of each specified feature that participates in the
+          target's build properties is appended to variable. In either
+          case, the variable will be set "on" the target so it may be used in
+          the build actions.
        4. 
         
      
+      
      3. 
     
    
 
     
    Example
    
 
     
    The description of the flags rule above is actually more
     complicated than it sounds. For example, the following line might be used
-    to specify how optimization can be turned off for MSVC:
+    to specify how optimization can be turned off for MSVC:
    
 
     
    
-
    flags msvc CFLAGS <optimization>off : /Od ;
+
    +flags msvc CFLAGS <optimization>off : /Od ;
 
    
     
    
-    It says that the string /Od should be added to the global CFLAGS 
-variable whenever a build configuration includes the property <optimization>off. 
+    It says that the string /Od should be added to the global
+    CFLAGS variable whenever a build configuration includes the
+    property <optimization>off. 
 
-
    Similarly, in the following example,
+    
    Similarly, in the following example,
    
 
     
    
-
    flags msvc CFLAGS <runtime-build>release/<runtime-link>dynamic : /MD ;
+
    +flags msvc CFLAGS <runtime-build>release/<runtime-link>dynamic : /MD ;
 
    
     
    
     we add /MD to the CFLAGS variable when both of the specified
     conditions are satisfied. We could grab all of the values of the free
-    feature <include> in the HDRS variable as follows: 
+    feature <include> in the HDRS variable as
+    follows: 
 
     
    
-
    flags msvc HDRS <include> ;
+
    +flags msvc HDRS <include> ;
 
    
     
    
 
     
    The use of these variables should be apparent from the declaration of
-    actions msvc-C++-action in the previous section.
+    actions msvc-C++-action in the previous section.
    
 
     
    Internals
    
 
     
    Jam Fundamentals
    
 
-    
    This section is derived from the official Jam documentation and from my
-    experience using it and reading the Jambase rules. I repeat the information
-    here mostly because it is essential to understanding and using Jam, but is
-    not consolidated in a single place. Some of it is missing from the official
-    documentation altogether. I hope it will be useful to anyone wishing to
-    become familiar with Jam and the Boost build system.
-
-    
    
+    
    This section is derived from the official Jam documentation and from
+    my experience using it and reading the Jambase rules. I repeat the
+    information here mostly because it is essential to understanding and
+    using Jam, but is not consolidated in a single place. Some of it is
+    missing from the official documentation altogether. I hope it will be
+    useful to anyone wishing to become familiar with Jam and the Boost build
+    system.
    
 
     
      
+      
    • Jam ``rules'' are actually simple procedural entities. Think
+      of them as functions. Arguments are separated by colons.
      • 
 
-      
    • 
-        Jam ``rules'' are actually simple procedural entities. Think of
-        them as functions. Arguments are separated by colons. 
+      
    • A Jam target is an abstract entity identified by an
+      arbitrary string. The build-in DEPENDS rule creates a link in
+      the dependency graph between the named targets.
      • 
 
-        
      
+      
    • Note that the documentation for the built-in INCLUDES rule
+      is incorrect: INCLUDES targets1 : targets2
+      causes everything that depends on a member of targets1 to depend
+      on all members of targets2. It does this in an odd way, by
+      tacking targets2 onto a special tail section in the dependency
+      list of everything in targets1. It seems to be OK to create
+      circular dependencies this way; in fact, it appears to be the ``right
+      thing to do'' when a single build action produces both targets1
+      and targets2.
      • 
 
-      
    • 
-        A Jam target is an abstract entity identified by an arbitrary
-        string. The build-in DEPENDS rule creates a link in the
-        dependency graph between the named targets. 
+      
    • When a rule is invoked, if there are actions
+      declared with the same name as the rule, the actions are added
+      to the updating actions for the target identified by the rule's first
+      argument. It is actually possible to invoke an undeclared rule if
+      corresponding actions are declared: the rule is treated as empty.
      • 
 
-        
      
-
-      
    • 
-        Note that the documentation for the built-in INCLUDES rule is
-        incorrect: INCLUDES targets1 : targets2 causes
-        everything that depends on a member of targets1 to depend on all
-        members of targets2. It does this in an odd way, by tacking
-        targets2 onto a special tail section in the dependency list of
-        everything in targets1. It seems to be OK to create circular
-        dependencies this way; in fact, it appears to be the ``right thing to
-        do'' when a single build action produces both targets1 and
-        targets2.
-
-        
      
-
-      
    • 
-        When a rule is invoked, if there are actions declared
-        with the same name as the rule, the actions are added to the
-        updating actions for the target identified by the rule's first
-        argument. It is actually possible to invoke an undeclared rule if
-        corresponding actions are declared: the rule is treated as empty. 
-
-        
      
-
-      
    • 
-        Targets (other than NOTFILE targets) are
-        associated with paths in the file system through a process called binding.
-        Binding is a process of searching for a file with the same name as the
-        target (sans grist), based on the settings of the
-        target-specific SEARCH and
-        LOCATE variables. 
-
-        
      
+      
    • Targets (other than NOTFILE targets)
+      are associated with paths in the file system through a process called
+      binding.
+      Binding is a process of searching for a file with the same name as the
+      target (sans grist), based on the settings of the
+      target-specific SEARCH and
+      LOCATE variables.
      • 
 
       
    • 
         In addition to local and global
@@ -1198,52 +1347,43 @@ variable whenever a build configuration includes the property <optimizati
         target. Target-specific variable values can usually not be read, and
         take effect only in the following contexts: 
 
-        
      
-
         
        
-          
      • In updating actions, variable values are first looked up
-          on the target named by the first argument (the target
-          being updated). Because Jam builds its entire dependency tree before
-          executing actions, Jam rules make target-specific variable
-          settings as a way of supplying parameters to the corresponding
-          actions.
+          
      • In updating actions, variable values are first looked
+          up on the target named by the first argument (the
+          target being updated). Because Jam builds its entire dependency
+          tree before executing actions, Jam rules make
+          target-specific variable settings as a way of supplying parameters
+          to the corresponding actions.
        • 
 
           
      • Binding is controlled entirely by the target-specific
           setting of the SEARCH and LOCATE variables, as
           described here.
+          "http://public.perforce.com/public/jam/src/Jam.html#search">here.
        • 
 
           
      • In the special rule used for header
           file scanning, variable values are first looked up
-          on the target named by the rule's first argument (the
-          source file being scanned).
+          on the target named by the rule's first argument
+          (the source file being scanned).
        • 
         
      
+      
      • 
 
-        
      
+      
    • The ``bound value'' of a variable is the path associated
+      with the target named by the variable. In build actions, the
+      first two arguments are automatically replaced with their bound values.
+      Target-specific variables can be selectively replaced by their bound
+      values using the bind
+      action modifier.
      • 
 
-      
    • 
-        The ``bound value'' of a variable is the path associated with
-        the target named by the variable. In build actions, the first
-        two arguments are automatically replaced with their bound values.
-        Target-specific variables can be selectively replaced by their bound
-        values using the bind
-        action modifier. 
-
-        
      
-
-      
    • 
-        Note that the term ``binding'' as used in the Jam documentation
-        indicates a phase of processing that includes three sub-phases:
-        binding (yes!), update determination, and header file scanning.
-        The repetition of the term ``binding'' can lead to some confusion. In
-        particular, the Modifying
-        Binding section in the Jam documentation should probably be titled
-        ``Modifying Update Determination''. 
-
-        
      
+      
    • Note that the term ``binding'' as used in the Jam documentation
+      indicates a phase of processing that includes three sub-phases:
+      binding (yes!), update determination, and header file scanning.
+      The repetition of the term ``binding'' can lead to some confusion. In
+      particular, the Modifying
+      Binding section in the Jam documentation should probably be titled
+      ``Modifying Update Determination''.
      • 
 
       
    • 
         
      ``Grist'' is just a string prefix of the form
@@ -1252,150 +1392,166 @@ variable whenever a build configuration includes the property <optimizati
         file name ``test.exe'' may be used by targets in separate
         subprojects, or for the debug and release variants of the ``same''
         abstract target. Each distinct target bound to a file called
-        ``test.exe'' has its own unique grist prefix. The Boost build
-        system also takes full advantage of Jam's ability to divide strings on
-        grist boundaries, sometimes concatenating multiple gristed elements at
-        the beginning of a string. Grist is used instead of identifying targets
-        with absolute paths for two reasons:
+        ``test.exe'' has its own unique grist prefix. The Boost
+        build system also takes full advantage of Jam's ability to divide
+        strings on grist boundaries, sometimes concatenating multiple gristed
+        elements at the beginning of a string. Grist is used instead of
+        identifying targets with absolute paths for two reasons:
      
 
         
        
-          
      1. The location of targets cannot always be derived solely from what
-          the user puts in a Jamfile, but sometimes depends also on the binding process. Some mechanism to distinctly
-          identify targets with the same name is still needed.
+          
      2. The location of targets cannot always be derived solely from
+          what the user puts in a Jamfile, but sometimes depends also on the
+          binding process. Some mechanism to
+          distinctly identify targets with the same name is still
+          needed.
        3. 
 
           
      3. Grist allows us to use a uniform abstract identifier for each
           built target, regardless of target file location (as allowed by
-          setting ALL_LOCATE_TARGET.
+          setting ALL_LOCATE_TARGET.
        4. 
         
      
-        When grist is extracted from a name with $(var:G), 
-        the result includes the leading and trailing angle brackets. When grist 
-        is added to a name with $(var:G=expr), 
-        existing grist is first stripped. Then, if expr is non-empty, leading 
-        <s and trailing >s are added if necessary to form 
-        an expression of the form <expr2>; <expr2> 
-        is then prepended. 
+        When grist is extracted from a name with
+        $(var:G), the result includes the leading
+        and trailing angle brackets. When grist is added to a name with
+        $(var:G=expr), existing
+        grist is first stripped. Then, if expr is non-empty, leading
+        <s and trailing >s are added if necessary to
+        form an expression of the form
+        <expr2>;
+        <expr2> is then prepended.
+      
      • 
 
-        
      
-
-      
-    
    •  When Jam is invoked it imports all environment 
-        variable settings into corresponding Jam variables, followed by all command-line 
-        (-s...) variable settings. Variables whose name ends in PATH, 
-        Path, or path are split into string lists on OS-specific 
-        path-list separator boundaries (e.g. ":" for UNIX and 
-        ";" for Windows). All other variables are split on 
-        space (" ") boundaries. Boost Jam modifies that 
-        behavior by allowing variables to be quoted. 
-
-        
      
+      
    • When Jam is invoked it imports all
+      environment variable settings into corresponding Jam variables,
+      followed by all command-line (-s...) variable settings.
+      Variables whose name ends in PATH, Path, or
+      path are split into string lists on OS-specific path-list
+      separator boundaries (e.g. ":" for UNIX and ";" for
+      Windows). All other variables are split on space (" ")
+      boundaries. Boost Jam modifies that behavior by allowing variables to
+      be quoted.
      • 
 
       
    • 
         A variable whose value is an empty list or which consists
         entirely of empty strings has a negative logical value. Thus, for
         example, code like the following allows a sensible non-empty default
-        which can easily be overridden by the user:
-
      MESSAGE ?= starting jam... ;
+        which can easily be overridden by the user: 
+
+        
      
+
      +MESSAGE ?= starting jam... ;
 if $(MESSAGE) { ECHO The message is: $(MESSAGE) ; }
-
      
+
      
+        
      
         If the user wants a specific message, he invokes jam with
-        "-sMESSAGE=message text". If he
-        wants no message, he invokes jam with -sMESSAGE= and nothing at
+        "-sMESSAGE=message text". If he wants
+        no message, he invokes jam with -sMESSAGE= and nothing at
         all is printed.
-
-        
      
-
+      
      • 
     
    
 
     
    Please also read The Jam language
     reference for the additional details, and the Jam release notes
-    for a brief description of recent, but fundamental changes to the Jam
-    language without which you will probably not understand any of the
-    build system code. In particular, note that the return statement
-    does not affect control flow.
+    "http://public.perforce.com/public/jam/src/RELNOTES">Jam release
+    notes for a brief description of recent, but fundamental changes
+    to the Jam language without which you will probably not understand
+    any of the build system code. In particular, note that the
+    return statement does not affect control flow.
    
 
     
    Core Jam Extensions
    
 
-    
    A number of enhancements have been made to the core language of Classic
-    Jam. These changes were aimed primarily at making it easier to manage the
-    complexity of a large system such as Boost.Build.
+    
    A number of enhancements have been made to the core language of
+    Classic Jam. These changes were aimed primarily at making it easier to
+    manage the complexity of a large system such as Boost.Build.
    
 
     
    
+      
    Command-line and Environment
+      Variable Quoting
    
 
-      
    Command-line and Environment Variable Quoting
    
+      
    Classic Jam had an odd behavior
+      with respect to command-line variable ( -s...) and environment
+      variable settings which made it impossible to define an arbitrary
+      variable with spaces in the value. Boost Jam remedies that by treating
+      all such settings as a single string if they are surrounded by
+      double-quotes. Uses of this feature can look interesting, since shells
+      require quotes to keep characters separated by whitespace from being
+      treated as separate arguments:
    
 
-      
    Classic Jam had an odd behavior with
-      respect to command-line variable ( -s...) and environment
-      variable settings which made it impossible to define an arbitrary variable
-      with spaces in the value. Boost Jam remedies that by treating all such
-      settings as a single string if they are surrounded by double-quotes. Uses
-      of this feature can look interesting, since shells require quotes to keep
-      characters separated by whitespace from being treated as separate
-      arguments:
-
    jam -sMSVCNT="\"\"C:\Program Files\Microsoft Visual C++\VC98\"\"" ...
-
    
+      
    
+
    +jam -sMSVCNT="\"\"C:\Program Files\Microsoft Visual C++\VC98\"\"" ...
+
    
+      
    
+      The outer quote is for the shell. The middle quote is for Jam, to tell
+      it to take everything within those quotes literally, and the inner
+      quotes are for the shell again when paths are passed as arguments to
+      build actions. Under NT, it looks a lot more sane to use environment
+      variables before invoking jam when you have to do this sort of quoting:
+      
 
-      The outer quote is for the shell. The middle quote is for Jam,
-      to tell it to take everything within those quotes literally, and
-      the inner quotes are for the shell again when paths are passed
-      as arguments to build actions. Under NT, it looks a lot more
-      sane to use environment variables before invoking jam when you
-      have to do this sort of quoting:
-
-
    set MSVCNT=""C:\Program Files\Microsoft Visual C++\VC98\""
-
    
+      
    
+
    +set MSVCNT=""C:\Program Files\Microsoft Visual C++\VC98\""
+
    
+      
    
 
       
    Startup Behavior
    
 
-      
    The Boost.Build v2 initialization behavior has been
-      implemented. This behavior only applies when the executable
-      being invoked is called "bjam" or, for
-      backward-compatibility, when the BOOST_ROOT
-      variable is set.
+      
    The Boost.Build v2 initialization behavior has been implemented.
+      This behavior only applies when the executable being invoked is called
+      "bjam" or, for backward-compatibility, when the
+      BOOST_ROOT variable is set.
    
 
-   
      
-   
    1.  We attempt to load "boost-build.jam" by searching from the
-        current invocation directory up to the root of the
-        file-system. This file is expected to invoke the
-        boost-build rule to indicate where the Boost.Build
-        system files are, and to load them.
-   
    2.  If boost-build.jam is not found we error and exit, giving
-        brief instructions on possible errors. 
-
      
-As a backward-compatibility measure for older versions of Boost.Build,
-when the BOOST_ROOT variable is set, we first search for
-boost-build.jam in $(BOOST_ROOT)/tools/build
-and $(BOOST_BUILD_PATH). If found, it is loaded and
-initialization is complete.
-
      
-   
    3.  The boost-build rule adds its (optional) argument
-        to the front of BOOST_BUILD_PATH, and attempts to
-        load bootstrap.jam from those directories. If a
-        relative path is specified as an argument, it is treated as
-        though it was relative to the boost-build.jam
-        file.
-   
    4.  If the bootstrap.jam file was not found, we print a likely
-           error message and exit.
-
    
+      
      
+        
    1. We attempt to load "boost-build.jam" by searching from the
+        current invocation directory up to the root of the file-system. This
+        file is expected to invoke the boost-build rule to indicate
+        where the Boost.Build system files are, and to load them.
      2. 
+
+        
    2. 
+          If boost-build.jam is not found we error and exit, giving brief
+          instructions on possible errors. 
+
+          
      
+            As a backward-compatibility measure for older versions of
+            Boost.Build, when the BOOST_ROOT variable is set, we
+            first search for boost-build.jam in
+            $(BOOST_ROOT)/tools/build and
+            $(BOOST_BUILD_PATH). If found, it is loaded and
+            initialization is complete.
+          
      
+        
      3. 
+
+        
    3. The boost-build rule adds its (optional) argument to
+        the front of BOOST_BUILD_PATH, and attempts to load
+        bootstrap.jam from those directories. If a relative path
+        is specified as an argument, it is treated as though it was relative
+        to the boost-build.jam file.
      4. 
+
+        
    4. If the bootstrap.jam file was not found, we print a likely error
+        message and exit.
      5. 
+      
    
 
       
    Rule Indirection
    
 
-      
    Boost Jam allows you to call a rule whose name is held in a variable or
-      computed as the result of an expression:
-
    x = foo ;
+      
    Boost Jam allows you to call a rule whose name is held in a variable
+      or computed as the result of an expression:
    
+
+      
    
+
    +x = foo ;
 rule foobar { ECHO foobar ; }   # a trivial rule
 $(x)bar ;                       # invokes foobar
 
-
    
-      
-      Furthermore, if the first expression expands to more than one
-      list item, everything after the first item becomes part of the
-      first argument. This allows a crude form of argument binding:
+
    
+      
    
+      Furthermore, if the first expression expands to more than one list
+      item, everything after the first item becomes part of the first
+      argument. This allows a crude form of argument binding: 
 
-
    # return the elements of sequence for which predicate returns non-nil
+      
    
+
    +# return the elements of sequence for which predicate returns non-nil
 rule filter ( sequence * : predicate + )
 {
     local result ;
@@ -1415,16 +1571,18 @@ rule equal ( x y )
 # bind 3 to the first argument of equal
 ECHO [ filter 1 2 3 4 5 4 3 : equal 3 ] ; # prints "3 3"
 
-
    
+
    
+      
    
 
-
    Argument lists
    
+      
    Argument lists
    
 
       
    You can now describe the arguments accepted by a rule, and refer to
       them by name within the rule. For example, the following prints ``I'm
-      sorry, Dave'' to the console:
+      sorry, Dave'' to the console:
    
 
       
    
-
    rule report ( pronoun index ? : state : names + )
+
    +rule report ( pronoun index ? : state : names + )
 {
     local he.suffix she.suffix it.suffix = s ;
     local I.suffix = m ;
@@ -1441,35 +1599,40 @@ report I 2 : sorry : Joe Dave Pete ;
 
       
-          
 
-          
+        
-          
 
-          
+        
-          
 
-          
+        
-          
 
-          
+        
    
         
    Symbol
+          SymbolSemantics of preceding symbol
+          Semantics of preceding symbol
    
 
         
    ? 
+          ?optional
+          optional
    
 
         
    * 
+          *Bind to zero or more unbound elements of the actual
-          argument. When ``*'' appears where an argument name
-          is expected, any number of additional arguments are
-          accepted. This feature can be used to implement
-          "varargs" rules.
+          Bind to zero or more unbound elements of the actual argument.
+          When ``*'' appears where an argument name is expected, any
+          number of additional arguments are accepted. This feature can be
+          used to implement "varargs" rules.
    
 
         
    + 
+          +Bind to one or more unbound elements of the actual argument.
+          Bind to one or more unbound elements of the actual
+          argument.
    
       
    
 
-      
    The actual and formal arguments are checked for inconsistencies, which
-      cause Jam to exit with an error code:
+      
    The actual and formal arguments are checked for inconsistencies,
+      which cause Jam to exit with an error code:
    
 
       
    
-
    ### argument error
+
    +### argument error
 # rule report ( pronoun index ?  : state  : names + )
 # called with: ( I 2 foo  : sorry  : Joe Dave Pete )
 # extra argument foo
@@ -1480,36 +1643,38 @@ report I 2 : sorry : Joe Dave Pete ;
 # missing argument names
 
    
       
    
-      
    If you omit the list of formal arguments, all checking is
-      bypassed as in ``classic'' Jam. Argument lists drastically improve the
+
+      
    If you omit the list of formal arguments, all checking is bypassed
+      as in ``classic'' Jam. Argument lists drastically improve the
       reliability and readability of your rules, however, and are strongly
-      recommended for any new Jam code you write.
+      recommended for any new Jam code you write.
    
 
       
    Module Support
    
 
       
    Boost Jam introduces support for modules, which provide some
       rudimentary namespace protection for rules and variables. A new
       keyword, ``module'' was also introduced. The features
-      described in this section are primitives, meaning that
-      they are meant to provide the operations needed to write Jam
-      rules which provide a more elegant module interface.
-
-      
    
+      described in this section are primitives, meaning that they are
+      meant to provide the operations needed to write Jam rules which provide
+      a more elegant module interface.
    
 
       
    
-        
    Declaration
    
-         module 
-        expression {  ... }  
+        
    Declaration
    
+        module 
+        expression {  ... } 
+        
 
-        
    Code within the {  ... } executes within the
-        module named by evaluating expression. Rule definitions can be
-        found in the module's own namespace, and in the namespace of the global
-        module as module-name.rule-name, so within a
-        module, other rules in that module may always be invoked without
-        qualification:
+        
    Code within the {  ... } executes
+        within the module named by evaluating expression. Rule
+        definitions can be found in the module's own namespace, and in the
+        namespace of the global module as
+        module-name.rule-name, so within a module,
+        other rules in that module may always be invoked without
+        qualification:
    
 
         
    
-
    module my_module
+
    +module my_module
 {
     rule salute ( x ) { ECHO $(x), world ; }
     rule greet ( ) { salute hello ; }
@@ -1518,28 +1683,29 @@ report I 2 : sorry : Joe Dave Pete ;
 my_module.salute goodbye ;
 
    
         
    
-        When an invoked rule is not found in the current module's namespace, it
-        is looked up in the namespace of the global module, so qualified calls
-        work across modules: 
+        When an invoked rule is not found in the current module's namespace,
+        it is looked up in the namespace of the global module, so qualified
+        calls work across modules: 
 
         
    
-
    module your_module
+
    +module your_module
 {
     rule bedtime ( ) { my_module.salute goodnight ; }
 }
 
    
         
    
 
-        
    
-
         
    Variable Scope
    
 
-        
    Each module has its own set of dynamically nested variable
-        scopes. When execution passes from module A to module B, all
-        the variable bindings from A become unavailable, and are
-        replaced by the bindings that belong to B. This applies
-        equally to local and global variables:
-
    
+        
    Each module has its own set of dynamically nested variable scopes.
+        When execution passes from module A to module B, all the variable
+        bindings from A become unavailable, and are replaced by the bindings
+        that belong to B. This applies equally to local and global
+        variables:
    
+
+        
    
+
     module A
 {
     x = 1 ;
@@ -1550,7 +1716,7 @@ module A
     }
     rule g ( )
     {
-        ECHO $(y) ;     # prints "999"
+        ECHO $(y) ;     # prints "999"
     }
 }
 
@@ -1559,18 +1725,18 @@ module B
     y = 2 ;
     rule f ( )
     {
-        ECHO $(y) ; # always prints "2"
+        ECHO $(y) ; # always prints "2"
         A.g ;
     }
 }
-
    
 
    
-
-        The only way to access another module's variables is by
-        entering that module:
+        
    
+        The only way to access another module's variables is by entering that
+        module: 
 
         
    
-
    rule peek ( module-name ? : variables + )
+
    +rule peek ( module-name ? : variables + )
 {
     module $(module-name)
     {
@@ -1579,55 +1745,59 @@ module B
 }
 
    
         
    
-
-        Note that because existing variable bindings change whenever a
-        new module scope is entered, argument bindings become
-        unavailable. That explains the use of
-        "$(>)" in the peek rule
-        above.
+        Note that because existing variable bindings change whenever a new
+        module scope is entered, argument bindings become unavailable. That
+        explains the use of "$(>)" in the peek
+        rule above. 
 
         
    Local Rules
    
 
         
    
-              local rule rulename...
+          local rule rulename...
         
    
 
-        
    The rule is declared locally to the current module. It is
-        not entered in the global module with qualification, and its
-        name will not appear in the result of
+        
    The rule is declared locally to the current module. It is not
+        entered in the global module with qualification, and its name will
+        not appear in the result of
    
+
         
    
-        [ RULENAMES module-name ].
+          [ RULENAMES module-name ].
         
    
-                
+
         
    The RULENAMES Rule
    
-        
+
         
    
-
    rule RULENAMES ( module ? )
+
    +rule RULENAMES ( module ? )
 
    
         
    
-        Returns a list of the names of all non-local rules in the given module. 
-        If module is omitted, the names of all non-local rules in the 
-        global module are returned. 
+        Returns a list of the names of all non-local rules in the given
+        module. If module is omitted, the names of all non-local
+        rules in the global module are returned. 
+
         
    The IMPORT Rule
    
-        
-        IMPORT allows rule name aliasing across modules:
+        IMPORT allows rule name aliasing across modules: 
 
         
    
-
    rule IMPORT (  source_module ? : source_rules *
+
    +rule IMPORT (  source_module ? : source_rules *
                 : target_module ? : target_rules * )
 
    
         
    
- The IMPORT rule copies rules from the source_module into the
- target_module as local rules. If either source_module or
- target_module is not supplied, it refers to the global
- module. source_rules specifies which rules from the source_module to
- import; TARGET_RULES specifies the names to give those rules in
- target_module. If source_rules contains a name which doesn't
- correspond to a rule in source_module, or if it contains a different
- number of items than target_rules, an error is issued. For example,
+        The IMPORT rule copies rules from the source_module
+        into the target_module as local rules. If either
+        source_module or target_module is not supplied, it
+        refers to the global module. source_rules specifies which
+        rules from the source_module to import;
+        TARGET_RULES specifies the names to give those rules in
+        target_module. If source_rules contains a name
+        which doesn't correspond to a rule in source_module, or if
+        it contains a different number of items than target_rules,
+        an error is issued. For example, 
 
         
    
-
    # import m1.rule1 into m2 as local rule m1-rule1.
+
    +# import m1.rule1 into m2 as local rule m1-rule1.
 IMPORT m1 : rule1 : m2 : m1-rule1 ;
 
 # import all non-local rules from m1 into m2
@@ -1636,18 +1806,21 @@ IMPORT m1 : [ RULENAMES m1 ] : m2 : [ RULENAMES m1 ] ;
         
    
 
         
    The EXPORT Rule
    
-        
-        EXPORT allows rule name aliasing across modules:
+        EXPORT allows rule name aliasing across modules: 
 
         
    
-
    rule EXPORT ( module ? : rules * )
+
    +rule EXPORT ( module ? : rules * )
 
    
         
    
- The EXPORT rule marks rules from the source_module as non-local
- (and thus exportable). If an element of rules does not name a
- rule in module, an error is issued. For example,
+        The EXPORT rule marks rules from the
+        source_module as non-local (and thus exportable). If an
+        element of rules does not name a rule in module, an
+        error is issued. For example, 
+
         
    
-
    module X {
+
    +module X {
   local rule r { ECHO X.r ; }
 }
 IMPORT X : r : : r ; # error - r is local in X
@@ -1656,21 +1829,24 @@ IMPORT X : r : : r ; # OK.
 
    
         
    
 
-        
    The CALLER_MODULE Rule
    
-        
-        
    
-
    rule CALLER_MODULE ( levels ? )
-
    
-        
    
-        CALLER_MODULE returns the name of the module scope
-        enclosing the call to its caller (if levels is supplied, it is
-        interpreted as an integer number of additional levels of call stack to
-        traverse to locate the module). If the scope belongs to the global
-        module, or if no such module exists, returns the empty list. For
-        example, the following prints "{Y} {X}":
+        
    The CALLER_MODULE
+        Rule
    
 
         
    
-
    module X {
+
    +rule CALLER_MODULE ( levels ? )
+
    
+        
    
+        CALLER_MODULE returns the name of the module scope enclosing
+        the call to its caller (if levels is supplied, it is interpreted as
+        an integer number of additional levels of call stack to traverse to
+        locate the module). If the scope belongs to the global module, or if
+        no such module exists, returns the empty list. For example, the
+        following prints "{Y} {X}": 
+
+        
    
+
    +module X {
     rule get-caller { return [ CALLER_MODULE ] ; }
     rule get-caller's-caller { return [ CALLER_MODULE 1 ] ; }
 
@@ -1687,106 +1863,114 @@ ECHO {$(callers)} ;
 
 
    
         
    
-
       
    
 
       
    Local For Loop Variables
    
 
       
    Boost Jam allows you to declare a local for loop control
-      variable right in the loop:
-
    x = 1 2 3 ;
+      variable right in the loop:
    
+
+      
    
+
    +x = 1 2 3 ;
 y = 4 5 6 ;
 for local y in $(x)
 {
-    ECHO $(y) ; # prints "1", "2", or "3"
+    ECHO $(y) ; # prints "1", "2", or "3"
 }
-ECHO $(y) ;     # prints "4 5 6"
-
    
+ECHO $(y) ;     # prints "4 5 6"
+
    
+      
    
 
       
    Negative Indexing
    
-      
       Classic Jam supplies 1-based list indexing, and slicing on a closed
-      (inclusive) range:
-
    x = 1 2 3 4 5 ;
-ECHO $(x[3]) ;   # prints "3"
-ECHO $(x[2-4]) ; # prints "2 3 4"
-ECHO $(x[2-]) ;  # prints "2 3 4 5"
-
    
+      (inclusive) range: 
 
-      Boost Jam adds Python-style negative indexing to access locations relative
-      to the end of the list.
+      
    
+
    +x = 1 2 3 4 5 ;
+ECHO $(x[3]) ;   # prints "3"
+ECHO $(x[2-4]) ; # prints "2 3 4"
+ECHO $(x[2-]) ;  # prints "2 3 4 5"
+
    
+      
    
+      Boost Jam adds Python-style negative indexing to access locations
+      relative to the end of the list. 
 
-
    ECHO $(x[-1]) $(x[-3]) ; # prints "5 3"
-ECHO $(x[-3--1]) ;       # prints "3 4 5"
-ECHO $(x[-3-4]) ;        # prints "3 4"
-ECHO $(x[2--2]) ;        # prints "2 3 4"       
-
    
-
-      Consistency with the 1-based, inclusive
-      indexing of Classic Jam and the use of ``-'' as the
-      range separator make this feature a bit clumsier than it would otherwise
-      need to be, but it does work.
+      
    
+
    +ECHO $(x[-1]) $(x[-3]) ; # prints "5 3"
+ECHO $(x[-3--1]) ;       # prints "3 4 5"
+ECHO $(x[-3-4]) ;        # prints "3 4"
+ECHO $(x[2--2]) ;        # prints "2 3 4"       
+
    
+      
    
+      Consistency with the 1-based, inclusive indexing of Classic Jam and the
+      use of ``-'' as the range separator make this feature a bit
+      clumsier than it would otherwise need to be, but it does work. 
 
       
    Target Binding Detection
    
 
-      
    Whenever a target is bound to a location in the
-      filesystem, Boost Jam will look for a variable called BINDRULE (first
-      ``on'' the target being bound, then in the global module). If
-      non-empty, $(BINDRULE[1]) names a rule which is called with the
-      name of the target and the path it is being bound to. The signature of the
-      rule named by $(BINDRULE[1]) should match the following:
-
-
    rule bind-rule ( target : path )
-
    
+      
    Whenever a target is bound to a location in
+      the filesystem, Boost Jam will look for a variable called
+      BINDRULE (first ``on'' the target being bound, then
+      in the global module). If non-empty, $(BINDRULE[1]) names a
+      rule which is called with the name of the target and the path it is
+      being bound to. The signature of the rule named by
+      $(BINDRULE[1]) should match the following:
    
 
+      
    
+
    +rule bind-rule ( target : path )
+
    
+      
    
       This facility is useful for correct header file scanning, since many
-      compilers will search for #included files first in the directory
-      containing the file doing the #include
-      directive. $(BINDRULE) can be used to make a record of that
-      directory.
-      
+      compilers will search for #included files first in the
+      directory containing the file doing the #include directive.
+      $(BINDRULE) can be used to make a record of that directory. 
+
       
    Return Code Inversion
    
 
-      
    For handling targets whose build actions are expected to fail
-      (e.g. when testing that assertions or compile-time type checkin work
+      
    For handling targets whose build actions are expected to fail (e.g.
+      when testing that assertions or compile-time type checkin work
       properly), Boost Jam supplies a FAIL_EXPECTED rule in the same
-      style as NOCARE, et. al. During target updating, the return code
-      of the build actions for arguments to FAIL_EXPECTED is inverted:
-      if it fails, building of dependent targets continues as though it
-      succeeded. If it succeeds, dependent targets are skipped.
+      style as NOCARE, et. al. During target updating, the return
+      code of the build actions for arguments to FAIL_EXPECTED is
+      inverted: if it fails, building of dependent targets continues as
+      though it succeeded. If it succeeds, dependent targets are skipped.
    
 
       
    Ignoring Return Codes
    
 
-      
-    
    Perforce Jam supplied a NOCARE rule which is typically used for 
-        header files to indicate that if they are not found, the dependent targets 
-        should be built anyway. Boost Jam extends NOCARE to apply to 
-        targets with build actions: if their build actions exit with a nonzero 
-        return code, dependent targets will still be built. 
+      
    Perforce Jam supplied a NOCARE rule which is typically used
+      for header files to indicate that if they are not found, the dependent
+      targets should be built anyway. Boost Jam extends NOCARE to
+      apply to targets with build actions: if their build actions exit with a
+      nonzero return code, dependent targets will still be built.
    
 
       
    Removing Outdated Targets
    
-
    
-
    rule RMOLD ( targets * )
+
+      
    
+
    +rule RMOLD ( targets * )
 
    
-
    
+      
    
 
-      
    Perforce Jam removes any target files that may exist on disk
-      when the rule used to build those targets fails. However,
-      targets whose dependencies fail to build are not removed by
-      default. The RMOLD rule causes its arguments to be
-      removed if any of their dependencies fail to build.
+      
    Perforce Jam removes any target files that may exist on disk when
+      the rule used to build those targets fails. However, targets whose
+      dependencies fail to build are not removed by default. The
+      RMOLD rule causes its arguments to be removed if any of
+      their dependencies fail to build.
    
 
-      
-    
    The SUBST Rule
    
+      
    The SUBST Rule
    
 
-    
    Note: the SUBST rule is deprecated in favor
-    of Perforce Jam's built-in MATCH rule, which has been
-    rolled into Boost.Jam.
+      
    Note: the SUBST rule is deprecated in favor of
+      Perforce Jam's built-in MATCH rule, which has been rolled
+      into Boost.Jam.
    
 
-      
    The behavior of the SUBST rule for regular-expression matching
-      and replacement (originally added in The behavior of the SUBST rule for regular-expression
+      matching and replacement (originally added in FTJam) has been
-      modified:
+      modified:
    
 
       
      
         
    • 
@@ -1794,238 +1978,250 @@ ECHO $(x[2--2]) ;        # prints "2 3 4"
           for SUBST is: 
 
           
      
-
      SUBST ( source pattern replacements + )
+
      +SUBST ( source pattern replacements + )
 
      
           
      
-          The return value is the concatenated results of applying each element
-          of replacements in turn. For example, the following will
-          print ``[x] (y) {z}'': 
+          The return value is the concatenated results of applying each
+          element of replacements in turn. For example, the
+          following will print ``[x] (y) {z}'': 
 
           
      
-
      ECHO [ SUBST xyz (.)(.)(.) [$1] ($2) {$3} ] ;
+
      +ECHO [ SUBST xyz (.)(.)(.) [$1] ($2) {$3} ] ;
 
      
           
      
+        
      • 
 
-        
    • 
-          If there is no match, SUBST now returns an empty list. In
-          FTJam, the original source string was returned, making it
-          awkward to check whether a pattern was matched. 
-
-          
      
+        
    • If there is no match, SUBST now returns an empty list.
+        In FTJam, the original source string was returned, making it
+        awkward to check whether a pattern was matched.
      • 
 
         
    • Compiled regular expressions are now internally cached, making it
-        much faster to use SUBST multiple times with the same string.
+        much faster to use SUBST multiple times with the same
+        string.
      • 
       
    
 
-    
    The JAM_VERSION global variable
    
+      
    The JAM_VERSION global
+      variable
    
 
-    
    A predefined global variable with two elements indicates the version
-    number of Boost Jam. Boost Jam versions start at "03" "00". Earlier
-    versions of Jam do not automatically define JAM_VERSION.
+      
    A predefined global variable with two elements indicates the version
+      number of Boost Jam. Boost Jam versions start at "03" "00".
+      Earlier versions of Jam do not automatically define
+      JAM_VERSION.
    
 
+      
    Debugging Support
    
 
-    
    Debugging Support
    
+      
    The BACKTRACE rule
    
 
-    
    The BACKTRACE rule
    
+      
    
+
    +rule BACKTRACE ( )
+
    
+      
    
+      Returns a list of quadruples: filename line module rulename...,
+      describing each shallower level of the call stack. This rule can be
+      used to generate useful diagnostic messages from Jam rules. 
 
-
    rule BACKTRACE ( )
-
    
+      
    The -d command-line option admits new arguments:
    
 
-        Returns a list of quadruples: filename line module
-        rulename..., describing each shallower level of the call
-        stack. This rule can be used to generate useful diagnostic
-        messages from Jam rules.
+      
      
+        
    • -d+10 - enables profiling
+        of rule invocations. When Jam exits, it dumps all rules invoked,
+        their gross and net times in platform-dependent units, and the number
+        of times the rule was invoked.
      • 
 
-    
      The -d command-line option admits new arguments:
-
-    
        
-         
      •  -d+10 - enables profiling of rule
-         invocations. When Jam exits, it dumps all rules invoked, their gross
-         and net times in platform-dependent units, and the number of times the
-         rule was invoked.
-
-         
      •  -d+11 - enables parser
-        debugging, if Jam has been compiled with the "--debug"
-        option to the parser generator named by $(YACC).
-
-         
      •  -d+12 - enables dependency graph output
-        . This feature was ``stolen'' from a version of Jam
-        modified by Craig
-        McPheeters.
-
-    
      
+        
    • -d+11 - enables parser
+        debugging, if Jam has been compiled with the "--debug" option
+        to the parser generator named by $(YACC).
      • 
 
+        
    • -d+12 - enables dependency
+        graph output . This feature was ``stolen'' from a version of
+        Jam modified by Craig
+        McPheeters.
      • 
+      
    
     
    
 
     
    Target Names
    
 
     
    In addition to user targets, which
-    correspond directly to the names the user writes in her subproject Jamfile,
-    several additional targets are generated, regardless of the directory from
-    which Jam was invoked:
+    correspond directly to the names the user writes in her subproject
+    Jamfile, several additional targets are generated, regardless of the
+    directory from which Jam was invoked:
    
 
     
      
       
    • A main target has all the same dependencies as a user target
       (i.e. building it updates all requested subvariants). Its name is the
       same except for the addition of $(SOURCE_GRIST), which
-      identifies the subproject. The identification looks like the names of the
-      path components from the project root to the subproject, separated by
-      exclamation points. Thus, if the project is rooted at foo, in
-      the subproject at foo/bar/baz the target my_target is
-      identified by <bar!baz>my_target.
+      identifies the subproject. The identification looks like the names of
+      the path components from the project root to the subproject, separated
+      by exclamation points. Thus, if the project is rooted at foo,
+      in the subproject at foo/bar/baz the target my_target
+      is identified by <bar!baz>my_target.
      • 
 
-      
-    
    • A subvariant target has additional grist identifying its main target 
-        and subvariant. This grist is joined to $(SOURCE_GRIST) with 
-        the platform's directory separator. Thus, on UNIX, a subvariant target 
-        of my_target above might be identified as
-        <bar!baz/my_target/optimization-space/runtime-link-static>my_source.o. 
-        Note that the part of the grist following the first slash, known as the 
-        subvariant id, also corresponds to a fragment of the subvariant 
-        directory path where the corresponding target is generated. Most built 
-        targets will be identified this way. 
-
    
+      
  • A subvariant target has additional grist identifying its
+      main target and subvariant. This grist is joined to
+      $(SOURCE_GRIST) with the platform's directory separator. Thus,
+      on UNIX, a subvariant target of my_target above might be
+      identified as
+      <bar!baz/my_target/optimization-space/runtime-link-static>my_source.o.
+      Note that the part of the grist following the first slash, known as the
+      subvariant id, also corresponds to a fragment of the subvariant
+      directory path where the corresponding target is generated. Most built
+      targets will be identified this way.
    • 
+    
 
     
    Global Variables
    
 
     
    This section describes some of the global variables used by the build
     system. Please note that some parts of the system (particularly those in
     allyourbase.jam) are heavily based on the Jambase file supplied
-    with Jam, and as such do not follow the conventions described below.
+    with Jam, and as such do not follow the conventions described below.
    
 
-    
    Global variables used in the build system fall into three categories:
+    
    Global variables used in the build system fall into three
+    categories:
    
 
     
      
-    
    •  Global variables intended to
-    be set by the user on the command-line or in the environment use
-    ALL_UPPER_CASE names.
+      
    • Global variables intended to be set by the user on the command-line
+      or in the environment use ALL_UPPER_CASE names.
      • 
 
-    
    •  Internal global variables begin with a lower-case "g" and
-    continue in upper-case: gSOME_GLOBAL
+      
    • Internal global variables begin with a lower-case "g" and continue
+      in upper-case: gSOME_GLOBAL
      • 
 
-    
    •  Global variables of the form:
-    gBASE_NAME(arguments), where arguments is a
-    comma-separated argument list, are used internally to achieve a kind of
-    indirection by concatenating variable values:
-    
-
          ECHO $(gFUBAR($(x),$(y))) ;
+      
    • 
+        Global variables of the form:
+        gBASE_NAME(arguments), where
+        arguments is a comma-separated argument list, are used
+        internally to achieve a kind of indirection by concatenating variable
+        values: 
+
+        
      
+
      +    ECHO $(gFUBAR($(x),$(y))) ;
 
      
         
      
+      
      • 
     
    
 
-    
    Please note that the build system commonly takes advantage of Jam's
-    Dynamic Scoping feature (see the local command in the
-    "Flow of Control" section below the link target) to temporarily
-    "change" a global variable by declaring a local of the
-    same name.
+    
    Please note that the build system commonly takes advantage of Jam's
+    Dynamic Scoping feature (see the local command in the "Flow
+    of Control" section below the link target) to temporarily "change" a
+    global variable by declaring a local of the same name.
    
 
     
    Many of the variables that are used to configure how Boost.Build works
-    internally are listed here with brief descriptions.
+    internally are listed here with brief
+    descriptions.
    
 
     
    Variables Associated with SubProject Identity
    
 
     
      
-      
    • SUBDIR_TOKENS - a list of the path elements relative to the
-      project root of the current subproject.
+      
    • SUBDIR_TOKENS - a list of the path elements relative to
+      the project root of the current subproject.
      • 
 
       
    • SUBDIR - the path from the invocation directory to the
-      current subproject directory.
+      current subproject directory.
      • 
     
    
 
     
    Grist Variables
    
 
     
      
       
    • TARGET_GRIST takes the form
-      subproject!id/target/toolset/variant/subvariant-path.
+      subproject!id/target/toolset/variant/subvariant-path.
      • 
     
    
 
     
    Design Criteria
    
 
     
    Assumptions
    
 
-    
    The requirements are driven by several basic assumptions:
+    
    The requirements are driven by several basic assumptions:
    
 
     
      
-      
    • There is no single Boost developer or test facility with access to or
-      knowledge of all the platforms and compilers Boost libraries are used
-      with.
+      
    • There is no single Boost developer or test facility with access to
+      or knowledge of all the platforms and compilers Boost libraries are
+      used with.
      • 
 
       
    • Boost libraries are used across such a wide range of platforms and
-      compilers that almost no other assumptions can be made.
+      compilers that almost no other assumptions can be made.
      • 
     
    
 
     
    Requirements
    
 
-    
    This build system was designed to satisfy the following requirements:
+    
    This build system was designed to satisfy the following
+    requirements:
    
 
     
      
       
    • A developer adding a new library or test program must only have to
       add simple entries naming the source files to a text file, and not have
-      to know anything about platform specific files. The developer should not
-      have to supply header dependency information.
+      to know anything about platform specific files. The developer should
+      not have to supply header dependency information.
      • 
 
       
    • There should be a very high likelihood of builds succeeding on all
       platforms if a build succeeds on any platform. In other words, a
       developer must not be required to have access to many platforms or
-      compilers to ensure correct builds
+      compilers to ensure correct builds
      • 
 
       
    • A user or developer adding support for a new platform or compiler
       should only have to add to a single file describing how to do the build
       for that platform or compiler, and shouldn't have to identify the files
-      that will need to be built.
+      that will need to be built.
      • 
 
       
    • The build should rely only on tools native to the platform and
-      compiler, or supplied via the boost download.
+      compiler, or supplied via the boost download.
      • 
 
       
    • The details of how the build is done for a particular platform or
-      compiler should be appropriate for that platform.
+      compiler should be appropriate for that platform.
      • 
 
-      
    • It should be possible to build multiple variants (e.g. debug/release)
-      of a single target.
+      
    • It should be possible to build multiple variants (e.g.
+      debug/release) of a single target.
      • 
 
-      
    • It should be possible to build multiple variants of multiple targets
-      with multiple compilers from a single build command.
+      
    • It should be possible to build multiple variants of multiple
+      targets with multiple compilers from a single build command.
      • 
 
       
    • The build tools must be able to handle Boost growth issues such as
-      identified in Directory Structure proposals and discussion.
+      identified in Directory Structure proposals and discussion.
      • 
 
-      
    • Support for dynamic and static linking should be included.
+      
    • Support for dynamic and static linking should be included.
      • 
 
       
    • It should be relatively straightforward to add support for a new
       compiler. In most cases, no modification of files used to describe
-      existing targets should be required.
+      existing targets should be required.
      • 
 
       
    • Support for compiler- and variant-specific configuration for each
-      target
+      target
      • 
 
-      
    • It should be possible to build targets into a directory unrelated to
-      the source directories (they may be read-only)
+      
    • It should be possible to build targets into a directory unrelated
+      to the source directories (they may be read-only)
      • 
     
    
 
-    
    Footnotes
     
-[1] Boost Jam is actually descended directly from FTJam, which was 
-itself a variant of Jam/MR. It is hoped that crucial 
-features we rely on will eventually be incorporated back into the Jam/MR release. 
+    
    Footnotes
    
+    [1] Boost Jam is actually descended directly from FTJam, which
+    was itself a variant of Jam/MR. It is hoped that
+    crucial features we rely on will eventually be incorporated back into the
+    Jam/MR release. 
 
-
    [2] Note: right now, a dependency feature of a main
+    
    [2] Note: right now, a dependency feature of a main
     target makes all resulting built targets dependent, including
     intermediate targets. That means that if an executable is dependent on an
-    external library, and that library changes, all the sources comprising the
-    executable will be recompiled as well. This behavior should probably be
-    fixed.
+    external library, and that library changes, all the sources comprising
+    the executable will be recompiled as well. This behavior should probably
+    be fixed.
    
     
    
 
     
    © Copyright David Abrahams 2001. Permission to copy, use, modify,
-    sell and distribute this document is granted provided this copyright notice
-    appears in all copies. This document is provided "as is" without express or
-    implied warranty, and with no claim as to its suitability for any purpose.
+    sell and distribute this document is granted provided this copyright
+    notice appears in all copies. This document is provided "as is" without
+    express or implied warranty, and with no claim as to its suitability for
+    any purpose.
    
 
     
    Revised 
     24 May, 2002
-
\ No newline at end of file
+                                -->24 May, 2002 
+    
+    
    
+  
+
+