In plain English, abuild guarantees that if A depends on B and B depends on C, A and B see the same copy of C. To be more precise, abuild checks to make sure that no build item in a backing area references as a dependency or plugin an item that is shadowed in the local forest. (Plugins are covered in Chapter 29, Enhancing Abuild with Plugins.)

We illustrate this in Figure 11.1, “Shadowed Dependency”. Suppose that build items A, B, and C are defined in build tree T2 and that A depends on B and B depends on C. Now suppose you have a local build tree called T1 that has T2 as its backing area, and that you have build items A and C copied locally into T1, but that B is resolved in the backing area.

Figure 11.1. Shadowed Dependency

A in /T1 sees B in /T2 and C in /T1, but B in /T2 sees C in /T2. This means A in /T1 builds with two different copies of C.

If you were to attempt to build A, A would refer to files in B, which comes from a backing area. B would therefore already be built, and it would have been built with the copy of C from the backing area. A, on the other hand, would see C in the local build tree. That means that A is indirectly using two different copies of C. Depending on what changes were made to C in the local build tree, this would likely cause the build of A to be unreproducible at best and completely broken at worst. The situation of B coming from a backing area and depending on C, which is shadowed locally, is what we mean when we say that B has shadowed dependencies. If you attempt to build in this situation, abuild will provide a detailed error message telling you which build items are shadowed and which other build items depend on them. One way to resolve this would be to copy the shadowed build items into your local build tree. In this case, that would mean copying B into T1. Another way to resolve it would be to remove C from your local area and allow that to be resolved in the backing area as well. This solution would obviously only be suitable if you were not working on C anymore.