Add more gn documentation

tools/gn/docs/reference.md

 # GN Reference
 
 *This page is automatically generated from* `gn help --markdown all`.
 
 ## **\--args**: Specifies build arguments overrides.
 
 ```
   See "gn help buildargs" for an overview of how build arguments work.
 
   Most operations take a build directory. The build arguments are taken from
@@ skipping 19 matching lines @@
 ```
   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.
 
+
 ```
 ## **\--fail-on-unused-args**: Treat unused build args as fatal errors.
 
 ```
   If you set a value in a build's "gn args" and never use it in the build (in
   a declare_args() block), GN will normally print an error but not fail the
   build.
 
   In many cases engineers would use build args to enable or disable features
   that would sometimes get removed. It would by annoying to block work for
   typically benign problems. In Chrome in particular, flags might be configured
   for build bots in a separate infrastructure repository, or a declare_args
   block might be changed in a third party repository. Treating these errors as
   blocking forced complex multi- way patches to land what would otherwise be
   simple changes.
 
   In some cases, such concerns are not as important, and a mismatch in build
   flags between the invoker of the build and the build files represents a
   critical mismatch that should be immediately fixed. Such users can set this
   flag to force GN to fail in that case.
 
+
 ```
 ## **\--markdown**: Write help 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"
 
+
 ```
 ## **\--runtime-deps-list-file**: Save runtime dependencies for targets in file.
 
 ```
   --runtime-deps-list-file=<filename>
 
   Where <filename> is a text file consisting of the labels, one per line, of
   the targets for which runtime dependencies are desired.
 
   See "gn help runtime_deps" for a description of how runtime dependencies are
@@ skipping 13 matching lines @@
 
   If a source set, action, copy, or group is listed, the runtime deps file will
   correspond to the .stamp file corresponding to that target. This is probably
   not useful; the use-case for this feature is generally executable targets.
 
   The runtime dependency file will list one file per line, with no escaping.
   The files will be relative to the root_build_dir. The first line of the file
   will be the main output file of the target itself (in the above example,
   "bar.so").
 
+
 ```
 ## **\--script-executable**: Set the executable used to execute scripts.
 
 ```
   By default GN searches the PATH for Python to execute scripts in action
   targets and exec_script calls. This flag allows the specification of a
   specific Python executable or potentially a different language
   interpreter.
 
+
 ```
 ## **\--threads**: Specify number of worker threads.
 
 ```
   GN runs many threads to load and run build files. This can make debugging
   challenging. Or you may want to experiment with different values to see how
   it affects performance.
 
   The parameter is the number of worker threads. This does not count the main
   thread (so there are always at least two).
 
 ```
 
 ### **Examples**
 
 ```
   gen gen out/Default --threads=1
 
+
 ```
 ## **\--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 analyze <out_dir> <input_path> <output_path>**
 
 ```
   Analyze which targets are affected by a list of files.
 
   This command takes three arguments:
 
   out_dir is the path to the build directory.
 
@@ skipping 51 matching lines @@
      a string describing the error. This includes cases where the input file is
      not in the right format, or contains invalid targets.
 
   The command returns 1 if it is unable to read the input file or write the
   output file, or if there is something wrong with the build such that gen
   would also fail, and 0 otherwise. In particular, it returns 0 even if the
   "error" key is non-empty and a non-fatal error occurred. In other words, it
   tries really hard to always write something to the output JSON and convey
   errors that way rather than via return codes.
 
+
 ```
 ## **gn args <out_dir> [\--list] [\--short] [\--args]**
 
 ```
   See also "gn help buildargs" for a more high-level overview of how
   build arguments work.
 
 ```
 
 ### **Usage**
@@ skipping 45 matching lines @@
   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's include header checker validates that the includes for C-like source
   files match the build dependency graph.
 
   "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.
@@ skipping 102 matching lines @@
 ```
   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> <label or pattern> [<what to show>] [\--blame] "**
@@ skipping 155 matching lines @@
       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] (\--stdin | <build_file>)**
 
 ```
   Formats .gn file to a standard format.
 
   The contents of some lists ('sources', 'deps', etc.) will be sorted to a
   canonical order. To suppress this, you can add a comment of the form "#
   NOSORT" immediately preceeding the assignment. e.g.
 
@@ skipping 26 matching lines @@
 
 ```
 
 ### **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 [<ide options>] <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:
@@ skipping 96 matching lines @@
 
   --json-ide-script=<path_to_python_script>
       Executes python script after the JSON file is generated. Path can be
       project absolute (//), system absolute (/) or relative, in which case the
       output directory will be base. Path to generated JSON file will be first
       argument when invoking script.
 
   --json-ide-script-args=<argument>
       Optional second argument that will passed to executed script.
 
+
 ```
 ## **gn help <anything>**
 
 ```
   Yo dawg, I heard you like help on your help so I put help on the help in the
   help.
 
   You can also use "all" as the parameter to get all help at once.
 
 ```
 
 ### **Switches**
 
 ```
   --markdown
       Format output in markdown syntax.
 
 ```
 
 ### **Example**
 
 ```
   gn help --markdown all
       Dump all help to stdout in markdown format.
 
+
 ```
 ## **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
@@ skipping 56 matching lines @@
   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 path <out_dir> <target_one> <target_two>**
 
 ```
   Finds paths of dependencies between two targets. Each unique path will be
   printed in one group, and groups will be separate by newlines. The two
   targets can appear in either order (paths will be found going in either
   direction).
 
   By default, a single path will be printed. If there is a path with only
@@ skipping 29 matching lines @@
      Additionally follows data deps. Without this flag, only public and private
      linked deps will be followed. Can't be used with --public.
 
 ```
 
 ### **Example**
 
 ```
   gn path out/Default //base //tools/gn
 
+
 ```
