In this section, we will discuss backing areas from a functionality standpoint. This section presents a somewhat simplified view of how backing areas actually work, but it is good enough to cover the normal cases. To understand the exact mechanism that abuild uses to handle backing areas and externals with enough detail to fully understand the subtleties of how they work, please see Section 29.3, “Traversal Details”.

The purpose of a backing area is to enable a developer to create a partially populated build tree and to fall back to a more complete area for build items that are omitted in the local build tree. A build tree may have at most one backing area, but its backing area's backing area is also searched, thus creating a chain of backing areas. When abuild attempts to resolve a name to a path, if it is unable to resolve the name in your local build tree or its externals, it effectively searches for the name in your backing area chain, using whichever location it finds first. ^[21] In this respect, your local build tree may shadow build items in your backing area. We should draw a contrast here between backing areas and externals. Although they are both separate build trees that abuild uses to discover build items, a local build tree can only shadow build items in its backing area chain. It cannot shadow build items in its externals. If a local build tree and one of its externals define build items with the same name, this is an error. If a local build tree and its backing area define build items with the same name, this is a normal case of using your local build area to modify code that may exist in the backing area in an earlier version.

There is one important point about how abuild resolves build items in backing areas. When abuild looks for a build item, it looks for it only by name, not by path. This means that a build item in your local build tree does not have to have the same location relative to the root of the tree as that item has in the backing area. This is very important as it allows you to use a local build tree to reorganize build items. Note that this means that if you delete a build item from your local build tree and that build item exists in your backing area, the build item doesn't really go away from abuild's perspective; rather it moves from the local build tree to the backing area. If it is actually your intention to remove the build item so that its name is not known to other build items in your build tree, you can do this by adding the name of the build item to the deleted key of the root build item's Abuild.conf file. If a build item is listed there, abuild requires that the build item be present in the backing area chain but not in the local build tree. We present an example that illustrates the use of the deleted key in Section 10.7, “Deleted Build Item”.