Add a --markdown flag to GN to be able to output help in markdown.

tools/gn/docs/reference.md

Index: tools/gn/docs/reference.md
diff --git a/tools/gn/docs/reference.md b/tools/gn/docs/reference.md
new file mode 100644
index 0000000000000000000000000000000000000000..311401b827955b72090cf2436f82944a6f1c4cb0
--- /dev/null
+++ b/tools/gn/docs/reference.md
@@ -0,0 +1,4296 @@
+# GN Reference
+
+[TOC]
+
+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
+  from the previous build done in that directory. If a command specifies
+  --args, it will override the previous arguments stored in the build
+  directory, and use the specified ones.
+
+  The args specified will be saved to the build directory for subsequent
+  commands. Specifying --args="" will clear all build arguments.
+
+```
+
+### **Formatting**
+
+```
+  The value of the switch is interpreted in GN syntax. For typical usage
+  of string arguments, you will need to be careful about escaping of
+  quotes.
+
+```
+
+### **Examples**
+
+```
+  gn gen out/Default --args="foo=\"bar\""
+
+  gn gen out/Default --args='foo="bar" enable=true blah=7'
+
+  gn check out/Default --args=""
+    Clears existing build args from the directory.
+
+  gn desc out/Default --args="some_list=[1, false, \"foo\"]"
+
+
+```
+## **--[no]color**: Forces colored output on or off.
+
+```
+  Normally GN will try to detect whether it is outputting to a terminal
+  and will enable or disable color accordingly. Use of these switches
+  will override the default.
+
+```
+
+### **Examples**
+
+```
+  gn gen out/Default --color
+
+  gn gen out/Default --nocolor
+
+
+```
+## **--dotfile**: override the name of the ".gn" file.
+
+```
+  Normally GN loads the ".gn"file  from the source root for some basic
+  configuration (see "gn help dotfile"). This flag allows you to
+  use a different file.
+
+  Note that this interacts with "--root" in a possibly incorrect way.
+  It would be nice to test the edge cases and document or fix.
+
+
+```
+## **--markdown**: write the output in the Markdown format.
+
+## **--[no]color**: Forces colored output on or off.
+
+```
+  Normally GN will try to detect whether it is outputting to a terminal
+  and will enable or disable color accordingly. Use of these switches
+  will override the default.
+
+```
+
+### **Examples**
+
+```
+  gn gen out/Default --color
+
+  gn gen out/Default --nocolor
+
+
+```
+## **-q**: Quiet mode. Don't print output on success.
+
+```
+  This is useful when running as a part of another script.
+
+
+```
+## **--root**: Explicitly specify source root.
+
+```
+  Normally GN will look up in the directory tree from the current
+  directory to find a ".gn" file. The source root directory specifies
+  the meaning of "//" beginning with paths, and the BUILD.gn file
+  in that directory will be the first thing loaded.
+
+  Specifying --root allows GN to do builds in a specific directory
+  regardless of the current directory.
+
+```
+
+### **Examples**
+
+```
+  gn gen //out/Default --root=/home/baracko/src
+
+  gn desc //out/Default --root="C:\Users\BObama\My Documents\foo"
+
+
+```
+## **--time**: Outputs a summary of how long everything took.
+
+```
+  Hopefully self-explanatory.
+
+```
+
+### **Examples**
+
+```
+  gn gen out/Default --time
+
+
+```
+## **--tracelog**: Writes a Chrome-compatible trace log to the given file.
+
+```
+  The trace log will show file loads, executions, scripts, and writes.
+  This allows performance analysis of the generation step.
+
+  To view the trace, open Chrome and navigate to "chrome://tracing/",
+  then press "Load" and specify the file you passed to this parameter.
+
+```
+
+### **Examples**
+
+```
+  gn gen out/Default --tracelog=mytrace.trace
+
+
+```
+## **-v**: Verbose logging.
+
+```
+  This will spew logging events to the console for debugging issues.
+  Good luck!
+
+
+```
+## **gn args <out_dir> [--list] [--short] [--args]**
+
+```
+  See also "gn help buildargs" for a more high-level overview of how
+  build arguments work.
+
+```
+
+### **Usage**
+```
+  gn args <out_dir>
+      Open the arguments for the given build directory in an editor
+      (as specified by the EDITOR environment variable). If the given
+      build directory doesn't exist, it will be created and an empty
+      args file will be opened in the editor. You would type something
+      like this into that file:
+          enable_doom_melon=false
+          os="android"
+
+      Note: you can edit the build args manually by editing the file
+      "args.gn" in the build directory and then running
+      "gn gen <out_dir>".
+
+  gn args <out_dir> --list[=<exact_arg>] [--short]
+      Lists all build arguments available in the current configuration,
+      or, if an exact_arg is specified for the list flag, just that one
+      build argument.
+
+      The output will list the declaration location, default value, and
+      comment preceeding the declaration. If --short is specified,
+      only the names and values will be printed.
+
+      If the out_dir is specified, the build configuration will be
+      taken from that build directory. The reason this is needed is that
+      the definition of some arguments is dependent on the build
+      configuration, so setting some values might add, remove, or change
+      the default values for other arguments. Specifying your exact
+      configuration allows the proper arguments to be displayed.
+
+      Instead of specifying the out_dir, you can also use the
+      command-line flag to specify the build configuration:
+        --args=<exact list of args to use>
+
+```
+
+### **Examples**
+```
+  gn args out/Debug
+    Opens an editor with the args for out/Debug.
+
+  gn args out/Debug --list --short
+    Prints all arguments with their default values for the out/Debug
+    build.
+
+  gn args out/Debug --list=target_cpu
+    Prints information about the "target_cpu" argument for the out/Debug
+    build.
+
+  gn args --list --args="os=\"android\" enable_doom_melon=true"
+    Prints all arguments with the default values for a build with the
+    given arguments set (which may affect the values of other
+    arguments).
+
+
+```
+## **gn check <out_dir> [<label_pattern>] [--force]**
+
+```
+  "gn check" is the same thing as "gn gen" with the "--check" flag
+  except that this command does not write out any build files. It's
+  intended to be an easy way to manually trigger include file checking.
+
+  The <label_pattern> can take exact labels or patterns that match more
+  than one (although not general regular expressions). If specified,
+  only those matching targets will be checked. See
+  "gn help label_pattern" for details.
+
+  The .gn file may specify a list of targets to be checked. Only these
+  targets will be checked if no label_pattern is specified on the
+  command line. Otherwise, the command-line list is used instead. See
+  "gn help dotfile".
+
+```
+
+### **Command-specific switches**
+
+```
+  --force
+      Ignores specifications of "check_includes = false" and checks
+      all target's files that match the target label.
+
+```
+
+### **Examples**
+
+```
+  gn check out/Debug
+      Check everything.
+
+  gn check out/Default //foo:bar
+      Check only the files in the //foo:bar target.
+
+  gn check out/Default "//foo/*
+      Check only the files in targets in the //foo directory tree.
+
+
+```
+## **gn clean <out_dir>**
+
+```
+  Deletes the contents of the output directory except for args.gn and
+  creates a Ninja build environment sufficient to regenerate the build.
+
+
+```
+## **gn desc <out_dir> <target label> [<what to show>] [--blame]**
+
+```
+  Displays information about a given labeled target for the given build.
+  The build parameters will be taken for the build in the given
+  <out_dir>.
+
+```
+
+### **Possibilities for <what to show>**
+```
+  (If unspecified an overall summary will be displayed.)
+
+  sources
+      Source files.
+
+  inputs
+      Additional input dependencies.
+
+  public
+      Public header files.
+
+  check_includes
+      Whether "gn check" checks this target for include usage.
+
+  allow_circular_includes_from
+      Permit includes from these targets.
+
+  visibility
+      Prints which targets can depend on this one.
+
+  testonly
+      Whether this target may only be used in tests.
+
+  configs
+      Shows configs applied to the given target, sorted in the order
+      they're specified. This includes both configs specified in the
+      "configs" variable, as well as configs pushed onto this target
+      via dependencies specifying "all" or "direct" dependent
+      configs.
+
+  deps
+      Show immediate or recursive dependencies. See below for flags that
+      control deps printing.
+
+  public_configs
+  all_dependent_configs
+      Shows the labels of configs applied to targets that depend on this
+      one (either directly or all of them).
+
+  forward_dependent_configs_from
+      Shows the labels of dependencies for which dependent configs will
+      be pushed to targets depending on the current one.
+
+  script
+  args
+  depfile
+      Actions only. The script and related values.
+
+  outputs
+      Outputs for script and copy target types.
+
+  defines       [--blame]
+  include_dirs  [--blame]
+  cflags        [--blame]
+  cflags_cc     [--blame]
+  cflags_cxx    [--blame]
+  ldflags       [--blame]
+  lib_dirs
+  libs
+      Shows the given values taken from the target and all configs
+      applying. See "--blame" below.
+
+  --blame
+      Used with any value specified by a config, this will name
+      the config that specified the value. This doesn't currently work
+      for libs and lib_dirs because those are inherited and are more
+      complicated to figure out the blame (patches welcome).
+
+```
+
+### **Flags that control how deps are printed**
+
+```
+  --all
+      Collects all recursive dependencies and prints a sorted flat list.
+      Also usable with --tree (see below).
+
+  --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.
+
+  --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.
+
+      The "deps", "public_deps", and "data_deps" will all be
+      included in the tree.
+
+      Tree output can not be used with the filtering or output flags:
+      --as, --type, --testonly.
+
+  --type=(action|copy|executable|group|shared_library|source_set|
+          static_library)
+      Restrict outputs to targets matching the given type. If
+      unspecified, no filtering will be performed.
+
+```
+
+### **Note**
+
+```
+  This command will show the full name of directories and source files,
+  but when directories and source paths are written to the build file,
+  they will be adjusted to be relative to the build directory. So the
+  values for paths displayed by this command won't match (but should
+  mean the same thing).
+
+```
+
+### **Examples**
+
+```
+  gn desc out/Debug //base:base
+      Summarizes the given target.
+
+  gn desc out/Foo :base_unittests deps --tree
+      Shows a dependency tree of the "base_unittests" project in
+      the current directory.
+
+  gn desc out/Debug //base defines --blame
+      Shows defines set for the //base:base target, annotated by where
+      each one was set from.
+
+
+```
+## **gn format [--dump-tree] [--in-place] [--stdin] BUILD.gn**
+
+```
+  Formats .gn file to a standard format.
+
+```
+
+### **Arguments**
+```
+  --dry-run
+      Does not change or output anything, but sets the process exit code
+      based on whether output would be different than what's on disk.
+      This is useful for presubmit/lint-type checks.
+      - Exit code 0: successful format, matches on disk.
+      - Exit code 1: general failure (parse error, etc.)
+      - Exit code 2: successful format, but differs from on disk.
+
+  --dump-tree
+      For debugging only, dumps the parse tree.
+
+  --in-place
+      Instead of writing the formatted file to stdout, replace the input
+      file with the formatted output. If no reformatting is required,
+      the input file will not be touched, and nothing printed.
+
+  --stdin
+      Read input from stdin (and write to stdout). Not compatible with
+      --in-place of course.
+
+```
+
+### **Examples**
+```
+  gn format //some/BUILD.gn
+  gn format some\BUILD.gn
+  gn format /abspath/some/BUILD.gn
+  gn format --stdin
+
+
+```
+## **gn gen**: Generate ninja files.
+
+```
+  gn gen <out_dir>
+
+  Generates ninja files from the current tree and puts them in the given
+  output directory.
+
+  The output directory can be a source-repo-absolute path name such as:
+      //out/foo
+  Or it can be a directory relative to the current directory such as:
+      out/foo
+
+  See "gn help" for the common command-line switches.
+
+
+```
+## **gn help <anything>**
+```
+  Yo dawg, I heard you like help on your help so I put help on the help
+  in the help.
+
+
+```
+## **gn ls <out_dir> [<label_pattern>] [--all-toolchains] [--as=...]**
+```
+      [--type=...] [--testonly=...]
+
+  Lists all targets matching the given pattern for the given build
+  directory. By default, only targets in the default toolchain will
+  be matched unless a toolchain is explicitly supplied.
+
+  If the label pattern is unspecified, list all targets. The label
+  pattern is not a general regular expression (see
+  "gn help label_pattern"). If you need more complex expressions,
+  pipe the result through grep.
+
+```
+
+### **Options**
+
+```
+  --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.
+
+  --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
+      ignored.
+
+  --type=(action|copy|executable|group|shared_library|source_set|
+          static_library)
+      Restrict outputs to targets matching the given type. If
+      unspecified, no filtering will be performed.
+
+```
+
+### **Examples**
+
+```
+  gn ls out/Debug
+      Lists all targets in the default toolchain.
+
+  gn ls out/Debug "//base/*"
+      Lists all targets in the directory base and all subdirectories.
+
+  gn ls out/Debug "//base:*"
+      Lists all targets defined in //base/BUILD.gn.
+
+  gn ls out/Debug //base --as=output
+      Lists the build output file for //base:base
+
+  gn ls out/Debug --type=executable
+      Lists all executables produced by the build.
+
+  gn ls out/Debug "//base/*" --as=output | xargs ninja -C out/Debug
+      Builds all targets in //base and all subdirectories.
+
+  gn ls out/Debug //base --all-toolchains
+      Lists all variants of the target //base:base (it may be referenced
+      in multiple toolchains).
+
+
+```
+## **gn refs <out_dir> (<label_pattern>|<label>|<file>)* [--all]**
+```
+        [--all-toolchains] [--as=...] [--testonly=...] [--type=...]
+
+  Finds reverse dependencies (which targets reference something). The
+  input is a list containing:
+
+   - Target label: The result will be which targets depend on it.
+
+   - Config label: The result will be which targets list the given
+     config in its "configs" or "public_configs" list.
+
+   - Label pattern: The result will be which targets depend on any
+     target matching the given pattern. Patterns will not match
+     configs. These are not general regular expressions, see
+     "gn help label_pattern" for details.
+
+   - File name: The result will be which targets list the given file in
+     its "inputs", "sources", "public", or "data". Any input
+     that does not contain wildcards and does not match a target or a
+     config will be treated as a file.
+
+```
+
+### **Options**
+
+```
+  --all
+      When used without --tree, will recurse and display all unique
+      dependencies of the given targets. For example, if the input is
+      a target, this will output all targets that depend directly or
+      indirectly on the input. If the input is a file, this will output
+      all targets that depend directly or indirectly on that file.
+
+      When used with --tree, turns off eliding to show a complete tree.
+
+  --all-toolchains
+      Normally only inputs in the default toolchain will be included.
+      This switch will turn on matching all toolchains.
+
+      For example, a file is in a target might be compiled twice:
+      once in the default toolchain and once in a secondary one. Without
+      this flag, only the default toolchain one will be matched and
+      printed (potentially with its recursive dependencies, depending on
+      the other options). With this flag, both will be printed
+      (potentially with both of their recursive dependencies).
+
+  --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.
+
+  -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
+      ignored.
+
+  --tree
+      Outputs a reverse dependency tree from the given target.
+      Duplicates will be elided. Combine with --all to see a full
+      dependency tree.
+
+      Tree output can not be used with the filtering or output flags:
+      --as, --type, --testonly.
+
+  --type=(action|copy|executable|group|shared_library|source_set|
+          static_library)
+      Restrict outputs to targets matching the given type. If
+      unspecified, no filtering will be performed.
+
+```
+
+### **Examples (target input)**
+
+```
+  gn refs out/Debug //tools/gn:gn
+      Find all targets depending on the given exact target name.
+
+  gn refs out/Debug //base:i18n --as=buildfiles | xargs gvim
+      Edit all .gn files containing references to //base:i18n
+
+  gn refs out/Debug //base --all
+      List all targets depending directly or indirectly on //base:base.
+
+  gn refs out/Debug "//base/*"
+      List all targets depending directly on any target in //base or
+      its subdirectories.
+
+  gn refs out/Debug "//base:*"
+      List all targets depending directly on any target in
+      //base/BUILD.gn.
+
+  gn refs out/Debug //base --tree
+      Print a reverse dependency tree of //base:base
+
+```
+
+### **Examples (file input)**
+
+```
+  gn refs out/Debug //base/macros.h
+      Print target(s) listing //base/macros.h as a source.
+
+  gn refs out/Debug //base/macros.h --tree
+      Display a reverse dependency tree to get to the given file. This
+      will show how dependencies will reference that file.
+
+  gn refs out/Debug //base/macros.h //base/basictypes.h --all
+      Display all unique targets with some dependency path to a target
+      containing either of the given files as a source.
+
+  gn refs out/Debug //base/macros.h --testonly=true --type=executable
+          --all --as=output
+      Display the executable file names of all test executables
+      potentially affected by a change to the given file.
+
+
+```
+## **action**: Declare a target that runs a script a single time.
+
+```
+  This target type allows you to run a script a single time to produce
+  or more output files. If you want to run a script once for each of a
+  set of input files, see "gn help action_foreach".
+
+```
+
+### **Inputs**
+
+```
+  In an action the "sources" and "inputs" are treated the same:
+  they're both input dependencies on script execution with no special
+  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".
+
+  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.
+
+```
+
+### **Outputs**
+
+```
+  You should specify files created by your script by specifying them in
+  the "outputs".
+
+  The script will be executed with the given arguments with the current
+  directory being that of the root build directory. If you pass files
+  to your script, see "gn help rebase_path" for how to convert
+  file names to be relative to the build directory (file names in the
+  sources, outputs, and inputs will be all treated as relative to the
+  current build file and converted as needed automatically).
+
+```
+
+### **File name handling**
+
+```
+  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*,
+  inputs, sources
+  * = required
+
+```
+
+### **Example**
+
+```
+  action("run_this_guy_once") {
+    script = "doprocessing.py"
+    sources = [ "my_configuration.txt" ]
+    outputs = [ "$target_gen_dir/insightful_output.txt" ]
+
+*    # Our script imports this Python file so we want to rebuild if it
+**    # changes.
+*    inputs = [ "helper_library.py" ]
+
+*    # Note that we have to manually pass the sources to our script if
+**    # the script needs them as inputs.
+*    args = [ "--out", rebase_path(target_gen_dir, root_build_dir) ] +
+           rebase_path(sources, root_build_dir)
+  }
+
+
+```
+## **action_foreach**: Declare a target that runs a script over a set of files.
+
+```
+  This target type allows you to run a script once-per-file over a set
+  of sources. If you want to run a script once that takes many files as
+  input, see "gn help action".
+
+```
+
+### **Inputs**
+
+```
+  The script will be run once per file in the "sources" variable. The
+  "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.
+
+  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.
+
+```
+
+### **Outputs**
+
+```
+  The script will be executed with the given arguments with the current
+  directory being that of the root build directory. If you pass files
+  to your script, see "gn help rebase_path" for how to convert
+  file names to be relative to the build directory (file names in the
+  sources, outputs, and inputs will be all treated as relative to the
+  current build file and converted as needed automatically).
+
+```
+
+### **File name handling**
+
+```
+  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*,
+  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.