-## **gn refs <out_dir> (<label_pattern>|<label>|<file>|@<response_file>)* [\--all]**
+## **gn refs <out_dir> (<label_pattern>|<label>|<file>|@<response_file>)***
 ```
-        [--all-toolchains] [--as=...] [--testonly=...] [--type=...]
+        [--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
@@ skipping 104 matching lines @@
 
   gn refs out/Debug //base/macros.h //base/at_exit.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 one 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".
 
 ```
 
@@ skipping 69 matching lines @@
 
     # 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".
 
 ```
 
@@ skipping 74 matching lines @@
     # 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");
 
+
 ```
 ## **bundle_data**: [iOS/OS X] Declare a target without output.
 
 ```
   This target type allows to declare data that is required at runtime. It is
   used to inform "create_bundle" targets of the files to copy into generated
   bundle, see "gn help create_bundle" for help.
 
   The target must define a list of files as "sources" and a single "outputs".
   If there are multiple files, source expansions must be used to express the
@@ skipping 37 matching lines @@
       "src/MaterialTypography.bundle/Roboto-Italic.ttf",
       "src/MaterialTypography.bundle/Roboto-Regular.ttf",
       "src/MaterialTypography.bundle/Roboto-Thin.ttf",
     ]
     outputs = [
       "{{bundle_resources_dir}}/MaterialTypography.bundle/"
           "{{source_file_part}}"
     ]
   }
 
+
 ```
 ## **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.
 
@@ skipping 31 matching lines @@
 ```
   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.
 
@@ skipping 19 matching lines @@
 
   # 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}}" ]
   }
 
+
 ```
 ## **create_bundle**: [iOS/OS X] Build an OS X / iOS bundle.
 
 ```
   This target generates an iOS/OS X bundle (which is a directory with a
   well-know structure). This target does not define any sources, instead they
   are computed from all "bundle_data" target this one depends on transitively
   (the recursion stops at "create_bundle" targets).
 
   The "bundle_*_dir" properties must be defined. They will be used for the
@@ skipping 127 matching lines @@
                 "$target_gen_dir/$app_name.xcent", root_build_dir),
             rebase_path(bundle_root_dir, root_build_dir),
           ]
         } else {
           deps += [ ":${app_name}_bundle_executable" ]
         }
       }
     }
   }
 
+
 ```
 ## **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.
@@ skipping 43 matching lines @@
   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
@@ skipping 16 matching lines @@
 
     # 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
@@ skipping 39 matching lines @@
 
 ```
   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,
          asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
          precompiled_header, precompiled_source
   Deps: data_deps, deps, public_deps
   Dependent configs: all_dependent_configs, public_configs
   General: check_includes, configs, data, inputs, output_name,
            output_extension, public, sources, testonly, visibility
 
 
@@ skipping 25 matching lines @@
   mylist = [ "a", "b", "c" ]
   foreach(i, mylist) {
     print(i)
   }
 
   Prints:
   a
   b
   c
 
+
 ```
 ## **forward_variables_from**: Copies variables from a different scope.
 
 ```
   forward_variables_from(from_scope, variable_list_or_star,
                          variable_to_not_forward_list = [])
 
   Copies the given variables from the given scope to the local scope if they
   exist. This is normally used in the context of templates to use the values of
   variables defined in the template invocation to a template-defined target.
@@ skipping 59 matching lines @@
   template("my_ios_test_app") {
     ios_test_app(target_name) {
       forward_variables_from(invoker, "*", ["test_bundle_name"])
       if (!defined(extra_substitutions)) {
         extra_substitutions = []
       }
       extra_substitutions += [ "BUNDLE_ID_TEST_NAME=$test_bundle_name" ]
     }
   }
 
+
 ```
 ## **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.
 
@@ skipping 47 matching lines @@
 
 ### **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.
 
@@ skipping 63 matching lines @@
   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
@@ skipping 40 matching lines @@
   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.
 
 ```
 
 ### **Variables**
+
 ```
   Deps: data_deps, deps, 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
@@ skipping 17 matching lines @@
 ```
 
 ### **Examples**
 
 ```
   import("//build/rules/idl_compilation_rule.gni")
 
   # Looks in the current directory.
   import("my_vars.gni")
 
+
 ```
 ## **loadable_module**: Declare a loadable module target.
 
 ```
   This target type allows you to create an object file that is (and can only
   be) loaded and unloaded at runtime.
 
   A loadable module will be specified on the linker line for targets listing
   the loadable module in its "deps". If you don't want this (if you don't need
   to dynamically load the library at runtime), then you should use a
   "shared_library" target type instead.
 
 ```
 
 ### **Variables**
+
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
          asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
          precompiled_header, precompiled_source
   Deps: data_deps, deps, public_deps
   Dependent configs: all_dependent_configs, public_configs
   General: check_includes, configs, data, inputs, output_name,
            output_extension, public, sources, testonly, visibility
 
 
@@ skipping 30 matching lines @@
     }
   }
 
   toolchain("toolchain") {
     tool("link") {
       command = "..."
       pool = ":link_pool($default_toolchain)")
     }
   }
 
+
 ```
 ## **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.
 
@@ skipping 28 matching lines @@
       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.
@@ skipping 80 matching lines @@
     # 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 "gn help
   toolchain"). This toolchain will be used for all targets unless otherwise
   specified.
 
