In order for abuild to use multiple trees, it must be able to find the roots of all the trees when it traverses the file system looking for Abuild.conf files. As described earlier, abuild locates the root of the forest by looking up toward the root of the file system for other Abuild.conf files that list previous Abuild.conf directories in their child-dirs key. The parent directory of our previous example contains (see Section 6.4, “Simple Build Tree Example”) the following Abuild.conf file:

child-dirs: common project derived

This is an unnamed build item containing only a child-dirs key. The child-dirs key lists not only the common directory, which is the root of the common tree, but also two other directories: project and derived, each of which we will discuss below. These directories contain additional build tree root build items, thus making them known to any abuild invocation that builds common. It is also okay to create one build tree underneath another named tree. As with build items, having one tree physically located beneath another doesn't have any implications about the dependency relationships among the trees.

We will examine a new build tree that declares the build tree from our previous example as an dependency. This new tree, which we will call the project build tree, can be found at doc/example/general/reference/project. The first file we examine is the new build tree's root build item's Abuild.conf:

tree-name: project
tree-deps: common
child-dirs: main lib

This build item configuration file, in addition to having the tree-name key (indicating that it is a root build item), also has a tree-deps key, whose value is the word common, which is the name of the tree whose items we want to use. Note that, as with build items, abuild never requires you to know the location of a build tree.

Inside the project build tree, the project-lib build item is defined inside the lib directory. It is set up exactly the same way as common-lib1 and the other libraries in the common tree. Here is its Abuild.conf:

name: project-lib
child-dirs: src test
deps: project-lib.src

Now look at project-lib.src's Abuild.conf:

name: project-lib.src
platform-types: native
deps: common-lib1

Notice that it declares a dependency on common-lib1, which is defined in the common tree. This works because abuild automatically makes available to you all the build items in any build trees your depends on.

This build tree also includes a main program, but we will not go through the rest of the files in depth. You are encouraged to study the files on your own. There are also examples of traits in this build tree. We will return to this build tree during our discussion of traits (see Section 9.5, “Traits”).

When you declare another build tree as a tree dependency, you automatically inherit any tree dependencies that that tree declared, so like item dependencies, tree dependencies are transitive. If this were not the case, abuild would not be able to resolve dependencies declared in the other tree if those dependencies were resolved in one of its tree dependencies. To illustrate this, we have a third build tree located in doc/example/general/reference/derived. This build tree is for a second project that is derived from the first project. This build tree declares project as an tree dependency as you can see in its root Abuild.conf file:

tree-name: derived
tree-deps: project
child-dirs: main

For a diagram of the entire general/reference collection of build tress, see Figure 7.2, “Build Trees in general/reference”.

Figure 7.2. Build Trees in general/reference

The derived build tree declares a dependency on the project build tree. The project build tree declares a dependency on the common build tree.

The derived build tree contains a derived-main build item structured identically to the C++ program build items we've seen earlier. Here at the main program's Abuild.conf:

name: derived-main.src
platform-types: native
deps: common-lib2 project-lib
traits: tester -item=derived-main.src

In this file, you can see that derived-main.src depends on project-lib from the project build tree and also common-lib2 which is found in project's dependency, common. We will return to this build tree in the examples at the end of Chapter 9, Telling Abuild What to Build.