Boost logo

Boost-Build :

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
> 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
> 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
> in the section called “Build process”.

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

> 1.
> Applying default build. If the default-build property of a
> 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
> alternative's requirements, and in build request. The
> alternative with large number of matching properties is
> 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
> 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
> 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
> 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,
> 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.

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

Boost-Build list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at