@@ skipping 14 matching lines @@
 
 ```
   toolchain_label
       Toolchain name.
 
 ```
 
 ### **Example**
 
 ```
-  set_default_toolchain("//build/config/win:vs32")
+  # Set default toolchain only has an effect when run in the context of the
+  # default toolchain. Pick the right one according to the current CPU
+  # architecture.
+  if (target_cpu == "x64") {
+    set_default_toolchain("//toolchains:64")
+  } else if (target_cpu == "x86") {
+    set_default_toolchain("//toolchains:32")
+  }
+
 
 ```
 ## **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.
@@ skipping 17 matching lines @@
   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 will
   do nothing for non-lists.
 
   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
@@ skipping 48 matching lines @@
 
 ### **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" or, on Darwin platforms, use a "loadable_module" target type
   instead.
 
 ```
 
 ### **Variables**
+
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
          asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
          precompiled_header, precompiled_source
   Deps: data_deps, deps, public_deps
   Dependent configs: all_dependent_configs, public_configs
   General: check_includes, configs, data, inputs, output_name,
            output_extension, public, sources, testonly, visibility
 
 
@@ skipping 18 matching lines @@
 
   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,
          asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
          precompiled_header, precompiled_source
   Deps: data_deps, deps, public_deps
   Dependent configs: all_dependent_configs, public_configs
   General: check_includes, configs, data, inputs, output_name,
            output_extension, public, sources, testonly, visibility
 
 
@@ skipping 15 matching lines @@
 ### **Example**
 
 ```
   The code:
     mylist = [1, 2, 3, 4, 5, 6]
     print(split_list(mylist, 3))
 
   Will print:
     [[1, 2], [3, 4], [5, 6]
 
+
 ```
 ## **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.
 
@@ skipping 39 matching lines @@
   if (foo_build_as_shared) {
     my_type = "shared_library"
   } else {
     my_type = "source_set"
   }
 
   target(my_type, "foo") {
     ...
   }
 
+
 ```
 ## **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.
 
@@ skipping 132 matching lines @@
 
   # 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...>
   }
 
@@ skipping 446 matching lines @@
       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.
+  code. The toolchain() function defines these commands.
 
 ```
 
+### **Toolchain overview**
+
+```
+  You can have more than one toolchain in use at once in a build and a target
+  can exist simultaneously in multiple toolchains. A build file is executed
+  once for each toolchain it is referenced in so the GN code can vary all
+  parameters of each target (or which targets exist) on a per-toolchain basis.
+
+  When you have a simple build with only one toolchain, the build config file
+  is loaded only once at the beginning of the build. It must call
+  set_default_toolchain() (see "gn help set_default_toolchain") to tell GN the
+  label of the toolchain definition to use. The "toolchain_args" section of the
+  toolchain definition is ignored.
+
+  When a target has a dependency on a target using different toolchain (see "gn
+  help labels" for how to specify this), GN will start a build using that
+  secondary toolchain to resolve the target. GN will load the build config file
+  with the build arguements overridden as specified in the toolchain_args.
+  Because the default toolchain is already known, calls to
+  set_default_toolchain() are ignored.
+
+  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.
+    3. Loads the destination build file in the context of the configuration file
+       in the previous step.
+
+  The toolchain configuration is two-way. In the default toolchain (i.e. the
+  main build target) the configuration flows from the build config file to the
+  toolchain. The build config file looks at the state of the build (OS type,
+  CPU architecture, etc.) and decides which toolchain to use (via
+  set_default_toolchain()). In secondary toolchains, the configuration flows
+  from the toolchain to the build config file: the "toolchain_args" in the
+  toolchain definition specifies the arguments to re-invoke the 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
     Overrides for build arguments to pass to the toolchain when invoking it.
     This is a variable of type "scope" where the variable names correspond to
@@ skipping 20 matching lines @@
 
     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.
 
 ```
 
-### **Invoking targets in toolchains**
+### **Example of defining a toolchain**
 
 ```
-  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.
-   3. Loads the destination build file in the context of the configuration file
-      in the previous step.
-
-```
-
-### **Example**
-
-```
-  toolchain("plugin_toolchain") {
+  toolchain("32") {
     tool("cc") {
       command = "gcc {{source}}"
       ...
     }
 
     toolchain_args = {
-      is_plugin = true
-      is_32bit = true
-      is_64bit = false
+      use_doom_melon = true  # Doom melon always required for 32-bit builds.
+      current_cpu = "x86"
     }
-  };
+  }
+
+  toolchain("64") {
+    tool("cc") {
+      command = "gcc {{source}}"
+      ...
+    }
+
+    toolchain_args = {
+      # use_doom_melon is not overridden here, it will take the default.
+      current_cpu = "x64"
+    }
+  }
+
+```
+
+### **Example of cross-toolchain dependencies**
+
+```
+  If a 64-bit target wants to depend on a 32-bit binary, it would specify a
+  dependency using data_deps (data deps are like deps that are only needed at
+  runtime and aren't linked, since you can't link a 32-bit and a 64-bit
+  library).
+
+    executable("my_program") {
+      ...
+      if (target_cpu == "x64") {
+        # The 64-bit build needs this 32-bit helper.
+        data_deps = [ ":helper(//toolchains:32)" ]
+      }
+    }
+
+    if (target_cpu == "x86") {
+      # Our helper library is only compiled in 32-bits.
+      shared_library("helper") {
+        ...
+      }
+    }
+
 
 ```
 ## **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.
 
@@ skipping 12 matching lines @@
 
 ### **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
@@ skipping 10 matching lines @@
   "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"
 
+
 ```
 ## **invoker**: [string] The invoking scope inside a template.
 
 ```
   Inside a template invocation, this variable refers to the scope of the
   invoker of the template. Outside of template invocations, this variable is
   undefined.
 
   All of the variables defined inside the template invocation are accessible as
   members of the "invoker" scope. This is the way that templates read values
@@ skipping 13 matching lines @@
     print(invoker.sources)       # Prints [ "a.cc", "b.cc" ]
     print(defined(invoker.foo))  # Prints false.
     print(defined(invoker.bar))  # Prints true.
   }
 
   my_template("doom_melon") {
     sources = [ "a.cc", "b.cc" ]
     bar = 123
   }
 
+
 ```
 ## **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, but not necessarily the current 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
@@ skipping 11 matching lines @@
 
 ### **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_name**: [string] The name of the current target.
 
 ```
   Inside a target or template invocation, this variable refers to the name
   given to the target or template invocation. Outside of these, this variable
   is undefined.
 
   This is most often used in template definitions to name targets defined in
   the template based on the name of the invocation. This is necessary both to
@@ skipping 21 matching lines @@
     print(target_name)    # Prints "space_ray" when invoked below.
 
     executable(target_name + "_impl") {
       print(target_name)  # Prints "space_ray_impl".
     }
   }
 
   my_template("space_ray") {
   }
 
+
 ```
 ## **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"
@@ skipping 23 matching lines @@
 
 ```
   - "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.
 
@@ skipping 96 matching lines @@
   source_set("b") {
     deps = [ ":a_b_shared_deps" ]
     # Sources here can include headers from a despite lack of deps.
     ...
   }
 
   group("a_b_shared_deps") {
     public_deps = [ ":c" ]
   }
 
+
 ```
 ## **arflags**: Arguments passed to static_library archiver.
 
 ```
   A list of flags passed to the archive/lib command that creates static
   libraries.
 
   arflags are NOT pushed to dependents, so applying arflags to source sets or
   any other target type will be a no-op. As with ldflags, you could put the
   arflags in a config and set that as a public or "all dependent" config, but
@@ skipping 26 matching lines @@
 ```
 ## **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".
 
+
 ```
 ## **asmflags**: Flags passed to the assembler.
 
 ```
   A list of strings.
 
   "asmflags" are passed to any invocation of a tool that takes an .asm or .S
   file as input.
 
 ```
@@ skipping 51 matching lines @@
 ```
   executable("doom_melon") {
     deps = [ "//foo:bar" ]
     ...
     assert_no_deps = [
       "//evil/*",  # Don't link any code from the evil directory.
       "//foo:test_support",  # This target is also disallowed.
     ]
   }
 
+
 ```
 ## **bundle_deps_filter**: [label list] A list of labels that are filtered out.
 
 ```
   A list of target labels.
 
   This list contains target label patterns that should be filtered out when
   creating the bundle. Any target matching one of those label will be removed
   from the dependencies of the create_bundle target.
 
@@ skipping 13 matching lines @@
       "//base"
     ]
     bundle_root_dir = "$root_out_dir/today_extension.appex"
     bundle_deps_filter = [
       # The extension uses //base but does not use any function calling into
       # third_party/icu and thus does not need the icudtl.dat file.
       "//third_party/icu:icudata",
     ]
   }
 
