Index: tools/gn/docs/reference.md |
diff --git a/tools/gn/docs/reference.md b/tools/gn/docs/reference.md |
index 3929fc434f65a9ecf887e648bc91b49d7b119c00..9c318b8ecb14fa59f7f45b9a6e9b9b3915eb173f 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) |
- |
``` |