So far we've only considered examples with one project (i.e. with one Jamfile). A typical large software project would be composed of sub-projects organized into a tree. The top of the tree is called the project root. Besides a Jamfile, the project root directory contains a file called project-root.jam. Every other Jamfile in the project has a single parent project, rooted in the nearest parent directory containing a Jamfile. For example, in the following directory layout:

top/ 
  |
  +-- Jamfile
  +-- project-root.jam
  |
  +-- src/
  |    |
  |    +-- 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/src/ and top/util/foo/ are immediate children of the root project.

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/Jamfile has

<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 additional includes. ^[3] More details can be found in the section on projects.

Invoking bjam without explicitly specifying any targets on the command-line builds the project rooted in the current directory. 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/Jamfile might contain:

build-project src ;

which would cause the project in top/src/ 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/src/.