1. Introduction
Want to learn about B2 features? Start with the tutorial and continue with the overview. When you’re ready to try B2 in practice, go to the installation.
Building a project with B2? See the installation and then read the overview.
Setting up B2 on your project? Take a look at the overview and extender manual.
If there’s anything you find unclear in this documentation, report the problem directly in the issue tracker. For more general questions, please post them to our discussion forums (https://github.com/bfgroup/b2/discussions).
2. Installation
To install B2 from an official release, as available on GitHub, follow these steps:
-
Unpack the release. On the command line, go to the root of the unpacked tree.
-
Run either
.\bootstrap.bat
(on Windows), or./bootstrap.sh
(on other operating systems). -
Run
$ ./b2 install --prefix=PREFIX
where PREFIX is a directory where you want B2 to be installed.
-
Optionally, add
PREFIX/bin
to your PATH environment variable.
$ PREFIX/bin/b2
A simple executable should be built.
|
ℹ
|
A C++11 capable compiler is needed to build the b2 engine. But using
the b2 engine and build system does not require C++11.
|
3. Tutorial
This section will guide you though the most basic features of B2. We will start with the “Hello, world” example, learn how to use libraries, and finish with testing and installing features.
3.1. Hello, world
The simplest project that B2 can construct is stored in
example/hello/
directory. The project is described by a file called
Jamfile
that contains:
exe hello : hello.cpp ;
Even with this simple setup, you can do some interesting things. First
of all, just invoking b2
will build the hello
executable by compiling
and linking hello.cpp
. By default, the debug variant is built. Now, to
build the release variant of hello
, invoke
b2 release
Note that the debug and release variants are created in different
directories, so you can switch between variants or even build multiple
variants at once, without any unnecessary recompilation. Let us extend
the example by adding another line to our project’s Jamfile
:
exe hello2 : hello.cpp ;
Now let us build both the debug and release variants of our project again:
b2 debug release
Note that two variants of hello2
are linked. Since we have already
built both variants of hello
, hello.cpp will not be recompiled;
instead the existing object files will just be linked into the
corresponding variants of hello2
. Now let us remove all the built
products:
b2 --clean debug release
It is also possible to build or clean specific targets. The following
two commands, respectively, build or clean only the debug version of
hello2
.
b2 hello2
b2 --clean hello2
3.2. Properties
To represent aspects of target configuration such as debug and release
variants, or single- and multi-threaded builds portably, B2
uses features with associated values. For example, the debug-symbols
feature can have a value of on
or off
. A property is just a
(feature, value) pair. When a user initiates a build, B2
automatically translates the requested properties into appropriate
command-line flags for invoking toolset components like compilers and
linkers.
There are many built-in features that can be combined to produce
arbitrary build configurations. The following command builds the
project’s release
variant with inlining disabled and debug symbols
enabled:
b2 release inlining=off debug-symbols=on
Properties on the command-line are specified with the syntax:
feature-name=feature-value
The release
and debug
that we have seen in b2
invocations are just
a shorthand way to specify values of the variant
feature. For example,
the command above could also have been written this way:
b2 variant=release inlining=off debug-symbols=on
variant
is so commonly-used that it has been given special status as
an implicit feature—B2 will deduce its identity just from the
name of one of its values.
A complete description of features can be found in the section called “Features and properties”.
3.2.1. Build Requests and Target Requirements
The set of properties specified on the command line constitutes a build
request—a description of the desired properties for building the
requested targets (or, if no targets were explicitly requested, the
project in the current directory). The actual properties used for
building targets are typically a combination of the build request and
properties derived from the project’s Jamfile
(and its other Jamfiles,
as described in
the section called “Project Hierarchies”).
For example, the locations of `#include`d header files are normally not
specified on the command-line, but described in Jamfiles as target
requirements and automatically combined with the build request for those
targets. Multi-threaded compilation is another example of a typical
target requirement. The Jamfile fragment below illustrates how these
requirements might be specified.
exe hello
: hello.cpp
: <include>boost <threading>multi
;
When hello
is built, the two requirements specified above will always
be present. If the build request given on the b2
command-line
explicitly contradicts a target’s requirements, the target requirements
usually override (or, in the case of “free” features like
<include>
, [1]
augment) the build request.
|
☀
|
The value of the <include> feature is relative to the location of
Jamfile where it is used.
|
3.2.2. Project Attributes
If we want the same requirements for our other target, hello2
, we
could simply duplicate them. However, as projects grow, that approach
leads to a great deal of repeated boilerplate in Jamfiles. Fortunately,
there’s a better way. Each project can specify a set of attributes,
including requirements:
project
: requirements <include>/home/ghost/Work/boost <threading>multi
;
exe hello : hello.cpp ;
exe hello2 : hello.cpp ;
The effect would be as if we specified the same requirement for both
hello
and hello2
.
3.3. Project Hierarchies
So far we have only considered examples with one project, with one
user-written Jamfile
file. A typical large codebase would
be composed of many projects organized into a tree. The top of the tree
is called the project root. Every subproject is defined by a file called
Jamfile
in a descendant directory of the project root. The parent
project of a subproject is defined by the nearest Jamfile
file in an ancestor directory. For example, in the following directory
layout:
top/ | +-- Jamfile | +-- app/ | | | +-- Jamfile | `-- app.cpp | `-- util/ | +-- foo/ . | . +-- Jamfile . `-- bar.cpp
the project root is top/
. The projects in top/app/
and
top/util/foo/
are immediate children of the root project.
|
ℹ
|
When we refer to a “Jamfile,” set in normal type, we mean a file called
either Jamfile or Jamroot . When we need to be more specific, the
filename will be set as “Jamfile ” or “Jamroot .”
|
Projects inherit all attributes (such as requirements) from their
parents. Inherited requirements are combined with any requirements
specified by the subproject. For example, if top/Jamfile
has
<include>/home/ghost/local
in its requirements, then all of its sub-projects will have it in their requirements, too. Of course, any project can add include paths to those specified by its parents. [2] More details can be found in the section called “Projects”.
Invoking b2
without explicitly specifying any targets on the command
line builds the project rooted in the current directory. Building a
project does not automatically cause its sub-projects to be built unless
the parent project’s Jamfile explicitly requests it. In our example,
top/Jamfile
might contain:
build-project app ;
which would cause the project in top/app/
to be built whenever the
project in top/
is built. However, targets in top/util/foo/
will be
built only if they are needed by targets in top/
or top/app/
.
3.4. Dependent Targets
When building a target X
that depends on first building another target
Y
(such as a library that must be linked with X), Y
is called a
dependency of X
and X
is termed a dependent of Y
.
To get a feeling of target dependencies, let’s continue the above
example and see how top/app/Jamfile
can use libraries from
top/util/foo
. If top/util/foo/Jamfile
contains
lib bar : bar.cpp ;
then to use this library in top/app/Jamfile
, we can write:
exe app : app.cpp ../util/foo//bar ;
While app.cpp
refers to a regular source file, ../util/foo//bar
is a
reference to another target: a library bar
declared in the Jamfile at
../util/foo
.
|
☀
|
Some other build system have special syntax for listing dependent
libraries, for example LIBS variable. In B2, you just add the
library to the list of sources.
|
Suppose we build app
with:
b2 app optimization=full define=USE_ASM
Which properties will be used to build foo
? The answer is that some
features are propagated — B2 attempts to use dependencies with
the same value of propagated features. The <optimization>
feature is
propagated, so both app
and foo
will be compiled with full
optimization. But <define>
is not propagated: its value will be added
as-is to the compiler flags for a.cpp
, but won’t affect foo
.
Let’s improve this project further. The library probably has some
headers that must be used when compiling app.cpp
. We could manually
add the necessary #include
paths to the app
requirements as values of
the <include>
feature, but then this work will be repeated for all
programs that use foo
. A better solution is to modify
util/foo/Jamfile
in this way:
project
: usage-requirements <include>.
;
lib foo : foo.cpp ;
Usage requirements are applied not to the target being declared but to
its dependents. In this case, <include>.
will be applied to all
targets that directly depend on foo
.
Another improvement is using symbolic identifiers to refer to the
library, as opposed to Jamfile
location. In a large project, a library
can be used by many targets, and if they all use Jamfile
location, a change
in directory organization entails much work.
The solution is to use project ids—symbolic names not tied to directory
layout. First, we need to assign a project id by adding this code to
Jamfile
:
use-project /library-example/foo : util/foo ;
Second, we modify app/Jamfile
to use the project id:
exe app : app.cpp /library-example/foo//bar ;
The /library-example/foo//bar
syntax is used to refer to the target
bar
in the project with id /library-example/foo
. We’ve achieved our
goal—if the library is moved to a different directory, only top/Jamfile
must be modified. Note that project ids are global—two Jamfiles
are not allowed to assign the same project id to different directories.
|
☀
|
If you want all applications in some project to link to a certain
library, you can avoid having to specify directly the sources of every
target by using the
|
3.5. Static and shared libraries
Libraries can be either static, which means they are included in executable files that use them, or shared (a.k.a. dynamic), which are only referred to from executables, and must be available at run time. B2 can create and use both kinds.
The kind of library produced from a lib
target is determined by the
value of the link
feature. Default value is shared
, and to build a
static library, the value should be static
. You can request a static
build either on the command line:
b2 link=static
or in the library’s requirements:
lib l : l.cpp : <link>static ;
We can also use the <link>
property to express linking requirements on
a per-target basis. For example, if a particular executable can be
correctly built only with the static version of a library, we can
qualify the executable’s target
reference to the library as follows:
exe important : main.cpp helpers/<link>static ;
No matter what arguments are specified on the b2
command line,
important
will only be linked with the static version of helpers
.
Specifying properties in target references is especially useful if you use a library defined in some other project (one you can’t change) but you still want static (or dynamic) linking to that library in all cases. If that library is used by many targets, you could use target references everywhere:
exe e1 : e1.cpp /other_project//bar/<link>static ;
exe e10 : e10.cpp /other_project//bar/<link>static ;
but that’s far from being convenient. A better approach is to introduce
a level of indirection. Create a local alias
target that refers to the
static (or dynamic) version of foo
:
alias foo : /other_project//bar/<link>static ;
exe e1 : e1.cpp foo ;
exe e10 : e10.cpp foo ;
The alias rule is specifically used to rename a reference to a target and possibly change the properties.
|
☀
|
When one library uses another, you put the second library in the source list of the first. For example:
This works no matter what kind of linking is used. When |
|
ℹ
|
(Note for non-UNIX system). Typically, shared libraries must be
installed to a directory in the dynamic linker’s search path. Otherwise,
applications that use shared libraries can’t be started. On Windows, the
dynamic linker’s search path is given by the PATH environment variable.
This restriction is lifted when you use B2 testing
facilities—the PATH variable will be automatically adjusted before
running the executable.
|
3.6. Conditions and alternatives
Sometimes, particular relationships need to be maintained among a
target’s build properties. For example, you might want to set specific
#define
when a library is built as shared, or when a target’s
release
variant is built. This can be achieved using conditional
requirements.
lib network : network.cpp
: <link>shared:<define>NETWORK_LIB_SHARED
<variant>release:<define>EXTRA_FAST
;
In the example above, whenever network
is built with <link>shared
,
<define>NETWORK_LIB_SHARED
will be in its properties, too. Also, whenever
its release variant is built, <define>EXTRA_FAST
will appear in its
properties.
Sometimes the ways a target is built are so different that describing them using conditional requirements would be hard. For example, imagine that a library actually uses different source files depending on the toolset used to build it. We can express this situation using target alternatives:
lib demangler : dummy_demangler.cpp ; # (1)
lib demangler : demangler_gcc.cpp : <toolset>gcc ; # (2)
lib demangler : demangler_msvc.cpp : <toolset>msvc ; # (3)
When building demangler
, B2 will compare requirements for
each alternative with build properties to find the best match. For
example, when building with <toolset>gcc
alternative (2), will be
selected, and when building with <toolset>msvc
alternative (3) will be
selected. In all other cases, the most generic alternative (1) will be
built.
3.7. Prebuilt targets
To link to libraries whose build instructions aren’t given in a Jamfile,
you need to create lib
targets with an appropriate file
property.
Target alternatives can be used to associate multiple library files with
a single conceptual target. For example:
# util/lib2/Jamfile
lib lib2
:
: <file>lib2_release.a <variant>release
;
lib lib2
:
: <file>lib2_debug.a <variant>debug
;
This example defines two alternatives for lib2
, and for each one names
a prebuilt file. Naturally, there are no sources. Instead, the <file>
feature is used to specify the file name.
Once a prebuilt target has been declared, it can be used just like any other target:
exe app : app.cpp ../util/lib2//lib2 ;
As with any target, the alternative selected depends on the properties
propagated from lib2’s dependents. If we build the release and debug
versions of `app
it will be linked with lib2_release.a
and
lib2_debug.a
, respectively.
System libraries — those that are automatically found by the toolset by searching through some set of predetermined paths — should be declared almost like regular ones:
lib pythonlib : : <name>python22 ;
We again don’t specify any sources, but give a name
that should be
passed to the compiler. If the gcc toolset were used to link an
executable target to pythonlib
, -lpython22
would appear in the
command line (other compilers may use different options).
We can also specify where the toolset should look for the library:
lib pythonlib : : <name>python22 <search>/opt/lib ;
And, of course, target alternatives can be used in the usual way:
lib pythonlib : : <name>python22 <variant>release ;
lib pythonlib : : <name>python22_d <variant>debug ;
A more advanced use of prebuilt targets is described in the section called “Targets in site-config.jam”.
4. Overview
This section will provide the information necessary to create your own
projects using B2. The information provided here is relatively
high-level, and the Reference as well as the on-line
help system must be used to obtain low-level documentation (see
--help
).
B2 has two parts — a build engine with its own interpreted
language, and B2 itself, implemented in that language. The
chain of events when you type b2
on the command line is as follows:
-
The B2 executable tries to find B2 modules and loads the top-level module. The exact process is described in the section called “Initialization”
-
The top-level module loads user-defined configuration files,
user-config.jam
andsite-config.jam
, which define available toolsets. -
The Jamfile in the current directory is read. That in turn might cause reading of further Jamfiles. As a result, a tree of projects is created, with targets inside projects.
-
Finally, using the build request specified on the command line, B2 decides which targets should be built and how. That information is passed back to Boost.Jam, which takes care of actually running the scheduled build action commands.
So, to be able to successfully use B2, you need to know only four things:
-
Some Basics about the Boost.Jam language. See the section called “Boost.Jam Language”.
4.1. Concepts
B2 has a few unique concepts that are introduced in this section. The best way to explain the concepts is by comparison with more classical build tools.
When using any flavor of make, you directly specify targets and
commands that are used to create them from other target. The below
example creates a.o
from a.c
using a hardcoded compiler invocation
command.
a.o: a.c
g++ -o a.o -g a.c
This is a rather low-level description mechanism and it’s hard to adjust commands, options, and sets of created targets depending on the compiler and operating system used.
To improve portability, most modern build system provide a set of higher-level functions that can be used in build description files. Consider this example:
add_program ("a", "a.c")
This is a function call that creates the targets necessary to create an
executable file from the source file a.c
. Depending on configured
properties, different command lines may be used. However, add_program
is higher-level, but rather thin level. All targets are created
immediately when the build description is parsed, which makes it
impossible to perform multi-variant builds. Often, change in any build
property requires a complete reconfiguration of the build tree.
In order to support true multi-variant builds, B2 introduces the concept of a metatarget definition main target metatarget metatarget — an object that is created when the build description is parsed and can be called later with specific build properties to generate actual targets.
Consider an example:
exe a : a.cpp ;
When this declaration is parsed, B2 creates a metatarget, but does not yet decide what files must be created, or what commands must be used. After all build files are parsed, B2 considers the properties requested on the command line. Supposed you have invoked B2 with:
b2 toolset=gcc toolset=msvc
In that case, the metatarget will be called twice, once with
toolset=gcc
and once with toolset=msvc
. Both invocations will
produce concrete targets, that will have different extensions and use
different command lines.
Another key concept is build property. A build property is a variable that affects the build process. It can be specified on the command line, and is passed when calling a metatarget. While all build tools have a similar mechanism, B2 differs by requiring that all build properties are declared in advance, and providing a large set of properties with portable semantics.
The final concept is property propagation. B2 does not require that every metatarget is called with the same properties. Instead, the "top-level" metatargets are called with the properties specified on the command line. Each metatarget can elect to augment or override some properties (in particular, using the requirements mechanism, see the section called “Requirements”). Then, the dependency metatargets are called with the modified properties and produce concrete targets that are then used in the build process. Of course, dependency metatargets maybe in turn modify build properties and have dependencies of their own.
For a more in-depth treatment of the requirements and concepts, you may refer to SYRCoSE 2009 B2 article.
4.2. Boost.Jam Language
This section will describe the basics of the Boost.Jam language—just enough for writing Jamfiles. For more information, please see the Boost.Jam documentation.
Boost.Jam has an interpreted, procedural language. On the lowest level, a Boost.Jam program consists of variables and rules (the Jam term for functions). They are grouped into modules—there is one global module and a number of named modules. Besides that, a Boost.Jam program contains classes and class instances.
Syntactically, a Boost.Jam program consists of two kinds of elements—keywords (which have a special meaning to Boost.Jam) and literals. Consider this code:
a = b ;
which assigns the value b
to the variable a
. Here, =
and ;
are
keywords, while a
and b
are literals.
|
⚠
|
All syntax elements, even keywords, must be separated by spaces. For
example, omitting the space character before ; will lead to a syntax
error.
|
If you want to use a literal value that is the same as some keyword, the value can be quoted:
a = "=" ;
All variables in Boost.Jam have the same type—list of
strings. To define a variable one assigns a value to it, like in the
previous example. An undefined variable is the same as a variable with
an empty value. Variables can be accessed using the $(variable)
syntax. For example:
a = $(b) $(c) ;
Rules are defined by specifying the rule name, the parameter names, and the allowed value list size for each parameter.
rule example
(
parameter1 :
parameter2 ? :
parameter3 + :
parameter4 *
)
{
# rule body
}
When this rule is called, the list passed as the first argument must have exactly one value. The list passed as the second argument can either have one value of be empty. The two remaining arguments can be arbitrarily long, but the third argument may not be empty.
The overview of Boost.Jam language statements is given below:
helper 1 : 2 : 3 ;
x = [ helper 1 : 2 : 3 ] ;
This code calls the named rule with the specified arguments. When the result of the call must be used inside some expression, you need to add brackets around the call, like shown on the second line.
if cond { statements } [ else { statements } ]
This is a regular if-statement. The condition is composed of:
-
Literals (true if at least one string is not empty)
-
Comparisons:
a operator b
where operator is one of=
,!=
,<
,>
,⇐
or>=
. The comparison is done pairwise between each string in the left and the right arguments. -
Logical operations:
! a
,a && b
,a || b
-
Grouping:
( cond )
for var in list { statements }
Executes statements for each element in list, setting the variable var
to the element value.
while cond { statements }
Repeatedly execute statements while cond remains true upon entry.
return values ;
This statement should be used only inside a rule and returns values
to
the caller of the rule.
import module ;
import module : rule ;
The first form imports the specified module. All rules from that module
are made available using the qualified name: module.rule
. The second form
imports the specified rules only, and they can be called using unqualified
names.
Sometimes, you need to specify the actual command lines to be used when creating targets. In the jam language, you use named actions to do this. For example:
actions create-file-from-another
{
create-file-from-another $(<) $(>)
}
This specifies a named action called create-file-from-another
. The text
inside braces is the command to invoke. The $(<)
variable will be expanded
to a list of generated files, and the $(>)
variable will be expanded to a
list of source files.
To adjust the command line flexibly, you can define a rule with the same name as the action and taking three parameters — targets, sources and properties. For example:
rule create-file-from-another ( targets * : sources * : properties * )
{
if <variant>debug in $(properties)
{
OPTIONS on $(targets) = --debug ;
}
}
actions create-file-from-another
{
create-file-from-another $(OPTIONS) $(<) $(>)
}
In this example, the rule checks if a certain build property is
specified. If so, it sets the variable OPTIONS
that is then used
inside the action. Note that the variables set "on a target" will be
visible only inside actions building that target, not globally. Were
they set globally, using variable named OPTIONS
in two unrelated
actions would be impossible.
More details can be found in the Jam reference, the section called “Rules”.
4.3. Configuration
On startup, B2 searches and reads three configuration files:
site-config.jam
, user-config.jam
, and project-config.jam
. The
first one is usually installed and maintained by a system administrator,
and the second is for the user to modify. You can edit the one in the
top-level directory of your B2 installation or create a copy in
your home directory and edit the copy. The third is used for project
specific configuration. The following table explains where the files are
searched.
| site-config.jam | user-config.jam | project-config.jam | |
|---|---|---|---|
Linux |
|
|
… |
Windows |
|
|
… |
Any of these files may also be overridden on the command line.
|
☀
|
You can use the --debug-configuration option to find which
configuration files are actually loaded.
|
Usually, user-config.jam
just defines the available compilers and
other tools (see the section called “Targets
in site-config.jam” for more advanced usage). A tool is configured using
the following syntax:
using tool-name : ... ;
The using
rule is given the name of tool, and will make that tool
available to B2. For example,
using gcc ;
will make the GCC compiler available.
|
☀
|
You can put using <tool> ; with no other argument in a Jamfile
that needs the tool , provided that the tool supports this usage.
In all other cases, the using rule should be in a configuration file.
The general principle is that descriptions in Jamfile should be
maintained as portable while configuration files are system specific.
|
All the supported tools are documented in the section called “Builtin tools”, including the specific options they take. Some general notes that apply to most C++ compilers are below.
For all the C++ compiler toolsets that B2 supports
out-of-the-box, the list of parameters to using
is the same:
toolset-name
, version
, invocation-command
, and options
.
If you have a single compiler, and the compiler executable
-
has its “usual name” and is in the
PATH
, or -
was installed in a standard “installation directory”, or
-
can be found using a global system like the Windows registry.
it can be configured by simply:
using tool-name ;
If the compiler is installed in a custom directory, you should provide the command that invokes the compiler, for example:
using gcc : : g++-3.2 ;
using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ;
Some B2 toolsets will use that path to take additional actions required before invoking the compiler, such as calling vendor-supplied scripts to set up its required environment variables. When the compiler executables for C and C++ are different, the path to the C++ compiler executable must be specified. The command can be any command allowed by the operating system. For example:
using msvc : : echo Compiling && foo/bar/baz/cl ;
will work.
To configure several versions of a toolset, simply invoke the using
rule multiple times:
using gcc : 3.3 ;
using gcc : 3.4 : g++-3.4 ;
using gcc : 3.2 : g++-3.2 ;
using gcc : 5 ;
using clang : 3.9 ;
using msvc : 14.0 ;
Note that in the first call to using
, the compiler found in the PATH
will be used, and there is no need to explicitly specify the command.
Many of toolsets have an options
parameter to fine-tune the
configuration. All of B2’s standard compiler toolsets accept
four options cflags
, cxxflags
, compileflags
and linkflags
as
options
specifying flags that will be always passed to the
corresponding tools. There must not be a space between the tag for the
option name and the value. Values of the cflags
feature are passed
directly to the C compiler, values of the cxxflags
feature are passed
directly to the C++ compiler, and values of the compileflags
feature
are passed to both. For example, to configure a gcc
toolset so that it
always generates 64-bit code you could write:
using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ;
If multiple of the same type of options are needed, they can be concatenated with quotes or have multiple instances of the option tag.
using gcc : 5 : : <cxxflags>"-std=c++14 -O2" ;
using clang : 3.9 : : <cxxflags>-std=c++14 <cxxflags>-O2 ;
Multiple variations of the same tool can be used for most tools. These are delineated by the version passed in. Because the dash '-' cannot be used here, the convention has become to use the tilde '~' to delineate variations.
using gcc : 5 : g++-5 : ; # default is C++ 98
using gcc : 5~c++03 : g++-5 : <cxxflags>-std=c++03 ; # C++ 03
using gcc : 5~gnu03 : g++-5 : <cxxflags>-std=gnu++03 ; # C++ 03 with GNU
using gcc : 5~c++11 : g++-5 : <cxxflags>-std=c++11 ; # C++ 11
using gcc : 5~c++14 : g++-5 : <cxxflags>-std=c++14 ; # C++ 14
These are then used as normal toolsets:
b2 toolset=gcc-5 stage
b2 toolset=gcc-5~c++14 stage
|
⚠
|
Although the syntax used to specify toolset options is very similar to syntax used to specify requirements in Jamfiles, the toolset options are not the same as features. Don’t try to specify a feature value in toolset initialization. |
4.4. Invocation
To invoke B2, type b2
on the command line. Three kinds of
command-line tokens are accepted, in any order:
- options
-
Options start with either one or two dashes. The standard options are listed below, and each project may add additional options
- properties
-
Properties specify details of what you want to build (e.g. debug or release variant). Syntactically, all command line tokens with an equal sign in them are considered to specify properties. In the simplest form, a property looks like
feature=value
- target
-
All tokens that are neither options nor properties specify what targets to build. The available targets entirely depend on the project you are building.
4.4.1. Examples
To build all targets defined in the Jamfile in the current directory with the default properties, run:
b2
To build specific targets, specify them on the command line:
b2 lib1 subproject//lib2
To request a certain value for some property, add property=value
to the
command line:
b2 toolset=gcc variant=debug optimization=space
4.4.2. Options
B2 recognizes the following command line options.
--help
-
Invokes the online help system. This prints general information on how to use the help system with additional --help* options.
--clean
-
Cleans all targets in the current directory and in any sub-projects. Note that unlike the
clean
target in make, you can use--clean
together with target names to clean specific targets. --clean-all
-
Cleans all targets, no matter where they are defined. In particular, it will clean targets in parent Jamfiles, and targets defined under other project roots.
--build-dir
-
Changes the build directories for all project roots being built. When this option is specified, all Jamroot files must declare a project name. The build directory for the project root will be computed by concatenating the value of the
--build-dir
option, the project name specified in Jamroot, and the build dir specified in Jamroot (orbin
, if none is specified). The option is primarily useful when building from read-only media, when you can’t modify Jamroot. --abbreviate-paths
-
Compresses target paths by abbreviating each component. This option is useful to keep paths from becoming longer than the filesystem supports. See also the section called “Target Paths”.
--hash
-
Compresses target paths using an MD5 hash. This option is useful to keep paths from becoming longer than the filesystem supports. This option produces shorter paths than
--abbreviate-paths
does, but at the cost of making them less understandable. See also the section called “Target Paths”. --version
-
Prints information on the B2 and Boost.Jam versions.
-a
-
Causes all files to be rebuilt.
-n
-
Do not execute the commands, only print them.
-q
-
Stop at the first error, as opposed to continuing to build targets that don’t depend on the failed ones.
-j N
-
Run up to N commands in parallel. Default number of jobs is the number of detected available CPU threads. Note: There are circumstances when that default can be larger than the allocated cpu resources, for instance in some virtualized container installs.
--config=filename
-
Override all configuration files
--site-config=filename
-
Override the default site-config.jam
--user-config=filename
-
Override the default user-config.jam
--project-config=filename
-
Override the default project-config.jam
--debug-configuration
-
Produces debug information about the loading of B2 and toolset files.
--debug-building
-
Prints what targets are being built and with what properties.
--debug-generators
-
Produces debug output from the generator search process. Useful for debugging custom generators.
-d0
-
Suppress all informational messages.
-d N
-
Enable cumulative debugging levels from 1 to n. Values are: +
-
Show the actions taken for building targets, as they are executed (the default).
-
Show "quiet" actions and display all action text, as they are executed.
-
Show dependency analysis, and target/source timestamps/paths.
-
Show arguments and timing of shell invocations.
-
Show rule invocations and variable expansions.
-
Show directory/header file/archive scans, and attempts at binding to targets.
-
Show variable settings.
-
Show variable fetches, variable expansions, and evaluation of '"if"' expressions.
-
Show variable manipulation, scanner tokens, and memory usage.
-
Show profile information for rules, both timing and memory.
-
Show parsing progress of Jamfiles.
-
Show graph of target dependencies.
-
Show change target status (fate).
-
-d +N
-
Enable debugging level
N
. -o file
-
Write the updating actions to the specified file instead of running them.
-s var=value
-
Set the variable
var
tovalue
in the global scope of the jam language interpreter, overriding variables imported from the environment.
4.4.3. Properties
In the simplest case, the build is performed with a single set of
properties, that you specify on the command line with elements in the
form feature=value
. The complete list of features can be found in
the section called “Builtin features”.
The most common features are summarized below.
| Feature | Allowed values | Notes |
|---|---|---|
variant |
debug,release |
|
link |
shared,static |
Determines if B2 creates shared or static libraries |
threading |
single,multi |
Cause the produced binaries to be thread-safe. This requires proper support in the source code itself. |
address-model |
32,64 |
Explicitly request either 32-bit or 64-bit code generation. This typically requires that your compiler is appropriately configured. Please refer to the section called “C++ Compilers” and your compiler documentation in case of problems. |
toolset |
(Depends on configuration) |
The C++ compiler to use. See the section called “C++ Compilers” for a detailed list. |
include |
(Arbitrary string) |
Additional include paths for C and C++ compilers. |
define |
(Arbitrary string) |
Additional macro definitions for C and C++ compilers. The string should be
either |
cxxflags |
(Arbitrary string) |
Custom options to pass to the C++ compiler. |
cflags |
(Arbitrary string) |
Custom options to pass to the C compiler. |
linkflags |
(Arbitrary string) |
Custom options to pass to the C++ linker. |
runtime-link |
shared,static |
Determines if shared or static version of C and C++ runtimes should be used. |
If you have more than one version of a given C++ toolset (e.g.
configured in user-config.jam
, or autodetected, as happens with msvc),
you can request the specific version by passing toolset-version
as the
value of the toolset
feature, for example toolset=msvc-8.0
.
If a feature has a fixed set of values it can be specified more than once on the command line. In which case, everything will be built several times — once for each specified value of a feature. For example, if you use
b2 link=static link=shared threading=single threading=multi
Then a total of 4 builds will be performed. For convenience, instead of specifying all requested values of a feature in separate command line elements, you can separate the values with commas, for example:
b2 link=static,shared threading=single,multi
The comma has this special meaning only if the feature has a fixed set of values, so
b2 include=static,shared
is not treated specially.
Multiple features may be grouped by using a forwards slash.
b2 gcc/link=shared msvc/link=static,shared
This will build 3 different variants, altogether.
4.4.4. Targets
All command line elements that are neither options nor properties are the names of the targets to build. See the section called “Target identifiers and references”. If no target is specified, the project in the current directory is built.
4.5. Declaring Targets
A Main target is a user-defined named entity that can be built, for example an executable file. Declaring a main target is usually done using one of the main target rules described in the section called “Builtin rules”. The user can also declare custom main target rules as shown in the section called “Main target rules”.
rule rule-name (
main-target-name :
sources + :
requirements * :
default-build * :
usage-requirements * )
-
main-target-name
is the name used to request the target on command line and to use it from other main targets. A main target name may contain alphanumeric characters, dashes (‘-
’), and underscores (‘_
’). -
sources
is the list of source files and other main targets that must be combined. -
requirements
is the list of properties that must always be present when this main target is built. -
default-build
is the list of properties that will be used unless some other value of the same feature is already specified, e.g. on the command line or by propagation from a dependent target. -
usage-requirements
is the list of properties that will be propagated to all main targets that use this one, i.e. to all its dependents.
Some main target rules have a different list of parameters as explicitly stated in their documentation.
The actual requirements for a target are obtained by refining the requirements of the project where the target is declared with the explicitly specified requirements. The same is true for usage-requirements. More details can be found in the section called “Property refinement”.
4.5.1. Name
The name of main target has two purposes. First, it’s used to refer to this target from other targets and from command line. Second, it’s used to compute the names of the generated files. Typically, filenames are obtained from main target name by appending system-dependent suffixes and prefixes.
The name of a main target can contain alphanumeric characters, dashes, underscores and dots. The entire name is significant when resolving references from other targets. For determining filenames, only the part before the first dot is taken. For example:
obj test.release : test.cpp : <variant>release ;
obj test.debug : test.cpp : <variant>debug ;
will generate two files named test.obj
(in two different directories),
not two files named test.release.obj
and test.debug.obj
.
4.5.2. Sources
The list of sources specifies what should be processed to get the resulting targets. Most of the time, it’s just a list of files. Sometimes, you’ll want to automatically construct the list of source files rather than having to spell it out manually, in which case you can use the glob rule. Here are two examples:
exe a : a.cpp ; (1)
exe b : [ glob *.cpp ] ; (2)
-
a.cpp
is the only source file -
all
.cpp
files in this directory are sources
Unless you specify a file with an absolute path, the name is considered relative to the source directory — which is typically the directory where the Jamfile is located, but can be changed as described in the section called “Projects”.
The list of sources can also refer to other main targets. Targets in the same project can be referred to by name, while targets in other projects must be qualified with a directory or a symbolic project name. The directory/project name is separated from the target name by a double forward slash. There is no special syntax to distinguish the directory name from the project name—the part before the double slash is first looked up as project name, and then as directory name. For example:
lib helper : helper.cpp ;
exe a : a.cpp helper ;
exe b : b.cpp ..//utils ; (1)
exe c : c.cpp /boost/program_options//program_options ;
-
Since all project ids start with slash, “..” is a directory name.
The first exe uses the library defined in the same project. The second one uses some target (most likely a library) defined by a Jamfile one level higher. Finally, the third target uses a C++ Boost library, referring to it using its absolute symbolic name. More information about target references can be found in the section called “Dependent Targets” and the section called “Target identifiers and references”.
4.5.3. Requirements
Requirements are the properties that should always be present when building a target. Typically, they are includes and defines:
exe hello : hello.cpp : <include>/opt/boost <define>MY_DEBUG ;
There are a number of other features, listed in the section called “Builtin features”. For example if a library can only be built statically, or a file can’t be compiled with optimization due to a compiler bug, one can use.
lib util : util.cpp : <link>static ;
obj main : main.cpp : <optimization>off ;
Sometimes, particular
relationships need to be
maintained among a target’s build properties. This can be achieved with
conditional requirements. For example, you might want to set specific
#defines
when a library is built as shared, or when a target’s
release
variant is built in release mode.
lib network : network.cpp
: <link>shared:<define>NETWORK_LIB_SHARED
<variant>release:<define>EXTRA_FAST
;
In the example above, whenever network
is built with <link>shared
,
<define>NETWORK_LIB_SHARED
will be in its properties, too.
You can use several properties in the condition, for example:
lib network : network.cpp
: <toolset>gcc,<optimization>speed:<define>USE_INLINE_ASSEMBLER
;
A more powerful variant of conditional requirements is indirect conditional requirements. You can provide a rule that will be called with the current build properties and can compute additional properties to be added. For example:
lib network : network.cpp
: <conditional>@my-rule
;
rule my-rule ( properties * )
{
local result ;
if <toolset>gcc <optimization>speed in $(properties)
{
result += <define>USE_INLINE_ASSEMBLER ;
}
return $(result) ;
}
This example is equivalent to the previous one, but for complex cases, indirect conditional requirements can be easier to write and understand.
Requirements explicitly specified for a target are usually combined with the requirements specified for the containing project. You can cause a target to completely ignore a specific project requirement using the syntax by adding a minus sign before the property, for example:
exe main : main.cpp : -<define>UNNECESSARY_DEFINE ;
This syntax is the only way to ignore free properties, such as defines, from a parent. It can be also useful for ordinary properties. Consider this example:
project test : requirements <threading>multi ;
exe test1 : test1.cpp ;
exe test2 : test2.cpp : <threading>single ;
exe test3 : test3.cpp : -<threading>multi ;
Here, test1
inherits the project requirements and will always be built
in multi-threaded mode. The test2
target overrides the project’s
requirements and will always be built in single-threaded mode. In
contrast, the test3
target removes a property from the project
requirements and will be built either in single-threaded or
multi-threaded mode depending on which variant is requested by the user.
Note that the removal of requirements is completely textual: you need to specify exactly the same property to remove it.
4.5.4. Default Build
The default-build
parameter is a set of properties to be used if the
build request does not otherwise specify a value for features in the
set. For example:
exe hello : hello.cpp : : <threading>multi ;
would build a multi-threaded target unless the user explicitly requests a single-threaded version. The difference between the requirements and the default-build is that the requirements cannot be overridden in any way.
4.5.5. Additional Information
The ways a target is built can be so different that describing them using conditional requirements would be hard. For example, imagine that a library actually uses different source files depending on the toolset used to build it. We can express this situation using target alternatives:
lib demangler : dummy_demangler.cpp ; # alternative 1
lib demangler : demangler_gcc.cpp : <toolset>gcc ; # alternative 2
lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3
In the example above, when built with gcc
or msvc
, demangler
will
use a source file specific to the toolset. Otherwise, it will use a
generic source file, dummy_demangler.cpp
.
It is possible to declare a target inline, i.e. the "sources" parameter may include calls to other main rules. For example:
exe hello : hello.cpp
[ obj helpers : helpers.cpp : <optimization>off ] ;
Will cause "helpers.cpp" to be always compiled without optimization.
When referring to an inline main target, its declared name must be
prefixed by its parent target’s name and two dots. In the example above,
to build only helpers, one should run b2 hello..helpers
.
When no target is requested on the command line, all targets in the current project will be built. If a target should be built only by explicit request, this can be expressed by the explicit rule:
explicit install_programs ;
4.6. Projects
As mentioned before, targets are grouped into projects, and each Jamfile is a separate project. Projects are useful because they allow us to group related targets together, define properties common to all those targets, and assign a symbolic name to the project that can be used in referring to its targets.
Projects are named using the project
rule, which has the following
syntax:
project id : attributes ;
Here, attributes is a sequence of rule arguments, each of which begins with an attribute-name and is followed by any number of build properties. The list of attribute names along with its handling is also shown in the table below. For example, it is possible to write:
project tennis
: requirements <threading>multi
: default-build release
;
The possible attributes are listed below.
Project id is a short way to denote a project, as opposed to the Jamfile’s pathname. It is a hierarchical path, unrelated to filesystem, such as "boost/thread". Target references make use of project ids to specify a target.
Source location specifies the directory where sources for the project are located.
Project requirements are requirements that apply to all the targets in the projects as well as all sub-projects.
Default build is the build request that should be used when no build request is specified explicitly.
The default values for those attributes are given in the table below.
| Attribute | Name | Default value | Handling by the project rule |
|---|---|---|---|
Project id |
none |
none |
Assigned from the first parameter of the 'project' rule. It is assumed to denote absolute project id. |
Source location |
|
The location of jamfile for the project |
Sets to the passed value |
Requirements |
|
The parent’s requirements |
The parent’s requirements are refined with the passed requirement and the result is used as the project requirements. |
Default build |
|
none |
Sets to the passed value |
Build directory |
|
Empty if the parent has no build directory set. Otherwise, the parent’s build directory with the relative path from parent to the current project appended to it. |
Sets to the passed value, interpreted as relative to the project’s location. |
Besides defining projects and main targets, Jamfiles often invoke various utility rules. For the full list of rules that can be directly used in Jamfile see the section called “Builtin rules”.
Each subproject inherits attributes, constants and rules from its parent
project, which is defined by the nearest Jamfile in an ancestor
directory above the subproject. The top-level project is declared in a
file called Jamroot
, or Jamfile
. When loading a project,
B2 looks for either Jamroot
or Jamfile
. They are handled
identically, except that if the file is called Jamroot
, the search for
a parent project is not performed. A Jamfile
without a parent project
is also considered the top-level project.
Even when building in a subproject directory, parent project files are
always loaded before those of their sub-projects, so that every
definition made in a parent project is always available to its children.
The loading order of any other projects is unspecified. Even if one
project refers to another via the use-project
or a target reference,
no specific order should be assumed.
|
ℹ
|
Giving the root project the special name “Jamroot ” ensures that
B2 won’t misinterpret a directory above it as the project root
just because the directory contains a Jamfile.
|
4.7. The Build Process
When you’ve described your targets, you want B2 to run the right tools and create the needed targets. This section will describe two things: how you specify what to build, and how the main targets are actually constructed.
The most important thing to note is that in B2, unlike other build tools, the targets you declare do not correspond to specific files. What you declare in a Jamfile is more like a “metatarget.” Depending on the properties you specify on the command line, each metatarget will produce a set of real targets corresponding to the requested properties. It is quite possible that the same metatarget is built several times with different properties, producing different files.
|
☀
|
This means that for B2, you cannot directly obtain a build variant from a Jamfile. There could be several variants requested by the user, and each target can be built with different properties. |
4.7.1. Build Request
The command line specifies which targets to build and with which properties. For example:
b2 app1 lib1//lib1 toolset=gcc variant=debug optimization=full
would build two targets, "app1" and "lib1//lib1" with the specified properties. You can refer to any targets, using target id and specify arbitrary properties. Some of the properties are very common, and for them the name of the property can be omitted. For example, the above can be written as:
b2 app1 lib1//lib1 gcc debug optimization=full
The complete syntax, which has some additional shortcuts, is described in the section called “Invocation”.
4.7.2. Building a main target
When you request, directly or indirectly, a build of a main target with specific requirements, the following steps are done. Some brief explanation is provided, and more details are given in the section called “Build process”.
-
Applying default build. If the default-build property of a target specifies a value of a feature that is not present in the build request, that value is added.
-
Selecting the main target alternative to use. For each alternative we look how many properties are present both in alternative’s requirements, and in build request. The alternative with largest number of matching properties is selected.
-
Determining "common" properties. The build request is refined with target’s requirements. The conditional properties in requirements are handled as well. Finally, default values of features are added.
-
Building targets referred by the sources list and dependency properties. The list of sources and the properties can refer to other target using target references. For each reference, we take all propagated properties, refine them by explicit properties specified in the target reference, and pass the resulting properties as build request to the other target.
-
Adding the usage requirements produced when building dependencies to the "common" properties. When dependencies are built in the previous step, they return both the set of created "real" targets, and usage requirements. The usage requirements are added to the common properties and the resulting property set will be used for building the current target.
-
Building the target using generators. To convert the sources to the desired type, B2 uses "generators" — objects that correspond to tools like compilers and linkers. Each generator declares what type of targets it can produce and what type of sources it requires. Using this information, B2 determines which generators must be run to produce a specific target from specific sources. When generators are run, they return the "real" targets.
-
Computing the usage requirements to be returned. The conditional properties in usage requirements are expanded and the result is returned.
4.7.3. Building a Project
Often, a user builds a complete project, not just one main target. In
fact, invoking b2
without arguments builds the project defined in the
current directory.
When a project is built, the build request is passed without
modification to all main targets in that project. It’s is possible to
prevent implicit building of a target in a project with the explicit
rule:
explicit hello_test ;
would cause the hello_test
target to be built only if explicitly
requested by the user or by some other target.
The Jamfile for a project can include a number of build-project
rule
calls that specify additional projects to be built.
5. Common tasks
This section describes main targets types that B2 supports out-of-the-box. Unless otherwise noted, all mentioned main target rules have the common signature, described in the section called “Declaring Targets”.
5.1. Programs
Programs are created using the exe
rule, which follows the
common syntax. For example:
exe hello
: hello.cpp some_library.lib /some_project//library
: <threading>multi
;
This will create an executable file from the sources—in this case, one C++ file, one library file present in the same directory, and another library that is created by B2. Generally, sources can include C and C++ files, object files and libraries. B2 will automatically try to convert targets of other types.
|
☀
|
On Windows, if an application uses shared libraries, and both the
application and the libraries are built using B2, it is not
possible to immediately run the application, because the PATH environment
variable should include the path to the libraries. It means you have to either
add the paths manually, or have the build place the application and the
libraries into the same directory. See
the section called “Installing”.
|
5.2. Libraries
Library targets are created using the lib
rule, which follows the
common syntax. For example:
lib helpers : helpers.cpp ;
This will define a library target named helpers
built from the
helpers.cpp
source file. It can be either a static library or a shared
library, depending on the value of the
<link>
feature.
Library targets can represent:
-
Libraries that should be built from source, as in the example above.
-
Prebuilt libraries which already exist on the system. Such libraries can be searched for by the tools using them (typically with the linker’s
-l
option) or their paths can be known in advance by the build system.
The syntax for prebuilt libraries is given below:
lib z : : <name>z <search>/home/ghost ;
lib compress : : <file>/opt/libs/compress.a ;
The name
property specifies the name of the library without the
standard prefixes and suffixes. For example, depending on the system,
z
could refer to a file called z.so
, libz.a
, or z.lib
, etc. The
search
feature specifies paths in which to search for the library in
addition to the default compiler paths. search
can be specified
several times or it can be omitted, in which case only the default
compiler paths will be searched. The file
property specifies the file
location.
The difference between using the file
feature and using a combination
of the name
and search
features is that file
is more precise.
|
⚠
|
The value of the
If /pool/release/a.so, /pool/release/b.so, /pool/debug/a.so, and
/pool/release/b.so all exist, the linker will probably take both |
For convenience, the following syntax is allowed:
lib z ;
lib gui db aux ;
which has exactly the same effect as:
lib z : : <name>z ;
lib gui : : <name>gui ;
lib db : : <name>db ;
lib aux : : <name>aux ;
When a library references another library you should put that other library in its list of sources. This will do the right thing in all cases. For portability, you should specify library dependencies even for searched and prebuilt libraries, otherwise, static linking on Unix will not work. For example:
lib z ;
lib png : z : <name>png ;
|
ℹ
|
When a library has a shared library as a source, or a static library has another static library as a source then any target linking to the first library with automatically link to its source library as well. On the other hand, when a shared library has a static library as a source then the first library will be built so that it completely includes the second one. If you do not want a shared library to include all the libraries specified in its sources (especially statically linked ones), you would need to use the following:
This specifies that library |
Usage requirements are often very useful
for defining library targets. For example, imagine that you want you
build a helpers
library and its interface is described in its
helpers.hpp
header file located in the same directory as the
helpers.cpp
source file. Then you could add the following to the
Jamfile located in that same directory:
lib helpers : helpers.cpp : : : <include>. ;
which would automatically add the directory where the target has been
defined (and where the library’s header file is located) to the
compiler’s include path for all targets using the helpers
library.
This feature greatly simplifies Jamfiles.
5.3. Alias
The alias
rule gives an alternative name to a group of targets. For
example, to give the name core
to a group of three other targets with
the following code:
alias core : im reader writer ;
Using core
on the command line, or in the source list of any other
target is the same as explicitly using im
, reader
, and writer
.
Another use of the alias
rule is to change build properties. For
example, if you want to link statically to the Boost Threads
library, you can write the following:
alias threads : /boost/thread//boost_thread : <link>static ;
and use only the threads
alias in your Jamfiles.
You can also specify usage requirements for the alias
target. If you
write the following:
alias header_only_library : : : : <include>/usr/include/header_only_library ;
then using header_only_library
in sources will only add an include
path. Also note that when an alias has sources, their usage requirements
are propagated as well. For example:
lib library1 : library1.cpp : : : <include>/library/include1 ;
lib library2 : library2.cpp : : : <include>/library/include2 ;
alias static_libraries : library1 library2 : <link>static ;
exe main : main.cpp static_libraries ;
will compile main.cpp
with additional includes required for using the
specified static libraries.
5.4. Installing
This section describes various ways to install built targets and arbitrary files.
5.4.1. Basic install
For installing a built target you should use the install
rule, which
follows the common syntax. For
example:
install dist : hello helpers ;
will cause the targets hello
and helpers
to be moved to the dist
directory, relative to the Jamfile’s directory. The directory can be
changed using the location
property:
install dist : hello helpers : <location>/usr/bin ;
While you can achieve the same effect by changing the target name to
/usr/bin
, using the location
property is better as it allows you to
use a mnemonic target name.
The location
property is especially handy when the location is not
fixed, but depends on the build variant or environment variables:
install dist : hello helpers :
<variant>release:<location>dist/release
<variant>debug:<location>dist/debug ;
install dist2 : hello helpers : <location>$(DIST) ;
See also conditional properties and environment variables
5.4.2. Installing with all dependencies
Specifying the names of all libraries to install can be boring. The
install
allows you to specify only the top-level executable targets to
install, and automatically install all dependencies:
install dist : hello :
<install-dependencies>on <install-type>EXE
<install-type>LIB
;
will find all targets that hello
depends on, and install all of those
which are either executables or libraries. More specifically, for each
target, other targets that were specified as sources or as dependency
properties, will be recursively found. One exception is that targets
referred with the use
feature are not
considered, as that feature is typically used to refer to header-only
libraries. If the set of target types is specified, only targets of that
type will be installed, otherwise, all found target will be installed.
5.4.3. Preserving Directory Hierarchy
By default, the install
rule will strip paths from its sources. So, if
sources include a/b/c.hpp
, the a/b
part will be ignored. To make the
install
rule preserve the directory hierarchy you need to use the
<install-source-root>
feature to specify the root of the hierarchy you
are installing. Relative paths from that root will be preserved. For
example, if you write:
install headers
: a/b/c.h
: <location>/tmp <install-source-root>a
;
the a file named /tmp/b/c.h
will be created.
The glob-tree
rule can be used to find
all files below a given directory, making it easy to install an entire
directory tree.
5.4.4. Installing into Several Directories
The alias
rule can be used when targets need
to be installed into several directories:
alias install : install-bin install-lib ;
install install-bin : applications : /usr/bin ;
install install-lib : helper : /usr/lib ;
Because the install
rule just copies targets, most free features
[3]
have no effect when used in requirements of the install
rule. The only two
that matter are
dependency
and, on Unix,
dll-path
.
|
ℹ
|
(Unix specific) On Unix, executables built using B2 typically
contain the list of paths to all used shared libraries. For installing,
this is not desired, so B2 relinks the executable with an empty
list of paths. You can also specify additional paths for installed
executables using the dll-path feature.
|
5.5. Testing
B2 has convenient support for running unit tests. The simplest
way is the unit-test
rule, which follows the
common syntax. For example:
unit-test helpers_test : helpers_test.cpp helpers ;
The unit-test
rule behaves like the exe
rule, but after the executable is created it is also run. If the
executable returns an error code, the build system will also return an
error and will try running the executable on the next invocation until
it runs successfully. This behavior ensures that you can not miss a
unit test failure.
There are few specialized testing rules, listed below:
rule compile ( sources : requirements * : target-name ? )
rule compile-fail ( sources : requirements * : target-name ? )
rule link ( sources + : requirements * : target-name ? )
rule link-fail ( sources + : requirements * : target-name ? )
They are given a list of sources and requirements. If the target name is
not provided, the name of the first source file is used instead. The
compile*
tests try to compile the passed source. The link*
rules try
to compile and link an application from all the passed sources. The
compile
and link
rules expect that compilation/linking succeeds. The
compile-fail
and link-fail
rules expect that the
compilation/linking fails.
There are two specialized rules for running executables, which are more
powerful than the unit-test
rule. The run
rule has the following
signature:
rule run ( sources + : args * : input-files * : requirements * : target-name ?
: default-build * )
The rule builds application from the provided sources and runs it,
passing args
and input-files
as command-line arguments. The args
parameter is passed verbatim and the values of the input-files
parameter are treated as paths relative to containing Jamfile, and are
adjusted if b2
is invoked from a different directory. The run-fail
rule is identical to the run
rule, except that it expects that the run
fails.
All rules described in this section, if executed successfully, create a
special manifest file to indicate that the test passed. For the
unit-test
rule the files is named target-name.passed
and for the other
rules it is called target-name.test
. The run*
rules also capture all
output from the program, and store it in a file named target-name.output
.
If the preserve-test-targets
feature has the
value off
, then run
and the run-fail
rules will remove the
executable after running it. This somewhat decreases disk space
requirements for continuous testing environments. The default value of
preserve-test-targets
feature is on
.
It is possible to print the list of all test targets (except for
unit-test
) declared in your project, by passing the --dump-tests
command-line option. The output will consist of lines of the form:
boost-test(test-type) path : sources
It is possible to process the list of tests, B2 output and the
presence/absence of the *.test
files created when test passes into
human-readable status table of tests. Such processing utilities are not
included in B2.
The following features adjust behavior of the testing metatargets.
testing.arg
-
Defines an argument to be passed to the target when it is executed before the list of input files.
unit-test helpers_test : helpers_test.cpp helpers : <testing.arg>"--foo bar" ;
testing.input-file
-
Specifies a file to be passed to the executable on the command line after the arguments. All files must be specified in alphabetical order due to constraints in the current implementation.
testing.launcher
-
By default, the executable is run directly. Sometimes, it is desirable to run the executable using some helper command. You should use this property to specify the name of the helper command. For example, if you write:
unit-test helpers_test : helpers_test.cpp helpers : <testing.launcher>valgrind ;
The command used to run the executable will be:
valgrind bin/$toolset/debug/helpers_test
test-info
-
A description of the test. This is displayed as part of the
--dump-tests
command-line option.
5.6. Custom commands
For most main target rules, B2 automatically figures out the commands to run. When you want to use new file types or support new tools, one approach is to extend B2 to support them smoothly, as documented in Extender Manual. However, if the new tool is only used in a single place, it might be easier just to specify the commands to run explicitly.
Three main target rules can be used for that. The make
rule allows you to
construct a single file from any number of source file, by running a command
you specify. The notfile
rule allows you to run an arbitrary command,
without creating any files.  This is
higher-level than the file names that the make
rule operates with and
allows you to create more than one target, create differently named targets
depending on properties, or use more than one tool.
The make
rule is used when you want to create one file from a number
of sources using some specific command. The notfile
is used to
unconditionally run a command.
Suppose you want to create the file file.out
from the file file.in
by running the command in2out
. Here is how you would do this in B2:
make file.out : file.in : @in2out ;
actions in2out
{
in2out $(<) $(>)
}
If you run b2
and file.out
does not exist, B2 will run the
in2out
command to create that file. For more details on specifying
actions, see
the section called “Boost.Jam Language”.
It could be that you just want to run some command unconditionally, and
that command does not create any specific files. For that you can use
the notfile
rule. For example:
notfile echo_something : @echo ;
actions echo
{
echo "something"
}
The only difference from the make
rule is that the name of the target
is not considered a name of a file, so B2 will unconditionally
run the action.
The generate
rule is used when you want to express transformations
using B2’s virtual targets, as opposed to just filenames. The
generate
rule has the standard main target rule signature, but you are
required to specify the generating-rule
property. The value of the
property should be in the form @rule-name
, the named rule should have the
following signature:
rule generating-rule ( project name : property-set : sources * )
and will be called with an instance of the project-target
class, the
name of the main target, an instance of the property-set
class
containing build properties, and the list of instances of the
virtual-target
class corresponding to sources. The rule must return a
list of virtual-target
instances. The interface of the
virtual-target
class can be learned by looking at the
build/virtual-target.jam
file. The generate
example contained in the
B2 distribution illustrates how the generate
rule can be
used.
5.7. Precompiled Headers
Precompiled headers is a mechanism to speed up compilation by creating a partially processed version of some header files, and then using that version during compilations rather then repeatedly parsing the original headers. B2 supports precompiled headers with gcc and msvc toolsets.
To use precompiled headers, follow the following steps:
-
Create a header that includes headers used by your project that you want precompiled. It is better to include only headers that are sufficiently stable — like headers from the compiler and external libraries. B2 will include the header automatically and on-demand.
-
Declare a new B2 target for the precompiled header and add that precompiled header to the sources of the target whose compilation you want to speed up:
cpp-pch pch : pch.hpp ; exe main : main.cpp pch ;
You can use the
c-pch
rule if you want to use the precompiled header in C programs.
The pch
example in B2 distribution can be used as reference.
Please note the following:
-
The build properties used to compile the source files and the precompiled header must be the same. Consider using project requirements to assure this.
-
Precompiled headers must be used purely as a way to improve compilation time, not to save the number of
#include
statements. If a source file needs to include some header, explicitly include it in the source file, even if the same header is included from the precompiled header. This makes sure that your project will build even if precompiled headers are not supported. -
Prior to version 4.2, the gcc compiler did not allow anonymous namespaces in precompiled headers, which limits their utility. See the bug report for details.
-
Previosuly B2 had not been automatically inluding the header, a user was required to include the header at the top of every source file the precompiled header will be used with.
5.8. Generated headers
Usually, B2 handles implicit dependencies completely
automatically. For example, for C++ files, all #include
statements are
found and handled. The only aspect where user help might be needed is
implicit dependency on generated files.
By default, B2 handles such dependencies within one main target. For example, assume that main target "app" has two sources, "app.cpp" and "parser.y". The latter source is converted into "parser.c" and "parser.h". Then, if "app.cpp" includes "parser.h", B2 will detect this dependency. Moreover, since "parser.h" will be generated into a build directory, the path to that directory will automatically be added to the include path.
Making this mechanism work across main target boundaries is possible,
but imposes certain overhead. For that reason, if there is implicit
dependency on files from other main targets, the <implicit-dependency>
feature must be used, for example:
lib parser : parser.y ;
exe app : app.cpp : <implicit-dependency>parser ;
The above example tells the build system that when scanning all sources of "app" for implicit-dependencies, it should consider targets from "parser" as potential dependencies.
5.9. Cross-compilation
B2 supports cross compilation with the gcc and msvc toolsets.
When using gcc, you first need to specify your cross compiler in
user-config.jam
(see
the section called “Configuration”), for
example:
using gcc : arm : arm-none-linux-gnueabi-g++ ;
After that, if the host and target os are the same, for example Linux, you can just request that this compiler version be used:
b2 toolset=gcc-arm
If you want to target a different operating system from the host, you
need to additionally specify the value for the target-os
feature, for
example:
# On windows box
b2 toolset=gcc-arm target-os=linux
# On Linux box
b2 toolset=gcc-mingw target-os=windows
For the complete list of allowed operating system names, please see the documentation for target-os feature.
When using the msvc compiler, it’s only possible to cross-compile to a 64-bit system on a 32-bit host. Please see the section called “64-bit support” for details.
5.10. Package Managers
B2 support automatic, or manual, loading of generated build files
from package managers. For example using the Conan package manager which
generates conanbuildinfo.jam
files B2 will load that files automatically
when it loads the project at the same location. The included file can
define targets and other project declarations in the context of the
project it’s being loaded into. Control over what package manager file
is loaded can be controlled with (in order of priority):
-
With the
use-packages
rule. -
Command line argument
--use-package-manager=X
. -
Environment variable
PACKAGE_MANAGER_BUILD_INFO
. -
Built-in detection of the file. Currently this includes: "conan".
use-packages
rule:
rule use-packages ( name-or-glob-pattern ? )
The use-packages
rule allows one to specify in the projects themselves kind
of package definitions to use either as the ones for a built-in package
manager support. For example:
use-packages conan ;
Or to specify a glob
pattern to find the file with the definitions. For
instance:
use-packages "packages.jam" ;
--use-package-manager
command line option:
The --use-package-manager=NAME
command line option allows one to
non-intrusively specify per invocation which of the built-in package manager
types to use.
PACKAGE_MANAGER_BUILD_INFO
variable:
The PACKAGE_MANAGER_BUILD_INFO
variable, which is taken from the environment
or defined with the -sX=Y
option, specifies a glob
pattern to use to find
the package definitions.
Built-in detection:
There are a number of built-in glob
patterns to support popular package
managers. Currently the supported ones are:
-
Conan (
conan
): currently supports theb2 generator
.
6. Reference
6.1. General information
6.1.1. Initialization
Immediately upon starting, the B2 engine (b2
) loads the Jam
code that implements the build system. To do this, it searches for the
build system bootstrap.jam
file in specific installation locations.
The search is based on the location of the b2(.exe)
executable
location.
The default bootstrap.jam
, after loading some standard definitions,
loads both site-config.jam
and user-config.jam
.
|
ℹ
|
To maintain backward compatibility the file called
boost-build.jam , is loaded if present. The search starts first in the
invocation directory, then in its parent and so forth up to the filesystem
root, and finally in the directories specified by the environment variable
BOOST_BUILD_PATH. On Unix BOOST_BUILD_PATH defaults to /usr/share/b2 .
|
6.2. Builtin rules
This section contains the list of all rules that can be used in Jamfile — both rules that define new targets and auxiliary rules.
exe
-
Creates an executable file. See the section called “Programs”.
lib
-
Creates an library file. See the section called “Libraries”.
install
-
Installs built targets and other files. See the section called “Installing”.
alias
-
Creates an alias for other targets. See the section called “Alias”.
unit-test
-
Creates an executable that will be automatically run. See the section called “Testing”.
compile
;compile-fail
;link
;link-fail
;run
;run-fail
-
Specialized rules for testing. See the section called “Testing”.
check-target-builds
-
The
check-target-builds
allows you to conditionally use different properties depending on whether some metatarget builds, or not. This is similar to functionality of configure script inautotools
projects. The function signature is:rule check-target-builds ( target message ? : true-properties * : false-properties * )
This function can only be used when passing requirements or usage requirements to a metatarget rule. For example, to make an application link to a library if it’s available, one has use the following:
exe app : app.cpp : [ check-target-builds has_foo "System has foo" : <library>foo : <define>FOO_MISSING=1 ] ;
For another example, the alias rule can be used to consolidate configuration choices and make them available to other metatargets, like so:
alias foobar : : : : [ check-target-builds has_foo "System has foo" : <library>foo : <library>bar ] ;
obj
-
Creates an object file. Useful when a single source file must be compiled with special properties.
preprocessed
-
Creates an preprocessed source file. The arguments follow the common syntax.
glob
-
The
glob
rule takes a list shell pattern and returns the list of files in the project’s source directory that match the pattern. For example:lib tools : [ glob *.cpp ] ;
It is possible to also pass a second argument—the list of exclude patterns. The result will then include the list of files matching any of include patterns, and not matching any of the exclude patterns. For example:
lib tools : [ glob *.cpp : file_to_exclude.cpp bad*.cpp ] ;
glob-tree
-
The
glob-tree
is similar to theglob
except that it operates recursively from the directory of the containing Jamfile. For example:ECHO [ glob-tree *.cpp : .svn ] ;
will print the names of all C++ files in your project. The
.svn
exclude pattern prevents theglob-tree
rule from entering administrative directories of the Subversion version control system. project
-
Declares project id and attributes, including project requirements. See the section called “Projects”.
use-project
-
Assigns a symbolic project ID to a project at a given path. This rule must be better documented!
explicit
-
The
explicit
rule takes a single parameter—a list of target names. The named targets will be marked explicit, and will be built only if they are explicitly requested on the command line, or if their dependents are built. Compare this to ordinary targets, that are built implicitly when their containing project is built. always
-
The
always
function takes a single parameter—a list of metatarget names. The targets produced by the named metatargets will be always considered out of date. Consider this example:exe hello : hello.cpp ; exe bye : bye.cpp ; always hello ;
If a build of
hello
is requested, then it will always be recompiled. Note that if a build ofhello
is not requested, for example you specify justbye
on the command line,hello
will not be recompiled. constant
-
Sets project-wide constant. Takes two parameters: variable name and a value and makes the specified variable name accessible in this Jamfile and any child Jamfiles. For example:
constant VERSION : 1.34.0 ;
path-constant
-
Same as
constant
except that the value is treated as path relative to Jamfile location. For example, ifb2
is invoked in the current directory, and Jamfile inhelper
subdirectory has:path-constant DATA : data/a.txt ;
then the variable
DATA
will be set tohelper/data/a.txt
, and ifb2
is invoked from thehelper
directory, then the variableDATA
will be set todata/a.txt
. build-project
-
Cause some other project to be built. This rule takes a single parameter—a directory name relative to the containing Jamfile. When the containing Jamfile is built, the project located at that directory will be built as well. At the moment, the parameter to this rule should be a directory name. Project ID or general target references are not allowed.
test-suite
-
This rule is deprecated and equivalent to
alias
.
6.3. Builtin features
This section documents the features that are built-in into B2. For features with a fixed set of values, that set is provided, with the default value listed first.
address-model
-
Allowed values:
32
,64
.Specifies if 32-bit or 64-bit code should be generated by the compiler. Whether this feature works depends on the used compiler, its version, how the compiler is configured, and the values of the
architecture
instruction-set
features. Please see the section C++ Compilers for details. address-sanitizer
-
Allowed values:
on
,norecover
.Enables address sanitizer. Value
norecover
disables recovery for the sanitizer. The feature is optional, thus no sanitizer is enabled by default. allow
-
This feature is used to allow specific generators to run. For example, Qt tools can only be invoked when Qt library is used. In that case,
<allow>qt
will be in usage requirement of the library. architecture
-
Allowed values:
x86
,ia64
,sparc
,power
,mips
,mips1
,mips2
,mips3
,mips4
,mips32
,mips32r2
,mips64
,parisc
,arm
,s390x
,loongarch
.Specifies the general processor family to generate code for.
archiveflags
-
The value of this feature is passed without modification to the archiver tool when creating static libraries.
asmflags
-
The value of this feature is passed without modification to the assembler.
asynch-exceptions
-
Allowed values:
off
,on
.Selects whether there is support for asynchronous EH (e.g. catching SEGVs).
build
-
Allowed values:
no
Used to conditionally disable build of a target. If
<build>no
is in properties when building a target, build of that target is skipped. Combined with conditional requirements this allows you to skip building some target in configurations where the build is known to fail. cflags
;cxxflags
;linkflags
-
The value of these features is passed without modification to the corresponding tools. For
cflags
that is both the C and C++ compilers, forcxxflags
that is the C++ compiler, and forlinkflags
that is the linker. The features are handy when you are trying to do something special that cannot be achieved by a higher-level feature in B2. conditional
-
Used to introduce indirect conditional requirements. The value should have the form:
@rulename
where rulename should be a name of a rule with the following signature:
rule rulename ( properties * )
The rule will be called for each target with its properties and should return any additional properties. See also section Requirements for an example.
coverage
-
Allowed values:
off
,on
.Enables code instrumentation to generate coverage data during execution.
cxxflags
-
See
<cflags>
. cxxstd
-
Allowed values:
98
,03
,0x
,11
,1y
,14
,1z
,17
,2a
,20
,2b
,23
,2c
,26
,latest
.Specifies the version of the C++ Standard Language to build with. All the official versions of the standard since "98" are included. It is also possible to specify using the experimental, work in progress,
latest
version. Some compilers specified intermediate versions for the experimental versions leading up to the released standard version. Those are included following the GNU nomenclature as0x
,1y
,1z
,2a
,2b
and2c
. Depending on the compilerlatest
would map to one of those.
|
ℹ
|
This is an optional feature. Hence when not specified the compiler
default behaviour is used.
|
|
ℹ
|
Please consult the toolset specific documentation for which cxxstd
is supported.
|
cxxstd-dialect
-
Subfeature of
cxxstd
Allowed values:
iso
,gnu
,ms
.Indicates if a non-standard dialect should be used. These usually have either/or extensions or platform specific functionality. Not specifying the dialect will default to 'iso' which will attempt to use ISO C++ Standard conformance to the best of the compiler’s ability.
c++abi
-
Selects a specific variant of C++ ABI if the compiler supports several.
c++-template-depth
-
Allowed values: Any positive integer.
Allows configuring a C++ compiler with the maximal template instantiation depth parameter. Specific toolsets may or may not provide support for this feature depending on whether their compilers provide a corresponding command-line option.
ℹDue to some internal details in the current B2 implementation it is not possible to have features whose valid values are all positive integer. As a workaround a large set of allowed values has been defined for this feature and, if a different one is needed, user can easily add it by calling the feature.extend rule. debug-symbols
-
Allowed values:
on
,off
.Specifies if produced object files, executables, and libraries should include debug information. Typically, the value of this feature is implicitly set by the
variant
feature, but it can be explicitly specified by the user. The most common usage is to build release variant with debugging information. define
-
Specifies a preprocessor symbol that should be defined on the command line. You may either specify just the symbol, which will be defined without any value, or both the symbol and the value, separated by equal sign.
def-file
-
Provides a means to specify def-file for windows DLLs.
dependency
-
Introduces a dependency on the target named by the value of this feature (so it will be brought up-to-date whenever the target being declared is). The dependency is not used in any other way.
dll-path
-
Specifies an additional directory where the system should look for shared libraries when the executable or shared library is run. This feature only affects Unix compilers. Please see Why are the
dll-path
andhardcode-dll-paths
properties useful? in Frequently Asked Questions for details. embed-manifest
-
Allowed values:
on
,off
.This feature is specific to the
msvc
toolset (see Microsoft Visual C++), and controls whether the manifest files should be embedded inside executables and shared libraries, or placed alongside them. This feature corresponds to the IDE option found in the project settings dialog, under Configuration Properties → Manifest Tool → Input and Output → Embed manifest. embed-manifest-file
-
This feature is specific to the
msvc
toolset (see Microsoft Visual C++), and controls which manifest files should be embedded inside executables and shared libraries. This feature corresponds to the IDE option found in the project settings dialog, under Configuration Properties → Manifest Tool → Input and Output → Additional Manifest Files. embed-manifest-via
-
This feature is specific to the
msvc
toolset (see Microsoft Visual C++), and controls whether a manifest should be embedded via linker or manifest tool. exception-handling
-
Allowed values:
on
,off
.Disables exceptions.
extern-c-nothrow
-
Allowed values:
off
,on
.Selects whether all
extern "C"
functions are considerednothrow
by default. fflags
-
The value of this feature is passed without modification to the tool when compiling Fortran sources.
file
-
When used in requirements of a prebuilt library target this feature specifies the path to the library file. See Prebuilt targets for examples.
find-shared-library
-
Adds a shared library to link to. Usually
lib
targets should be preferred over using this feature. find-static-library
-
Adds a static library to link to. Usually
lib
targets should be preferred over using this feature. flags
-
This feature is used for generic, i.e. non-language specific, flags for tools. The value of this feature is passed without modification to the tool that will build the target.
hardcode-dll-paths
-
Allowed values:
true
,false
.Controls automatic generation of dll-path properties.
This property is specific to Unix systems. If an executable is built with
<hardcode-dll-paths>true
, the generated binary will contain the list of all the paths to the used shared libraries. As the result, the executable can be run without changing system paths to shared libraries or installing the libraries to system paths. This is very convenient during development. Please see the FAQ entry for details. Note that on Mac OSX, the paths are unconditionally hardcoded by the linker, and it is not possible to disable that behavior implicit-dependency
-
Indicates that the target named by the value of this feature may produce files that are included by the sources of the target being declared. See the section Generated headers for more information.
force-include
-
Specifies an include path that has to be included in a way like if
#include "file"
appeared as the first line of every target’s source file.
The include order is not guaranteed if used multiple times on a single target.
include
-
Specifies an additional include path that is to be passed to C and C++ compilers.
inlining
-
Allowed values:
off
,on
,full
.Enables inlining.
install-package
-
Specifies the name of the package to which installed files belong. This is used for default installation prefix on certain platforms.
install-<name>
-
Specifies installation prefix for
install
targets. These named installation prefixes are registered by default:-
prefix
:C:\<package name>
if<target-os>windows
is in the property set,/usr/local
otherwise -
exec-prefix
:(prefix)
-
bindir
:(exec-prefix)/bin
-
sbindir
:(exec-prefix)/sbin
-
libexecdir
:(exec-prefix)/libexec
-
libdir
:(exec-prefix)/lib
-
datarootdir
:(prefix)/share
-
datadir
:(datarootdir)
-
sysconfdir
:(prefix)/etc
-
sharedstatedir
:(prefix)/com
-
localstatedir
:(prefix)/var
-
runstatedir
:(localstatedir)/run
-
includedir
:(prefix)/include
-
oldincludedir
:/usr/include
-
docdir
:(datarootdir)/doc/<package name>
-
infodir
:(datarootdir)/info
-
htmldir
:(docdir)
-
dvidir
:(docdir)
-
pdfdir
:(docdir)
-
psdir
:(docdir)
-
lispdir
:(datarootdir)/emacs/site-lisp
-
localedir
:(datarootdir)/locale
-
mandir
:(datarootdir)/man
-
If more are necessary, they could be added with
stage.add-install-dir
.
instruction-set
-
Allowed values: depends on the used toolset.
Specifies for which specific instruction set the code should be generated. The code in general might not run on processors with older/different instruction sets.
While B2 allows a large set of possible values for this features, whether a given value works depends on which compiler you use. Please see the section C++ Compilers for details.
library
-
This feature is almost equivalent to the
<source>
feature, except that it takes effect only for linking. When you want to link all targets in a Jamfile to certain library, the<library>
feature is preferred over<source>X
— the latter will add the library to all targets, even those that have nothing to do with libraries. library-path
-
Adds to the list of directories which will be used by the linker to search for libraries.
leak-sanitizer
-
Allowed values:
on
,norecover
.Enables leak sanitizer. Value
norecover
disables recovery for the sanitizer. The feature is optional, thus no sanitizer is enabled by default. link
-
Allowed values:
shared
,static
Controls how libraries are built.
linkflags
-
See
<cflags>
. local-visibility
-
Allowed values:
global
,protected
,hidden
.This feature has the same effect as the
visibility
feature but is intended to be used by targets that require a particular symbol visibility. Unlike thevisibility
feature,local-visibility
is not inherited by the target dependencies and only affects the target to which it is applied.The
local-visibility
feature supports the same values with the same meaning as thevisibility
feature. By default, iflocal-visibility
is not specified for a target, the value of thevisibility
feature is used. location
-
Specifies the build directory for a target. The feature is used primarily with
<install>
rule. location-prefix
-
Sets the build directory for a target as the project’s build directory prefixed with the value of this feature. See section Target Paths for an example.
mflags
-
The value of this feature is passed without modification to the tool when compiling Objective C sources.
mmflags
-
The value of this feature is passed without modification to the tool when compiling Objective C++ sources.
name
-
When used in requirements of a prebuilt library target this feature specifies the name of the library (the name of the library file without any platform-specific suffixes or prefixes). See Prebuilt targets for examples.
When used in requirements of an
<install>
target it specifies the name of the target file. optimization
-
Allowed values:
off
,speed
,space
, 'minimal', 'debug'.Enables optimization.
speed
optimizes for faster code,space
optimizes for smaller binary. profiling
-
Allowed values:
off
,on
.Enables generation of extra code to write profile information.
relevant
-
Allowed values: the name of any feature.
Indicates which other features are relevant for a given target. It is usually not necessary to manage it explicitly, as B2 can deduce it in most cases. Features which are not relevant will not affect target paths, and will not cause conflicts.
-
A feature will be considered relevant if any of the following are true
-
It is referenced by
toolset.flags
ortoolset.uses-features
-
It is used by the requirements of a generator
-
It is a sub-feature of a relevant feature
-
It has a sub-feature which is relevant
-
It is a composite feature, and any composed feature is relevant
-
It affects target alternative selection for a main target
-
It is a propagated feature and is relevant for any dependency
-
It is relevant for any dependency created by the same main target
-
It is used in the condition of a conditional property and the corresponding value is relevant
-
It is explicitly named as relevant
-
-
Relevant features cannot be automatically deduced in the following cases:
-
Indirect conditionals. Solution: return properties of the form
<relevant>result-feature:<relevant>condition-feature
ℹThis isn’t really a conditional, although for most purposes it functions like one. In particular, it does not support multiple comma-separated elements in the condition, and it does work correctly even in contexts where conditional properties are not allowed -
Action rules that read properties. Solution: add toolset.uses-features to tell B2 that the feature is actually used.
-
Generators and targets that manipulate property-sets directly. Solution: set <relevant> manually.
-
-
rtti
-
Allowed values:
on
,off
.Disables run-time type information.
runtime-debugging
-
Allowed values:
on
,off
.Specifies whether produced object files, executables, and libraries should include behavior useful only for debugging, such as asserts. Typically, the value of this feature is implicitly set by the
variant
feature, but it can be explicitly specified by the user. The most common usage is to build release variant with debugging output. runtime-link
-
Allowed values:
shared
,static
Controls if a static or shared C/C++ runtime should be used. There are some restrictions how this feature can be used, for example on some compilers an application using static runtime should not use shared libraries at all, and on some compilers, mixing static and shared runtime requires extreme care. Check your compiler documentation for more details.
search
-
When used in requirements of a prebuilt library target this feature adds to the list of directories to search for the library file. See Prebuilt targets for examples.
source
-
The
<source>X
property has the same effect on building a target as putting X in the list of sources. It is useful when you want to add the same source to all targets in the project (you can put<source>
in requirements) or to conditionally include a source (using conditional requirements, see the section Conditions and alternatives. See also the<library>
feature. staging-prefix
-
Specifies staging prefix for
install
targets. If present, it will be used instead of the path to named directoryprefix
. Example:project : requirements <install-prefix>x/y/z ; install a1 : a : <location>(bindir) ; # installs into x/y/z/bin install a2 : a : <location>(bindir) <staging-prefix>q ; # installs into q/bin
The feature is useful when you cannot (or don’t want to) put build artfiacts into their intented locations during the build (such as when cross-compiling), but still need to communicate those intended locations to the build system, e.g. to generate configuration files.
stdlib
-
Allowed values:
native
,gnu
,gnu11
,libc++
,sun-stlport
,apache
.Specifies C++ standard library to link to and in some cases the library ABI to use:
native
-
Use compiler’s default.
gnu
-
Use GNU Standard Library (a.k.a. libstdc++) with the old ABI.
gnu11
-
Use GNU Standard Library with the new ABI.
libc++
-
Use LLVM libc++.
sun-stlport
-
Use the STLport implementation of the standard library provided with the Solaris Studio compiler.
apache
-
Use the Apache stdcxx version 4 C++ standard library provided with the Solaris Studio compiler.
strip
-
Allowed values:
off
,on
.Controls whether the binary should be stripped — that is have everything not necessary to running removed.
ℹThis feature will show up in target paths of everything, not just binaries. suppress-import-lib
-
Suppresses creation of import library by the linker.
tag
-
Used to customize the name of the generated files. The value should have the form:
@rulename
where rulename should be a name of a rule with the following signature:
rule tag ( name : type ? : property-set )
The rule will be called for each target with the default name computed by B2, the type of the target, and property set. The rule can either return a string that must be used as the name of the target, or an empty string, in which case the default name will be used.
Most typical use of the
tag
feature is to encode build properties, or library version in library target names. You should take care to return non-empty string from the tag rule only for types you care about — otherwise, you might end up modifying names of object files, generated header file and other targets for which changing names does not make sense. target-os
-
Allowed values:
aix
,android
,appletv
,bsd
,cygwin
,darwin
,freebsd
,haiku
,hpux
,iphone
,linux
,netbsd
,openbsd
,osf
,qnx
,qnxnto
,sgi
,solaris
,unix
,unixware
,windows
,vms
,vxworks
,freertos
.Specifies the operating system for which the code is to be generated. The compiler you used should be the compiler for that operating system. This option causes B2 to use naming conventions suitable for that operating system, and adjust build process accordingly. For example, with gcc, it controls if import libraries are produced for shared libraries or not.
See the section Cross-compilation for details of cross-compilation.
threading
-
Allowed values:
single
,multi
Controls if the project should be built in multi-threaded mode. This feature does not necessary change code generation in the compiler, but it causes the compiler to link to additional or different runtime libraries, and define additional preprocessor symbols (for example,
_MT
on Windows and_REENTRANT
on Linux). How those symbols affect the compiled code depends on the code itself. thread-sanitizer
-
Allowed values:
on
,norecover
.Enables thread sanitizer. Value
norecover
disables recovery for the sanitizer. The feature is optional, thus no sanitizer is enabled by default. toolset
-
Allowed values: any of the toolset modules.
Selects the toolset that will be used to build binary targets. The full list of toolset modules is in the Builtin tools section.
undef
-
Specifies a preprocessor symbol to undefine.
undefined-sanitizer
-
Allowed values:
on
,norecover
.Enables undefined behavior sanitizer. Value
norecover
disables recovery for the sanitizer. The feature is optional, thus no sanitizer is enabled by default. use
-
Introduces a dependency on the target named by the value of this feature (so it will be brought up-to-date whenever the target being declared is), and adds its usage requirements to the build properties of the target being declared. The dependency is not used in any other way. The primary use case is when you want the usage requirements (such as
#include
paths) of some library to be applied, but do not want to link to it. user-interface
-
Allowed values:
console
,gui
,wince
,native
,auto
.Specifies the environment for the executable which affects the entry point symbol (or entry point function) that the linker will select. This feature is Windows-specific.
console
-
console application.
gui
-
application does not require a console (it is supposed to create its own windows.
wince
-
application is intended to run on a device that has a version of the Windows CE kernel.
native
-
application runs without a subsystem environment.
auto
-
application runs in the POSIX subsystem in Windows.
variant
-
Allowed values:
debug
,release
,profile
.A feature combining several low-level features, making it easy to request common build configurations.
The value
debug
expands to<optimization>off <debug-symbols>on <inlining>off <runtime-debugging>on
The value
release
expands to<optimization>speed <debug-symbols>off <inlining>full <runtime-debugging>off
The value
profile
expands to the same asrelease
, plus:<profiling>on <debug-symbols>on
Users can define their own build variants using the
variant
rule from thecommon
module.ℹRuntime debugging is on in debug builds to suit the expectations of people used to various IDEs. vectorize
-
Allowed values:
off
,on
,full
.Enables vectorization.
version
-
This feature isn’t used by any of the builtin tools, but can be used, for example, to adjust target’s name via
<tag>
feature. visibility
-
Allowed values:
global
,protected
,hidden
.Specifies the default symbol visibility in compiled binaries. Not all values are supported on all platforms and on some platforms (for example, Windows) symbol visibility is not supported at all.
The supported values have the following meaning:
global
-
a.k.a. "default" in gcc documentation. Global symbols are considered public, they are exported from shared libraries and can be redefined by another shared library or executable.
protected
-
a.k.a. "symbolic". Protected symbols are exported from shared ibraries but cannot be redefined by another shared library or executable. This mode is not supported on some platforms, for example OS X.
hidden
-
Hidden symbols are not exported from shared libraries and cannot be redefined by a different shared library or executable loaded in a process. In this mode, public symbols have to be explicitly marked in the source code to be exported from shared libraries. This is the recommended mode.
By default compiler default visibility mode is used (no compiler flags are added).
ℹIn Boost super-project Jamroot file this property is set to the default value of hidden
. This means that Boost libraries are built with hidden visibility by default, unless the user overrides it with a differentvisibility
or a library sets a differentlocal-visibility
(see below).
warnings
-
Allowed values:
on
,all
,extra
,pedantic
,off
.Controls the warning level of compilers.
on
-
enable default/"reasonable" warning level.
all
-
enable most warnings.
extra
-
enable extra, possibly conflicting, warnings.
pedantic
-
enable likely inconsequential, and conflicting, warnings.
off
-
disable all warnings.
Default value is
all
.
warnings-as-errors
-
Allowed values:
off
,on
.Makes it possible to treat warnings as errors and abort compilation on a warning.
translate-path
-
Used to introduce custom path feature translation. The value should have the form:
@rulename
where rulename should be a name of a rule with the following signature:
rule rulename ( feature value : properties * : project-id : project-location )
The rule is called for each target with the
feature
of a path property, the path property value, target properties, the target project ID, and the target project location. It should return the translated path value. Or return nothing if it doesn’t do path translation. Leaving it do the default path translation. lto
-
Allowed values:
on
.Enables link time optimizations (also known as interprocedural optimizations or whole-program optimizations). Currently supported toolsets are GNU C++, clang and Microsoft Visual C++. The feature is optional.
lto-mode
-
Subfeature of
lto
Allowed values:
full
,thin
,fat
.Specifies the type of LTO to use.
full
-
Use the monolithic LTO: on linking all input is merged into a single module.
thin
-
Use clang’s ThinLTO: each compiled file contains a summary of the module, these summaries are merged into a single index. This allows to avoid merging all modules together, which greatly reduces linking time.
fat
-
Produce gcc’s fat LTO objects: compiled files contain both the intermidiate language suitable for LTO and object code suitable for regular linking.
response-file
-
Allowed values:
auto
,file
,contents
.Controls whether a response file is used, or not, during the build of the applicable target. For
file
a response file is created and the filename replaced in the action. Forcontents
the contents (:E=
) is replaced in the action and no response file is created. Forauto
either a response file is created, or the contents replaced, based on the length of the contents such that if the contents fits within the limits of the command execution line length limits the contents is replaced. Otherwise a response file is created and the filename is replaced in the actions.Supported for
clang-linux
andmsvc
toolsets.
6.4. Builtin tools
B2 comes with support for a large number of C++ compilers, and other tools. This section documents how to use those tools.
Before using any tool, you must declare your intention, and possibly
specify additional information about the tool’s configuration. This is
done by calling the using
rule, typically in your user-config.jam
,
for example:
using gcc ;
additional parameters can be passed just like for other rules, for example:
using gcc : 4.0 : g++-4.0 ;
The options that can be passed to each tool are documented in the subsequent sections.
6.4.1. C++ Compilers
This section lists all B2 modules that support C++ compilers
and documents how each one can be initialized. The name of support
module for compiler is also the value for the toolset
feature that can
be used to explicitly request that compiler.
HP aC++ compiler
The acc
module supports the
HP
aC++ compiler for the HP-UX operating system.
The module is initialized using the following syntax:
using acc : [version] : [c++-compile-command] : [compiler options] ;
This statement may be repeated several times, if you want to configure several versions of the compiler.
If the command is not specified, the aCC
binary will be searched in
PATH.
The following options can be provided, using `<option-name>option-value syntax`:
cflags
-
Specifies additional compiler flags that will be used when compiling C sources.
cxxflags
-
Specifies additional compiler flags that will be used when compiling C++ sources.
compileflags
-
Specifies additional compiler flags that will be used when compiling both C and C++ sources.
linkflags
-
Specifies additional command line options that will be passed to the linker.
Borland C++ Compiler
The borland
module supports the 32-bit command line C compilers
running on Microsoft Windows. This is the bcc32 executable for all
versions of Borland C and C Builder, as well as the command line
compatible compiler bcc32c on later versions of C Builder.
The module is initialized using the following syntax:
using borland : [version] : [c++-compile-command] : [compiler options] ;
This statement may be repeated several times, if you want to configure several versions of the compiler.
If the command is not specified, Boost.Build will search for a binary
named bcc32
in PATH.
The following options can be provided, using `<option-name>option-value syntax`:
cflags
-
Specifies additional compiler flags that will be used when compiling C sources.
cxxflags
-
Specifies additional compiler flags that will be used when compiling C++ sources.
compileflags
-
Specifies additional compiler flags that will be used when compiling both C and C++ sources.
linkflags
-
Specifies additional command line options that will be passed to the linker.
user-interface
-
Specifies the user interface for applications. Valid choices are
console
for a console applicatiuon andgui
for a Windows application.
Comeau C/C++ Compiler
The como-linux
and the como-win
modules supports the
Comeau C/C++ Compiler on Linux and
Windows respectively.
The module is initialized using the following syntax:
using como : [version] : [c++-compile-command] : [compiler options] ;
This statement may be repeated several times, if you want to configure several versions of the compiler.
If the command is not specified, B2 will search for a binary
named como
in PATH.
The following options can be provided, using `<option-name>option-value syntax`:
cflags
-
Specifies additional compiler flags that will be used when compiling C sources.
cxxflags
-
Specifies additional compiler flags that will be used when compiling C++ sources.
compileflags
-
Specifies additional compiler flags that will be used when compiling both C and C++ sources.
linkflags
-
Specifies additional command line options that will be passed to the linker.
Before using the Windows version of the compiler, you need to setup necessary environment variables per compiler’s documentation. In particular, the COMO_XXX_INCLUDE variable should be set, where XXX corresponds to the used backend C compiler.
Code Warrior
The cw
module support CodeWarrior compiler, originally produced by
Metrowerks and presently developed by Freescale. B2 supports
only the versions of the compiler that target x86 processors. All such
versions were released by Metrowerks before acquisition and are not sold
any longer. The last version known to work is 9.4.
The module is initialized using the following syntax:
using cw : [version] : [c++-compile-command] : [compiler options] ;
This statement may be repeated several times, if you want to configure several versions of the compiler.
If the command is not specified, B2 will search for a binary
named mwcc
in default installation paths and in PATH.
The following options can be provided, using `<option-name>option-value syntax`:
cflags
-
Specifies additional compiler flags that will be used when compiling C sources.
cxxflags
-
Specifies additional compiler flags that will be used when compiling C++ sources.
compileflags
-
Specifies additional compiler flags that will be used when compiling both C and C++ sources.
linkflags
-
Specifies additional command line options that will be passed to the linker.
setup
-
The command that sets up environment variables prior to invoking the compiler. If not specified,
cwenv.bat
alongside the compiler binary will be used. compiler
-
The command that compiles C and C++ sources. If not specified,
mwcc
will be used. The command will be invoked after the setup script was executed and adjusted the PATH variable. linker
-
The command that links executables and dynamic libraries. If not specified,
mwld
will be used. The command will be invoked after the setup script was executed and adjusted the PATH variable.
Digital Mars C/C++ Compiler
The dmc
module supports the Digital Mars
C++ compiler.
The module is initialized using the following syntax:
using dmc : [version] : [c++-compile-command] : [compiler options] ;
This statement may be repeated several times, if you want to configure several versions of the compiler.
If the command is not specified, B2 will search for a binary
named dmc
in PATH.
The following options can be provided, using `<option-name>option-value syntax`:
cflags
-
Specifies additional compiler flags that will be used when compiling C sources.
cxxflags
-
Specifies additional compiler flags that will be used when compiling C++ sources.
compileflags
-
Specifies additional compiler flags that will be used when compiling both C and C++ sources.
linkflags
-
Specifies additional command line options that will be passed to the linker.
GNU C++
The gcc
module supports the GNU C++ compiler on
Linux, a number of Unix-like system including SunOS and on Windows
(either Cygwin or MinGW).
The gcc
module is initialized using the following syntax:
using gcc : [version] : [c++-compile-command] : [compiler options] ;
This statement may be repeated several times, if you want to configure several versions of the compiler.
If the version is not explicitly specified, it will be automatically
detected by running the compiler with the -v
option. If the command is
not specified, the g++
binary will be searched in PATH.
The following options can be provided, using `<option-name>option-value syntax`:
asmflags
-
Specifies additional compiler flags that will be used when compiling assembler sources.
cflags
-
Specifies additional compiler flags that will be used when compiling C sources.
cxxflags
-
Specifies additional compiler flags that will be used when compiling C++ sources.
fflags
-
Specifies additional compiler flags that will be used when compiling Fortran sources.
mflags
-
Specifies additional compiler flags that will be used when compiling Objective-C sources.
mmflags
-
Specifies additional compiler flags that will be used when compiling Objective-C++ sources.
compileflags
-
Specifies additional compiler flags that will be used when compiling any language sources.
linkflags
-
Specifies additional command line options that will be passed to the linker.
root
-
Specifies root directory of the compiler installation. This option is necessary only if it is not possible to detect this information from the compiler command—for example if the specified compiler command is a user script.
archiver
-
Specifies the archiver command that is used to produce static libraries. Normally, it is autodetected using gcc
-print-prog-name
option or defaulted toar
, but in some cases you might want to override it, for example to explicitly use a system version instead of one included with gcc. rc
-
Specifies the resource compiler command that will be used with the version of gcc that is being configured. This setting makes sense only for Windows and only if you plan to use resource files. By default
windres
will be used. rc-type
-
Specifies the type of resource compiler. The value can be either
windres
for msvc resource compiler, orrc
for borland’s resource compiler.
In order to compile 64-bit applications, you have to specify
address-model=64
, and the instruction-set
feature should refer to a 64
bit processor. Currently, those include nocona
, opteron
, athlon64
and
athlon-fx
.
HP C++ Compiler for Tru64 Unix
The hp_cxx
modules supports the
HP C++ Compiler
for Tru64 Unix.
The module is initialized using the following syntax:
using hp_cxx : [version] : [c++-compile-command] : [compiler options] ;
This statement may be repeated several times, if you want to configure several versions of the compiler.
If the command is not specified, B2 will search for a binary
named hp_cxx
in PATH.
The following options can be provided, using `<option-name>option-value syntax`:
cflags
-
Specifies additional compiler flags that will be used when compiling C sources.
cxxflags
-
Specifies additional compiler flags that will be used when compiling C++ sources.
compileflags
-
Specifies additional compiler flags that will be used when compiling both C and C++ sources.
linkflags
-
Specifies additional command line options that will be passed to the linker.
Intel C++
The intel-*
modules support the Intel C++ command-line compiler.
The module is initialized using the following syntax:
using intel : [version] : [c++-compile-command] : [compiler options] ;
This statement may be repeated several times, if you want to configure several versions of the compiler.
If compiler command is not specified, then B2 will look in PATH
for an executable icpc
(on Linux), or icl.exe
(on Windows).
The following options can be provided, using `<option-name>option-value syntax`:
cflags
-
Specifies additional compiler flags that will be used when compiling C sources.
cxxflags
-
Specifies additional compiler flags that will be used when compiling C++ sources.
compileflags
-
Specifies additional compiler flags that will be used when compiling both C and C++ sources.
linkflags
-
Specifies additional command line options that will be passed to the linker.
root
-
For the Linux version, specifies the root directory of the compiler installation. This option is necessary only if it is not possible to detect this information from the compiler command — for example if the specified compiler command is a user script. For the Windows version, specifies the directory of the
iclvars.bat
file, for versions prior to 21 ( or 2021 ), or of thesetvars.bat
, for versions from 21 ( or 2021 ) on up, for configuring the compiler. Specifying theroot
option without specifying the compiler command allows the end-user not to have to worry about whether they are compiling 32-bit or 64-bit code, as the toolset will automatically configure the compiler for the appropriate address model and compiler command using theiclvars.bat
orsetvars.bat
batch file.
Microsoft Visual C++
The msvc
module supports the
Microsoft Visual C++ command-line
tools on Microsoft Windows. The supported products and versions of
command line tools are listed below:
-
Visual Studio 2019-14.2
-
Visual Studio 2017—14.1
-
Visual Studio 2015—14.0
-
Visual Studio 2013—12.0
-
Visual Studio 2012—11.0
-
Visual Studio 2010—10.0
-
Visual Studio 2008—9.0
-
Visual Studio 2005—8.0
-
Visual Studio .NET 2003—7.1
-
Visual Studio .NET—7.0
-
Visual Studio 6.0, Service Pack 5—6.5
The user would then call the boost build executable with the toolset set
equal to msvc-[version number]
for example to build with Visual Studio
2019 one could run:
.\b2 toolset=msvc-14.2 target
The msvc
module is initialized using the following syntax:
using msvc : [version] : [c++-compile-command] : [compiler options] ;
This statement may be repeated several times, if you want to configure several versions of the compiler.
If the version is not explicitly specified, the most recent version
found in the registry will be used instead. If the special value all
is passed as the version, all versions found in the registry will be
configured. If a version is specified, but the command is not, the
compiler binary will be searched in standard installation paths for that
version, followed by PATH.
The compiler command should be specified using forward slashes, and quoted.
The following options can be provided, using `<option-name>option-value syntax`:
cflags
-
Specifies additional compiler flags that will be used when compiling C sources.
cxxflags
-
Specifies additional compiler flags that will be used when compiling C++ sources.
compileflags
-
Specifies additional compiler flags that will be used when compiling both C and C++ sources.
linkflags
-
Specifies additional command line options that will be passed to the linker.
assembler
-
The command that compiles assembler sources. If not specified,
ml
will be used. The command will be invoked after the setup script was executed and adjusted the PATH variable. compiler
-
The command that compiles C and C++ sources. If not specified,
cl
will be used. The command will be invoked after the setup script was executed and adjusted the PATH variable. compiler-filter
-
Command through which to pipe the output of running the compiler. For example to pass the output to STLfilt.
idl-compiler
-
The command that compiles Microsoft COM interface definition files. If not specified,
midl
will be used. The command will be invoked after the setup script was executed and adjusted the PATH variable. linker
-
The command that links executables and dynamic libraries. If not specified,
link
will be used. The command will be invoked after the setup script was executed and adjusted the PATH variable. mc-compiler
-
The command that compiles Microsoft message catalog files. If not specified,
mc
will be used. The command will be invoked after the setup script was executed and adjusted the PATH variable. resource-compiler
-
The command that compiles resource files. If not specified,
rc
will be used. The command will be invoked after the setup script was executed and adjusted the PATH variable. setup
-
The filename of the global environment setup script to run before invoking any of the tools defined in this toolset. Will not be used in case a target platform specific script has been explicitly specified for the current target platform. Used setup script will be passed the target platform identifier (x86, x86_amd64, x86_ia64, amd64 or ia64) as a parameter. If not specified a default script is chosen based on the used compiler binary, e.g.
vcvars32.bat
orvsvars32.bat
. setup-amd64
;setup-i386
;setup-ia64
-
The filename of the target platform specific environment setup script to run before invoking any of the tools defined in this toolset. If not specified the global environment setup script is used.
64-bit support
Starting with version 8.0, Microsoft Visual Studio can generate binaries for 64-bit processor, both 64-bit flavours of x86 (codenamed AMD64/EM64T), and Itanium (codenamed IA64). In addition, compilers that are itself run in 64-bit mode, for better performance, are provided. The complete list of compiler configurations are as follows (we abbreviate AMD64/EM64T to just AMD64):
-
32-bit x86 host, 32-bit x86 target
-
32-bit x86 host, 64-bit AMD64 target
-
32-bit x86 host, 64-bit IA64 target
-
64-bit AMD64 host, 64-bit AMD64 target
-
64-bit IA64 host, 64-bit IA64 target
The 32-bit host compilers can be always used, even on 64-bit Windows. On the contrary, 64-bit host compilers require both 64-bit host processor and 64-bit Windows, but can be faster. By default, only 32-bit host, 32-bit target compiler is installed, and additional compilers need to be installed explicitly.
To use 64-bit compilation you should:
-
Configure you compiler as usual. If you provide a path to the compiler explicitly, provide the path to the 32-bit compiler. If you try to specify the path to any of 64-bit compilers, configuration will not work.
-
When compiling, use
address-model=64
, to generate AMD64 code. -
To generate IA64 code, use
architecture=ia64
The (AMD64 host, AMD64 target) compiler will be used automatically when you are generating AMD64 code and are running 64-bit Windows on AMD64. The (IA64 host, IA64 target) compiler will never be used, since nobody has an IA64 machine to test.
It is believed that AMD64 and EM64T targets are essentially compatible.
The compiler options /favor:AMD64
and /favor:EM64T
, which are
accepted only by AMD64 targeting compilers, cause the generated code to
be tuned to a specific flavor of 64-bit x86. B2 will make use
of those options depending on the value of the`instruction-set` feature.
Windows Runtime support
Starting with version 11.0, Microsoft Visual Studio can produce binaries
for Windows Store and Phone in addition to traditional Win32 desktop. To
specify which Windows API set to target, use the windows-api
feature.
Available options are desktop
, store
, or phone
. If not specified,
desktop
will be used.
When using store
or phone
the specified toolset determines what
Windows version is targeted. The following options are available:
-
Windows 8.0: toolset=msvc-11.0 windows-api=store
-
Windows 8.1: toolset=msvc-12.0 windows-api=store
-
Windows Phone 8.0: toolset=msvc-11.0 windows-api=phone
-
Windows Phone 8.1: toolset=msvc-12.0 windows-api=phone
For example use the following to build for Windows Store 8.1 with the ARM architecture:
.\b2 toolset=msvc-12.0 windows-api=store architecture=arm
Note that when targeting Windows Phone 8.1, version 12.0 didn’t include the vcvars phone setup scripts. They can be separately downloaded from here.
Sun Studio
The sun
module supports the
Sun Studio C++ compilers
for the Solaris OS.
The module is initialized using the following syntax:
using sun : [version] : [c++-compile-command] : [compiler options] ;
This statement may be repeated several times, if you want to configure several versions of the compiler.
If the command is not specified, B2 will search for a binary
named CC
in /opt/SUNWspro/bin
and in PATH.
When using this compiler on complex C code, such as the
http://boost.org[Boost C library], it is recommended to specify the
following options when initializing the sun
module:
-library=stlport4 -features=tmplife -features=tmplrefstatic
See the Sun C++ Frontend Tales for details.
The following options can be provided, using `<option-name>option-value syntax`:
cflags
-
Specifies additional compiler flags that will be used when compiling C sources.
cxxflags
-
Specifies additional compiler flags that will be used when compiling C++ sources.
compileflags
-
Specifies additional compiler flags that will be used when compiling both C and C++ sources.
linkflags
-
Specifies additional command line options that will be passed to the linker.
Starting with Sun Studio 12, you can create 64-bit applications by using
the address-model=64
property.
IBM Visual Age
The vacpp
module supports the IBM
Visual Age C++ Compiler, for the AIX operating system. Versions 7.1 and
8.0 are known to work.
The module is initialized using the following syntax:
using vacpp ;
The module does not accept any initialization options. The compiler
should be installed in the /usr/vacpp/bin
directory.
Later versions of Visual Age are known as XL C/C++. They were not tested
with the the vacpp
module.
6.4.2. Third-party libraries
B2 provides special support for some third-party C++ libraries, documented below.
STLport library
The STLport library is an alternative implementation of C++ runtime library. B2 supports using that library on Windows platform. Linux is hampered by different naming of libraries in each STLport version and is not officially supported.
Before using STLport, you need to configure it in user-config.jam
using the following syntax:
using stlport : version : header-path : library-path ;
Where version is the version of STLport, for example 5.1.4
, headers is
the location where STLport headers can be found, and libraries is the
location where STLport libraries can be found. The version should always
be provided, and the library path should be provided if you’re using
STLport’s implementation of iostreams
. Note that STLport 5.* always uses
its own iostream
implementation, so the library path is required.
When STLport is configured, you can build with STLport by requesting
stdlib=stlport
on the command line.
zlib
Provides support for the zlib library. zlib can be configured either to use precompiled binaries or to build the library from source.
zlib can be initialized using the following syntax
using zlib : version : options : condition : is-default ;
Options for using a prebuilt library:
search
-
The directory containing the zlib binaries.
name
-
Overrides the default library name.
include
-