We will examine a new build tree that uses the build tree from our previous example (see Section 6.4, “Simple Build Tree Example”) as an external. 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:

external-dirs: ../common
child-dirs: main lib

This build item configuration file, in addition to having the child-dirs key, also has an external-dirs key. In this case, the value of this key is the relative path ../common. It is common for an external tree to be in a parallel directory structure to your build tree, so having the location start with “..” is not unusual. There are also valid reasons to have an external build tree nested inside of your own tree. As always, it's best to come up with some conventions and to follow them uniformly.

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 external tree. Here is its Abuild.conf:

this: project-lib
parent-dir: ..
child-dirs: src test
deps: project-lib.src

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

this: project-lib.src
platform-types: native
parent-dir: ..
deps: common-lib1

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

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 8.3, “Traits”).

When you declare another build tree as an external, you automatically inherit any externals that that tree declared as externals as well. If this were not the case, abuild would not be able to resolve dependencies declared in the external if those dependencies were resolved in its externals. 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 external build tree. For a diagram of the entire general/reference collection of build tress, see Figure 7.1, “Build Trees in general/reference”.

Figure 7.1. Build Trees in general/reference

The derived build tree declares the project build tree as an external. The project build tree declares the common build tree as an external.

Here is its root Abuild.conf:

child-dirs: main
external-dirs: ../project

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

this: derived-main.src
platform-types: native
parent-dir: ..
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 external located at ../common. We will return to this build tree in the examples at the end of Chapter 8, Telling Abuild What to Build.