aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2019-05-06 13:59:51 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2019-05-06 13:59:51 +0200
commit29f1eb02ea4619b985864e28c4ceff70f1d2e21c (patch)
tree88ad665cc906e1fa0ca2222390999720aef3f1a0
parenta8c2fa28947960cce78d905ac9bbcb490ec78382 (diff)
Update and clarify target grouping terminology and semantics
-rw-r--r--build2/target.hxx59
1 files changed, 32 insertions, 27 deletions
diff --git a/build2/target.hxx b/build2/target.hxx
index cb1163f..a86a8be 100644
--- a/build2/target.hxx
+++ b/build2/target.hxx
@@ -154,7 +154,7 @@ namespace build2
// Target group to which this target belongs, if any. Note that we assume
// that the group and all its members are in the same scope (for example,
- // in variable lookup). We also don't support nested groups (with a small
+ // in variable lookup). We also don't support nested groups (with an
// exception for ad hoc groups; see below).
//
// The semantics of the interaction between the group and its members and
@@ -163,24 +163,24 @@ namespace build2
// out of member types that have no idea they are part of this group
// (e.g., cli.cxx{}).
//
- // Normally, however, there are two kinds of groups: "alternatives" and
- // "combination". In an alternatives group, normally one of the members is
- // selected when the group is mentioned as a prerequisite with, perhaps,
- // an exception for special rules, like aliases, where it makes more sense
- // to treat the group as a whole. In this case we say that the rule
+ // Normally, however, there are two kinds of groups: "all" and "choice".
+ // In a choice-group, normally one of the members is selected when the
+ // group is mentioned as a prerequisite with, perhaps, an exception for
+ // special rules, like aliases, where it makes more sense to treat such
+ // group prerequisites as a whole. In this case we say that the rule
// "semantically recognizes" the group and picks some of its members.
//
- // Updating an alternatives group as a whole can mean updating some subset
- // of its members (e.g., lib{}). Or the group may not support this at all
- // (e.g., obj{}).
+ // Updating a choice-group as a whole can mean updating some subset of its
+ // members (e.g., lib{}). Or the group may not support this at all (e.g.,
+ // obj{}).
//
- // In a combination group, when a group is updated, normally all members
- // are updates (and usually with a single command), though there could be
- // some members that are omitted, depending on the configuration (e.g., an
- // inline file not/being generated). When a combination group is mentioned
- // as a prerequisite, the rule is usually interested in the individual
- // members rather than the whole group. For example, a C++ compile rule
- // would like to "see" the ?xx{} members when it gets a cli.cxx{} group.
+ // In an all-group, when a group is updated, normally all its members are
+ // updates (and usually with a single command), though there could be some
+ // members that are omitted, depending on the configuration (e.g., an
+ // inline file not/being generated). When an all-group is mentioned as a
+ // prerequisite, the rule is usually interested in the individual members
+ // rather than the whole group. For example, a C++ compile rule would like
+ // to "see" the ?xx{} members when it gets a cli.cxx{} group.
//
// Which brings us to the group iteration mode. The target type contains a
// member called see_through that indicates whether the default iteration
@@ -188,10 +188,10 @@ namespace build2
// members or the group itself. For the iteration support itself, see the
// *_prerequisite_members() machinery below.
//
- // In a combination group we usually want the state (and timestamp; see
- // mtime()) for members to come from the group. This is achieved with the
- // special target_state::group state. You would normally also use the
- // group_recipe for group members.
+ // In an all-group we usually want the state (and timestamp; see mtime())
+ // for members to come from the group. This is achieved with the special
+ // target_state::group state. You would normally also use the group_recipe
+ // for group members.
//
// Note that the group-member link-up can happen anywhere between the
// member creation and rule matching so reading the group before the
@@ -199,9 +199,9 @@ namespace build2
//
const target* group = nullptr;
- // What has been described above is a "normal" group. That is, there is
- // a dedicated target type that explicitly serves as a group and there
- // is an explicit mechanism for discovering the group's members.
+ // What has been described above is a "explicit" group. That is, there is
+ // a dedicated target type that explicitly serves as a group and there is
+ // an explicit mechanism for discovering the group's members.
//
// However, sometimes, we may want to create a group on the fly out of a
// normal target type. For example, we have the libs{} target type. But
@@ -233,11 +233,16 @@ namespace build2
//
// - Members don't have prerequisites.
//
- // - Ad hoc group cannot have sub groups (of any kind) though an ad hoc
- // group can be a sub group of a normal group.
+ // - Ad hoc group cannot have sub-groups (of any kind) though an ad hoc
+ // group can be a sub-group of an explicit group.
//
- // - Member variable lookup skips the ad hoc group (since the group is
- // the first member, this is normally what we want).
+ // - Member variable lookup skips the ad hoc group (since the group is the
+ // first member, this is normally what we want).
+ //
+ // Note that ad hoc groups can be part of explicit groups. In a sense, we
+ // have a two-level grouping: an explicit group with its members each of
+ // which can be an ad hoc group. For example, lib{} contains libs{} which
+ // may have an import stub as its ad hoc member.
//
// Use add_adhoc_member(), find_adhoc_member() from algorithms to manage
// ad hoc members.