[brettw, 2015/04/17 00:01:53]

These are a bug. I think you will need to handle the case where the outputted
string ends in a newline.

[Dirk Pranke, 2015/04/17 00:08:15]

Good catch. Will look.

+*  action_foreach("my_idl") {
+    script = "idl_processor.py"
+    sources = [ "foo.idl", "bar.idl" ]
+
+*    # Our script reads this file each time, so we need to list is as a
+**    # dependency so we can rebuild if it changes.
+*    inputs = [ "my_configuration.txt" ]
+
+*    # Transformation from source file name to output file names.
+*    outputs = [ "$target_gen_dir/{{source_name_part}}.h",
+                "$target_gen_dir/{{source_name_part}}.cc" ]
+
+*    # Note that since "args" is opaque to GN, if you specify paths
+**    # here, you will need to convert it to be relative to the build
+**    # directory using "rebase_path()".
+*    args = [
+      "{{source}}",
+      "-o",
+      rebase_path(relative_target_gen_dir, root_build_dir) +
+        "/{{source_name_part}}.h" ]
+  }
+
+
+
+```
+## **assert**: Assert an expression is true at generation time.
+
+```
+  assert(<condition> [, <error string>])
+
+  If the condition is false, the build will fail with an error. If the
+  optional second argument is provided, that string will be printed
+  with the error message.
+
+```
+
+### **Examples**:
+```
+  assert(is_win)
+  assert(defined(sources), "Sources must be defined")
+
+
+```
+## **config**: Defines a configuration object.
+
+```
+  Configuration objects can be applied to targets and specify sets of
+  compiler flags, includes, defines, etc. They provide a way to
+  conveniently group sets of this configuration information.
+
+  A config is referenced by its label just like a target.
+
+  The values in a config are additive only. If you want to remove a flag
+  you need to remove the corresponding config that sets it. The final
+  set of flags, defines, etc. for a target is generated in this order:
+
+   1. The values specified directly on the target (rather than using a
+      config.
+   2. The configs specified in the target's "configs" list, in order.
+   3. Public_configs from a breadth-first traversal of the dependency
+      tree in the order that the targets appear in "deps".
+   4. All dependent configs from a breadth-first traversal of the
+      dependency tree in the order that the targets appear in "deps".
+
+```
+
+### **Variables valid in a config definition**:
+```
+  Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
+         defines, include_dirs, ldflags, lib_dirs, libs
+
+```
+
+### **Variables on a target used to apply configs**:
+```
+  all_dependent_configs, configs, public_configs,
+  forward_dependent_configs_from
+
+```
+
+### **Example**:
+```
+  config("myconfig") {
+    includes = [ "include/common" ]
+    defines = [ "ENABLE_DOOM_MELON" ]
+  }
+
+  executable("mything") {
+    configs = [ ":myconfig" ]
+  }
+
+
+```
+## **copy**: Declare a target that copies files.
+
+### **File name handling**
+
+```
+  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.
+
+  Both "sources" and "outputs" must be specified. Sources can
+  as many files as you want, but there can only be one item in the
+  outputs list (plural is used for the name for consistency with
+  other target types).
+
+  If there is more than one source file, your output name should specify
+  a mapping from each source files to output file names using source
+  expansion (see "gn help source_expansion"). The placeholders will
+  will look like "{{source_name_part}}", for example.
+
+```
+
+### **Examples**
+
+```
+*  # Write a rule that copies a checked-in DLL to the output directory.
+*  copy("mydll") {
+    sources = [ "mydll.dll" ]
+    outputs = [ "$target_out_dir/mydll.dll" ]
+  }
+
+*  # Write a rule to copy several files to the target generated files
+**  # directory.
+*  copy("myfiles") {
+    sources = [ "data1.dat", "data2.dat", "data3.dat" ]
+
+*    # Use source expansion to generate output files with the
+**    # corresponding file names in the gen dir. This will just copy each
+**    # file.
+*    outputs = [ "$target_gen_dir/{{source_file_part}}" ]
+  }
+
+
+```
+## **declare_args**: Declare build arguments.
+
+```
+  Introduces the given arguments into the current scope. If they are
+  not specified on the command line or in a toolchain's arguments,
+  the default values given in the declare_args block will be used.
+  However, these defaults will not override command-line values.
+
+  See also "gn help buildargs" for an overview.
+
+```
+
+### **Example**:
+```
+  declare_args() {
+    enable_teleporter = true
+    enable_doom_melon = false
+  }
+
+  If you want to override the (default disabled) Doom Melon:
+    gn --args="enable_doom_melon=true enable_teleporter=false"
+  This also sets the teleporter, but it's already defaulted to on so
+  it will have no effect.
+
+
+```
+## **defined**: Returns whether an identifier is defined.
+
+```
+  Returns true if the given argument is defined. This is most useful in
+  templates to assert that the caller set things up properly.
+
+  You can pass an identifier:
+    defined(foo)
+  which will return true or false depending on whether foo is defined in
+  the current scope.
+
+  You can also check a named scope:
+    defined(foo.bar)
+  which will return true or false depending on whether bar is defined in
+  the named scope foo. It will throw an error if foo is not defined or
+  is not a scope.
+
+```
+
+### **Example**:
+
+```
+  template("mytemplate") {
+*    # To help users call this template properly...
+*    assert(defined(invoker.sources), "Sources must be defined")
+
+*    # If we want to accept an optional "values" argument, we don't
+**    # want to dereference something that may not be defined.
+*    if (defined(invoker.values)) {
+      values = invoker.values
+    } else {
+      values = "some default value"
+    }
+  }
+
+
+```
+## **exec_script**: Synchronously run a script and return the output.
+
+```
+  exec_script(filename,
+              arguments = [],
+              input_conversion = "",
+              file_dependencies = [])
+
+  Runs the given script, returning the stdout of the script. The build
+  generation will fail if the script does not exist or returns a nonzero
+  exit code.
+
+  The current directory when executing the script will be the root
+  build directory. If you are passing file names, you will want to use
+  the rebase_path() function to make file names relative to this
+  path (see "gn help rebase_path").
+
+```
+
+### **Arguments**:
+
+```
+  filename:
+      File name of python script to execute. Non-absolute names will
+      be treated as relative to the current build file.
+
+  arguments:
+      A list of strings to be passed to the script as arguments.
+      May be unspecified or the empty list which means no arguments.
+
+  input_conversion:
+      Controls how the file is read and parsed.
+      See "gn help input_conversion".
+
+      If unspecified, defaults to the empty string which causes the
+      script result to be discarded. exec script will return None.
+
+  dependencies:
+      (Optional) A list of files that this script reads or otherwise
+      depends on. These dependencies will be added to the build result
+      such that if any of them change, the build will be regenerated and
+      the script will be re-run.
+
+      The script itself will be an implicit dependency so you do not
+      need to list it.
+
+```
+
+### **Example**:
+
+```
+  all_lines = exec_script(
+      "myscript.py", [some_input], "list lines",
+      [ rebase_path("data_file.txt", root_build_dir) ])
+
+*  # This example just calls the script with no arguments and discards
+**  # the result.
+*  exec_script("//foo/bar/myscript.py")
+
+
+```
+## **executable**: Declare an executable target.
+
+### **Variables**
+
+```
+  Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
+         defines, include_dirs, ldflags, lib_dirs, libs
+  Deps: data_deps, deps, forward_dependent_configs_from, public_deps
+  Dependent configs: all_dependent_configs, public_configs
+  General: check_includes, configs, data, inputs, output_name,
+           output_extension, public, sources, testonly, visibility
+
+
+```
+## **foreach**: Iterate over a list.
+
+```
+  foreach(<loop_var>, <list>) {
+    <loop contents>
+  }
+
+  Executes the loop contents block over each item in the list,
+  assigning the loop_var to each item in sequence.
+
+  The block does not introduce a new scope, so that variable assignments
+  inside the loop will be visible once the loop terminates.
+
+  The loop variable will temporarily shadow any existing variables with
+  the same name for the duration of the loop. After the loop terminates
+  the loop variable will no longer be in scope, and the previous value
+  (if any) will be restored.
+
+```
+
+### **Example**
+
+```
+  mylist = [ "a", "b", "c" ]
+  foreach(i, mylist) {
+    print(i)
+  }
+
+  Prints:
+  a
+  b
+  c
+
+
+```
+## **get_label_info**: Get an attribute from a target's label.
+
+```
+  get_label_info(target_label, what)
+
+  Given the label of a target, returns some attribute of that target.
+  The target need not have been previously defined in the same file,
+  since none of the attributes depend on the actual target definition,
+  only the label itself.
+
+  See also "gn help get_target_outputs".
+
+```
+
+### **Possible values for the "what" parameter**
+
+```
+  "name"
+      The short name of the target. This will match the value of the
+      "target_name" variable inside that target's declaration. For the
+      label "//foo/bar:baz" this will return "baz".
+
+  "dir"
+      The directory containing the target's definition, with no slash at
+      the end. For the label "//foo/bar:baz" this will return
+      "//foo/bar".
+
+  "target_gen_dir"
+      The generated file directory for the target. This will match the
+      value of the "target_gen_dir" variable when inside that target's
+      declaration.
+
+  "root_gen_dir"
+      The root of the generated file tree for the target. This will
+      match the value of the "root_gen_dir" variable when inside that
+      target's declaration.
+
+  "target_out_dir
+      The output directory for the target. This will match the
+      value of the "target_out_dir" variable when inside that target's
+      declaration.
+
+  "root_out_dir"
+      The root of the output file tree for the target. This will
+      match the value of the "root_gen_dir" variable when inside that
+      target's declaration.
+
+  "label_no_toolchain"
+      The fully qualified version of this label, not including the
+      toolchain. For the input ":bar" it might return
+      "//foo:bar".
+
+  "label_with_toolchain"
+      The fully qualified version of this label, including the
+      toolchain. For the input ":bar" it might return
+      "//foo:bar(//toolchain:x64)".
+
+  "toolchain"
+      The label of the toolchain. This will match the value of the
+      "current_toolchain" variable when inside that target's
+      declaration.
+
+```
+
+### **Examples**
+
+```
+  get_label_info(":foo", "name")
+*  # Returns string "foo".
+*
+  get_label_info("//foo/bar:baz", "gen_dir")
+*  # Returns string "//out/Debug/gen/foo/bar".
+*
+
+```
+## **get_path_info**: Extract parts of a file or directory name.
+
+```
+  get_path_info(input, what)
+
+  The first argument is either a string representing a file or
+  directory name, or a list of such strings. If the input is a list
+  the return value will be a list containing the result of applying the
+  rule to each item in the input.
+
+```
+
+### **Possible values for the "what" parameter**
+
+```
+  "file"
+      The substring after the last slash in the path, including the name
+      and extension. If the input ends in a slash, the empty string will
+      be returned.
+        "foo/bar.txt" => "bar.txt"
+        "bar.txt" => "bar.txt"
+        "foo/" => ""
+        "" => ""
+
+  "name"
+     The substring of the file name not including the extension.
+        "foo/bar.txt" => "bar"
+        "foo/bar" => "bar"
+        "foo/" => ""
+
+  "extension"
+      The substring following the last period following the last slash,
+      or the empty string if not found. The period is not included.
+        "foo/bar.txt" => "txt"
+        "foo/bar" => ""
+
+  "dir"
+      The directory portion of the name, not including the slash.
+        "foo/bar.txt" => "foo"
+        "//foo/bar" => "//foo"
+        "foo" => "."
+
+      The result will never end in a slash, so if the resulting
+      is empty, the system ("/") or source ("//") roots, a "."
+      will be appended such that it is always legal to append a slash
+      and a filename and get a valid path.
+
+  "out_dir"
+      The output file directory corresponding to the path of the
+      given file, not including a trailing slash.
+        "//foo/bar/baz.txt" => "//out/Default/obj/foo/bar"
+  "gen_dir"
+      The generated file directory corresponding to the path of the
+      given file, not including a trailing slash.
+        "//foo/bar/baz.txt" => "//out/Default/gen/foo/bar"
+
+  "abspath"
+      The full absolute path name to the file or directory. It will be
+      resolved relative to the currebt directory, and then the source-
+      absolute version will be returned. If the input is system-
+      absolute, the same input will be returned.
+        "foo/bar.txt" => "//mydir/foo/bar.txt"
+        "foo/" => "//mydir/foo/"
+        "//foo/bar" => "//foo/bar"  (already absolute)
+        "/usr/include" => "/usr/include"  (already absolute)
+
+      If you want to make the path relative to another directory, or to
+      be system-absolute, see rebase_path().
+
+```
+
+### **Examples**
+```
+  sources = [ "foo.cc", "foo.h" ]
+  result = get_path_info(source, "abspath")
+*  # result will be [ "//mydir/foo.cc", "//mydir/foo.h" ]
+*
+  result = get_path_info("//foo/bar/baz.cc", "dir")
+*  # result will be "//foo/bar"
+*
+*  # Extract the source-absolute directory name,
+*  result = get_path_info(get_path_info(path, "dir"), "abspath")
+
+
+```
+## **get_target_outputs**: [file list] Get the list of outputs from a target.
+
+```
+  get_target_outputs(target_label)
+
+  Returns a list of output files for the named target. The named target
+  must have been previously defined in the current file before this
+  function is called (it can't reference targets in other files because
+  there isn't a defined execution order, and it obviously can't
+  reference targets that are defined after the function call).
+
+  Only copy and action targets are supported. The outputs from binary
+  targets will depend on the toolchain definition which won't
+  necessarily have been loaded by the time a given line of code has run,
+  and source sets and groups have no useful output file.
+
+```
+
+### **Return value**
+
+```
+  The names in the resulting list will be absolute file paths (normally
+  like "//out/Debug/bar.exe", depending on the build directory).
+
+  action targets: this will just return the files specified in the
+  "outputs" variable of the target.
+
+  action_foreach targets: this will return the result of applying
+  the output template to the sources (see "gn help source_expansion").
+  This will be the same result (though with guaranteed absolute file
+  paths), as process_file_template will return for those inputs
+  (see "gn help process_file_template").
+
+  binary targets (executables, libraries): this will return a list
+  of the resulting binary file(s). The "main output" (the actual
+  binary or library) will always be the 0th element in the result.
+  Depending on the platform and output type, there may be other output
+  files as well (like import libraries) which will follow.
+
+  source sets and groups: this will return a list containing the path of
+  the "stamp" file that Ninja will produce once all outputs are
+  generated. This probably isn't very useful.
+
+```
+
+### **Example**
+
+```
+*  # Say this action generates a bunch of C source files.
+*  action_foreach("my_action") {
+    sources = [ ... ]
+    outputs = [ ... ]
+  }
+
+*  # Compile the resulting source files into a source set.
+*  source_set("my_lib") {
+    sources = get_target_outputs(":my_action")
+  }
+
+
+```
+## **getenv**: Get an environment variable.
+
+```
+  value = getenv(env_var_name)
+
+  Returns the value of the given enironment variable. If the value is
+  not found, it will try to look up the variable with the "opposite"
+  case (based on the case of the first letter of the variable), but
+  is otherwise case-sensitive.
+
+  If the environment variable is not found, the empty string will be
+  returned. Note: it might be nice to extend this if we had the concept
+  of "none" in the language to indicate lookup failure.
+
+```
+
+### **Example**:
+
+```
+  home_dir = getenv("HOME")
+
+
+```
+## **group**: Declare a named group of targets.
+
+```
+  This target type allows you to create meta-targets that just collect a
+  set of dependencies into one named target. Groups can additionally
+  specify configs that apply to their dependents.
+
+  Depending on a group is exactly like depending directly on that
+  group's deps. Direct dependent configs will get automatically
+  forwarded through the group so you shouldn't need to use
+  "forward_dependent_configs_from.
+
+```
+
+### **Variables**
+
+```
+  Deps: data_deps, deps, forward_dependent_configs_from, public_deps
+  Dependent configs: all_dependent_configs, public_configs
+
+```
+
+### **Example**
+
+```
+  group("all") {
+    deps = [
+      "//project:runner",
+      "//project:unit_tests",
+    ]
+  }
+
+
+```
+## **import**: Import a file into the current scope.
+
+```
+  The import command loads the rules and variables resulting from
+  executing the given file into the current scope.
+
+  By convention, imported files are named with a .gni extension.
+
+  An import is different than a C++ "include". The imported file is
+  executed in a standalone environment from the caller of the import
+  command. The results of this execution are cached for other files that
+  import the same .gni file.
+
+  Note that you can not import a BUILD.gn file that's otherwise used
+  in the build. Files must either be imported or implicitly loaded as
+  a result of deps rules, but not both.
+
+  The imported file's scope will be merged with the scope at the point
+  import was called. If there is a conflict (both the current scope and
+  the imported file define some variable or rule with the same name but
+  different value), a runtime error will be thrown. Therefore, it's good
+  practice to minimize the stuff that an imported file defines.
+
+  Variables and templates beginning with an underscore '_' are
+  considered private and will not be imported. Imported files can use
+  such variables for internal computation without affecting other files.
+
+```
+
+### **Examples**:
+
+```
+  import("//build/rules/idl_compilation_rule.gni")
+
+*  # Looks in the current directory.
+*  import("my_vars.gni")
+
+
+```
+## **print**: Prints to the console.
+
+```
+  Prints all arguments to the console separated by spaces. A newline is
+  automatically appended to the end.
+
+  This function is intended for debugging. Note that build files are run
+  in parallel so you may get interleaved prints. A buildfile may also
+  be executed more than once in parallel in the context of different
+  toolchains so the prints from one file may be duplicated or
+  interleaved with itself.
+
+```
+
+### **Examples**:
+```
+  print("Hello world")
+
+  print(sources, deps)
+
+
+```
+## **process_file_template**: Do template expansion over a list of files.
+
+```
+  process_file_template(source_list, template)
+
+  process_file_template applies a template list to a source file list,
+  returning the result of applying each template to each source. This is
+  typically used for computing output file names from input files.
+
+  In most cases, get_target_outputs() will give the same result with
+  shorter, more maintainable code. This function should only be used
+  when that function can't be used (like there's no target or the target
+  is defined in another build file).
+
+```
+
+### **Arguments**:
+
+```
+  The source_list is a list of file names.
+
+  The template can be a string or a list. If it is a list, multiple
+  output strings are generated for each input.
+
+  The template should contain source expansions to which each name in
+  the source list is applied. See "gn help source_expansion".
+
+```
+
+### **Example**:
+
+```
+  sources = [
+    "foo.idl",
+    "bar.idl",
+  ]
+  myoutputs = process_file_template(
+      sources,
+      [ "$target_gen_dir/{{source_name_part}}.cc",
+        "$target_gen_dir/{{source_name_part}}.h" ])
+
+ The result in this case will be:
+    [ "//out/Debug/foo.cc"
+      "//out/Debug/foo.h"
+      "//out/Debug/bar.cc"
+      "//out/Debug/bar.h" ]
+
+
+```
+## **read_file**: Read a file into a variable.
+
+```
+  read_file(filename, input_conversion)
+
+  Whitespace will be trimmed from the end of the file. Throws an error
+  if the file can not be opened.
+
+```
+
+### **Arguments**:
+
+```
+  filename
+      Filename to read, relative to the build file.
+
+  input_conversion
+      Controls how the file is read and parsed.
+      See "gn help input_conversion".
+
+```
+
+### **Example**
+```
+  lines = read_file("foo.txt", "list lines")
+
+
+```
+## **rebase_path**: Rebase a file or directory to another location.
+
+```
+  converted = rebase_path(input,
+                          new_base = "",
+                          current_base = ".")
+
+  Takes a string argument representing a file name, or a list of such
+  strings and converts it/them to be relative to a different base
+  directory.
+
+  When invoking the compiler or scripts, GN will automatically convert
+  sources and include directories to be relative to the build directory.
+  However, if you're passing files directly in the "args" array or
+  doing other manual manipulations where GN doesn't know something is
+  a file name, you will need to convert paths to be relative to what
+  your tool is expecting.
+
+  The common case is to use this to convert paths relative to the
+  current directory to be relative to the build directory (which will
+  be the current directory when executing scripts).
+
+  If you want to convert a file path to be source-absolute (that is,
+  beginning with a double slash like "//foo/bar"), you should use
+  the get_path_info() function. This function won't work because it will
+  always make relative paths, and it needs to support making paths
+  relative to the source root, so can't also generate source-absolute
+  paths without more special-cases.
+
+```
+
+### **Arguments**:
+
+```
+  input
+      A string or list of strings representing file or directory names
+      These can be relative paths ("foo/bar.txt"), system absolute
+      paths ("/foo/bar.txt"), or source absolute paths
+      ("//foo/bar.txt").
+
+  new_base
+      The directory to convert the paths to be relative to. This can be
+      an absolute path or a relative path (which will be treated
+      as being relative to the current BUILD-file's directory).
+
+      As a special case, if new_base is the empty string (the default),
+      all paths will be converted to system-absolute native style paths
+      with system path separators. This is useful for invoking external
+      programs.
+
+  current_base
+      Directory representing the base for relative paths in the input.
+      If this is not an absolute path, it will be treated as being
+      relative to the current build file. Use "." (the default) to
+      convert paths from the current BUILD-file's directory.
+
+```
+
+### **Return value**
+
+```
+  The return value will be the same type as the input value (either a
+  string or a list of strings). All relative and source-absolute file
+  names will be converted to be relative to the requested output
+  System-absolute paths will be unchanged.
+
+```
+
+### **Example**
+
+```
+*  # Convert a file in the current directory to be relative to the build
+**  # directory (the current dir when executing compilers and scripts).
+*  foo = rebase_path("myfile.txt", root_build_dir)
+*  # might produce "../../project/myfile.txt".
+*
+*  # Convert a file to be system absolute:
+*  foo = rebase_path("myfile.txt")
+*  # Might produce "D:\source\project\myfile.txt" on Windows or
+**  # "/home/you/source/project/myfile.txt" on Linux.
+*
+*  # Typical usage for converting to the build directory for a script.
+*  action("myscript") {
+*    # Don't convert sources, GN will automatically convert these to be
+**    # relative to the build directory when it constructs the command
+**    # line for your script.
+*    sources = [ "foo.txt", "bar.txt" ]
+
+*    # Extra file args passed manually need to be explicitly converted
+**    # to be relative to the build directory:
+*    args = [
+      "--data",
+      rebase_path("//mything/data/input.dat", root_build_dir),
+      "--rel",
+      rebase_path("relative_path.txt", root_build_dir)
+    ] + rebase_path(sources, root_build_dir)
+  }
+
+
+```
+## **set_default_toolchain**: Sets the default toolchain name.
+
+```
+  set_default_toolchain(toolchain_label)
+
+  The given label should identify a toolchain definition (see
+  "help toolchain"). This toolchain will be used for all targets
+  unless otherwise specified.
+
+  This function is only valid to call during the processing of the build
+  configuration file. Since the build configuration file is processed
+  separately for each toolchain, this function will be a no-op when
+  called under any non-default toolchains.
+
+  For example, the default toolchain should be appropriate for the
+  current environment. If the current environment is 32-bit and 
+  somebody references a target with a 64-bit toolchain, we wouldn't
+  want processing of the build config file for the 64-bit toolchain to
+  reset the default toolchain to 64-bit, we want to keep it 32-bits.
+
+```
+
+### **Argument**:
+
+```
+  toolchain_label
+      Toolchain name.
+
+```
+
+### **Example**:
+
+```
+  set_default_toolchain("//build/config/win:vs32")
+
+```
+## **set_defaults**: Set default values for a target type.
+
+```
+  set_defaults(<target_type_name>) { <values...> }
+
+  Sets the default values for a given target type. Whenever
+  target_type_name is seen in the future, the values specified in
+  set_default's block will be copied into the current scope.
+
+  When the target type is used, the variable copying is very strict.
+  If a variable with that name is already in scope, the build will fail
+  with an error.
+
+  set_defaults can be used for built-in target types ("executable",
+  "shared_library", etc.) and custom ones defined via the "template"
+  command.
+
+```
+
+### **Example**:
+```
+  set_defaults("static_library") {
+    configs = [ "//tools/mything:settings" ]
+  }
+
+  static_library("mylib")
+*    # The configs will be auto-populated as above. You can remove it if
+**    # you don't want the default for a particular default:
+*    configs -= "//tools/mything:settings"
+  }
+
+
+```
+## **set_sources_assignment_filter**: Set a pattern to filter source files.
+
+```
+  The sources assignment filter is a list of patterns that remove files
+  from the list implicitly whenever the "sources" variable is
+  assigned to. This is intended to be used to globally filter out files
+  with platform-specific naming schemes when they don't apply, for
+  example, you may want to filter out all "*_win.cc" files on non-
+  Windows platforms.
+
+  Typically this will be called once in the master build config script
+  to set up the filter for the current platform. Subsequent calls will
+  overwrite the previous values.
+
+  If you want to bypass the filter and add a file even if it might
+  be filtered out, call set_sources_assignment_filter([]) to clear the
+  list of filters. This will apply until the current scope exits
+
+```
+
+### **How to use patterns**
+
+```
+  File patterns are VERY limited regular expressions. They must match
+  the entire input string to be counted as a match. In regular
+  expression parlance, there is an implicit "^...$" surrounding your
+  input. If you want to match a substring, you need to use wildcards at
+  the beginning and end.
+
+  There are only two special tokens understood by the pattern matcher.
+  Everything else is a literal.
+
+   * Matches zero or more of any character. It does not depend on the
+     preceding character (in regular expression parlance it is
+     equivalent to ".*").
+
+  \b Matches a path boundary. This will match the beginning or end of
+     a string, or a slash.
+
+```
+
+### **Pattern examples**
+
+```
+  "*asdf*"
+      Matches a string containing "asdf" anywhere.
+
+  "asdf"
+      Matches only the exact string "asdf".
+
+  "*.cc"
+      Matches strings ending in the literal ".cc".
+
+  "\bwin/*"
+      Matches "win/foo" and "foo/win/bar.cc" but not "iwin/foo".
+
+```
+
+### **Sources assignment example**
+
+```
+*  # Filter out all _win files.
+*  set_sources_assignment_filter([ "*_win.cc", "*_win.h" ])
+  sources = [ "a.cc", "b_win.cc" ]
+  print(sources)
+*  # Will print [ "a.cc" ]. b_win one was filtered out.
+*
+
+```
+## **shared_library**: Declare a shared library target.
+
+```
+  A shared library will be specified on the linker line for targets
+  listing the shared library in its "deps". If you don't want this
+  (say you dynamically load the library at runtime), then you should
+  depend on the shared library via "data_deps" instead.
+
+```
+
+### **Variables**
+
+```
+  Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
+         defines, include_dirs, ldflags, lib_dirs, libs
+  Deps: data_deps, deps, forward_dependent_configs_from, public_deps
+  Dependent configs: all_dependent_configs, public_configs
+  General: check_includes, configs, data, inputs, output_name,
+           output_extension, public, sources, testonly, visibility
+
+
+```
+## **source_set**: Declare a source set target.
+
+```
+  A source set is a collection of sources that get compiled, but are not
+  linked to produce any kind of library. Instead, the resulting object
+  files are implicitly added to the linker line of all targets that
+  depend on the source set.
+
+  In most cases, a source set will behave like a static library, except
+  no actual library file will be produced. This will make the build go
+  a little faster by skipping creation of a large static library, while
+  maintaining the organizational benefits of focused build targets.
+
+  The main difference between a source set and a static library is
+  around handling of exported symbols. Most linkers assume declaring
+  a function exported means exported from the static library. The linker
+  can then do dead code elimination to delete code not reachable from
+  exported functions.
+
+  A source set will not do this code elimination since there is no link
+  step. This allows you to link many sources sets into a shared library
+  and have the "exported symbol" notation indicate "export from the
+  final shared library and not from the intermediate targets." There is
+  no way to express this concept when linking multiple static libraries
+  into a shared library.
+
+```
+
+### **Variables**
+
+```
+  Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
+         defines, include_dirs, ldflags, lib_dirs, libs
+  Deps: data_deps, deps, forward_dependent_configs_from, public_deps
+  Dependent configs: all_dependent_configs, public_configs
+  General: check_includes, configs, data, inputs, output_name,
+           output_extension, public, sources, testonly, visibility
+
+
+```
+## **static_library**: Declare a static library target.
+
+```
+  Make a ".a" / ".lib" file.
+
+  If you only need the static library for intermediate results in the
+  build, you should consider a source_set instead since it will skip
+  the (potentially slow) step of creating the intermediate library file.
+
+```
+
+### **Variables**
+
+```
+  Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
+         defines, include_dirs, ldflags, lib_dirs, libs
+  Deps: data_deps, deps, forward_dependent_configs_from, public_deps
+  Dependent configs: all_dependent_configs, public_configs
+  General: check_includes, configs, data, inputs, output_name,
+           output_extension, public, sources, testonly, visibility
+
+
+```
+## **template**: Define a template rule.
+
+```
+  A template defines a custom name that acts like a function. It
+  provides a way to add to the built-in target types.
+
+  The template() function is used to declare a template. To invoke the
+  template, just use the name of the template like any other target
+  type.
+
+  Often you will want to declare your template in a special file that
+  other files will import (see "gn help import") so your template
+  rule can be shared across build files.
+
+```
+
+### **More details**:
+
+```
+  When you call template() it creates a closure around all variables
+  currently in scope with the code in the template block. When the
+  template is invoked, the closure will be executed.
+
+  When the template is invoked, the code in the caller is executed and
+  passed to the template code as an implicit "invoker" variable. The
+  template uses this to read state out of the invoking code.
+
+  One thing explicitly excluded from the closure is the "current
+  directory" against which relative file names are resolved. The
+  current directory will be that of the invoking code, since typically
+  that code specifies the file names. This means all files internal
+  to the template should use absolute names.
+
+```
+
+### **Target naming**:
+
+```
+  Your template should almost always define a built-in target with the
+  name the template invoker specified. For example, if you have an IDL
+  template and somebody does:
+    idl("foo") {...
+  you will normally want this to expand to something defining a
+  source_set or static_library named "foo" (among other things you may
+  need). This way, when another target specifies a dependency on
+  "foo", the static_library or source_set will be linked.
+
+  It is also important that any other targets your template expands to
+  have globally unique names, or you will get collisions.
+
+  Access the invoking name in your template via the implicit
+  "target_name" variable. This should also be the basis of how other
+  targets that a template expands to to ensure uniquness.
+
+  A typical example would be a template that defines an action to
+  generate some source files, and a source_set to compile that source.
+  Your template would name the source_set "target_name" because
+  that's what you want external targets to depend on to link your code.
+  And you would name the action something like "${target_name}_action"
+  to make it unique. The source set would have a dependency on the
+  action to make it run.
+
+```
+
+### **Example of defining a template**:
+
+```
+  template("my_idl") {
+*    # Be nice and help callers debug problems by checking that the
+**    # variables the template requires are defined. This gives a nice
+**    # message rather than giving the user an error about an
+**    # undefined variable in the file defining the template
+**    #
+**    # You can also use defined() to give default values to variables
+**    # unspecified by the invoker.
+*    assert(defined(invoker.sources),
+           "Need sources in $target_name listing the idl files.")
+
+*    # Name of the intermediate target that does the code gen. This must
+**    # incorporate the target name so it's unique across template
+**    # instantiations.
+*    code_gen_target_name = target_name + "_code_gen"
+
+*    # Intermediate target to convert IDL to C source. Note that the name
+**    # is based on the name the invoker of the template specified. This
+**    # way, each time the template is invoked we get a unique
+**    # intermediate action name (since all target names are in the global
+**    # scope).
+*    action_foreach(code_gen_target_name) {
+*      # Access the scope defined by the invoker via the implicit
+**      # "invoker" variable.
+*      sources = invoker.sources
+
+*      # Note that we need an absolute path for our script file name.
+**      # The current directory when executing this code will be that of
+**      # the invoker (this is why we can use the "sources" directly
+**      # above without having to rebase all of the paths). But if we need
+**      # to reference a script relative to the template file, we'll need
+**      # to use an absolute path instead.
+*      script = "//tools/idl/idl_code_generator.py"
+
+*      # Tell GN how to expand output names given the sources.
+**      # See "gn help source_expansion" for more.
+*      outputs = [ "$target_gen_dir/{{source_name_part}}.cc",
+                  "$target_gen_dir/{{source_name_part}}.h" ]
+    }
+
+*    # Name the source set the same as the template invocation so
+**    # instancing this template produces something that other targets
+**    # can link to in their deps.
+*    source_set(target_name) {
+*      # Generates the list of sources, we get these from the
+**      # action_foreach above.
+*      sources = get_target_outputs(":$code_gen_target_name")
+
+*      # This target depends on the files produced by the above code gen
+**      # target.
+*      deps = [ ":$code_gen_target_name" ]
+    }
+  }
+
+```
+
+### **Example of invoking the resulting template**:
+
+```
+*  # This calls the template code above, defining target_name to be
+**  # "foo_idl_files" and "invoker" to be the set of stuff defined in
+**  # the curly brackets.
+*  my_idl("foo_idl_files") {
+*    # Goes into the template as "invoker.sources".
+*    sources = [ "foo.idl", "bar.idl" ]
+  }
+
+*  # Here is a target that depends on our template.
+*  executable("my_exe") {
+*    # Depend on the name we gave the template call above. Internally,
+**    # this will produce a dependency from executable to the source_set
+**    # inside the template (since it has this name), which will in turn
+**    # depend on the code gen action.
+*    deps = [ ":foo_idl_files" ]
+  }
+
+
+```
+## **tool**: Specify arguments to a toolchain tool.
+
+### **Usage**:
+
+```
+  tool(<tool type>) {
+    <tool variables...>
+  }
+
+```
+
+### **Tool types**
+
+```
+    Compiler tools:
+      "cc": C compiler
+      "cxx": C++ compiler
+      "objc": Objective C compiler
+      "objcxx": Objective C++ compiler
+      "rc": Resource compiler (Windows .rc files)
+      "asm": Assembler
+
+    Linker tools:
+      "alink": Linker for static libraries (archives)
+      "solink": Linker for shared libraries
+      "link": Linker for executables
+
+    Other tools:
+      "stamp": Tool for creating stamp files
+      "copy": Tool to copy files.
+
+```
+
+### **Tool variables**
+
+```
+    command  [string with substitutions]
+        Valid for: all tools (required)
+
+        The command to run.
+
+    default_output_extension  [string]
+        Valid for: linker tools
+
+        Extension for the main output of a linkable tool. It includes
+        the leading dot. This will be the default value for the
+        {{output_extension}} expansion (discussed below) but will be
+        overridden by by the "output extension" variable in a target,
+        if one is specified. Empty string means no extension.
+
+        GN doesn't actually do anything with this extension other than
+        pass it along, potentially with target-specific overrides. One
+        would typically use the {{output_extension}} value in the
+        "outputs" to read this value.
+
+        Example: default_output_extension = ".exe"
+
+    depfile  [string]
+        Valid for: compiler tools (optional)
+
+        If the tool can write ".d" files, this specifies the name of
+        the resulting file. These files are used to list header file
+        dependencies (or other implicit input dependencies) that are
+        discovered at build time. See also "depsformat".
+
+        Example: depfile = "{{output}}.d"
+
+    depsformat  [string]
+        Valid for: compiler tools (when depfile is specified)
+
+        Format for the deps outputs. This is either "gcc" or "msvc".
+        See the ninja documentation for "deps" for more information.
+
+        Example: depsformat = "gcc"
+
+    description  [string with substitutions, optional]
+        Valid for: all tools
+
+        What to print when the command is run.
+
+        Example: description = "Compiling {{source}}"
+
+    lib_switch  [string, optional, link tools only]
+    lib_dir_switch  [string, optional, link tools only]
+        Valid for: Linker tools except "alink"
+
+        These strings will be prepended to the libraries and library
+        search directories, respectively, because linkers differ on how
+        specify them. If you specified:
+          lib_switch = "-l"
+          lib_dir_switch = "-L"
+        then the "{{libs}}" expansion for [ "freetype", "expat"]
+        would be "-lfreetype -lexpat".
+
+    outputs  [list of strings with substitutions]
+        Valid for: Linker and compiler tools (required)
+
+        An array of names for the output files the tool produces. These
+        are relative to the build output directory. There must always be
+        at least one output file. There can be more than one output (a
+        linker might produce a library and an import library, for
+        example).
+
+        This array just declares to GN what files the tool will
+        produce. It is your responsibility to specify the tool command
+        that actually produces these files.
+
+        If you specify more than one output for shared library links,
+        you should consider setting link_output and depend_output.
+        Otherwise, the first entry in the outputs list should always be
+        the main output which will be linked to.
+
+        Example for a compiler tool that produces .obj files:
+          outputs = [
+            "{{source_out_dir}}/{{source_name_part}}.obj"
+          ]
+
+        Example for a linker tool that produces a .dll and a .lib. The
+        use of {{output_extension}} rather than hardcoding ".dll"
+        allows the extension of the library to be overridden on a
+        target-by-target basis, but in this example, it always
+        produces a ".lib" import library:
+          outputs = [
+            "{{root_out_dir}}/{{target_output_name}}{{output_extension}}",
+            "{{root_out_dir}}/{{target_output_name}}.lib",
+          ]
+
+    link_output  [string with substitutions]
+    depend_output  [string with substitutions]
+        Valid for: "solink" only (optional)
+
+        These two files specify whch of the outputs from the solink
+        tool should be used for linking and dependency tracking. These
+        should match entries in the "outputs". If unspecified, the
+        first item in the "outputs" array will be used for both. See
+        "Separate linking and dependencies for shared libraries"
+        below for more.
+
+        On Windows, where the tools produce a .dll shared library and
+        a .lib import library, you will want both of these to be the
+        import library. On Linux, if you're not doing the separate
+        linking/dependency optimization, both of these should be the
+        .so output.
+
+    output_prefix  [string]
+        Valid for: Linker tools (optional)
+
+        Prefix to use for the output name. Defaults to empty. This
+        prefix will be prepended to the name of the target (or the
+        output_name if one is manually specified for it) if the prefix
+        is not already there. The result will show up in the
+        {{output_name}} substitution pattern.
+
+        This is typically used to prepend "lib" to libraries on
+        Posix systems:
+          output_prefix = "lib"
+
+    restat  [boolean]
+        Valid for: all tools (optional, defaults to false)
+
+        Requests that Ninja check the file timestamp after this tool has
+        run to determine if anything changed. Set this if your tool has
+        the ability to skip writing output if the output file has not
+        changed.
+
+        Normally, Ninja will assume that when a tool runs the output
+        be new and downstream dependents must be rebuild. When this is
+        set to trye, Ninja can skip rebuilding downstream dependents for
+        input changes that don't actually affect the output.
+
+        Example:
+          restat = true
+
+    rspfile  [string with substitutions]
+        Valid for: all tools (optional)
+
+        Name of the response file. If empty, no response file will be
+        used. See "rspfile_content".
+
+    rspfile_content  [string with substitutions]
+        Valid for: all tools (required when "rspfile" is specified)
+
+        The contents to be written to the response file. This may
+        include all or part of the command to send to the tool which
+        allows you to get around OS command-line length limits.
+
+        This example adds the inputs and libraries to a response file,
+        but passes the linker flags directly on the command line:
+          tool("link") {
+            command = "link -o {{output}} {{ldflags}} @{{output}}.rsp"
+            rspfile = "{{output}}.rsp"
+            rspfile_content = "{{inputs}} {{solibs}} {{libs}}"
+          }
+
+```
+
+### **Expansions for tool variables**
+```
+  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.
+
+    {{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.
+        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:
+
+    {{cflags}}
+    {{cflags_c}}
+    {{cflags_cc}}
+    {{cflags_objc}}
+    {{cflags_objcc}}
+    {{defines}}
+    {{include_dirs}}
+        Strings correspond that to the processed flags/defines/include
+        directories specified for the target.
+        Example: "--enable-foo --enable-bar"
+
+        Defines will be prefixed by "-D" and include directories will
+        be prefixed by "-I" (these work with Posix tools as well as
+        Microsoft ones).
+
+    {{source}}
+        The relative path and name of the current input file.
+        Example: "../../base/my_file.cc"
+
+    {{source_file_part}}
+        The file part of the source including the extension (with no
+        directory information).
+        Example: "foo.cc"
+
+    {{source_name_part}}
+        The filename part of the source file with no directory or
+        extension.
+        Example: "foo"
+
+    {{source_gen_dir}}
+    {{source_out_dir}}
+        The directory in the generated file and output directories,
+        respectively, for the current input file. If the source file
+        is in the same directory as the target is declared in, they will
+        will be the same as the "target" versions above.
+        Example: "gen/base/test"
+
+  Linker tools have multiple inputs and (potentially) multiple outputs
+  The following expansions are available:
+
+    {{inputs}}
+    {{inputs_newline}}
+        Expands to the inputs to the link step. This will be a list of
+        object files and static libraries.
+        Example: "obj/foo.o obj/bar.o obj/somelibrary.a"
+
+        The "_newline" version will separate the input files with
+        newlines instead of spaces. This is useful in response files:
+        some linkers can take a "-filelist" flag which expects newline
+        separated files, and some Microsoft tools have a fixed-sized
+        buffer for parsing each line of a response file.
+
+    {{ldflags}}
+        Expands to the processed set of ldflags and library search paths
+        specified for the target.
+        Example: "-m64 -fPIC -pthread -L/usr/local/mylib"
+
+    {{libs}}
+        Expands to the list of system libraries to link to. Each will
+        be prefixed by the "lib_prefix".
+
+        As a special case to support Mac, libraries with names ending in
+        ".framework" will be added to the {{libs}} with "-framework"
+        preceeding it, and the lib prefix will be ignored.
+
+        Example: "-lfoo -lbar"
+
+    {{output_extension}}
+        The value of the "output_extension" variable in the target,
+        or the value of the "default_output_extension" value in the
+        tool if the target does not specify an output extension.
+        Example: ".so"
+
+    {{solibs}}
+        Extra libraries from shared library dependencide not specified
+        in the {{inputs}}. This is the list of link_output files from
+        shared libraries (if the solink tool specifies a "link_output"
+        variable separate from the "depend_output").
+
+        These should generally be treated the same as libs by your tool.
+        Example: "libfoo.so libbar.so"
+
+  The copy tool allows the common compiler/linker substitutions, plus
+  {{source}} which is the source of the copy. The stamp tool allows
+  only the common tool substitutions.
+
+```
+
+### **Separate linking and dependencies for shared libraries**
+
+```
+  Shared libraries are special in that not all changes to them require
+  that dependent targets be re-linked. If the shared library is changed
+  but no imports or exports are different, dependent code needn't be
+  relinked, which can speed up the build.
+
+  If your link step can output a list of exports from a shared library
+  and writes the file only if the new one is different, the timestamp of
+  this file can be used for triggering re-links, while the actual shared
+  library would be used for linking.
+
+  You will need to specify
+    restat = true
+  in the linker tool to make this work, so Ninja will detect if the
+  timestamp of the dependency file has changed after linking (otherwise
+  it will always assume that running a command updates the output):
+
+    tool("solink") {
+      command = "..."
+      outputs = [
+        "{{root_out_dir}}/{{target_output_name}}{{output_extension}}",
+        "{{root_out_dir}}/{{target_output_name}}{{output_extension}}.TOC",
+      ]
+      link_output =
+        "{{root_out_dir}}/{{target_output_name}}{{output_extension}}"
+      depend_output =
+        "{{root_out_dir}}/{{target_output_name}}{{output_extension}}.TOC"
+      restat = true
+    }
+
+```
+
+### **Example**
+
+```
+  toolchain("my_toolchain") {
+*    # Put these at the top to apply to all tools below.
+*    lib_prefix = "-l"
+    lib_dir_prefix = "-L"
+
+    tool("cc") {
+      command = "gcc {{source}} -o {{output}}"
+      outputs = [ "{{source_out_dir}}/{{source_name_part}}.o" ]
+      description = "GCC {{source}}"
+    }
+    tool("cxx") {
+      command = "g++ {{source}} -o {{output}}"
+      outputs = [ "{{source_out_dir}}/{{source_name_part}}.o" ]
+      description = "G++ {{source}}"
+    }
+  }
+
+
+```
+## **toolchain**: Defines a toolchain.
+
+```
+  A toolchain is a set of commands and build flags used to compile the
+  source code. You can have more than one toolchain in use at once in
+  a build.
+
+```
+
+### **Functions and variables**
+
+```
+  tool()
+    The tool() function call specifies the commands commands to run for
+    a given step. See "gn help tool".
+
+  toolchain_args()
+    List of arguments to pass to the toolchain when invoking this
+    toolchain. This applies only to non-default toolchains. See
+    "gn help toolchain_args" for more.
+
+  deps
+    Dependencies of this toolchain. These dependencies will be resolved
+    before any target in the toolchain is compiled. To avoid circular
+    dependencies these must be targets defined in another toolchain.
+
+    This is expressed as a list of targets, and generally these targets
+    will always specify a toolchain:
+      deps = [ "//foo/bar:baz(//build/toolchain:bootstrap)" ]
+
+    This concept is somewhat inefficient to express in Ninja (it
+    requires a lot of duplicate of rules) so should only be used when
+    absolutely necessary.
+
+  concurrent_links
+    In integer expressing the number of links that Ninja will perform in
+    parallel. GN will create a pool for shared library and executable
+    link steps with this many processes. Since linking is memory- and
+    I/O-intensive, projects with many large targets may want to limit
+    the number of parallel steps to avoid overloading the computer.
+    Since creating static libraries is generally not as intensive
+    there is no limit to "alink" steps.
+
+    Defaults to 0 which Ninja interprets as "no limit".
+
+    The value used will be the one from the default toolchain of the
+    current build.
+
+```
+
+### **Invoking targets in toolchains**:
+
+```
+  By default, when a target depends on another, there is an implicit
+  toolchain label that is inherited, so the dependee has the same one
+  as the dependent.
+
+  You can override this and refer to any other toolchain by explicitly
+  labeling the toolchain to use. For example:
+    data_deps = [ "//plugins:mine(//toolchains:plugin_toolchain)" ]
+  The string "//build/toolchains:plugin_toolchain" is a label that
+  identifies the toolchain declaration for compiling the sources.
+
+  To load a file in an alternate toolchain, GN does the following:
+
+   1. Loads the file with the toolchain definition in it (as determined
+      by the toolchain label).
+   2. Re-runs the master build configuration file, applying the
+      arguments specified by the toolchain_args section of the toolchain
+      definition (see "gn help toolchain_args").
+   3. Loads the destination build file in the context of the
+      configuration file in the previous step.
+
+```
+
+### **Example**:
+```
+  toolchain("plugin_toolchain") {
+    concurrent_links = 8
+
+    tool("cc") {
+      command = "gcc {{source}}"
+      ...
+    }
+
+    toolchain_args() {
+      is_plugin = true
+      is_32bit = true
+      is_64bit = false
+    }
+  }
+
+
+```
+## **toolchain_args**: Set build arguments for toolchain build setup.
+
+```
+  Used inside a toolchain definition to pass arguments to an alternate
+  toolchain's invocation of the build.
+
+  When you specify a target using an alternate toolchain, the master
+  build configuration file is re-interpreted in the context of that
+  toolchain (see "gn help toolchain"). The toolchain_args function
+  allows you to control the arguments passed into this alternate
+  invocation of the build.
+
+  Any default system arguments or arguments passed in on the command-
+  line will also be passed to the alternate invocation unless explicitly
+  overridden by toolchain_args.
+
+  The toolchain_args will be ignored when the toolchain being defined
+  is the default. In this case, it's expected you want the default
+  argument values.
+
+  See also "gn help buildargs" for an overview of these arguments.
+
+```
+
+### **Example**:
+```
+  toolchain("my_weird_toolchain") {
+    ...
+    toolchain_args() {
+*      # Override the system values for a generic Posix system.
+*      is_win = false
+      is_posix = true
+
+*      # Pass this new value for specific setup for my toolchain.
+*      is_my_weird_system = true
+    }
+  }
+
+
+```
+## **write_file**: Write a file to disk.
+
+```
+  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.
+
+  TODO(brettw) we probably need an optional third argument to control
+  list formatting.
+
+```
+
+### **Arguments**:
+
+```
+  filename
+      Filename to write. This must be within the output directory.
+
+  data:
+      The list or string to write.
+
+
+```
+## **current_cpu**: The processor architecture of the current toolchain.
+
+```
+  The build configuration usually sets this value based on the value
+  of "host_cpu" (see "gn help host_cpu") and then threads
+  this through the toolchain definitions to ensure that it always
+  reflects the appropriate value.
+
+  This value is not used internally by GN for any purpose. It is
+  set it to the empty string ("") by default but is declared so
+  that it can be overridden on the command line if so desired.
+
+  See "gn help target_cpu" for a list of common values returned.
+
+
+```
+## **current_os**: The operating system of the current toolchain.
+
+```
+  The build configuration usually sets this value based on the value
+  of "target_os" (see "gn help target_os"), and then threads this
+  through the toolchain definitions to ensure that it always reflects
+  the appropriate value.
+
+  This value is not used internally by GN for any purpose. It is
+  set it to the empty string ("") by default but is declared so
+  that it can be overridden on the command line if so desired.
+
+  See "gn help target_os" for a list of common values returned.
+
+
+```
+## **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**:
+
+```
+  if (current_toolchain == "//build:64_bit_toolchain") {
+    executable("output_thats_64_bit_only") {
+      ...
+
+
+```
+## **default_toolchain**: [string] Label of the default toolchain.
+
+```
+  A fully-qualified label representing the default toolchain, which may
+  not necessarily be the current one (see "current_toolchain").
+
+
+```
+## **host_cpu**: The processor architecture that GN is running on.
+
+```
+  This is value is exposed so that cross-compile toolchains can
+  access the host architecture when needed.
+
+  The value should generally be considered read-only, but it can be
+  overriden in order to handle unusual cases where there might
+  be multiple plausible values for the host architecture (e.g., if
+  you can do either 32-bit or 64-bit builds). The value is not used
+  internally by GN for any purpose.
+
+```
+
+### **Some possible values**:
+```
+  - "x64"
+  - "x86"
+
+
+```
+## **host_os**: [string] The operating system that GN is running on.
+
+```
+  This value is exposed so that cross-compiles can access the host
+  build system's settings.
+
+  This value should generally be treated as read-only. It, however,
+  is not used internally by GN for any purpose.
+
+```
+
+### **Some possible values**:
+```
+  - "linux"
+  - "mac"
+  - "win"
+
+
+```
+## **python_path**: Absolute path of Python.
+
+```
+  Normally used in toolchain definitions if running some command
+  requires Python. You will normally not need this when invoking scripts
+  since GN automatically finds it for you.
+
+
+```
+## **root_build_dir**: [string] Directory where build commands are run.
+
+```
+  This is the root build output directory which will be the current
+  directory when executing all compilers and scripts.
+
+  Most often this is used with rebase_path (see "gn help rebase_path")
+  to convert arguments to be relative to a script's current directory.
+
+
+```
+## **root_gen_dir**: Directory for the toolchain's generated files.
+
+```
+  Absolute path to the root of the generated output directory tree for
+  the current toolchain. An example would be "//out/Debug/gen" for the
+  default toolchain, or "//out/Debug/arm/gen" for the "arm"
+  toolchain.
+
+  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 "target_gen_dir" which is usually a better location for
+  generated files. It will be inside the root generated dir.
+
+
+```
+## **root_out_dir**: [string] Root directory for toolchain output files.
+
+```
+  Absolute path to the root of the output directory tree for the current
+  toolchain. It will not have a trailing slash.
+
+  For the default toolchain this will be the same as the root_build_dir.
+  An example would be "//out/Debug" for the default toolchain, or
+  "//out/Debug/arm" for the "arm" toolchain.
+
+  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**:
+
+```
+  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.
+
+```
+  This value should be used to indicate the desired architecture for
+  the primary objects of the build. It will match the cpu architecture
+  of the default toolchain.
+
+  In many cases, this is the same as "host_cpu", but in the case
+  of cross-compiles, this can be set to something different. This 
+  value is different from "current_cpu" in that it can be referenced
+  from inside any toolchain. This value can also be ignored if it is
+  not needed or meaningful for a project.
+
+  This value is not used internally by GN for any purpose, so it
+  may be set to whatever value is needed for the build.
+  GN defaults this value to the empty string ("") and the
+  configuration files should set it to an appropriate value
+  (e.g., setting it to the value of "host_cpu") if it is not
+  overridden on the command line or in the args.gn file.
+
+  Where practical, use one of the following list of common values:
+
+```
+
+### **Possible values**:
+```
+  - "x86"
+  - "x64"
+  - "arm"
+  - "arm64"
+  - "mipsel"
+
+
+```
+## **target_gen_dir**: Directory for a target's generated files.
+
+```
+  Absolute path to the target's generated file directory. This will be
+  the "root_gen_dir" followed by the relative path to the current
+  build file. If your file is in "//tools/doom_melon" then
+  target_gen_dir would be "//out/Debug/gen/tools/doom_melon". It will
+  not have a trailing slash.
+
+  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**:
+
+```
+  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.
+
+```
+  This value should be used to indicate the desired operating system
+  for the primary object(s) of the build. It will match the OS of
+  the default toolchain.
+
+  In many cases, this is the same as "host_os", but in the case of
+  cross-compiles, it may be different. This variable differs from
+  "current_os" in that it can be referenced from inside any
+  toolchain and will always return the initial value.
+
+  This should be set to the most specific value possible. So,
+  "android" or "chromeos" should be used instead of "linux"
+  where applicable, even though Android and ChromeOS are both Linux
+  variants. This can mean that one needs to write
+
+      if (target_os == "android" || target_os == "linux") {
+*          # ...
+*      }
+
+  and so forth.
+
+  This value is not used internally by GN for any purpose, so it
+  may be set to whatever value is needed for the build.
+  GN defaults this value to the empty string ("") and the
+  configuration files should set it to an appropriate value
+  (e.g., setting it to the value of "host_os") if it is not
+  set via the command line or in the args.gn file.
+
+  Where practical, use one of the following list of common values:
+
+```
+
+### **Possible values**:
+```
+  - "android"
+  - "chromeos"
+  - "ios"
+  - "linux"
+  - "nacl"
+  - "mac"
+  - "win"
+
+
+```
+## **target_out_dir**: [string] Directory for target output files.
+
+```
+  Absolute path to the target's generated file directory. If your
+  current target is in "//tools/doom_melon" then this value might be
+  "//out/Debug/obj/tools/doom_melon". It will not have a trailing
+  slash.
+
+  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**:
+
+```
+  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.
+
+```
+  A list of config labels.
+
+  All targets depending on this one, and recursively, all targets
+  depending on those, will have the configs listed in this variable
+  added to them. These configs will also apply to the current target.
+
+  This addition happens in a second phase once a target and all of its
+  dependencies have been resolved. Therefore, a target will not see
+  these force-added configs in their "configs" variable while the
+  script is running, and then can not be removed. As a result, this
+  capability should generally only be used to add defines and include
+  directories necessary to compile a target's headers.
+
+  See also "public_configs".
+
+```
+
+### **Ordering of flags and values**:
+
+```
+  1. Those set on the current target (not in a config).
+  2. Those set on the "configs" on the target in order that the
+     configs appear in the list.
+  3. Those set on the "all_dependent_configs" on the target in order
+     that the configs appear in the list.
+  4. Those set on the "public_configs" on the target in order that
+     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 has "forward_dependent_configs_from",
+     or are public dependencies, they will be applied recursively.
+
+
+```
+## **allow_circular_includes_from**: Permit includes from deps.
+
+```
+  A list of target labels. Must be a subset of the target's "deps".
+  These targets will be permitted to include headers from the current
+  target despite the dependency going in the opposite direction.
+
+```
+
+### **Tedious exposition**
+
+```
+  Normally, for a file in target A to include a file from target B,
+  A must list B as a dependency. This invariant is enforced by the
+  "gn check" command (and the --check flag to "gn gen").
+
+  Sometimes, two targets might be the same unit for linking purposes
+  (two source sets or static libraries that would always be linked
+  together in a final executable or shared library). In this case,
+  you want A to be able to include B's headers, and B to include A's
+  headers.
+
+  This list, if specified, lists which of the dependencies of the
+  current target can include header files from the current target.
+  That is, if A depends on B, B can only include headers from A if it is
+  in A's allow_circular_includes_from list.
+
+```
+
+### **Example**
+
+```
+  source_set("a") {
+    deps = [ ":b", ":c" ]
+    allow_circular_includes_from = [ ":b" ]
+    ...
+  }
+
+
+```
+## **args**: Arguments passed to an action.
+
+```
+  For action and action_foreach targets, args is the list of arguments
+  to pass to the script. Typically you would use source expansion (see
+  "gn help source_expansion") to insert the source file names.
+
+  See also "gn help action" and "gn help action_foreach".
+
+
+```
+## **cflags***: Flags passed to the C compiler.
+
+```
+  A list of strings.
+
+  "cflags" are passed to all invocations of the C, C++, Objective C,
+  and Objective C++ compilers.
+
+  To target one of these variants individually, use "cflags_c",
+  "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
+  These variant-specific versions will be appended to the "cflags".
+
+```
+
+### **Ordering of flags and values**:
+
+```
+  1. Those set on the current target (not in a config).
+  2. Those set on the "configs" on the target in order that the
+     configs appear in the list.
+  3. Those set on the "all_dependent_configs" on the target in order
+     that the configs appear in the list.
+  4. Those set on the "public_configs" on the target in order that
+     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 has "forward_dependent_configs_from",
+     or are public dependencies, they will be applied recursively.
+
+
+```
+## **cflags***: Flags passed to the C compiler.
+
+```
+  A list of strings.
+
+  "cflags" are passed to all invocations of the C, C++, Objective C,
+  and Objective C++ compilers.
+
+  To target one of these variants individually, use "cflags_c",
+  "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
+  These variant-specific versions will be appended to the "cflags".
+
+```
+
+### **Ordering of flags and values**:
+
+```
+  1. Those set on the current target (not in a config).
+  2. Those set on the "configs" on the target in order that the
+     configs appear in the list.
+  3. Those set on the "all_dependent_configs" on the target in order
+     that the configs appear in the list.
+  4. Those set on the "public_configs" on the target in order that
+     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 has "forward_dependent_configs_from",
+     or are public dependencies, they will be applied recursively.
+
+
+```
+## **cflags***: Flags passed to the C compiler.
+
+```
+  A list of strings.
+
+  "cflags" are passed to all invocations of the C, C++, Objective C,
+  and Objective C++ compilers.
+
+  To target one of these variants individually, use "cflags_c",
+  "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
+  These variant-specific versions will be appended to the "cflags".
+
+```
+
+### **Ordering of flags and values**:
+
+```
+  1. Those set on the current target (not in a config).
+  2. Those set on the "configs" on the target in order that the
+     configs appear in the list.
+  3. Those set on the "all_dependent_configs" on the target in order
+     that the configs appear in the list.
+  4. Those set on the "public_configs" on the target in order that
+     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 has "forward_dependent_configs_from",
+     or are public dependencies, they will be applied recursively.
+
+
+```
+## **cflags***: Flags passed to the C compiler.
+
+```
+  A list of strings.
+
+  "cflags" are passed to all invocations of the C, C++, Objective C,
+  and Objective C++ compilers.
+
+  To target one of these variants individually, use "cflags_c",
+  "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
+  These variant-specific versions will be appended to the "cflags".
+
+```
+
+### **Ordering of flags and values**:
+
+```
+  1. Those set on the current target (not in a config).
+  2. Those set on the "configs" on the target in order that the
+     configs appear in the list.
+  3. Those set on the "all_dependent_configs" on the target in order
+     that the configs appear in the list.
+  4. Those set on the "public_configs" on the target in order that
+     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 has "forward_dependent_configs_from",
+     or are public dependencies, they will be applied recursively.
+
+
+```
+## **cflags***: Flags passed to the C compiler.
+
+```
+  A list of strings.
+
+  "cflags" are passed to all invocations of the C, C++, Objective C,
+  and Objective C++ compilers.
+
+  To target one of these variants individually, use "cflags_c",
+  "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
+  These variant-specific versions will be appended to the "cflags".
+
+```
+
+### **Ordering of flags and values**:
+
+```
+  1. Those set on the current target (not in a config).
+  2. Those set on the "configs" on the target in order that the
+     configs appear in the list.
+  3. Those set on the "all_dependent_configs" on the target in order
+     that the configs appear in the list.
+  4. Those set on the "public_configs" on the target in order that
+     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 has "forward_dependent_configs_from",
+     or are public dependencies, they will be applied recursively.
+
+
+```
+## **check_includes**: [boolean] Controls whether a target's files are checked.
+
+```
+  When true (the default), the "gn check" command (as well as
+  "gn gen" with the --check flag) will check this target's sources
+  and headers for proper dependencies.
+
+  When false, the files in this target will be skipped by default.
+  This does not affect other targets that depend on the current target,
+  it just skips checking the includes of the current target's files.
+
+```
+
+### **Example**
+
+```
+  source_set("busted_includes") {
+*    # This target's includes are messed up, exclude it from checking.
+*    check_includes = false
+    ...
+  }
+
+
+```
+## **complete_static_lib**: [boolean] Links all deps into a static library.
+
+```
+  A static library normally doesn't include code from dependencies, but
+  instead forwards the static libraries and source sets in its deps up
+  the dependency chain until a linkable target (an executable or shared
+  library) is reached. The final linkable target only links each static
+  library once, even if it appears more than once in its dependency
+  graph.
+
+  In some cases the static library might be the final desired output.
+  For example, you may be producing a static library for distribution to
+  third parties. In this case, the static library should include code
+  for all dependencies in one complete package. Since GN does not unpack
+  static libraries to forward their contents up the dependency chain,
+  it is an error for complete static libraries to depend on other static
+  libraries.
+
+```
+
+### **Example**
+
+```
+  static_library("foo") {
+    complete_static_lib = true
+    deps = [ "bar" ]
+  }
+
+
+```
+## **configs**: Configs applying to this target.
+
+```
+  A list of config labels.
+
+  The include_dirs, defines, etc. in each config are appended in the
+  order they appear to the compile command for each file in the target.
+  They will appear after the include_dirs, defines, etc. that the target
+  sets directly.
+
+  The build configuration script will generally set up the default
+  configs applying to a given target type (see "set_defaults").
+  When a target is being defined, it can add to or remove from this
+  list.
+
+```
+
+### **Ordering of flags and values**:
+
+```
+  1. Those set on the current target (not in a config).
+  2. Those set on the "configs" on the target in order that the
+     configs appear in the list.
+  3. Those set on the "all_dependent_configs" on the target in order
+     that the configs appear in the list.
+  4. Those set on the "public_configs" on the target in order that
+     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 has "forward_dependent_configs_from",
+     or are public dependencies, they will be applied recursively.
+
+```
+
+### **Example**:
+```
+  static_library("foo") {
+    configs -= "//build:no_rtti"  # Don't use the default RTTI config.
+    configs += ":mysettings"      # Add some of our own settings.
+  }
+
+
+```
+## **data**: Runtime data file dependencies.
+
+```
+  Lists files required to run the given target. These are typically
+  data files.
+
+  Appearing in the "data" section does not imply any special handling
+  such as copying them to the output directory. This is just used for
+  declaring runtime dependencies. There currently isn't a good use for
+  these but it is envisioned that test data can be listed here for use
+  running automated tests.
+
+  See also "gn help inputs" and "gn help data_deps", both of
+  which actually affect the build in concrete ways.
+
+
+```
+## **data_deps**: Non-linked dependencies.
+
+```
+  A list of target labels.
+
+  Specifies dependencies of a target that are not actually linked into
+  the current target. Such dependencies will 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**:
+```
+  executable("foo") {
+    deps = [ "//base" ]
+    data_deps = [ "//plugins:my_runtime_plugin" ]
+  }
+
+
+```
+## **defines**: C preprocessor defines.
+
+```
+  A list of strings
+
+  These strings will be passed to the C/C++ compiler as #defines. The
+  strings may or may not include an "=" to assign a value.
+
+```
+
+### **Ordering of flags and values**:
+
+```
+  1. Those set on the current target (not in a config).
+  2. Those set on the "configs" on the target in order that the
+     configs appear in the list.
+  3. Those set on the "all_dependent_configs" on the target in order
+     that the configs appear in the list.
+  4. Those set on the "public_configs" on the target in order that
+     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 has "forward_dependent_configs_from",
+     or are public dependencies, they will be applied recursively.
+
+```
+
+### **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**:
+```
+  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.
+*    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. Other target types
+  that can't be linked (like actions and groups) listed in "deps" will
+  be treated as "data_deps". Likewise, if the current target isn't
+  linkable, then all deps will be treated as "data_deps".
+
+  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".
+
+
+```
+## **forward_dependent_configs_from**
+
+```
+  A list of target labels.
+
+  Exposes the public_configs from a private dependent target as
+  public_configs of the current one. Each label in this list
+  must also be in the deps.
+
+  Generally you should use public_deps instead of this variable to
+  express the concept of exposing a dependency as part of a target's
+  public API. We're considering removing this variable.
+
+```
+
+### **Discussion**
+
+```
+  Sometimes you depend on a child library that exports some necessary
+  configuration via public_configs. If your target in turn exposes the
+  child library's headers in its public headers, it might mean that
+  targets that depend on you won't work: they'll be seeing the child
+  library's code but not the necessary configuration. This list
+  specifies which of your deps' direct dependent configs to expose as
+  your own.
+
+```
+
+### **Examples**
+
+```
+  If we use a given library "a" from our public headers:
+
+    deps = [ ":a", ":b", ... ]
+    forward_dependent_configs_from = [ ":a" ]
+
+  This example makes a "transparent" target that forwards a dependency
+  to another:
+
+    group("frob") {
+      if (use_system_frob) {
+        deps = ":system_frob"
+      } else {
+        deps = "//third_party/fallback_frob"
+      }
+      forward_dependent_configs_from = 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.
+
+```
+
+### **Ordering of flags and values**:
+
+```
+  1. Those set on the current target (not in a config).
+  2. Those set on the "configs" on the target in order that the
+     configs appear in the list.
+  3. Those set on the "all_dependent_configs" on the target in order
+     that the configs appear in the list.
+  4. Those set on the "public_configs" on the target in order that
+     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 has "forward_dependent_configs_from",
+     or are public dependencies, they will be applied recursively.
+
+```
+
+### **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.
+
+  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.
+
+```
+
+### **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.
+
+```
+
+### **Example**
+
+```
+  action("myscript") {
+    script = "domything.py"
+    inputs = [ "input.data" ]
+  }
+
+
+```
+## **ldflags**: Flags passed to the linker.
+
+```
+  A list of strings.
+
+  These flags are passed on the command-line to the linker and generally
+  specify various linking options. Most targets will not need these and
+  will use "libs" and "lib_dirs" instead.
+
+  ldflags are NOT pushed to dependents, so applying ldflags to source
+  sets or static libraries will be a no-op. If you want to apply ldflags
+  to dependent targets, put them in a config and set it in the
+  all_dependent_configs or public_configs.
+
+
+```
+## **lib_dirs**: Additional library directories.
+
+```
+  A list of directories.
+
+  Specifies additional directories passed to the linker for searching
+  for the required libraries. If an item is not an absolute path, it
+  will be treated as being relative to the current build file.
+
+  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**:
+
+```
+  1. Those set on the current target (not in a config).
+  2. Those set on the "configs" on the target in order that the
+     configs appear in the list.
+  3. Those set on the "all_dependent_configs" on the target in order
+     that the configs appear in the list.
+  4. Those set on the "public_configs" on the target in order that
+     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 has "forward_dependent_configs_from",
+     or are public dependencies, they will be applied recursively.
+
+```
+
+### **Example**:
+```
+  lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ]
+
+
+```
+## **libs**: Additional libraries to link.
+
+```
+  A list of strings.
+
+  These files will be passed to the linker, which will generally search
+  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.
+
+  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**:
+
+```
+  1. Those set on the current target (not in a config).
+  2. Those set on the "configs" on the target in order that the
+     configs appear in the list.
+  3. Those set on the "all_dependent_configs" on the target in order
+     that the configs appear in the list.
+  4. Those set on the "public_configs" on the target in order that
+     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 has "forward_dependent_configs_from",
+     or are public dependencies, they will be applied recursively.
+
+```
+
+### **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).
+
+```
+## **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".
+
+  This variable is valid for all binary output target types.
+
+```
+
+### **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").
+
+  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.
+
+
+```
+## **public**: Declare public header files for a target.
+
+```
+  A list of files that other targets can include. These permissions are
+  checked via the "check" command (see "gn help check").
+
+  If no public files are declared, other targets (assuming they have
+  visibility to depend on this target can include any file in the
+  sources list. If this variable is defined on a target, dependent
+  targets may only include files on this whitelist.
+
+  Header file permissions are also subject to visibility. A target
+  must be visible to another target to include any files from it at all
+  and the public headers indicate which subset of those files are
+  permitted. See "gn help visibility" for more.
+
+  Public files are inherited through the dependency tree. So if there is
+  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**:
+```
+  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.
+
+```
+  A list of config labels.
+
+  Targets directly depending on this one will have the configs listed in
+  this variable added to them. These configs will also apply to the
+  current target.
+
+  This addition happens in a second phase once a target and all of its
+  dependencies have been resolved. Therefore, a target will not see
+  these force-added configs in their "configs" variable while the
+  script is running, and then can not be removed. As a result, this
+  capability should generally only be used to add defines and include
+  directories necessary to compile a target's headers.
+
+  See also "all_dependent_configs".
+
+```
+
+### **Ordering of flags and values**:
+
+```
+  1. Those set on the current target (not in a config).
+  2. Those set on the "configs" on the target in order that the
+     configs appear in the list.
+  3. Those set on the "all_dependent_configs" on the target in order
+     that the configs appear in the list.
+  4. Those set on the "public_configs" on the target in order that
+     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 has "forward_dependent_configs_from",
+     or are public dependencies, 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.
+
+  This has two ramifications:
+
+    - public_configs that are part of the dependency are forwarded
+      to direct dependents (this is the same as using
+      forward_dependent_configs_from).
+
+    - public headers in the dependency are usable by dependents
+      (includes do not require a direct dependency or visibility).
+
+```
+
+### **Discussion**
+
+```
+  Say you have three targets: A -> B -> C. C's visibility may allow
+  B to depend on it but not A. Normally, this would prevent A from
+  including any headers from C, and C's public_configs would apply
+  only to B.
+
+  If B lists C in its public_deps instead of regular deps, A will now
+  inherit C's public_configs and the ability to include C's public
+  headers.
+
+  Generally if you are writing a target B and you include C's headers
+  as part of B's public headers, or targets depending on B should
+  consider B and C to be part of a unit, you should use public_deps
+  instead of deps.
+
+```
+
+### **Example**
+
+```
+*  # This target can include files from "c" but not from
+**  # "super_secret_implementation_details".
+*  executable("a") {
+    deps = [ ":b" ]
+  }
+
+  shared_library("b") {
+    deps = [ ":super_secret_implementation_details" ]
+    public_deps = [ ":c" ]
+  }
+
+
+```
+## **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
+
+```
+  A list of files relative to the current buildfile.
+
+
+```
+## **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
+  that the depenedency is not allowed.
+
+  This feature is intended to prevent accidentally shipping test code
+  in a final product.
+
+```
+
+### **Example**
+
+```
+  source_set("test_support") {
+    testonly = true
+    ...
+  }
+
+
+```
+## **visibility**: A list of labels that can depend on a target.
+
+```
+  A list of labels and label patterns that define which targets can
+  depend on the current one. These permissions are checked via the
+  "check" command (see "gn help check").
+
+  If visibility is not defined, it defaults to public ("*").
+
+  If visibility is defined, only the targets with labels that match it
+  can depend on the current target. The empty list means no targets
+  can depend on the current target.
+
+  Tip: Often you will want the same visibility for all targets in a
+  BUILD file. In this case you can just put the definition at the top,
+  outside of any target, and the targets will inherit that scope and see
+  the definition.
+
+```
+
+### **Patterns**
+
+```
+  See "gn help label_pattern" for more details on what types of
+  patterns are supported. If a toolchain is specified, only targets
+  in that toolchain will be matched. If a toolchain is not specified on
+  a pattern, targets in all toolchains will be matched.
+
+```
+
+### **Examples**
+
+```
+  Only targets in the current buildfile ("private"):
+    visibility = [ ":*" ]
+
+  No targets (used for targets that should be leaf nodes):
+    visibility = []
+
+  Any target ("public", the default):
+    visibility = [ "*" ]
+
+  All targets in the current directory and any subdirectory:
+    visibility = [ "./*" ]
+
+  Any target in "//bar/BUILD.gn":
+    visibility = [ "//bar:*" ]
+
+  Any target in "//bar/" or any subdirectory thereof:
+    visibility = [ "//bar/*" ]
+
+  Just these specific targets:
+    visibility = [ ":mything", "//foo:something_else" ]
+
+  Any target in the current directory and any subdirectory thereof, plus
+  any targets in "//bar/" and any subdirectory thereof.
+    visibility = [ "./*", "//bar/*" ]
+
+
+```
+## **Build Arguments Overview**
+
+```
+  Build arguments are variables passed in from outside of the build
+  that build files can query to determine how the build works.
+
+```
+
+### **How build arguments are set**
+
+```
+  First, system default arguments are set based on the current system.
+  The built-in arguments are:
+   - host_cpu
+   - host_os
+   - current_cpu
+   - current_os
+   - target_cpu
+   - target_os
+
+  If specified, arguments from the --args command line flag are used. If
+  that flag is not specified, args from previous builds in the build
+  directory will be used (this is in the file args.gn in the build
+  directory).
+
+  Last, for targets being compiled with a non-default toolchain, the
+  toolchain overrides are applied. These are specified in the
+  toolchain_args section of a toolchain definition. The use-case for
+  this is that a toolchain may be building code for a different
+  platform, and that it may want to always specify Posix, for example.
+  See "gn help toolchain_args" for more.
+
+  If you specify an override for a build argument that never appears in
+  a "declare_args" call, a nonfatal error will be displayed.
+
+```
+
+### **Examples**
+
+```
+  gn args out/FooBar
+      Create the directory out/FooBar and open an editor. You would type
+      something like this into that file:
+          enable_doom_melon=false
+          os="android"
+
+  gn gen out/FooBar --args="enable_doom_melon=true os=\"android\""
+      This will overwrite the build directory with the given arguments.
+      (Note that the quotes inside the args command will usually need to
+      be escaped for your shell to pass through strings values.)
+
+```
+
+### **How build arguments are used**
+
+```
+  If you want to use an argument, you use declare_args() and specify
+  default values. These default values will apply if none of the steps
+  listed in the "How build arguments are set" section above apply to
+  the given argument, but the defaults will not override any of these.
+
+  Often, the root build config file will declare global arguments that
+  will be passed to all buildfiles. Individual build files can also
+  specify arguments that apply only to those files. It is also useful
+  to specify build args in an "import"-ed file if you want such
+  arguments to apply to multiple buildfiles.
+
+
+```
+## **.gn file**
+
+```
+  When gn starts, it will search the current directory and parent
+  directories for a file called ".gn". This indicates the source root.
+  You can override this detection by using the --root command-line
+  argument
+
+  The .gn file in the source root will be executed. The syntax is the
+  same as a buildfile, but with very limited build setup-specific
+  meaning.
+
+  If you specify --root, by default GN will look for the file .gn in
+  that directory. If you want to specify a different file, you can
+  additionally pass --dotfile:
+
+    gn gen out/Debug --root=/home/build --dotfile=/home/my_gn_file.gn
+
+```
+
+### **Variables**
+
+```
+  buildconfig [required]
+      Label of the build config file. This file will be used to set up
+      the build file execution environment for each toolchain.
+
+  check_targets [optional]
+      A list of labels and label patterns that should be checked when
+      running "gn check" or "gn gen --check". If unspecified, all
+      targets will be checked. If it is the empty list, no targets will
+      be checked.
+
+      The format of this list is identical to that of "visibility"
+      so see "gn help visibility" for examples.
+
+  exec_script_whitelist [optional]
+      A list of .gn/.gni files (not labels) that have permission to call
+      the exec_script function. If this list is defined, calls to
+      exec_script will be checked against this list and GN will fail if
+      the current file isn't in the list.
+
+      This is to allow the use of exec_script to be restricted since
+      is easy to use inappropriately. Wildcards are not supported.
+      Files in the secondary_source tree (if defined) should be
+      referenced by ignoring the secondary tree and naming them as if
+      they are in the main tree.
+
+      If unspecified, the ability to call exec_script is unrestricted.
+
+      Example:
+        exec_script_whitelist = [
+          "//base/BUILD.gn",
+          "//build/my_config.gni",
+        ]
+
+  root [optional]
+      Label of the root build target. The GN build will start by loading
+      the build file containing this target name. This defaults to
+      "//:" which will cause the file //BUILD.gn to be loaded.
+
+  secondary_source [optional]
+      Label of an alternate directory tree to find input files. When
+      searching for a BUILD.gn file (or the build config file discussed
+      above), the file will first be looked for in the source root.
+      If it's not found, the secondary source root will be checked
+      (which would contain a parallel directory hierarchy).
+
+      This behavior is intended to be used when BUILD.gn files can't be
+      checked in to certain source directories for whatever reason.
+
+      The secondary source root must be inside the main source tree.
+
+```
+
+### **Example .gn file contents**
+
+```
+  buildconfig = "//build/config/BUILDCONFIG.gn"
+
+  check_targets = [
+    "//doom_melon/*",  # Check everything in this subtree.
+    "//tools:mind_controlling_ant",  # Check this specific target.
+  ]
+
+  root = "//:root"
+
+  secondary_source = "//build/config/temporary_buildfiles/"
+
+
+```
+## **input_conversion**: Specifies how to transform input to a variable.
+
+```
+  input_conversion is an argument to read_file and exec_script that
+  specifies how the result of the read operation should be converted
+  into a variable.
+
+  "" (the default)
+      Discard the result and return None.
+
+  "list lines"
+      Return the file contents as a list, with a string for each line.
+      The newlines will not be present in the result. The last line may
+      or may not end in a newline.
+
+      After splitting, each individual line will be trimmed of
+      whitespace on both ends.
+
+  "scope"
+      Execute the block as GN code and return a scope with the
+      resulting values in it. If the input was:
+        a = [ "hello.cc", "world.cc" ]
+        b = 26
+      and you read the result into a variable named "val", then you
+      could access contents the "." operator on "val":
+        sources = val.a
+        some_count = val.b
+
+  "string"
+      Return the file contents into a single string.
+
+  "value"
+      Parse the input as if it was a literal rvalue in a buildfile.
+      Examples of typical program output using this mode:
+        [ "foo", "bar" ]     (result will be a list)
+      or
+        "foo bar"            (result will be a string)
+      or
+        5                    (result will be an integer)
+
+      Note that if the input is empty, the result will be a null value
+      which will produce an error if assigned to a variable.
+
+  "trim ..."
+      Prefixing any of the other transformations with the word "trim"
+      will result in whitespace being trimmed from the beginning and end
+      of the result before processing.
+
+      Examples: "trim string" or "trim list lines"
+
+      Note that "trim value" is useless because the value parser skips
+      whitespace anyway.
+
+
+```
+## **Label patterns**
+
+```
+  A label pattern is a way of expressing one or more labels in a portion
+  of the source tree. They are not general regular expressions.
+
+  They can take the following forms only:
+
+   - Explicit (no wildcard):
+       "//foo/bar:baz"
+       ":baz"
+
+   - Wildcard target names:
+       "//foo/bar:*" (all targets in the //foo/bar/BUILD.gn file)
+       ":*"  (all targets in the current build file)
+
+   - Wildcard directory names ("*" is only supported at the end)
+       "*"  (all targets)
+       "//foo/bar/*"  (all targets in any subdir of //foo/bar)
+       "./*"  (all targets in the current build file or sub dirs)
+
+  Any of the above forms can additionally take an explicit toolchain.
+  In this case, the toolchain must be fully qualified (no wildcards
+  are supported in the toolchain name).
+
+    "//foo:bar(//build/toochain:mac)"
+        An explicit target in an explicit toolchain.
+
+    ":*(//build/toolchain/linux:32bit)"
+        All targets in the current build file using the 32-bit Linux
+        toolchain.
+
+    "//foo/*(//build/toolchain:win)"
+        All targets in //foo and any subdirectory using the Windows
+        toolchain.
+
+
+```
+## **How Source Expansion Works**
+
+```
+  Source expansion is used for the action_foreach and copy target types
+  to map source file names to output file names or arguments.
+
+  To perform source expansion in the outputs, GN maps every entry in the
+  sources to every entry in the outputs list, producing the cross
+  product of all combinations, expanding placeholders (see below).
+
+  Source expansion in the args works similarly, but performing the
+  placeholder substitution produces a different set of arguments for
+  each invocation of the script.
+
+  If no placeholders are found, the outputs or args list will be treated
+  as a static list of literal file names that do not depend on the
+  sources.
+
+  See "gn help copy" and "gn help action_foreach" for more on how
+  this is applied.
+
+```
+
+### **Placeholders**
+
+```
+  {{source}}
+      The name of the source file including directory (*). This will
+      generally be used for specifying inputs to a script in the
+      "args" variable.
+        "//foo/bar/baz.txt" => "../../foo/bar/baz.txt"
+
+  {{source_file_part}}
+      The file part of the source including the extension.
+        "//foo/bar/baz.txt" => "baz.txt"
+
+  {{source_name_part}}
+      The filename part of the source file with no directory or
+      extension. This will generally be used for specifying a
+      transformation from a soruce file to a destination file with the
+      same name but different extension.
+        "//foo/bar/baz.txt" => "baz"
+
+  {{source_dir}}
+      The directory (*) containing the source file with no
+      trailing slash.
+        "//foo/bar/baz.txt" => "../../foo/bar"
+
+  {{source_root_relative_dir}}
+      The path to the source file's directory relative to the source
+      root, with no leading "//" or trailing slashes. If the path is
+      system-absolute, (beginning in a single slash) this will just
+      return the path with no trailing slash. This value will always
+      be the same, regardless of whether it appears in the "outputs"
+      or "args" section.
+        "//foo/bar/baz.txt" => "foo/bar"
+
+  {{source_gen_dir}}
+      The generated file directory (*) corresponding to the source
+      file's path. This will be different than the target's generated
+      file directory if the source file is in a different directory
+      than the BUILD.gn file.
+        "//foo/bar/baz.txt" => "gen/foo/bar"
+
+  {{source_out_dir}}
+      The object file directory (*) corresponding to the source file's
+      path, relative to the build directory. this us be different than
+      the target's out directory if the source file is in a different
+      directory than the build.gn file.
+        "//foo/bar/baz.txt" => "obj/foo/bar"
+
+```
+
+### **(*) Note on directories**
+
+```
+  Paths containing directories (except the source_root_relative_dir)
+  will be different depending on what context the expansion is evaluated
+  in. Generally it should "just work" but it means you can't
+  concatenate strings containing these values with reasonable results.
+
+  Details: source expansions can be used in the "outputs" variable,
+  the "args" variable, and in calls to "process_file_template". The
+  "args" are passed to a script which is run from the build directory,
+  so these directories will relative to the build directory for the
+  script to find. In the other cases, the directories will be source-
+  absolute (begin with a "//") because the results of those expansions
+  will be handled by GN internally.
+
+```
+
+### **Examples**
+
+```
+  Non-varying outputs:
+    action("hardcoded_outputs") {
+      sources = [ "input1.idl", "input2.idl" ]
+      outputs = [ "$target_out_dir/output1.dat",
+                  "$target_out_dir/output2.dat" ]
+    }
+  The outputs in this case will be the two literal files given.
+
+  Varying outputs:
+    action_foreach("varying_outputs") {
+      sources = [ "input1.idl", "input2.idl" ]
+      outputs = [ "{{source_gen_dir}}/{{source_name_part}}.h",
+                  "{{source_gen_dir}}/{{source_name_part}}.cc" ]
+    }
+  Performing source expansion will result in the following output names:
+    //out/Debug/obj/mydirectory/input1.h
+    //out/Debug/obj/mydirectory/input1.cc
+    //out/Debug/obj/mydirectory/input2.h
+    //out/Debug/obj/mydirectory/input2.cc
+
+
+```
+**Available global switches
+**  Do "gn help --the_switch_you_want_help_on" for more. Individual
+  commands may take command-specific switches not listed here. See the
+  help on your specific command for more.
+
+```
+
+**  --args**: Specifies build arguments overrides.
+**  --color**: Force colored output.
+**  --dotfile**: override the name of the ".gn" file.
+**  --markdown**: write the output in the Markdown format.
+**  --nocolor**: Force non-colored output.
+**  -q**: Quiet mode. Don't print output on success.
+**  --root**: Explicitly specify source root.
+**  --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.
+
+```