Boost.Build is a system for large project software construction built on Boost.Jam, a descendant of "Perforce Jam", an open-source make replacement[1]. Key features are:
Here are some of the design criteria that led to these features.
Boost.Build responds to several global variable settins. The
easiest way to get going is usually to use environment variables,
though you can also set them on the command-line, using
-sVARIABLE_NAME=value. In
addition to the toolset
configuration variables, you can use the TOOLS
variable to indicate which toolset(s) to build with, and the
BUILD variable to describe how you want things built. In
many cases it should be sufficient to invoke bjam
with no variable settings.
Some example Boost.Jam invocations:
Command Line(s) | Effects |
---|---|
bjam -sTOOLS=gcc my_target | default (debug) BUILD of my_targetwith GCC |
bjam -sTOOLS="msvc gcc" | default-build all with msvc and gcc |
set TOOLS=msvc bjam | Set an NT environment variable to always build with MSVC default-build all. |
bjam "-sBUILD=release <debug-symbols>on" | release build with debug symbols of all using default TOOLS |
bjam -sBUILD="debug release" | debug and release build all. |
The "-s" options in the command lines above are passing variable settings to the build system. There are actually three ways to do that:
This approach can be OK for quick-and-dirty tests, but environment variable settings tend to be unstable and non-uniform across users and machines, so it's best not to rely on the environment much.> BUILD="debug release" # assuming Unix > export BUILD > bjam ...
subproject foo/bar/baz ; # path to here from project root # A static library called 'baz' lib baz : baz1.cpp baz2.cpp # C++ sources parser/src/baz4.ll # Lex->C++ sources parser/src/baz5.yy # Yacc->C++ sources : <include>$(BOOST_PARENT_DIRECTORY) # Put boost in #include path ; # An executable called 'test' exe test : <lib>baz # use the 'baz' library baz_test.cpp # C++ source : <include>$(BOOST_ROOT) ;
That's it! The build system takes care of the rest. If the you want to be able to build all subprojects from the project root directory, you can add a Jamfile at the root:
project-root ; # declare this to be the project root directory # Read subproject Jamfiles subinclude foo/bar/baz foo/bar/... ; subinclude a/b/c ... ; # more subincludes
To use the build system, the following must be located in your project's root directory, or in a directory specified in the BOOST_BUILD_PATH variable. It is usually convenient to specify the BOOST_BUILD_PATH in your project's Jamrules file. The Boost Jamrules file shows an example.
Filename(s) | Meaning |
---|---|
toolset-tools.jam | Feature-to-command-line mapping for toolset. |
features.jam | Abstract toolset feature descriptions. |
boost-base.jam | Boost build system-specific rule definitions. |
unit-tests.jam | Unit tests and assertions for boost Jam code. |
A project is a source directory tree containing at least one Jamfile. The root directory of the project is known as the project root. The root directory of a project may contain a Jamrules file, which contains project-specific Jam code. If the Jamrules file is not present when Jam is invoked, a warning will be issued.
Subdirectories containing Jamfiles are called subproject directories. Each such Jamfile describes a subproject.
The build system installation directory is a directory containing Jam files describing compilers and build variants. The installation directory can be specified implicitly by setting the variable BOOST_BUILD_PATH. This lists a set of directories to search for the files comprising the build system. If the installation directory is not specified, it is the same as the project root, and BOOST_BUILD_PATH is set to include that directory.
Each Jamfile describes one or more main targets.
Each main target is an abstract description of one or more built targets which are expressions of the corresponding main target under particular compilers and build variants. Intermediate files such as .o/.obj files generated by compiling .cpp files as a consequence of building a main target are also referred to as built targets. The term build directory tree refers to the location of built target files.
A feature is a normalized (toolset-independent) description of an individual build parameter, such as whether inlining is enabled. Each feature usually corresponds to a command-line option of one or more build tools. Features come in four varieties:
A feature-value pair is known as a build property, or simply property. The prefixes simple, free, path, and dependency apply to properties in an analogous way to features.
A build variant, or simply variant is a named set of build properties describing how targets should be built. Typically you'll want at least two separate variants: one for debugging, and one for your release code.
Built targets for distinct build variants and toolsets are generated in separate parts of the build directory tree, known as the variant directories. For example, a (sub)project with main targets foo and bar, compiled with both GCC and KAI for debug and release variants might generate the following structure (target directories in bold).
bin +-foo <--- foo's build root | +-gcc | | +-debug | | `-release | `-kai | +-debug | `-release `-bar <--- bar's build root +-gcc | +-debug | `-release `-kai +-debug `-release
The properties constituting a variant may differ according to toolset, so debug may mean a slightly different set of properties for two different compilers.
When a target is built with simple properties that don't exactly match those specified in a build variant, the non-matching features are called subvariant features and the target is located in a subvariant directory beneath the directory of the base variant. This can occur for two reasons:
Because the default value of runtime-link is dynamic, when the debug variant is requested, the runtime-link-dynamic subvariant of foo is built.bin +-foo <--- foo's build root | +-msvc | | +-debug . . . `-runtime-link-dynamic . . .
bin +-foo <--- foo's build root | +-msvc | | +-debug . . . +-runtime-link-dynamic . . . `-runtime-link-static . . .
When a subvariant includes multiple subvariant features, targets are built into a subvariant directory whose path is determined by concatenating the properties sorted in order of their feature names. For example, the borland compiler, which uses different libraries depending on whether the target is a console or GUI program, might create the following structure for a DLL:
bin +-foo <--- foo's build root | +-msvc | | +-debug | | | +-runtime-link-dynamic | | | | +-user-interface-console | | | | `-user-interface-gui . . . `-runtime-link-static . . . +-user-interface-console . . . `user-interface-gui
Any configuration of properties for which a target is built, whether base variant or subvariant, is known as a build configuration, or simply a build.
When a main target depends on the product of a second main target (as when an executable depends on and links to a static library), each build configuration of the dependent target is depends on the corresponding build of the dependency. Because only simple features participate in build identity, the dependent and dependency targets may have completely different free features. This puts the onus on the user for ensuring link-compatibility when certain free properties are used. For example, when assert() is used in header files, the preprocessor symbol NDEBUG can impact link-compatibility of separate compilation units. This danger can be minimized by encapsulating such feature differences inside of build variants.
This section describes how to start a build from the command-line and how to write project and subproject Jamfiles. It also describes the other files written in the Jam language: build-tool specification files, feature descriptions files.
This section describes in detail how the build system can be invoked.
The Jam command line ends with an optional list of target names; if no target names are supplied, the built-in pseudotarget all is built. In a large project, naming targets can be dicey because of collisions. Jam uses a mechanism called grist to distinguish targets that would otherwise have the same name. Fortunately, you won't often have to supply grist at the command-line. When you declare a main target, a Jam pseudotarget of the same name is created which depends on all of the subvariants requested for your invocation of the build system. For example, if your subproject declares:
and you invoke Jam with -sBUILD="debug release" my_target, you will build both the debug and release versions of my_target.exe my_target : my_source1.cpp my_source2.c ;
These simple, ungristed names are called user targets, and are only available for the subproject where Jam is invoked. That way, builds from the top level (which may include many Jamfiles through the subinclude rule) and builds of library dependencies (which may live in other subprojects), don't collide. If it is necessary to refer more explicitly to a particular target from the command-line, you will have to add ``grist''. Please see this section for a more complete description of how to name particular targets in a build.
This is a partial list of global variables that can be set on the command-line. Of course you are free to write your own Jam rules which interpret other variables from the command-line. This list just details some of the variables used by the build system itself. Note also that if you don't like the default values you can override them in your project's Jamrules file.
Variable | Default | Example | Notes |
---|---|---|---|
TOOLS | Platform-dependent | "-sTOOLS=gcc msvc" | build with gcc and msvc |
-sTOOLS=gcc | build with gcc | ||
BUILD | debug | -sBUILD=release | build the release variant |
"-sBUILD=debug release" | build both debug and release variants | ||
"-sBUILD=<optimization>speed" | build a subvariant of the default variant (debug) with optimization for speed. | ||
"-sBUILD=debug release <runtime-link>static/dynamic" | build subvariants of the debug and release variants that link to the runtime both statically and dynamically. | ||
ALL_LOCATE_TARGET | empty | -sALL_LOCATE_TARGET=~/build | Generate all build results in the build subdirectory of the user's home directory (UNIX). |
A subproject's Jamfile begins with an invocation of the subproject rule that specifies the subproject's location relative to the top of the project tree:
subproject path-from-top ;
The subproject rule tells the build system where to place built targets from the subproject in case ALL_LOCATE_TARGET is used to specify the build directory tree. If there is a Jamfile in the project root directory, you should use the project-root rule instead:
project-root ;
A main target is described using the following syntax:
target-type name : sources [ : requirements [ : default-BUILD ] ] ;
<compiler> and <variant>, if supplied, can be used to restrict the applicability of the requirement. Either one may be replaced by <*>, which is the same as omitting it.[[<compiler>]<variant>]<feature>value
The system checks that simple feature requirements are not violated
by explicit subvariant build requests, and will issue a warning otherwise.
Free features specified as requirements are simply added to each corresponding
build configuration.
When multiple values are specified, it causes all the implied configurations to be built by default. It is also possible to prevent any default builds from occurring on this target by using[[<compiler>]<variant>]<feature>value1[/value2...]
<suppress>true
. This suppresses any local targets, either implicit or explicit, from
building. But, this does not prevent implied targets as required by a
dependency by another target to this one from being built. This is useful,
for example, for defining a set of libraries generically and having them
built only when another target like an exe is built. Such use might look
like:
With that the basic library will only be built when the test executable is built, and only the variations required by the executable will be built.lib basic : basic.cpp : : <suppress>true ;
exe test : test.cpp <lib>basic ;
NOTE: for simple features in both requirements and default-BUILD, more-specific qualification overrides less-specific.
Template targets provide a way to handle commonalities between projects targets. They have the same form as main targets but do not initiate build requests. A target that lists a template as a dependency inherits all the settings from the template, i.e. the templates sources, requirements and default build settings will be added to the targets settings. Paths mentioned in a template definition are always relative to the subdirectory of the Jamfile containing the templates definition, regardless of the subdirectory of the dependent main target. Typically a project will have at least one template target that handles defines, include paths and additional compiler flags common to all targets in the project.
Stage targets are a special kind of target that don't build a single file but to a collection of files. The goal is to create a directory which is composed of the various files that other targets generate, or individual files. When built a stage target creates a directory with the same name as the target, and copies the dependent files to it. The form of the target is the same as that of main targets with some differences...
<tag><feature|variant>value
This artificially complex example shows how two executables called "foo" and "fop" might be described in a Jamfile. All common settings are factored out in the templates "base" and "executable". Foo is composed of the sources ./foo.cpp and ./src/bar.cpp (specified relative to the directory in which the Jamfile resides). Fop only has one sourcefile ./fop.cpp. Both executables link against the built target which results from building the target baz as described in ../bazlib/Jamfile.
template base : ## Requirements ## : <include>../bazlib/include <define>BUILDING_FOO=1 <release><define>FOO_RELEASE <msvc><*><define>FOO_MSVC <msvc><release><define>FOO_MSVC_RELEASE <gcc><*><optimization>off <gcc><release><optimization>space <threading>multi <sysinclude>/usr/local/foolib/include ## default-BUILD ## : debug release <debug><runtime-link>static/dynamic ; template executable : <template>base <lib>../bazlib/baz ; exe foo : <template>executable foo.cpp src/bar.cpp ; exe fop : <template>executable fop.cpp ;
The requirements section:
The default-BUILD section:
Features are described by stating the feature type (simple features are specified with "feature"), followed by the feature name. An optional second argument can be used to list the permissible values of the feature. Examples can be found in features.jam.
Variants are described with the following syntax:
The variant rule specifies the list of properties comprising a variant. Properties may be optionally qualified with a toolset name, which specifies that the property applies only to that toolset. One or more parent variants may be specified to inherit the properties from those parent(s). For inherited properties precedence is given on a left to right order, making the immediate properties override those in the parent(s). This can be used to great effect for describing global properties that are shared amongst various variants, and therefore targets. For example:variant name : [<toolset-name>]<feature>value... ;
More examples can be found in features.jam.variant my-globals : <rtti>off ; variant my-debug : my-globals debug ; variant my-release : my-globals release ;
Toolset descriptions are located in the project's root directory, or a directory specified by BOOST_BUILD_INSTALLATION, which may be set in a Jamfile or the project's Jamrules file. Each file is called toolset-name-tools.jam, where toolset-name is the name of the toolset. The toolset description file has two main jobs:
Note that Link-action may require special care: on platforms where the global variable gEXPORT_SUFFIX(DLL) is defined (e.g. Windows), the first argument may have two elements when linking a shared library. The first is the shared library target, and the second is the import library target, with suffix given by $(gEXPORT_SUFFIX(DLL)). It will always have a third argument which is either ``EXE'' or ``DLL''. This can be used to dispatch to different actions for linking DLLs and EXEs if necessary, but usually it will be easier to take advantage of the special <target-type> feature, which will have the same value using the flags rule described below.rule C++-action { msvc-C++-action $(<) : $(>) ; } actions msvc-C++-action { cl -nologo -GX -c -U$(UNDEFS) -D$(DEFINES) $(CFLAGS) $(C++FLAGS) -I$(HDRS) -I$(STDHDRS) -Fo$(<) -Tp$(>) }
The parameters are:flags toolset variable condition [: value...]
Semantics only affect targets built with the specified toolset, and depend on the target's build configuration:
The description of the flags rule above is actually more complicated than it sounds. For example, the following line might be used to specify how optimization can be turned off for MSVC:
It says that the string /Od should be added to the global CFLAGS variable whenever a build configuration includes the property <optimization>off.flags msvc CFLAGS <optimization>off : /Od ;
Similarly, in the following example,
we add /MD to the CFLAGS variable when both of the specified conditions are satisfied. We could grab all of the values of the free feature <include> in the HDRS variable as follows:flags msvc CFLAGS <runtime-build>release/<runtime-link>dynamic : /MD ;
flags msvc HDRS <include> ;
The use of these variables should be apparent from the declaration of actions msvc-C++-action in the previous section.
This section is derived from the official Jam documentation and from my experience using it and reading the Jambase rules. I repeat the information here mostly because it is essential to understanding and using Jam, but is not consolidated in a single place. Some of it is missing from the official documentation altogether. I hope it will be useful to anyone wishing to become familiar with Jam and the Boost build system.
``Grist'' is just a string prefix of the form <characters>. It is used in Jam to create unique target names based on simpler names. For example, the file name ``test.exe'' may be used by targets in separate subprojects, or for the debug and release variants of the ``same'' abstract target. Each distinct target bound to a file called ``test.exe'' has its own unique grist prefix. The Boost build system also takes full advantage of Jam's ability to divide strings on grist boundaries, sometimes concatenating multiple gristed elements at the beginning of a string. Grist is used instead of identifying targets with absolute paths for two reasons:
If the user wants a specific message, he invokes jam with "-sMESSAGE=message text". If he wants no message, he invokes jam with -sMESSAGE= and nothing at all is printed.MESSAGE ?= starting jam... ; if $(MESSAGE) { ECHO The message is: $(MESSAGE) ; }
Please also read The Jam language reference for the additional details, and the Jam release notes for a brief description of recent, but fundamental changes to the Jam language without which you will probably not understand any of the build system code. In particular, note that the return statement does not affect control flow.
A number of enhancements have been made to the core language of Classic Jam. These changes were aimed primarily at making it easier to manage the complexity of a large system such as Boost.Build.
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:
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:jam -sMSVCNT="\"\"C:\Program Files\Microsoft Visual C++\VC98\"\"" ...set MSVCNT=""C:\Program Files\Microsoft Visual C++\VC98\""Startup Behavior
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 theBOOST_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 theBOOST_ROOT
variable is set, we first search forboost-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 ofBOOST_BUILD_PATH
, and attempts to loadbootstrap.jam
from those directories. If a relative path is specified as an argument, it is treated as though it was relative to theboost-build.jam
file.- If the bootstrap.jam file was not found, we print a likely error message and exit.
Rule Indirection
Boost Jam allows you to call a rule whose name is held in a variable or computed as the result of an expression:
Furthermore, if the first expression expands to more than one list item, everything after the first item becomes part of the first argument. This allows a crude form of argument binding:x = foo ; rule foobar { ECHO foobar ; } # a trivial rule $(x)bar ; # invokes foobar# return the elements of sequence for which predicate returns non-nil rule filter ( sequence * : predicate + ) { local result ; for local x in $(sequence) { if [ $(predicate) $(x) ] { result += $(x); } } return $(result); } # true iff x == y rule equal ( x y ) { if $(x) = $(y) { return true; } } # bind 3 to the first argument of equal ECHO [ filter 1 2 3 4 5 4 3 : equal 3 ] ; # prints "3 3"Argument lists
You can now 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:
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: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 ;
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 namesIf 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.
Module Support
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:
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 my_module { rule salute ( x ) { ECHO $(x), world ; } rule greet ( ) { salute hello ; } greet ; } my_module.salute goodbye ;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:
The only way to access another module's variables is by entering that module: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 ; } }Note that because existing variable bindings change whenever a new module scope is entered, argument bindings become unavailable. That explains the use of "rule peek ( module-name ? : variables + ) { module $(module-name) { return $($(>)) ; } }$(>)
" in thepeek
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
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 RULENAMES ( module ? )The IMPORT Rule
IMPORT allows rule name aliasing across modules: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,rule IMPORT ( source_module ? : source_rules * : target_module ? : target_rules * )# 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: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,rule EXPORT ( module ? : rules * )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
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}":rule CALLER_MODULE ( levels ? )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)} ;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"Negative Indexing
Classic Jam supplies 1-based list indexing, and slicing on a closed (inclusive) range:Boost Jam adds Python-style negative indexing to access locations relative to the end of the list.x = 1 2 3 4 5 ; ECHO $(x[3]) ; # prints "3" ECHO $(x[2-4]) ; # prints "2 3 4" ECHO $(x[2-]) ; # prints "2 3 4 5"Consistency with the 1-based, inclusive indexing of Classic Jam and the use of ``-'' as the range separator make this feature a bit clumsier than it would otherwise need to be, but it does work.ECHO $(x[-1]) $(x[-3]) ; # prints "5 3" ECHO $(x[-3--1]) ; # prints "3 4 5" ECHO $(x[-3-4]) ; # prints "3 4" ECHO $(x[2--2]) ; # prints "2 3 4"Target 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:
This facility is useful for correct header file scanning, since many compilers will search for #included files first in the directory containing the file doing the #include directive. $(BINDRULE) can be used to make a record of that directory.rule bind-rule ( target : path )Return Code Inversion
For handling targets whose build actions are expected to fail (e.g. when testing that assertions or compile-time type checkin work properly), Boost Jam supplies a 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.
Ignoring Return Codes
Perforce Jam supplied a NOCARE rule which is typically used for header files to indicate that if they are not found, the dependent targets should be built anyway. Boost Jam extends NOCARE to apply to targets with build actions: if their build actions exit with a nonzero return code, dependent targets will still be built.
Removing Outdated Targets
rule RMOLD ( targets * )Perforce Jam 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.The SUBST Rule
Note: the
SUBST
rule is deprecated in favor of Perforce Jam's built-inMATCH rule, which has been rolled into Boost.Jam.The behavior of the SUBST rule for regular-expression matching and replacement (originally added in FTJam) has been modified:
- One or more replacement patterns may be supplied. The new signature for SUBST is:
The return value is the concatenated results of applying each element of replacements in turn. For example, the following will print ``[x] (y) {z}'':SUBST ( source pattern replacements + )ECHO [ SUBST xyz (.)(.)(.) [$1] ($2) {$3} ] ;- If there is no match, SUBST now returns an empty list. In FTJam, the original source string was returned, making it awkward to check whether a pattern was matched.
- Compiled regular expressions are now internally cached, making it much faster to use SUBST multiple times with the same string.
The JAM_VERSION global variable
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.
Debugging Support
The BACKTRACE rule
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 BACKTRACE ( )The -d command-line option admits new arguments:
- -d+10 - enables profiling of rule invocations. When Jam exits, it dumps all rules invoked, their gross and net times in platform-dependent units, and the number of times the rule was invoked.
- -d+11 - enables parser debugging, if Jam has been compiled with the "--debug" option to the parser generator named by $(YACC).
- -d+12 - enables dependency graph output . This feature was ``stolen'' from a version of Jam modified by Craig McPheeters.
In addition to user targets, which correspond directly to the names the user writes in her subproject Jamfile, several additional targets are generated, regardless of the directory from which Jam was invoked:
This section describes some of the global variables used by the build system. Please note that some parts of the system (particularly those in allyourbase.jam) are heavily based on the Jambase file supplied with Jam, and as such do not follow the conventions described below.
Global variables used in the build system fall into three categories:
ECHO $(gFUBAR($(x),$(y))) ;
Please note that the build system commonly takes advantage of Jam's Dynamic Scoping feature (see the local command in the "Flow of Control" section below the link target) to temporarily "change" a global variable by declaring a local of the same name.
Many of the variables that are used to configure how Boost.Build works internally are listed here with brief descriptions.
The requirements are driven by several basic assumptions:
This build system was designed to satisfy the following requirements:
[2] Note: right now, a dependency feature of a main target makes all resulting built targets dependent, including intermediate targets. That means that if an executable is dependent on an external library, and that library changes, all the sources comprising the executable will be recompiled as well. This behavior should probably be fixed.
© Copyright David Abrahams 2001. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.
Revised 11 November, 2001