Document GN invoker and target name variables.

tools/gn/docs/reference.md

 # GN Reference
 
 *This page is automatically generated from* `gn help --markdown all`.
 
 ## **\--args**: Specifies build arguments overrides.
 
 ```
   See "gn help buildargs" for an overview of how build arguments work.
 
   Most operations take a build directory. The build arguments are taken
@@ skipping 521 matching lines @@
   The "configs" section will list all configs that apply. For targets
   this will include configs specified in the "configs" variable of
   the target, and also configs pushed onto this target via public
   or "all dependent" configs.
 
   Configs can have child configs. Specifying --tree will show the
   hierarchy.
 
 ```
 
+### **Printing outputs**
+
+```
+  The "outputs" section will list all outputs that apply, including
+  the outputs computed from the tool definition (eg for "executable",
+  "static_library", ... targets).
+
+```
+
 ### **Printing deps**
 
 ```
   Deps will include all public, private, and data deps (TODO this could
   be clarified and enhanced) sorted in order applying. The following
   may be used:
 
   --all
       Collects all recursive dependencies and prints a sorted flat list.
       Also usable with --tree (see below).
@@ skipping 1934 matching lines @@
   Sets the default values for a given target type. Whenever
   target_type_name is seen in the future, the values specified in
   set_default's block will be copied into the current scope.
 
   When the target type is used, the variable copying is very strict.
   If a variable with that name is already in scope, the build will fail
   with an error.
 
   set_defaults can be used for built-in target types ("executable",
   "shared_library", etc.) and custom ones defined via the "template"
-  command.
+  command. It can be called more than once and the most recent call in
+  any scope will apply, but there is no way to refer to the previous
+  defaults and modify them (each call to set_defaults must supply a
+  complete list of all defaults it wants). If you want to share
+  defaults, store them in a separate variable.
 
 ```
 
-### **Example**:
+### **Example**
+
 ```
   set_defaults("static_library") {
     configs = [ "//tools/mything:settings" ]
   }
 
   static_library("mylib")
     # The configs will be auto-populated as above. You can remove it if
     # you don't want the default for a particular default:
     configs -= "//tools/mything:settings"
   }
@@ skipping 127 matching lines @@
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
          asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
          precompiled_header, precompiled_source
   Deps: data_deps, deps, public_deps
   Dependent configs: all_dependent_configs, public_configs
   General: check_includes, configs, data, inputs, output_name,
            output_extension, public, sources, testonly, visibility
 
 
 ```
+## **split_list**: Splits a list into N different sub-lists.
+
+```
+  result = split_list(input, n)
+
+  Given a list and a number N, splits the list into N sub-lists of
+  approximately equal size. The return value is a list of the sub-lists.
+  The result will always be a list of size N. If N is greater than the
+  number of elements in the input, it will be padded with empty lists.
+
+  The expected use is to divide source files into smaller uniform
+  chunks.
+
+```
+
+### **Example**
+
+```
+  The code:
+    mylist = [1, 2, 3, 4, 5, 6]
+    print(split_list(mylist, 3))
+
+  Will print:
+    [[1, 2], [3, 4], [5, 6]
+
+
+```
 ## **static_library**: Declare a static library target.
 
 ```
   Make a ".a" / ".lib" file.
 
   If you only need the static library for intermediate results in the
   build, you should consider a source_set instead since it will skip
   the (potentially slow) step of creating the intermediate library file.
 
 ```
@@ skipping 926 matching lines @@
 ```
 
 ### **Some possible values**:
 ```
   - "linux"
   - "mac"
   - "win"
 
 
 ```
+## **invoker**: [string] The invoking scope inside a template.
+
+```
+  Inside a template invocation, this variable refers to the scope of
+  the invoker of the template. Outside of template invocations, this
+  variable is undefined.
+
+  All of the variables defined inside the template invocation are
+  accessible as members of the "invoker" scope. This is the way that
+  templates read values set by the callers.
+
+  This is often used with "defined" to see if a value is set on the
+  invoking scope.
+
+  See "gn help template" for more examples.
+
+```
+
+### **Example**
+
+```
+  template("my_template") {
+    print(invoker.sources)       # Prints [ "a.cc", "b.cc" ]
+    print(defined(invoker.foo))  # Prints false.
+    print(defined(invoker.bar))  # Prints true.
+  }
+
+  my_template("doom_melon") {
+    sources = [ "a.cc", "b.cc" ]
+    bar = 123
+  }
+
+
+```
 ## **python_path**: Absolute path of Python.
 
 ```
   Normally used in toolchain definitions if running some command
   requires Python. You will normally not need this when invoking scripts
   since GN automatically finds it for you.
 
 
 ```
 ## **root_build_dir**: [string] Directory where build commands are run.
@@ skipping 110 matching lines @@
 ### **Example**
 
 ```
   action("myscript") {
     # Pass the generated output dir to the script.
     args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]
   }
 
 
 ```
+## **target_name**: [string] The name of the current target.
+
+```
+  Inside a target or template invocation, this variable refers to the
+  name given to the target or template invocation. Outside of these,
+  this variable is undefined.
+
+  This is most often used in template definitions to name targets
+  defined in the template based on the name of the invocation. This
+  is necessary both to ensure generated targets have unique names and
+  to generate a target with the exact name of the invocation that
+  other targets can depend on.
+
+  Be aware that this value will always reflect the innermost scope. So
+  when defining a target inside a template, target_name will refer to
+  the target rather than the template invocation. To get the name of the
+  template invocation in this case, you should save target_name to a
+  temporary variable outside of any target definitions.
+
+  See "gn help template" for more examples.
+
+```
+
+### **Example**
+
+```
+  executable("doom_melon") {
+    print(target_name)    # Prints "doom_melon".
+  }
+
+  template("my_template") {
+    print(target_name)    # Prints "space_ray" when invoked below.
+
+    executable(target_name + "_impl") {
+      print(target_name)  # Prints "space_ray_impl".
+    }
+  }
+
+  my_template("space_ray") {
+  }
+
+
+```
 ## **target_os**: The desired operating system for the build.
 
 ```
   This value should be used to indicate the desired operating system
   for the primary object(s) of the build. It will match the OS of
   the default toolchain.
 
   In many cases, this is the same as "host_os", but in the case of
   cross-compiles, it may be different. This variable differs from
   "current_os" in that it can be referenced from inside any
@@ skipping 2450 matching lines @@
 **  \--root**: Explicitly specify source root.
 **  \--runtime-deps-list-file**: Save runtime dependencies for targets in file.
 **  \--script-executable**: Set the executable used to execute scripts.
 **  \--threads**: Specify number of worker threads.
 **  \--time**: Outputs a summary of how long everything took.
 **  \--tracelog**: Writes a Chrome-compatible trace log to the given file.
 **  -v**: Verbose logging.
 **  \--version**: Prints the GN version number and exits.
 
 ```