9.6. Target Selection

Although we have described how various options affect which
build items are built with which targets, we summarize that
information here so that it all appears in one place. Put
simply, the default behavior is that abuild applies any
explicitly named targets to all build items that directly match
the criteria for belonging to the named build set. Any build
items that abuild is building just to satisfy dependencies are
built with the all target. This behavior is
overridden by specifying
--apply-targets-to-deps, which causes abuild
to build all build items with the explicit targets. The exact
rules are described in the list below. These rules apply only
when a build set is specified with --build or
-b. There are several mutually exclusive
cases:

The --apply-targets-to-deps option was
specified or the explicit target is no-op.
In this case, any explicitly named targets are applied to all
items in the build set.

The --apply-targets-to-deps option was not
specified, the target is not no-op, and no
trait arguments were specified. In this case, all items that
were initially added to the build set, along with any build
items specified by any of their
build-also keys (with the
build-also relationship applied
recursively) are built with any explicitly specified targets.
Any other build items added to the build set to satisfy
dependencies are built with the all target.

The --apply-targets-to-deps option was not
specified, the target is not no-op,
--only-with-traitswas
specified, and --related-by-traitswas not specified. In this case, all
items belonging to the original build set (including
build-also expansion) and having all of
the named traits are built with the explicit targets. Other
items (dependencies of build items with the named traits but
that do not have the named traits themselves) are built with
the all target.

The --apply-targets-to-deps option was not
specified, the target is not no-op, and
--related-by-traitswas
specified. In this case, the build set is first constructed
normally and then restricted to any items that have all the
traits specified in the --only-with-traits
option, if any. Then it is expanded to include any build
item related to one of the original build set members by all
the traits named in --related-by-traits.
These related items are built with the explicit targets.
Other items, including additional dependencies of related
items, are built with the all target.