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 2579 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 1294 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)
 ```