Properties

Build Requests and Target Requirements
Project Attributes

To portably represent aspects of target configuration such as debug and release variants, or single- and multi-threaded builds, Boost.Build 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, Boost.Build 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:

bjam 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've seen in bjam 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:

bjam variant=release inlining=off debug-symbols=on

variant is so commonly-used that it has been given special status as an implicit feature—Boost.Build will deduce the 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”.

Build Requests and Target Requirements

The set of properties specified on the command line constitute 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 Jamroot (and its other Jamfiles, as described in the section called “Project Hierarchies”). For example, the locations of #included 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. Multithread-enabled 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 bjam command-line explictly contradicts a target's requirements, the target requirements usually override (or, in the case of “free”” features like <include>, ^[4] augments) the build request.

Tip

The value of the <include> feature is relative to the location of Jamroot where it's used.

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.

^[4] See the section called “Feature Attributes”