|  | Home | Libraries | People | FAQ | More | 
      B2 has an interpreted, procedural language. Statements in
      b2 are rule (procedure) definitions, rule invocations, flow-of-control
      structures, variable assignments, and sundry language support.
    
        B2 treats its input files as whitespace-separated tokens,
        with two exceptions: double quotes (") can enclose whitespace to embed
        it into a token, and everything between the matching curly braces ({}) in
        the definition of a rule action is treated as a single string. A backslash
        (\) can escape a double quote, or any single whitespace character.
      
        B2 requires whitespace (blanks, tabs, or newlines) to
        surround all tokens, including the colon (:) and semicolon (;) tokens.
      
        B2 keywords (an mentioned in this document) are reserved
        and generally must be quoted with double quotes (") to be used as arbitrary
        tokens, such as variable or target names.
      
        Comments start with the # character and extend until the
        end of line. And block comments start with #| and extend
        until the next |#.
      
        The essential b2 data entity is a target. Build targets
        are files to be updated. Source targets are the files used in updating built
        targets. Built targets and source targets are collectively referred to as
        file targets, and frequently built targets are source targets for other built
        targets. Pseudotargets are symbols representing dependencies on other targets,
        but which are not themselves associated with any real file.
      
        A file target's identifier is generally the file's name, which can be absolutely
        rooted, relative to the directory of b2's invocation,
        or simply local (no directory). Most often it is the last case, and the actual
        file path is bound using the $(SEARCH) and $(LOCATE)
        special variables. See SEARCH
        and LOCATE Variables below. A local filename is optionally qualified
        with grist, a string value used to assure uniqueness. A file target with
        an identifier of the form file(member) is a library
        member (usually an ar(1) archive on Unix).
      
          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 #include
          files first in the directory containing the file doing the #include directive. $(BINDRULE)
          can be used to make a record of that directory.
        
        The basic b2 language entity is called a rule. A rule
        is defined in two parts: the procedure and the actions. The procedure is
        a body of jam statements to be run when the rule is invoked; the actions
        are the OS shell commands to execute when updating the built targets of the
        rule.
      
Rules can return values, which can be expanded into a list with "[ rule args ... ]". A rule's value is the value of its last statement, though only the following statements have values: 'if' (value of the leg chosen), 'switch' (value of the case chosen), set (value of the resulting variable), and 'return' (value of its arguments).
        The b2 statements for defining and invoking rules are
        as follows:
      
Define a rule's procedure, replacing any previous definition.
rule rulename { statements }
Define a rule's updating actions, replacing any previous definition.
actions [ modifiers ] rulename { commands }
Invoke a rule.
rulename field1 : field2 : ... : fieldN ;
Invoke a rule under the influence of target's specific variables..
on target rulename field1 : field2 : ... : fieldN ;
Used as an argument, expands to the return value of the rule invoked.
[ rulename field1 : field2 : ... : fieldN ] [ on target rulename field1 : field2 : ... : fieldN ]
        A rule is invoked with values in field1 through fieldN.
        They may be referenced in the procedure's statements as $(1)
        through $(N) (9 max), and the first
        two only may be referenced in the action's commands
        as $(1) and $(2). $(<)
        and $(>) are synonymous with $(1)
        and $(2).
      
        Rules fall into two categories: updating rules (with actions), and pure procedure
        rules (without actions). Updating rules treat arguments $(1)
        and $(2) as built targets and sources, respectively, while
        pure procedure rules can take arbitrary arguments.
      
        When an updating rule is invoked, its updating actions are added to those
        associated with its built targets ($(1)) before the rule's
        procedure is run. Later, to build the targets in the updating phase, commands
        are passed to the OS command shell, with $(1) and $(2)
        replaced by bound versions of the target names. See Binding above.
      
Rule invocation may be indirected through a variable:
$(var) field1 : field2 : ... : fieldN ; on target $(var) field1 : field2 : ... : fieldN ; [ $(var) field1 : field2 : ... : fieldN ] [ on target $(var) field1 : field2 : ... : fieldN ]
        The variable's value names the rule (or rules) to be invoked. A rule is invoked
        for each element in the list of $(var)'s
        values. The fields field1 : field2
        : ... are passed as arguments for each invocation.
        For the [ ... ] forms, the return value is the concatenation of the return
        values for all of the invocations.
      
The following action modifiers are understood:
actions bind vars
                $(vars) will be replaced
                with bound values.
              
actions existing
                $(>) includes only source targets currently
                existing.
              
actions ignoreThe return status of the commands is ignored.
actions piecemeal
                commands are repeatedly invoked with a subset of $(>)
                small enough to fit in the command buffer on this OS.
              
actions quietlyThe action is not echoed to the standard output.
actions together
                The $(>) from multiple invocations of the same
                action on the same built target are glommed together.
              
actions updated
                $(>) includes only source targets themselves
                marked for updating.
              
You can 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:
rule report ( pronoun index ? : state : names + )
{
    local he.suffix she.suffix it.suffix = s ;
    local I.suffix = m ;
    local they.suffix you.suffix = re ;
    ECHO $(pronoun)'$($(pronoun).suffix) $(state), $(names[$(index)]) ;
}
report I 2 : sorry : Joe Dave Pete ;
          Each name in a list of formal arguments (separated by ":"
          in the rule declaration) is bound to a single element of the corresponding
          actual argument unless followed by one of these modifiers:
        
| Symbol | Semantics of preceding symbol | 
|---|---|
| 
                     | optional | 
| 
                     | 
                    Bind to zero or more unbound elements of the actual argument.
                    When  | 
| 
                     | Bind to one or more unbound elements of the actual argument. | 
          The actual and formal arguments are checked for inconsistencies, which
          cause b2 to exit with an error code:
        
### argument error # rule report ( pronoun index ? : state : names + ) # called with: ( I 2 foo : sorry : Joe Dave Pete ) # extra argument foo ### argument error # rule report ( pronoun index ? : state : names + ) # called with: ( I 2 : sorry ) # missing argument names
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.
          B2 has a growing set of built-in rules, all of which
          are pure procedure rules without updating actions. They are in three groups:
          the first builds the dependency graph; the second modifies it; and the
          third are just utility rules.
        
rule DEPENDS ( targets1 * : targets2 * )
Builds a direct dependency: makes each of targets1 depend on each of targets2. Generally, targets1 will be rebuilt if targets2 are themselves rebuilt or are newer than targets1.
rule INCLUDES ( targets1 * : targets2 * )
Builds a sibling dependency: makes any target that depends on any of targets1 also depend on each of targets2. This reflects the dependencies that arise when one source file includes another: the object built from the source file depends both on the original and included source file, but the two sources files don't depend on each other. For example:
DEPENDS foo.o : foo.c ; INCLUDES foo.c : foo.h ;
              "foo.o" depends on "foo.c"
              and "foo.h" in this example.
            
            The six rules ALWAYS, LEAVES,
            NOCARE, NOTFILE, NOUPDATE,
            and TEMPORARY modify the dependency graph so that
            b2 treats the targets differently during its target
            binding phase. See Binding above. Normally, b2 updates
            a target if it is missing, if its filesystem modification time is older
            than any of its dependencies (recursively), or if any of its dependencies
            are being updated. This basic behavior can be changed by invoking the
            following rules:
          
rule ALWAYS ( targets * )
              Causes targets to be rebuilt regardless of whether
              they are up-to-date (they must still be in the dependency graph). This
              is used for the clean and uninstall targets, as they have no dependencies
              and would otherwise appear never to need building. It is best applied
              to targets that are also NOTFILE targets, but it
              can also be used to force a real file to be updated as well.
            
rule LEAVES ( targets * )
Makes each of targets depend only on its leaf sources, and not on any intermediate targets. This makes it immune to its dependencies being updated, as the "leaf" dependencies are those without their own dependencies and without updating actions. This allows a target to be updated only if original source files change.
rule NOCARE ( targets * )
              Causes b2 to ignore targets
              that neither can be found nor have updating actions to build them.
              Normally for such targets b2 issues a warning and
              then skips other targets that depend on these missing targets. The
              HdrRule in Jambase uses NOCARE
              on the header file names found during header file scanning, to let
              b2 know that the included files may not exist. For
              example, if an #include
              is within an #ifdef,
              the included file may not actually be around.
            
| ![[Warning]](../../../doc/src/images/warning.png) | Warning | 
|---|---|
| For targets with build actions: if their build actions exit with a nonzero return code, dependent targets will still be built. | 
rule NOTFILE ( targets * )
              Marks targets as pseudotargets and not real files.
              No timestamp is checked, and so the actions on such a target are only
              executed if the target's dependencies are updated, or if the target
              is also marked with ALWAYS. The default b2
              target "all" is a pseudotarget. In Jambase,
              NOTFILE is used to define several addition convenient
              pseudotargets.
            
rule NOUPDATE ( targets * )
              Causes the timestamps on targets to be ignored.
              This has two effects: first, once the target has been created it will
              never be updated; second, manually updating target will not cause other
              targets to be updated. In Jambase, for example,
              this rule is applied to directories by the MkDir
              rule, because MkDir only cares that the target directory
              exists, not when it has last been updated.
            
rule TEMPORARY ( targets * )
              Marks targets as temporary, allowing them to be
              removed after other targets that depend upon them have been updated.
              If a TEMPORARY target is missing, b2
              uses the timestamp of the target's parent. Jambase
              uses TEMPORARY to mark object files that are archived
              in a library after they are built, so that they can be deleted after
              they are archived.
            
rule FAIL_EXPECTED ( targets * )
              For handling targets whose build actions are expected to fail (e.g.
              when testing that assertions or compile-time type checking work properly),
              Boost Jam supplies the 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.
            
rule RMOLD ( targets * )
              B2 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.
            
rule ISFILE ( targets * )
              ISFILE marks targets as required to be files. This
              changes the way b2 searches for the target such
              that it ignores matches for file system items that are not files, like
              directories. This makes it possible to avoid #include
              "exception" matching
              if one happens to have a directory named exception in the header search
              path.
            
| ![[Warning]](../../../doc/src/images/warning.png) | Warning | 
|---|---|
| This is currently not fully implemented. | 
            The two rules ECHO and EXIT are
            utility rules, used only in b2's parsing phase.
          
rule EXIT ( message * : result-value ? )
Blurts out the message to stdout and then exits with a failure status if no result-value is given, otherwise it exits with the given result-value.
              "Echo", "echo",
              "Exit", and "exit"
              are accepted as aliases for ECHO and EXIT,
              since it is hard to tell that these are built-in rules and not part
              of the language, like "include".
            
              The GLOB rule does filename globbing.
            
rule GLOB ( directories * : patterns * : downcase-opt ? )
              Using the same wildcards as for the patterns in the switch statement.
              It is invoked by being used as an argument to a rule invocation inside
              of "=[ ]=". For example: "FILES = [ GLOB dir1
              dir2 : *.c *.h ]" sets FILES to the
              list of C source and header files in dir1 and dir2.
              The resulting filenames are the full pathnames, including the directory,
              but the pattern is applied only to the file name without the directory.
            
If downcase-opt is supplied, filenames are converted to all-lowercase before matching against the pattern; you can use this to do case-insensitive matching using lowercase patterns. The paths returned will still have mixed case if the OS supplies them. On Windows NT and Cygwin, and OpenVMS, filenames are always downcased before matching.
              The GLOB_ARCHIVE rule does name globbing of object
              archive members.
            
rule GLOB_ARCHIVE ( archives * : member-patterns * : downcase-opt ? : symbol-patterns ? )
              Similarly to GLOB, this rule is used to match names
              of member files in an archive (static object library). List of successfully
              matched members is returned or null otherwise. The resulting member
              names are qualified with pathname of the containing archive in the
              form archive-path(member-name). Member patterns
              are for matching member name only; when no wildcards specified -- an
              exact match is assumed. Member names generally correspond to object
              file names and as such are platform-specific -- use of platform-defined
              object suffix in the matching patterns can allow for portability.
            
If downcase-opt is supplied, the member names are converted to all-lowercase before matching against the pattern; you can use this to do case-insensitive matching using lowercase patterns. The paths returned will still have mixed case if the OS supplies them. On Windows NT, Cygwin, and OpenVMS, filenames are always downcased before matching.
Additionally, members can be matched with symbol/function patterns on supported platforms (currently, OpenVMS only). In this case, members containing the matching symbols are returned. Member and symbol patterns are applied as OR conditions, with member patterns taking precedence. On unsupported platforms, null is returned when any symbol patterns are specified.
              The MATCH rule does pattern matching.
            
rule MATCH ( regexps + : list * )
              Matches the egrep(1) style regular expressions
              regexps against the strings in list.
              The result is a list of matching () subexpressions
              for each string in list, and for each regular
              expression in regexps.
            
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 UPDATE ( targets * )
              Classic jam treats any non-option element of command line as a name
              of target to be updated. This prevented more sophisticated handling
              of command line. This is now enabled again but with additional changes
              to the UPDATE rule to allow for the flexibility
              of changing the list of targets to update. The UPDATE rule has two
              effects:
            
              If no target was specified with the UPDATE rule,
              no targets will be updated. To support changing of the update list
              in more useful ways, the rule also returns the targets previously in
              the update list. This makes it possible to add targets as such:
            
local previous-updates = [ UPDATE ] ; UPDATE $(previous-updates) a-new-target ;
rule W32_GETREG ( path : data ? )
Defined only for win32 platform. It reads the registry of Windows. 'path' is the location of the information, and 'data' is the name of the value which we want to get. If 'data' is omitted, the default value of 'path' will be returned. The 'path' value must conform to MS key path format and must be prefixed with one of the predefined root keys. As usual,
HKLM' is equivalent to 'HKEY_LOCAL_MACHINE'.
                HKCU' is equivalent to 'HKEY_CURRENT_USER'.
                HKCR' is equivalent to 'HKEY_CLASSES_ROOT'.
                Other predefined root keys are not supported.
              Currently supported data types : 'REG_DWORD', 'REG_SZ',
              'REG_EXPAND_SZ', 'REG_MULTI_SZ'.
              The data with 'REG_DWORD' type will be turned into
              a string, 'REG_MULTI_SZ' into a list of strings,
              and for those with 'REG_EXPAND_SZ' type environment
              variables in it will be replaced with their defined values. The data
              with 'REG_SZ' type and other unsupported types will
              be put into a string without modification. If it can't receive the
              value of the data, it just return an empty list. For example,
            
local PSDK-location = [ W32_GETREG HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\MicrosoftSDK\\Directories : "Install Dir" ] ;
rule W32_GETREGNAMES ( path : result-type )
              Defined only for win32 platform. It reads the registry of Windows.
              'path' is the location of the information, and
              'result-type' is either 'subkeys'
              or 'values'. For more information on 'path'
              format and constraints, please see W32_GETREG.
            
Depending on 'result-type', the rule returns one of the following:
subkeysNames of all direct subkeys of 'path'.
valuesNames of values contained in registry key given by 'path'. The "default" value of the key appears in the returned list only if its value has been set in the registry.
If 'result-type' is not recognized, or requested data cannot be retrieved, the rule returns an empty list. Example:
local key = "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths" ;
local subkeys = [ W32_GETREGNAMES "$(key)" : subkeys ] ;
for local subkey in $(subkeys)
{
    local values = [ W32_GETREGNAMES "$(key)\\$(subkey)" : values ] ;
    for local value in $(values)
    {
        local data = [ W32_GETREG "$(key)\\$(subkey)" : "$(value)" ] ;
        ECHO "Registry path: " $(key)\\$(subkey) ":" $(value) "=" $(data) ;
    }
}
rule SHELL ( command : * )
              SHELL executes command, and
              then returns the standard output of command.
              SHELL only works on platforms with a popen()
              function in the C library. On platforms without a working popen()
              function, SHELL is implemented as a no-op. SHELL
              works on Unix, MacOS X, and most Windows compilers. SHELL
              is a no-op on Metrowerks compilers under Windows. There is a variable
              set of allowed options as additional arguments:
            
exit-statusIn addition to the output the result status of the executed command is returned as a second element of the result.
no-outputDon't capture the output of the command. Instead an empty ("") string value is returned in place of the output.
strip-eolRemove trailing end-of-line character from output, if any.
              Because the Perforce/Jambase defines a SHELL rule
              which hides the builtin rule, COMMAND can be used
              as an alias for SHELL in such a case.
            
rule SPLIT_BY_CHARACTERS ( string : delimiters )
              SPLIT_BY_CHARACTERS splits the specified string
              on any delimiter character present in delimiters
              and returns the resulting list.
            
rule PRECIOUS ( targets * )
              The PRECIOUS rule specifies that each of the targets
              passed as the arguments should not be removed even if the command updating
              that target fails.
            
rule PAD ( string : width )
If string is shorter than width characters, pads it with whitespace characters on the right, and returns the result. Otherwise, returns string unmodified.
rule FILE_OPEN ( filename : mode )
              The FILE_OPEN rule opens the specified file and
              returns a file descriptor. The mode parameter
              can be either "w" or "r". Note that at present,
              only the UPDATE_NOW rule can use the resulting file
              descriptor number.
            
rule UPDATE_NOW ( targets * : log ? : ignore-minus-n ? )
              The UPDATE_NOW caused the specified targets to be
              updated immediately. If update was successful, non-empty string is
              returned. The log parameter, if present, specifies
              a descriptor of a file where all output from building is redirected.
              If the ignore-minus-n parameter is specified,
              the targets are updated even if the -n parameter
              is specified on the command line.
            
        B2 has several simple flow-of-control statements:
      
for var in list { statements }
Executes statements for each element in list, setting the variable var to the element value.
if cond { statements } [ else { statements } ]
        Does the obvious; the else clause is optional. cond
        is built of:
      
atrue if any a element is a non-zero-length string
a = blist a matches list b string-for-string
a != blist a does not match list b
a < ba[i] string is less than b[i] string, where i is first mismatched element in lists a and b
a <= bevery a string is less than or equal to its b counterpart
a > ba[i] string is greater than b[i] string, where i is first mismatched element
a >= bevery a string is greater than or equal to its b counterpart
a in btrue if all elements of a can be found in b, or if a has no elements
! condcondition not true
cond && condconjunction
cond || conddisjunction
( cond )precedence grouping
include file ;
        Causes b2 to read the named file.
        The file is bound like a regular target (see Binding
        above) but unlike a regular target the include file
        cannot be built.
      
        The include file is inserted into the input stream during
        the parsing phase. The primary input file and all the included file(s) are
        treated as a single file; that is, b2 infers no scope
        boundaries from included files.
      
local vars [ = values ] ;
        Creates new vars inside to the enclosing {}
        block, obscuring any previous values they might have. The previous values
        for vars are restored when the current block ends. Any rule called or file
        included will see the local and not the previous value (this is sometimes
        called Dynamic Scoping). The local statement may appear anywhere, even outside
        of a block (in which case the previous value is restored when the input ends).
        The vars are initialized to values
        if present, or left uninitialized otherwise.
      
return values ;
Within a rule body, the return statement sets the return value for an invocation of the rule and returns to the caller.
switch value { case pattern1 : statements ; case pattern2 : statements ; ... }
The switch statement executes zero or one of the enclosed statements, depending on which, if any, is the first case whose pattern matches value. The pattern values are not variable-expanded. The pattern values may include the following wildcards:
?match any single character
*match zero or more characters
[chars]match any single character in chars
[^chars]match any single character not in chars
\xmatch x (escapes the other wildcards)
while cond { statements }
Repeatedly execute statements while cond remains true upon entry. (See the description of cond expression syntax under if, above).
break ;
Immediately exits the nearest enclosing while or for loop.
continue ;
Jumps to the top of the nearest enclosing while or for loop.
        B2 variables are lists of zero or more elements, with
        each element being a string value. An undefined variable is indistinguishable
        from a variable with an empty list, however, a defined variable may have
        one more elements which are null strings. All variables are referenced as
        $(variable).
      
Variables are either global or target-specific. In the latter case, the variable takes on the given value only during the updating of the specific target.
A variable is defined with:
variable = elements ; variable += elements ; variable on targets = elements ; variable on targets += elements ; variable default = elements ; variable ?= elements ;
        The first two forms set variable globally. The third
        and forth forms set a target-specific variable. The =
        operator replaces any previous elements of variable
        with elements; the += operation adds
        elements to variable's list of
        elements. The final two forms are synonymous: they set variable
        globally, but only if it was previously unset.
      
        Variables referenced in updating commands will be replaced with their values;
        target-specific values take precedence over global values. Variables passed
        as arguments ($(1) and $(2)) to actions
        are replaced with their bound values; the "bind"
        modifier can be used on actions to cause other variables to be replaced with
        bound values. See Action Modifiers above.
      
        B2 variables are not re-exported to the environment of
        the shell that executes the updating actions, but the updating actions can
        reference b2 variables with $(variable).
      
          During parsing, b2 performs variable expansion on each
          token that is not a keyword or rule name. Such tokens with embedded variable
          references are replaced with zero or more tokens. Variable references are
          of the form $(v) or $(vm),
          where v is the variable name, and m
          are optional modifiers.
        
Variable expansion in a rule's actions is similar to variable expansion in statements, except that the action string is tokenized at whitespace regardless of quoting.
The result of a token after variable expansion is the product of the components of the token, where each component is a literal substring or a list substituting a variable reference. For example:
$(X) -> a b c t$(X) -> ta tb tc $(X)z -> az bz cz $(X)-$(X) -> a-a a-b a-c b-a b-b b-c c-a c-b c-c
The variable name and modifiers can themselves contain a variable reference, and this partakes of the product as well:
$(X) -> a b c $(Y) -> 1 2 $(Z) -> X Y $($(Z)) -> a b c 1 2
Because of this product expansion, if any variable reference in a token is undefined, the result of the expansion is an empty list. If any variable element is a null string, the result propagates the non-null elements:
$(X) -> a "" $(Y) -> "" 1 $(Z) -> -$(X)$(Y)- -> -a- -a1- -- -1- -$(X)$(Z)- ->
A variable element's string value can be parsed into grist and filename-related components. Modifiers to a variable are used to select elements, select components, and replace components. The modifiers are:
[n]Select element number n (starting at 1). If the variable contains fewer than n elements, the result is a zero-element list. n can be negative in which case the element number n from the last leftward is returned.
[n-m]Select elements number n through m. n and m can be negative in which case they refer to elements counting from the last leftward.
[n-]Select elements number n through the last. n can be negative in which case it refers to the element counting from the last leftward.
:BSelect filename base.
:SSelect (last) filename suffix.
:MSelect archive member name.
:DSelect directory path.
:PSelect parent directory.
:GSelect grist.
:UReplace lowercase characters with uppercase.
:LReplace uppercase characters with lowercase.
:TConverts all back-slashes ("\") to forward slashes ("/"). For example
x = "C:\\Program Files\\Borland" ; ECHO $(x:T) ;
                prints "C:/Program Files/Borland"
              
:W
                When invoking Windows-based tools from Cygwin
                it can be important to pass them true windows-style paths. The :W
                modifier, under Cygwin only, turns
                a cygwin path into a Win32 path using the cygwin_conv_to_win32_path
                function. For example
x = "/cygdrive/c/Program Files/Borland" ; ECHO $(x:W) ;
                prints "C:\Program Files\Borland" on
                Cygwin
              
                Similarly, when used on OpenVMS, the :W modifier
                translates a POSIX-style path into native VMS-style format using
                decc$to_vms CRTL function. This modifier is generally
                used inside action blocks to properly specify file paths in VMS-specific
                commands. For example
x = "subdir/filename.c" ; ECHO $(x:W) ;
                prints "[.subdir]filename.c" on OpenVMS
              
On other platforms, the string is unchanged.
:charsSelect the components listed in chars.
:G=gristReplace grist with grist.
:D=pathReplace directory with path.
:B=baseReplace the base part of file name with base.
:S=sufReplace the suffix of file name with suf.
:M=memReplace the archive member name with mem.
:R=rootPrepend root to the whole file name, if not already rooted.
:E=valueAssign value to the variable if it is unset.
:J=joinvalConcatentate list elements into single element, separated by joinval'.
          On VMS, $(var:P) is the parent directory of $(var:D).
        
Boost Jam allows you to declare a local for loop control 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 "4 5 6"
          During expansion of expressions b2 also looks for subexpressions
          of the form @(filename:E=filecontents) and replaces
          the expression with filename after creating the given
          file with the contents set to filecontents. This is
          useful for creating compiler response files, and other "internal"
          files. The expansion works both during parsing and action execution. Hence
          it is possible to create files during any of the three build phases.
        
          This section discusses variables that have special meaning to b2.
          All of these must be defined or used in the global module -- using those
          variables inside a named module will not have the desired effect. See
          Modules.
        
            These two variables control the binding of file target names to locations
            in the file system. Generally, $(SEARCH) is used to
            find existing sources while $(LOCATE) is used to fix
            the location for built targets.
          
            Rooted (absolute path) file targets are bound as is. Unrooted file target
            names are also normally bound as is, and thus relative to the current
            directory, but the settings of $(LOCATE) and $(SEARCH)
            alter this:
          
$(LOCATE) is set then the target is bound relative
                to the first directory in $(LOCATE). Only the
                first element is used for binding.
              $(SEARCH) is set then the target is bound to
                the first directory in $(SEARCH) where the target
                file already exists.
              $(SEARCH) search fails, the target is bound
                relative to the current directory anyhow.
              
            Both $(SEARCH) and $(LOCATE) should
            be set target-specific and not globally. If they were set globally,
            b2 would use the same paths for all file binding,
            which is not likely to produce sane results. When writing your own rules,
            especially ones not built upon those in Jambase, you may need to set
            $(SEARCH) or $(LOCATE) directly.
            Almost all of the rules defined in Jambase set $(SEARCH)
            and $(LOCATE) to sensible values for sources they
            are looking for and targets they create, respectively.
          
            These two variables control header file scanning. $(HDRSCAN)
            is an egrep(1) pattern, with ()'s surrounding the
            file name, used to find file inclusion statements in source files. Jambase
            uses $(HDRPATTERN) as the pattern for $(HDRSCAN).
            $(HDRRULE) is the name of a rule to invoke with the
            results of the scan: the scanned file is the target, the found files
            are the sources. This is the only place where b2 invokes
            a rule through a variable setting.
          
            Both $(HDRSCAN) and $(HDRRULE)
            must be set for header file scanning to take place, and they should be
            set target-specific and not globally. If they were set globally, all
            files, including executables and libraries, would be scanned for header
            file include statements.
          
            The scanning for header file inclusions is not exact, but it is at least
            dynamic, so there is no need to run something like makedepend(GNU)
            to create a static dependency file. The scanning mechanism errs on the
            side of inclusion (i.e., it is more likely to return filenames that are
            not actually used by the compiler than to miss include files) because
            it can't tell if #include
            lines are inside #ifdefs
            or other conditional logic. In Jambase, HdrRule
            applies the NOCARE rule to each header file found
            during scanning so that if the file isn't present yet doesn't cause the
            compilation to fail, b2 won't care.
          
            Also, scanning for regular expressions only works where the included
            file name is literally in the source file. It can't handle languages
            that allow including files using variable names (as the Jam
            language itself does).
          
It is sometimes desirable to disallow parallel execution of some actions. For example:
Craig McPeeters has extended Perforce Jam to solve such problems, and that extension was integrated in Boost.Jam.
            Any target can be assigned a semaphore, by setting
            a variable called SEMAPHORE on that target. The value
            of the variable is the semaphore name. It must be different from names
            of any declared target, but is arbitrary otherwise.
          
            The semantic of semaphores is that in a group of targets which have the
            same semaphore, only one can be updated at the moment, regardless of
            "-j" option.
          
A number of Jam built-in variables can be used to identify runtime platform:
OSOS identifier string
OSPLATUnderlying architecture, when applicable
MACtrue on MAC platform
NTtrue on NT platform
OS2true on OS2 platform
UNIXtrue on Unix platforms
VMStrue on VMS platform
JAMDATE
                  Time and date at b2 start-up as an ISO-8601
                  UTC value.
                
JAMUNAMEOuput of uname(1) command (Unix only)
JAMVERSION
                  b2 version, currently "3.1.19"
                
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.
                
            When b2 executes a rule's action block, it forks and
            execs a shell, passing the action block as an argument to the shell.
            The invocation of the shell can be controlled by $(JAMSHELL).
            The default on Unix is, for example:
          
JAMSHELL = /bin/sh -c % ;
            The % is replaced with the text of the action block.
          
            B2 does not directly support building in parallel
            across multiple hosts, since that is heavily dependent on the local environment.
            To build in parallel across multiple hosts, you need to write your own
            shell that provides access to the multiple hosts. You then reset $(JAMSHELL)
            to reference it.
          
            Just as b2 expands a % to be the
            text of the rule's action block, it expands a ! to
            be the multi-process slot number. The slot number varies between 1 and
            the number of concurrent jobs permitted by the -j
            flag given on the command line. Armed with this, it is possible to write
            a multiple host shell. For example:
          
#!/bin/sh # This sample JAMSHELL uses the SunOS on(1) command to execute a # command string with an identical environment on another host. # Set JAMSHELL = jamshell ! % # # where jamshell is the name of this shell file. # # This version handles up to -j6; after that they get executed # locally. case $1 in 1|4) on winken sh -c "$2";; 2|5) on blinken sh -c "$2";; 3|6) on nod sh -c "$2";; *) eval "$2";; esac
            The __TIMING_RULE__ and __ACTION_RULE__
            can be set to the name of a rule for b2 to call after an action completes for a target. They both
            give diagnostic information about the action that completed. For __TIMING_RULE__
            the rule is called as:
          
rule timing-rule ( args * : target : start end user system )
            And __ACTION_RULE__ is called as:
          
rule action-rule ( args * : target : command status start end user system : output ? )
The arguments for both are:
args
                  Any values following the rule name in the __TIMING_RULE__
                  or __ACTION_RULE__ are passed along here.
                
target
                  The b2 target that was built.
                
commandThe text of the executed command in the action body.
statusThe integer result of the executed command.
startThe starting timestamp of the executed command as a ISO-8601 UTC value.
endThe completion timestamp of the executed command as a ISO-8601 UTC value.
userThe number of user CPU seconds the executed command spent as a floating point value.
systemThe number of system CPU seconds the executed command spent as a floating point value.
output
                  The output of the command as a single string. The content of the
                  output reflects the use of the -pX option.
                
| ![[Note]](../../../doc/src/images/note.png) | Note | 
|---|---|
| 
              If both variables are set for a target both are called, first  | 
        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.
      
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:
        
module my_module { rule salute ( x ) { ECHO $(x), world ; } rule greet ( ) { salute hello ; } greet ; } 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:
module your_module
{
    rule bedtime ( ) { my_module.salute goodnight ; }
}
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 ;
    rule f ( )
    {
        local y = 999 ; # becomes visible again when B.f calls A.g
        B.f ;
    }
    rule g ( )
    {
        ECHO $(y) ;     # prints "999"
    }
}
module B
{
    y = 2 ;
    rule f ( )
    {
        ECHO $(y) ; # always prints "2"
        A.g ;
    }
}
The only way to access another module's variables is by entering that module:
rule peek ( module-name ? : variables + )
{
    module $(module-name)
    {
        return $($(>)) ;
    }
}
          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 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:
[ RULENAMES module-name ]
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.
rule VARNAMES ( module ? )
Returns a list of the names of all variable bindings in the given module. If module is omitted, the names of all variable bindings in the global module are returned.
| ![[Note]](../../../doc/src/images/note.png) | Note | 
|---|---|
| 
            This includes any local variables in rules from the call stack which
            have not returned at the time of the  | 
          IMPORT allows rule name aliasing across modules:
        
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,
        
# 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 IMPORT m1 : [ RULENAMES m1 ] : m2 : [ RULENAMES m1 ] ;
          EXPORT allows rule name aliasing across modules:
        
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,
        
module X {
  local rule r { ECHO X.r ; }
}
IMPORT X : r : : r ; # error - r is local in X
EXPORT X : r ;
IMPORT X : r : : r ; # OK.
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 ] ; }
    rule call-Y { return Y.call-X2 ; }
}
module Y {
    rule call-X { return X.get-caller ; }
    rule call-X2 { return X.get-caller's-caller ; }
}
callers = [ X.get-caller ] [ Y.call-X ] [ X.call-Y ] ;
ECHO {$(callers)} ;
rule DELETE_MODULE ( module ? )
          DELETE_MODULE removes all of the variable bindings and
          otherwise-unreferenced rules from the given module (or the global module,
          if no module is supplied), and returns their memory to the system.
        
| ![[Note]](../../../doc/src/images/note.png) | Note | 
|---|---|
| 
            Though it won't affect rules that are currently executing until they
            complete,  |