Fix GN docs for 'gn help deps' and update reference.md.

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 136 matching lines @@
   This is probably not useful; the use-case for this feature is
   generally executable targets.
 
   The runtime dependency file will list one file per line, with no
   escaping. The files will be relative to the root_build_dir. The first
   line of the file will be the main output file of the target itself
   (in the above example, "bar.so").
 
 
 ```
+## **\--threads**: Specify number of worker threads.
+
+```
+  GN runs many threads to load and run build files. This can make
+  debugging challenging. Or you may want to experiment with different
+  values to see how it affects performance.
+
+  The parameter is the number of worker threads. This does not count the
+  main thread (so there are always at least two).
+
+```
+
+### **Examples**
+
+```
+  gen gen out/Default --threads=1
+
+
+```
 ## **\--time**: Outputs a summary of how long everything took.
 
 ```
   Hopefully self-explanatory.
 
 ```
 
 ### **Examples**
 
 ```
@@ skipping 836 matching lines @@
    3. Public_configs from a breadth-first traversal of the dependency
       tree in the order that the targets appear in "deps".
    4. All dependent configs from a breadth-first traversal of the
       dependency tree in the order that the targets appear in "deps".
 
 ```
 
 ### **Variables valid in a config definition**:
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
-         defines, include_dirs, ldflags, lib_dirs, libs
+         defines, include_dirs, ldflags, lib_dirs, libs,
          precompiled_header, precompiled_source
 
 ```
 
 ### **Variables on a target used to apply configs**:
 ```
   all_dependent_configs, configs, public_configs,
   forward_dependent_configs_from
 
 ```
@@ skipping 178 matching lines @@
   exec_script("//foo/bar/myscript.py")
 
 
 ```
 ## **executable**: Declare an executable target.
 
 ### **Variables**
 
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
-         defines, include_dirs, ldflags, lib_dirs, libs
+         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
 
 
 ```
 ## **foreach**: Iterate over a list.
 
@@ skipping 754 matching lines @@
   listing the shared library in its "deps". If you don't want this
   (say you dynamically load the library at runtime), then you should
   depend on the shared library via "data_deps" instead.
 
 ```
 
 ### **Variables**
 
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
-         defines, include_dirs, ldflags, lib_dirs, libs
+         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
 
 
 ```
 ## **source_set**: Declare a source set target.
 
@@ skipping 20 matching lines @@
   final shared library and not from the intermediate targets." There is
   no way to express this concept when linking multiple static libraries
   into a shared library.
 
 ```
 
 ### **Variables**
 
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
-         defines, include_dirs, ldflags, lib_dirs, libs
+         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
 
 
 ```
 ## **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.
 
 ```
 
 ### **Variables**
 
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
-         defines, include_dirs, ldflags, lib_dirs, libs
+         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.
 
@@ skipping 343 matching lines @@
 
         This is typically used to prepend "lib" to libraries on
         Posix systems:
           output_prefix = "lib"
 
     precompiled_header_type  [string]
         Valid for: "cc", "cxx", "objc", "objcxx"
 
         Type of precompiled headers. If undefined or the empty string,
         precompiled headers will not be used for this tool. Otherwise
-        use "msvc" which is the only currently supported value.
+        use "gcc" or "msvc".
 
         For precompiled headers to be used for a given target, the
         target (or a config applied to it) must also specify a
         "precompiled_header" and, for "msvc"-style headers, a
-        "precompiled_source" value.
-
+        "precompiled_source" value. If the type is "gcc", then both
+        "precompiled_header" and "precompiled_source" must resolve
+        to the same file, despite the different formats required for each.
         See "gn help precompiled_header" for more.
 
     restat  [boolean]
         Valid for: all tools (optional, defaults to false)
 
         Requests that Ninja check the file timestamp after this tool has
         run to determine if anything changed. Set this if your tool has
         the ability to skip writing output if the output file has not
         changed.
 
@@ skipping 685 matching lines @@
   dependencies have been resolved. Therefore, a target will not see
   these force-added configs in their "configs" variable while the
   script is running, and then can not be removed. As a result, this
   capability should generally only be used to add defines and include
   directories necessary to compile a target's headers.
 
   See also "public_configs".
 
 ```
 
