Document GN invoker and target name variables.

tools/gn/variables.cc

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "tools/gn/variables.h"
 
 namespace variables {
 
 // Built-in variables ----------------------------------------------------------
 
@@ skipping 26 matching lines @@
     "  build system's settings.\n"
     "\n"
     "  This value should generally be treated as read-only. It, however,\n"
     "  is not used internally by GN for any purpose.\n"
     "\n"
     "Some possible values:\n"
     "  - \"linux\"\n"
     "  - \"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.";
 const char kTargetCpu_Help[] =
     "target_cpu: The desired cpu architecture for the build.\n"
     "\n"
     "  This value should be used to indicate the desired architecture for\n"
     "  the primary objects of the build. It will match the cpu architecture\n"
     "  of the default toolchain, but not necessarily the current toolchain.\n"
     "\n"
@@ skipping 12 matching lines @@
     "\n"
     "  Where practical, use one of the following list of common values:\n"
     "\n"
     "Possible values:\n"
     "  - \"x86\"\n"
     "  - \"x64\"\n"
     "  - \"arm\"\n"
     "  - \"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.";
 const char kTargetOs_Help[] =
     "target_os: The desired operating system for the build.\n"
     "\n"
     "  This value should be used to indicate the desired operating system\n"
     "  for the primary object(s) of the build. It will match the OS of\n"
     "  the default toolchain.\n"
     "\n"
@@ skipping 1617 matching lines @@
 
 const VariableInfoMap& GetBuiltinVariables() {
   static VariableInfoMap info_map;
   if (info_map.empty()) {
     INSERT_VARIABLE(CurrentCpu)
     INSERT_VARIABLE(CurrentOs)
     INSERT_VARIABLE(CurrentToolchain)
     INSERT_VARIABLE(DefaultToolchain)
     INSERT_VARIABLE(HostCpu)
     INSERT_VARIABLE(HostOs)
+    INSERT_VARIABLE(Invoker)
     INSERT_VARIABLE(PythonPath)
     INSERT_VARIABLE(RootBuildDir)
     INSERT_VARIABLE(RootGenDir)
     INSERT_VARIABLE(RootOutDir)
     INSERT_VARIABLE(TargetCpu)
     INSERT_VARIABLE(TargetOs)
     INSERT_VARIABLE(TargetGenDir)
+    INSERT_VARIABLE(TargetName)
     INSERT_VARIABLE(TargetOutDir)
   }
   return info_map;
 }
 
 const VariableInfoMap& GetTargetVariables() {
   static VariableInfoMap info_map;
   if (info_map.empty()) {
     INSERT_VARIABLE(AllDependentConfigs)
     INSERT_VARIABLE(AllowCircularIncludesFrom)
@@ skipping 45 matching lines @@
     INSERT_VARIABLE(Testonly)
     INSERT_VARIABLE(Visibility)
     INSERT_VARIABLE(WriteRuntimeDeps)
   }
   return info_map;
 }
 
 #undef INSERT_VARIABLE
 
 }  // namespace variables