-```
-## **bundle_executable_dir**: Expansion of {{bundle_executable_dir}} in create_bundle.
 
 ```
+## **bundle_executable_dir**: Expansion of {{bundle_executable_dir}} in
+```
+                              create_bundle.
+
   A string corresponding to a path in $root_build_dir.
 
   This string is used by the "create_bundle" target to expand the
   {{bundle_executable_dir}} of the "bundle_data" target it depends on. This
   must correspond to a path under "bundle_root_dir".
 
   See "gn help bundle_root_dir" for examples.
 
+
 ```
 ## **bundle_plugins_dir**: Expansion of {{bundle_plugins_dir}} in create_bundle.
 
 ```
   A string corresponding to a path in $root_build_dir.
 
   This string is used by the "create_bundle" target to expand the
   {{bundle_plugins_dir}} of the "bundle_data" target it depends on. This must
   correspond to a path under "bundle_root_dir".
 
   See "gn help bundle_root_dir" for examples.
 
-```
-## **bundle_resources_dir**: Expansion of {{bundle_resources_dir}} in create_bundle.
 
 ```
+## **bundle_resources_dir**: Expansion of {{bundle_resources_dir}} in
+```
+                             create_bundle.
+
   A string corresponding to a path in $root_build_dir.
 
   This string is used by the "create_bundle" target to expand the
   {{bundle_resources_dir}} of the "bundle_data" target it depends on. This must
   correspond to a path under "bundle_root_dir".
 
   See "gn help bundle_root_dir" for examples.
 
+
 ```
 ## **bundle_root_dir**: Expansion of {{bundle_root_dir}} in create_bundle.
 
 ```
   A string corresponding to a path in root_build_dir.
 
   This string is used by the "create_bundle" target to expand the
   {{bundle_root_dir}} of the "bundle_data" target it depends on. This must
   correspond to a path under root_build_dir.
 
 ```
 
 ### **Example**
 
 ```
   bundle_data("info_plist") {
     sources = [ "Info.plist" ]
     outputs = [ "{{bundle_root_dir}}/Info.plist" ]
   }
 
   create_bundle("doom_melon.app") {
     deps = [ ":info_plist" ]
     bundle_root_dir = root_build_dir + "/doom_melon.app/Contents"
     bundle_resources_dir = bundle_root_dir + "/Resources"
     bundle_executable_dir = bundle_root_dir + "/MacOS"
     bundle_plugins_dir = bundle_root_dir + "/PlugIns"
   }
 
