admin管理员组文章数量:1622289
GN Reference
This page is automatically generated from gn help --markdown all
.
–args: Specifies build arguments overrides.
See "gn help buildargs" for an overview of how build arguments work.
Most operations take a build directory. The build arguments are taken
from the previous build done in that directory. If a command specifies
--args, it will override the previous arguments stored in the build
directory, and use the specified ones.
The args specified will be saved to the build directory for subsequent
commands. Specifying --args="" will clear all build arguments.
Formatting
The value of the switch is interpreted in GN syntax. For typical usage
of string arguments, you will need to be careful about escaping of
quotes.
Examples
gn gen out/Default --args="foo=\"bar\""
gn gen out/Default --args='foo="bar" enable=true blah=7'
gn check out/Default --args=""
Clears existing build args from the directory.
gn desc out/Default --args="some_list=[1, false, \"foo\"]"
–[no]color: Forces colored output on or off.
Normally GN will try to detect whether it is outputting to a terminal
and will enable or disable color accordingly. Use of these switches
will override the default.
Examples
gn gen out/Default --color
gn gen out/Default --nocolor
–dotfile: Override the name of the “.gn” file.
Normally GN loads the ".gn"file from the source root for some basic
configuration (see "gn help dotfile"). This flag allows you to
use a different file.
Note that this interacts with "--root" in a possibly incorrect way.
It would be nice to test the edge cases and document or fix.
–markdown: write the output in the Markdown format.
–[no]color: Forces colored output on or off.
Normally GN will try to detect whether it is outputting to a terminal
and will enable or disable color accordingly. Use of these switches
will override the default.
Examples
gn gen out/Default --color
gn gen out/Default --nocolor
-q: Quiet mode. Don’t print output on success.
This is useful when running as a part of another script.
–root: Explicitly specify source root.
Normally GN will look up in the directory tree from the current
directory to find a ".gn" file. The source root directory specifies
the meaning of "//" beginning with paths, and the BUILD.gn file
in that directory will be the first thing loaded.
Specifying --root allows GN to do builds in a specific directory
regardless of the current directory.
Examples
gn gen //out/Default --root=/home/baracko/src
gn desc //out/Default --root="C:\Users\BObama\My Documents\foo"
–runtime-deps-list-file: Save runtime dependencies for targets in file.
--runtime-deps-list-file=<filename>
Where <filename> is a text file consisting of the labels, one per
line, of the targets for which runtime dependencies are desired.
See "gn help runtime_deps" for a description of how runtime
dependencies are computed.
Runtime deps output file
For each target requested, GN will write a separate runtime dependency
file. The runtime dependency file will be in the output directory
alongside the output file of the target, with a ".runtime_deps"
extension. For example, if the target "//foo:bar" is listed in the
input file, and that target produces an output file "bar.so", GN
will create a file "bar.so.runtime_deps" in the build directory.
If a source set, action, copy, or group is listed, the runtime deps
file will correspond to the .stamp file corresponding to that target.
This is probably not useful; the use-case for this feature is
generally executable targets.
The runtime dependency file will list one file per line, with no
escaping. The files will be relative to the root_build_dir. The first
line of the file will be the main output file of the target itself
(in the above example, "bar.so").
–time: Outputs a summary of how long everything took.
Hopefully self-explanatory.
Examples
gn gen out/Default --time
–tracelog: Writes a Chrome-compatible trace log to the given file.
The trace log will show file loads, executions, scripts, and writes.
This allows performance analysis of the generation step.
To view the trace, open Chrome and navigate to "chrome://tracing/",
then press "Load" and specify the file you passed to this parameter.
Examples
gn gen out/Default --tracelog=mytrace.trace
-v: Verbose logging.
This will spew logging events to the console for debugging issues.
Good luck!
gn args <out_dir> [–list] [–short] [–args]
See also "gn help buildargs" for a more high-level overview of how
build arguments work.
Usage
gn args <out_dir>
Open the arguments for the given build directory in an editor
(as specified by the EDITOR environment variable). If the given
build directory doesn't exist, it will be created and an empty
args file will be opened in the editor. You would type something
like this into that file:
enable_doom_melon=false
os="android"
Note: you can edit the build args manually by editing the file
"args.gn" in the build directory and then running
"gn gen <out_dir>".
gn args <out_dir> --list[=<exact_arg>] [--short]
Lists all build arguments available in the current configuration,
or, if an exact_arg is specified for the list flag, just that one
build argument.
The output will list the declaration location, default value, and
comment preceeding the declaration. If --short is specified,
only the names and values will be printed.
If the out_dir is specified, the build configuration will be
taken from that build directory. The reason this is needed is that
the definition of some arguments is dependent on the build
configuration, so setting some values might add, remove, or change
the default values for other arguments. Specifying your exact
configuration allows the proper arguments to be displayed.
Instead of specifying the out_dir, you can also use the
command-line flag to specify the build configuration:
--args=<exact list of args to use>
Examples
gn args out/Debug
Opens an editor with the args for out/Debug.
gn args out/Debug --list --short
Prints all arguments with their default values for the out/Debug
build.
gn args out/Debug --list=target_cpu
Prints information about the "target_cpu" argument for the out/Debug
build.
gn args --list --args="os=\"android\" enable_doom_melon=true"
Prints all arguments with the default values for a build with the
given arguments set (which may affect the values of other
arguments).
gn check <out_dir> [<label_pattern>] [–force]
"gn check" is the same thing as "gn gen" with the "--check" flag
except that this command does not write out any build files. It's
intended to be an easy way to manually trigger include file checking.
The <label_pattern> can take exact labels or patterns that match more
than one (although not general regular expressions). If specified,
only those matching targets will be checked. See
"gn help label_pattern" for details.
The .gn file may specify a list of targets to be checked. Only these
targets will be checked if no label_pattern is specified on the
command line. Otherwise, the command-line list is used instead. See
"gn help dotfile".
Command-specific switches
--force
Ignores specifications of "check_includes = false" and checks
all target's files that match the target label.
Examples
gn check out/Debug
Check everything.
gn check out/Default //foo:bar
Check only the files in the //foo:bar target.
gn check out/Default "//foo/*
Check only the files in targets in the //foo directory tree.
gn clean <out_dir>
Deletes the contents of the output directory except for args.gn and
creates a Ninja build environment sufficient to regenerate the build.
gn desc <out_dir> [] [–blame]
Displays information about a given labeled target for the given build.
The build parameters will be taken for the build in the given
<out_dir>.
Possibilities for
(If unspecified an overall summary will be displayed.)
sources
Source files.
inputs
Additional input dependencies.
public
Public header files.
check_includes
Whether "gn check" checks this target for include usage.
allow_circular_includes_from
Permit includes from these targets.
visibility
Prints which targets can depend on this one.
testonly
Whether this target may only be used in tests.
configs
Shows configs applied to the given target, sorted in the order
they're specified. This includes both configs specified in the
"configs" variable, as well as configs pushed onto this target
via dependencies specifying "all" or "direct" dependent
configs.
deps
Show immediate or recursive dependencies. See below for flags that
control deps printing.
public_configs
all_dependent_configs
Shows the labels of configs applied to targets that depend on this
one (either directly or all of them).
forward_dependent_configs_from
Shows the labels of dependencies for which dependent configs will
be pushed to targets depending on the current one.
script
args
depfile
Actions only. The script and related values.
outputs
Outputs for script and copy target types.
defines [--blame]
include_dirs [--blame]
cflags [--blame]
cflags_cc [--blame]
cflags_cxx [--blame]
ldflags [--blame]
lib_dirs
libs
Shows the given values taken from the target and all configs
applying. See "--blame" below.
runtime_deps
Compute all runtime deps for the given target. This is a
computed list and does not correspond to any GN variable, unlike
most other values here.
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
--blame
Used with any value specified by a config, this will name
the config that specified the value. This doesn't currently work
for libs and lib_dirs because those are inherited and are more
complicated to figure out the blame (patches welcome).
Flags that control how deps are printed
--all
Collects all recursive dependencies and prints a sorted flat list.
Also usable with --tree (see below).
--as=(buildfile|label|output)
How to print targets.
buildfile
Prints the build files where the given target was declared as
file names.
label (default)
Prints the label of the target.
output
Prints the first output file for the target relative to the
current directory.
--testonly=(true|false)
Restrict outputs to targets with the testonly flag set
accordingly. When unspecified, the target's testonly flags are
ignored.
--tree
Print a dependency tree. By default, duplicates will be elided
with "..." but when --all and -tree are used together, no
eliding will be performed.
The "deps", "public_deps", and "data_deps" will all be
included in the tree.
Tree output can not be used with the filtering or output flags:
--as, --type, --testonly.
--type=(action|copy|executable|group|shared_library|source_set|
static_library)
Restrict outputs to targets matching the given type. If
unspecified, no filtering will be performed.
Note
This command will show the full name of directories and source files,
but when directories and source paths are written to the build file,
they will be adjusted to be relative to the build directory. So the
values for paths displayed by this command won't match (but should
mean the same thing).
Examples
gn desc out/Debug //base:base
Summarizes the given target.
gn desc out/Foo :base_unittests deps --tree
Shows a dependency tree of the "base_unittests" project in
the current directory.
gn desc out/Debug //base defines --blame
Shows defines set for the //base:base target, annotated by where
each one was set from.
gn format [–dump-tree] [–in-place] [–stdin] BUILD.gn
Formats .gn file to a standard format.
Arguments
--dry-run
Does not change or output anything, but sets the process exit code
based on whether output would be different than what's on disk.
This is useful for presubmit/lint-type checks.
- Exit code 0: successful format, matches on disk.
- Exit code 1: general failure (parse error, etc.)
- Exit code 2: successful format, but differs from on disk.
--dump-tree
For debugging only, dumps the parse tree.
--in-place
Instead of writing the formatted file to stdout, replace the input
file with the formatted output. If no reformatting is required,
the input file will not be touched, and nothing printed.
--stdin
Read input from stdin (and write to stdout). Not compatible with
--in-place of course.
Examples
gn format //some/BUILD.gn
gn format some\BUILD.gn
gn format /abspath/some/BUILD.gn
gn format --stdin
gn gen: Generate ninja files.
gn gen <out_dir>
Generates ninja files from the current tree and puts them in the given
output directory.
The output directory can be a source-repo-absolute path name such as:
//out/foo
Or it can be a directory relative to the current directory such as:
out/foo
See "gn help" for the common command-line switches.
gn help
Yo dawg, I heard you like help on your help so I put help on the help
in the help.
gn ls <out_dir> [<label_pattern>] [–all-toolchains] [–as=…]
[--type=...] [--testonly=...]
Lists all targets matching the given pattern for the given build
directory. By default, only targets in the default toolchain will
be matched unless a toolchain is explicitly supplied.
If the label pattern is unspecified, list all targets. The label
pattern is not a general regular expression (see
"gn help label_pattern"). If you need more complex expressions,
pipe the result through grep.
Options
--as=(buildfile|label|output)
How to print targets.
buildfile
Prints the build files where the given target was declared as
file names.
label (default)
Prints the label of the target.
output
Prints the first output file for the target relative to the
current directory.
--all-toolchains
Matches all toolchains. When set, if the label pattern does not
specify an explicit toolchain, labels from all toolchains will be
matched. When unset, only targets in the default toolchain will
be matched unless an explicit toolchain in the label is set.
--testonly=(true|false)
Restrict outputs to targets with the testonly flag set
accordingly. When unspecified, the target's testonly flags are
ignored.
--type=(action|copy|executable|group|shared_library|source_set|
static_library)
Restrict outputs to targets matching the given type. If
unspecified, no filtering will be performed.
Examples
gn ls out/Debug
Lists all targets in the default toolchain.
gn ls out/Debug "//base/*"
Lists all targets in the directory base and all subdirectories.
gn ls out/Debug "//base:*"
Lists all targets defined in //base/BUILD.gn.
gn ls out/Debug //base --as=output
Lists the build output file for //base:base
gn ls out/Debug --type=executable
Lists all executables produced by the build.
gn ls out/Debug "//base/*" --as=output | xargs ninja -C out/Debug
Builds all targets in //base and all subdirectories.
gn ls out/Debug //base --all-toolchains
Lists all variants of the target //base:base (it may be referenced
in multiple toolchains).
gn path <out_dir> <target_one> <target_two>
Finds paths of dependencies between two targets. Each unique path
will be printed in one group, and groups will be separate by newlines.
The two targets can appear in either order: paths will be found going
in either direction.
Each dependency will be annotated with its type. By default, only the
first path encountered will be printed, which is not necessarily the
shortest path.
Options
--all
Prints all paths found rather than just the first one.
Example
gn path out/Default //base //tools/gn
gn refs <out_dir> (<label_pattern>|||@<response_file>)* [–all]
[--all-toolchains] [--as=...] [--testonly=...] [--type=...]
Finds reverse dependencies (which targets reference something). The
input is a list containing:
- Target label: The result will be which targets depend on it.
- Config label: The result will be which targets list the given
config in its "configs" or "public_configs" list.
- Label pattern: The result will be which targets depend on any
target matching the given pattern. Patterns will not match
configs. These are not general regular expressions, see
"gn help label_pattern" for details.
- File name: The result will be which targets list the given file in
its "inputs", "sources", "public", "data", or "outputs".
Any input that does not contain wildcards and does not match a
target or a config will be treated as a file.
- Response file: If the input starts with an "@", it will be
interpreted as 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
--all
When used without --tree, will recurse and display all unique
dependencies of the given targets. For example, if the input is
a target, this will output all targets that depend directly or
indirectly on the input. If the input is a file, this will output
all targets that depend directly or indirectly on that file.
When used with --tree, turns off eliding to show a complete tree.
--all-toolchains
Normally only inputs in the default toolchain will be included.
This switch will turn on matching all toolchains.
For example, a file is in a target might be compiled twice:
once in the default toolchain and once in a secondary one. Without
this flag, only the default toolchain one will be matched and
printed (potentially with its recursive dependencies, depending on
the other options). With this flag, both will be printed
(potentially with both of their recursive dependencies).
--as=(buildfile|label|output)
How to print targets.
buildfile
Prints the build files where the given target was declared as
file names.
label (default)
Prints the label of the target.
output
Prints the first output file for the target relative to the
current directory.
-q
Quiet. If nothing matches, don't print any output. Without this
option, if there are no matches there will be an informational
message printed which might interfere with scripts processing the
output.
--testonly=(true|false)
Restrict outputs to targets with the testonly flag set
accordingly. When unspecified, the target's testonly flags are
ignored.
--tree
Outputs a reverse dependency tree from the given target.
Duplicates will be elided. Combine with --all to see a full
dependency tree.
Tree output can not be used with the filtering or output flags:
--as, --type, --testonly.
--type=(action|copy|executable|group|shared_library|source_set|
static_library)
Restrict outputs to targets matching the given type. If
unspecified, no filtering will be performed.
Examples (target input)
gn refs out/Debug //tools/gn:gn
Find all targets depending on the given exact target name.
gn refs out/Debug //base:i18n --as=buildfiles | xargs gvim
Edit all .gn files containing references to //base:i18n
gn refs out/Debug //base --all
List all targets depending directly or indirectly on //base:base.
gn refs out/Debug "//base/*"
List all targets depending directly on any target in //base or
its subdirectories.
gn refs out/Debug "//base:*"
List all targets depending directly on any target in
//base/BUILD.gn.
gn refs out/Debug //base --tree
Print a reverse dependency tree of //base:base
Examples (file input)
gn refs out/Debug //base/macros.h
Print target(s) listing //base/macros.h as a source.
gn refs out/Debug //base/macros.h --tree
Display a reverse dependency tree to get to the given file. This
will show how dependencies will reference that file.
gn refs out/Debug //base/macros.h //base/at_exit.h --all
Display all unique targets with some dependency path to a target
containing either of the given files as a source.
gn refs out/Debug //base/macros.h --testonly=true --type=executable
--all --as=output
Display the executable file names of all test executables
potentially affected by a change to the given file.
action: Declare a target that runs a script a single time.
This target type allows you to run a script a single time to produce
or more output files. If you want to run a script once for each of a
set of input files, see "gn help action_foreach".
Inputs
In an action the "sources" and "inputs" are treated the same:
they're both input dependencies on script execution with no special
handling. If you want to pass the sources to your script, you must do
so explicitly by including them in the "args". Note also that this
means there is no special handling of paths since GN doesn't know
which of the args are paths and not. You will want to use
rebase_path() to convert paths to be relative to the root_build_dir.
You can dynamically write input dependencies (for incremental rebuilds
if an input file changes) by writing a depfile when the script is run
(see "gn help depfile"). This is more flexible than "inputs".
It is recommended you put inputs to your script in the "sources"
variable, and stuff like other Python files required to run your
script in the "inputs" variable.
The "deps" and "public_deps" for an action will always be
completed before any part of the action is run so it can depend on
the output of previous steps. The "data_deps" will be built if the
action is built, but may not have completed before all steps of the
action are started. This can give additional parallelism in the build
for runtime-only dependencies.
Outputs
You should specify files created by your script by specifying them in
the "outputs".
The script will be executed with the given arguments with the current
directory being that of the root build directory. If you pass files
to your script, see "gn help rebase_path" for how to convert
file names to be relative to the build directory (file names in the
sources, outputs, and inputs will be all treated as relative to the
current build file and converted as needed automatically).
File name handling
All output files must be inside the output directory of the build.
You would generally use |$target_out_dir| or |$target_gen_dir| to
reference the output or generated intermediate file directories,
respectively.
Variables
args, data, data_deps, depfile, deps, outputs*, script*,
inputs, sources
* = required
Example
action("run_this_guy_once") {
script = "doprocessing.py"
sources = [ "my_configuration.txt" ]
outputs = [ "$target_gen_dir/insightful_output.txt" ]
# Our script imports this Python file so we want to rebuild if it
# changes.
inputs = [ "helper_library.py" ]
# Note that we have to manually pass the sources to our script if
# the script needs them as inputs.
args = [ "--out", rebase_path(target_gen_dir, root_build_dir) ] +
rebase_path(sources, root_build_dir)
}
action_foreach: Declare a target that runs a script over a set of files.
This target type allows you to run a script once-per-file over a set
of sources. If you want to run a script once that takes many files as
input, see "gn help action".
Inputs
The script will be run once per file in the "sources" variable. The
"outputs" variable should specify one or more files with a source
expansion pattern in it (see "gn help source_expansion"). The output
file(s) for each script invocation should be unique. Normally you
use "{
{source_name_part}}" in each output file.
If your script takes additional data as input, such as a shared
configuration file or a Python module it uses, those files should be
listed in the "inputs" variable. These files are treated as
dependencies of each script invocation.
You can dynamically write input dependencies (for incremental rebuilds
if an input file changes) by writing a depfile when the script is run
(see "gn help depfile"). This is more flexible than "inputs".
The "deps" and "public_deps" for an action will always be
completed before any part of the action is run so it can depend on
the output of previous steps. The "data_deps" will be built if the
action is built, but may not have completed before all steps of the
action are started. This can give additional parallelism in the build
for runtime-only dependencies.
Outputs
The script will be executed with the given arguments with the current
directory being that of the root build directory. If you pass files
to your script, see "gn help rebase_path" for how to convert
file names to be relative to the build directory (file names in the
sources, outputs, and inputs will be all treated as relative to the
current build file and converted as needed automatically).
File name handling
All output files must be inside the output directory of the build.
You would generally use |$target_out_dir| or |$target_gen_dir| to
reference the output or generated intermediate file directories,
respectively.
Variables
args, data, data_deps, depfile, deps, outputs*, script*,
inputs, sources*
* = required
Example
# Runs the script over each IDL file. The IDL script will generate
# both a and a .h file for each input.
action_foreach("my_idl") {
script = "idl_processor.py"
sources = [ "foo.idl", "bar.idl" ]
# Our script reads this file each time, so we need to list is as a
# dependency so we can rebuild if it changes.
inputs = [ "my_configuration.txt" ]
# Transformation from source file name to output file names.
outputs = [ "$target_gen_dir/{
{source_name_part}}.h",
"$target_gen_dir/{
{source_name_part}}" ]
# Note that since "args" is opaque to GN, if you specify paths
# here, you will need to convert it to be relative to the build
# directory using "rebase_path()".
args = [
"{
{source}}",
"-o",
rebase_path(relative_target_gen_dir, root_build_dir) +
"/{
{source_name_part}}.h" ]
}
assert: Assert an expression is true at generation time.
assert(<condition> [, <error string>])
If the condition is false, the build will fail with an error. If the
optional second argument is provided, that string will be printed
with the error message.
Examples:
assert(is_win)
assert(defined(sources), "Sources must be defined")
config: Defines a configuration object.
Configuration objects can be applied to targets and specify sets of
compiler flags, includes, defines, etc. They provide a way to
conveniently group sets of this configuration information.
A config is referenced by its label just like a target.
The values in a config are additive only. If you want to remove a flag
you need to remove the corresponding config that sets it. The final
set of flags, defines, etc. for a target is generated in this order:
1. The values specified directly on the target (rather than using a
config.
2. The configs specified in the target's "configs" list, in order.
3. Public_configs from a breadth-first traversal of the dependency
tree in the order that the targets appear in "deps".
4. All dependent conf
版权声明:本文标题:GN Reference 内容由热心网友自发贡献,该文观点仅代表作者本人, 转载请联系作者并注明出处:https://m.elefans.com/dianzi/1728850252a1176585.html, 本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌抄袭侵权/违法违规的内容,一经查实,本站将立刻删除。
发表评论