Enhance GN documentation.

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 844 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, data, data_deps, depfile, deps, outputs*, script*,
+  args, console, data, data_deps, depfile, deps, outputs*, script*,
   inputs, sources
   * = required
 
 ```
 
 ### **Example**
 
 ```
   action("run_this_guy_once") {
     script = "doprocessing.py"
@@ skipping 66 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, data, data_deps, depfile, deps, outputs*, script*,
+  args, console, data, data_deps, depfile, deps, outputs*, script*,
   inputs, 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.
@@ skipping 1895 matching lines @@
 ```
 ## **current_toolchain**: Label of the current toolchain.
 
 ```
   A fully-qualified label representing the current toolchain. You can
   use this to make toolchain-related decisions in the build. See also
   "default_toolchain".
 
 ```
 
-### **Example**:
+### **Example**
 
 ```
   if (current_toolchain == "//build:64_bit_toolchain") {
     executable("output_thats_64_bit_only") {
       ...
 
 
 ```
 ## **default_toolchain**: [string] Label of the default toolchain.
 
@@ skipping 94 matching lines @@
   This is primarily useful for setting up script calls. If you are
   passing this to a script, you will want to pass it through
   rebase_path() (see "gn help rebase_path") to convert it
   to be relative to the build directory.
 
   See also "target_out_dir" which is usually a better location for
   output files. It will be inside the root output dir.
 
 ```
 
-### **Example**:
+### **Example**
 
 ```
   action("myscript") {
     # Pass the output dir to the script.
     args = [ "-o", rebase_path(root_out_dir, root_build_dir) ]
   }
 
 
 ```
 ## **target_cpu**: The desired cpu architecture for the build.
@@ skipping 41 matching lines @@
 
   This is primarily useful for setting up include paths for generated
   files. If you are passing this to a script, you will want to pass it
   through rebase_path() (see "gn help rebase_path") to convert it
   to be relative to the build directory.
 
   See also "gn help root_gen_dir".
 
 ```
 
-### **Example**:
+### **Example**
 
 ```
   action("myscript") {
     # Pass the generated output dir to the script.
     args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]
   }
 
 
 ```
 ## **target_os**: The desired operating system for the build.
@@ skipping 52 matching lines @@
 
   This is primarily useful for setting up arguments for calling
   scripts. If you are passing this to a script, you will want to pass it
   through rebase_path() (see "gn help rebase_path") to convert it
   to be relative to the build directory.
 
   See also "gn help root_out_dir".
 
 ```
 
-### **Example**:
+### **Example**
 
 ```
   action("myscript") {
     # Pass the output dir to the script.
     args = [ "-o", rebase_path(target_out_dir, root_build_dir) ]
   }
 
 
 ```
 ## **all_dependent_configs**: Configs to be forced on dependents.
@@ skipping 423 matching lines @@
   config("default_optimization") {
     if (optimize_everything) {
       configs = [ ":super_optimization" ]
     } else {
       configs = [ ":no_optimization" ]
     }
   }
 
 
 ```
+## **console**: Run this action in the console pool.
+
+```
+  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.
+
+  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
+  }
+
+
+```
 ## **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".
 
   Appearing in the "data" section does not imply any special handling
@@ skipping 25 matching lines @@
   the current target. Such dependencies will be built and will be
   available at runtime.
 
   This is normally used for things like plugins or helper programs that
   a target needs at runtime.
 
   See also "gn help deps" and "gn help data".
 
 ```
 
-### **Example**:
+### **Example**
+
 ```
   executable("foo") {
     deps = [ "//base" ]
     data_deps = [ "//plugins:my_runtime_plugin" ]
   }
 
 
 ```
 ## **defines**: C preprocessor defines.
 
@@ skipping 17 matching lines @@
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
      the "deps" list. This is done recursively. If a config appears
      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.
 
 ```
 
-### **Example**:
+### **Example**
+
 ```
   defines = [ "AWESOME_FEATURE", "LOG_LEVEL=3" ]
 
 
 ```
 ## **depfile**: [string] File name for input dependencies for actions.
 
 ```
   If nonempty, this string specifies that the current action or
   action_foreach target will generate the given ".d" file containing
   the dependencies of the input. Empty or unset means that the script
   doesn't generate the files.
 
   The .d file should go in the target output directory. If you have more
   than one source file that the script is being run over, you can use
   the output file expansions described in "gn help action_foreach" to
   name the .d file according to the input.
   The format is that of a Makefile, and all of the paths should be
   relative to the root build directory.
 
 ```
 
-### **Example**:
+### **Example**
+
 ```
   action_foreach("myscript_target") {
     script = "myscript.py"
     sources = [ ... ]
 
     # Locate the depfile in the output directory named like the
     # inputs but with a ".d" appended.
     depfile = "$relative_target_output_dir/{{source_name}}.d"
 
     # Say our script uses "-o <d file>" to indicate the depfile.
@@ skipping 92 matching lines @@
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
      the "deps" list. This is done recursively. If a config appears
      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.
 
 ```
 
-### **Example**:
+### **Example**
+
 ```
   include_dirs = [ "src/include", "//third_party/foo" ]
 
 
 ```
 ## **inputs**: Additional compile-time dependencies.
 
 ```
   Inputs are compile-time dependencies of the current target. This means
   that all inputs must be available before compiling any of the sources
   or executing any actions.
 
   Inputs are typically only used for action and action_foreach targets.
 
 ```
 
 ### **Inputs for actions**
 
 ```
   For action and action_foreach targets, inputs should be the inputs to
   script that don't vary. These should be all .py files that the script
   uses via imports (the main script itself will be an implcit dependency
   of the action so need not be listed).
 
-  For action targets, inputs should be the entire set of inputs the
-  script needs. For action_foreach targets, inputs should be the set of
-  dependencies that don't change. These will be applied to each script
-  invocation over the sources.
+  For action targets, inputs and sources are treated the same, but from
+  a style perspective, it's recommended to follow the same rule as
+  action_foreach and put helper files in the inputs, and the data used
+  by the script (if any) in sources.
 
   Note that another way to declare input dependencies from an action
   is to have the action write a depfile (see "gn help depfile"). This
   allows the script to dynamically write input dependencies, that might
   not be known until actually executing the script. This is more
   efficient than doing processing while running GN to determine the
   inputs, and is easier to keep in-sync than hardcoding the list.
 
 ```
 
+### **Script input gotchas**
+
+```
+  It may be tempting to write a script that enumerates all files in a
+  directory as inputs. Don't do this! Even if you specify all the files
+  in the inputs or sources in the GN target (or worse, enumerate the
+  files in an exec_script call when running GN, which will be slow), the
+  dependencies will be broken.
+
+  The problem happens if a file is ever removed because the inputs are
+  not listed on the command line to the script. Because the script
+  hasn't changed and all inputs are up-to-date, the script will not
+  re-run and you will get a stale build. Instead, either list all
+  inputs on the command line to the script, or if there are many, create
+  a separate list file that the script reads. As long as this file is
+  listed in the inputs, the build will detect when it has changed in any
+  way and the action will re-run.
+
+```
+
 ### **Inputs for binary targets**
 
 ```
   Any input dependencies will be resolved before compiling any sources.
   Normally, all actions that a target depends on will be run before any
   files in a target are compiled. So if you depend on generated headers,
   you do not typically need to list them in the inputs section.
 
+  Inputs for binary targets will be treated as order-only dependencies,
+  meaning that they will be forced up-to-date before compiling or
+  any files in the target, but changes in the inputs will not
+  necessarily force the target to compile. This is because it is
+  expected that the compiler will report the precise list of input
+  dependencies required to recompile each file once the initial build
+  is done.
+
 ```
 
 ### **Example**
 
 ```
   action("myscript") {
     script = "domything.py"
     inputs = [ "input.data" ]
   }
 
@@ skipping 63 matching lines @@
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
      the "deps" list. This is done recursively. If a config appears
      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.
 
 ```
 
-### **Example**:
+### **Example**
+
 ```
   lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ]
 
 
 ```
 ## **libs**: Additional libraries to link.
 
 ```
   A list of strings.
 
@@ skipping 32 matching lines @@
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
      the "deps" list. This is done recursively. If a config appears
      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.
 
 ```
 
-### **Examples**:
+### **Examples**
+
 ```
   On Windows:
     libs = [ "ctl3d.lib" ]
   On Linux:
     libs = [ "ld" ]
 
 
 ```
 ## **output_extension**: Value to use for the output's file extension.
 
 ```
   Normally the file extension for a target is based on the target
   type and the operating system, but in rare cases you will need to
   override the name (for example to use "libfreetype.so.6" instead
   of libfreetype.so on Linux).
 
+  This value should not include a leading dot. If undefined or empty,
+  the default_output_extension specified on the tool will be used.
+  The output_extension will be used in the "{{output_extension}}"
+  expansion which the linker tool will generally use to specify the
+  output file name. See "gn help tool".
+
+```
+
+### **Example**
+
+```
+  shared_library("freetype") {
+    if (is_linux) {
+      # Call the output "libfreetype.so.6"
+      output_extension = "so.6"
+    }
+    ...
+  }
+
+  # On Windows, generate a "mysettings.cpl" control panel applet.
+  # Control panel applets are actually special shared libraries.
+  if (is_win) {
+    shared_library("mysettings") {
+      output_extension = "cpl"
+      ...
+    }
+  }
+
+
 ```
 ## **output_name**: Define a name for the output file other than the default.
 
 ```
   Normally the output name of a target will be based on the target name,
   so the target "//foo/bar:bar_unittests" will generate an output
   file such as "bar_unittests.exe" (using Windows as an example).
 
   Sometimes you will want an alternate name to avoid collisions or
   if the internal name isn't appropriate for public distribution.
 
   The output name should have no extension or prefixes, these will be
   added using the default system rules. For example, on Linux an output
-  name of "foo" will produce a shared library "libfoo.so".
+  name of "foo" will produce a shared library "libfoo.so". There
+  is no way to override the output prefix of a linker tool on a per-
+  target basis. If you need more flexibility, create a copy target
+  to produce the file you want.
 
   This variable is valid for all binary output target types.
 
 ```
 
-### **Example**:
+### **Example**
+
 ```
   static_library("doom_melon") {
     output_name = "fluffy_bunny"
   }
 
 
 ```
 ## **outputs**: Output files for actions and copy targets.
 
 ```
   Outputs is valid for "copy", "action", and "action_foreach"
-  target types and indicates the resulting files. The values may contain
-  source expansions to generate the output names from the sources (see
-  "gn help source_expansion").
+  target types and indicates the resulting files. Outputs must always
+  refer to files in the build directory.
 
-  For copy targets, the outputs is the destination for the copied
-  file(s). For actions, the outputs should be the list of files
-  generated by the script.
+  copy
+    Copy targets should have exactly one entry in the outputs list. If
+    there is exactly one source, this can be a literal file name or a
+    source expansion. If there is more than one source, this must
+    contain a source expansion to map a single input name to a single
+    output name. See "gn help copy".
+
+  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".
 
 
 ```
 ## **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
@@ skipping 81 matching lines @@
   a dependency A -> B -> C, then A can include C's public headers.
   However, the same is NOT true of visibility, so unless A is in C's
   visibility list, the include will be rejected.
 
   GN only knows about files declared in the "sources" and "public"
   sections of targets. If a file is included that is not known to the
   build, it will be allowed.
 
 ```
 
-### **Examples**:
+### **Examples**
+
 ```
   These exact files are public:
     public = [ "foo.h", "bar.h" ]
 
   No files are public (no targets may include headers from this one):
     public = []
 
 
 ```
 ## **public_configs**: Configs to be applied on dependents.
@@ skipping 96 matching lines @@
 ```
   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
 
 ```
-  A list of files relative to the current buildfile.
+  A list of files. Non-absolute paths will be resolved relative to the
+  current build file.
+
+```
+
+### **Sources for binary targets**
+
+```
+  For binary targets (source sets, executables, and libraries), the
+  known file types will be compiled with the associated tools. Unknown
+  file types and headers will be skipped. However, you should still
+  list all C/C+ header files so GN knows about the existance of those
+  files for the purposes of include checking.
+
+  As a special case, a file ending in ".def" will be treated as a
+  Windows module definition file. It will be appended to the link
+  line with a preceeding "/DEF:" string. There must be at most one
+  .def file in a target and they do not cross dependency boundaries
+  (so specifying a .def file in a static library or source set will have
+  no effect on the executable or shared library they're linked into).
+
+```
+
+### **Sources for non-binary targets**
+
+```
+  action_foreach
+    The sources are the set of files that the script will be executed
+    over. The script will run once per file.
+
+  action
+    The sources will be treated the same as inputs. See "gn help inputs"
+    for more information and usage advice.
+
+  copy
+    The source are the source files to copy.
 
 
 ```
 ## **testonly**: Declares a target must only be used for testing.
 
 ```
   Boolean. Defaults to false.
 
   When a target is marked "testonly = true", it must only be depended
   on by other test-only targets. Otherwise, GN will issue an error
@@ skipping 669 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.
 
 ```