+
 ```
 ## **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",
@@ skipping 190 matching lines @@
 
 ### **Example**
 
 ```
   source_set("busted_includes") {
     # This target's includes are messed up, exclude it from checking.
     check_includes = false
     ...
   }
 
+
 ```
 ## **code_signing_args**: [string list] Arguments passed to code signing script.
 
 ```
   For create_bundle targets, code_signing_args is the list of arguments to pass
   to the code signing script. Typically you would use source expansion (see "gn
   help source_expansion") to insert the source file names.
 
   See also "gn help create_bundle".
 
+
 ```
 ## **code_signing_outputs**: [file list] Output files for code signing step.
 
 ```
   Outputs from the code signing step of a create_bundle target. Must refer to
   files in the build directory.
 
   See also "gn help create_bundle".
 
+
 ```
 ## **code_signing_script**: [file name] Script for code signing."
 
 ```
   An absolute or buildfile-relative file name of a Python script to run for a
   create_bundle target to perform code signing step.
 
   See also "gn help create_bundle".
 
+
 ```
 ## **code_signing_sources**: [file list] Sources for code signing step.
 
 ```
   A list of files used as input for code signing script step of a create_bundle
   target. Non-absolute paths will be resolved relative to the current build
   file.
 
   See also "gn help create_bundle".
 
+
 ```
 ## **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.
 
@@ skipping 17 matching lines @@
 ```
 
 ### **Example**
 
 ```
   static_library("foo") {
     complete_static_lib = true
     deps = [ "bar" ]
   }
 
+
 ```
 ## **configs**: Configs applying to this target or config.
 
 ```
   A list of config labels.
 
 ```
 
 ### **Configs on a target**
 
@@ skipping 78 matching lines @@
     cflags = [ ... ]
   }
   config("default_optimization") {
     if (optimize_everything) {
       configs = [ ":super_optimization" ]
     } else {
       configs = [ ":no_optimization" ]
     }
   }
 
+
 ```
 ## **console**: Run this action in the console pool.
 
 ```
   Boolean. Defaults to false.
 
   Actions marked "console = true" will be run in the built-in ninja "console"
   pool. They will have access to real stdin and stdout, and output will not be
   buffered by ninja. This can be useful for long-running actions with progress
   logs, or actions that require user input.
 
   Only one console pool target can run at any one time in Ninja. Refer to the
   Ninja documentation on the console pool for more info.
 
 ```
 
 ### **Example**
 
 ```
   action("long_action_with_progress_logs") {
     console = true
   }
 
+
 ```
 ## **data**: Runtime data file dependencies.
 
 ```
   Lists files or directories required to run the given target. These are
   typically data files or directories of data files. The paths are interpreted
   as being relative to the current build file. Since these are runtime
   dependencies, they do not affect which targets are built or when. To declare
   input files to a script, use "inputs".
 
@@ skipping 10 matching lines @@
   By convention, directories are listed with a trailing slash:
     data = [ "test/data/" ]
   However, no verification is done on these so GN doesn't enforce this. The
   paths are just rebased and passed along when requested.
 
   Note: On iOS and OS X, create_bundle targets will not be recursed into when
   gathering data. See "gn help create_bundle" for details.
 
   See "gn help runtime_deps" for how these are used.
 
+
 ```
 ## **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 be built and will be available at
   runtime.
 
   This is normally used for things like plugins or helper programs that a
   target needs at runtime.
 
   Note: On iOS and OS X, create_bundle targets will not be recursed into when
   gathering data_deps. See "gn help create_bundle" for details.
 
   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.
 
 ```
@@ skipping 15 matching lines @@
      "deps" list. If a dependency is public, 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.
 
   A depfile should be used only when a target depends on files that are not
   already specified by a target's inputs and sources. Likewise, depfiles should
@@ skipping 21 matching lines @@
     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. Private dependencies are
   propagated up the dependency tree and linked to dependant targets, but do not
   grant the ability to include headers from the dependency. Public configs are
   not forwarded.
@@ skipping 15 matching lines @@
   Propagation of all_dependent_configs and public_configs happens independently
   of target type. all_dependent_configs are always propagated across all types
   of targets, and public_configs are always propagated across public deps of
   all types of targets.
 
   Data dependencies are propagated differently. See "gn help data_deps" and
   "gn help runtime_deps".
 
   See also "public_deps".
 
+
 ```
 ## **include_dirs**: Additional include directories.
 
 ```
   A list of source directories.
 
   The directories in this list will be added to the include path for the files
   in the affected target.
 
 ```
@@ skipping 15 matching lines @@
      "deps" list. If a dependency is public, 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.
 
@@ skipping 55 matching lines @@
 ```
 
 ### **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.
 
@@ skipping 61 matching lines @@
   dependencies (as described above) are applied last assuming they
   are not already in the list.
 
 ```
 
 ### **Example**
 
 ```
   lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ]
 
+
 ```
 ## **libs**: Additional libraries to link.
 
 ```
   A list of library names or library paths.
 
   These libraries will be linked into the final binary (executable or shared
   library) containing the current target.
 
   libs and lib_dirs work differently than other flags in two respects.
