Here we present a new series of build trees located under doc/example/general/user. These build trees back to our task and reference build trees from earlier examples. We will use these build trees to illustrate the use of the deleted key in a build tree's root build item's Abuild.conf.

Suppose we have a user who is working on changes that are related in some way to the task branch. We want to create a user branch that backs to the task branch. Our user branch contains all three areas: common, project, and derived. We will ignore derived for the moment and focus only common and project. Observe that common contains only the lib1 directory and that project contains only the lib directory. We make a gratuitous change to a source file in common-lib1.src just as another example of shadowing a build item from our backing area. Since our task branch didn't contain common, the common in our user branch has to back to reference. Here is user/common/Abuild.backing:

../../reference/common

For a diagram of the user build trees, see Figure 10.5, “Build Trees in general/user”.

Figure 10.5. Build Trees in general/user

The derived build tree in the user area declares the project build tree as an external. The project build tree in the user area declares the common build tree as an external. Each backs to its corresponding build tree in task except common. Since common does not exist in the task branch, common in the user area backs directly to common in reference.

In project, we have made changes to project-lib to make use of private interfaces, which we discuss in Chapter 20, Interface Flags and will ignore for the moment. We have also deleted the new build item project-lib.extra that we added in the task branch. To delete the build item, we removed the extra directory from project/lib and from the child-dirs key in project/lib/Abuild.conf:

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

That in itself was not sufficient since, even though the extra directory is no longer present in the child-dirs key of project-lib's Abuild.conf, we would just inherit project-lib.extra from our backing area. To really delete the build item, we also had to add a deleted key in user/project's Abuild.conf:

external-dirs: ../common
child-dirs: main lib
supported-traits: interesting
deleted: project-lib.extra

This has effectively prevented abuild from looking for project-lib.extra in the backing area chain. If any build item in the local tree references project-lib.extra, an error will be reported because abuild now considers that to be an unknown build item.