-### **Ordering of flags and values**:
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
@@ skipping 63 matching lines @@
 
   "cflags" are passed to all invocations of the C, C++, Objective C,
   and Objective C++ compilers.
 
   To target one of these variants individually, use "cflags_c",
   "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
   These variant-specific versions will be appended to the "cflags".
 
 ```
 
-### **Ordering of flags and values**:
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
@@ skipping 12 matching lines @@
 
   "cflags" are passed to all invocations of the C, C++, Objective C,
   and Objective C++ compilers.
 
   To target one of these variants individually, use "cflags_c",
   "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
   These variant-specific versions will be appended to the "cflags".
 
 ```
 
-### **Ordering of flags and values**:
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
@@ skipping 12 matching lines @@
 
   "cflags" are passed to all invocations of the C, C++, Objective C,
   and Objective C++ compilers.
 
   To target one of these variants individually, use "cflags_c",
   "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
   These variant-specific versions will be appended to the "cflags".
 
 ```
 
-### **Ordering of flags and values**:
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
@@ skipping 12 matching lines @@
 
   "cflags" are passed to all invocations of the C, C++, Objective C,
   and Objective C++ compilers.
 
   To target one of these variants individually, use "cflags_c",
   "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
   These variant-specific versions will be appended to the "cflags".
 
 ```
 
-### **Ordering of flags and values**:
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
@@ skipping 12 matching lines @@
 
   "cflags" are passed to all invocations of the C, C++, Objective C,
   and Objective C++ compilers.
 
   To target one of these variants individually, use "cflags_c",
   "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
   These variant-specific versions will be appended to the "cflags".
 
 ```
 
-### **Ordering of flags and values**:
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
@@ skipping 76 matching lines @@
 ### **Example**
 
 ```
   static_library("foo") {
     complete_static_lib = true
     deps = [ "bar" ]
   }
 
 
 ```
-## **configs**: Configs applying to this target.
+## **configs**: Configs applying to this target or config.
 
 ```
   A list of config labels.
 
-  The include_dirs, defines, etc. in each config are appended in the
-  order they appear to the compile command for each file in the target.
-  They will appear after the include_dirs, defines, etc. that the target
-  sets directly.
+```
+
+### **Configs on a target**
+
+```
+  When used on a target, the include_dirs, defines, etc. in each config
+  are appended in the order they appear to the compile command for each
+  file in the target. They will appear after the include_dirs, defines,
+  etc. that the target sets directly.
+
+  Since configs apply after the values set on a target, directly setting
+  a compiler flag will prepend it to the command line. If you want to
+  append a flag instead, you can put that flag in a one-off config and
+  append that config to the target's configs list.
 
   The build configuration script will generally set up the default
   configs applying to a given target type (see "set_defaults").
   When a target is being defined, it can add to or remove from this
   list.
 
 ```
 
-### **Ordering of flags and values**:
+### **Configs on a config**
+
+```
+  It is possible to create composite configs by specifying configs on a
+  config. One might do this to forward values, or to factor out blocks
+  of settings from very large configs into more manageable named chunks.
+
+  In this case, the composite config is expanded to be the concatenation
+  of its own values, and in order, the values from its sub-configs
+  *before* anything else happens. This has some ramifications:
+
+   - A target has no visibility into a config's sub-configs. Target
+     code only sees the name of the composite config. It can't remove
+     sub-configs or opt in to only parts of it. The composite config may
+     not even be defined before the target is.
+
+   - You can get duplication of values if a config is listed twice, say,
+     on a target and in a sub-config that also applies. In other cases,
+     the configs applying to a target are de-duped. It's expected that
+     if a config is listed as a sub-config that it is only used in that
+     context. (Note that it's possible to fix this and de-dupe, but it's
+     not normally relevant and complicates the implementation.)
+
+```
+
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
      the "deps" list. This is done recursively. If a config appears
      more than once, only the first occurance will be used.
   6. public_configs pulled from dependencies, in the order of the
      "deps" list. If a dependency is public, they will be applied
      recursively.
 
 ```
 