@@ skipping 57 matching lines @@
 
 ### **Examples**
 
 ```
   On Windows:
     libs = [ "ctl3d.lib" ]
 
   On Linux:
     libs = [ "ld" ]
 
+
 ```
 ## **output_dir**: [directory] Directory to put output file in.
 
 ```
   For library and executable targets, overrides the directory for the final
   output. This must be in the root_build_dir or a child thereof.
 
   This should generally be in the root_out_dir or a subdirectory thereof (the
   root_out_dir will be the same as the root_build_dir for the default
   toolchain, and will be a subdirectory for other toolchains). Not putting the
   output in a subdirectory of root_out_dir can result in collisions between
   different toolchains, so you will need to take steps to ensure that your
   target is only present in one toolchain.
 
   Normally the toolchain specifies the output directory for libraries and
   executables (see "gn help tool"). You will have to consult that for the
   default location. The default location will be used if output_dir is
   undefined or empty.
 
 ```
 
 ### **Example**
 
 ```
   shared_library("doom_melon") {
     output_dir = "$root_out_dir/plugin_libs"
     ...
   }
 
+
 ```
 ## **output_extension**: Value to use for the output's file extension.
 
 ```
   Normally the file extension for a target is based on the target type and the
   operating system, but in rare cases you will need to override the name (for
   example to use "libfreetype.so.6" instead of libfreetype.so on Linux).
 
   This value should not include a leading dot. If undefined, the default
   specified on the tool will be used. If set to the empty string, no output
@@ skipping 18 matching lines @@
 
   # On Windows, generate a "mysettings.cpl" control panel applet. Control panel
   # applets are actually special shared libraries.
   if (is_win) {
     shared_library("mysettings") {
       output_extension = "cpl"
       ...
     }
   }
 
+
 ```
 ## **output_name**: Define a name for the output file other than the default.
 
 ```
   Normally the output name of a target will be based on the target name, so the
   target "//foo/bar:bar_unittests" will generate an output file such as
   "bar_unittests.exe" (using Windows as an example).
 
   Sometimes you will want an alternate name to avoid collisions or if the
   internal name isn't appropriate for public distribution.
 
   The output name should have no extension or prefixes, these will be added
   using the default system rules. For example, on Linux an output name of "foo"
   will produce a shared library "libfoo.so". There is no way to override the
   output prefix of a linker tool on a per- target basis. If you need more
   flexibility, create a copy target to produce the file you want.
 
   This variable is valid for all binary output target types.
 
 ```
 
 ### **Example**
 
 ```
   static_library("doom_melon") {
     output_name = "fluffy_bunny"
   }
 
+
 ```
 ## **output_prefix_override**: Don't use prefix for output name.
 
 ```
   A boolean that overrides the output prefix for a target. Defaults to false.
 
   Some systems use prefixes for the names of the final target output file. The
   normal example is "libfoo.so" on Linux for a target named "foo".
 
   The output prefix for a given target type is specified on the linker tool
   (see "gn help tool"). Sometimes this prefix is undesired.
 
   See also "gn help output_extension".
 
 ```
 
 ### **Example**
 
 ```
   shared_library("doom_melon") {
     # Normally this will produce "libdoom_melon.so" on Linux. Setting this flag
     # will produce "doom_melon.so".
     output_prefix_override = true
     ...
   }
 
+
 ```
 ## **outputs**: Output files for actions and copy targets.
 
 ```
   Outputs is valid for "copy", "action", and "action_foreach" target types and
   indicates the resulting files. Outputs must always refer to files in the
   build directory.
 
   copy
     Copy targets should have exactly one entry in the outputs list. If there is
     exactly one source, this can be a literal file name or a source expansion.
     If there is more than one source, this must contain a source expansion to
     map a single input name to a single output name. See "gn help copy".
 
   action_foreach
     Action_foreach targets must always use source expansions to map input files
     to output files. There can be more than one output, which means that each
     invocation of the script will produce a set of files (presumably based on
     the name of the input file). See "gn help action_foreach".
 
   action
     Action targets (excluding action_foreach) must list literal output file(s)
     with no source expansions. See "gn help action".
 
+
 ```
 ## **precompiled_header**: [string] Header file to precompile.
 
 ```
   Precompiled headers will be used when a target specifies this value, or a
   config applying to this target specifies this value. In addition, the tool
   corresponding to the source files must also specify precompiled headers (see
   "gn help tool"). The tool will also specify what type of precompiled headers
   to use.
 
@@ skipping 48 matching lines @@
 
 
 ```
 ## **precompiled_source**: [file name] Source file to precompile.
 
 ```
   The source file that goes along with the precompiled_header when using
   "msvc"-style precompiled headers. It will be implicitly added to the sources
   of the target. See "gn help precompiled_header".
 
+
 ```
 ## **product_type**: Product type for Xcode projects.
 
 ```
   Correspond to the type of the product of a create_bundle target. Only
   meaningful to Xcode (used as part of the Xcode project generation).
 
   When generating Xcode project files, only create_bundle target with a
   non-empty product_type will have a corresponding target in Xcode project.
 
+
 ```
 ## **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
@@ skipping 17 matching lines @@
 
 ### **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
@@ skipping 70 matching lines @@
   # "super_secret_implementation_details".
   executable("a") {
     deps = [ ":b" ]
   }
 
   shared_library("b") {
     deps = [ ":super_secret_implementation_details" ]
     public_deps = [ ":c" ]
   }
 
+
 ```
 ## **response_file_contents**: Contents of a response file for actions.
 
 ```
   Sometimes the arguments passed to a script can be too long for the system's
   command-line capabilities. This is especially the case on Windows where the
   maximum command-line length is less than 8K. A response file allows you to
   pass an unlimited amount of data to a script in a temporary file for an
   action or action_foreach target.
 
@@ skipping 20 matching lines @@
     # make the paths relative to the script working directory.
     response_file_contents = rebase_path(inputs, root_build_dir)
 
     # The script expects the name of the response file in --file-list.
     args = [
       "--enable-foo",
       "--file-list={{response_file_name}}",
     ]
   }
 
