7.3. Tree Dependency Example

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:

general/reference/Abuild.conf

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:

general/reference/project/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:

general/reference/project/lib/Abuild.conf

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

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

general/reference/project/lib/src/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:

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.