Although backing areas and externals serve completely different purposes, there are a number of similarities between them. For this reason, people often get confused initially about which one to use for a particular case. Here is a list of use cases, each of which is accompanied by a discussion of which type of outside build tree to use.
If you had a collection of build items implementing common code, you would reference the common code build tree as an external. The common code build tree would be expected to be a stand-alone build tree (possibly with its own additional externals and backing area) that could exist completely independently from your local build tree. Your local tree would include additional build items that may depend on these, but it would not override or replace any build items from the common code area.
Suppose you had a large software baseline consisting of thousands of build items, and that you didn't want your developers to all have to have fully populated local copies of the build tree. Instead, you wanted to provide a read-only reference area that was fully built, say, once a day. Then your developers could create local work areas populated only with the portions of the code that they were actually modifying. Each developer could set their backing area to the location of this read-only reference area. Each developer's local tree would most likely shadow some build items from the backing area, and they may also add new build items corresponding to development of new code.
If you had a collection of build items that provided abuild
wrappers around third-party software, such as
Abuild.interface files that add those
libraries to the library path or classpath, you would likely
put those utility items in an external. As with the common
code area, developers would depend on the items from the
third-party support area but would not override or replace
them.
Suppose you wanted to make modifications to a project to complete a particular task. You may create a side branch for that task in your version control system. In this case, you might have a build tree based on the branch point of your side branch that would serve as the backing area for the task branch. You could modify some components in your local work area and simply omit any unmodified portions of the system from that work area. We provide an example of this usage below.
A good rule of thumb is this: if your purpose is to make modifications to a part of a build tree without having to have local copies of the part of the system that you are not changing, you should be using a backing area. If your purpose is to make use of a separate and self-contained collection of build items, you should be using an external. It is very common for externals to correspond to separate development efforts. Backing areas typically correspond to earlier or more stable versions of the same development effort.
Here we will draw a comparison to how abuild treats certain situations with respect to backing areas and externals:
If a build item in your local tree has the same name as a build item in one of its externals, abuild considers this to be an error and reports it as a duplicated build item name. If a build item in your local tree has the same name as a build item in its backing area, this is the normal case of using a local tree to shadow a backing area.
A build item in a local tree is free to depend on a build item located in either an external or a backing area. If a build item in an external tried to depend on a build item in the local tree, abuild would report this as a dependency on an unknown build item because the build items in the external have no knowledge of the build items in the local tree. If a build item in a backing area had a dependency on a build item that was shadowed in the local tree, abuild would report this as an integrity error and require you to make a local copy of the build item from the backing area, as discussed above in Section 10.4, “Integrity Checks”.