+
 ```
 ## **script**: Script file for actions.
 
 ```
   An absolute or buildfile-relative file name of a Python script to run for a
   action and action_foreach targets (see "gn help action" and "gn help
   action_foreach").
 
+
 ```
 ## **sources**: Source files for a target
 
 ```
   A list of files. Non-absolute paths will be resolved relative to the current
   build file.
 
 ```
 
 ### **Sources for binary targets**
@@ skipping 21 matching lines @@
     The sources are the set of files that the script will be executed over. The
     script will run once per file.
 
   action
     The sources will be treated the same as inputs. See "gn help inputs" for
     more information and usage advice.
 
   copy
     The source are the source files to copy.
 
+
 ```
 ## **testonly**: Declares a target must only be used for testing.
 
 ```
   Boolean. Defaults to false.
 
   When a target is marked "testonly = true", it must only be depended on by
   other test-only targets. Otherwise, GN will issue an error 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 ("*").
 
@@ skipping 38 matching lines @@
   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/*" ]
 
+
 ```
 ## **write_runtime_deps**: Writes the target's runtime_deps to the given path.
 
 ```
   Does not synchronously write the file, but rather schedules it to be written
   at the end of generation.
 
   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.
 
   Path must be within the output directory.
 
   See "gn help runtime_deps" for how the runtime dependencies are computed.
 
   The format of this file will list one file per line with no escaping. The
   files will be relative to the root_build_dir. The first line of the file will
   be the main output file of the target itself. The file contents will be the
   same as requesting the runtime deps be written on the command line (see "gn
   help --runtime-deps-list-file").
 
+
 ```
 ## **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**
@@ skipping 132 matching lines @@
 
   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/"
 
+
+```
+## **Build graph and execution overview**
+
+### **Overall build flow**
+
+```
+  1. Look for ".gn" file (see "gn help dotfile") in the current directory and
+     walk up the directory tree until one is found. Set this directory to be
+     the "source root" and interpret this file to find the name of the build
+     config file.
+
+  2. Execute the build config file identified by .gn to set up the global
+     variables and default toolchain name. Any arguments, variables, defaults,
+     etc. set up in this file will be visible to all files in the build.
+
+  3. Load the //BUILD.gn (in the source root directory).
+
+  4. Recursively evaluate rules and load BUILD.gn in other directories as
+     necessary to resolve dependencies. If a BUILD file isn't found in the
+     specified location, GN will look in the corresponding location inside
+     the secondary_source defined in the dotfile (see "gn help dotfile").
+
+  5. When a target's dependencies are resolved, write out the `.ninja`
+     file to disk.
+
+  6. When all targets are resolved, write out the root build.ninja file.
+
+```
+
+### **Executing target definitions and templates**
+
+```
+  Build files are loaded in parallel. This means it is impossible to
+  interrogate a target from GN code for any information not derivable from its
+  label (see "gn help label"). The exception is the get_target_outputs()
+  function which requires the target being interrogated to have been defined
+  previously in the same file.
+
+  Targets are declared by their type and given a name:
+
+    static_library("my_static_library") {
+      ... target parameter definitions ...
+    }
+
+  There is also a generic "target" function for programatically defined types
+  (see "gn help target"). You can define new types using templates (see "gn
+  help template"). A template defines some custom code that expands to one or
+  more other targets.
+
+  Before executing the code inside the target's { }, the target defaults are
+  applied (see "gn help set_defaults"). It will inject implicit variable
+  definitions that can be overridden by the target code as necessary. Typically
+  this mechanism is used to inject a default set of configs that define the
+  global compiler and linker flags.
+
+```
+
+### **Which targets are built**
+
+```
+  All targets encountered in the default toolchain (see "gn help toolchain")
+  will have build rules generated for them, even if no other targets reference
+  them. Their dependencies must resolve and they will be added to the implicit
+  "all" rule (see "gn help ninja_rules").
+
+  Targets in non-default toolchains will only be generated when they are
+  required (directly or transitively) to build a target in the default
+  toolchain.
+
+  See also "gn help ninja_rules".
+
+```
+
+### **Dependencies**
+
+```
+  The only difference between "public_deps" and "deps" except for pushing
+  configs around the build tree and allowing includes for the purposes of "gn
+  check".
+
+  A target's "data_deps" are guaranteed to be built whenever the target is
+  built, but the ordering is not defined. The meaning of this is dependencies
+  required at runtime. Currently data deps will be complete before the target
+  is linked, but this is not semantically guaranteed and this is undesirable
+  from a build performance perspective. Since we hope to change this in the
+  future, do not rely on this behavior.
+
+
 ```
 ## **Language and grammar for GN build files**
 
 ### **Tokens**
 
 ```
   GN build files are read as sequences of tokens.  While splitting the file
   into tokens, the next token is the longest sequence of characters that form a
   valid token.
 
@@ skipping 214 matching lines @@
     }
 
   Inside such a scope definition can be any GN code including conditionals and
   function calls. After the close of the scope, it will contain all variables
   explicitly set by the code contained inside it. After this, the values can be
   read, modified, or added to:
 
     myvalues.foo += 2
     empty_scope.new_thing = [ 1, 2, 3 ]
 
+
 ```
 ## **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.
 
@@ skipping 33 matching lines @@
   "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):
@@ skipping 16 matching lines @@
     "//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.
 
+
+```
+## **About labels**
+
+```
+  Everything that can participate in the dependency graph (targets, configs,
+  and toolchains) are identified by labels. A common label looks like:
+
+    //base/test:test_support
+
+  This consists of a source-root-absolute path, a colon, and a name. This means
+  to look for the thing named "test_support" in "base/test/BUILD.gn".
+
+  You can also specify system absolute paths if necessary. Typically such
+  paths would be specified via a build arg so the developer can specify where
+  the component is on their system.
+
+    /usr/local/foo:bar    (Posix)
+    /C:/Program Files/MyLibs:bar   (Windows)
+
+```
+
+### **Toolchains**
+
+```
+  A canonical label includes the label of the toolchain being used. Normally,
+  the toolchain label is implicitly inherited from the current execution
+  context, but you can override this to specify cross-toolchain dependencies:
+
+    //base/test:test_support(//build/toolchain/win:msvc)
+
+  Here GN will look for the toolchain definition called "msvc" in the file
+  "//build/toolchain/win" to know how to compile this target.
+
+```
+
+### **Relative labels**
+
+```
+  If you want to refer to something in the same buildfile, you can omit
+  the path name and just start with a colon. This format is recommended for
+  all same-file references.
+
+    :base
+
+  Labels can be specified as being relative to the current directory.
+  Stylistically, we prefer to use absolute paths for all non-file-local
+  references unless a build file needs to be run in different contexts (like a
+  project needs to be both standalone and pulled into other projects in
+  difference places in the directory hierarchy).
+
+    source/plugin:myplugin
+    ../net:url_request
+
+```
+
+### **Implicit names**
+
+```
+  If a name is unspecified, it will inherit the directory name. Stylistically,
+  we prefer to omit the colon and name when possible:
+
+    //net  ->  //net:net
+    //tools/gn  ->  //tools/gn:gn
+
+
+```
+## **Ninja build rules**
+
+### **The "all" and "default" rules**
+
+```
+  All generated targets (see "gn help execution") will be added to an implicit
+  build rule called "all" so "ninja all" will always compile everything. The
+  default rule will be used by Ninja if no specific target is specified (just
+  typing "ninja"). If there is a target named "//:default" it will be the
+  default build rule, otherwise the implicit "all" rule will be used.
+
+```
+
+### **Phony rules**
+
+```
+  GN generates Ninja "phony" rules for targets in the default toolchain.  The
+  phony rules can collide with each other and with the names of generated files
+  so are generated with the following priority:
+
+    1. Actual files generated by the build always take precedence.
+
+    2. Targets in the toplevel //BUILD.gn file.
+
+    3. Targets in toplevel directories matching the names of the directories.
+       So "ninja foo" can be used to compile "//foo:foo". This only applies to
+       the first level of directories since usually these are the most
+       important (so this won't apply to "//foo/bar:bar").
+
+    4. The short names of executables if there is only one executable with that
+       short name. Use "ninja doom_melon" to compile the
+       "//tools/fruit:doom_melon" executable.
+
+    5. The short names of all targets if there is only one target with that
+       short name.
+
+    6. Full label name with no leading slashes. So you can use
+       "ninja tools/fruit:doom_melon" to build "//tools/fruit:doom_melon".
+
+    7. Labels with an implicit name part (when the short names match the
+       directory). So you can use "ninja foo/bar" to compile "//foo/bar:bar".
+
+  These "phony" rules are provided only for running Ninja since this matches
+  people's historical expectations for building. For consistency with the rest
+  of the program, GN introspection commands accept explicit labels.
+
+  To explicitly compile a target in a non-default toolchain, you must give
+  Ninja the exact name of the output file relative to the build directory.
+
+
 ```
 ## **nogncheck**: Skip an include line from checking.
 
 ```
   GN's header checker helps validate that the includes match the build
   dependency graph. Sometimes an include might be conditional or otherwise
   problematic, but you want to specifically allow it. In this case, it can be
   whitelisted.
 
   Include lines containing the substring "nogncheck" will be excluded from
@@ skipping 19 matching lines @@
 
 ```
 
 ### **More information**
 
 ```
   The topic "gn help check" has general information on how checking works and
   advice on fixing problems. Targets can also opt-out of checking, see
   "gn help check_includes".
 
+
 ```
 ## **Runtime dependencies**
 
 ```
   Runtime dependencies of a target are exposed via the "runtime_deps" category
   of "gn desc" (see "gn help desc") or they can be written at build generation
   time via write_runtime_deps(), or --runtime-deps-list-file (see "gn help
   --runtime-deps-list-file").
 
   To a first approximation, the runtime dependencies of a target are the set of
@@ skipping 61 matching lines @@
 
 ```
 
 ### **Multiple outputs**
 
 ```
   Linker tools can specify which of their outputs should be considered when
   computing the runtime deps by setting runtime_outputs. If this is unset on
   the tool, the default will be the first output only.
 
+
 ```
 ## **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).
@@ skipping 91 matching lines @@
       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.
 **  \--fail-on-unused-args**: Treat unused build args as fatal errors.
 **  \--markdown**: Write help output in the Markdown format.
 **  \--nocolor**: Force non-colored output.
 **  -q**: Quiet mode. Don't print output on success.
 **  \--root**: Explicitly specify source root.
 **  \--runtime-deps-list-file**: Save runtime dependencies for targets in file.
 **  \--script-executable**: Set the executable used to execute scripts.
 **  \--threads**: Specify number of worker threads.
 **  \--time**: Outputs a summary of how long everything took.
 **  \--tracelog**: Writes a Chrome-compatible trace log to the given file.
 **  -v**: Verbose logging.
 **  \--version**: Prints the GN version number and exits.
 
 ```