B.5. Redesigned Build Tree Structure

Abuild 1.1 introduces a new build tree structure that replaces
externals with named trees and named tree dependencies. In
abuild 1.0, one build tree established a one-way relationship
with another tree, gaining the ability to use the other tree's
build items without making its own build items available to the
other tree, by declaring the other tree as an external.
Externals were set up by specifying a relative path to the other
tree. Externals could be resolved in backing areas by resolving
that relative path as relative to the backing area instead of to
the tree itself.

There were three major problems with this approach. The first
and most important problem is that externals were based on path.
Not only is this in violation of a fundamental design principle
of abuild, but it forced build environments with multiple trees
to organize those trees in a strict relative directory structure.
Worse, knowledge of that directory structure was not contained in
any one location but was, instead, spread out among all the root
build trees in the system. This made it very hard to reuse
specific trees across multiple projects or even across multiple
configurations of the same project. The second problem with the
1.0 scheme was that there was no way for you to get a complete
list of all the trees that comprised any given build environment.
The third problem is that the interaction with backing areas an
externals was too complex and didn't scale. People were never
really able to understand how backing areas and externals
interacted.

Abuild 1.1 resolves all of these problems by requiring build
trees to be named and by setting up the one-way relationship
among build trees through named tree dependencies. The new
mechanism is discussed in detail in Chapter 7, Multiple Build Trees. Here is a brief summary of the
changes:

Abuild 1.1 introduces the term build
forest to refer to the collection of all the build
trees that are built together. The 1.1 concept of build
forests roughly corresponds to an abuild 1.0 build tree with
all of its externals.

The this key has been replaced with
name.

Build trees are required to be named. Root build items must
contain a key called tree-name which
gives the name of the tree.

Rather than using the deprecated
external-dirs key to indicate by path a
one-way dependency on another build tree, use
tree-deps to indicate this dependency
using the name of the other build tree.
This removes abuild 1.0's flawed use of paths for this
purpose.

The parent-dir key is no longer used.

It is permissible to have Abuild.conf
files above the roots of all your build trees that contain
only child-dirs keys. These files, in
addition to build tree root files, may be roots of the entire
forest of build trees.

Additionally, the way backing areas work has been significantly
improved. Backing areas are discussed in Chapter 11, Backing Areas. Here is a summary of the changes:

Backing areas are at the forest level, not at the tree level.
When abuild 1.1 is used, any given development effort
requires only a single Abuild.backing
file, and that file will be located at the root of the forest.
In 1.0 compatibility mode, abuild will still use information
from old style Abuild.backing files at
the roots of not-yet-upgraded trees in the forest, though such
files are considered deprecated.

Abuild.backing files are now key/value
pairs like Abuild.conf files. Valid keys
are backing-areas,
deleted-trees, and
deleted-items.

The paths to your backing areas are specified as the value to
the backing-areas key in
Abuild.backing. You may now have
multiple backing areas. Abuild will issue an error if
unrelated backing areas try to supply build items or build
trees with the same name. (If one of your backing areas backs
to another one of your backing areas, abuild will notice
this case and handle it appropriately.)

The deleted key is no longer valid in
Abuild.conf. Instead, use the
deleted-items key in
Abuild.backing. In 1.0 compatibility
mode, abuild will still read the information from the
Abuild.conf file and treat it as if it
had been read from an Abuild.backing
file.

It is possible to suppress inheritance of entire trees from
backing ares using the deleted-trees key
in Abuild.backing.