Re: [jamboost] [BBv2 doc editorial] tutorial/properties

From: Andrey Melnikov (melnikov_at_[hidden])
Date: 2005-09-20 16:30:30

David Abrahams wrote:
>>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:

Compare this with my variant from my Migration Guide in Wiki:

----
Portable compiler configuration switches
Abstract "features" are used instead of compiler-specific switches to 
improve portablity and reduce clutter in Jamfiles.
Toolset modules map Boost.Build features to actual compiler commandline 
switches, allowing project and file compilation settings to be specified 
independently of compiler and OS.
Commonly available settings like <optimization>speed have the same 
meaning for all compilers reducing or completely removing 
compiler-specific configuration. If nesessary, compiler- or os-specific 
options can be set too. Boost.Build doesn't limit you in any way.
exe hello : [ glob * cpp ] ;
obj very_slow_class : very_slow_class.cpp : <optimization>speed ; # 
always optimize, even in debug builds
----
- The highly techical and sometimes BB-specific terms such as "Build 
Target", "Build Variant", "associated values", "toolset components", 
"command-line flags", "requested properties", "build initiation", 
"properties", "build configuration" aren't used at all.
- The "Features" and "Toolset" terms are defined
- The ideas behind the features are explained. The current document 
misses "why" questions almost completely.
>>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.
IMO command line won't be used by newbies for a long time. They need to 
learn a lot first. bjam {toolset-name} is the most complex syntax they 
need in the Tutorial.
>>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
>> ;
Again, we can omit the fact that default build can be overridden by 
command line.
The terms used:
- properties
- targets
- build request
- requested targets
- explicitly vs implicitly requested targets
- property derivation
- target requirements
>>
>>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.
- Free features vs incidental vs "normal"
Again, we can omit the overriding. We can explain it later. It's an 
advanced feature.
>>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"
We can move the tip into the reference documentation for <include> feature.
>>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 ;
>>
The example is very artificial. My example looks more realistic:
lib common : [ glob common/*.cpp ] ;
exe Client : Client.cpp common ;
exe Server : Server.cpp common ;
>>^[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.
> 
What are the "feature attributes" and "project attributes"? I don't know 
what this term means, but I'm able to use the BB and even to develop the 
BB. IMO we should use a simpler terminology. It's very cryptic for the 
beginners.
Andrey