Builtin features

This section documents the features that are built-in into Boost.Build. For features with a fixed set of values, that set is provided, with the default value listed first.

variant

A feature combining several low-level features, making it easy to request common build configurations.

Allowed values: debug, release, profile.

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 as release, plus:

<profiling>on <debug-symbols>on

Users can define their own build variants using the variant rule from the common module.

Note: Runtime debugging is on in debug builds to suit the expectations of people used to various IDEs.

link

Allowed values: shared, static

A feature controling how libraries are built.

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.

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.

source

The <source>X feature 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 called “Conditions and alternatives”). See also the

<library>

feature.

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.

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.

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 called “Generated headers” for more information.

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.

dll-path

Specify 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. Plase see the section called “ Why are the dll-path and

hardcode-dll-paths

properties useful? ” in Chapter 7, Frequently Asked Questions for details.

hardcode-dll-paths

Controls automatic generation of dll-path properties.

Allowed values: true, false. 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. Plase 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 behaviour.

cflags, cxxflags, linkflags

The value of those features is passed without modification to the corresponding tools. For cflags that is both the C and C++ compilers, for cxxflags that is the C++ compiler and for linkflags 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 Boost.Build.

include

Specifies an additional include path that is to be passed to C and C++ compilers.

define

Specifies an 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.

warnings

The <warnings> feature controls the warning level of compilers. It has the following values:

off - disables all warnings.
on - enables default warning level for the tool.
all - enables all warnings.

Default value is all.

warnings-as-errors

The <warnings-as-errors> makes it possible to treat warnings as errors and abort compilation on a warning. The value on enables this behaviour. The default value is off.

build

Allowed values: no

The build feature is 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.

tag

The tag feature is 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 Boost.Build, 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.

debug-symbols

Allowed values: on, off.

The debug-symbols feature 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.

runtime-debugging

Allowed values: on, off.

The runtime-debugging feature specifies if produced object files, executables and libraries should include behaviour 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.

target-os

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 Boost.Build 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.

The complete list of possible values for this feature is: aix, bsd, cygwin, darwin, freebsd, hpux, iphone, linux, netbsd, openbsd, osf, qnx, qnxnto, sgi, solaris, unix, unixware, windows.

See the section called “Cross-compilation” for details of crosscompilation

architecture

The architecture features specifies the general processor familty to generate code for.

instruction-set

Allowed values: depend on the used toolset.

The instruction-set 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 Boost.Build 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 called “C++ Compilers” for details.

address-model

Allowed values: 32, 64.

The address-model 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 called “C++ Compilers” for details.

c++-template-depth

Allowed values: Any positive integer.

This feature 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.

Note: Due to some internal details in the current Boost.Build 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.

embed-manifest

Allowed values: on, off.

This feature is specific to the msvc toolset (see the section called “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 the section called “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.