update reference doc page for GN

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 1235 matching lines @@
     print(i)
   }
 
   Prints:
   a
   b
   c
 
 
 ```
+## **forward_variables_from**: Copies variables from a different scope.
+
+```
+  forward_variables_from(from_scope, variable_list_or_star)
+
+  Copies the given variables from the given scope to the local scope
+  if they exist. This is normally used in the context of templates to
+  use the values of variables defined in the template invocation to
+  a template-defined target.
+
+  The variables in the given variable_list will be copied if they exist
+  in the given scope or any enclosing scope. If they do not exist,
+  nothing will happen and they be left undefined in the current scope.
+
+  As a special case, if the variable_list is a string with the value of
+  "*", all variables from the given scope will be copied. "*" only
+  copies variables set directly on the from_scope, not enclosing ones.
+  Otherwise it would duplicate all global variables.
+
+  When an explicit list of variables is supplied, if the variable exists
+  in the current (destination) scope already, an error will be thrown.
+  If "*" is specified, variables in the current scope will be
+  clobbered (the latter is important because most targets have an
+  implicit configs list, which means it wouldn't work at all if it
+  didn't clobber).
+
+  The sources assignment filter (see "gn help set_sources_assignment_filter")
+  is never applied by this function. It's assumed than any desired
+  filtering was already done when sources was set on the from_scope.
+
+```
+
+### **Examples**
+
+```
+  # This is a common action template. It would invoke a script with
+  # some given parameters, and wants to use the various types of deps
+  # and the visibility from the invoker if it's defined. It also injects
+  # an additional dependency to all targets.
+  template("my_test") {
+    action(target_name) {
+      forward_variables_from(invoker, [ "data_deps", "deps",
+                                        "public_deps", "visibility" ])
+      # Add our test code to the dependencies.
+      # "deps" may or may not be defined at this point.
+      if (defined(deps)) {
+        deps += [ "//tools/doom_melon" ]
+      } else {
+        deps = [ "//tools/doom_melon" ]
+      }
+    }
+  }
+
+  # This is a template around either a target whose type depends on a
+  # global variable. It forwards all values from the invoker.
+  template("my_wrapper") {
+    target(my_wrapper_target_type, target_name) {
+      forward_variables_from(invoker, "*")
+    }
+ }
+
+
+```
 ## **get_label_info**: Get an attribute from a target's label.
 
 ```
   get_label_info(target_label, what)
 
   Given the label of a target, returns some attribute of that target.
   The target need not have been previously defined in the same file,
   since none of the attributes depend on the actual target definition,
   only the label itself.
 
@@ skipping 722 matching lines @@
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
          defines, include_dirs, ldflags, lib_dirs, libs
          precompiled_header, precompiled_source
   Deps: data_deps, deps, forward_dependent_configs_from, public_deps
   Dependent configs: all_dependent_configs, public_configs
   General: check_includes, configs, data, inputs, output_name,
            output_extension, public, sources, testonly, visibility
 
 
 ```
+## **target**: Declare an target with the given programmatic type.
+
+```
+  target(target_type_string, target_name_string) { ... }
+
+  The target() function is a way to invoke a built-in target or template
+  with a type determined at runtime. This is useful for cases where the
+  type of a target might not be known statically.
+
+  Only templates and built-in target functions are supported for the
+  target_type_string parameter. Arbitrary functions, configs, and
+  toolchains are not supported.
+
+  The call:
+    target("source_set", "doom_melon") {
+  Is equivalent to:
+    source_set("doom_melon") {
+
+```
+
+### **Example**
+
+```
+  if (foo_build_as_shared) {
+    my_type = "shared_library"
+  } else {
+    my_type = "source_set"
+  }
+
+  target(my_type, "foo") {
+    ...
+  }
+
+
+```
 ## **template**: Define a template rule.
 
 ```
   A template defines a custom name that acts like a function. It
   provides a way to add to the built-in target types.
 
   The template() function is used to declare a template. To invoke the
   template, just use the name of the template like any other target
   type.
 
   Often you will want to declare your template in a special file that
   other files will import (see "gn help import") so your template
   rule can be shared across build files.
 
 ```
 
-### **More details**:
+### **Variables and templates**:
 
 ```
   When you call template() it creates a closure around all variables
   currently in scope with the code in the template block. When the
   template is invoked, the closure will be executed.
 
   When the template is invoked, the code in the caller is executed and
   passed to the template code as an implicit "invoker" variable. The
   template uses this to read state out of the invoking code.
 
   One thing explicitly excluded from the closure is the "current
   directory" against which relative file names are resolved. The
   current directory will be that of the invoking code, since typically
   that code specifies the file names. This means all files internal
   to the template should use absolute names.
 
+  A template will typically forward some or all variables from the
+  invoking scope to a target that it defines. Often, such variables
+  might be optional. Use the pattern:
+
+    if (defined(invoker.deps)) {
+      deps = invoker.deps
+    }
+
+  The function forward_variables_from() provides a shortcut to forward
+  one or more or possibly all variables in this manner:
+
+    forward_variables_from(invoker, ["deps", "public_deps"])
+
 ```
 
 ### **Target naming**:
 
 ```
   Your template should almost always define a built-in target with the
   name the template invoker specified. For example, if you have an IDL
   template and somebody does:
     idl("foo") {...
   you will normally want this to expand to something defining a
@@ skipping 2293 matching lines @@
   Leading zeros and negative zero are disallowed.
 
 ```
 
 ### **String literals**
 
 ```
   A string literal represents a string value consisting of the quoted
   characters with possible escape sequences and variable expansions.
 
-      string    = `"` { char | escape | expansion } `"` .
-      escape    = `\` ( "$" | `"` | char ) .
-      expansion = "$" ( identifier | "{" identifier "}" ) .
-      char      = /* any character except "$", `"`, or newline */ .
+      string           = `"` { char | escape | expansion } `"` .
+      escape           = `\` ( "$" | `"` | char ) .
+      BracketExpansion = "{" ( identifier | ArrayAccess | ScopeAccess ) "}" .
+      expansion        = "$" ( identifier | BracketExpansion ) .
+      char             = /* any character except "$", `"`, or newline */ .
 
   After a backslash, certain sequences represent special characters:
 
           \"    U+0022    quotation mark
           \$    U+0024    dollar sign
           \\    U+005C    backslash
 
   All other backslashes represent themselves.
 
 ```
@@ skipping 18 matching lines @@
       File = StatementList .
 
       Statement     = Assignment | Call | Condition .
       Assignment    = identifier AssignOp Expr .
       Call          = identifier "(" [ ExprList ] ")" [ Block ] .
       Condition     = "if" "(" Expr ")" Block
                       [ "else" ( Condition | Block ) ] .
       Block         = "{" StatementList "}" .
       StatementList = { Statement } .
 
+      ArrayAccess = identifier "[" { identifier | integer } "]" .
+      ScopeAccess = identifier "." identifier .
       Expr        = UnaryExpr | Expr BinaryOp Expr .
       UnaryExpr   = PrimaryExpr | UnaryOp UnaryExpr .
       PrimaryExpr = identifier | integer | string | Call
-                  | identifier "[" Expr "]"
-                  | identifier "." identifier
+                  | ArrayAccess | ScopeAccess
                   | "(" Expr ")"
                   | "[" [ ExprList [ "," ] ] "]" .
       ExprList    = Expr { "," Expr } .
 
       AssignOp = "=" | "+=" | "-=" .
       UnaryOp  = "!" .
       BinaryOp = "+" | "-"                  // highest priority
                | "<" | "<=" | ">" | ">="
                | "==" | "!="
                | "&&"
@@ skipping 104 matching lines @@
   at build generation time via "--runtime-deps-list-file"
   (see "gn help --runtime-deps-list-file").
 
   To a first approximation, the runtime dependencies of a target are
   the set of "data" files, data directories, and the shared libraries
   from all transitive dependencies. Executables and shared libraries are
   considered runtime dependencies of themselves.
 
 ```
 
-### **Details**
+### **Executables**
 
 ```
   Executable targets and those executable targets' transitive
   dependencies are not considered unless that executable is listed in
   "data_deps". Otherwise, GN assumes that the executable (and
   everything it requires) is a build-time dependency only.
 
+```
+
+### **Actions and copies**
+
+```
   Action and copy targets that are listed as "data_deps" will have all
   of their outputs and data files considered as runtime dependencies.
   Action and copy targets that are "deps" or "public_deps" will have
   only their data files considered as runtime dependencies. These
   targets can list an output file in both the "outputs" and "data"
   lists to force an output file as a runtime dependency in all cases.
 
+  The different rules for deps and data_deps are to express build-time
+  (deps) vs. run-time (data_deps) outputs. If GN counted all build-time
+  copy steps as data dependencies, there would be a lot of extra stuff,
+  and if GN counted all run-time dependencies as regular deps, the
+  build's parallelism would be unnecessarily constrained.
+
+  This rule can sometimes lead to unintuitive results. For example,
+  given the three targets:
+    A  --[data_deps]-->  B  --[deps]-->  ACTION
+  GN would say that A does not have runtime deps on the result of the
+  ACTION, which is often correct. But the purpose of the B target might
+  be to collect many actions into one logic unit, and the "data"-ness
+  of A's dependency is lost. Solutions:
+
+   - List the outputs of the action in it's data section (if the
+     results of that action are always runtime files).
+   - Have B list the action in data_deps (if the outputs of the actions
+     are always runtime files).
+   - Have B list the action in both deps and data deps (if the outputs
+     might be used in both contexts and you don't care about unnecessary
+     entries in the list of files required at runtime).
+   - Split B into run-time and build-time versions with the appropriate
+     "deps" for each.
+
+```
+
+### **Static libraries and source sets**
+
+```
   The results of static_library or source_set targets are not considered
   runtime dependencies since these are assumed to be intermediate
   targets only. If you need to list a static library as a runtime
   dependency, you can manually compute the .a/.lib file name for the
   current platform and list it in the "data" list of a target
   (possibly on the static library target itself).
 
+```
+
+### **Multiple outputs**
+
+```
   When a tool produces more than one output, only the first output
   is considered. For example, a shared library target may produce a
   .dll and a .lib file on Windows. Only the .dll file will be considered
-  a runtime dependency.
+  a runtime dependency. This applies only to linker tools, scripts and
+  copy steps with multiple outputs will also get all outputs listed.
 
 
 ```
 ## **How Source Expansion Works**
 
 ```
   Source expansion is used for the action_foreach and copy target types
   to map source file names to output file names or arguments.
 
   To perform source expansion in the outputs, GN maps every entry in the
@@ skipping 120 matching lines @@
 **  --nocolor**: Force non-colored output.
 **  -q**: Quiet mode. Don't print output on success.
 **  --root**: Explicitly specify source root.
 **  --runtime-deps-list-file**: Save runtime dependencies for targets in file.
 **  --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.
 
 ```