[BBv2 doc editorial] The Build Process

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-22 14:19:38

> When you've described your targets, you want Boost.Build to run the
> right tools and create the needed targets. This section will
> describe two things: how you specify what to build, and how the main
> targets are actually constructed.
> 
> The most important thing to note is that in Boost.Build, unlike
^^^^^^^^^^^^^^^^^^^^^^^^^^^
strike
> other build tools, the targets you declare do not correspond to
> specific files. What you declare in a Jamfile is more like a
> “metatarget.” Depending on the properties you specify on the command
> line, each metatarget will produce a set of real targets
> corresponding to the requested properties. It is quite possible that
> the same metatarget is built several times with different
> properties, producing different files. 

> Tip
> 
> This means that for Boost.Build, you cannot directly obtain a
> build variant from a Jamfile. 

What could "obtain a build variant from a Jamfile" possibly mean?

> There could be several variants
> requested by the user, and each target can be built with
> different properties.

This is not a tip. A tip is: "here's an easy way to do xxx"
I don't know what it is, in fact, because I can't understand it.

> Build request

Ironically, this section doesn't define the term "build request,"
which is being used as a technical term!

> The command line specifies which targets to build and with which
> properties. For example:
>
> 
> bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full
> 
> would build two targets, "app1" and "lib1//lib1" with the specified
> properties. You can refer to any targets, using target id and
^^^^^^^^^
what is that supposed to be? You haven't defined it. ^
comma required here--------^

> specify arbitrary properties. Some of the properties are very
^^^^^^
strike
> common, and for them the name of the property can be omitted. For
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
so Boost.Build has been designed to infer them automatically from a
solitary value.
> example, the above can be written as:
>
> 
> bjam app1 lib1//lib1 gcc debug optimization=full
> 
> The complete syntax, which has some additional shortcuts, is
> described in the section called “Command line”.
>
> Building a main target
> 
> When you request, directly or indirectly, 
^^^^^^^^^^

I don't think most readers will infer what that means.

> a build of a main target
> with specific requirements, the following steps are 
^^^^^^^^^^^^^^^^^^^^^^^^^^
strike. All main targets have specific requirements, which may be
empty. Also your phraseology makes it sound like the "specific
requirements" are part of the request.

> made. Some brief explanation is provided, and more details are given
^^^^
"taken"
> in the section called “Build process”.

Point of preference: I would remove "ing" from the first word of each
item.

> 1.
> 
> Applying default build. If the default-build property of a
^
"the"
> target specifies a value of a feature that is not present in the
> build request, that value is added.

Added to what?

> 2.
> 
> Selecting the main target alternative to use. For each
> alternative we look how many properties are present both in
^^^^
count
> alternative's requirements, and in build request. The
> alternative with large number of matching properties is
^^^^^
greatest
> selected.
> 
> 3.
> 
> Determining "common" properties. The build request is refined
^^^^^^^
???????
> with target's requirements. The conditional properties in
> requirements are handled as well. Finally, default values of
> features are added.

This is just too vague. What is "handled?" What is "refined?"

> 4.
> 
> Building targets referred by the sources list and 
^
"to"
> dependency properties. The list of sources and the properties
^^^^^^^^^^^^^^^^^^^^^
What is that? Brand new term?!
> can refer to other target using target references. For each
^
"s"
> reference, we take all propagated properties, refine them by
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^
What is that? Brand new term?! ??????

> explicit properties specified in the target reference, and
> pass the resulting properties as build request to the other
^^^^^
"dependency"
> target.

What does it mean to "pass the properties as a build request to" a
target? Are targets like functions that can be called?

> 5.
> 
> Adding the usage requirements produced when building
> dependencies to the "common" properties. When dependencies are
^^^^^^^^^^^^^^^^^^^
What is that? Brand new term?!

> built in the previous step, they return both the set of
^^^^^^
What is that? The reader can't understand and doesn't need to know
this! Strike this sentence

> created "real" targets, and usage requirements. The usage
> requirements are added to the common properties and the
^ ^^^^^^^^^^^^^^^^^---????
"of dependencies built in step 4"
> resulting property set will be used for building the current
> target.
> 
> 6.
> 
> Building the target using generators. To convert the sources
> to the desired type, Boost.Build uses "generators" --- objects
^^^^
replace w/em dash-^^^^
> that correspond to tools like compilers and linkers. Each
> generator declares what type of targets it can produce and
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"the target types it produces"
> what type of sources it requires. Using this information,
^^^^
the
> Boost.Build determines which generators must be run to produce
> a specific target from specific sources. When generators are
> run, they return the "real" targets.
^^^^^^
?????? maybe "determine?"
> 
> 7.
> 
> Computing the usage requirements to be returned. The
^^^^^^^^^^^^^^
?????????????? strike
> conditional properties in usage requirements are expanded 
^^^^^^^^
????????
> and the result is returned.
> 
> 
> Building a project
> 
> Often, a user builds a complete project, not just one main
> target. In fact, invoking bjam without arguments builds the project
> defined in the current directory.
> 
> When a project is built, the build request is passed without
> modification to all main targets in that project. It's is possible
> to prevent implicit building of a target in a project with the
> explicit rule:
> 
> explicit hello_test ;
> 
> would cause the hello_test target to be built only if explicitly
> requested by the user or by some other target.
> 
> The Jamfile for a project can include a number of build-project rule
^^^^^^^^^^^^^^^^^^^
"invoke the"
> calls that specify additional projects to be built.
^^^^^^^^^^
"to"

At this point I get the feeling that I'm wasting my time poking at
these low-level problems because the real, deep problems are in two
other places: lack of a workable overall high-level organization for
the documentation with a vision for what should be communicated at
each stage, and implementation/design choices that make certain
features almost impossible to explain.

We're fixing the first one, but I don't know what to do about the
second one.

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