...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Warning | |
---|---|
Most probably, you are looking for Boost.Build manual or Boost.Build command-line syntax. This section documents only low-level options used by the Boost.Jam build engine, and does not mention any high-level syntax of Boost.Build |
If target is provided on the command line, bjam
builds target; otherwise bjam
builds
the target all
.
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:
-a
Build all targets anyway, even if they are up-to-date.
-d n
Enable cummulative debugging levels from 1 to n. Values are:
-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.
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\""
BJam has four phases of operation: start-up, parsing, binding, and updating.
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.
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.
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.
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.
bootstrap.jam
file was not found, we print
a likely error message and exit.
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.
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.
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.
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.
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.