[BBv2 doc editorial] tutorial/hierarchy

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,
e.g.

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
www.boost-consulting.com