33.5. Construction of the Build Set

This section describes the process that abuild uses to construct the build set. First, abuild creates a list of build items that directly match the criteria of the specified build set. If --only-with-traits was specified, only build items that match the build set criteria and have all of the named traits are included. This is considered the explicit build set. In the absence of --related-by-traits or --apply-target-to-deps, this is the set of build items that will be built with any explicitly specified target.

Once this is finished, expansion of the build set is performed based on dependencies, build-also specification, traits, or reverse dependencies. Expansion is performed in two phases. In the first phase of expansion, all dependencies of any item in the build set is added to the build set, as are any item specified in any build-also key of any item's Abuild.conf. In the second phase, the build set is additionally expanded based on traits or reverse dependencies. Specifically, if abuild was invoked with the --with-rdeps option, all direct or indirect reverse dependencies of every item in the build set are added to the build set. Then, if --related-by-traits was specified, every build item that is related to an item in the set by the named traits is added to the build set.

After the completion of phase 2, we repeat the expansion process until we go through an expansion pass that adds no items. During repetitions of the expansion, the default behavior is that only phase 1 (dependencies and build-also) is repeated. However, if --repeat-expansion was specified, then phase 2 is repeated as well.

To understand the distinction between whether phase 2 of the expansion process is repeated, consider the following scenario. Suppose the original build set contains A and B, and that AC-test is declared as a tester of item A, which is in the build set, and also of item C which is not in the build set. If we are adding items related by the tester trait, the AC-test build item will be added to the build set. Assuming AC-test depends on C, then C will also be added to the build set since this is part of phase 1 of the expansion, which is always repeated until no new items are added. Now if there is another build item called C-test that tests C, it will only be added to the build set if --repeat-expansion was specified since it test an item that wasn't an original member of the build set. [63] When --with-rdeps is specified, the --repeat-expansion option is likely to have a much greater affect. In fact, it will cause any build item that is reachable in the dependency graph from any initial build item to be added to the build set. For many build trees, the combination of --with-rdeps and --repeat-expansion may end up causing every build item to be built. [64]

[63] In versions of abuild prior to 1.0.3, the second expansion phase was never repeated. In version 1.0.3, it was always repeated. When the --with-rdeps flag was introduced in abuild 1.1 and reverse dependency expansion was added to the second phase of expansion, the differences between repeating and not repeating the second phase became significant, so the --repeat-expansion option was added.

[64] Formally, if the dependency graph is divided into independent sets, the combination of --with-rdeps and --repeat-expansion will cause inclusion of all build items in any independent set that contains any of the initial build set members.