When abuild starts up, it determines a list of object-code platform types and, within each platform type, a list of platforms. Platforms are given initial priorities based on the order in which they are declared with later declarations having higher priority than earlier ones. (In this way, platforms added by plugins are preferred over internally defined ones.) By default, abuild builds each object-code build item on the highest priority platform in each of its platform types. Abuild may also choose to build an item on additional platforms to satisfy dependencies.

The list of platforms on which abuild will attempt to build an item may be overridden using platform selectors. Platform selectors may be specified in the ABUILD_PLATFORM_SELECTORS environment variable or on the command line using the --platform-selector or -p command-line flag. Each platform selector may refer to a specific platform type or may be a general selector for all platform types. There may be at most one selector for each platform type and at most one general selector. If multiple selectors for the sample platform type or multiple general selectors are specified, abuild chooses the last one. Selectors given on the command line always take precedence over those in the environment variable. This makes it possible for later options to override earlier ones or for the command line to override the environment. To specify multiple selectors in the environment, set the variable to contain multiple space-separated words. To specify multiple selectors on the command line, provide the command-line option more than once. For example:

--platform-selector selector [ --platform-selector selector ... ]

or

ABUILD_PLATFORM_SELECTORS="selector[ selector ... ]"

Each selector is of the form

[platform-type:]criteria

If no platform-type is specified, then the selector applies to all platform types. When applying selectors, abuild will always first try a selector for the specific platform type first. Only if there isn't one will abuild attempt to use the general selector.

The criteria field above may have one of the following forms:

The special skip selector removes all platforms from the type and is not valid without a platform-type qualifier. When it is used, all platforms are removed from that platform type, so no builds will be done in that platform type for any reason. This could be useful if you only wanted to do embedded builds, for example.

The other selectors are translated into an (os, cpu, toolset, compiler, option) tuple. Each field may be * or a platform field. The empty string may not be explicitly specified, but omitted fields are mapped to the empty string. For example, compiler=x is equivalent to ("", "", "", "x", ""). Any empty string field except for option matches the corresponding field of the highest priority platform (the last one declared) in the list of platforms for the given type. This is the always the first platform listed for the platform type by abuild --list-platforms. An empty option field means that the option field of the platform must be empty.

When picking platforms on which to build by default, abuild will always pick the first platform that matches the criteria. If there are no matches, it will pick the first platform of the platform type. If any of the fields of the selector are equal to *, then abuild will select all platforms that match the criteria, again falling back to only the first platform in the type if there are no matches.

Here are several examples. For purposes of discussion, assume that we have the following platforms, shown here by type:

If no platform selectors were provided, we would build native build items with linux.x86.rhel4.xlc and vxworks build items with vxworks.ppc.6_3.vxgcc. Here are several platform selectors along with a description of what they mean: