Document GN invoker and target name variables.

tools/gn/variables.cc

Index: tools/gn/variables.cc
diff --git a/tools/gn/variables.cc b/tools/gn/variables.cc
index 7b2c4a088f7c6b1947e0edff16f022f7055b936b..948495cf7037c4671bc52cba176482a778941e68 100644
--- a/tools/gn/variables.cc
+++ b/tools/gn/variables.cc
@@ -44,6 +44,38 @@ const char kHostOs_Help[] =
     "  - \"mac\"\n"
     "  - \"win\"\n";
 
+const char kInvoker[] = "invoker";
+const char kInvoker_HelpShort[] =
+    "invoker: [string] The invoking scope inside a template.";
+const char kInvoker_Help[] =
+    "invoker: [string] The invoking scope inside a template.\n"
+    "\n"
+    "  Inside a template invocation, this variable refers to the scope of\n"
+    "  the invoker of the template. Outside of template invocations, this\n"
+    "  variable is undefined.\n"
+    "\n"
+    "  All of the variables defined inside the template invocation are\n"
+    "  accessible as members of the \"invoker\" scope. This is the way that\n"
+    "  templates read values set by the callers.\n"
+    "\n"
+    "  This is often used with \"defined\" to see if a value is set on the\n"
+    "  invoking scope.\n"
+    "\n"
+    "  See \"gn help template\" for more examples.\n"
+    "\n"
+    "Example\n"
+    "\n"
+    "  template(\"my_template\") {\n"
+    "    print(invoker.sources)       # Prints [ \"a.cc\", \"b.cc\" ]\n"
+    "    print(defined(invoker.foo))  # Prints false.\n"
+    "    print(defined(invoker.bar))  # Prints true.\n"
+    "  }\n"
+    "\n"
+    "  my_template(\"doom_melon\") {\n"
+    "    sources = [ \"a.cc\", \"b.cc\" ]\n"
+    "    bar = 123\n"
+    "  }\n";
+
 const char kTargetCpu[] = "target_cpu";
 const char kTargetCpu_HelpShort[] =
     "target_cpu: [string] The desired cpu architecture for the build.";
@@ -76,6 +108,47 @@ const char kTargetCpu_Help[] =
     "  - \"arm64\"\n"
     "  - \"mipsel\"\n";
 
+const char kTargetName[] = "target_name";
+const char kTargetName_HelpShort[] =
+    "target_name: [string] The name of the current target.";
+const char kTargetName_Help[] =
+    "target_name: [string] The name of the current target.\n"
+    "\n"
+    "  Inside a target or template invocation, this variable refers to the\n"
+    "  name given to the target or template invocation. Outside of these,\n"
+    "  this variable is undefined.\n"
+    "\n"
+    "  This is most often used in template definitions to name targets\n"
+    "  defined in the template based on the name of the invocation. This\n"
+    "  is necessary both to ensure generated targets have unique names and\n"
+    "  to generate a target with the exact name of the invocation that\n"
+    "  other targets can depend on.\n"
+    "\n"
+    "  Be aware that this value will always reflect the innermost scope. So\n"
+    "  when defining a target inside a template, target_name will refer to\n"
+    "  the target rather than the template invocation. To get the name of the\n"
+    "  template invocation in this case, you should save target_name to a\n"
+    "  temporary variable outside of any target definitions.\n"
+    "\n"
+    "  See \"gn help template\" for more examples.\n"
+    "\n"
+    "Example\n"
+    "\n"
+    "  executable(\"doom_melon\") {\n"
+    "    print(target_name)    # Prints \"doom_melon\".\n"
+    "  }\n"
+    "\n"
+    "  template(\"my_template\") {\n"
+    "    print(target_name)    # Prints \"space_ray\" when invoked below.\n"
+    "\n"
+    "    executable(target_name + \"_impl\") {\n"
+    "      print(target_name)  # Prints \"space_ray_impl\".\n"
+    "    }\n"
+    "  }\n"
+    "\n"
+    "  my_template(\"space_ray\") {\n"
+    "  }\n";
+
 const char kTargetOs[] = "target_os";
 const char kTargetOs_HelpShort[] =
     "target_os: [string] The desired operating system for the build.";
@@ -1713,6 +1786,7 @@ const VariableInfoMap& GetBuiltinVariables() {
     INSERT_VARIABLE(DefaultToolchain)
     INSERT_VARIABLE(HostCpu)
     INSERT_VARIABLE(HostOs)
+    INSERT_VARIABLE(Invoker)
     INSERT_VARIABLE(PythonPath)
     INSERT_VARIABLE(RootBuildDir)
     INSERT_VARIABLE(RootGenDir)
@@ -1720,6 +1794,7 @@ const VariableInfoMap& GetBuiltinVariables() {
     INSERT_VARIABLE(TargetCpu)
     INSERT_VARIABLE(TargetOs)
     INSERT_VARIABLE(TargetGenDir)
+    INSERT_VARIABLE(TargetName)
     INSERT_VARIABLE(TargetOutDir)
   }
   return info_map;