Don't propagate deps across actions in GN.

tools/gn/docs/reference.md

 # GN Reference
 
 *This page is automatically generated from* `gn help --markdown all`.
 
 ## **\--args**: Specifies build arguments overrides.
 
 ```
   See "gn help buildargs" for an overview of how build arguments work.
 
   Most operations take a build directory. The build arguments are taken
@@ skipping 419 matching lines @@
   --as=(buildfile|label|output)
       How to print targets.
 
       buildfile
           Prints the build files where the given target was declared as
           file names.
       label  (default)
           Prints the label of the target.
       output
           Prints the first output file for the target relative to the
-          current directory.
+          root build directory.
 
   --testonly=(true|false)
       Restrict outputs to targets with the testonly flag set
       accordingly. When unspecified, the target's testonly flags are
       ignored.
 
   --tree
       Print a dependency tree. By default, duplicates will be elided
       with "..." but when --all and -tree are used together, no
       eliding will be performed.
@@ skipping 123 matching lines @@
   --as=(buildfile|label|output)
       How to print targets.
 
       buildfile
           Prints the build files where the given target was declared as
           file names.
       label  (default)
           Prints the label of the target.
       output
           Prints the first output file for the target relative to the
-          current directory.
+          root build directory.
 
   --all-toolchains
       Matches all toolchains. When set, if the label pattern does not
       specify an explicit toolchain, labels from all toolchains will be
       matched. When unset, only targets in the default toolchain will
       be matched unless an explicit toolchain in the label is set.
 
   --testonly=(true|false)
       Restrict outputs to targets with the testonly flag set
       accordingly. When unspecified, the target's testonly flags are
@@ skipping 34 matching lines @@
 
 ```
 ## **gn path <out_dir> <target_one> <target_two>**
 
 ```
   Finds paths of dependencies between two targets. Each unique path
   will be printed in one group, and groups will be separate by newlines.
   The two targets can appear in either order: paths will be found going
   in either direction.
 
-  Each dependency will be annotated with its type. By default, only the
-  first path encountered will be printed, which is not necessarily the
-  shortest path.
+  By default, a single path will be printed. If there is a path with
+  only public dependencies, the shortest public path will be printed.
+  Otherwise, the shortest path using either public or private
+  dependencies will be printed. If --with-data is specified, data deps
+  will also be considered. If there are multiple shortest paths, an
+  arbitrary one will be selected.
 
 ```
 
 ### **Options**
 
 ```
   --all
-     Prints all paths found rather than just the first one.
+     Prints all paths found rather than just the first one. Public paths
+     will be printed first in order of increasing length, followed by
+     non-public paths in order of increasing length.
+
+  --public
+     Considers only public paths. Can't be used with --with-data.
+
+  --with-data
+     Additionally follows data deps. Without this flag, only public and
+     private linked deps will be followed. Can't be used with --public.
 
 ```
 
 ### **Example**
 
 ```
   gn path out/Default //base //tools/gn
 
 
 ```
@@ skipping 52 matching lines @@
   --as=(buildfile|label|output)
       How to print targets.
 
       buildfile
           Prints the build files where the given target was declared as
           file names.
       label  (default)
           Prints the label of the target.
       output
           Prints the first output file for the target relative to the
-          current directory.
+          root build directory.
 
   -q
      Quiet. If nothing matches, don't print any output. Without this
      option, if there are no matches there will be an informational
      message printed which might interfere with scripts processing the
      output.
 
   --testonly=(true|false)
       Restrict outputs to targets with the testonly flag set
       accordingly. When unspecified, the target's testonly flags are
@@ skipping 77 matching lines @@
   handling. If you want to pass the sources to your script, you must do
   so explicitly by including them in the "args". Note also that this
   means there is no special handling of paths since GN doesn't know
   which of the args are paths and not. You will want to use
   rebase_path() to convert paths to be relative to the root_build_dir.
 
   You can dynamically write input dependencies (for incremental rebuilds
   if an input file changes) by writing a depfile when the script is run
   (see "gn help depfile"). This is more flexible than "inputs".
 
+  If the command line length is very long, you can use response files
+  to pass args to your script. See "gn help response_file_contents".
+
   It is recommended you put inputs to your script in the "sources"
   variable, and stuff like other Python files required to run your
   script in the "inputs" variable.
 
   The "deps" and "public_deps" for an action will always be
   completed before any part of the action is run so it can depend on
   the output of previous steps. The "data_deps" will be built if the
   action is built, but may not have completed before all steps of the
   action are started. This can give additional parallelism in the build
   for runtime-only dependencies.
@@ skipping 21 matching lines @@
   All output files must be inside the output directory of the build.
   You would generally use |$target_out_dir| or |$target_gen_dir| to
   reference the output or generated intermediate file directories,
   respectively.
 
 ```
 
 ### **Variables**
 
 ```
