If target is provided on the command line,
builds target; otherwise
bjam ( -option [value] | target ) *
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:
Build all targets anyway, even if they are up-to-date.
Enable cummulative debugging levels from 1 to n. Values are:
Enable debugging level n.
Turn off all debugging levels. Only errors are reported.
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.
Run up to n shell commands concurrently (UNIX and NT only). The default is 1.
Limit actions to running for n number of seconds, after which they are stopped. Note: Windows only.
Don't actually execute the updating actions, but do everything else.
This changes the debug level default to
Write the updating actions to the specified file instead of running them.
Quit quickly (as if an interrupt was received) as soon as any target fails.
Set the variable var to value, overriding both internal variables and variables imported from the environment.
Rebuild target and everything that depends on it, even if it is up-to-date.
The option and value is ignored, but is available
Print the version of
bjam and exit.
Classic Jam had an odd behavior with respect to command-line variable (
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\""
BJam has four phases of operation: start-up, parsing, binding, and updating.
bjam imports environment variable settings
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
are split at
$(SPLITPATH) characters (e.g.,
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
The Boost.Build v2 initialization behavior has been implemented. This behavior
only applies when the executable being invoked is called "
or, for backward-compatibility, when the
variable is set.
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-buildrule to indicate where the Boost.Build system files are, and to load them.
boost-build.jamis 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_ROOTvariable is set, we first search for
$(BOOST_BUILD_PATH). If found, it is loaded and initialization is complete.
boost-buildrule adds its (optional) argument to the front of
BOOST_BUILD_PATH, and attempts to load
bootstrap.jamfrom those directories. If a relative path is specified as an argument, it is treated as though it was relative to the
bootstrap.jamfile was not found, we print a likely error message and exit.
In the parsing phase,
bjam reads and parses the
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 "
Collectively, the purpose of the
Jambase and the
is to name build targets and source files, construct the dependency graph
among them, and associate build actions with targets. The
defines boilerplate rules and variable assignments, and the
uses these to specify the actual relationship among the target and source
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
$(LOCATE) variables, which enable jam to find and
build targets spread across a directory tree. See SEARCH
and LOCATE Variables below.
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,
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.
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.
-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.