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.