Language

Lexical Features
Targets
Rules
Flow-of-Control
Variables
Modules

BJam has an interpreted, procedural language. Statements in bjam are rule (procedure) definitions, rule invocations, flow-of-control structures, variable assignments, and sundry language support.

BJam 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.

BJam requires whitespace (blanks, tabs, or newlines) to surround all tokens, including the colon (:) and semicolon (;) tokens.

BJam 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.

Targets

Binding Detection

The essential bjam 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 which represent 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 bjam'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).

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 )

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.

Rules

Action Modifiers
Argument lists
Built-in Rules

The basic bjam 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). Note that 'return' doesn't actually cause a return, i.e., is a no-op unless it is the last statement of the last block executed within rule body.

The bjam 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 invokation. For the [ ... ] forms, the return value is the concatenation of the return values for all of the invocations.

Action Modifiers

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 ignore: The 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 quietly: The 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.

Argument lists

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 `*` 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.

The actual and formal arguments are checked for inconsistencies, which cause Jam 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.

Built-in Rules

Dependency Building
Modifying Binding
Utility

BJam 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.

Dependency Building

`DEPENDS`

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.

`INCLUDES`

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.

Modifying Binding

The six rules ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, and TEMPORARY modify the dependency graph so that bjam treats the targets differently during its target binding phase. See Binding above. Normally, bjam 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:

`ALWAYS`

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.

`LEAVES`

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.

`NOCARE`

rule NOCARE ( targets * )

Causes bjam to ignore targets that neither can be found nor have updating actions to build them. Normally for such targets bjam 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 bjam 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
	For targets with build actions: if their build actions exit with a nonzero return code, dependent targets will still be built.

`NOTFILE`

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 bjam target "all" is a pseudotarget. In Jambase, NOTFILE is used to define several addition convenient pseudotargets.

`NOUPDATE`

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.

`TEMPORARY`

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, bjam 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.

`FAIL_EXPECTED`

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.

`RMOLD`

rule RMOLD ( targets * )

BJam 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.

`ISFILE`

rule ISFILE ( targets * )

ISFILE marks targets as required to be files. This changes the way bjam searches for the target such that it ignores mathes for file system items that are not file, 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
	This is currently not fully implemented.

Utility

The two rules ECHO and EXIT are utility rules, used only in bjam's parsing phase.

`ECHO`

rule ECHO ( args * )

Blurts out the message args to stdout.

`EXIT`

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".

`GLOB`

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, filenames are always downcased before matching.

`MATCH`

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 the concatenation of matching () subexpressions for each string in list, and for each regular expression in regexps. Only useful within the "[ ]" construct, to change the result into a list.

`BACKTRACE`

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.

`UPDATE`

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:

It clears the list of targets to update, and
Causes the specified targets to be updated.

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 ;

`W32_GETREG`

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" ] ;

`W32_GETREGNAMES`

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:

subkeys: Names of all direct subkeys of 'path'.
values: Names 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) ;
    }
}

`SHELL`

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-status: In addition to the output the result status of the executed command is returned as a second element of the result.
no-output: Don't capture the output of the command. Instead an empty ("") string value is returned in place of the output.

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.

`MD5`

rule MD5 ( string )

MD5 computes the MD5 hash of the string passed as paramater and returns it.

`SPLIT_BY_CHARACTERS`

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.

`PRECIOUS`

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.

`PAD`

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.

`FILE_OPEN`

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.

`UPDATE_NOW`

rule UPDATE_NOW ( targets * : log ? : ignore-minus-n ? )

The UPDATE_NOW caused the specified targets to be updated immediately. If update was successfull, 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.

Flow-of-Control

BJam 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:

a: true if any a element is a non-zero-length string
a = b: list a matches list b string-for-string
a != b: list a does not match list b
a < b: a[i] string is less than b[i] string, where i is first mismatched element in lists a and b
a <= b: every a string is less than or equal to its b counterpart
a > b: a[i] string is greater than b[i] string, where i is first mismatched element
a >= b: every a string is greater than or equal to its b counterpart
a in b: true if all elements of a can be found in b, or if a has no elements
! cond: condition not true
cond && cond: conjunction
cond || cond: disjunction
( cond ): precedence grouping

include file ;

Causes bjam 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, jam 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. It does not cause the rule to return; a rule's value is actually the value of the last statement executed, so a return should be the last statement executed before the rule "naturally" returns.

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
\x: match 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).

Variables

