[BBv2 doc editorial] tutorial/properties

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-20 11:56:08

> 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
^
^-- this comma could be dropped.

> 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
^^^
strike this
> 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.
^^^^^^^^^^^^^^^^^^^^^^^
replace with "the file it appears in"

> 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:
^^^^^^^^^^^^^^^^^^^^^^
strike this
> 
> project 
> : requirements <include>/home/ghost/Work/boost <threading>multi 
> ;

> exe hello : hello.cpp ;
> exe hello2 : hello.cpp ;
> 

Show an additional attribute in use in this example, then follow the
example with a description of what the both attributes are doing, so
that people can relate the attribute name tags in the example to the
attributes you describe.

> The effect would be as if we specified the same requirement for both
> hello and hello2.
> 
> ━━━━━━━━━━━━
> 
> ^[4] See the section called “Feature Attributes”

I think it may be a little confusing to have feature attributes and
project attributes introduced on the same page; they're so different.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com