Rename GN source_prereqs to inputs, enhance "desc"

tools/gn/functions_target.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/functions.h"
 
 #include "tools/gn/config_values_generator.h"
 #include "tools/gn/err.h"
 #include "tools/gn/parse_tree.h"
 #include "tools/gn/scope.h"
 #include "tools/gn/target_generator.h"
 #include "tools/gn/value.h"
 #include "tools/gn/variables.h"
 
 #define DEPENDENT_CONFIG_VARS \
     "  Dependent configs: all_dependent_configs, direct_dependent_configs\n"
 #define DEPS_VARS \
     "  Deps: data, datadeps, deps, forward_dependent_configs_from, hard_dep\n"
 #define GENERAL_TARGET_VARS \
-    "  General: configs, source_prereqs, sources\n"
+    "  General: configs, inputs, sources\n"
 
 namespace functions {
 
 namespace {
 
 Value ExecuteGenericTarget(const char* target_type,
                            Scope* scope,
                            const FunctionCallNode* function,
                            const std::vector<Value>& args,
                            BlockNode* block,
@@ skipping 22 matching lines @@
 }  // namespace
 
 // action ----------------------------------------------------------------------
 
 // Common help paragraph on script runtime execution directories.
 #define SCRIPT_EXECUTION_CONTEXT \
     "  The script will be executed with the given arguments with the current\n"\
     "  directory being that of the root build directory. If you pass files\n"\
     "  to your script, see \"gn help rebase_path\" for how to convert\n" \
     "  file names to be relative to the build directory (file names in the\n" \
-    "  sources, outputs, and source_prereqs will be all treated as relative\n" \
-    "  to the current build file and converted as needed automatically).\n"
+    "  sources, outputs, and inputs will be all treated as relative to the\n" \
+    "  current build file and converted as needed automatically).\n"
 
 // Common help paragraph on script output directories.
 #define SCRIPT_EXECUTION_OUTPUTS \
     "  All output files must be inside the output directory of the build.\n" \
     "  You would generally use |$target_out_dir| or |$target_gen_dir| to\n" \
     "  reference the output or generated intermediate file directories,\n" \
     "  respectively.\n"
 
 #define ACTION_DEPS \
     "  The \"deps\" for an action will always be completed before any part\n" \
     "  of the action is run so it can depend on the output of previous\n" \
     "  steps. The \"datadeps\" will be built if the action is built, but\n" \
     "  may not have completed before all steps of the action are started.\n" \
     "  This can give additional parallelism in the build for runtime-only\n" \
     "  dependencies.\n"
 
 const char kAction[] = "action";
 const char kAction_HelpShort[] =
     "action: Declare a target that runs a script a single time.";
 const char kAction_Help[] =
     "action: Declare a target that runs a script a single time.\n"
     "\n"
     "  This target type allows you to run a script a single time to produce\n"
     "  or more output files. If you want to run a script once for each of a\n"
     "  set of input files, see \"gn help action_foreach\".\n"
     "\n"
     "Inputs\n"
     "\n"
-    "  In an action the \"sources\" and \"source_prereqs\" are treated the\n"
-    "  same: they're both input dependencies on script execution with no\n"
-    "  special handling. If you want to pass the sources to your script, you\n"
-    "  must do so explicitly by including them in the \"args\". Note also\n"
-    "  that this means there is no special handling of paths since GN\n"
-    "  doesn't know which of the args are paths and not. You will want to use\n"
+    "  In an action the \"sources\" and \"inputs\" are treated the same:\n"
+    "  they're both input dependencies on script execution with no special\n"
+    "  handling. If you want to pass the sources to your script, you must do\n"
+    "  so explicitly by including them in the \"args\". Note also that this\n"
+    "  means there is no special handling of paths since GN doesn't know\n"
+    "  which of the args are paths and not. You will want to use\n"
     "  rebase_path() to convert paths to be relative to the root_build_dir.\n"
     "\n"
+    "  You can dynamically write input dependencies (for incremental rebuilds\n"
+    "  if an input file changes) by writing a depfile when the script is run\n"
+    "  (see \"gn help depfile\"). This is more flexible than \"inputs\".\n"
+    "\n"
     "  It is recommended you put inputs to your script in the \"sources\"\n"
     "  variable, and stuff like other Python files required to run your\n"
-    "  script in the \"source_prereqs\" variable.\n"
+    "  script in the \"inputs\" variable.\n"
     "\n"
     ACTION_DEPS
     "\n"
     "Outputs\n"
     "\n"
     "  You should specify files created by your script by specifying them in\n"
     "  the \"outputs\".\n"
     "\n"
     SCRIPT_EXECUTION_CONTEXT
     "\n"
     "File name handling\n"
     "\n"
     SCRIPT_EXECUTION_OUTPUTS
     "\n"
     "Variables\n"
     "\n"
     "  args, data, datadeps, depfile, deps, outputs*, script*,\n"
-    "  source_prereqs, sources\n"
+    "  inputs, sources\n"
     "  * = required\n"
     "\n"
     "Example\n"
     "\n"
     "  action(\"run_this_guy_once\") {\n"
     "    script = \"doprocessing.py\"\n"
     "    sources = [ \"my_configuration.txt\" ]\n"
     "    outputs = [ \"$target_gen_dir/insightful_output.txt\" ]\n"
     "\n"
     "    # Our script imports this Python file so we want to rebuild if it\n"
     "    # changes.\n"
-    "    source_prereqs = [ \"helper_library.py\" ]\n"
+    "    inputs = [ \"helper_library.py\" ]\n"
     "\n"
     "    # Note that we have to manually pass the sources to our script if\n"
     "    # the script needs them as inputs.\n"
     "    args = [ \"--out\", rebase_path(target_gen_dir, root_build_dir) ] +\n"
     "           rebase_path(sources, root_build_dir)\n"
     "  }\n";
 
 Value RunAction(Scope* scope,
                 const FunctionCallNode* function,
                 const std::vector<Value>& args,
@@ skipping 18 matching lines @@
     "Inputs\n"
     "\n"
     "  The script will be run once per file in the \"sources\" variable. The\n"
     "  \"outputs\" variable should specify one or more files with a source\n"
     "  expansion pattern in it (see \"gn help source_expansion\"). The output\n"
     "  file(s) for each script invocation should be unique. Normally you\n"
     "  use \"{{source_name_part}}\" in each output file.\n"
     "\n"
     "  If your script takes additional data as input, such as a shared\n"
     "  configuration file or a Python module it uses, those files should be\n"
-    "  listed in the \"source_prereqs\" variable. These files are treated as\n"
+    "  listed in the \"inputs\" variable. These files are treated as\n"
     "  dependencies of each script invocation.\n"
     "\n"
+    "  You can dynamically write input dependencies (for incremental rebuilds\n"
+    "  if an input file changes) by writing a depfile when the script is run\n"
+    "  (see \"gn help depfile\"). This is more flexible than \"inputs\".\n"
+    "\n"
     ACTION_DEPS
     "\n"
     "Outputs\n"
     "\n"
     SCRIPT_EXECUTION_CONTEXT
     "\n"
     "File name handling\n"
     "\n"
     SCRIPT_EXECUTION_OUTPUTS
     "\n"
     "Variables\n"
     "\n"
     "  args, data, datadeps, depfile, deps, outputs*, script*,\n"
-    "  source_prereqs, sources*\n"
+    "  inputs, sources*\n"
     "  * = required\n"
     "\n"
     "Example\n"
     "\n"
     "  # Runs the script over each IDL file. The IDL script will generate\n"
     "  # both a .cc and a .h file for each input.\n"
     "  action_foreach(\"my_idl\") {\n"
     "    script = \"idl_processor.py\"\n"
     "    sources = [ \"foo.idl\", \"bar.idl\" ]\n"
     "\n"
     "    # Our script reads this file each time, so we need to list is as a\n"
     "    # dependency so we can rebuild if it changes.\n"
-    "    source_prereqs = [ \"my_configuration.txt\" ]\n"
+    "    inputs = [ \"my_configuration.txt\" ]\n"
     "\n"
     "    # Transformation from source file name to output file names.\n"
     "    outputs = [ \"$target_gen_dir/{{source_name_part}}.h\",\n"
     "                \"$target_gen_dir/{{source_name_part}}.cc\" ]\n"
     "\n"
     "    # Note that since \"args\" is opaque to GN, if you specify paths\n"
     "    # here, you will need to convert it to be relative to the build\n"
     "    # directory using \"rebase_path()\".\n"
     "    args = [\n"
     "      \"{{source}}\",\n"
@@ skipping 318 matching lines @@
 Value RunTest(Scope* scope,
               const FunctionCallNode* function,
               const std::vector<Value>& args,
               BlockNode* block,
               Err* err) {
   return ExecuteGenericTarget(functions::kExecutable, scope, function, args,
                               block, err);
 }
 
 }  // namespace functions