Support explicit pools in actions

tools/gn/docs/reference.md

 # GN Reference
 
 *This page is automatically generated from* `gn help --markdown all`.
 
 ## Contents
 
 *   [Commands](#commands)
     *   [analyze: Analyze which targets are affected by a list of files.](#analyze)
     *   [args: Display or configure arguments declared by the build.](#args)
     *   [check: Check header dependencies.](#check)
@@ skipping 78 matching lines @@
     *   [cflags_cc: [string list] Flags passed to the C++ compiler.](#cflags_cc)
     *   [cflags_objc: [string list] Flags passed to the Objective C compiler.](#cflags_objc)
     *   [cflags_objcc: [string list] Flags passed to the Objective C++ compiler.](#cflags_objcc)
     *   [check_includes: [boolean] Controls whether a target's files are checked.](#check_includes)
     *   [code_signing_args: [string list] Arguments passed to code signing script.](#code_signing_args)
     *   [code_signing_outputs: [file list] Output files for code signing step.](#code_signing_outputs)
     *   [code_signing_script: [file name] Script for code signing.](#code_signing_script)
     *   [code_signing_sources: [file list] Sources for code signing step.](#code_signing_sources)
     *   [complete_static_lib: [boolean] Links all deps into a static library.](#complete_static_lib)
     *   [configs: [label list] Configs applying to this target or config.](#configs)
-    *   [console: [boolean] Run this action in the console pool.](#console)
+    *   [console: [boolean] Use console pool for the pool object.](#console)
     *   [data: [file list] Runtime data file dependencies.](#data)
     *   [data_deps: [label list] Non-linked dependencies.](#data_deps)
     *   [defines: [string list] C preprocessor defines.](#defines)
     *   [depfile: [string] File name for input dependencies for actions.](#depfile)
     *   [deps: [label list] Private linked dependencies.](#deps)
     *   [include_dirs: [directory list] Additional include directories.](#include_dirs)
     *   [inputs: [file list] Additional compile-time dependencies.](#inputs)
     *   [ldflags: [string list] Flags passed to the linker.](#ldflags)
     *   [lib_dirs: [directory list] Additional library directories.](#lib_dirs)
     *   [libs: [string list] Additional libraries to link.](#libs)
@@ skipping 481 matching lines @@
 #### **Examples**
 ```
   gn format //some/BUILD.gn
   gn format some\\BUILD.gn
   gn format /abspath/some/BUILD.gn
   gn format --stdin
 ```
 ### <a name="gen:"></a>**gn gen**: Generate ninja files.
 
 ```
-  gn gen [<ide options>] <out_dir>
+  gn gen [--check] [<ide options>] <out_dir>
 
   Generates ninja files from the current tree and puts them in the given output
   directory.
 
   The output directory can be a source-repo-absolute path name such as:
       //out/foo
   Or it can be a directory relative to the current directory such as:
       out/foo
 
+  "gn gen --check" is the same as running "gn check". See "gn help check"
+  for documentation on that mode.
+
   See "gn help switches" for the common command-line switches.
 ```
 
 #### **IDE options**
 
 ```
   GN optionally generates files for IDE. Possibilities for <ide options>
 
   --ide=<ide_name>
       Generate files for an IDE. Currently supported values:
@@ skipping 60 matching lines @@
   a list of include paths and defines. Because GN does not generate a full
   .cproject definition, it is not possible to properly define includes/defines
   for each file individually. Instead, one set of includes/defines is generated
   for the entire project. This works fairly well but may still result in a few
   indexer issues here and there.
 ```
 
 #### **Generic JSON Output**
 
 ```
-  Dumps target information to JSON file and optionally invokes python script on
-  generated file. See comments at the beginning of json_project_writer.cc and
-  desc_builder.cc for overview of JSON file format.
+  Dumps target information to a JSON file and optionally invokes a
+  python script on the generated file. See the comments at the beginning
+  of json_project_writer.cc and desc_builder.cc for an overview of the JSON
+  file format.
 
   --json-file-name=<json_file_name>
       Overrides default file name (project.json) of generated JSON file.
 
   --json-ide-script=<path_to_python_script>
       Executes python script after the JSON file is generated. Path can be
       project absolute (//), system absolute (/) or relative, in which case the
       output directory will be base. Path to generated JSON file will be first
       argument when invoking script.
 
@@ skipping 1427 matching lines @@
 
 ```
   Pool objects can be applied to a tool to limit the parallelism of the
   build. This object has a single property "depth" corresponding to
   the number of tasks that may run simultaneously.
 
   As the file containing the pool definition may be executed in the
   context of more than one toolchain it is recommended to specify an
   explicit toolchain when defining and referencing a pool.
 
+  A pool marked "console = true" will use the built-in ninja "console"
+  pool and cannot specify "depth" which is always 1.
+
   A pool is referenced by its label just like a target.
 ```
 
 #### **Variables**
 
 ```
-  depth*
+  console, depth*
   * = required
 ```
 
 #### **Example**
 
 ```
   if (current_toolchain == default_toolchain) {
     pool("link_pool") {
       depth = 1
     }
@@ skipping 521 matching lines @@
       "asm": Assembler
 
     Linker tools:
       "alink": Linker for static libraries (archives)
       "solink": Linker for shared libraries
       "link": Linker for executables
 
     Other tools:
       "stamp": Tool for creating stamp files
       "copy": Tool to copy files.
+      "action": Defaults for actions
 
     Platform specific tools:
       "copy_bundle_data": [iOS, OS X] Tool to copy files in a bundle.
       "compile_xcassets": [iOS, OS X] Tool to compile asset catalogs.
 ```
 
 #### **Tool variables**
 
 ```
     command  [string with substitutions]
-        Valid for: all tools (required)
+        Valid for: all tools except "action" (required)
 
         The command to run.
 
     default_output_dir  [string with substitutions]
         Valid for: linker tools
 
         Default directory name for the output file relative to the
         root_build_dir. It can contain other substitution patterns. This will
         be the default value for the {{output_dir}} expansion (discussed below)
         but will be overridden by the "output_dir" variable in a target, if one
@@ skipping 79 matching lines @@
         Example for a linker tool that produces a .dll and a .lib. The use of
         {{target_output_name}}, {{output_extension}} and {{output_dir}} allows
         the target to override these values.
           outputs = [
             "{{output_dir}}/{{target_output_name}}"
                 "{{output_extension}}",
             "{{output_dir}}/{{target_output_name}}.lib",
           ]
 
     pool [label, optional]
+        Valid for: all tools (optional)
 
         Label of the pool to use for the tool. Pools are used to limit the
         number of tasks that can execute concurrently during the build.
 
         See also "gn help pool".
 
     link_output  [string with substitutions]
     depend_output  [string with substitutions]
         Valid for: "solink" only (optional)
 
@@ skipping 50 matching lines @@
 
         Normally, Ninja will assume that when a tool runs the output be new and
         downstream dependents must be rebuild. When this is set to trye, Ninja
         can skip rebuilding downstream dependents for input changes that don't
         actually affect the output.
 
         Example:
           restat = true
 
     rspfile  [string with substitutions]
-        Valid for: all tools (optional)
+        Valid for: all tools except "action" (optional)
 
         Name of the response file. If empty, no response file will be
         used. See "rspfile_content".
 
     rspfile_content  [string with substitutions]
-        Valid for: all tools (required when "rspfile" is specified)
+        Valid for: all tools except "action" (required when "rspfile" is used)
 
         The contents to be written to the response file. This may include all
         or part of the command to send to the tool which allows you to get
         around OS command-line length limits.
 
         This example adds the inputs and libraries to a response file, but
         passes the linker flags directly on the command line:
           tool("link") {
             command = "link -o {{output}} {{ldflags}} @{{output}}.rsp"
             rspfile = "{{output}}.rsp"
@@ skipping 1386 matching lines @@
     cflags = [ ... ]
   }
   config("default_optimization") {
     if (optimize_everything) {
       configs = [ ":super_optimization" ]
     } else {
       configs = [ ":no_optimization" ]
     }
   }
 ```
-### <a name="console"></a>**console**: Run this action in the console pool.
+### <a name="console"></a>**console**: Use console pool for the pool object.
 
 ```
   Boolean. Defaults to false.
 
-  Actions marked "console = true" will be run in the built-in ninja "console"
+  Pool objects marked "console = true" will use the built-in ninja "console"
   pool. They will have access to real stdin and stdout, and output will not be
   buffered by ninja. This can be useful for long-running actions with progress
   logs, or actions that require user input.
 
   Only one console pool target can run at any one time in Ninja. Refer to the
   Ninja documentation on the console pool for more info.
 ```
 
 #### **Example**
 
 ```
-  action("long_action_with_progress_logs") {
+  pool("action_pool") {
     console = true
   }
 ```
 ### <a name="data"></a>**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 are runtime
   dependencies, they do not affect which targets are built or when. To declare
@@ skipping 1837 matching lines @@
     *   [--root: Explicitly specify source root.](#--root)
     *   [--runtime-deps-list-file: Save runtime dependencies for targets in file.](#--runtime-deps-list-file)
     *   [--script-executable: Set the executable used to execute scripts.](#--script-executable)
     *   [--threads: Specify number of worker threads.](#--threads)
     *   [--time: Outputs a summary of how long everything took.](#--time)
     *   [--tracelog: Writes a Chrome-compatible trace log to the given file.](#--tracelog)
     *   [-v: Verbose logging.](#-v)
     *   [--version: Prints the GN version number and exits.](#--version)
 ```