Using BJam

Options
Operation

If target is provided on the command line, bjam builds target; otherwise bjam builds the target all.

bjam ( -option [value] | target ) *

Options

Command-line and Environment Variable Quoting

Options are either singular or have an accompanying value. When a value is allowed, or required, it can be either given as an argument following the option argument, or it can be given immediately after the option as part of the option argument. The allowed options are:

-a: Build all targets anyway, even if they are up-to-date.
-d n: Enable cummulative debugging levels from 1 to n. Values are:
1 - Show the actions taken for building targets, as they are executed (the default).
2 - Show "quiet" actions and display all action text, as they are executed.
3 - Show dependency analysis, and target/source timestamps/paths.
4 - Show arguments and timming of shell invocations.
5 - Show rule invocations and variable expansions.
6 - Show directory/header file/archive scans, and attempts at binding to targets.
7 - Show variable settings.
8 - Show variable fetches, variable expansions, and evaluation of '"if"' expressions.
9 - Show variable manipulation, scanner tokens, and memory usage.
10 - Show profile information for rules, both timing and memory.
11 - Show parsing progress of Jamfiles.
12 - Show graph of target dependencies.
13 - Show change target status (fate).
-d +n: Enable debugging level n.
-d 0: Turn off all debugging levels. Only errors are reported.
-f Jambase: Read Jambase instead of using the built-in Jambase. Only one -f flag is permitted, but the Jambase may explicitly include other files. A Jambase name of "-" is allowed, in which case console input is read until it is closed, at which point the input is treated as the Jambase.
-j n: Run up to n shell commands concurrently (UNIX and NT only). The default is 1.
-l n: Limit actions to running for n number of seconds, after which they are stopped. Note: Windows only.
-n: Don't actually execute the updating actions, but do everything else. This changes the debug level default to -d 2.
-o file: Write the updating actions to the specified file instead of running them.
-q: Quit quickly (as if an interrupt was received) as soon as any target fails.
-s var=value: Set the variable var to value, overriding both internal variables and variables imported from the environment.
-t target: Rebuild target and everything that depends on it, even if it is up-to-date.
-- value: The option and value is ignored, but is available from the $(ARGV) variable.
-v: Print the version of bjam and exit.

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:

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:

set MSVCNT=""C:\Program Files\Microsoft Visual C++\VC98\""

Operation

Start-up
Parsing
Binding
Updating

BJam has four phases of operation: start-up, parsing, binding, and updating.

Start-up

Upon start-up, bjam imports environment variable settings into bjam variables. Environment variables are split at blanks with each word becoming an element in the variable's list of values. Environment variables whose names end in PATH are split at $(SPLITPATH) characters (e.g., ":" for Unix).

To set a variable's value on the command line, overriding the variable's environment value, use the -s option. To see variable assignments made during bjam's execution, use the -d+7 option.

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.

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.
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.
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.
If the bootstrap.jam file was not found, we print a likely error message and exit.

Parsing

In the parsing phase, bjam reads and parses the Jambase file, by default the built-in one. It is written in the jam language. The last action of the Jambase is to read (via the "include" rule) a user-provided file called "Jamfile".

Collectively, the purpose of the Jambase and the Jamfile is to name build targets and source files, construct the dependency graph among them, and associate build actions with targets. The Jambase defines boilerplate rules and variable assignments, and the Jamfile uses these to specify the actual relationship among the target and source files.

Binding

Update Determination
Header File Scanning

After parsing, bjam recursively descends the dependency graph and binds every file target with a location in the filesystem. If bjam detects a circular dependency in the graph, it issues a warning.

File target names are given as absolute or relative path names in the filesystem. If the path name is absolute, it is bound as is. If the path name is relative, it is normally bound as is, and thus relative to the current directory. This can be modified by the settings of the $(SEARCH) and $(LOCATE) variables, which enable jam to find and build targets spread across a directory tree. See SEARCH and LOCATE Variables below.

Update Determination

After binding each target, bjam determines whether the target needs updating, and if so marks the target for the updating phase. A target is normally so marked if it is missing, it is older than any of its sources, or any of its sources are marked for updating. This behavior can be modified by the application of special built-in rules, ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, and TEMPORARY. See Modifying Binding below.

Header File Scanning

During the binding phase, bjam also performs header file scanning, where it looks inside source files for the implicit dependencies on other files caused by C's #include syntax. This is controlled by the special variables $(HDRSCAN) and $(HDRRULE). The result of the scan is formed into a rule invocation, with the scanned file as the target and the found included file names as the sources. Note that this is the only case where rules are invoked outside the parsing phase. See HDRSCAN and HDRRULE Variables below.

Updating

After binding, bjam again recursively descends the dependency graph, this time executing the update actions for each target marked for update during the binding phase. If a target's updating actions fail, then all other targets which depend on that target are skipped.

The -j flag instructs bjam to build more than one target at a time. If there are multiple actions on a single target, they are run sequentially.