# GN Reference
*This page is automatically generated from* `gn help --markdown all`.
## Contents
* [Commands](#commands)
* [analyze: Analyze which targets are affected by a list of files.](#cmd_analyze)
* [args: Display or configure arguments declared by the build.](#cmd_args)
* [check: Check header dependencies.](#cmd_check)
* [clean: Cleans the output directory.](#cmd_clean)
* [clean_stale: Cleans the stale output files from the output directory.](#cmd_clean_stale)
* [desc: Show lots of insightful information about a target or config.](#cmd_desc)
* [format: Format .gn files.](#cmd_format)
* [gen: Generate ninja files.](#cmd_gen)
* [help: Does what you think.](#cmd_help)
* [ls: List matching targets.](#cmd_ls)
* [meta: List target metadata collection results.](#cmd_meta)
* [outputs: Which files a source/target make.](#cmd_outputs)
* [path: Find paths between two targets.](#cmd_path)
* [refs: Find stuff referencing a target or file.](#cmd_refs)
* [Target declarations](#targets)
* [action: Declare a target that runs a script a single time.](#func_action)
* [action_foreach: Declare a target that runs a script over a set of files.](#func_action_foreach)
* [bundle_data: [iOS/macOS] Declare a target without output.](#func_bundle_data)
* [copy: Declare a target that copies files.](#func_copy)
* [create_bundle: [iOS/macOS] Build an iOS or macOS bundle.](#func_create_bundle)
* [executable: Declare an executable target.](#func_executable)
* [generated_file: Declare a generated_file target.](#func_generated_file)
* [group: Declare a named group of targets.](#func_group)
* [loadable_module: Declare a loadable module target.](#func_loadable_module)
* [rust_library: Declare a Rust library target.](#func_rust_library)
* [rust_proc_macro: Declare a Rust procedural macro target.](#func_rust_proc_macro)
* [shared_library: Declare a shared library target.](#func_shared_library)
* [source_set: Declare a source set target.](#func_source_set)
* [static_library: Declare a static library target.](#func_static_library)
* [target: Declare an target with the given programmatic type.](#func_target)
* [Buildfile functions](#functions)
* [assert: Assert an expression is true at generation time.](#func_assert)
* [config: Defines a configuration object.](#func_config)
* [declare_args: Declare build arguments.](#func_declare_args)
* [defined: Returns whether an identifier is defined.](#func_defined)
* [exec_script: Synchronously run a script and return the output.](#func_exec_script)
* [filter_exclude: Remove values that match a set of patterns.](#func_filter_exclude)
* [filter_include: Remove values that do not match a set of patterns.](#func_filter_include)
* [foreach: Iterate over a list.](#func_foreach)
* [forward_variables_from: Copies variables from a different scope.](#func_forward_variables_from)
* [get_label_info: Get an attribute from a target's label.](#func_get_label_info)
* [get_path_info: Extract parts of a file or directory name.](#func_get_path_info)
* [get_target_outputs: [file list] Get the list of outputs from a target.](#func_get_target_outputs)
* [getenv: Get an environment variable.](#func_getenv)
* [import: Import a file into the current scope.](#func_import)
* [not_needed: Mark variables from scope as not needed.](#func_not_needed)
* [pool: Defines a pool object.](#func_pool)
* [print: Prints to the console.](#func_print)
* [process_file_template: Do template expansion over a list of files.](#func_process_file_template)
* [read_file: Read a file into a variable.](#func_read_file)
* [rebase_path: Rebase a file or directory to another location.](#func_rebase_path)
* [set_default_toolchain: Sets the default toolchain name.](#func_set_default_toolchain)
* [set_defaults: Set default values for a target type.](#func_set_defaults)
* [split_list: Splits a list into N different sub-lists.](#func_split_list)
* [string_join: Concatenates a list of strings with a separator.](#func_string_join)
* [string_replace: Replaces substring in the given string.](#func_string_replace)
* [string_split: Split string into a list of strings.](#func_string_split)
* [template: Define a template rule.](#func_template)
* [tool: Specify arguments to a toolchain tool.](#func_tool)
* [toolchain: Defines a toolchain.](#func_toolchain)
* [write_file: Write a file to disk.](#func_write_file)
* [Built-in predefined variables](#predefined_variables)
* [current_cpu: [string] The processor architecture of the current toolchain.](#var_current_cpu)
* [current_os: [string] The operating system of the current toolchain.](#var_current_os)
* [current_toolchain: [string] Label of the current toolchain.](#var_current_toolchain)
* [default_toolchain: [string] Label of the default toolchain.](#var_default_toolchain)
* [gn_version: [number] The version of gn.](#var_gn_version)
* [host_cpu: [string] The processor architecture that GN is running on.](#var_host_cpu)
* [host_os: [string] The operating system that GN is running on.](#var_host_os)
* [invoker: [string] The invoking scope inside a template.](#var_invoker)
* [python_path: [string] Absolute path of Python.](#var_python_path)
* [root_build_dir: [string] Directory where build commands are run.](#var_root_build_dir)
* [root_gen_dir: [string] Directory for the toolchain's generated files.](#var_root_gen_dir)
* [root_out_dir: [string] Root directory for toolchain output files.](#var_root_out_dir)
* [target_cpu: [string] The desired cpu architecture for the build.](#var_target_cpu)
* [target_gen_dir: [string] Directory for a target's generated files.](#var_target_gen_dir)
* [target_name: [string] The name of the current target.](#var_target_name)
* [target_os: [string] The desired operating system for the build.](#var_target_os)
* [target_out_dir: [string] Directory for target output files.](#var_target_out_dir)
* [Variables you set in targets](#target_variables)
* [aliased_deps: [scope] Set of crate-dependency pairs.](#var_aliased_deps)
* [all_dependent_configs: [label list] Configs to be forced on dependents.](#var_all_dependent_configs)
* [allow_circular_includes_from: [label list] Permit includes from deps.](#var_allow_circular_includes_from)
* [arflags: [string list] Arguments passed to static_library archiver.](#var_arflags)
* [args: [string list] Arguments passed to an action.](#var_args)
* [asmflags: [string list] Flags passed to the assembler.](#var_asmflags)
* [assert_no_deps: [label pattern list] Ensure no deps on these targets.](#var_assert_no_deps)
* [bridge_header: [string] Path to C/Objective-C compatibility header.](#var_bridge_header)
* [bundle_contents_dir: Expansion of {{bundle_contents_dir}} in create_bundle.](#var_bundle_contents_dir)
* [bundle_deps_filter: [label list] A list of labels that are filtered out.](#var_bundle_deps_filter)
* [bundle_executable_dir: Expansion of {{bundle_executable_dir}} in create_bundle](#var_bundle_executable_dir)
* [bundle_resources_dir: Expansion of {{bundle_resources_dir}} in create_bundle.](#var_bundle_resources_dir)
* [bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle.](#var_bundle_root_dir)
* [cflags: [string list] Flags passed to all C compiler variants.](#var_cflags)
* [cflags_c: [string list] Flags passed to the C compiler.](#var_cflags_c)
* [cflags_cc: [string list] Flags passed to the C++ compiler.](#var_cflags_cc)
* [cflags_objc: [string list] Flags passed to the Objective C compiler.](#var_cflags_objc)
* [cflags_objcc: [string list] Flags passed to the Objective C++ compiler.](#var_cflags_objcc)
* [check_includes: [boolean] Controls whether a target's files are checked.](#var_check_includes)
* [code_signing_args: [string list] Arguments passed to code signing script.](#var_code_signing_args)
* [code_signing_outputs: [file list] Output files for code signing step.](#var_code_signing_outputs)
* [code_signing_script: [file name] Script for code signing.](#var_code_signing_script)
* [code_signing_sources: [file list] Sources for code signing step.](#var_code_signing_sources)
* [complete_static_lib: [boolean] Links all deps into a static library.](#var_complete_static_lib)
* [configs: [label list] Configs applying to this target or config.](#var_configs)
* [contents: Contents to write to file.](#var_contents)
* [crate_name: [string] The name for the compiled crate.](#var_crate_name)
* [crate_root: [string] The root source file for a binary or library.](#var_crate_root)
* [crate_type: [string] The type of linkage to use on a shared_library.](#var_crate_type)
* [data: [file list] Runtime data file dependencies.](#var_data)
* [data_deps: [label list] Non-linked dependencies.](#var_data_deps)
* [data_keys: [string list] Keys from which to collect metadata.](#var_data_keys)
* [defines: [string list] C preprocessor defines.](#var_defines)
* [depfile: [string] File name for input dependencies for actions.](#var_depfile)
* [deps: [label list] Private linked dependencies.](#var_deps)
* [externs: [scope] Set of Rust crate-dependency pairs.](#var_externs)
* [framework_dirs: [directory list] Additional framework search directories.](#var_framework_dirs)
* [frameworks: [name list] Name of frameworks that must be linked.](#var_frameworks)
* [friend: [label pattern list] Allow targets to include private headers.](#var_friend)
* [gen_deps: [label list] Declares targets that should generate when this one does.](#var_gen_deps)
* [include_dirs: [directory list] Additional include directories.](#var_include_dirs)
* [inputs: [file list] Additional compile-time dependencies.](#var_inputs)
* [ldflags: [string list] Flags passed to the linker.](#var_ldflags)
* [lib_dirs: [directory list] Additional library directories.](#var_lib_dirs)
* [libs: [string list] Additional libraries to link.](#var_libs)
* [metadata: [scope] Metadata of this target.](#var_metadata)
* [module_name: [string] The name for the compiled module.](#var_module_name)
* [output_conversion: Data format for generated_file targets.](#var_output_conversion)
* [output_dir: [directory] Directory to put output file in.](#var_output_dir)
* [output_extension: [string] Value to use for the output's file extension.](#var_output_extension)
* [output_name: [string] Name for the output file other than the default.](#var_output_name)
* [output_prefix_override: [boolean] Don't use prefix for output name.](#var_output_prefix_override)
* [outputs: [file list] Output files for actions and copy targets.](#var_outputs)
* [partial_info_plist: [filename] Path plist from asset catalog compiler.](#var_partial_info_plist)
* [pool: [string] Label of the pool used by the action.](#var_pool)
* [precompiled_header: [string] Header file to precompile.](#var_precompiled_header)
* [precompiled_header_type: [string] "gcc" or "msvc".](#var_precompiled_header_type)
* [precompiled_source: [file name] Source file to precompile.](#var_precompiled_source)
* [product_type: [string] Product type for Xcode projects.](#var_product_type)
* [public: [file list] Declare public header files for a target.](#var_public)
* [public_configs: [label list] Configs applied to dependents.](#var_public_configs)
* [public_deps: [label list] Declare public dependencies.](#var_public_deps)
* [rebase: [boolean] Rebase collected metadata as files.](#var_rebase)
* [response_file_contents: [string list] Contents of .rsp file for actions.](#var_response_file_contents)
* [script: [file name] Script file for actions.](#var_script)
* [sources: [file list] Source files for a target.](#var_sources)
* [swiftflags: [string list] Flags passed to the swift compiler.](#var_swiftflags)
* [testonly: [boolean] Declares a target must only be used for testing.](#var_testonly)
* [visibility: [label list] A list of labels that can depend on a target.](#var_visibility)
* [walk_keys: [string list] Key(s) for managing the metadata collection walk.](#var_walk_keys)
* [weak_frameworks: [name list] Name of frameworks that must be weak linked.](#var_weak_frameworks)
* [write_runtime_deps: Writes the target's runtime_deps to the given path.](#var_write_runtime_deps)
* [xcasset_compiler_flags: [string list] Flags passed to xcassets compiler](#var_xcasset_compiler_flags)
* [xcode_extra_attributes: [scope] Extra attributes for Xcode projects.](#var_xcode_extra_attributes)
* [xcode_test_application_name: [string] Name for Xcode test target.](#var_xcode_test_application_name)
* [Other help topics](#other)
* all: Print all the help at once
* [buildargs: How build arguments work.](#buildargs)
* [dotfile: Info about the toplevel .gn file.](#dotfile)
* [execution: Build graph and execution overview.](#execution)
* [grammar: Language and grammar for GN build files.](#grammar)
* [input_conversion: Processing input from exec_script and read_file.](#io_conversion)
* [file_pattern: Matching more than one file.](#file_pattern)
* [label_pattern: Matching more than one label.](#label_pattern)
* [labels: About labels.](#labels)
* [metadata_collection: About metadata and its collection.](#metadata_collection)
* [ninja_rules: How Ninja build rules are named.](#ninja_rules)
* [nogncheck: Annotating includes for checking.](#nogncheck)
* [output_conversion: Specifies how to transform a value to output.](#io_conversion)
* [runtime_deps: How runtime dependency computation works.](#runtime_deps)
* [source_expansion: Map sources to outputs for scripts.](#source_expansion)
* [switches: Show available command-line switches.](#switch_list)
## [--list] [--short] [--args] [--overrides-only]
See also "gn help buildargs" for a more high-level overview of how
build arguments work.
```
#### **Usage**
```
gn args
Open the arguments for the given build directory in an editor. 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"
To find your editor on Posix, GN will search the environment variables in
order: GN_EDITOR, VISUAL, and EDITOR. On Windows GN will open the command
associated with .txt files.
Note: you can edit the build args manually by editing the file "args.gn"
in the build directory and then running "gn gen ".
gn args --list[=] [--short] [--overrides-only] [--json]
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, current value for the
build, default value (if different than the current value), and comment
preceding the declaration.
If --short is specified, only the names and current values will be
printed.
If --overrides-only is specified, only the names and current values of
arguments that have been overridden (i.e. non-default arguments) will
be printed. Overrides come from the /args.gn file and //.gn
If --json is specified, the output will be emitted in json format.
JSON schema for output:
[
{
"name": variable_name,
"current": {
"value": overridden_value,
"file": file_name,
"line": line_no
},
"default": {
"value": default_value,
"file": file_name,
"line": line_no
},
"comment": comment_string
},
...
]
```
#### **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 --short --overrides-only
Prints overridden arguments 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).
```
### 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**
```
--check-generated
Generated files are normally not checked since they do not exist
until after a build. With this flag, those generated files that
can be found on disk are also checked.
--check-system
Check system style includes (using ) in addition to
"double quote" includes.
--default-toolchain
Normally wildcard targets are matched in all toolchains. This
switch makes wildcard labels with no explicit toolchain reference
only match targets in the default toolchain.
Non-wildcard inputs with no explicit toolchain specification will
always match only a target in the default toolchain if one exists.
--force
Ignores specifications of "check_includes = false" and checks all
target's files that match the target label.
```
#### **What gets checked**
```
The .gn file may specify a list of targets to be checked in the list
check_targets (see "gn help dotfile"). Alternatively, the .gn file may
specify a list of targets not to be checked in no_check_targets. If a label
pattern is specified on the command line, neither check_targets or
no_check_targets is used.
Targets can opt-out from checking with "check_includes = false" (see
"gn help check_includes").
For targets being checked:
- GN opens all C-like source files in the targets to be checked and scans
the top for includes.
- Generated files (that might not exist yet) are ignored unless
the --check-generated flag is provided.
- Includes with a "nogncheck" annotation are skipped (see
"gn help nogncheck").
- Includes using "quotes" are always checked.
If system style checking is enabled, includes using
are also checked.
- Include paths are assumed to be relative to any of the "include_dirs" for
the target (including the implicit current dir).
- GN does not run the preprocessor so will not understand conditional
includes.
- Only includes matching known files in the build are checked: includes
matching unknown paths are ignored.
For an include to be valid:
- The included file must be in the current target, or there must be a path
following only public dependencies to a target with the file in it
("gn path" is a good way to diagnose problems).
- There can be multiple targets with an included file: only one needs to be
valid for the include to be allowed.
- If there are only "sources" in a target, all are considered to be public
and can be included by other targets with a valid public dependency path.
- If a target lists files as "public", only those files are able to be
included by other targets. Anything in the sources will be considered
private and will not be includable regardless of dependency paths.
- Outputs from actions are treated like public sources on that target.
- 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**
```
If you have a third party project that is difficult to fix or doesn't care
about include checks it's generally best to exclude that target from checking
altogether via "check_includes = false".
If you have conditional includes, make sure the build conditions and the
preprocessor conditions match, and annotate the line with "nogncheck" (see
"gn help nogncheck" for an example).
If two targets are hopelessly intertwined, use the
"allow_circular_includes_from" annotation. Ideally each should have identical
dependencies so configs inherited from those dependencies are consistent (see
"gn help allow_circular_includes_from").
If you have a standalone header file or files that need to be shared between
a few targets, you can consider making a source_set listing only those
headers as public sources. With only header files, the source set will be a
no-op from a build perspective, but will give a central place to refer to
those headers. That source set's files will still need to pass "gn check" in
isolation.
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**
```
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.
```
###
Can be used to specify the ninja executable to use.
```
### [] [--blame]
[--format=json]
Displays information about a given target or config. The build parameters
will be taken for the build in the given .
The 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>**
```
(If unspecified an overall summary will be displayed.)
all_dependent_configs
allow_circular_includes_from
arflags [--blame]
args
cflags [--blame]
cflags_c [--blame]
cflags_cc [--blame]
check_includes
configs [--tree] (see below)
data_keys
defines [--blame]
depfile
deps [--all] [--tree] (see below)
framework_dirs
frameworks
include_dirs [--blame]
inputs
ldflags [--blame]
lib_dirs
libs
metadata
output_conversion
outputs
public_configs
public
rebase
script
sources
testonly
visibility
walk_keys
weak_frameworks
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**
```
--default-toolchain
Normally wildcard targets are matched in all toolchains. This
switch makes wildcard labels with no explicit toolchain reference
only match targets in the default toolchain.
Non-wildcard inputs with no explicit toolchain specification will
always match only a target in the default toolchain if one exists.
--format=json
Format the output as JSON instead of text.
```
#### **Target flags**
```
--blame
Used with any value specified on a config, this will name the config that
causes that target to get the flag. This doesn't currently work for libs,
lib_dirs, frameworks, weak_frameworks and framework_dirs because those are
inherited and are more complicated to figure out the blame (patches
welcome).
```
#### **Configs**
```
The "configs" section will list all configs that apply. For targets this will
include configs specified in the "configs" variable of the target, and also
configs pushed onto this target via public or "all dependent" configs.
Configs can have child configs. Specifying --tree will show the hierarchy.
```
#### **Printing outputs**
```
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**
```
Deps will include all public, private, and data deps (TODO this could be
clarified and enhanced) sorted in order applying. The following may be used:
--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
root build 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|loadable_module|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.
```
###
Can be used to specify the ninja executable to use. This executable will
be used as an IDE option to indicate which ninja to use for building. This
executable will also be used as part of the gen process for triggering a
restat on generated ninja files and for use with --clean-stale.
--clean-stale
This option will cause no longer needed output files to be removed from
the build directory, and their records pruned from the ninja build log and
dependency database after the ninja build graph has been generated. This
option requires a ninja executable of at least version 1.10.0. It can be
provided by the --ninja-executable switch. Also see "gn help clean_stale".
```
#### **IDE options**
```
GN optionally generates files for IDE. Files won't be overwritten if their
contents don't change. Possibilities for
--ide=
Generate files for an IDE. Currently supported values:
"eclipse" - Eclipse CDT settings file.
"vs" - Visual Studio project/solution files.
(default Visual Studio version: 2019)
"vs2013" - Visual Studio 2013 project/solution files.
"vs2015" - Visual Studio 2015 project/solution files.
"vs2017" - Visual Studio 2017 project/solution files.
"vs2019" - Visual Studio 2019 project/solution files.
"vs2022" - Visual Studio 2022 project/solution files.
"xcode" - Xcode workspace/solution files.
"qtcreator" - QtCreator project files.
"json" - JSON file containing target information
--filters=
Semicolon-separated list of label patterns used to limit the set of
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**
```
--sln=
Override default sln file name ("all"). Solution file is written to the
root build directory.
--no-deps
Don't include targets dependencies to the solution. Changes the way how
--filters option works. Only directly matching targets are included.
--winsdk=
Use the specified Windows 10 SDK version to generate project files.
As an example, "10.0.15063.0" can be specified to use Creators Update SDK
instead of the default one.
--ninja-executable=
Can be used to specify the ninja executable to use when building.
--ninja-extra-args=
This string is passed without any quoting to the ninja invocation
command-line. Can be used to configure ninja flags, like "-j".
```
#### **Xcode Flags**
```
--xcode-project=
Override default Xcode project file name ("all"). The project file is
written to the root build directory.
--xcode-build-system=
Configure the build system to use for the Xcode project. Supported
values are (default to "legacy"):
"legacy" - Legacy Build system
"new" - New Build System
--ninja-executable=
Can be used to specify the ninja executable to use when building.
--ninja-extra-args=
This string is passed without any quoting to the ninja invocation
command-line. Can be used to configure ninja flags, like "-j".
--ide-root-target=
Name of the target corresponding to "All" target in Xcode. If unset,
"All" invokes ninja without any target and builds everything.
```
#### **QtCreator Flags**
```
--ide-root-target=
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**
```
GN DOES NOT generate Eclipse CDT projects. Instead, it generates a settings
file which can be imported into an Eclipse CDT project. The XML file contains
a list of include paths and defines. Because GN does not generate a full
.cproject definition, it is not possible to properly define includes/defines
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**
```
Dumps target information to a JSON file and optionally invokes a
python script on the generated file. See the comments at the beginning
of json_project_writer.cc and desc_builder.cc for an overview of the JSON
file format.
--json-file-name=
Overrides default file name (project.json) of generated JSON file.
--json-ide-script=
Executes python script after the JSON file is generated or updated with
new content. Path can be project absolute (//), system absolute (/) or
relative, in which case the output directory will be base. Path to
generated JSON file will be first argument when invoking script.
--json-ide-script-args=
Optional second argument that will passed to executed script.
```
#### **Compilation Database**
```
--export-rust-project
Produces a rust-project.json file in the root of the build directory
This is used for various tools in the Rust ecosystem allowing for the
replay of individual compilations independent of the build system.
This is an unstable format and likely to change without warning.
--export-compile-commands[=]
Produces a compile_commands.json file in the root of the build directory
containing an array of “command objects”, where each command object
specifies one way a translation unit is compiled in the project. If a list
of target_name is supplied, only targets that are reachable from any
target in any build file whose name is target_name will be used for
“command objects” generation, otherwise all available targets will be used.
This is used for various Clang-based tooling, allowing for the replay of
individual compilations independent of the build system.
e.g. "foo" will match:
- "//path/to/src:foo"
- "//other/path:foo"
- "//foo:foo"
and not match:
- "//foo:bar"
```
### * --data=[,*]* [--walk=[,*]*]
[--rebase=]
Lists collected metaresults of all given targets for the given data key(s),
collecting metadata dependencies as specified by the given walk key(s).
See `gn help generated_file` for more information on the walk.
```
#### **Arguments**
```
A list of target labels from which to initiate the walk.
--data
A comma-separated list of keys from which to extract data. In each target
walked, its metadata scope is checked for the presence of these keys. If
present, the contents of those variable in the scope are appended to the
results list.
--walk (optional)
A comma-separated list of keys from which to control the walk. In each
target walked, its metadata scope is checked for the presence of any of
these keys. If present, the contents of those variables is checked to ensure
that it is a label of a valid dependency of the target and then added to the
set of targets to walk. If the empty string ("") is present in any of these
keys, all deps and data_deps are added to the walk set.
--rebase (optional)
A destination directory onto which to rebase any paths found. If set, all
collected metadata will be rebased onto this path. This option will throw errors
if collected metadata is not a list of strings.
```
#### **Examples**
```
gn meta out/Debug "//base/foo" --data=files
Lists collected metaresults for the `files` key in the //base/foo:foo
target and all of its dependency tree.
gn meta out/Debug "//base/foo" --data=files,other
Lists collected metaresults for the `files` and `other` keys in the
//base/foo:foo target and all of its dependency tree.
gn meta out/Debug "//base/foo" --data=files --walk=stop
Lists collected metaresults for the `files` key in the //base/foo:foo
target and all of the dependencies listed in the `stop` key (and so on).
gn meta out/Debug "//base/foo" --data=files --rebase="/"
Lists collected metaresults for the `files` key in the //base/foo:foo
target and all of its dependency tree, rebasing the strings in the `files`
key onto the source directory of the target's declaration relative to "/".
```
### (|||@)* [--all]
[--default-toolchain] [--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.
--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
root build directory.
--default-toolchain
Normally wildcard targets are matched in all toolchains. This
switch makes wildcard labels with no explicit toolchain reference
only match targets in the default toolchain.
Non-wildcard inputs with no explicit toolchain specification will
always match only a target in the default toolchain if one exists.
-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|loadable_module|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 //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.
```
## [, ])
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");
```
### , ) {
}
Executes the loop contents block over each item in the list, assigning the
loop_var to each item in sequence. The will be a copy so assigning
to it will not mutate the list. The loop will iterate over a copy of
so mutating it inside the loop will not affect iteration.
The block does not introduce a new scope, so that variable assignments inside
the loop will be visible once the loop terminates.
The loop variable will temporarily shadow any existing variables with the
same name for the duration of the loop. After the loop terminates the loop
variable will no longer be in scope, and the previous value (if any) will be
restored.
```
#### **Example**
```
mylist = [ "a", "b", "c" ]
foreach(i, mylist) {
print(i)
}
Prints:
a
b
c
```
### ) { }
Sets the default values for a given target type. Whenever target_type_name is
seen in the future, the values specified in set_default's block will be
copied into the current scope.
When the target type is used, the variable copying is very strict. If a
variable with that name is already in scope, the build will fail with an
error.
set_defaults can be used for built-in target types ("executable",
"shared_library", etc.) and custom ones defined via the "template" command.
It can be called more than once and the most recent call in any scope will
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**
```
set_defaults("static_library") {
configs = [ "//tools/mything:settings" ]
}
static_library("mylib") {
# The configs will be auto-populated as above. You can remove it if
# you don't want the default for a particular default:
configs -= [ "//tools/mything:settings" ]
}
```
### ) {
}
```
#### **Tool types**
```
Compiler tools:
"cc": C compiler
"cxx": C++ compiler
"cxx_module": C++ compiler used for Clang .modulemap files
"objc": Objective C compiler
"objcxx": Objective C++ compiler
"rc": Resource compiler (Windows .rc files)
"asm": Assembler
"swift": Swift compiler driver
Linker tools:
"alink": Linker for static libraries (archives)
"solink": Linker for shared libraries
"link": Linker for executables
Other tools:
"stamp": Tool for creating stamp files
"copy": Tool to copy files.
"action": Defaults for actions
Platform specific tools:
"copy_bundle_data": [iOS, macOS] Tool to copy files in a bundle.
"compile_xcassets": [iOS, macOS] Tool to compile asset catalogs.
Rust tools:
"rust_bin": Tool for compiling Rust binaries
"rust_cdylib": Tool for compiling C-compatible dynamic libraries.
"rust_dylib": Tool for compiling Rust dynamic libraries.
"rust_macro": Tool for compiling Rust procedural macros.
"rust_rlib": Tool for compiling Rust libraries.
"rust_staticlib": Tool for compiling Rust static libraries.
```
#### **Tool variables**
```
command [string with substitutions]
Valid for: all tools except "action" (required)
The command to run.
command_launcher [string]
Valid for: all tools except "action" (optional)
The prefix with which to launch the command (e.g. the path to a Goma or
CCache compiler launcher).
Note that this prefix will not be included in the compilation database or
IDE files generated from the build.
default_output_dir [string with substitutions]
Valid for: linker tools
Default directory name for the output file relative to the
root_build_dir. It can contain other substitution patterns. This will
be the default value for the {{output_dir}} expansion (discussed below)
but will be overridden by the "output_dir" variable in a target, if one
is specified.
GN doesn't do anything with this string other than pass it along,
potentially with target-specific overrides. It is the tool's job to use
the expansion so that the files will be in the right place.
default_output_extension [string]
Valid for: linker tools
Extension for the main output of a linkable tool. It includes the
leading dot. This will be the default value for the
{{output_extension}} expansion (discussed below) but will be overridden
by by the "output extension" variable in a target, if one is specified.
Empty string means no extension.
GN doesn't actually do anything with this extension other than pass it
along, potentially with target-specific overrides. One would typically
use the {{output_extension}} value in the "outputs" to read this value.
Example: default_output_extension = ".exe"
depfile [string with substitutions]
Valid for: compiler tools (optional)
If the tool can write ".d" files, this specifies the name of the
resulting file. These files are used to list header file dependencies
(or other implicit input dependencies) that are discovered at build
time. See also "depsformat".
Example: depfile = "{{output}}.d"
depsformat [string]
Valid for: compiler tools (when depfile is specified)
Format for the deps outputs. This is either "gcc" or "msvc". See the
ninja documentation for "deps" for more information.
Example: depsformat = "gcc"
description [string with substitutions, optional]
Valid for: all tools
What to print when the command is run.
Example: description = "Compiling {{source}}"
exe_output_extension [string, optional, rust tools only]
rlib_output_extension [string, optional, rust tools only]
dylib_output_extension [string, optional, rust tools only]
cdylib_output_extension [string, optional, rust tools only]
rust_proc_macro_output_extension [string, optional, rust tools only]
Valid for: Rust tools
These specify the default tool output for each of the crate types.
The default is empty for executables, shared, and static libraries and
".rlib" for rlibs. Note that the Rust compiler complains with an error
if external crates do not take the form `lib.rlib` or
`lib.`, where `` is `.so`,
`.dylib`, or `.dll` as appropriate for the platform.
lib_switch [string, optional, link tools only]
lib_dir_switch [string, optional, link tools only]
Valid for: Linker tools except "alink"
These strings will be prepended to the libraries and library search
directories, respectively, because linkers differ on how to specify
them.
If you specified:
lib_switch = "-l"
lib_dir_switch = "-L"
then the "{{libs}}" expansion for
[ "freetype", "expat" ]
would be
"-lfreetype -lexpat".
framework_switch [string, optional, link tools only]
weak_framework_switch [string, optional, link tools only]
framework_dir_switch [string, optional, link tools only]
Valid for: Linker tools
These strings will be prepended to the frameworks and framework search
path directories, respectively, because linkers differ on how to specify
them.
If you specified:
framework_switch = "-framework "
weak_framework_switch = "-weak_framework "
framework_dir_switch = "-F"
and:
framework_dirs = [ "$root_out_dir" ]
frameworks = [ "UIKit.framework", "Foo.framework" ]
weak_frameworks = [ "MediaPlayer.framework" ]
would be:
"-F. -framework UIKit -framework Foo -weak_framework MediaPlayer"
swiftmodule_switch [string, optional, link tools only]
Valid for: Linker tools except "alink"
The string will be prependend to the path to the .swiftmodule files
that are embedded in the linker output.
If you specified:
swiftmodule_swift = "-Wl,-add_ast_path,"
then the "{{swiftmodules}}" expansion for
[ "obj/foo/Foo.swiftmodule" ]
would be
"-Wl,-add_ast_path,obj/foo/Foo.swiftmodule"
outputs [list of strings with substitutions]
Valid for: Linker and compiler tools (required)
An array of names for the output files the tool produces. These are
relative to the build output directory. There must always be at least
one output file. There can be more than one output (a linker might
produce a library and an import library, for example).
This array just declares to GN what files the tool will produce. It is
your responsibility to specify the tool command that actually produces
these files.
If you specify more than one output for shared library links, you
should consider setting link_output, depend_output, and
runtime_outputs.
Example for a compiler tool that produces .obj files:
outputs = [
"{{source_out_dir}}/{{source_name_part}}.obj"
]
Example for a linker tool that produces a .dll and a .lib. The use of
{{target_output_name}}, {{output_extension}} and {{output_dir}} allows
the target to override these values.
outputs = [
"{{output_dir}}/{{target_output_name}}{{output_extension}}",
"{{output_dir}}/{{target_output_name}}.lib",
]
partial_outputs [list of strings with substitutions]
Valid for: "swift" only
An array of names for the partial outputs the tool produces. These
are relative to the build output directory. The expansion will be
evaluated for each file listed in the "sources" of the target.
This is used to deal with whole module optimization, allowing to
list one object file per source file when whole module optimization
is disabled.
pool [label, optional]
Valid for: all tools (optional)
Label of the pool to use for the tool. Pools are used to limit the
number of tasks that can execute concurrently during the build.
See also "gn help pool".
link_output [string with substitutions]
depend_output [string with substitutions]
Valid for: "solink" only (optional)
These two files specify which of the outputs from the solink tool
should be used for linking and dependency tracking. These should match
entries in the "outputs". If unspecified, the first item in the
"outputs" array will be used for all. See "Separate linking and
dependencies for shared libraries" below for more.
On Windows, where the tools produce a .dll shared library and a .lib
import library, you will want the first two to be the import library
and the third one to be the .dll file. On Linux, if you're not doing
the separate linking/dependency optimization, all of these should be
the .so output.
output_prefix [string]
Valid for: Linker tools (optional)
Prefix to use for the output name. Defaults to empty. This prefix will
be prepended to the name of the target (or the output_name if one is
manually specified for it) if the prefix is not already there. The
result will show up in the {{output_name}} substitution pattern.
Individual targets can opt-out of the output prefix by setting:
output_prefix_override = true
(see "gn help output_prefix_override").
This is typically used to prepend "lib" to libraries on
Posix systems:
output_prefix = "lib"
precompiled_header_type [string]
Valid for: "cc", "cxx", "objc", "objcxx"
Type of precompiled headers. If undefined or the empty string,
precompiled headers will not be used for this tool. Otherwise use "gcc"
or "msvc".
For precompiled headers to be used for a given target, the target (or a
config applied to it) must also specify a "precompiled_header" and, for
"msvc"-style headers, a "precompiled_source" value. If the type is
"gcc", then both "precompiled_header" and "precompiled_source" must
resolve to the same file, despite the different formats required for
each."
See "gn help precompiled_header" for more.
restat [boolean]
Valid for: all tools (optional, defaults to false)
Requests that Ninja check the file timestamp after this tool has run to
determine if anything changed. Set this if your tool has the ability to
skip writing output if the output file has not changed.
Normally, Ninja will assume that when a tool runs the output be new and
downstream dependents must be rebuild. When this is set to trye, Ninja
can skip rebuilding downstream dependents for input changes that don't
actually affect the output.
Example:
restat = true
rspfile [string with substitutions]
Valid for: all tools except "action" (optional)
Name of the response file. If empty, no response file will be
used. See "rspfile_content".
rspfile_content [string with substitutions]
Valid for: all tools except "action" (required when "rspfile" is used)
The contents to be written to the response file. This may include all
or part of the command to send to the tool which allows you to get
around OS command-line length limits.
This example adds the inputs and libraries to a response file, but
passes the linker flags directly on the command line:
tool("link") {
command = "link -o {{output}} {{ldflags}} @{{output}}.rsp"
rspfile = "{{output}}.rsp"
rspfile_content = "{{inputs}} {{solibs}} {{libs}} {{rlibs}}"
}
runtime_outputs [string list with substitutions]
Valid for: linker tools
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.
rust_sysroot
Valid for: Rust tools
A path relative to root_out_dir. This is not used in the build
process, but may be used when generating metadata for rust-analyzer.
(See --export-rust-project). It enables such metadata to include
information about the Rust standard library.
```
#### **Expansions for tool variables**
```
All paths are relative to the root build directory, which is the current
directory for running all tools. These expansions are available to all tools:
{{label}}
The label of the current target. This is typically used in the
"description" field for link tools. The toolchain will be omitted from
the label for targets in the default toolchain, and will be included
for targets in other toolchains.
{{label_name}}
The short name of the label of the target. This is the part after the
colon. For "//foo/bar:baz" this will be "baz". Unlike
{{target_output_name}}, this is not affected by the "output_prefix" in
the tool or the "output_name" set on the target.
{{label_no_toolchain}}
The label of the current target, never including the toolchain
(otherwise, this is identical to {{label}}). This is used as the module
name when using .modulemap files.
{{output}}
The relative path and name of the output(s) of the current build step.
If there is more than one output, this will expand to a list of all of
them. Example: "out/base/my_file.o"
{{target_gen_dir}}
{{target_out_dir}}
The directory of the generated file and output directories,
respectively, for the current target. There is no trailing slash. See
also {{output_dir}} for linker tools. Example: "out/base/test"
{{target_output_name}}
The short name of the current target with no path information, or the
value of the "output_name" variable if one is specified in the target.
This will include the "output_prefix" if any. See also {{label_name}}.
Example: "libfoo" for the target named "foo" and an output prefix for
the linker tool of "lib".
Compiler tools have the notion of a single input and a single output, along
with a set of compiler-specific flags. The following expansions are
available:
{{asmflags}}
{{cflags}}
{{cflags_c}}
{{cflags_cc}}
{{cflags_objc}}
{{cflags_objcc}}
{{defines}}
{{include_dirs}}
Strings correspond that to the processed flags/defines/include
directories specified for the target.
Example: "--enable-foo --enable-bar"
Defines will be prefixed by "-D" and include directories will be
prefixed by "-I" (these work with Posix tools as well as Microsoft
ones).
{{module_deps}}
{{module_deps_no_self}}
Strings that correspond to the flags necessary to depend upon the Clang
modules referenced by the current target. The "_no_self" version doesn't
include the module for the current target, and can be used to compile
the pcm itself.
{{source}}
The relative path and name of the current input file.
Example: "../../base/my_file.cc"
{{source_file_part}}
The file part of the source including the extension (with no directory
information).
Example: "foo.cc"
{{source_name_part}}
The filename part of the source file with no directory or extension.
Example: "foo"
{{source_gen_dir}}
{{source_out_dir}}
The directory in the generated file and output directories,
respectively, for the current input file. If the source file is in the
same directory as the target is declared in, they will will be the same
as the "target" versions above. Example: "gen/base/test"
Linker tools have multiple inputs and (potentially) multiple outputs. The
static library tool ("alink") is not considered a linker tool. The following
expansions are available:
{{inputs}}
{{inputs_newline}}
Expands to the inputs to the link step. This will be a list of object
files and static libraries.
Example: "obj/foo.o obj/bar.o obj/somelibrary.a"
The "_newline" version will separate the input files with newlines
instead of spaces. This is useful in response files: some linkers can
take a "-filelist" flag which expects newline separated files, and some
Microsoft tools have a fixed-sized buffer for parsing each line of a
response file.
{{ldflags}}
Expands to the processed set of ldflags and library search paths
specified for the target.
Example: "-m64 -fPIC -pthread -L/usr/local/mylib"
{{libs}}
Expands to the list of system libraries to link to. Each will be
prefixed by the "lib_switch".
Example: "-lfoo -lbar"
{{output_dir}}
The value of the "output_dir" variable in the target, or the the value
of the "default_output_dir" value in the tool if the target does not
override the output directory. This will be relative to the
root_build_dir and will not end in a slash. Will be "." for output to
the root_build_dir.
This is subtly different than {{target_out_dir}} which is defined by GN
based on the target's path and not overridable. {{output_dir}} is for
the final output, {{target_out_dir}} is generally for object files and
other outputs.
Usually {{output_dir}} would be defined in terms of either
{{target_out_dir}} or {{root_out_dir}}
{{output_extension}}
The value of the "output_extension" variable in the target, or the
value of the "default_output_extension" value in the tool if the target
does not specify an output extension.
Example: ".so"
{{solibs}}
Extra libraries from shared library dependencies not specified in the
{{inputs}}. This is the list of link_output files from shared libraries
(if the solink tool specifies a "link_output" variable separate from
the "depend_output").
These should generally be treated the same as libs by your tool.
Example: "libfoo.so libbar.so"
{{rlibs}}
Any Rust .rlibs which need to be linked into a final C++ target.
These should be treated as {{inputs}} except that sometimes
they might have different linker directives applied.
Example: "obj/foo/libfoo.rlib"
{{frameworks}}
Shared libraries packaged as framework bundle. This is principally
used on Apple's platforms (macOS and iOS). All name must be ending
with ".framework" suffix; the suffix will be stripped when expanding
{{frameworks}} and each item will be preceded by "-framework" or
"-weak_framework".
{{swiftmodules}}
Swift .swiftmodule files that needs to be embedded into the binary.
This is necessary to correctly link with object generated by the
Swift compiler (the .swiftmodule file cannot be embedded in object
files directly). Those will be prefixed with "swiftmodule_switch"
value.
The static library ("alink") tool allows {{arflags}} plus the common tool
substitutions.
The copy tool allows the common compiler/linker substitutions, plus
{{source}} which is the source of the copy. The stamp tool allows only the
common tool substitutions.
The copy_bundle_data and compile_xcassets tools only allows the common tool
substitutions. Both tools are required to create iOS/macOS bundles and need
only be defined on those platforms.
The copy_bundle_data tool will be called with one source and needs to copy
(optionally optimizing the data representation) to its output. It may be
called with a directory as input and it needs to be recursively copied.
The compile_xcassets tool will be called with one or more source (each an
asset catalog) that needs to be compiled to a single output. The following
substitutions are available:
{{inputs}}
Expands to the list of .xcassets to use as input to compile the asset
catalog.
{{bundle_product_type}}
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.
{{bundle_partial_info_plist}}
Expands to the path to the partial Info.plist generated by the
assets catalog compiler. Usually based on the target_name of
the create_bundle target.
{{xcasset_compiler_flags}}
Expands to the list of flags specified in corresponding
create_bundle target.
The Swift tool has multiple input and outputs. It must have exactly one
output of .swiftmodule type, but can have one or more object file outputs,
in addition to other type of outputs. The following expansions are available:
{{module_name}}
Expands to the string representing the module name of target under
compilation (see "module_name" variable).
{{module_dirs}}
Expands to the list of -I for the target Swift module search
path computed from target dependencies.
{{swiftflags}}
Expands to the list of strings representing Swift compiler flags.
Rust tools have the notion of a single input and a single output, along
with a set of compiler-specific flags. The following expansions are
available:
{{crate_name}}
Expands to the string representing the crate name of target under
compilation.
{{crate_type}}
Expands to the string representing the type of crate for the target
under compilation.
{{externs}}
Expands to the list of --extern flags needed to include addition Rust
libraries in this target. Includes any specified renamed dependencies.
{{rustdeps}}
Expands to the list of -Ldependency= strings needed to compile
this target.
{{rustenv}}
Expands to the list of environment variables.
{{rustflags}}
Expands to the list of strings representing Rust compiler flags.
```
#### **Separate linking and dependencies for shared libraries**
```
Shared libraries are special in that not all changes to them require that
dependent targets be re-linked. If the shared library is changed but no
imports or exports are different, dependent code needn't be relinked, which
can speed up the build.
If your link step can output a list of exports from a shared library and
writes the file only if the new one is different, the timestamp of this file
can be used for triggering re-links, while the actual shared library would be
used for linking.
You will need to specify
restat = true
in the linker tool to make this work, so Ninja will detect if the timestamp
of the dependency file has changed after linking (otherwise it will always
assume that running a command updates the output):
tool("solink") {
command = "..."
outputs = [
"{{output_dir}}/{{target_output_name}}{{output_extension}}",
"{{output_dir}}/{{target_output_name}}{{output_extension}}.TOC",
]
link_output =
"{{output_dir}}/{{target_output_name}}{{output_extension}}"
depend_output =
"{{output_dir}}/{{target_output_name}}{{output_extension}}.TOC"
restat = true
}
```
#### **Example**
```
toolchain("my_toolchain") {
# Put these at the top to apply to all tools below.
lib_switch = "-l"
lib_dir_switch = "-L"
tool("cc") {
command = "gcc {{source}} -o {{output}}"
outputs = [ "{{source_out_dir}}/{{source_name_part}}.o" ]
description = "GCC {{source}}"
}
tool("cxx") {
command = "g++ {{source}} -o {{output}}"
outputs = [ "{{source_out_dir}}/{{source_name_part}}.o" ]
description = "G++ {{source}}"
}
};
```
### /obj/bar`
executable("foo") {
sources = [ "main.rs" ]
deps = [ ":bar" ]
aliased_deps = {
bar_renamed = ":bar"
}
}
With the addition of `aliased_deps`, above target would instead compile with:
`rustc ...command... --extern bar_renamed=/obj/bar`
```
### " to indicate the depfile.
args = [ "{{source}}", "-o", depfile ]
}
```
###