Rename certain target_set::insert() versions to insert_implied() for clarity

Also clarify the target_decl documentation.

7 files changed, 64 insertions, 57 deletions

diff --git a/libbuild2/build/script/parser.test.cxx b/libbuild2/build/script/parser.test.cxx
index 97eac22..1b28ec3 100644
--- a/libbuild2/build/script/parser.test.cxx
+++ b/libbuild2/build/script/parser.test.cxx
@@ -247,11 +247,11 @@ namespace build2
           // really care.
           //
           file& tt (
-            ctx.targets.insert<file> (work,
-                                      dir_path (),
-                                      "driver",
-                                      string (),
-                                      trace));
+            ctx.targets.insert_implied<file> (work,
+                                              dir_path (),
+                                              "driver",
+                                              string (),
+                                              trace));
 
           tt.path (path ("driver"));
 
diff --git a/libbuild2/cli/rule.cxx b/libbuild2/cli/rule.cxx
index 996ca51..7c571d4 100644
--- a/libbuild2/cli/rule.cxx
+++ b/libbuild2/cli/rule.cxx
@@ -120,7 +120,8 @@ namespace build2
                 prerequisite_members (a, t)))
           {
             if (g == nullptr)
-              g = &t.ctx.targets.insert<cli_cxx> (t.dir, t.out, t.name, trace);
+              g = &t.ctx.targets.insert_implied<cli_cxx> (
+                t.dir, t.out, t.name, trace);
 
             prerequisites ps;
             ps.push_back (p->as_prerequisite ());
diff --git a/libbuild2/cli/target.cxx b/libbuild2/cli/target.cxx
index 22ae75c..6e9601b 100644
--- a/libbuild2/cli/target.cxx
+++ b/libbuild2/cli/target.cxx
@@ -52,9 +52,9 @@ namespace build2
       //
       // Also required for the src-out remapping logic.
       //
-      ctx.targets.insert<cxx::hxx> (d, o, n, trace);
-      ctx.targets.insert<cxx::cxx> (d, o, n, trace);
-      ctx.targets.insert<cxx::ixx> (d, o, n, trace);
+      ctx.targets.insert_implied<cxx::hxx> (d, o, n, trace);
+      ctx.targets.insert_implied<cxx::cxx> (d, o, n, trace);
+      ctx.targets.insert_implied<cxx::ixx> (d, o, n, trace);
 
       return new cli_cxx (ctx, move (d), move (o), move (n));
     }
diff --git a/libbuild2/dist/operation.cxx b/libbuild2/dist/operation.cxx
index cfc90cf..dd1c87b 100644
--- a/libbuild2/dist/operation.cxx
+++ b/libbuild2/dist/operation.cxx
@@ -112,7 +112,7 @@ namespace build2
         //
         dir_path out (!rs.out_eq_src () ? out_src (d, rs) : dir_path ());
 
