Rename GN source_prereqs to inputs, enhance "desc"

We picked the name "source_prereqs" to try to emphasize that these are source
(compile-time) dependencies rather than data or link-time dependencies.
However, now that all actions are implicit hard deps, the use-case of using
this for binary targets is almost nonexistant (I want to eventually put back
actions-as-soft-deps but this requires some additional checking to make sure
people don't mess up, at which time this may becomre more relevant.)

source_prereqs is hard to type and difficult to understand. Inputs is much more
clear, especially since the typical case is an action.

This will fall back to reading "source_prereqs" for back-compat until we change
all users.

Significantly enhance the "gn desc" command. A bunch of action-related fields
were missing.

BUG=374271
R=jamesr@chromium.org

Review URL: https://codereview.chromium.org/333243004

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@277850 0039d316-1c4b-4281-b951-d872f2087c98

tools/gn/action_target_generator.cc

@@ -55,7 +55,7 @@ void ActionTargetGenerator::DoRun() {
     return;
   }
 
-  FillSourcePrereqs();
+  FillInputs();
   if (err_->has_error())
     return;
 

tools/gn/binary_target_generator.cc

@@ -41,7 +41,7 @@ void BinaryTargetGenerator::DoRun() {
   if (err_->has_error())
     return;
 
-  FillSourcePrereqs();
+  FillInputs();
   if (err_->has_error())
     return;
 

tools/gn/functions_target.cc

@@ -17,7 +17,7 @@
 #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 {
 
@@ -60,8 +60,8 @@ Value ExecuteGenericTarget(const char* target_type,
     "  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 \
@@ -90,17 +90,21 @@ const char kAction_Help[] =
     "\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"
@@ -118,7 +122,7 @@ const char kAction_Help[] =
     "Variables\n"
     "\n"
     "  args, data, datadeps, depfile, deps, outputs*, script*,\n"
-    "  source_prereqs, sources\n"
+    "  inputs, sources\n"
     "  * = required\n"
     "\n"
     "Example\n"
@@ -130,7 +134,7 @@ const char kAction_Help[] =
     "\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"
@@ -169,9 +173,13 @@ const char kActionForEach_Help[] =
     "\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"
@@ -185,7 +193,7 @@ const char kActionForEach_Help[] =
     "Variables\n"
     "\n"
     "  args, data, datadeps, depfile, deps, outputs*, script*,\n"
-    "  source_prereqs, sources*\n"
+    "  inputs, sources*\n"
     "  * = required\n"
     "\n"
     "Example\n"
@@ -198,7 +206,7 @@ const char kActionForEach_Help[] =
     "\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"

tools/gn/ninja_action_target_writer_unittest.cc

@@ -59,8 +59,7 @@ TEST(NinjaActionTargetWriter, WriteArgsSubstitutions) {
 }
 
 // Makes sure that we write sources as input dependencies for actions with
-// both sources and source_prereqs (ACTION_FOREACH treats the sources
-// differently).
+// both sources and inputs (ACTION_FOREACH treats the sources differently).
 TEST(NinjaActionTargetWriter, ActionWithSources) {
   TestWithScope setup;
   setup.build_settings()->SetBuildDir(SourceDir("//out/Debug/"));
@@ -70,7 +69,7 @@ TEST(NinjaActionTargetWriter, ActionWithSources) {
   target.action_values().set_script(SourceFile("//foo/script.py"));
 
   target.sources().push_back(SourceFile("//foo/source.txt"));
-  target.source_prereqs().push_back(SourceFile("//foo/included.txt"));
+  target.inputs().push_back(SourceFile("//foo/included.txt"));
 
   target.action_values().outputs().push_back(
       SourceFile("//out/Debug/foo.out"));
@@ -159,7 +158,7 @@ TEST(NinjaActionTargetWriter, ForEach) {
   target.action_values().outputs().push_back(
       SourceFile("//out/Debug/{{source_name_part}}.out"));
 
-  target.source_prereqs().push_back(SourceFile("//foo/included.txt"));
+  target.inputs().push_back(SourceFile("//foo/included.txt"));
 
   // Posix.
   {
@@ -268,7 +267,7 @@ TEST(NinjaActionTargetWriter, ForEachWithDepfile) {
   target.action_values().outputs().push_back(
       SourceFile("//out/Debug/{{source_name_part}}.out"));
 
-  target.source_prereqs().push_back(SourceFile("//foo/included.txt"));
+  target.inputs().push_back(SourceFile("//foo/included.txt"));
 
   // Posix.
   {

tools/gn/ninja_target_writer.cc

@@ -94,7 +94,7 @@ std::string NinjaTargetWriter::WriteInputDepsStampAndGetDep(
 
   if (!add_script_source_as_dep &&
       extra_hard_deps.empty() &&
-      target_->source_prereqs().empty() &&
+      target_->inputs().empty() &&
       target_->recursive_hard_deps().empty() &&
       (!list_sources_as_input_deps || target_->sources().empty()))
     return std::string();  // No input/hard deps.
@@ -124,7 +124,7 @@ std::string NinjaTargetWriter::WriteInputDepsStampAndGetDep(
   }
 
   // Input files are order-only deps.
-  const Target::FileList& prereqs = target_->source_prereqs();
+  const Target::FileList& prereqs = target_->inputs();
   for (size_t i = 0; i < prereqs.size(); i++) {
     out_ << " ";
     path_output_.WriteFile(out_, prereqs[i]);

tools/gn/ninja_target_writer_unittest.cc

@@ -41,12 +41,12 @@ TEST(NinjaTargetWriter, WriteInputDepsStampAndGetDep) {
   // included) and a source (should not be included).
   Target target(setup.settings(), Label(SourceDir("//foo/"), "target"));
   target.set_output_type(Target::EXECUTABLE);
-  target.source_prereqs().push_back(SourceFile("//foo/input.txt"));
+  target.inputs().push_back(SourceFile("//foo/input.txt"));
   target.sources().push_back(SourceFile("//foo/source.txt"));
   target.deps().push_back(LabelTargetPair(&base_target));
 
   // Dependent action to test that action sources will be treated the same as
-  // source_prereqs.
+  // inputs.
   Target action(setup.settings(), Label(SourceDir("//foo/"), "action"));
   action.set_output_type(Target::ACTION);
   action.action_values().set_script(SourceFile("//foo/script.py"));

tools/gn/target.h

@@ -80,8 +80,8 @@ class Target : public Item {
   FileList& public_headers() { return public_headers_; }
 
   // Compile-time extra dependencies.
-  const FileList& source_prereqs() const { return source_prereqs_; }
-  FileList& source_prereqs() { return source_prereqs_; }
+  const FileList& inputs() const { return inputs_; }
+  FileList& inputs() { return inputs_; }
 
   // Runtime dependencies.
   const FileList& data() const { return data_; }
@@ -171,7 +171,7 @@ class Target : public Item {
   FileList sources_;
   bool all_headers_public_;
   FileList public_headers_;
-  FileList source_prereqs_;
+  FileList inputs_;
   FileList data_;
 
   bool hard_dep_;

tools/gn/target_generator.cc

@@ -160,16 +160,23 @@ void TargetGenerator::FillPublic() {
   target_->public_headers().swap(dest_public);
 }
 
-void TargetGenerator::FillSourcePrereqs() {
-  const Value* value = scope_->GetValue(variables::kSourcePrereqs, true);
-  if (!value)
-    return;
+void TargetGenerator::FillInputs() {
+  const Value* value = scope_->GetValue(variables::kInputs, true);
+  if (!value) {
+    // Older versions used "source_prereqs". Allow use of this variable until
+    // all callers are updated.
+    // TODO(brettw) remove this eventually.
+    value = scope_->GetValue("source_prereqs", true);
+
+    if (!value)
+      return;
+  }
 
-  Target::FileList dest_reqs;
+  Target::FileList dest_inputs;
   if (!ExtractListOfRelativeFiles(scope_->settings()->build_settings(), *value,
-                                  scope_->GetSourceDir(), &dest_reqs, err_))
+                                  scope_->GetSourceDir(), &dest_inputs, err_))
     return;
-  target_->source_prereqs().swap(dest_reqs);
+  target_->inputs().swap(dest_inputs);
 }
 
 void TargetGenerator::FillConfigs() {

tools/gn/target_generator.h

@@ -50,7 +50,7 @@ class TargetGenerator {
 
   void FillSources();
   void FillPublic();
-  void FillSourcePrereqs();
+  void FillInputs();
   void FillConfigs();
   void FillOutputs();
 

tools/gn/variables.cc

@@ -370,7 +370,7 @@ const char kData_Help[] =
     "  these but it is envisioned that test data can be listed here for use\n"
     "  running automated tests.\n"
     "\n"
-    "  See also \"gn help source_prereqs\" and \"gn help datadeps\", both of\n"
+    "  See also \"gn help inputs\" and \"gn help datadeps\", both of\n"
     "  which actually affect the build in concrete ways.\n";
 
 const char kDatadeps[] = "datadeps";
@@ -536,6 +536,51 @@ const char kIncludeDirs_Help[] =
     "Example:\n"
     "  include_dirs = [ \"src/include\", \"//third_party/foo\" ]\n";
 
+const char kInputs[] = "inputs";
+const char kInputs_HelpShort[] =
+    "inputs: [file list] Additional compile-time dependencies.";
+const char kInputs_Help[] =
+    "inputs: Additional compile-time dependencies.\n"
+    "\n"
+    "  Inputs are compile-time dependencies of the current target. This means\n"
+    "  that all inputs must be available before compiling any of the sources\n"
+    "  or executing any actions.\n"
+    "\n"
+    "  Inputs are typically only used for action and action_foreach targets.\n"
+    "\n"
+    "Inputs for actions\n"
+    "\n"
+    "  For action and action_foreach targets, inputs should be the inputs to\n"
+    "  script that don't vary. These should be all .py files that the script\n"
+    "  uses via imports (the main script itself will be an implcit dependency\n"
+    "  of the action so need not be listed).\n"
+    "\n"
+    "  For action targets, inputs should be the entire set of inputs the\n"
+    "  script needs. For action_foreach targets, inputs should be the set of\n"
+    "  dependencies that don't change. These will be applied to each script\n"
+    "  invocation over the sources.\n"
+    "\n"
+    "  Note that another way to declare input dependencies from an action\n"
+    "  is to have the action write a depfile (see \"gn help depfile\"). This\n"
+    "  allows the script to dynamically write input dependencies, that might\n"
+    "  not be known until actually executing the script. This is more\n"
+    "  efficient than doing processing while running GN to determine the\n"
+    "  inputs, and is easier to keep in-sync than hardcoding the list.\n"
+    "\n"
+    "Inputs for binary targets\n"
+    "\n"
+    "  Any input dependencies will be resolved before compiling any sources.\n"
+    "  Normally, all actions that a target depends on will be run before any\n"
+    "  files in a target are compiled. So if you depend on generated headers,\n"
+    "  you do not typically need to list them in the inputs section.\n"
+    "\n"
+    "Example\n"
+    "\n"
+    "  action(\"myscript\") {\n"
+    "    script = \"domything.py\"\n"
+    "    inputs = [ \"input.data\" ]\n"
+    "  }\n";
+
 const char kLdflags[] = "ldflags";
 const char kLdflags_HelpShort[] =
     "ldflags: [string list] Flags passed to the linker.";
@@ -704,51 +749,6 @@ const char kScript_Help[] =
     "  for a action and action_foreach targets (see \"gn help action\" and\n"
     "  \"gn help action_foreach\").\n";
 
-const char kSourcePrereqs[] = "source_prereqs";
-const char kSourcePrereqs_HelpShort[] =
-    "source_prereqs: [file list] Additional compile-time dependencies.";
-const char kSourcePrereqs_Help[] =
-    "source_prereqs: Additional compile-time dependencies.\n"
-    "\n"
-    "  Inputs are compile-time dependencies of the current target. This means\n"
-    "  that all source prerequisites must be available before compiling any\n"
-    "  of the sources.\n"
-    "\n"
-    "  If one of your sources #includes a generated file, that file must be\n"
-    "  available before that source file is compiled. For subsequent builds,\n"
-    "  the \".d\" files will list the include dependencies of each source\n"
-    "  and Ninja can know about that dependency to make sure it's generated\n"
-    "  before compiling your source file. However, for the first run it's\n"
-    "  not possible for Ninja to know about this dependency.\n"
-    "\n"
-    "  Source prerequisites solves this problem by declaring such\n"
-    "  dependencies. It will introduce a Ninja \"implicit\" dependency for\n"
-    "  each source file in the target on the listed files.\n"
-    "\n"
-    "  For binary targets, the files in the \"source_prereqs\" should all be\n"
-    "  listed in the \"outputs\" section of another target. There is no\n"
-    "  reason to declare static source files as source prerequisites since\n"
-    "  the normal include file dependency management will handle them more\n"
-    "  efficiently anyway.\n"
-    "\n"
-    "  For action targets that don't generate \".d\" files, the\n"
-    "  \"source_prereqs\" section is how you can list known compile-time\n"
-    "  dependencies your script may have.\n"
-    "\n"
-    "  See also \"gn help data\" and \"gn help datadeps\" (which declare\n"
-    "  run-time rather than compile-time dependencies).\n"
-    "\n"
-    "Examples:\n"
-    "  executable(\"foo\") {\n"
-    "    sources = [ \"foo.cc\" ]\n"
-    "    source_prereqs = [ \"$root_gen_dir/something/generated_data.h\" ]\n"
-    "  }\n"
-    "\n"
-    "  action(\"myscript\") {\n"
-    "    script = \"domything.py\"\n"
-    "    source_prereqs = [ \"input.data\" ]\n"
-    "  }\n";
-
 const char kSources[] = "sources";
 const char kSources_HelpShort[] =
     "sources: [file list] Source files for a target.";
@@ -877,6 +877,7 @@ const VariableInfoMap& GetTargetVariables() {
     INSERT_VARIABLE(DirectDependentConfigs)
     INSERT_VARIABLE(ForwardDependentConfigsFrom)
     INSERT_VARIABLE(IncludeDirs)
+    INSERT_VARIABLE(Inputs)
     INSERT_VARIABLE(Ldflags)
     INSERT_VARIABLE(Libs)
     INSERT_VARIABLE(LibDirs)
@@ -885,7 +886,6 @@ const VariableInfoMap& GetTargetVariables() {
     INSERT_VARIABLE(Outputs)
     INSERT_VARIABLE(Public)
     INSERT_VARIABLE(Script)
-    INSERT_VARIABLE(SourcePrereqs)
     INSERT_VARIABLE(Sources)
     INSERT_VARIABLE(Visibility)
   }

tools/gn/variables.h

@@ -131,6 +131,10 @@ extern const char kIncludeDirs[];
 extern const char kIncludeDirs_HelpShort[];
 extern const char kIncludeDirs_Help[];
 
+extern const char kInputs[];
+extern const char kInputs_HelpShort[];
+extern const char kInputs_Help[];
+
 extern const char kLdflags[];
 extern const char kLdflags_HelpShort[];
 extern const char kLdflags_Help[];
@@ -163,10 +167,6 @@ extern const char kScript[];
 extern const char kScript_HelpShort[];
 extern const char kScript_Help[];
 
-extern const char kSourcePrereqs[];
-extern const char kSourcePrereqs_HelpShort[];
-extern const char kSourcePrereqs_Help[];
-
 extern const char kSources[];
 extern const char kSources_HelpShort[];
 extern const char kSources_Help[];