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: [label] Console 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)
     *   [output_dir: [directory] Directory to put output file in.](#output_dir)
     *   [output_extension: [string] Value to use for the output's file extension.](#output_extension)
     *   [output_name: [string] Name for the output file other than the default.](#output_name)
     *   [output_prefix_override: [boolean] Don't use prefix for output name.](#output_prefix_override)
     *   [outputs: [file list] Output files for actions and copy targets.](#outputs)
+    *   [pool: [string] Label of the pool used by the action.](#pool)
     *   [precompiled_header: [string] Header file to precompile.](#precompiled_header)
     *   [precompiled_header_type: [string] "gcc" or "msvc".](#precompiled_header_type)
     *   [precompiled_source: [file name] Source file to precompile.](#precompiled_source)
     *   [product_type: [string] Product type for Xcode projects.](#product_type)
     *   [public: [file list] Declare public header files for a target.](#public)
     *   [public_configs: [label list] Configs applied to dependents.](#public_configs)
     *   [public_deps: [label list] Declare public dependencies.](#public_deps)
     *   [response_file_contents: [string list] Contents of .rsp file for actions.](#response_file_contents)
     *   [script: [file name] Script file for actions.](#script)
     *   [sources: [file list] Source files for a target.](#sources)
@@ skipping 466 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 17 matching lines @@
 #### **Visual Studio Flags**
 
 ```
   --sln=<file_name>
       Override default sln file name ("all"). Solution file is written to the
       root build directory.
 
   --no-deps
       Don't include targets dependencies to the solution. Changes the way how
       --filters option works. Only directly matching targets are included.
+
+  --winsdk=<sdk_version>
+      Use the specified Windows 10 SDK version to generate project files.
+      As an example, "10.0.15063.0" can be specified to use Creators Update SDK
+      instead of the default one.
 ```
 
 #### **Xcode Flags**
 
 ```
   --workspace=<file_name>
       Override defaut workspace file name ("all"). The workspace file is
       written to the root build directory.
 
   --ninja-extra-args=<string>
@@ skipping 23 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 1221 matching lines @@
       The label of the toolchain. This will match the value of the
       "current_toolchain" variable when inside that target's declaration.
 ```
 
 #### **Examples**
 
 ```
   get_label_info(":foo", "name")
   # Returns string "foo".
 
-  get_label_info("//foo/bar:baz", "gen_dir")
+  get_label_info("//foo/bar:baz", "target_gen_dir")
   # Returns string "//out/Debug/gen/foo/bar".
 ```
 ### <a name="get_path_info"></a>**get_path_info**: Extract parts of a file or directory name.
 
 ```
   get_path_info(input, what)
 
   The first argument is either a string representing a file or directory name,
   or a list of such strings. If the input is a list the return value will be a
   list containing the result of applying the rule to each item in the input.
@@ skipping 733 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**: Console pool objects.
 
 ```
-  Boolean. Defaults to false.
-
-  Actions marked "console = true" will be run in 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.
+  Console pool is a special pool object that uses the built-in ninja "console"
+  pool. Target using this pool 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") {
-    console = true
+  action("my_action") {
+    ...
+    pool = console
+    ...
   }
 ```
 ### <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
   input files to a script, use "inputs".
@@ skipping 527 matching lines @@
   action_foreach
     Action_foreach targets must always use source expansions to map input files
     to output files. There can be more than one output, which means that each
     invocation of the script will produce a set of files (presumably based on
     the name of the input file). See "gn help action_foreach".
 
   action
     Action targets (excluding action_foreach) must list literal output file(s)
     with no source expansions. See "gn help action".
 ```
+### <a name="pool"></a>**pool**: Label of the pool used by the action.
+
+```
+  A fully-qualified label representing the pool that will be used for the
+  action. Pools are defined using the pool() {...} declaration.
+```
+
+#### **Example**
+
+```
+  action("action") {
+    pool = "//build:custom_pool"
+    ...
+  }
+```
 ### <a name="precompiled_header"></a>**precompiled_header**: [string] Header file to precompile.
 
 ```
   Precompiled headers will be used when a target specifies this value, or a
   config applying to this target specifies this value. In addition, the tool
   corresponding to the source files must also specify precompiled headers (see
   "gn help tool"). The tool will also specify what type of precompiled headers
   to use, by setting precompiled_header_type to either "gcc" or "msvc".
 
   The precompiled header/source variables can be specified on a target or a
@@ skipping 1289 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)
 ```