-  args, console, data, data_deps, depfile, deps, outputs*, script*,
-  inputs, sources
+  args, console, data, data_deps, depfile, deps, inputs, outputs*,
+  response_file_contents, script*, sources
   * = required
 
 ```
 
 ### **Example**
 
 ```
   action("run_this_guy_once") {
     script = "doprocessing.py"
     sources = [ "my_configuration.txt" ]
@@ skipping 27 matching lines @@
   "outputs" variable should specify one or more files with a source
   expansion pattern in it (see "gn help source_expansion"). The output
   file(s) for each script invocation should be unique. Normally you
   use "{{source_name_part}}" in each output file.
 
   If your script takes additional data as input, such as a shared
   configuration file or a Python module it uses, those files should be
   listed in the "inputs" variable. These files are treated as
   dependencies of each script invocation.
 
+  If the command line length is very long, you can use response files
+  to pass args to your script. See "gn help response_file_contents".
+
   You can dynamically write input dependencies (for incremental rebuilds
   if an input file changes) by writing a depfile when the script is run
   (see "gn help depfile"). This is more flexible than "inputs".
 
   The "deps" and "public_deps" for an action will always be
   completed before any part of the action is run so it can depend on
   the output of previous steps. The "data_deps" will be built if the
   action is built, but may not have completed before all steps of the
   action are started. This can give additional parallelism in the build
   for runtime-only dependencies.
@@ skipping 18 matching lines @@
   All output files must be inside the output directory of the build.
   You would generally use |$target_out_dir| or |$target_gen_dir| to
   reference the output or generated intermediate file directories,
   respectively.
 
 ```
 
 ### **Variables**
 
 ```
-  args, console, data, data_deps, depfile, deps, outputs*, script*,
-  inputs, sources*
+  args, console, data, data_deps, depfile, deps, inputs, outputs*,
+  response_file_contents, script*, sources*
   * = required
 
 ```
 
 ### **Example**
 
 ```
   # Runs the script over each IDL file. The IDL script will generate
   # both a .cc and a .h file for each input.
   action_foreach("my_idl") {
@@ skipping 1586 matching lines @@
   All paths are relative to the root build directory, which is the
   current directory for running all tools. These expansions are
   available to all tools:
 
     {{label}}
         The label of the current target. This is typically used in the
         "description" field for link tools. The toolchain will be
         omitted from the label for targets in the default toolchain, and
         will be included for targets in other toolchains.
 
+    {{label_name}}
+        The short name of the label of the target. This is the part
+        after the colon. For "//foo/bar:baz" this will be "baz".
+        Unlike {{target_output_name}}, this is not affected by the
+        "output_prefix" in the tool or the "output_name" set
+        on the target.
+
     {{output}}
         The relative path and name of the output(s) of the current
         build step. If there is more than one output, this will expand
         to a list of all of them.
         Example: "out/base/my_file.o"
 
     {{target_gen_dir}}
     {{target_out_dir}}
         The directory of the generated file and output directories,
         respectively, for the current target. There is no trailing
         slash.
         Example: "out/base/test"
 
     {{target_output_name}}
         The short name of the current target with no path information,
         or the value of the "output_name" variable if one is specified
         in the target. This will include the "output_prefix" if any.
+        See also {{label_name}}.
         Example: "libfoo" for the target named "foo" and an
         output prefix for the linker tool of "lib".
 
   Compiler tools have the notion of a single input and a single output,
   along with a set of compiler-specific flags. The following expansions
   are available:
 
     {{asmflags}}
     {{cflags}}
     {{cflags_c}}
@@ skipping 278 matching lines @@
 ```
   write_file(filename, data)
 
   If data is a list, the list will be written one-item-per-line with no
   quoting or brackets.
 
   If the file exists and the contents are identical to that being
   written, the file will not be updated. This will prevent unnecessary
   rebuilds of targets that depend on this file.
 
+  One use for write_file is to write a list of inputs to an script
+  that might be too long for the command line. However, it is
+  preferrable to use response files for this purpose. See
+  "gn help response_file_contents".
+
   TODO(brettw) we probably need an optional third argument to control
   list formatting.
 
 ```
 
-### **Arguments**:
+### **Arguments**
 
 ```
   filename
       Filename to write. This must be within the output directory.
 
   data:
       The list or string to write.
 
 
 ```
@@ skipping 895 matching lines @@
     args = [ "{{source}}", "-o", depfile ]
   }
 
 
 ```
 ## **deps**: Private linked dependencies.
 
 ```
   A list of target labels.
 
-  Specifies private dependencies of a target. Shared and dynamic
-  libraries will be linked into the current target.
+  Specifies private dependencies of a target. Private dependencies are
+  propagated up the dependency tree and linked to dependant targets, but
+  do not grant the ability to include headers from the dependency.
+  Public configs are not forwarded.
 
-  These dependencies are private in that it does not grant dependent
-  targets the ability to include headers from the dependency, and direct
-  dependent configs are not forwarded.
+```
 
-  See also "public_deps" and "data_deps".
+### **Details of dependency propagation**
+
+```
+  Source sets, shared libraries, and non-complete static libraries
+  will be propagated up the dependency tree across groups, non-complete
+  static libraries and source sets.
+
+  Executables, shared libraries, and complete static libraries will
+  link all propagated targets and stop propagation. Actions and copy
+  steps also stop propagation, allowing them to take a library as an
+  input but not force dependants to link to it.
+
+  Propagation of all_dependent_configs and public_configs happens
+  independently of target type. all_dependent_configs are always
+  propagated across all types of targets, and public_configs
+  are always propagated across public deps of all types of targets.
+
+  Data dependencies are propagated differently. See
+  "gn help data_deps" and "gn help runtime_deps".
+
+  See also "public_deps".
 
 
 ```
 ## **include_dirs**: Additional include directories.
 
 ```
   A list of source directories.
 
   The directories in this list will be added to the include path for
   the files in the affected target.
@@ skipping 194 matching lines @@
   the library include path. Unlike a normal list of files, they will be
   passed to the linker unmodified rather than being treated as file
   names relative to the current build file. Generally you would set
   the "lib_dirs" so your library is found. If you need to specify
   a path, you can use "rebase_path" to convert a path to be relative
   to the build directory.
 
   When constructing the linker command, the "lib_prefix" attribute of
   the linker tool in the current toolchain will be prepended to each
   library. So your BUILD file should not specify the switch prefix
-  (like "-l"). On Mac, libraries ending in ".framework" will be
-  special-cased: the switch "-framework" will be prepended instead of
-  the lib_prefix, and the ".framework" suffix will be trimmed.
+  (like "-l").
+
+  Libraries ending in ".framework" will be special-cased: the switch
+  "-framework" will be prepended instead of the lib_prefix, and the
+  ".framework" suffix will be trimmed. This is to support the way Mac
+  links framework dependencies.
 
   libs and lib_dirs work differently than other flags in two respects.
   First, then are inherited across static library boundaries until a
   shared library or executable target is reached. Second, they are
   uniquified so each one is only passed once (the first instance of it
   will be the one used).
 
 ```
 
 ### **Ordering of flags and values**
@@ skipping 264 matching lines @@
      more than once, only the first occurance will be used.
   6. public_configs pulled from dependencies, in the order of the
      "deps" list. If a dependency is public, they will be applied
      recursively.
 
 
 ```
 ## **public_deps**: Declare public dependencies.
 
 ```
-  Public dependencies are like private dependencies ("deps") but
-  additionally express that the current target exposes the listed deps
-  as part of its public API.
+  Public dependencies are like private dependencies (see
+  "gn help deps") but additionally express that the current target
+  exposes the listed deps as part of its public API.
 
   This has several ramifications:
 
     - public_configs that are part of the dependency are forwarded
       to direct dependents.
 
     - Public headers in the dependency are usable by dependents
       (includes do not require a direct dependency or visibility).
 
     - If the current target is a shared library, other shared libraries
@@ skipping 30 matching lines @@
     deps = [ ":b" ]
   }
 
   shared_library("b") {
     deps = [ ":super_secret_implementation_details" ]
     public_deps = [ ":c" ]
   }
 
 
 ```
+## **response_file_contents**: Contents of a response file for actions.
+
+```
+  Sometimes the arguments passed to a script can be too long for the
+  system's command-line capabilities. This is especially the case on
+  Windows where the maximum command-line length is less than 8K. A
+  response file allows you to pass an unlimited amount of data to a
+  script in a temporary file for an action or action_foreach target.
+
+  If the response_file_contents variable is defined and non-empty, the
+  list will be treated as script args (including possibly substitution
+  patterns) that will be written to a temporary file at build time.
+  The name of the temporary file will be substituted for
+  "{{response_file_name}}" in the script args.
+
+  The response file contents will always be quoted and escaped
+  according to Unix shell rules. To parse the response file, the Python
+  script should use "shlex.split(file_contents)".
+
+```
+
+### **Example**
+
+```
+  action("process_lots_of_files") {
+    script = "process.py",
+    inputs = [ ... huge list of files ... ]
+
+    # Write all the inputs to a response file for the script. Also,
+    # make the paths relative to the script working directory.
+    response_file_contents = rebase_path(inputs, root_build_dir)
+
+    # The script expects the name of the response file in --file-list.
+    args = [
+      "--enable-foo",
+      "--file-list={{response_file_name}}",
+    ]
+  }
+
+
+```
 ## **script**: Script file for actions.
 
 ```
   An absolute or buildfile-relative file name of a Python script to run
   for a action and action_foreach targets (see "gn help action" and
   "gn help action_foreach").
 
 
 ```
 ## **sources**: Source files for a target
@@ skipping 717 matching lines @@
 **  -q**: Quiet mode. Don't print output on success.
 **  \--root**: Explicitly specify source root.
 **  \--runtime-deps-list-file**: Save runtime dependencies for targets in file.
 **  \--threads**: Specify number of worker threads.
 **  \--time**: Outputs a summary of how long everything took.
 **  \--tracelog**: Writes a Chrome-compatible trace log to the given file.
 **  -v**: Verbose logging.
 **  \--version**: Prints the GN version number and exits.
 
 ```