GN: Re-generate reference.md
Necessary because https://codereview.chromium.org/2773043005/
changed the way GN outputs newlines when generating the reference.
BUG=
Review-Url: https://codereview.chromium.org/2790063007
Cr-Original-Commit-Position: refs/heads/master@{#461839}
Cr-Mirrored-From: https://chromium.googlesource.com/chromium/src
Cr-Mirrored-Commit: f6b258ce5b3d4224eafd5fb73ed1b38ebf20df3c
diff --git a/tools/gn/docs/reference.md b/tools/gn/docs/reference.md
index 3929fc4..9c318b8 100644
--- a/tools/gn/docs/reference.md
+++ b/tools/gn/docs/reference.md
@@ -211,15 +211,12 @@
"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.
-
-
```
### <a name="args"></a>**gn args <out_dir> [\--list] [\--short] [\--args]**
```
See also "gn help buildargs" for a more high-level overview of how
build arguments work.
-
```
#### **Usage**
@@ -251,7 +248,6 @@
If --short is specified, only the names and current values will be
printed.
-
```
#### **Examples**
@@ -273,8 +269,6 @@
Prints all arguments with the default values for a build with the
given arguments set (which may affect the values of other
arguments).
-
-
```
### <a name="check"></a>**gn check <out_dir> [<label_pattern>] [\--force]**
@@ -289,7 +283,6 @@
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.
-
```
#### **Command-specific switches**
@@ -298,7 +291,6 @@
--force
Ignores specifications of "check_includes = false" and checks all
target's files that match the target label.
-
```
#### **What gets checked**
@@ -354,7 +346,6 @@
- A target can include headers from a target that depends on it if the
other target is annotated accordingly. See "gn help
allow_circular_includes_from".
-
```
#### **Advice on fixing problems**
@@ -382,7 +373,6 @@
In rare cases it makes sense to list a header in more than one target if it
could be considered conceptually a member of both.
-
```
#### **Examples**
@@ -396,16 +386,12 @@
gn check out/Default "//foo/*
Check only the files in targets in the //foo directory tree.
-
-
```
### <a name="clean"></a>**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.
-
-
```
### <a name="desc"></a>**gn desc <out_dir> <label or pattern> [<what to show>] [\--blame] "**
#### **[\--format=json]**
@@ -417,7 +403,6 @@
The <label or pattern> can be a target label, a config label, or a label
pattern (see "gn help label_pattern"). A label pattern will only match
targets.
-
```
#### **Possibilities for <what to show>**
@@ -458,7 +443,6 @@
The output is a list of file names relative to the build directory. See
"gn help runtime_deps" for how this is computed. This also works with
"--blame" to see the source of the dependency.
-
```
#### **Shared flags**
@@ -474,7 +458,6 @@
--format=json
Format the output as JSON instead of text.
-
```
#### **Target flags**
@@ -485,7 +468,6 @@
cause that target to get the flag. 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).
-
```
#### **Configs**
@@ -496,7 +478,6 @@
configs pushed onto this target via public or "all dependent" configs.
Configs can have child configs. Specifying --tree will show the hierarchy.
-
```
#### **Printing outputs**
@@ -505,7 +486,6 @@
The "outputs" section will list all outputs that apply, including the outputs
computed from the tool definition (eg for "executable", "static_library", ...
targets).
-
```
#### **Printing deps**
@@ -556,7 +536,6 @@
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**
@@ -572,8 +551,6 @@
gn desc out/Debug //base defines --blame
Shows defines set for the //base:base target, annotated by where
each one was set from.
-
-
```
### <a name="format"></a>**gn format [\--dump-tree] (\--stdin | <build_file>)**
@@ -589,7 +566,6 @@
"z.cc",
"a.cc",
]
-
```
#### **Arguments**
@@ -610,7 +586,6 @@
--stdin
Read input from stdin and write to stdout rather than update a file
in-place.
-
```
#### **Examples**
@@ -619,8 +594,6 @@
gn format some\\BUILD.gn
gn format /abspath/some/BUILD.gn
gn format --stdin
-
-
```
### <a name="gen:"></a>**gn gen**: Generate ninja files.
@@ -636,7 +609,6 @@
out/foo
See "gn help switches" for the common command-line switches.
-
```
#### **IDE options**
@@ -661,7 +633,6 @@
generated projects (see "gn help label_pattern"). Only matching targets
and their dependencies will be included in the solution. Only used for
Visual Studio, Xcode and JSON.
-
```
#### **Visual Studio Flags**
@@ -674,7 +645,6 @@
--no-deps
Don't include targets dependencies to the solution. Changes the way how
--filters option works. Only directly matching targets are included.
-
```
#### **Xcode Flags**
@@ -692,7 +662,6 @@
--root-target=<target_name>
Name of the target corresponding to "All" target in Xcode. If unset,
"All" invokes ninja without any target and builds everything.
-
```
#### **QtCreator Flags**
@@ -702,8 +671,6 @@
Name of the root target for which the QtCreator project will be generated
to contain files of it and its dependencies. If unset, the whole build
graph will be emitted.
-
-
```
#### **Eclipse IDE Support**
@@ -716,7 +683,6 @@
for each file individually. Instead, one set of includes/defines is generated
for the entire project. This works fairly well but may still result in a few
indexer issues here and there.
-
```
#### **Generic JSON Output**
@@ -737,8 +703,6 @@
--json-ide-script-args=<argument>
Optional second argument that will passed to executed script.
-
-
```
### <a name="help"></a>**gn help <anything>**
@@ -747,7 +711,6 @@
help.
You can also use "all" as the parameter to get all help at once.
-
```
#### **Switches**
@@ -755,7 +718,6 @@
```
--markdown
Format output in markdown syntax.
-
```
#### **Example**
@@ -763,8 +725,6 @@
```
gn help --markdown all
Dump all help to stdout in markdown format.
-
-
```
### <a name="ls"></a>**gn ls <out_dir> [<label_pattern>] [\--all-toolchains] [\--as=...]**
```
@@ -777,7 +737,6 @@
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**
@@ -813,7 +772,6 @@
source_set|static_library)
Restrict outputs to targets matching the given type. If
unspecified, no filtering will be performed.
-
```
#### **Examples**
@@ -840,8 +798,6 @@
gn ls out/Debug //base --all-toolchains
Lists all variants of the target //base:base (it may be referenced
in multiple toolchains).
-
-
```
### <a name="path"></a>**gn path <out_dir> <target_one> <target_two>**
@@ -856,7 +812,6 @@
shortest path using either public or private dependencies will be printed. If
--with-data is specified, data deps will also be considered. If there are
multiple shortest paths, an arbitrary one will be selected.
-
```
#### **Interesting paths**
@@ -866,7 +821,6 @@
very high level and a common low-level target. To make the output more useful
(and terminate in a reasonable time), GN will not revisit sub-paths
previously known to lead to the target.
-
```
#### **Options**
@@ -883,15 +837,12 @@
--with-data
Additionally follows data deps. Without this flag, only public and private
linked deps will be followed. Can't be used with --public.
-
```
#### **Example**
```
gn path out/Default //base //tools/gn
-
-
```
### <a name="refs"></a>**gn refs <out_dir> (<label_pattern>|<label>|<file>|@<response_file>)***
```
@@ -918,7 +869,6 @@
a path to a file containing a list of labels or file names, one per line.
This allows us to handle long lists of inputs without worrying about
command line limits.
-
```
#### **Options**
@@ -972,8 +922,6 @@
source_set|static_library)
Restrict outputs to targets matching the given type. If
unspecified, no filtering will be performed.
-
-
```
#### **Examples (target input)**
@@ -998,7 +946,6 @@
gn refs out/Debug //base --tree
Print a reverse dependency tree of //base:base
-
```
#### **Examples (file input)**
@@ -1019,8 +966,6 @@
--all --as=output
Display the executable file names of all test executables
potentially affected by a change to the given file.
-
-
```
## <a name="targets"></a>Target declarations
@@ -1030,7 +975,6 @@
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".
-
```
#### **Inputs**
@@ -1060,7 +1004,6 @@
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**
@@ -1074,7 +1017,6 @@
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**
@@ -1083,7 +1025,6 @@
You would generally use |$target_out_dir| or |$target_gen_dir| to
reference the output or generated intermediate file directories,
respectively.
-
```
#### **Variables**
@@ -1092,7 +1033,6 @@
args, console, data, data_deps, depfile, deps, inputs, outputs*,
response_file_contents, script*, sources
* = required
-
```
#### **Example**
@@ -1111,8 +1051,6 @@
args = [ "--out", rebase_path(target_gen_dir, root_build_dir) ] +
rebase_path(sources, root_build_dir)
}
-
-
```
### <a name="action_foreach"></a>**action_foreach**: Declare a target that runs a script over a set of files.
@@ -1120,7 +1058,6 @@
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**
@@ -1148,7 +1085,6 @@
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**
@@ -1159,7 +1095,6 @@
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**
@@ -1168,7 +1103,6 @@
You would generally use |$target_out_dir| or |$target_gen_dir| to
reference the output or generated intermediate file directories,
respectively.
-
```
#### **Variables**
@@ -1177,7 +1111,6 @@
args, console, data, data_deps, depfile, deps, inputs, outputs*,
response_file_contents, script*, sources*
* = required
-
```
#### **Example**
@@ -1206,8 +1139,6 @@
rebase_path(relative_target_gen_dir, root_build_dir) +
"/{{source_name_part}}.h" ]
}
-
-
```
### <a name="bundle_data"></a>**bundle_data**: [iOS/OS X] Declare a target without output.
@@ -1225,7 +1156,6 @@
behind iOS/Mac conditionals.
See "gn help create_bundle" for more information.
-
```
#### **Variables**
@@ -1233,7 +1163,6 @@
```
sources*, outputs*, deps, data_deps, public_deps, visibility
* = required
-
```
#### **Examples**
@@ -1264,8 +1193,6 @@
"{{source_file_part}}"
]
}
-
-
```
### <a name="copy"></a>**copy**: Declare a target that copies files.
@@ -1284,7 +1211,6 @@
mapping from each source file to an output file name using source expansion
(see "gn help source_expansion"). The placeholders will look like
"{{source_name_part}}", for example.
-
```
#### **Examples**
@@ -1304,8 +1230,6 @@
# names in the gen dir. This will just copy each file.
outputs = [ "$target_gen_dir/{{source_file_part}}" ]
}
-
-
```
### <a name="create_bundle"></a>**create_bundle**: [iOS/OS X] Build an OS X / iOS bundle.
@@ -1327,7 +1251,6 @@
contribute to any data or data_deps. Required runtime dependencies should be
placed in the bundle. A create_bundle can declare its own explicit data and
data_deps, however.
-
```
#### **Code signing**
@@ -1346,7 +1269,6 @@
code_signing_args will be passed as is to the script (so path have to be
rebased) and additional inputs may be listed with the variable
code_signing_sources.
-
```
#### **Variables**
@@ -1357,7 +1279,6 @@
visibility, product_type, code_signing_args, code_signing_script,
code_signing_sources, code_signing_outputs
* = required
-
```
#### **Example**
@@ -1452,8 +1373,6 @@
}
}
}
-
-
```
### <a name="executable"></a>**executable**: Declare an executable target.
@@ -1467,8 +1386,6 @@
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, inputs, output_name,
output_extension, public, sources, testonly, visibility
-
-
```
### <a name="group"></a>**group**: Declare a named group of targets.
@@ -1476,7 +1393,6 @@
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**
@@ -1484,7 +1400,6 @@
```
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
-
```
#### **Example**
@@ -1496,8 +1411,6 @@
"//project:unit_tests",
]
}
-
-
```
### <a name="loadable_module"></a>**loadable_module**: Declare a loadable module target.
@@ -1509,7 +1422,6 @@
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**
@@ -1522,8 +1434,6 @@
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, inputs, output_name,
output_extension, public, sources, testonly, visibility
-
-
```
### <a name="shared_library"></a>**shared_library**: Declare a shared library target.
@@ -1533,7 +1443,6 @@
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**
@@ -1546,8 +1455,6 @@
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, inputs, output_name,
output_extension, public, sources, testonly, visibility
-
-
```
### <a name="source_set"></a>**source_set**: Declare a source set target.
@@ -1572,7 +1479,6 @@
"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**
@@ -1585,8 +1491,6 @@
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, inputs, output_name,
output_extension, public, sources, testonly, visibility
-
-
```
### <a name="static_library"></a>**static_library**: Declare a static library target.
@@ -1596,7 +1500,6 @@
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**
@@ -1610,8 +1513,6 @@
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, inputs, output_name,
output_extension, public, sources, testonly, visibility
-
-
```
### <a name="target"></a>**target**: Declare an target with the given programmatic type.
@@ -1630,7 +1531,6 @@
target("source_set", "doom_melon") {
Is equivalent to:
source_set("doom_melon") {
-
```
#### **Example**
@@ -1645,8 +1545,6 @@
target(my_type, "foo") {
...
}
-
-
```
## <a name="functions"></a>Buildfile functions
@@ -1658,7 +1556,6 @@
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**
@@ -1666,8 +1563,6 @@
```
assert(is_win)
assert(defined(sources), "Sources must be defined");
-
-
```
### <a name="config"></a>**config**: Defines a configuration object.
@@ -1688,7 +1583,6 @@
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**
@@ -1697,14 +1591,12 @@
asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
precompiled_header, precompiled_source
Nested configs: configs
-
```
#### **Variables on a target used to apply configs**
```
all_dependent_configs, configs, public_configs
-
```
#### **Example**
@@ -1718,8 +1610,6 @@
executable("mything") {
configs = [ ":myconfig" ]
}
-
-
```
### <a name="declare_args"></a>**declare_args**: Declare build arguments.
@@ -1766,7 +1656,6 @@
# Bar defaults to same user-overridden state as foo.
enable_bar = enable_foo
}
-
```
#### **Example**
@@ -1781,8 +1670,6 @@
gn --args="enable_doom_melon=true enable_teleporter=true"
This also sets the teleporter, but it's already defaulted to on so it will
have no effect.
-
-
```
### <a name="defined"></a>**defined**: Returns whether an identifier is defined.
@@ -1800,7 +1687,6 @@
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**
@@ -1818,8 +1704,6 @@
values = "some default value"
}
}
-
-
```
### <a name="exec_script"></a>**exec_script**: Synchronously run a script and return the output.
@@ -1837,7 +1721,6 @@
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**:
@@ -1865,7 +1748,6 @@
The script itself will be an implicit dependency so you do not need to
list it.
-
```
#### **Example**
@@ -1878,8 +1760,6 @@
# This example just calls the script with no arguments and discards the
# result.
exec_script("//foo/bar/myscript.py")
-
-
```
### <a name="foreach"></a>**foreach**: Iterate over a list.
@@ -1899,7 +1779,6 @@
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**
@@ -1914,8 +1793,6 @@
a
b
c
-
-
```
### <a name="forward_variables_from"></a>**forward_variables_from**: Copies variables from a different scope.
@@ -1950,7 +1827,6 @@
If variables_to_not_forward_list is non-empty, then it must contains a list
of variable names that will not be forwarded. This is mostly useful when
variable_list_or_star has a value of "*".
-
```
#### **Examples**
@@ -1994,8 +1870,6 @@
extra_substitutions += [ "BUNDLE_ID_TEST_NAME=$test_bundle_name" ]
}
}
-
-
```
### <a name="get_label_info"></a>**get_label_info**: Get an attribute from a target's label.
@@ -2007,7 +1881,6 @@
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**
@@ -2051,7 +1924,6 @@
"toolchain"
The label of the toolchain. This will match the value of the
"current_toolchain" variable when inside that target's declaration.
-
```
#### **Examples**
@@ -2062,8 +1934,6 @@
get_label_info("//foo/bar:baz", "gen_dir")
# Returns string "//out/Debug/gen/foo/bar".
-
-
```
### <a name="get_path_info"></a>**get_path_info**: Extract parts of a file or directory name.
@@ -2073,7 +1943,6 @@
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**
@@ -2132,7 +2001,6 @@
If you want to make the path relative to another directory, or to be
system-absolute, see rebase_path().
-
```
#### **Examples**
@@ -2146,8 +2014,6 @@
# Extract the source-absolute directory name,
result = get_path_info(get_path_info(path, "dir"), "abspath"
-
-
```
### <a name="get_target_outputs"></a>**get_target_outputs**: [file list] Get the list of outputs from a target.
@@ -2164,7 +2030,6 @@
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**
@@ -2191,7 +2056,6 @@
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**
@@ -2207,8 +2071,6 @@
source_set("my_lib") {
sources = get_target_outputs(":my_action")
}
-
-
```
### <a name="getenv"></a>**getenv**: Get an environment variable.
@@ -2223,15 +2085,12 @@
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")
-
-
```
### <a name="import"></a>**import**: Import a file into the current scope.
@@ -2258,7 +2117,6 @@
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**
@@ -2268,8 +2126,6 @@
# Looks in the current directory.
import("my_vars.gni")
-
-
```
### <a name="pool"></a>**pool**: Defines a pool object.
@@ -2283,7 +2139,6 @@
explicit toolchain when defining and referencing a pool.
A pool is referenced by its label just like a target.
-
```
#### **Variables**
@@ -2291,7 +2146,6 @@
```
depth*
* = required
-
```
#### **Example**
@@ -2309,8 +2163,6 @@
pool = ":link_pool($default_toolchain)")
}
}
-
-
```
### <a name="print"></a>**print**: Prints to the console.
@@ -2323,7 +2175,6 @@
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**
@@ -2332,8 +2183,6 @@
print("Hello world")
print(sources, deps)
-
-
```
### <a name="process_file_template"></a>**process_file_template**: Do template expansion over a list of files.
@@ -2348,7 +2197,6 @@
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**
@@ -2361,7 +2209,6 @@
The template should contain source expansions to which each name in the
source list is applied. See "gn help source_expansion".
-
```
#### **Example**
@@ -2381,8 +2228,6 @@
"//out/Debug/foo.h"
"//out/Debug/bar.cc"
"//out/Debug/bar.h" ]
-
-
```
### <a name="read_file"></a>**read_file**: Read a file into a variable.
@@ -2391,7 +2236,6 @@
Whitespace will be trimmed from the end of the file. Throws an error if the
file can not be opened.
-
```
#### **Arguments**
@@ -2402,15 +2246,12 @@
input_conversion
Controls how the file is read and parsed. See "gn help input_conversion".
-
```
#### **Example**
```
lines = read_file("foo.txt", "list lines")
-
-
```
### <a name="rebase_path"></a>**rebase_path**: Rebase a file or directory to another location.
@@ -2437,7 +2278,6 @@
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**
@@ -2462,7 +2302,6 @@
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**
@@ -2478,7 +2317,6 @@
(depending on whether the input ends in a slash) to avoid returning empty
strings. This means if you want a root path ("//" or "/") not ending in a
slash, you can add a dot ("//.").
-
```
#### **Example**
@@ -2510,8 +2348,6 @@
rebase_path("relative_path.txt", root_build_dir)
] + rebase_path(sources, root_build_dir)
}
-
-
```
### <a name="set_default_toolchain"></a>**set_default_toolchain**: Sets the default toolchain name.
@@ -2532,7 +2368,6 @@
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**
@@ -2540,7 +2375,6 @@
```
toolchain_label
Toolchain name.
-
```
#### **Example**
@@ -2554,8 +2388,6 @@
} else if (target_cpu == "x86") {
set_default_toolchain("//toolchains:32")
}
-
-
```
### <a name="set_defaults"></a>**set_defaults**: Set default values for a target type.
@@ -2576,7 +2408,6 @@
apply, but there is no way to refer to the previous defaults and modify them
(each call to set_defaults must supply a complete list of all defaults it
wants). If you want to share defaults, store them in a separate variable.
-
```
#### **Example**
@@ -2591,8 +2422,6 @@
# you don't want the default for a particular default:
configs -= [ "//tools/mything:settings" ]
}
-
-
```
### <a name="set_sources_assignment_filter"></a>**set_sources_assignment_filter**: Set a pattern to filter source files.
@@ -2612,7 +2441,6 @@
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**
@@ -2632,7 +2460,6 @@
- "\b" Matches a path boundary. This will match the beginning or end of a
string, or a slash.
-
```
#### **Pattern examples**
@@ -2649,7 +2476,6 @@
"\bwin/*"
Matches "win/foo" and "foo/win/bar.cc" but not "iwin/foo".
-
```
#### **Sources assignment example**
@@ -2660,8 +2486,6 @@
sources = [ "a.cc", "b_win.cc" ]
print(sources)
# Will print [ "a.cc" ]. b_win one was filtered out.
-
-
```
### <a name="split_list"></a>**split_list**: Splits a list into N different sub-lists.
@@ -2674,7 +2498,6 @@
elements in the input, it will be padded with empty lists.
The expected use is to divide source files into smaller uniform chunks.
-
```
#### **Example**
@@ -2686,8 +2509,6 @@
Will print:
[[1, 2], [3, 4], [5, 6]
-
-
```
### <a name="template"></a>**template**: Define a template rule.
@@ -2701,7 +2522,6 @@
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.
-
```
#### **Variables and templates**:
@@ -2733,7 +2553,6 @@
more or possibly all variables in this manner:
forward_variables_from(invoker, ["deps", "public_deps"])
-
```
#### **Target naming**
@@ -2761,7 +2580,6 @@
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**
@@ -2817,7 +2635,6 @@
deps = [ ":$code_gen_target_name" ]
}
}
-
```
#### **Example of invoking the resulting template**
@@ -2839,8 +2656,6 @@
# gen action.
deps = [ ":foo_idl_files" ]
}
-
-
```
### <a name="tool"></a>**tool**: Specify arguments to a toolchain tool.
@@ -2850,7 +2665,6 @@
tool(<tool type>) {
<tool variables...>
}
-
```
#### **Tool types**
@@ -2876,7 +2690,6 @@
Platform specific tools:
"copy_bundle_data": [iOS, OS X] Tool to copy files in a bundle.
"compile_xcassets": [iOS, OS X] Tool to compile asset catalogs.
-
```
#### **Tool variables**
@@ -3079,7 +2892,6 @@
If specified, this list is the subset of the outputs that should be
added to runtime deps (see "gn help runtime_deps"). By default (if
runtime_outputs is empty or unspecified), it will be the link_output.
-
```
#### **Expansions for tool variables**
@@ -3248,7 +3060,6 @@
Expands to the product_type of the bundle that will contain the
compiled asset catalog. Usually corresponds to the product_type
property of the corresponding create_bundle target.
-
```
#### **Separate linking and dependencies for shared libraries**
@@ -3284,7 +3095,6 @@
"{{output_extension}}.TOC"
restat = true
}
-
```
#### **Example**
@@ -3306,15 +3116,12 @@
description = "G++ {{source}}"
}
};
-
-
```
### <a name="toolchain"></a>**toolchain**: Defines a toolchain.
```
A toolchain is a set of commands and build flags used to compile the source
code. The toolchain() function defines these commands.
-
```
#### **Toolchain overview**
@@ -3354,7 +3161,6 @@
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**
@@ -3394,7 +3200,6 @@
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.
-
```
#### **Example of defining a toolchain**
@@ -3423,7 +3228,6 @@
current_cpu = "x64"
}
}
-
```
#### **Example of cross-toolchain dependencies**
@@ -3448,8 +3252,6 @@
...
}
}
-
-
```
### <a name="write_file"></a>**write_file**: Write a file to disk.
@@ -3469,7 +3271,6 @@
TODO(brettw) we probably need an optional third argument to control list
formatting.
-
```
#### **Arguments**
@@ -3480,8 +3281,6 @@
data
The list or string to write.
-
-
```
## <a name="predefined_variables"></a>Built-in predefined variables
@@ -3498,7 +3297,6 @@
the command line if so desired.
See "gn help target_cpu" for a list of common values returned.
-
```
### <a name="current_os"></a>**current_os**: The operating system of the current toolchain.
@@ -3513,8 +3311,6 @@
the command line if so desired.
See "gn help target_os" for a list of common values returned.
-
-
```
### <a name="current_toolchain"></a>**current_toolchain**: Label of the current toolchain.
@@ -3522,7 +3318,6 @@
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**
@@ -3531,16 +3326,12 @@
if (current_toolchain == "//build:64_bit_toolchain") {
executable("output_thats_64_bit_only") {
...
-
-
```
### <a name="default_toolchain"></a>**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").
-
-
```
### <a name="host_cpu"></a>**host_cpu**: The processor architecture that GN is running on.
@@ -3552,7 +3343,6 @@
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**
@@ -3560,8 +3350,6 @@
```
- "x64"
- "x86"
-
-
```
### <a name="host_os"></a>**host_os**: [string] The operating system that GN is running on.
@@ -3571,7 +3359,6 @@
This value should generally be treated as read-only. It, however, is not used
internally by GN for any purpose.
-
```
#### **Some possible values**
@@ -3580,8 +3367,6 @@
- "linux"
- "mac"
- "win"
-
-
```
### <a name="invoker"></a>**invoker**: [string] The invoking scope inside a template.
@@ -3598,7 +3383,6 @@
scope.
See "gn help template" for more examples.
-
```
#### **Example**
@@ -3614,8 +3398,6 @@
sources = [ "a.cc", "b.cc" ]
bar = 123
}
-
-
```
### <a name="python_path"></a>**python_path**: Absolute path of Python.
@@ -3623,8 +3405,6 @@
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.
-
-
```
### <a name="root_build_dir"></a>**root_build_dir**: [string] Directory where build commands are run.
@@ -3634,8 +3414,6 @@
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.
-
-
```
### <a name="root_gen_dir"></a>**root_gen_dir**: Directory for the toolchain's generated files.
@@ -3651,8 +3429,6 @@
See also "target_gen_dir" which is usually a better location for generated
files. It will be inside the root generated dir.
-
-
```
### <a name="root_out_dir"></a>**root_out_dir**: [string] Root directory for toolchain output files.
@@ -3670,7 +3446,6 @@
See also "target_out_dir" which is usually a better location for output
files. It will be inside the root output dir.
-
```
#### **Example**
@@ -3680,8 +3455,6 @@
# Pass the output dir to the script.
args = [ "-o", rebase_path(root_out_dir, root_build_dir) ]
}
-
-
```
### <a name="target_cpu"></a>**target_cpu**: The desired cpu architecture for the build.
@@ -3701,7 +3474,6 @@
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.
-
```
#### **Possible values**
@@ -3712,8 +3484,6 @@
- "arm"
- "arm64"
- "mipsel"
-
-
```
### <a name="target_gen_dir"></a>**target_gen_dir**: Directory for a target's generated files.
@@ -3729,7 +3499,6 @@
build directory.
See also "gn help root_gen_dir".
-
```
#### **Example**
@@ -3739,8 +3508,6 @@
# Pass the generated output dir to the script.
args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]"
}
-
-
```
### <a name="target_name"></a>**target_name**: [string] The name of the current target.
@@ -3761,7 +3528,6 @@
outside of any target definitions.
See "gn help template" for more examples.
-
```
#### **Example**
@@ -3781,8 +3547,6 @@
my_template("space_ray") {
}
-
-
```
### <a name="target_os"></a>**target_os**: The desired operating system for the build.
@@ -3812,7 +3576,6 @@
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.
-
```
#### **Possible values**
@@ -3825,8 +3588,6 @@
- "nacl"
- "mac"
- "win"
-
-
```
### <a name="target_out_dir"></a>**target_out_dir**: [string] Directory for target output files.
@@ -3841,7 +3602,6 @@
directory.
See also "gn help root_out_dir".
-
```
#### **Example**
@@ -3852,8 +3612,6 @@
args = [ "-o", rebase_path(target_out_dir, root_build_dir) ]"
}
-
-
```
## <a name="target_variables"></a>Variables you set in targets
@@ -3874,7 +3632,6 @@
target's headers.
See also "public_configs".
-
```
#### **Ordering of flags and values**
@@ -3893,8 +3650,6 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
-
```
### <a name="allow_circular_includes_from"></a>**allow_circular_includes_from**: Permit includes from deps.
@@ -3908,7 +3663,6 @@
external dependencies depend only on one of the two targets, and to set the
visibility on the other to enforce this. Thus the targets will always be
linked together in any output.
-
```
#### **Details**
@@ -3930,7 +3684,6 @@
allow_circular_includes_from list. Normally includes must follow the
direction of dependencies, this flag allows them to go in the opposite
direction.
-
```
#### **Danger**
@@ -3950,7 +3703,6 @@
(consider putting such things in a shared config they can both reference).
Make sure the dependencies are also the same (you might consider a group to
collect such dependencies they both depend on).
-
```
#### **Example**
@@ -3971,8 +3723,6 @@
group("a_b_shared_deps") {
public_deps = [ ":c" ]
}
-
-
```
### <a name="arflags"></a>**arflags**: Arguments passed to static_library archiver.
@@ -3988,7 +3738,6 @@
to other static libraries. Due to the nature of how arflags are typically
used, you will normally want to apply them directly on static_library targets
themselves.
-
```
#### **Ordering of flags and values**
@@ -4007,8 +3756,6 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
-
```
### <a name="args"></a>**args**: Arguments passed to an action.
@@ -4018,8 +3765,6 @@
source_expansion") to insert the source file names.
See also "gn help action" and "gn help action_foreach".
-
-
```
### <a name="asmflags"></a>**asmflags**: Flags passed to the assembler.
@@ -4028,7 +3773,6 @@
"asmflags" are passed to any invocation of a tool that takes an .asm or .S
file as input.
-
```
#### **Ordering of flags and values**
@@ -4047,8 +3791,6 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
-
```
### <a name="assert_no_deps"></a>**assert_no_deps**: Ensure no deps on these targets.
@@ -4076,7 +3818,6 @@
on a target or set of targets. One efficient way to express this is to create
a group with the assert_no_deps rule on it, and make that group depend on all
targets you want to apply that assertion to.
-
```
#### **Example**
@@ -4090,8 +3831,6 @@
"//foo:test_support", # This target is also disallowed.
]
}
-
-
```
### <a name="bundle_deps_filter"></a>**bundle_deps_filter**: [label list] A list of labels that are filtered out.
@@ -4107,7 +3846,6 @@
bundle and thus do not require a second copy.
See "gn help create_bundle" for more information.
-
```
#### **Example**
@@ -4124,8 +3862,6 @@
"//third_party/icu:icudata",
]
}
-
-
```
### <a name="bundle_executable_dir"></a>**bundle_executable_dir**: Expansion of {{bundle_executable_dir}} in
```
@@ -4138,8 +3874,6 @@
must correspond to a path under "bundle_root_dir".
See "gn help bundle_root_dir" for examples.
-
-
```
### <a name="bundle_plugins_dir"></a>**bundle_plugins_dir**: Expansion of {{bundle_plugins_dir}} in create_bundle.
@@ -4151,8 +3885,6 @@
correspond to a path under "bundle_root_dir".
See "gn help bundle_root_dir" for examples.
-
-
```
### <a name="bundle_resources_dir"></a>**bundle_resources_dir**: Expansion of {{bundle_resources_dir}} in
```
@@ -4165,8 +3897,6 @@
correspond to a path under "bundle_root_dir".
See "gn help bundle_root_dir" for examples.
-
-
```
### <a name="bundle_root_dir"></a>**bundle_root_dir**: Expansion of {{bundle_root_dir}} in create_bundle.
@@ -4176,7 +3906,6 @@
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**
@@ -4194,8 +3923,6 @@
bundle_executable_dir = bundle_root_dir + "/MacOS"
bundle_plugins_dir = bundle_root_dir + "/PlugIns"
}
-
-
```
### <a name="cflags*"></a>**cflags***: Flags passed to the C compiler.
@@ -4211,7 +3938,6 @@
"cflags".
See also "asmflags" for flags for assembly-language files.
-
```
#### **Ordering of flags and values**
@@ -4230,8 +3956,6 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
-
```
### <a name="cflags*"></a>**cflags***: Flags passed to the C compiler.
@@ -4247,7 +3971,6 @@
"cflags".
See also "asmflags" for flags for assembly-language files.
-
```
#### **Ordering of flags and values**
@@ -4266,8 +3989,6 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
-
```
### <a name="cflags*"></a>**cflags***: Flags passed to the C compiler.
@@ -4283,7 +4004,6 @@
"cflags".
See also "asmflags" for flags for assembly-language files.
-
```
#### **Ordering of flags and values**
@@ -4302,8 +4022,6 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
-
```
### <a name="cflags*"></a>**cflags***: Flags passed to the C compiler.
@@ -4319,7 +4037,6 @@
"cflags".
See also "asmflags" for flags for assembly-language files.
-
```
#### **Ordering of flags and values**
@@ -4338,8 +4055,6 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
-
```
### <a name="cflags*"></a>**cflags***: Flags passed to the C compiler.
@@ -4355,7 +4070,6 @@
"cflags".
See also "asmflags" for flags for assembly-language files.
-
```
#### **Ordering of flags and values**
@@ -4374,8 +4088,6 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
-
```
### <a name="check_includes"></a>**check_includes**: [boolean] Controls whether a target's files are checked.
@@ -4394,7 +4106,6 @@
The topic "gn help check" has general information on how checking works and
advice on how to pass a check in problematic cases.
-
```
#### **Example**
@@ -4405,8 +4116,6 @@
check_includes = false
...
}
-
-
```
### <a name="code_signing_args"></a>**code_signing_args**: [string list] Arguments passed to code signing script.
@@ -4416,8 +4125,6 @@
help source_expansion") to insert the source file names.
See also "gn help create_bundle".
-
-
```
### <a name="code_signing_outputs"></a>**code_signing_outputs**: [file list] Output files for code signing step.
@@ -4426,8 +4133,6 @@
files in the build directory.
See also "gn help create_bundle".
-
-
```
### <a name="code_signing_script"></a>**code_signing_script**: [file name] Script for code signing."
@@ -4436,8 +4141,6 @@
create_bundle target to perform code signing step.
See also "gn help create_bundle".
-
-
```
### <a name="code_signing_sources"></a>**code_signing_sources**: [file list] Sources for code signing step.
@@ -4447,8 +4150,6 @@
file.
See also "gn help create_bundle".
-
-
```
### <a name="complete_static_lib"></a>**complete_static_lib**: [boolean] Links all deps into a static library.
@@ -4475,7 +4176,6 @@
In rare cases it makes sense to list a header in more than one target if it
could be considered conceptually a member of both. libraries.
-
```
#### **Example**
@@ -4485,14 +4185,11 @@
complete_static_lib = true
deps = [ "bar" ]
}
-
-
```
### <a name="configs"></a>**configs**: Configs applying to this target or config.
```
A list of config labels.
-
```
#### **Configs on a target**
@@ -4511,7 +4208,6 @@
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.
-
```
#### **Configs on a config**
@@ -4536,7 +4232,6 @@
listed as a sub-config that it is only used in that context. (Note that
it's possible to fix this and de-dupe, but it's not normally relevant and
complicates the implementation.)
-
```
#### **Ordering of flags and values**
@@ -4555,7 +4250,6 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
```
#### **Example**
@@ -4584,8 +4278,6 @@
configs = [ ":no_optimization" ]
}
}
-
-
```
### <a name="console"></a>**console**: Run this action in the console pool.
@@ -4599,7 +4291,6 @@
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**
@@ -4608,8 +4299,6 @@
action("long_action_with_progress_logs") {
console = true
}
-
-
```
### <a name="data"></a>**data**: Runtime data file dependencies.
@@ -4639,8 +4328,6 @@
gathering data. See "gn help create_bundle" for details.
See "gn help runtime_deps" for how these are used.
-
-
```
### <a name="data_deps"></a>**data_deps**: Non-linked dependencies.
@@ -4658,7 +4345,6 @@
gathering data_deps. See "gn help create_bundle" for details.
See also "gn help deps" and "gn help data".
-
```
#### **Example**
@@ -4668,8 +4354,6 @@
deps = [ "//base" ]
data_deps = [ "//plugins:my_runtime_plugin" ]
}
-
-
```
### <a name="defines"></a>**defines**: C preprocessor defines.
@@ -4678,7 +4362,6 @@
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**
@@ -4697,15 +4380,12 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
```
#### **Example**
```
defines = [ "AWESOME_FEATURE", "LOG_LEVEL=3" ]
-
-
```
### <a name="depfile"></a>**depfile**: [string] File name for input dependencies for actions.
@@ -4729,7 +4409,6 @@
Although depfiles are created by an action, they should not be listed in the
action's "outputs" unless another target will use the file as an input.
-
```
#### **Example**
@@ -4746,8 +4425,6 @@
# Say our script uses "-o <d file>" to indicate the depfile.
args = [ "{{source}}", "-o", depfile ]
}
-
-
```
### <a name="deps"></a>**deps**: Private linked dependencies.
@@ -4758,7 +4435,6 @@
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.
-
```
#### **Details of dependency propagation**
@@ -4782,8 +4458,6 @@
"gn help runtime_deps".
See also "public_deps".
-
-
```
### <a name="include_dirs"></a>**include_dirs**: Additional include directories.
@@ -4792,7 +4466,6 @@
The directories in this list will be added to the include path for the files
in the affected target.
-
```
#### **Ordering of flags and values**
@@ -4811,15 +4484,12 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
```
#### **Example**
```
include_dirs = [ "src/include", "//third_party/foo" ]
-
-
```
### <a name="inputs"></a>**inputs**: Additional compile-time dependencies.
@@ -4829,7 +4499,6 @@
any actions.
Inputs are typically only used for action and action_foreach targets.
-
```
#### **Inputs for actions**
@@ -4851,7 +4520,6 @@
executing the script. This is more efficient than doing processing while
running GN to determine the inputs, and is easier to keep in-sync than
hardcoding the list.
-
```
#### **Script input gotchas**
@@ -4869,7 +4537,6 @@
script, or if there are many, create a separate list file that the script
reads. As long as this file is listed in the inputs, the build will detect
when it has changed in any way and the action will re-run.
-
```
#### **Inputs for binary targets**
@@ -4884,7 +4551,6 @@
that changes in any of the inputs will force all sources in the target to be
recompiled. If an input only applies to a subset of source files, you may
want to split those into a separate target to avoid unnecessary recompiles.
-
```
#### **Example**
@@ -4894,8 +4560,6 @@
script = "domything.py"
inputs = [ "input.data" ]
}
-
-
```
### <a name="ldflags"></a>**ldflags**: Flags passed to the linker.
@@ -4910,7 +4574,6 @@
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.
-
```
#### **Ordering of flags and values**
@@ -4929,8 +4592,6 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
-
```
### <a name="lib_dirs"></a>**lib_dirs**: Additional library directories.
@@ -4946,7 +4607,6 @@
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**
@@ -4969,15 +4629,12 @@
For "libs" and "lib_dirs" only, the values propagated from
dependencies (as described above) are applied last assuming they
are not already in the list.
-
```
#### **Example**
```
lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ]
-
-
```
### <a name="libs"></a>**libs**: Additional libraries to link.
@@ -4992,7 +4649,6 @@
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).
-
```
#### **Types of libs**
@@ -5020,7 +4676,6 @@
"-framework" will be prepended instead of the lib_prefix, and the
".framework" suffix will be trimmed. This is to support the way Mac links
framework dependencies.
-
```
#### **Ordering of flags and values**
@@ -5043,7 +4698,6 @@
For "libs" and "lib_dirs" only, the values propagated from
dependencies (as described above) are applied last assuming they
are not already in the list.
-
```
#### **Examples**
@@ -5054,8 +4708,6 @@
On Linux:
libs = [ "ld" ]
-
-
```
### <a name="output_dir"></a>**output_dir**: [directory] Directory to put output file in.
@@ -5074,7 +4726,6 @@
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**
@@ -5084,8 +4735,6 @@
output_dir = "$root_out_dir/plugin_libs"
...
}
-
-
```
### <a name="output_extension"></a>**output_extension**: Value to use for the output's file extension.
@@ -5101,7 +4750,6 @@
The output_extension will be used to set the "{{output_extension}}" expansion
which the linker tool will generally use to specify the output file name. See
"gn help tool".
-
```
#### **Example**
@@ -5123,8 +4771,6 @@
...
}
}
-
-
```
### <a name="output_name"></a>**output_name**: Define a name for the output file other than the default.
@@ -5143,7 +4789,6 @@
flexibility, create a copy target to produce the file you want.
This variable is valid for all binary output target types.
-
```
#### **Example**
@@ -5152,8 +4797,6 @@
static_library("doom_melon") {
output_name = "fluffy_bunny"
}
-
-
```
### <a name="output_prefix_override"></a>**output_prefix_override**: Don't use prefix for output name.
@@ -5167,7 +4810,6 @@
(see "gn help tool"). Sometimes this prefix is undesired.
See also "gn help output_extension".
-
```
#### **Example**
@@ -5179,8 +4821,6 @@
output_prefix_override = true
...
}
-
-
```
### <a name="outputs"></a>**outputs**: Output files for actions and copy targets.
@@ -5204,8 +4844,6 @@
action
Action targets (excluding action_foreach) must list literal output file(s)
with no source expansions. See "gn help action".
-
-
```
### <a name="precompiled_header"></a>**precompiled_header**: [string] Header file to precompile.
@@ -5223,7 +4861,6 @@
If you use both C and C++ sources, the precompiled header and source file
will be compiled once per language. You will want to make sure to wrap C++
includes in __cplusplus #ifdefs so the file will compile in C mode.
-
```
#### **GCC precompiled headers**
@@ -5235,7 +4872,6 @@
The value of "precompiled_header" is not used with GCC-style precompiled
headers.
-
```
#### **MSVC precompiled headers**
@@ -5276,15 +4912,11 @@
executable("doom_melon") {
configs += [ ":use_precompiled_headers" ]
...
-
-
```
### <a name="precompiled_header_type"></a>**precompiled_header_type**: [string] "gcc" or "msvc".
```
See "gn help precompiled_header".
-
-
```
### <a name="precompiled_source"></a>**precompiled_source**: [file name] Source file to precompile.
@@ -5292,8 +4924,6 @@
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".
-
-
```
### <a name="product_type"></a>**product_type**: Product type for Xcode projects.
@@ -5303,8 +4933,6 @@
When generating Xcode project files, only create_bundle target with a
non-empty product_type will have a corresponding target in Xcode project.
-
-
```
### <a name="public"></a>**public**: Declare public header files for a target.
@@ -5330,7 +4958,6 @@
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**
@@ -5341,8 +4968,6 @@
No files are public (no targets may include headers from this one):
public = []
-
-
```
### <a name="public_configs"></a>**public_configs**: Configs to be applied on dependents.
@@ -5360,7 +4985,6 @@
target's headers.
See also "all_dependent_configs".
-
```
#### **Ordering of flags and values**
@@ -5379,8 +5003,6 @@
6. public_configs pulled from dependencies, in the order of the
"deps" list. If a dependency is public, they will be applied
recursively.
-
-
```
### <a name="public_deps"></a>**public_deps**: Declare public dependencies.
@@ -5400,7 +5022,6 @@
- If the current target is a shared library, other shared libraries that it
publicly depends on (directly or indirectly) are propagated up the
dependency tree to dependents for linking.
-
```
#### **Discussion**
@@ -5416,7 +5037,6 @@
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**
@@ -5432,8 +5052,6 @@
deps = [ ":super_secret_implementation_details" ]
public_deps = [ ":c" ]
}
-
-
```
### <a name="response_file_contents"></a>**response_file_contents**: Contents of a response file for actions.
@@ -5453,7 +5071,6 @@
The response file contents will always be quoted and escaped according to
Unix shell rules. To parse the response file, the Python script should use
"shlex.split(file_contents)".
-
```
#### **Example**
@@ -5473,8 +5090,6 @@
"--file-list={{response_file_name}}",
]
}
-
-
```
### <a name="script"></a>**script**: Script file for actions.
@@ -5482,15 +5097,12 @@
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").
-
-
```
### <a name="sources"></a>**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**
@@ -5508,7 +5120,6 @@
and they do not cross dependency boundaries (so specifying a .def file in a
static library or source set will have no effect on the executable or shared
library they're linked into).
-
```
#### **Sources for non-binary targets**
@@ -5524,8 +5135,6 @@
copy
The source are the source files to copy.
-
-
```
### <a name="testonly"></a>**testonly**: Declares a target must only be used for testing.
@@ -5538,7 +5147,6 @@
This feature is intended to prevent accidentally shipping test code in a
final product.
-
```
#### **Example**
@@ -5548,8 +5156,6 @@
testonly = true
...
}
-
-
```
### <a name="visibility"></a>**visibility**: A list of labels that can depend on a target.
@@ -5567,7 +5173,6 @@
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**
@@ -5577,7 +5182,6 @@
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**
@@ -5607,8 +5211,6 @@
Any target in the current directory and any subdirectory thereof, plus
any targets in "//bar/" and any subdirectory thereof.
visibility = [ "./*", "//bar/*" ]
-
-
```
### <a name="write_runtime_deps"></a>**write_runtime_deps**: Writes the target's runtime_deps to the given path.
@@ -5629,8 +5231,6 @@
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").
-
-
```
## <a name="other"></a>Other help topics
@@ -5639,7 +5239,6 @@
```
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**
@@ -5669,7 +5268,6 @@
If you specify an override for a build argument that never appears in a
"declare_args" call, a nonfatal error will be displayed.
-
```
#### **Examples**
@@ -5685,7 +5283,6 @@
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**
@@ -5700,8 +5297,6 @@
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.
-
-
```
### <a name="dotfile"></a>**.gn file**
@@ -5718,7 +5313,6 @@
--dotfile:
gn gen out/Debug --root=/home/build --dotfile=/home/my_gn_file.gn
-
```
#### **Variables**
@@ -5784,7 +5378,6 @@
This is intended to be used when subprojects declare arguments with
default values that need to be changed for whatever reason.
-
```
#### **Example .gn file contents**
@@ -5806,8 +5399,6 @@
is_debug = false
is_component_build = false
}
-
-
```
### <a name="execution"></a>**Build graph and execution overview**
@@ -5834,7 +5425,6 @@
file to disk.
6. When all targets are resolved, write out the root build.ninja file.
-
```
#### **Executing target definitions and templates**
@@ -5862,7 +5452,6 @@
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**
@@ -5878,7 +5467,6 @@
toolchain.
See also "gn help ninja_rules".
-
```
#### **Dependencies**
@@ -5894,8 +5482,6 @@
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.
-
-
```
### <a name="grammar"></a>**Language and grammar for GN build files**
@@ -5905,7 +5491,6 @@
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.
-
```
#### **White space and comments**
@@ -5918,7 +5503,6 @@
White space and comments are ignored except that they may separate tokens
that would otherwise combine into a single token.
-
```
#### **Identifiers**
@@ -5929,7 +5513,6 @@
identifier = letter { letter | digit } .
letter = "A" ... "Z" | "a" ... "z" | "_" .
digit = "0" ... "9" .
-
```
#### **Keywords**
@@ -5938,7 +5521,6 @@
The following keywords are reserved and may not be used as identifiers:
else false if true
-
```
#### **Integer literals**
@@ -5949,7 +5531,6 @@
integer = [ "-" ] digit { digit } .
Leading zeros and negative zero are disallowed.
-
```
#### **String literals**
@@ -5984,7 +5565,6 @@
"$var_one/$var_two"
Use the "${var_one}" format to be explicitly deliniate the variable for
otherwise-ambiguous cases.
-
```
#### **Punctuation**
@@ -5996,7 +5576,6 @@
- -= < <= [ ]
! = > >= { }
&& || . ,
-
```
#### **Grammar**
@@ -6034,7 +5613,6 @@
| "||" . // lowest priority
All binary operators are left-associative.
-
```
#### **Types**
@@ -6057,7 +5635,6 @@
- Scopes: Scopes are like dictionaries that use variable names for keys. See
"Scopes" below for more.
-
```
#### **Lists**
@@ -6094,7 +5671,6 @@
When assigning to a list named 'sources' using '=' or '+=', list items may be
automatically filtered out. See "gn help set_sources_assignment_filter" for
more.
-
```
#### **Scopes**
@@ -6129,8 +5705,6 @@
myvalues.foo += 2
empty_scope.new_thing = [ 1, 2, 3 ]
-
-
```
### <a name="input_conversion"></a>**input_conversion**: Specifies how to transform input to a variable.
@@ -6183,8 +5757,6 @@
Note that "trim value" is useless because the value parser skips
whitespace anyway.
-
-
```
### <a name="label_pattern"></a>**Label patterns**
@@ -6220,8 +5792,6 @@
"//foo/*(//build/toolchain:win)"
All targets in //foo and any subdirectory using the Windows
toolchain.
-
-
```
### <a name="labels"></a>**About labels**
@@ -6240,7 +5810,6 @@
/usr/local/foo:bar (Posix)
/C:/Program Files/MyLibs:bar (Windows)
-
```
#### **Toolchains**
@@ -6254,7 +5823,6 @@
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**
@@ -6274,7 +5842,6 @@
source/plugin:myplugin
../net:url_request
-
```
#### **Implicit names**
@@ -6285,8 +5852,6 @@
//net -> //net:net
//tools/gn -> //tools/gn:gn
-
-
```
### <a name="ninja_rules"></a>**Ninja build rules**
@@ -6298,7 +5863,6 @@
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**
@@ -6336,8 +5900,6 @@
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.
-
-
```
### <a name="nogncheck"></a>**nogncheck**: Skip an include line from checking.
@@ -6367,7 +5929,6 @@
But GN's header checker does not understand preprocessor directives, won't
know it matches the build dependencies, and will flag this include as
incorrect when the condition is false.
-
```
#### **More information**
@@ -6376,8 +5937,6 @@
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".
-
-
```
### <a name="runtime_deps"></a>**Runtime dependencies**
@@ -6391,7 +5950,6 @@
"data" files, data directories, and the shared libraries from all transitive
dependencies. Executables, shared libraries, and loadable modules are
considered runtime dependencies of themselves.
-
```
#### **Executables**
@@ -6401,7 +5959,6 @@
not considered unless that executable is listed in "data_deps". Otherwise, GN
assumes that the executable (and everything it requires) is a build-time
dependency only.
-
```
#### **Actions and copies**
@@ -6437,7 +5994,6 @@
list of files required at runtime).
- Split B into run-time and build-time versions with the appropriate "deps"
for each.
-
```
#### **Static libraries and source sets**
@@ -6449,7 +6005,6 @@
manually compute the .a/.lib file name for the current platform and list it
in the "data" list of a target (possibly on the static library target
itself).
-
```
#### **Multiple outputs**
@@ -6458,8 +6013,6 @@
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.
-
-
```
### <a name="source_expansion"></a>**How Source Expansion Works**
@@ -6480,7 +6033,6 @@
See "gn help copy" and "gn help action_foreach" for more on how this is
applied.
-
```
#### **Placeholders**
@@ -6535,7 +6087,6 @@
output directory. This can only be used in actions and it is an error to
use in process_file_template where there is no "target".
"//foo/bar/baz.txt" => "baz.txt"
-
```
#### **(*) Note on directories**
@@ -6552,7 +6103,6 @@
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**
@@ -6577,8 +6127,6 @@
//out/Debug/obj/mydirectory/input1.cc
//out/Debug/obj/mydirectory/input2.h
//out/Debug/obj/mydirectory/input2.cc
-
-
```
## <a name="switches"></a>Command Line Switches
@@ -6588,7 +6136,6 @@
help on your specific command for more.
```
-
* [--args: Specifies build arguments overrides.](#--args)
* [--color: Force colored output.](#--color)
* [--dotfile: Override the name of the ".gn" file.](#--dotfile)
@@ -6604,6 +6151,5 @@
* [--tracelog: Writes a Chrome-compatible trace log to the given file.](#--tracelog)
* [-v: Verbose logging.](#-v)
* [--version: Prints the GN version number and exits.](#--version)
-
```
