Chapter 9. Telling Abuild What to Build

Table of Contents

9.1. Build Targets
9.2. Build Sets
9.2.1. Example Build Set Invocations
9.3. Using build-also for Top-level Builds
9.4. Building Reverse Dependencies
9.5. Traits
9.5.1. Declaring Traits
9.5.2. Specifying Traits at Build Time
9.5.3. Example Trait Invocations
9.6. Target Selection
9.7. Build Set and Trait Examples
9.7.1. Common Code Area
9.7.2. Tree Dependency Example: Project Code Area
9.7.3. Trait Example
9.7.4. Building Reverse Dependencies
9.7.5. Derived Project Example

Up to this point, we have seen only simple invocations of abuild to build a single item with all of its dependencies. Abuild offers several ways of creating sets of build items to build or clean. These are known as build sets. In addition, abuild's list of items to build can be expanded or restricted based on traits that are assigned to build items.

9.1. Build Targets

As defined in Section 3.2, “Basic Terminology”, the term target refers to a specific build product. In most cases, abuild passes any targets specified on the command line to the backend build system. Abuild provides several standard targets (see Chapter 13, Command-Line Reference). We have already encountered all and clean in earlier examples. It is also possible to add new targets through mechanisms that are covered later in the document. For now, you really only need to know a few things about targets:

  • Different targets tell abuild to build different things.

  • The all target is abuild's default target. When abuild builds a build item in order to satisfy a dependency, building the all target is required to be sufficient to satisfy the needs of items that depend on it. This means that the all target is responsible for building all parts of a build item that are potentially needed by any of its dependencies. This may seem significant, but it's a detail that takes care of itself most of the time.

  • With the exception of two special targets, abuild doesn't do anything itself with targets other than pass them onto the backend build tool.

Abuild defines two special targets: clean and no-op. These targets are special in two ways: abuild does not allow them to be combined with other targets, and abuild handles them itself without passing them to a backend.

The clean target is used to remove the artifacts that are built by the other targets. Abuild implements the clean target by simply removing all abuild-generated output directories (see Section 5.3, “Output Directories”). When abuild processes the clean target, it ignores any dependency relationships among build items. Since it ignores dependencies and performs the cleanup itself without invoking a backend, running the clean target or cleaning multiple items using a clean set (described below) is very fast.

Note that, starting with version 1.0.3, abuild cleans all build items, not just those with build files. There are several reasons for this:

  • In certain debugging modes, such as interface debugging mode, abuild may create output directories for items that don't build anything.

  • You might change a build item from an item that builds something to an interface-only build item. In this case, you will want a subsequent clean to remove the no-longer-needed output directories.

  • Although it is not necessarily recommended, there are some use cases in which build items may “push” files into the output directory of an interface-only build item. Some people may choose to implement installers that work this way. Having abuild clean interface-only build items makes it easier to clean up in those cases.

The no-op target is used primarily for debugging build tree problems. When abuild is invoked with the no-op target, it goes through all the motions of performing a build except that it does not read any Abuild.interface files or invoke any backends. It does, however, perform full validation of Abuild.conf files including dependency and integrity checking. This makes abuild no-op, especially with a build set (described below), very useful for taking a quick look at what items would be built on what platforms and in what order. We make heavy use of the no-op target in the examples at the end of this chapter so that we can illustrate certain aspects of build ordering without being concerned about the actual compilation steps.