Properties

| Home | Libraries | People | FAQ | More

## Properties

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 here.

### Build Requests and Target Requirements

The set of properties specified in 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 is typically a combination of the build request and properties derived from the project's `Jamfile`s. For example, the locations of `#include`d header files are normally not specified on the command-line, but described in `Jamfile`s 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>/home/ghost/Work/boost <threading>multi
        ;

When `hello` is built, the two requirements specified above will normally always be present. If the build request given on the bjam command-line explictly contradicts a target's requirements, the command-line usually overrides (or, in the case of "free" feautures like `<include>`[2], augments) the target requirements.

### 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 (i.e. each `Jamfile`), 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.

[2] the section called “Feature Attributes”