-### **Example**:
+### **Example**
+
 ```
-  static_library("foo") {
-    configs -= "//build:no_rtti"  # Don't use the default RTTI config.
-    configs += ":mysettings"      # Add some of our own settings.
+  # Configs on a target.
+  source_set("foo") {
+    # Don't use the default RTTI config that BUILDCONFIG applied to us.
+    configs -= [ "//build:no_rtti" ]
+
+    # Add some of our own settings.
+    configs += [ ":mysettings" ]
+  }
+
+  # Create a default_optimization config that forwards to one of a set
+  # of more specialized configs depending on build flags. This pattern
+  # is useful because it allows a target to opt in to either a default
+  # set, or a more specific set, while avoid duplicating the settings in
+  # two places.
+  config("super_optimization") {
+    cflags = [ ... ]
+  }
+  config("default_optimization") {
+    if (optimize_everything) {
+      configs = [ ":super_optimization" ]
+    } else {
+      configs = [ ":no_optimization" ]
+    }
   }
 
 
 ```
 ## **data**: Runtime data file dependencies.
 
 ```
   Lists files or directories required to run the given target. These are
   typically data files or directories of data files. The paths are
   interpreted as being relative to the current build file. Since these
@@ skipping 48 matching lines @@
 ## **defines**: C preprocessor defines.
 
 ```
   A list of strings
 
   These strings will be passed to the C/C++ compiler as #defines. The
   strings may or may not include an "=" to assign a value.
 
 ```
 
-### **Ordering of flags and values**:
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
@@ skipping 43 matching lines @@
   }
 
 
 ```
 ## **deps**: Private linked dependencies.
 
 ```
   A list of target labels.
 
   Specifies private dependencies of a target. Shared and dynamic
-  libraries will be linked into the current target. Other target types
-  that can't be linked (like actions and groups) listed in "deps" will
-  be treated as "data_deps". Likewise, if the current target isn't
-  linkable, then all deps will be treated as "data_deps".
+  libraries will be linked into the current target.
 
   These dependencies are private in that it does not grant dependent
   targets the ability to include headers from the dependency, and direct
   dependent configs are not forwarded.
 
   See also "public_deps" and "data_deps".
 
 
 ```
 ## **forward_dependent_configs_from**
@@ skipping 51 matching lines @@
 ## **include_dirs**: Additional include directories.
 
 ```
   A list of source directories.
 
   The directories in this list will be added to the include path for
   the files in the affected target.
 
 ```
 
-### **Ordering of flags and values**:
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
@@ skipping 73 matching lines @@
   specify various linking options. Most targets will not need these and
   will use "libs" and "lib_dirs" instead.
 
   ldflags are NOT pushed to dependents, so applying ldflags to source
   sets or static libraries will be a no-op. If you want to apply ldflags
   to dependent targets, put them in a config and set it in the
   all_dependent_configs or public_configs.
 
 ```
 
-### **Ordering of flags and values**:
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
@@ skipping 15 matching lines @@
   will be treated as being relative to the current build file.
 
   libs and lib_dirs work differently than other flags in two respects.
   First, then are inherited across static library boundaries until a
   shared library or executable target is reached. Second, they are
   uniquified so each one is only passed once (the first instance of it
   will be the one used).
 
 ```
 
-### **Ordering of flags and values**:
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
@@ skipping 32 matching lines @@
   the lib_prefix, and the ".framework" suffix will be trimmed.
 
   libs and lib_dirs work differently than other flags in two respects.
   First, then are inherited across static library boundaries until a
   shared library or executable target is reached. Second, they are
   uniquified so each one is only passed once (the first instance of it
   will be the one used).
 
 ```
 
-### **Ordering of flags and values**:
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
@@ skipping 184 matching lines @@
   dependencies have been resolved. Therefore, a target will not see
   these force-added configs in their "configs" variable while the
   script is running, and then can not be removed. As a result, this
   capability should generally only be used to add defines and include
   directories necessary to compile a target's headers.
 
   See also "all_dependent_configs".
 
 ```
 
-### **Ordering of flags and values**:
+### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
@@ skipping 749 matching lines @@
 ```
 
 **  \--args**: Specifies build arguments overrides.
 **  \--color**: Force colored output.
 **  \--dotfile**: Override the name of the ".gn" file.
 **  \--markdown**: write the output in the Markdown format.
 **  \--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.
+**  \--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.
 
 ```