8.2. Build Sets

8.2. Build Sets
Prev	Chapter 8. Telling Abuild What to Build	Next

We have already seen the --with-deps option, which tells abuild to build all 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 and without the --with-deps, it builds the build item whose Abuild.conf is in the current directory, assuming that all items that this build item depends on are up to date. ^[18] When any build set is specified, abuild attempts to build all dependencies, just like when --with-deps is specified.

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. If you want abuild to build those items 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); --with-deps is equivalent 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)
local: all items in the build tree containing the item in the current directory; i.e., the local build tree without any of its externals
all: all items in the local build tree and all writable external build trees
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

8.2.1. Example Build Set Invocations

abuild: builds the current directory without building any of its dependencies
abuild --with-deps: 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 --with-deps 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 --build=current --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 external trees
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
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
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

^[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] Ideally, one would never invoke abuild in this way: the maximum reliability would be achieved if abuild always checked all dependent build items. In practice, however, the typical development process involves multiple cycles of changing files and recompiling individual units of code while the rest of the system stays the same. In these cases, having abuild re-evaluate all the dependencies when you know that nothing has changed would cause an unnecessary increase in the amount of time you spend waiting for abuild to run.