Re: [BBv2 doc editorial] tutorial/properties

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-21 11:28:52

Andrey Melnikov <melnikov_at_[hidden]> writes:

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

The passive voice doesn't help you here. Reducing clutter wasn't an
aim of introducing features. I like the corresponding part from my
original docs better.

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

That's important, and I think saying it improves things.

> Commonly available settings like <optimization>speed have the same 
> meaning for all compilers reducing or completely removing 
^--- need a comma here
> compiler-specific configuration. If nesessary, compiler- or
^^^^^^^^^
"necessary"
> os-specific options can be set too. 

Good to know, but I wonder if the user will be upset that you don't
show an example of that.

> Boost.Build doesn't limit you in any way.

That's a slight exaggeration, isn't it? I suggest dropping it.

> 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", 

These are common build-system related terms. Maybe it's too early to
introduce them here, but the reader should get some exposure early
on. Also, at least the meaning of "build variant" is easy to deduce
from the meaning of "variant" and the context.

> "associated values",

That's not a technical term; it's plain English.

> "toolset components", 
> "command-line flags", "requested properties", "build initiation", 
> "properties", "build configuration" aren't used at all.

Okay, I get your point.

> - The "Features" and "Toolset" terms are defined

Good; those are the most important terms to get exposed to early on.

> - The ideas behind the features are explained. The current document 
> misses "why" questions almost completely.

Good. Okay, I agree that your direction is a big improvement.

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

Surely you don't mean that. Do you mean that properties on the
command line won't be used for some time?

> They need to learn a lot first. bjam {toolset-name} is the most
> complex syntax they need in the Tutorial.

That may be true, but I don't think the syntax above is difficult, and
it's good for people to be exposed to a few simple things in an
introduction.

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

Okay, okay, point taken. Obviously we need someone to write an
_outline_ of the documentation structure, to decide when and how
particular ideas will be introduced. Gee sounds like something I was
advocating a year ago or so. Would you care to take that job on? It
doesn't require much skill with English grammar.

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

Yes, I meant to note that the tip was out of place here.

>>>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 ;

Yes, that's much better.

>>>^[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"? 

Umm, attributes of features and attributes of projects, respectively.
The term "attribute" is used with its plain English meaning.

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

I don't think there's anything wrong with this terminology, but I'd be
happy to consider alternatives if you have any suggestions.

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