-        const T& t (rs.ctx.targets.insert<T> (
+        const T& t (rs.ctx.targets.insert_implied<T> (
                       move (d),
                       move (out),
                       p.leaf ().base ().string (),
diff --git a/libbuild2/parser.cxx b/libbuild2/parser.cxx
index 5321cd5..8af5804 100644
--- a/libbuild2/parser.cxx
+++ b/libbuild2/parser.cxx
@@ -10086,7 +10086,7 @@ namespace build2
       o = out_src (d, *root_);
     }
 
-    return ctx->targets.insert<T> (
+    return ctx->targets.insert_implied<T> (
       move (d),
       move (o),
       p.leaf ().base ().string (),
diff --git a/libbuild2/target.hxx b/libbuild2/target.hxx
index c1da26c..b008347 100644
--- a/libbuild2/target.hxx
+++ b/libbuild2/target.hxx
@@ -382,25 +382,28 @@ namespace build2
   //
 
   // A target can be entered for several reasons that are useful to
-  // distinguish for diagnostics, when considering as the default
-  // target, etc.
+  // distinguish for diagnostics, when considering as the default target, etc.
   //
-  // Note that the order of the enumerators is arranged so that their
-  // integral values indicate whether one "overrides" the other.
+  // Note that the order of the enumerators is arranged so that their integral
+  // values indicate whether one "overrides" the other.
   //
-  // We refer to the targets other than real and implied as
-  // dynamically-created or just dynamic.
+  // We refer to the targets other than real and implied as dynamically-
+  // created or just dynamic.
   //
-  // @@ We have cases (like pkg-config extraction) where it should probably be
-  //    prereq_file rather than implied (also audit targets.insert<> calls).
+  // Implied means the target's existence is implied by the presence of
+  // another entity in the buildfile or the environment. This can range from a
+  // target-specific variable assignment, to a group target (which may imply
+  // the presence of member), to targets implied by the presence of installed
+  // artifacts.
   //
-  // @@ Also, synthesized dependency declarations (e.g., in cc::link_rule) are
-  //    fuzzy: they feel more `real` than `implied`. Maybe introduce
-  //    `synthesized` in-between?
-  //
-  // @@ There are also now dynamically-discovered targets (ad hoc group
-  //    members; see depdb-dyndep --dyn-target) which currently end up
-  //    with prereq_new.
+  // Note that it's often tempting to add another class of declarations for
+  // what we refer to as synthesized dependencies (see cc::link_rule for an
+  // example). However, this is probably an orthogonal notion (maybe a
+  // sub-state) to declaration since we can synthesize a dependency based on
+  // any declaration, including real.  And saying that synthesized is stronger
+  // than real feels wrong. To put it another way, synthesized dependencies
+  // are more about the target-prerequisite relationship rather that the
+  // target.
   //
   enum class target_decl: uint8_t
   {
@@ -2030,17 +2033,18 @@ namespace build2
       return pair<target&, bool> (p.first, p.second.mutex () != nullptr);
     }
 
-    // Note that the following versions always enter implied targets.
+    // The following versions always enter implied targets and are primarily
+    // meant for entering members when there is a group or vice versa.
     //
     template <typename T>
     T&
-    insert (const target_type& tt,
-            dir_path dir,
-            dir_path out,
-            string name,
-            optional<string> ext,
-            tracer& t,
-            bool skip_find = false)
+    insert_implied (const target_type& tt,
+                    dir_path dir,
+                    dir_path out,
+                    string name,
+                    optional<string> ext,
+                    tracer& t,
+                    bool skip_find = false)
     {
       return insert (tt,
                      move (dir),
@@ -2054,25 +2058,26 @@ namespace build2
 
     template <typename T>
     T&
-    insert (const dir_path& dir,
-            const dir_path& out,
-            const string& name,
-            const optional<string>& ext,
-            tracer& t,
-            bool skip_find = false)
+    insert_implied (const dir_path& dir,
+                    const dir_path& out,
+                    const string& name,
+                    const optional<string>& ext,
+                    tracer& t,
+                    bool skip_find = false)
     {
-      return insert<T> (T::static_type, dir, out, name, ext, t, skip_find);
+      return insert_implied<T> (
+        T::static_type, dir, out, name, ext, t, skip_find);
     }
 
     template <typename T>
     T&
-    insert (const dir_path& dir,
-            const dir_path& out,
-            const string& name,
-            tracer& t,
-            bool skip_find = false)
+    insert_implied (const dir_path& dir,
+                    const dir_path& out,
+                    const string& name,
+                    tracer& t,
+                    bool skip_find = false)
     {
-      return insert<T> (dir, out, name, nullopt, t, skip_find);
+      return insert_implied<T> (dir, out, name, nullopt, t, skip_find);
     }
 
     // Note: not MT-safe so can only be used during serial execution.
diff --git a/libbuild2/test/script/parser.test.cxx b/libbuild2/test/script/parser.test.cxx
index 6838e47..7d63e7d 100644
--- a/libbuild2/test/script/parser.test.cxx
+++ b/libbuild2/test/script/parser.test.cxx
@@ -255,11 +255,11 @@ namespace build2
           // really care.
           //
           file& tt (
-            ctx.targets.insert<file> (work,
-                                      dir_path (),
-                                      "driver",
-                                      string (),
-                                      trace));
+            ctx.targets.insert_implied<file> (work,
+                                              dir_path (),
+                                              "driver",
+                                              string (),
+                                              trace));
 
           value& v (
             tt.assign (
@@ -268,11 +268,12 @@ namespace build2
           v = *ctx.build_host;
 
           testscript& st (
-            ctx.targets.insert<testscript> (work,
-                                            dir_path (),
-                                            name.leaf ().base ().string (),
-                                            name.leaf ().extension (),
-                                            trace));
+            ctx.targets.insert_implied<testscript> (
+              work,
+              dir_path (),
+              name.leaf ().base ().string (),
+              name.leaf ().extension (),
+              trace));
 
           tt.path (path ("driver"));
           st.path (name);