Variable Expansion
Local For Loop Variables
Generated File Expansion
Built-in Variables

BJam 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.

BJam variables are not re-exported to the environment of the shell that executes the updating actions, but the updating actions can reference bjam variables with $(variable).

Variable Expansion

During parsing, bjam 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.

:B

Select filename base.

:S

Select (last) filename suffix.

:M

Select archive member name.

:D

Select directory path.

:P

Select parent directory.

:G

Select grist.

:U

Replace lowercase characters with uppercase.

:L

Replace uppercase characters with lowercase.

:T

Converts 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. On other platforms, the string is unchanged. For example

x = "/cygdrive/c/Program Files/Borland" ; ECHO $(x:W) ;

prints "C:\Program Files\Borland" on Cygwin

:chars

Select the components listed in chars.

:G=grist

Replace grist with grist.

:D=path

Replace directory with path.

:B=base

Replace the base part of file name with base.

:S=suf

Replace the suffix of file name with suf.

:M=mem

Replace the archive member name with mem.

:R=root

Prepend root to the whole file name, if not already rooted.

:E=value

Assign value to the variable if it is unset.

:J=joinval

Concatentate list elements into single element, separated by joinval'.

On VMS, $(var:P) is the parent directory of $(var:D).

Local For Loop Variables

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"

Generated File Expansion

During expansion of expressions bjam also looks for subexpressions of the form =@(filename:Efilecontents) 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.

Built-in Variables

SEARCH and LOCATE
HDRSCAN and HDRRULE
Semaphores
Platform Identifier
Jam Version
JAMSHELL
__TIMING_RULE__ and __ACTION_RULE__

This section discusses variables that have special meaning to bjam. 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.

SEARCH and LOCATE

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:

If $(LOCATE) is set then the target is bound relative to the first directory in $(LOCATE). Only the first element is used for binding.
If $(SEARCH) is set then the target is bound to the first directory in $(SEARCH) where the target file already exists.
If the $(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, bjam 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.

HDRSCAN and HDRRULE

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 bjam 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, bjam 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).

Semaphores

It is sometimes desirable to disallow parallel execution of some actions. For example:

Old versions of yacc use files with fixed names. So, running two yacc actions is dangerous.
One might want to perform parallel compiling, but not do parallel linking, because linking is i/o bound and only gets slower.

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.

Platform Identifier

A number of Jam built-in variables can be used to identify runtime platform:

OS: OS identifier string
OSPLAT: Underlying architecture, when applicable
MAC: true on MAC platform
NT: true on NT platform
OS2: true on OS2 platform
UNIX: true on Unix platforms
VMS: true on VMS platform

Jam Version

JAMDATE: Time and date at bjam start-up as an ISO-8601 UTC value.
JAMUNAME: Ouput of uname(1) command (Unix only)
JAMVERSION: bjam version, currently "3.1.18"
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.

JAMSHELL

When bjam 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.

BJam 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 bjam 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

`__TIMING_RULE` and `ACTION_RULE__`

The __TIMING_RULE__ and __ACTION_RULE__ can be set to the name of a rule for bjam 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 bjam target that was built.
command: The text of the executed command in the action body.
status: The integer result of the executed command.
start: The starting timestamp of the executed command as a ISO-8601 UTC value.
end: The completion timestamp of the executed command as a ISO-8601 UTC value.
user: The number of user CPU seconds the executed command spent as a floating point value.
system: The 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
	If both variables are set for a target both are called, first `__TIMING_RULE__` then `__ACTION_RULE__`.

Modules

Declaration
Variable Scope
Local Rules
The RULENAMES Rule
The VARNAMES Rule
The IMPORT Rule
The EXPORT Rule
The CALLER_MODULE Rule
The DELETE_MODULE Rule

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.

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:

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 ; }
}

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:

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 Rules

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 ]

The `RULENAMES` Rule

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.

The `VARNAMES` Rule

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
	This includes any local variables in rules from the call stack which have not returned at the time of the `VARNAMES` invocation.

The `IMPORT` Rule

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 ] ;

The `EXPORT` Rule

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.

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}":

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)} ;

The `DELETE_MODULE` Rule

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
	Though it won't affect rules that are currently executing until they complete, `DELETE_MODULE` should be used with extreme care because it will wipe out any others and all variable (including locals in that module) immediately. Because of the way dynamic binding works, variables which are shadowed by locals will not be destroyed, so the results can be really unpredictable.