Boost logo

Boost-Build :

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-20 12:07:47

> Project Hierarchies
> So far we've only considered examples with one project (i.e. with one
> user-written Boost.Jam file, Jamroot).

Remove parentheses and place an em-dash before i.e.

> A typical large codebase would
> be composed of many projects organized into a tree. The top of the
> tree is called the project root. Every subproject is defined by a
> file called Jamfile in a descendant directory of the project root.
> The parent project of a subproject is defined by the nearest Jamfile
> or Jamroot file in an ancestor directory. For example, in the
> following directory layout:
> top/
> |
> +-- Jamroot
> |
> +-- app/
> | |
> | +-- Jamfile
> | `-- app.cpp
> |
> `-- util/
> |
> +-- foo/
> . |
> . +-- Jamfile
> . `-- bar.cpp
> the project root is top/. Because there is no Jamfile in top/util/,
> the projects in top/app/ and top/util/foo/ are immediate children of
> the root project.

It is not at all clear what the significance of the latter statement
is. I find it confusing to see it here with no explanation or way of
relating it to what I'm going to do with BB.

> Note
> When we refer to a “Jamfile,” set in normal type, we mean a file
> called either Jamfile or Jamroot. When we need to be more specific,
> the filename will be set as “Jamfile” or “Jamroot.”
> Projects inherit all attributes (such as requirements) from their
> parents. Inherited requirements are combined with any requirements
> specified by the sub-project. For example, if top/Jamroot has

Do a global search for "sub-project" and replace it with "subproject."

> <include>/home/ghost/local
> in its requirements, then all of its sub-projects will have it in
> their requirements, too. Of course, any project can add include paths
> to those specified by its parents. ^[5] More details can be found in
> the section called “Projects”.
> Invoking bjam without explicitly specifying any targets on the
> command-line builds the project rooted in the current directory.

"command-line" should only be hyphenated when used as an adjective,

a command-line tool

when used as a noun, command line is two separate words.

> Building a project does not automatically cause its sub-projects to
> be built unless the parent project's Jamfile explicitly requests it.
> In our example, top/Jamroot might contain:
> build-project app ;
Is this a directory or a subproject name? It isn't
clear from the example. It would be clearer to use a
subdirectory like util/foo, to distinguish whether I'm
going to be specifying a path

> which would cause the project in top/app/ to be built whenever the
> project in top/ is built. However, targets in top/util/foo/ will be
> built only if they are needed by targets in top/ or top/app/.
> ━━━━━━━━━━━━
> ^[5] Many features will be overridden, rather than added-to, in
> sub-projects. See the section called “Feature Attributes” for more
> information

Dave Abrahams
Boost Consulting

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