In addition to being able to resolve build items to backing areas, it is also possible to resolve externals to backing areas. Specifically, if abuild can't find the specified external relative to the root of the current build tree, it will search for it relative to the roots of each tree in the backing area chain. ^[22] This is illustrated in Figure 10.1, “External Resolved in a Backing Area”. In this case, we have a build tree at /backing/1 that declares ../ext as an external in its root Abuild.conf. Abuild finds this external at /backing/ext. We also have a tree at /tree/1 that declares /backing/1 as a backing area. As is typical with build trees that have backing areas, the new build tree's root Abuild.conf is initially a copy of the root Abuild.conf from its backing area. It therefore also declares ../ext as an external. When abuild attempts to find the external, it looks first in ../ext relative to /tree/1, which would be /tree/ext. Since that path does not exist, abuild will look for ../ext relative to each backing area in the backing area chain. In this case, it finds /backing/ext as ../ext relative to backing area /backing/1, thus successfully resolving the external to the backing area.

Figure 10.1. External Resolved in a Backing Area

/tree/1 resolves external ../ext to /backing/ext.

The upshot of this behavior is that, when you wish to shadow build items in a particular build tree but you don't need to shadow any of the build items in its externals, you can just ignore the externals. Abuild will resolve them to the backing area just as it would resolve any build items you omitted from your local tree.

There is one corner case with backing areas and externals. It will very seldom occur, but it's worth mentioning for completeness. Understanding this case is not essential to make use of abuild for the vast majority of cases, so if this doesn't make sense to you, just continue reading at the beginning of the next section.

For this case, suppose that you still didn't actually want to shadow any of the build items in the external tree but you wanted your local tree to see the external in some location other than /backing/ext, say /other/ext. As illustrated in Figure 10.2, “External with Separate Backing Area”, you could create a directory called /tree/ext and place within that directory an Abuild.backing containing /other/ext as the only file in /tree/ext; i.e., there would be no /tree/ext/Abuild.conf file. In this case, the build tree at /tree/ext would be an empty build tree that resolves all of its build items from its backing area, /other/ext.

Figure 10.2. External with Separate Backing Area

/tree/1's external ../ext backs to /other/ext rather than /backing/ext.

This is the only case in which abuild will allow a build tree to not contain an Abuild.conf file at its root.