9.2. Build Sets

We have already seen that, by default, abuild will build all of
the build items on which the current item depends (directly or
indirectly) in addition to building the current item. Now we
generalize on this concept by introducing build
sets. A build set is a collection of build items
defined by certain criteria. Build sets can be used both to tell
abuild which items to build and also to tell it which items to
clean.
[17]
When abuild is invoked with no build set specified, its default
behavior is to build all of the current item's dependencies as
well as the current item. Sometimes, you may wish to assume all
the dependencies are up to date and just build the current build
item without building any of its
dependencies. To do this, you may invoke abuild with the
--no-deps option. This will generally only work
if all dependencies are up to date. Using
--no-deps is most convenient when you are in the
midst of the edit/compile/test cycle on a single build item and
you want to save the time of checking whether a potentially long
chain of dependencies is already up to date.
[18]

To instruct abuild to build all the items in a specific build
set, run abuild
--build=set-name (or
abuild -b
set-name). To instruct
abuild to clean all the items in a specific build set, run
abuild
--clean=set-name (or
abuild -c
set-name). When building a
build set, abuild will also automatically build any items that
are direct or indirect dependencies of any items in the build
set. However, if you specify any explicit targets on the command
line, abuild will not, by default, apply those targets to items
that it only added to the build set to satisfy dependencies; it
will build those items with the all target
instead. This is important as it enables you to add custom
targets to a build item without necessarily having those targets
be defined for build items it depends on. If you want abuild
to build dependencies with explicitly named targets as well, use
the --apply-targets-to-deps option. When
cleaning with a build set, abuild does not ordinarily also
clean the dependencies of the items in the set. To apply the
clean target to all the dependencies as well,
we also use the --apply-targets-to-deps option.
This is a bit subtle, so we present several examples below.

The following build sets are defined:

current

the current build item (i.e., the build
item whose Abuild.conf is in the current
directory); abuild's default behavior is identical to
--build=current

deps

all direct and indirect dependencies of the current build item
but not the item itself

desc

all build items located at or below the current directory
(items that are descendants of the
current directory)

descending

alias for desc

down

alias for desc

local

all items in the build tree containing the item in the
current directory; i.e., the local build
tree without any of its trees dependencies, noting that items
in tree dependencies may, as always, still to be built to
satisfy item dependencies

deptrees

all items in the build tree containing the item in the
current directory as well as all items in any of its tree
dependencies
[19]

descdeptrees

all build items that are located at or below the current
directory and are either in the current build tree or one of
its dependencies—effectively the intersection between
desc and deptrees[20]

all

all items in all known build trees, including those items in
trees that are not related to the current build tree

Ordinarily, when you invoke abuild clean or
abuild
--clean=set-name, abuild
will remove all output directories for any affected build items.
You may also restrict abuild to remove only specified output
directories. There are two ways to do this. One way is to run
abuild clean from inside an output directory.
In that case, abuild will remove all the files in the output
directory.
[21]
The other way is to use the --clean-platforms
option, which may be followed by a shell-style regular expression
that is matched against the platform portion of the output
directory name. Examples are shown below.

9.2.1. Example Build Set Invocations

abuild

builds the all target for all dependencies
of the current directory's build item and for the current
directory; equivalent to abuild
--build=current

abuild --no-deps

builds the current directory without building any of its
dependencies

abuild check
(or abuild --build=current check)

builds the check target for the current
build item and the all target for all of
its direct and indirect dependencies

abuild --apply-targets-to-deps check

builds the check target for the current
build item and all of its direct and indirect dependencies

abuild --build=local check

builds the check target for all build items
in the local build tree and the all target
for any dependencies of any local items that may be satisfied
in other trees

abuild --build=deptrees check

builds the check target for all build items
in the local build tree and all of its tree dependencies

abuild --clean=current (or abuild
clean)

removes all output directories for the current build item but
not for any of its dependencies

abuild --clean=desc

removes all output directories for all build items at or below
the current directory but not any of its dependencies

for all build items, removes all
abuild-java output directories and all
output directories for platforms containing the string
“.ix86.”

abuild --clean=current --apply-targets-to-deps

removes all output directories for the current build item and
everything it depends on; useful when you want to try a
completely clean build of a particular item

abuild --apply-targets-to-deps --clean=desc

removes all output directories for all build items at or
below the current directory and all of their direct or
indirect dependencies, including those that are not located
at or below the current directory

abuild --build=name:lib1,lib2 xyz

builds the custom xyz target for the
lib1 and lib2
build items and the all target for their
direct or indirect dependencies

abuild --build=pattern:'.*\.test'

builds the all target for any item whose
name ends with .test and any of those
items' direct or indirect dependencies

abuild -b all

builds the all target for all build items
in all known trees in the forest

abuild -c all

removes all output directories in all the build trees in the
forest

[17]
In retrospect, the term build item set
would probably have been a better name for this. Just keep in
mind that build sets can be used for both building and
cleaning, and that when we use build sets for cleaning, we
sometimes call them clean sets instead.

[18]
In abuild 1.0, this was the default behavior, and the
--with-deps option was required in order to
tell abuild to build the dependencies.

[19]
This is what the [all] build set did in
abuild 1.0. In abuild 1.1, [all]
may be more expansive since abuild now actually knows
about all trees in the forest, not just those referenced by
the current tree.

[20]
This is what the [desc] build set did in
abuild 1.0. In abuild 1.1, [desc]
includes all build items at or below
the current directory, but in abuild 1.0, abuild didn't
know about those not in the dependency chain of the current
tree. This build set is provided so there is an equivalent
in abuild 1.1 to every build set from abuild 1.0.
There are relatively few reasons to ever use it.

[21]
In abuild 1.0, abuild actually passed the
clean target to the backend, but abuild
version 1.1 handles this clean invocation
internally as it does for other clean
invocations.