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.
A feature combining several low-level features, making it easy to request common build configurations.
<optimization>off <debug-symbols>on <inlining>off <runtime-debugging>on
<optimization>speed <debug-symbols>off <inlining>full <runtime-debugging>off
profileexpands to the same as
Users can define their own build variants using the
variantrule from the
Note: Runtime debugging is on in debug builds to suit the expectations of people used to various IDEs.
A feature controling how libraries are built.
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.
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,
_MTon Windows and
_REENTRANTon Linux). How those symbols affect the compiled code depends on the code itself.
<source>Xfeature 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
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.
- 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.
- 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.
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
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
#includepaths) of some library to be applied, but do not want to link to it.
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
hardcode-dll-pathsproperties useful? ” in Chapter 8, Frequently Asked Questions for details.
Controls automatic generation of dll-path properties.
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.
The value of those features is passed without modification to the
corresponding tools. For
cflagsthat is both the C and C++ compilers, for
cxxflagsthat is the C++ compiler and for
linkflagsthat 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.
- Specifies an additional include path that is to be passed to C and C++ compilers.
- 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>feature controls the warning level of compilers. It has the following values:Default value is
off- disables all warnings.
on- enables default warning level for the tool.
all- enables all warnings.
<warnings-as-errors>makes it possible to treat warnings as errors and abort compilation on a warning. The value
onenables this behaviour. The default value is
buildfeature is used to conditionally disable build of a target. If
<build>nois 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.
tagfeature is used to customize the name of the generated files. The value should have the form:
rulenameshould 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
tagfeature 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-symbolsfeature specifies if produced object files, executables and libraries should include debug information. Typically, the value of this feature is implicitly set by the
variantfeature, but it can be explicitly specified by the user. The most common usage is to build release variant with debugging information.
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
architecturefeatures specifies the general processor familty to generate code for.
Allowed values: depend on the used toolset.
instruction-setspecifies 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-modelspecifies 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
instruction-setfeatures. Please see the section called “C++ Compilers” for details.
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.
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 → → → .