Here we present a new forest located under doc/example/general/user. This forest backs to the task forest from the previous example. We will use this forest to illustrate the use of the deleted-item key in the Abuild.backing.

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 trees: common, project, and derived. We will ignore derived for the moment and focus only common and project. For a diagram of the user build trees, see Figure 11.3, “Build Trees in general/user”.

Figure 11.3. Build Trees in general/user

The user forest backs to the task forest. All trees are present, so they all resolve locally.

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.

In project, we have made changes to project-lib to make use of private interfaces, which we discuss in Chapter 23, 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:

name: project-lib
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-item key in user/Abuild.backing:

backing-areas: ../task
deleted-items: project-lib.extra

This has effectively prevented abuild from looking for project-lib.extra in the backing area. 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.

Although we don't present any examples of using deleted-tree, it works in a very similar fashion. Ordinarily, any build tree you do not have locally will be inherited from the backing area. If your intention is to change the code so that it no longer uses a particular tree, and you want to make sure that that tree is not available at all in your local area, you can delete it using deleted-tree. However, if you simply remove it from all your tree-deps directives, there is no risk of your using its items by accident. As such, most people will probably never need to use the deleted-tree feature.