Support explicit pools in actions

tools/gn/variables.cc

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "tools/gn/variables.h"
 
 namespace variables {
 
 // Built-in variables ----------------------------------------------------------
 
@@ skipping 911 matching lines @@
     if (optimize_everything) {
       configs = [ ":super_optimization" ]
     } else {
       configs = [ ":no_optimization" ]
     }
   }
 )";
 
 const char kConsole[] = "console";
 const char kConsole_HelpShort[] =
-    "console: [boolean] Run this action in the console pool.";
+    "console: [boolean] Use console pool for the pool object.";
 const char kConsole_Help[] =
-    R"(console: Run this action in the console pool.
+    R"(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
   }
 )";
 
 const char kData[] = "data";
 const char kData_HelpShort[] =
     "data: [file list] Runtime data file dependencies.";
 const char kData_Help[] =
     R"(data: Runtime data file dependencies.
 
@@ skipping 475 matching lines @@
     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".
 )";
 
+const char kPool[] = "pool";

[brettw, 2017/06/13 21:59:16]

Did you have any thouhgs on how to fix the "gn help" issue for this?

[Petr Hosek, 2017/06/17 02:44:25]

I tried to modify help command to handle the case where the same topic is
defined for functions and variables and it doesn't look too terrible, what do
you think?

+const char kPool_HelpShort[] =
+    "pool: [string] Label of the pool used by the action.";
+const char kPool_Help[] =
+    R"(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"
+    ...
+  }
+)";
+
 const char kPrecompiledHeader[] = "precompiled_header";
 const char kPrecompiledHeader_HelpShort[] =
     "precompiled_header: [string] Header file to precompile.";
 const char kPrecompiledHeader_Help[] =
     R"(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
@@ skipping 480 matching lines @@
     INSERT_VARIABLE(Testonly)
     INSERT_VARIABLE(Visibility)
     INSERT_VARIABLE(WriteRuntimeDeps)
   }
   return info_map;
 }
 
 #undef INSERT_VARIABLE
 
 }  // namespace variables