9.2. Build Sets

9.2. Build Sets
Prev	Chapter 9. Telling Abuild What to Build	Next

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
name:item-name[,item-name,...]: all build items whose names are listed
pattern:regular-expression: all build items whose names match the given perl-compatible regular expression

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
abuild --clean=all --clean-platforms java --clean-platforms '*.ix86.*': 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.