In large development environments, it is common to have collections of code that may be shared across multiple projects, and it's also common to have multiple development efforts being worked in parallel with the intention of integrating them at a later date. Ideally, such collections of shared code should be accessible by multiple projects but should not be able to access code from the those projects, and parallel development efforts should be kept independent to the maximum possible extent. In order to support this distributed and parallel style of software development, abuild allows you to divide your work up into multiple build trees, which coexist in a build forest. These trees can remain completely independent from each other, and you can also establish one-way dependency relationships among trees.
We define the following additional terms:
The local build tree is the build tree that contains the current directory.
A tree dependency is a separate build tree whose items can supplement the local build tree. Build items in the local build tree can resolve the names of build items in the tree named as a tree dependency, but build items in the dependency cannot see items in the dependent (local) build tree.
Abuild.conf
The top-level Abuild.conf is an
Abuild.conf file that is higher in th
file system than any other Abuild.conf
file in the build forest. If you are building a single tree,
the top-level Abuild.conf file is
typically the root build item of that tree. If you are
building multiple trees, you have to create a higher-level
Abuild.conf file that can reach the roots
of all the trees you are going to use, directly or indirectly,
through its child-dirs key.
Even when abuild knows about multiple trees, it still won't
allow items in one build tree to refer to items in other trees
without an explicit instruction to do so. This makes it possible
to ensure that items in one tree are not
accidentally modified to depend on items in
a tree that is supposed to be unrelated. When you want items in
one tree to be able to use items in another tree, you declare a
tree dependency of one tree on another.
This creates a one-way relationship between the two trees such
that items in the dependent tree (the one
that declares the dependency) can see items in the tree on which
it depends, but no visibility is possible in the other direction.
To declare a tree dependency, you list the name of the tree
dependency in the tree-deps key of the
dependent tree's Abuild.conf file. As with
item dependencies listed in deps, abuild
requires that there are no cycles among tree dependencies.
There is nothing special about a build tree that makes it able to be the target of a tree dependency: any tree can depend on any other tree as long as no dependency cycles are created.
Once you set up another tree as a tree dependency of your tree,
all build items defined in the tree named by the tree dependency
are available to you (subject to normal scoping rules) as if they
were in your local build tree. Since any tree can potentially
have a dependency relationship with any other, abuild enforces
that none of the build items in any build tree may have the same
name as any build item in any tree in the forest. In order to
avoid build item name clashes, it's a good idea to pick a naming
convention for your build items that includes some kind of
tree-based prefix, as we have done with names like
common-lib1.