Add reference.md This was generated by running "gn help --markdown all" Change-Id: I7641e7c91ecc57eab782b7eab69444aa5787b679 Reviewed-on: https://gn-review.googlesource.com/2220 Reviewed-by: Brett Wilson <brettw@chromium.org> Commit-Queue: Brett Wilson <brettw@chromium.org>
diff --git a/docs/reference.md b/docs/reference.md new file mode 100644 index 0000000..902adc0 --- /dev/null +++ b/docs/reference.md
@@ -0,0 +1,6380 @@ +# 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.](#analyze) + * [args: Display or configure arguments declared by the build.](#args) + * [check: Check header dependencies.](#check) + * [clean: Cleans the output directory.](#clean) + * [desc: Show lots of insightful information about a target or config.](#desc) + * [format: Format .gn file.](#format) + * [gen: Generate ninja files.](#gen) + * [help: Does what you think.](#help) + * [ls: List matching targets.](#ls) + * [path: Find paths between two targets.](#path) + * [refs: Find stuff referencing a target or file.](#refs) +* [Target declarations](#targets) + * [action: Declare a target that runs a script a single time.](#action) + * [action_foreach: Declare a target that runs a script over a set of files.](#action_foreach) + * [bundle_data: [iOS/macOS] Declare a target without output.](#bundle_data) + * [copy: Declare a target that copies files.](#copy) + * [create_bundle: [iOS/macOS] Build an iOS or macOS bundle.](#create_bundle) + * [executable: Declare an executable target.](#executable) + * [group: Declare a named group of targets.](#group) + * [loadable_module: Declare a loadable module target.](#loadable_module) + * [shared_library: Declare a shared library target.](#shared_library) + * [source_set: Declare a source set target.](#source_set) + * [static_library: Declare a static library target.](#static_library) + * [target: Declare an target with the given programmatic type.](#target) +* [Buildfile functions](#functions) + * [assert: Assert an expression is true at generation time.](#assert) + * [config: Defines a configuration object.](#config) + * [declare_args: Declare build arguments.](#declare_args) + * [defined: Returns whether an identifier is defined.](#defined) + * [exec_script: Synchronously run a script and return the output.](#exec_script) + * [foreach: Iterate over a list.](#foreach) + * [forward_variables_from: Copies variables from a different scope.](#forward_variables_from) + * [get_label_info: Get an attribute from a target's label.](#get_label_info) + * [get_path_info: Extract parts of a file or directory name.](#get_path_info) + * [get_target_outputs: [file list] Get the list of outputs from a target.](#get_target_outputs) + * [getenv: Get an environment variable.](#getenv) + * [import: Import a file into the current scope.](#import) + * [not_needed: Mark variables from scope as not needed.](#not_needed) + * [pool: Defines a pool object.](#pool) + * [print: Prints to the console.](#print) + * [process_file_template: Do template expansion over a list of files.](#process_file_template) + * [read_file: Read a file into a variable.](#read_file) + * [rebase_path: Rebase a file or directory to another location.](#rebase_path) + * [set_default_toolchain: Sets the default toolchain name.](#set_default_toolchain) + * [set_defaults: Set default values for a target type.](#set_defaults) + * [set_sources_assignment_filter: Set a pattern to filter source files.](#set_sources_assignment_filter) + * [split_list: Splits a list into N different sub-lists.](#split_list) + * [template: Define a template rule.](#template) + * [tool: Specify arguments to a toolchain tool.](#tool) + * [toolchain: Defines a toolchain.](#toolchain) + * [write_file: Write a file to disk.](#write_file) +* [Built-in predefined variables](#predefined_variables) + * [current_cpu: [string] The processor architecture of the current toolchain.](#current_cpu) + * [current_os: [string] The operating system of the current toolchain.](#current_os) + * [current_toolchain: [string] Label of the current toolchain.](#current_toolchain) + * [default_toolchain: [string] Label of the default toolchain.](#default_toolchain) + * [host_cpu: [string] The processor architecture that GN is running on.](#host_cpu) + * [host_os: [string] The operating system that GN is running on.](#host_os) + * [invoker: [string] The invoking scope inside a template.](#invoker) + * [python_path: [string] Absolute path of Python.](#python_path) + * [root_build_dir: [string] Directory where build commands are run.](#root_build_dir) + * [root_gen_dir: [string] Directory for the toolchain's generated files.](#root_gen_dir) + * [root_out_dir: [string] Root directory for toolchain output files.](#root_out_dir) + * [target_cpu: [string] The desired cpu architecture for the build.](#target_cpu) + * [target_gen_dir: [string] Directory for a target's generated files.](#target_gen_dir) + * [target_name: [string] The name of the current target.](#target_name) + * [target_os: [string] The desired operating system for the build.](#target_os) + * [target_out_dir: [string] Directory for target output files.](#target_out_dir) +* [Variables you set in targets](#target_variables) + * [all_dependent_configs: [label list] Configs to be forced on dependents.](#all_dependent_configs) + * [allow_circular_includes_from: [label list] Permit includes from deps.](#allow_circular_includes_from) + * [arflags: [string list] Arguments passed to static_library archiver.](#arflags) + * [args: [string list] Arguments passed to an action.](#args) + * [asmflags: [string list] Flags passed to the assembler.](#asmflags) + * [assert_no_deps: [label pattern list] Ensure no deps on these targets.](#assert_no_deps) + * [bundle_contents_dir: Expansion of {{bundle_contents_dir}} in create_bundle.](#bundle_contents_dir) + * [bundle_deps_filter: [label list] A list of labels that are filtered out.](#bundle_deps_filter) + * [bundle_executable_dir: Expansion of {{bundle_executable_dir}} in create_bundle](#bundle_executable_dir) + * [bundle_plugins_dir: Expansion of {{bundle_plugins_dir}} in create_bundle.](#bundle_plugins_dir) + * [bundle_resources_dir: Expansion of {{bundle_resources_dir}} in create_bundle.](#bundle_resources_dir) + * [bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle.](#bundle_root_dir) + * [cflags: [string list] Flags passed to all C compiler variants.](#cflags) + * [cflags_c: [string list] Flags passed to the C compiler.](#cflags_c) + * [cflags_cc: [string list] Flags passed to the C++ compiler.](#cflags_cc) + * [cflags_objc: [string list] Flags passed to the Objective C compiler.](#cflags_objc) + * [cflags_objcc: [string list] Flags passed to the Objective C++ compiler.](#cflags_objcc) + * [check_includes: [boolean] Controls whether a target's files are checked.](#check_includes) + * [code_signing_args: [string list] Arguments passed to code signing script.](#code_signing_args) + * [code_signing_outputs: [file list] Output files for code signing step.](#code_signing_outputs) + * [code_signing_script: [file name] Script for code signing.](#code_signing_script) + * [code_signing_sources: [file list] Sources for code signing step.](#code_signing_sources) + * [complete_static_lib: [boolean] Links all deps into a static library.](#complete_static_lib) + * [configs: [label list] Configs applying to this target or config.](#configs) + * [data: [file list] Runtime data file dependencies.](#data) + * [data_deps: [label list] Non-linked dependencies.](#data_deps) + * [defines: [string list] C preprocessor defines.](#defines) + * [depfile: [string] File name for input dependencies for actions.](#depfile) + * [deps: [label list] Private linked dependencies.](#deps) + * [friend: [label pattern list] Allow targets to include private headers.](#friend) + * [include_dirs: [directory list] Additional include directories.](#include_dirs) + * [inputs: [file list] Additional compile-time dependencies.](#inputs) + * [ldflags: [string list] Flags passed to the linker.](#ldflags) + * [lib_dirs: [directory list] Additional library directories.](#lib_dirs) + * [libs: [string list] Additional libraries to link.](#libs) + * [output_dir: [directory] Directory to put output file in.](#output_dir) + * [output_extension: [string] Value to use for the output's file extension.](#output_extension) + * [output_name: [string] Name for the output file other than the default.](#output_name) + * [output_prefix_override: [boolean] Don't use prefix for output name.](#output_prefix_override) + * [outputs: [file list] Output files for actions and copy targets.](#outputs) + * [partial_info_plist: [filename] Path plist from asset catalog compiler.](#partial_info_plist) + * [pool: [string] Label of the pool used by the action.](#pool) + * [precompiled_header: [string] Header file to precompile.](#precompiled_header) + * [precompiled_header_type: [string] "gcc" or "msvc".](#precompiled_header_type) + * [precompiled_source: [file name] Source file to precompile.](#precompiled_source) + * [product_type: [string] Product type for Xcode projects.](#product_type) + * [public: [file list] Declare public header files for a target.](#public) + * [public_configs: [label list] Configs applied to dependents.](#public_configs) + * [public_deps: [label list] Declare public dependencies.](#public_deps) + * [response_file_contents: [string list] Contents of .rsp file for actions.](#response_file_contents) + * [script: [file name] Script file for actions.](#script) + * [sources: [file list] Source files for a target.](#sources) + * [testonly: [boolean] Declares a target must only be used for testing.](#testonly) + * [visibility: [label list] A list of labels that can depend on a target.](#visibility) + * [write_runtime_deps: Writes the target's runtime_deps to the given path.](#write_runtime_deps) + * [xcode_extra_attributes: [scope] Extra attributes for Xcode projects.](#xcode_extra_attributes) + * [test_application_name: [string] Test application name for unit or ui test target.](#test_application_name) +* [Other help topics](#other) + * [all: Print all the help at once](#all) + * [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.](#input_conversion) + * [label_pattern: Matching more than one label.](#label_pattern) + * [labels: About labels.](#labels) + * [ninja_rules: How Ninja build rules are named.](#ninja_rules) + * [nogncheck: Annotating includes for checking.](#nogncheck) + * [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.](#switches) + +## <a name="commands"></a>Commands + +### <a name="analyze"></a>**gn analyze <out_dir> <input_path> <output_path>** + +``` + Analyze which targets are affected by a list of files. + + This command takes three arguments: + + out_dir is the path to the build directory. + + input_path is a path to a file containing a JSON object with three fields: + + - "files": A list of the filenames to check. + + - "test_targets": A list of the labels for targets that are needed to run + the tests we wish to run. + + - "additional_compile_targets": A list of the labels for targets that we + wish to rebuild, but aren't necessarily needed for testing. The important + difference between this field and "test_targets" is that if an item in + the additional_compile_targets list refers to a group, then any + dependencies of that group will be returned if they are out of date, but + the group itself does not need to be. If the dependencies themselves are + groups, the same filtering is repeated. This filtering can be used to + avoid rebuilding dependencies of a group that are unaffected by the input + files. The list may also contain the string "all" to refer to a + pseudo-group that contains every root target in the build graph. + + This filtering behavior is also known as "pruning" the list of compile + targets. + + output_path is a path indicating where the results of the command are to be + written. The results will be a file containing a JSON object with one or more + of following fields: + + - "compile_targets": A list of the labels derived from the input + compile_targets list that are affected by the input files. Due to the way + the filtering works for compile targets as described above, this list may + contain targets that do not appear in the input list. + + - "test_targets": A list of the labels from the input test_targets list that + are affected by the input files. This list will be a proper subset of the + input list. + + - "invalid_targets": A list of any names from the input that do not exist in + the build graph. If this list is non-empty, the "error" field will also be + set to "Invalid targets". + + - "status": A string containing one of three values: + + - "Found dependency" + - "No dependency" + - "Found dependency (all) " + + In the first case, the lists returned in compile_targets and test_targets + should be passed to ninja to build. In the second case, nothing was + affected and no build is necessary. In the third case, GN could not + determine the correct answer and returned the input as the output in order + to be safe. + + - "error": This will only be present if an error occurred, and will contain + a string describing the error. This includes cases where the input file is + not in the right format, or contains invalid targets. + + The command returns 1 if it is unable to read the input file or write the + output file, or if there is something wrong with the build such that gen + would also fail, and 0 otherwise. In particular, it returns 0 even if the + "error" key is non-empty and a non-fatal error occurred. In other words, it + tries really hard to always write something to the output JSON and convey + errors that way rather than via return codes. +``` +### <a name="args"></a>**gn args <out_dir> [\--list] [\--short] [\--args] [\--overrides-only]** + +``` + 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. 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 <out_dir>". + + gn args <out_dir> --list[=<exact_arg>] [--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 <out_dir>/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). +``` +### <a name="check"></a>**gn check <out_dir> [<label_pattern>] [\--force]** + +``` + GN's include header checker validates that the includes for C-like source + files match the build dependency graph. + + "gn check" is the same thing as "gn gen" with the "--check" flag except that + this command does not write out any build files. It's intended to be an easy + way to manually trigger include file checking. + + 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** + +``` + --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. 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". + + 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. + + - Includes with a "nogncheck" annotation are skipped (see + "gn help nogncheck"). + + - Only includes using "quotes" are checked. <brackets> are assumed to be + system includes. + + - 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. +``` +### <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]** + +``` + Displays information about a given target or config. The build build + parameters will be taken for the build in the given <out_dir>. + + 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>** + +``` + (If unspecified an overall summary will be displayed.) + + all_dependent_configs + allow_circular_includes_from + arflags [--blame] + args + cflags [--blame] + cflags_cc [--blame] + cflags_cxx [--blame] + check_includes + configs [--tree] (see below) + defines [--blame] + depfile + deps [--all] [--tree] (see below) + include_dirs [--blame] + inputs + ldflags [--blame] + lib_dirs + libs + outputs + public_configs + public + script + sources + testonly + visibility + + 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** +``` + --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 by + wildcards. With this flag, both will be matched. + + --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 + 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** + +``` + 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. +``` +### <a name="format"></a>**gn format [\--dump-tree] (\--stdin | <build_file>)** + +``` + Formats .gn file to a standard format. + + The contents of some lists ('sources', 'deps', etc.) will be sorted to a + canonical order. To suppress this, you can add a comment of the form "# + NOSORT" immediately preceding the assignment. e.g. + + # NOSORT + sources = [ + "z.cc", + "a.cc", + ] +``` + +#### **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, dumps the parse tree to stdout and does not update the + file or print formatted output. + + --stdin + Read input from stdin and write to stdout rather than update a file + in-place. +``` + +#### **Examples** +``` + gn format //some/BUILD.gn + gn format some\\BUILD.gn + gn format /abspath/some/BUILD.gn + gn format --stdin +``` +### <a name="gen"></a>**gn gen [\--check] [<ide options>] <out_dir>** + +``` + Generates ninja files from the current tree and puts them in the given output + directory. + + The output directory can be a source-repo-absolute path name such as: + //out/foo + Or it can be a directory relative to the current directory such as: + out/foo + + "gn gen --check" is the same as running "gn check". See "gn help check" + for documentation on that mode. + + See "gn help switches" for the common command-line switches. +``` + +#### **IDE options** + +``` + GN optionally generates files for IDE. Possibilities for <ide options> + + --ide=<ide_name> + Generate files for an IDE. Currently supported values: + "eclipse" - Eclipse CDT settings file. + "vs" - Visual Studio project/solution files. + (default Visual Studio version: 2017) + "vs2013" - Visual Studio 2013 project/solution files. + "vs2015" - Visual Studio 2015 project/solution files. + "vs2017" - Visual Studio 2017 project/solution files. + "xcode" - Xcode workspace/solution files. + "qtcreator" - QtCreator project files. + "json" - JSON file containing target information + + --filters=<path_prefixes> + 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=<file_name> + 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=<sdk_version> + 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-extra-args=<string> + This string is passed without any quoting to the ninja invocation + command-line. Can be used to configure ninja flags, like "-j". +``` + +#### **Xcode Flags** + +``` + --workspace=<file_name> + Override defaut workspace file name ("all"). The workspace file is + written to the root build directory. + + --ninja-extra-args=<string> + This string is passed without any quoting to the ninja invocation + command-line. Can be used to configure ninja flags, like "-j". + + --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** + +``` + --root-target=<target_name> + 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=<json_file_name> + Overrides default file name (project.json) of generated JSON file. + + --json-ide-script=<path_to_python_script> + Executes python script after the JSON file is generated. Path can be + project absolute (//), system absolute (/) or relative, in which case the + output directory will be base. Path to generated JSON file will be first + argument when invoking script. + + --json-ide-script-args=<argument> + Optional second argument that will passed to executed script. +``` +### <a name="help"></a>**gn help <anything>** + +``` + Yo dawg, I heard you like help on your help so I put help on the help in the + help. + + You can also use "all" as the parameter to get all help at once. +``` + +#### **Switches** + +``` + --markdown + Format output in markdown syntax. +``` + +#### **Example** + +``` + gn help --markdown all + Dump all help to stdout in markdown format. +``` +### <a name="ls"></a>**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 + root build directory. + + --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 by + wildcards. With this flag, both will be matched. + + --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|loadable_module|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). +``` +### <a name="path"></a>**gn path <out_dir> <target_one> <target_two>** + +``` + Finds paths of dependencies between two targets. Each unique path will be + printed in one group, and groups will be separate by newlines. The two + targets can appear in either order (paths will be found going in either + direction). + + By default, a single path will be printed. If there is a path with only + public dependencies, the shortest public path will be printed. Otherwise, the + 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** + +``` + In a large project, there can be 100's of millions of unique paths between a + 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** + +``` + --all + Prints all "interesting" paths found rather than just the first one. + Public paths will be printed first in order of increasing length, followed + by non-public paths in order of increasing length. + + --public + Considers only public paths. Can't be used with --with-data. + + --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>)*** +``` + [--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 by + wildcards. With this flag, both will be matched. + + --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. + + -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 //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. +``` +## <a name="targets"></a>Target declarations + +### <a name="action"></a>**action**: Declare a target that runs a script a single time. + +``` + This target type allows you to run a script a single time to produce one or + more output files. If you want to run a script once for each of a set of + input files, see "gn help action_foreach". +``` + +#### **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". + + If the command line length is very long, you can use response files to pass + args to your script. See "gn help response_file_contents". + + 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, inputs, outputs*, pool, + response_file_contents, script*, 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) + } +``` +### <a name="action_foreach"></a>**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. + + If the command line length is very long, you can use response files to pass + args to your script. See "gn help response_file_contents". + + 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, inputs, outputs*, pool, + response_file_contents, script*, sources* + * = required +``` + +#### **Example** + +``` + # Runs the script over each IDL file. The IDL script will generate both a .cc + # 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}}.cc" ] + + # 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" ] + } +``` +### <a name="bundle_data"></a>**bundle_data**: [iOS/macOS] Declare a target without output. + +``` + This target type allows to declare data that is required at runtime. It is + used to inform "create_bundle" targets of the files to copy into generated + bundle, see "gn help create_bundle" for help. + + The target must define a list of files as "sources" and a single "outputs". + If there are multiple files, source expansions must be used to express the + output. The output must reference a file inside of {{bundle_root_dir}}. + + This target can be used on all platforms though it is designed only to + generate iOS/macOS bundle. In cross-platform projects, it is advised to put it + behind iOS/macOS conditionals. + + See "gn help create_bundle" for more information. +``` + +#### **Variables** + +``` + sources*, outputs*, deps, data_deps, public_deps, visibility + * = required +``` + +#### **Examples** + +``` + bundle_data("icudata") { + sources = [ "sources/data/in/icudtl.dat" ] + outputs = [ "{{bundle_resources_dir}}/{{source_file_part}}" ] + } + + bundle_data("base_unittests_bundle_data]") { + sources = [ "test/data" ] + outputs = [ + "{{bundle_resources_dir}}/{{source_root_relative_dir}}/" + + "{{source_file_part}}" + ] + } + + bundle_data("material_typography_bundle_data") { + sources = [ + "src/MaterialTypography.bundle/Roboto-Bold.ttf", + "src/MaterialTypography.bundle/Roboto-Italic.ttf", + "src/MaterialTypography.bundle/Roboto-Regular.ttf", + "src/MaterialTypography.bundle/Roboto-Thin.ttf", + ] + outputs = [ + "{{bundle_resources_dir}}/MaterialTypography.bundle/" + "{{source_file_part}}" + ] + } +``` +### <a name="copy"></a>**copy**: Declare a target that copies files. + +#### **File name handling** + +``` + All output files must be inside the output directory of the build. You would + generally use |$target_out_dir| or |$target_gen_dir| to reference the output + or generated intermediate file directories, respectively. + + Both "sources" and "outputs" must be specified. Sources can include as many + files as you want, but there can only be one item in the outputs list (plural + is used for the name for consistency with other target types). + + If there is more than one source file, your output name should specify a + 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** + +``` + # Write a rule that copies a checked-in DLL to the output directory. + copy("mydll") { + sources = [ "mydll.dll" ] + outputs = [ "$target_out_dir/mydll.dll" ] + } + + # Write a rule to copy several files to the target generated files directory. + copy("myfiles") { + sources = [ "data1.dat", "data2.dat", "data3.dat" ] + + # Use source expansion to generate output files with the corresponding file + # names in the gen dir. This will just copy each file. + outputs = [ "$target_gen_dir/{{source_file_part}}" ] + } +``` +### <a name="create_bundle"></a>**create_bundle**: [ios/macOS] Build an iOS or macOS bundle. + +``` + This target generates an iOS or macOS bundle (which is a directory with a + well-know structure). This target does not define any sources, instead they + are computed from all "bundle_data" target this one depends on transitively + (the recursion stops at "create_bundle" targets). + + The "bundle_*_dir" properties must be defined. They will be used for the + expansion of {{bundle_*_dir}} rules in "bundle_data" outputs. + + This target can be used on all platforms though it is designed only to + generate iOS or macOS bundle. In cross-platform projects, it is advised to put + it behind iOS/macOS conditionals. + + If a create_bundle is specified as a data_deps for another target, the bundle + is considered a leaf, and its public and private dependencies will not + 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** + +``` + Some bundle needs to be code signed as part of the build (on iOS all + application needs to be code signed to run on a device). The code signature + can be configured via the code_signing_script variable. + + If set, code_signing_script is the path of a script that invoked after all + files have been moved into the bundle. The script must not change any file in + the bundle, but may add new files. + + If code_signing_script is defined, then code_signing_outputs must also be + defined and non-empty to inform when the script needs to be re-run. The + 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** + +``` + bundle_root_dir*, bundle_contents_dir*, bundle_resources_dir*, + bundle_executable_dir*, bundle_plugins_dir*, bundle_deps_filter, deps, + data_deps, public_deps, visibility, product_type, code_signing_args, + code_signing_script, code_signing_sources, code_signing_outputs, + xcode_extra_attributes, xcode_test_application_name, partial_info_plist + * = required +``` + +#### **Example** + +``` + # Defines a template to create an application. On most platform, this is just + # an alias for an "executable" target, but on iOS/macOS, it builds an + # application bundle. + template("app") { + if (!is_ios && !is_mac) { + executable(target_name) { + forward_variables_from(invoker, "*") + } + } else { + app_name = target_name + gen_path = target_gen_dir + + action("${app_name}_generate_info_plist") { + script = [ "//build/ios/ios_gen_plist.py" ] + sources = [ "templates/Info.plist" ] + outputs = [ "$gen_path/Info.plist" ] + args = rebase_path(sources, root_build_dir) + + rebase_path(outputs, root_build_dir) + } + + bundle_data("${app_name}_bundle_info_plist") { + deps = [ ":${app_name}_generate_info_plist" ] + sources = [ "$gen_path/Info.plist" ] + outputs = [ "{{bundle_contents_dir}}/Info.plist" ] + } + + executable("${app_name}_generate_executable") { + forward_variables_from(invoker, "*", [ + "output_name", + "visibility", + ]) + output_name = + rebase_path("$gen_path/$app_name", root_build_dir) + } + + code_signing = + defined(invoker.code_signing) && invoker.code_signing + + if (is_ios && !code_signing) { + bundle_data("${app_name}_bundle_executable") { + deps = [ ":${app_name}_generate_executable" ] + sources = [ "$gen_path/$app_name" ] + outputs = [ "{{bundle_executable_dir}}/$app_name" ] + } + } + + create_bundle("${app_name}.app") { + product_type = "com.apple.product-type.application" + + if (is_ios) { + bundle_root_dir = "${root_build_dir}/$target_name" + bundle_contents_dir = bundle_root_dir + bundle_resources_dir = bundle_contents_dir + bundle_executable_dir = bundle_contents_dir + bundle_plugins_dir = "${bundle_contents_dir}/Plugins" + + extra_attributes = { + ONLY_ACTIVE_ARCH = "YES" + DEBUG_INFORMATION_FORMAT = "dwarf" + } + } else { + bundle_root_dir = "${root_build_dir}/target_name" + bundle_contents_dir = "${bundle_root_dir}/Contents" + bundle_resources_dir = "${bundle_contents_dir}/Resources" + bundle_executable_dir = "${bundle_contents_dir}/MacOS" + bundle_plugins_dir = "${bundle_contents_dir}/Plugins" + } + deps = [ ":${app_name}_bundle_info_plist" ] + if (is_ios && code_signing) { + deps += [ ":${app_name}_generate_executable" ] + code_signing_script = "//build/config/ios/codesign.py" + code_signing_sources = [ + invoker.entitlements_path, + "$target_gen_dir/$app_name", + ] + code_signing_outputs = [ + "$bundle_root_dir/$app_name", + "$bundle_root_dir/_CodeSignature/CodeResources", + "$bundle_root_dir/embedded.mobileprovision", + "$target_gen_dir/$app_name.xcent", + ] + code_signing_args = [ + "-i=" + ios_code_signing_identity, + "-b=" + rebase_path( + "$target_gen_dir/$app_name", root_build_dir), + "-e=" + rebase_path( + invoker.entitlements_path, root_build_dir), + "-e=" + rebase_path( + "$target_gen_dir/$app_name.xcent", root_build_dir), + rebase_path(bundle_root_dir, root_build_dir), + ] + } else { + deps += [ ":${app_name}_bundle_executable" ] + } + } + } + } +``` +### <a name="executable"></a>**executable**: Declare an executable target. + +#### **Variables** + +``` + Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, + asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, + libs, precompiled_header, precompiled_source + Deps: data_deps, deps, public_deps + Dependent configs: all_dependent_configs, public_configs + General: check_includes, configs, data, friend, inputs, output_name, + output_extension, public, sources, testonly, visibility +``` +### <a name="group"></a>**group**: Declare a named group of targets. + +``` + This target type allows you to create meta-targets that just collect a set of + dependencies into one named target. Groups can additionally specify configs + that apply to their dependents. +``` + +#### **Variables** + +``` + Deps: data_deps, deps, public_deps + Dependent configs: all_dependent_configs, public_configs +``` + +#### **Example** + +``` + group("all") { + deps = [ + "//project:runner", + "//project:unit_tests", + ] + } +``` +### <a name="loadable_module"></a>**loadable_module**: Declare a loadable module target. + +``` + This target type allows you to create an object file that is (and can only + be) loaded and unloaded at runtime. + + A loadable module will be specified on the linker line for targets listing + the loadable module in its "deps". If you don't want this (if you don't need + to dynamically load the library at runtime), then you should use a + "shared_library" target type instead. +``` + +#### **Variables** + +``` + Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, + asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, + libs, precompiled_header, precompiled_source + Deps: data_deps, deps, public_deps + Dependent configs: all_dependent_configs, public_configs + General: check_includes, configs, data, friend, inputs, output_name, + output_extension, public, sources, testonly, visibility +``` +### <a name="shared_library"></a>**shared_library**: Declare a shared library target. + +``` + A shared library will be specified on the linker line for targets listing the + shared library in its "deps". If you don't want this (say you dynamically + load the library at runtime), then you should depend on the shared library + via "data_deps" or, on Darwin platforms, use a "loadable_module" target type + instead. +``` + +#### **Variables** + +``` + Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, + asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, + libs, precompiled_header, precompiled_source + Deps: data_deps, deps, public_deps + Dependent configs: all_dependent_configs, public_configs + General: check_includes, configs, data, friend, inputs, output_name, + output_extension, public, sources, testonly, visibility +``` +### <a name="source_set"></a>**source_set**: Declare a source set target. + +``` + A source set is a collection of sources that get compiled, but are not linked + to produce any kind of library. Instead, the resulting object files are + implicitly added to the linker line of all targets that depend on the source + set. + + In most cases, a source set will behave like a static library, except no + actual library file will be produced. This will make the build go a little + faster by skipping creation of a large static library, while maintaining the + organizational benefits of focused build targets. + + The main difference between a source set and a static library is around + handling of exported symbols. Most linkers assume declaring a function + exported means exported from the static library. The linker can then do dead + code elimination to delete code not reachable from exported functions. + + A source set will not do this code elimination since there is no link step. + This allows you to link many sources sets into a shared library and have the + "exported symbol" notation indicate "export from the final shared library and + not from the intermediate targets." There is no way to express this concept + when linking multiple static libraries into a shared library. +``` + +#### **Variables** + +``` + Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, + asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, + libs, precompiled_header, precompiled_source + Deps: data_deps, deps, public_deps + Dependent configs: all_dependent_configs, public_configs + General: check_includes, configs, data, friend, inputs, output_name, + output_extension, public, sources, testonly, visibility +``` +### <a name="static_library"></a>**static_library**: Declare a static library target. + +``` + Make a ".a" / ".lib" file. + + If you only need the static library for intermediate results in the build, + you should consider a source_set instead since it will skip the (potentially + slow) step of creating the intermediate library file. +``` + +#### **Variables** + +``` + complete_static_lib + Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, + asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, + libs, precompiled_header, precompiled_source + Deps: data_deps, deps, public_deps + Dependent configs: all_dependent_configs, public_configs + General: check_includes, configs, data, friend, inputs, output_name, + output_extension, public, sources, testonly, visibility +``` +### <a name="target"></a>**target**: Declare an target with the given programmatic type. + +``` + target(target_type_string, target_name_string) { ... } + + The target() function is a way to invoke a built-in target or template with a + type determined at runtime. This is useful for cases where the type of a + target might not be known statically. + + Only templates and built-in target functions are supported for the + target_type_string parameter. Arbitrary functions, configs, and toolchains + are not supported. + + The call: + target("source_set", "doom_melon") { + Is equivalent to: + source_set("doom_melon") { +``` + +#### **Example** + +``` + if (foo_build_as_shared) { + my_type = "shared_library" + } else { + my_type = "source_set" + } + + target(my_type, "foo") { + ... + } +``` +## <a name="functions"></a>Buildfile functions + +### <a name="assert"></a>**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"); +``` +### <a name="config"></a>**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 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** +``` + Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, + asmflags, defines, include_dirs, inputs, 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** + +``` + config("myconfig") { + includes = [ "include/common" ] + defines = [ "ENABLE_DOOM_MELON" ] + } + + executable("mything") { + configs = [ ":myconfig" ] + } +``` +### <a name="declare_args"></a>**declare_args**: Declare build arguments. + +``` + Introduces the given arguments into the current scope. If they are not + specified on the command line or in a toolchain's arguments, the default + values given in the declare_args block will be used. However, these defaults + will not override command-line values. + + See also "gn help buildargs" for an overview. + + The precise behavior of declare args is: + + 1. The declare_args() block executes. Any variable defined in the enclosing + scope is available for reading, but any variable defined earlier in + the current scope is not (since the overrides haven't been applied yet). + + 2. At the end of executing the block, any variables set within that scope + are saved globally as build arguments, with their current values being + saved as the "default value" for that argument. + + 3. User-defined overrides are applied. Anything set in "gn args" now + overrides any default values. The resulting set of variables is promoted + to be readable from the following code in the file. + + This has some ramifications that may not be obvious: + + - You should not perform difficult work inside a declare_args block since + this only sets a default value that may be discarded. In particular, + don't use the result of exec_script() to set the default value. If you + want to have a script-defined default, set some default "undefined" value + like [], "", or -1, and after the declare_args block, call exec_script if + the value is unset by the user. + + - Because you cannot read the value of a variable defined in the same + block, if you need to make the default value of one arg depend + on the possibly-overridden value of another, write two separate + declare_args() blocks: + + declare_args() { + enable_foo = true + } + declare_args() { + # Bar defaults to same user-overridden state as foo. + enable_bar = enable_foo + } +``` + +#### **Example** + +``` + declare_args() { + enable_teleporter = true + enable_doom_melon = false + } + + If you want to override the (default disabled) Doom Melon: + gn --args="enable_doom_melon=true enable_teleporter=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. + +``` + Returns true if the given argument is defined. This is most useful in + templates to assert that the caller set things up properly. + + You can pass an identifier: + defined(foo) + which will return true or false depending on whether foo is defined in the + current scope. + + You can also check a named scope: + defined(foo.bar) + 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** + +``` + template("mytemplate") { + # To help users call this template properly... + assert(defined(invoker.sources), "Sources must be defined") + + # If we want to accept an optional "values" argument, we don't + # want to dereference something that may not be defined. + if (defined(invoker.values)) { + values = invoker.values + } else { + values = "some default value" + } + } +``` +### <a name="exec_script"></a>**exec_script**: Synchronously run a script and return the output. + +``` + exec_script(filename, + arguments = [], + input_conversion = "", + file_dependencies = []) + + Runs the given script, returning the stdout of the script. The build + generation will fail if the script does not exist or returns a nonzero exit + code. + + The current directory when executing the script will be the root build + 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**: + +``` + filename: + File name of python script to execute. Non-absolute names will be treated + as relative to the current build file. + + arguments: + A list of strings to be passed to the script as arguments. May be + unspecified or the empty list which means no arguments. + + input_conversion: + Controls how the file is read and parsed. See "gn help input_conversion". + + If unspecified, defaults to the empty string which causes the script + result to be discarded. exec script will return None. + + dependencies: + (Optional) A list of files that this script reads or otherwise depends + on. These dependencies will be added to the build result such that if any + of them change, the build will be regenerated and the script will be + re-run. + + The script itself will be an implicit dependency so you do not need to + list it. +``` + +#### **Example** + +``` + all_lines = exec_script( + "myscript.py", [some_input], "list lines", + [ rebase_path("data_file.txt", root_build_dir) ]) + + # This example just calls the script with no arguments and discards the + # result. + exec_script("//foo/bar/myscript.py") +``` +### <a name="foreach"></a>**foreach**: Iterate over a list. + +``` + foreach(<loop_var>, <list>) { + <loop contents> + } + + Executes the loop contents block over each item in the list, assigning the + loop_var to each item in sequence. The <loop_var> will be a copy so assigning + to it will not mutate the list. The loop will iterate over a copy of <list> + 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 +``` +### <a name="forward_variables_from"></a>**forward_variables_from**: Copies variables from a different scope. + +``` + forward_variables_from(from_scope, variable_list_or_star, + variable_to_not_forward_list = []) + + Copies the given variables from the given scope to the local scope if they + exist. This is normally used in the context of templates to use the values of + variables defined in the template invocation to a template-defined target. + + The variables in the given variable_list will be copied if they exist in the + given scope or any enclosing scope. If they do not exist, nothing will happen + and they be left undefined in the current scope. + + As a special case, if the variable_list is a string with the value of "*", + all variables from the given scope will be copied. "*" only copies variables + set directly on the from_scope, not enclosing ones. Otherwise it would + duplicate all global variables. + + When an explicit list of variables is supplied, if the variable exists in the + current (destination) scope already, an error will be thrown. If "*" is + specified, variables in the current scope will be clobbered (the latter is + important because most targets have an implicit configs list, which means it + wouldn't work at all if it didn't clobber). + + The sources assignment filter (see "gn help set_sources_assignment_filter") + is never applied by this function. It's assumed than any desired filtering + was already done when sources was set on the from_scope. + + 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** + +``` + # This is a common action template. It would invoke a script with some given + # parameters, and wants to use the various types of deps and the visibility + # from the invoker if it's defined. It also injects an additional dependency + # to all targets. + template("my_test") { + action(target_name) { + forward_variables_from(invoker, [ "data_deps", "deps", + "public_deps", "visibility" " + "]) + # Add our test code to the dependencies. + # "deps" may or may not be defined at this point. + if (defined(deps)) { + deps += [ "//tools/doom_melon" ] + } else { + deps = [ "//tools/doom_melon" ] + } + } + } + + # This is a template around either a target whose type depends on a global + # variable. It forwards all values from the invoker. + template("my_wrapper") { + target(my_wrapper_target_type, target_name) { + forward_variables_from(invoker, "*") + } + } + + # A template that wraps another. It adds behavior based on one + # variable, and forwards all others to the nested target. + template("my_ios_test_app") { + ios_test_app(target_name) { + forward_variables_from(invoker, "*", ["test_bundle_name"]) + if (!defined(extra_substitutions)) { + extra_substitutions = [] + } + extra_substitutions += [ "BUNDLE_ID_TEST_NAME=$test_bundle_name" ] + } + } +``` +### <a name="get_label_info"></a>**get_label_info**: Get an attribute from a target's label. + +``` + get_label_info(target_label, what) + + Given the label of a target, returns some attribute of that target. The + target need not have been previously defined in the same file, since none of + the attributes depend on the actual target definition, only the label itself. + + See also "gn help get_target_outputs". +``` + +#### **Possible values for the "what" parameter** + +``` + "name" + The short name of the target. This will match the value of the + "target_name" variable inside that target's declaration. For the label + "//foo/bar:baz" this will return "baz". + + "dir" + The directory containing the target's definition, with no slash at the + end. For the label "//foo/bar:baz" this will return "//foo/bar". + + "target_gen_dir" + The generated file directory for the target. This will match the value of + the "target_gen_dir" variable when inside that target's declaration. + + "root_gen_dir" + The root of the generated file tree for the target. This will match the + value of the "root_gen_dir" variable when inside that target's + declaration. + + "target_out_dir + The output directory for the target. This will match the value of the + "target_out_dir" variable when inside that target's declaration. + + "root_out_dir" + The root of the output file tree for the target. This will match the + value of the "root_out_dir" variable when inside that target's + declaration. + + "label_no_toolchain" + The fully qualified version of this label, not including the toolchain. + For the input ":bar" it might return "//foo:bar". + + "label_with_toolchain" + The fully qualified version of this label, including the toolchain. For + the input ":bar" it might return "//foo:bar(//toolchain:x64)". + + "toolchain" + The label of the toolchain. This will match the value of the + "current_toolchain" variable when inside that target's declaration. +``` + +#### **Examples** + +``` + get_label_info(":foo", "name") + # Returns string "foo". + + get_label_info("//foo/bar:baz", "target_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. + +``` + get_path_info(input, what) + + The first argument is either a string representing a file or directory name, + or a list of such strings. If the input is a list the return value will be a + list containing the result of applying the rule to each item in the input. +``` + +#### **Possible values for the "what" parameter** + +``` + "file" + The substring after the last slash in the path, including the name and + extension. If the input ends in a slash, the empty string will be + returned. + "foo/bar.txt" => "bar.txt" + "bar.txt" => "bar.txt" + "foo/" => "" + "" => "" + + "name" + The substring of the file name not including the extension. + "foo/bar.txt" => "bar" + "foo/bar" => "bar" + "foo/" => "" + + "extension" + The substring following the last period following the last slash, or the + empty string if not found. The period is not included. + "foo/bar.txt" => "txt" + "foo/bar" => "" + + "dir" + The directory portion of the name, not including the slash. + "foo/bar.txt" => "foo" + "//foo/bar" => "//foo" + "foo" => "." + + The result will never end in a slash, so if the resulting is empty, the + system ("/") or source ("//") roots, a "." will be appended such that it + is always legal to append a slash and a filename and get a valid path. + + "out_dir" + The output file directory corresponding to the path of the given file, + not including a trailing slash. + "//foo/bar/baz.txt" => "//out/Default/obj/foo/bar" + + "gen_dir" + The generated file directory corresponding to the path of the given file, + not including a trailing slash. + "//foo/bar/baz.txt" => "//out/Default/gen/foo/bar" + + "abspath" + The full absolute path name to the file or directory. It will be resolved + relative to the current directory, and then the source- absolute version + will be returned. If the input is system- absolute, the same input will + be returned. + "foo/bar.txt" => "//mydir/foo/bar.txt" + "foo/" => "//mydir/foo/" + "//foo/bar" => "//foo/bar" (already absolute) + "/usr/include" => "/usr/include" (already absolute) + + If you want to make the path relative to another directory, or to be + system-absolute, see rebase_path(). +``` + +#### **Examples** +``` + sources = [ "foo.cc", "foo.h" ] + result = get_path_info(source, "abspath") + # result will be [ "//mydir/foo.cc", "//mydir/foo.h" ] + + result = get_path_info("//foo/bar/baz.cc", "dir") + # result will be "//foo/bar" + + # Extract the source-absolute directory name, + result = get_path_info(get_path_info(path, "dir"), "abspath" +``` +### <a name="get_target_outputs"></a>**get_target_outputs**: [file list] Get the list of outputs from a target. + +``` + get_target_outputs(target_label) + + Returns a list of output files for the named target. The named target must + have been previously defined in the current file before this function is + called (it can't reference targets in other files because there isn't a + defined execution order, and it obviously can't reference targets that are + defined after the function call). + + Only copy and action targets are supported. The outputs from binary targets + 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** + +``` + The names in the resulting list will be absolute file paths (normally like + "//out/Debug/bar.exe", depending on the build directory). + + action targets: this will just return the files specified in the "outputs" + variable of the target. + + action_foreach targets: this will return the result of applying the output + template to the sources (see "gn help source_expansion"). This will be the + same result (though with guaranteed absolute file paths), as + process_file_template will return for those inputs (see "gn help + process_file_template"). + + binary targets (executables, libraries): this will return a list of the + resulting binary file(s). The "main output" (the actual binary or library) + will always be the 0th element in the result. Depending on the platform and + output type, there may be other output files as well (like import libraries) + which will follow. + + 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** + +``` + # Say this action generates a bunch of C source files. + action_foreach("my_action") { + sources = [ ... ] + outputs = [ ... ] + } + + # Compile the resulting source files into a source set. + source_set("my_lib") { + sources = get_target_outputs(":my_action") + } +``` +### <a name="getenv"></a>**getenv**: Get an environment variable. + +``` + value = getenv(env_var_name) + + Returns the value of the given environment variable. If the value is not + found, it will try to look up the variable with the "opposite" case (based on + the case of the first letter of the variable), but is otherwise + case-sensitive. + + If the environment variable is not found, the empty string will be returned. + Note: it might be nice to extend this if we had the concept of "none" in the + language to indicate lookup failure. +``` + +#### **Example** + +``` + home_dir = getenv("HOME") +``` +### <a name="import"></a>**import**: Import a file into the current scope. + +``` + The import command loads the rules and variables resulting from executing the + given file into the current scope. + + By convention, imported files are named with a .gni extension. + + An import is different than a C++ "include". The imported file is executed in + a standalone environment from the caller of the import command. The results + of this execution are cached for other files that import the same .gni file. + + Note that you can not import a BUILD.gn file that's otherwise used in the + build. Files must either be imported or implicitly loaded as a result of deps + rules, but not both. + + The imported file's scope will be merged with the scope at the point import + was called. If there is a conflict (both the current scope and the imported + file define some variable or rule with the same name but different value), a + runtime error will be thrown. Therefore, it's good practice to minimize the + stuff that an imported file defines. + + 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** + +``` + import("//build/rules/idl_compilation_rule.gni") + + # Looks in the current directory. + import("my_vars.gni") +``` +### <a name="not_needed"></a>**not_needed**: Mark variables from scope as not needed. + +``` + not_needed(variable_list_or_star, variable_to_ignore_list = []) + not_needed(from_scope, variable_list_or_star, + variable_to_ignore_list = []) + + Mark the variables in the current or given scope as not needed, which means + you will not get an error about unused variables for these. The + variable_to_ignore_list allows excluding variables from "all matches" if + variable_list_or_star is "*". +``` + +#### **Example** + +``` + not_needed("*", [ "config" ]) + not_needed([ "data_deps", "deps" ]) + not_needed(invoker, "*", [ "config" ]) + not_needed(invoker, [ "data_deps", "deps" ]) +``` +### <a name="pool"></a>**pool**: Defines a pool object. + +``` + Pool objects can be applied to a tool to limit the parallelism of the + build. This object has a single property "depth" corresponding to + the number of tasks that may run simultaneously. + + As the file containing the pool definition may be executed in the + context of more than one toolchain it is recommended to specify an + explicit toolchain when defining and referencing a pool. + + A pool is referenced by its label just like a target. +``` + +#### **Variables** + +``` + depth* + * = required +``` + +#### **Example** + +``` + if (current_toolchain == default_toolchain) { + pool("link_pool") { + depth = 1 + } + } + + toolchain("toolchain") { + tool("link") { + command = "..." + pool = ":link_pool($default_toolchain)") + } + } +``` +### <a name="print"></a>**print**: Prints to the console. + +``` + Prints all arguments to the console separated by spaces. A newline is + automatically appended to the end. + + This function is intended for debugging. Note that build files are run in + parallel so you may get interleaved prints. A buildfile may also be executed + more than once in parallel in the context of different toolchains so the + prints from one file may be duplicated or + interleaved with itself. +``` + +#### **Examples** + +``` + print("Hello world") + + print(sources, deps) +``` +### <a name="process_file_template"></a>**process_file_template**: Do template expansion over a list of files. + +``` + process_file_template(source_list, template) + + process_file_template applies a template list to a source file list, + returning the result of applying each template to each source. This is + typically used for computing output file names from input files. + + In most cases, get_target_outputs() will give the same result with shorter, + 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** + +``` + The source_list is a list of file names. + + The template can be a string or a list. If it is a list, multiple output + strings are generated for each input. + + The template should contain source expansions to which each name in the + source list is applied. See "gn help source_expansion". +``` + +#### **Example** + +``` + sources = [ + "foo.idl", + "bar.idl", + ] + myoutputs = process_file_template( + sources, + [ "$target_gen_dir/{{source_name_part}}.cc", + "$target_gen_dir/{{source_name_part}}.h" ]) + + The result in this case will be: + [ "//out/Debug/foo.cc" + "//out/Debug/foo.h" + "//out/Debug/bar.cc" + "//out/Debug/bar.h" ] +``` +### <a name="read_file"></a>**read_file**: Read a file into a variable. + +``` + read_file(filename, input_conversion) + + Whitespace will be trimmed from the end of the file. Throws an error if the + file can not be opened. +``` + +#### **Arguments** + +``` + filename + Filename to read, relative to the build file. + + input_conversion + Controls how the file is read and parsed. See "gn help input_conversion". +``` + +#### **Example** + +``` + lines = read_file("foo.txt", "list lines") +``` +### <a name="rebase_path"></a>**rebase_path**: Rebase a file or directory to another location. + +``` + converted = rebase_path(input, + new_base = "", + current_base = ".") + + Takes a string argument representing a file name, or a list of such strings + and converts it/them to be relative to a different base directory. + + When invoking the compiler or scripts, GN will automatically convert sources + and include directories to be relative to the build directory. However, if + you're passing files directly in the "args" array or doing other manual + manipulations where GN doesn't know something is a file name, you will need + to convert paths to be relative to what your tool is expecting. + + The common case is to use this to convert paths relative to the current + directory to be relative to the build directory (which will be the current + directory when executing scripts). + + If you want to convert a file path to be source-absolute (that is, beginning + with a double slash like "//foo/bar"), you should use the get_path_info() + 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** + +``` + input + A string or list of strings representing file or directory names These + can be relative paths ("foo/bar.txt"), system absolute paths + ("/foo/bar.txt"), or source absolute paths ("//foo/bar.txt"). + + new_base + The directory to convert the paths to be relative to. This can be an + absolute path or a relative path (which will be treated as being relative + to the current BUILD-file's directory). + + As a special case, if new_base is the empty string (the default), all + paths will be converted to system-absolute native style paths with system + path separators. This is useful for invoking external programs. + + current_base + Directory representing the base for relative paths in the input. If this + 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** + +``` + The return value will be the same type as the input value (either a string or + a list of strings). All relative and source-absolute file names will be + converted to be relative to the requested output System-absolute paths will + be unchanged. + + Whether an output path will end in a slash will match whether the + corresponding input path ends in a slash. It will return "." or "./" + (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** + +``` + # Convert a file in the current directory to be relative to the build + # directory (the current dir when executing compilers and scripts). + foo = rebase_path("myfile.txt", root_build_dir) + # might produce "../../project/myfile.txt". + + # Convert a file to be system absolute: + foo = rebase_path("myfile.txt") + # Might produce "D:\\source\\project\\myfile.txt" on Windows or + # "/home/you/source/project/myfile.txt" on Linux. + + # Typical usage for converting to the build directory for a script. + action("myscript") { + # Don't convert sources, GN will automatically convert these to be relative + # to the build directory when it constructs the command line for your + # script. + sources = [ "foo.txt", "bar.txt" ] + + # Extra file args passed manually need to be explicitly converted + # to be relative to the build directory: + args = [ + "--data", + rebase_path("//mything/data/input.dat", root_build_dir), + "--rel", + rebase_path("relative_path.txt", root_build_dir) + ] + rebase_path(sources, root_build_dir) + } +``` +### <a name="set_default_toolchain"></a>**set_default_toolchain**: Sets the default toolchain name. + +``` + set_default_toolchain(toolchain_label) + + The given label should identify a toolchain definition (see "gn help + toolchain"). This toolchain will be used for all targets unless otherwise + specified. + + This function is only valid to call during the processing of the build + configuration file. Since the build configuration file is processed + separately for each toolchain, this function will be a no-op when called + under any non-default toolchains. + + For example, the default toolchain should be appropriate for the current + environment. If the current environment is 32-bit and somebody references a + 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** + +``` + toolchain_label + Toolchain name. +``` + +#### **Example** + +``` + # Set default toolchain only has an effect when run in the context of the + # default toolchain. Pick the right one according to the current CPU + # architecture. + if (target_cpu == "x64") { + set_default_toolchain("//toolchains:64") + } else if (target_cpu == "x86") { + set_default_toolchain("//toolchains:32") + } +``` +### <a name="set_defaults"></a>**set_defaults**: Set default values for a target type. + +``` + set_defaults(<target_type_name>) { <values...> } + + Sets the default values for a given target type. Whenever target_type_name is + seen in the future, the values specified in set_default's block will be + copied into the current scope. + + 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" ] + } +``` +### <a name="set_sources_assignment_filter"></a>**set_sources_assignment_filter**: Set a pattern to filter source files. + +``` + The sources assignment filter is a list of patterns that remove files from + the list implicitly whenever the "sources" variable is assigned to. This will + do nothing for non-lists. + + This is intended to be used to globally filter out files with + platform-specific naming schemes when they don't apply, for example you may + want to filter out all "*_win.cc" files on non-Windows platforms. + + Typically this will be called once in the master build config script to set + up the filter for the current platform. Subsequent calls will overwrite the + previous values. + + 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** + +``` + File patterns are VERY limited regular expressions. They must match the + entire input string to be counted as a match. In regular expression parlance, + there is an implicit "^...$" surrounding your input. If you want to match a + substring, you need to use wildcards at the beginning and end. + + There are only two special tokens understood by the pattern matcher. + Everything else is a literal. + + - "*" Matches zero or more of any character. It does not depend on the + preceding character (in regular expression parlance it is equivalent to + ".*"). + + - "\b" Matches a path boundary. This will match the beginning or end of a + string, or a slash. +``` + +#### **Pattern examples** + +``` + "*asdf*" + Matches a string containing "asdf" anywhere. + + "asdf" + Matches only the exact string "asdf". + + "*.cc" + Matches strings ending in the literal ".cc". + + "\bwin/*" + Matches "win/foo" and "foo/win/bar.cc" but not "iwin/foo". +``` + +#### **Sources assignment example** + +``` + # Filter out all _win files. + set_sources_assignment_filter([ "*_win.cc", "*_win.h" ]) + sources = [ "a.cc", "b_win.cc" ] + print(sources) + # Will print [ "a.cc" ]. b_win one was filtered out. +``` +### <a name="split_list"></a>**split_list**: Splits a list into N different sub-lists. + +``` + result = split_list(input, n) + + Given a list and a number N, splits the list into N sub-lists of + approximately equal size. The return value is a list of the sub-lists. The + result will always be a list of size N. If N is greater than the number of + elements in the input, it will be padded with empty lists. + + The expected use is to divide source files into smaller uniform chunks. +``` + +#### **Example** + +``` + The code: + mylist = [1, 2, 3, 4, 5, 6] + print(split_list(mylist, 3)) + + Will print: + [[1, 2], [3, 4], [5, 6] +``` +### <a name="template"></a>**template**: Define a template rule. + +``` + A template defines a custom name that acts like a function. It provides a way + to add to the built-in target types. + + The template() function is used to declare a template. To invoke the + template, just use the name of the template like any other target type. + + 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**: + +``` + When you call template() it creates a closure around all variables currently + in scope with the code in the template block. When the template is invoked, + the closure will be executed. + + When the template is invoked, the code in the caller is executed and passed + to the template code as an implicit "invoker" variable. The template uses + this to read state out of the invoking code. + + One thing explicitly excluded from the closure is the "current directory" + against which relative file names are resolved. The current directory will be + that of the invoking code, since typically that code specifies the file + names. This means all files internal to the template should use absolute + names. + + A template will typically forward some or all variables from the invoking + scope to a target that it defines. Often, such variables might be optional. + Use the pattern: + + if (defined(invoker.deps)) { + deps = invoker.deps + } + + The function forward_variables_from() provides a shortcut to forward one or + more or possibly all variables in this manner: + + forward_variables_from(invoker, ["deps", "public_deps"]) +``` + +#### **Target naming** + +``` + Your template should almost always define a built-in target with the name the + template invoker specified. For example, if you have an IDL template and + somebody does: + idl("foo") {... + you will normally want this to expand to something defining a source_set or + static_library named "foo" (among other things you may need). This way, when + another target specifies a dependency on "foo", the static_library or + source_set will be linked. + + It is also important that any other targets your template expands to have + unique names, or you will get collisions. + + Access the invoking name in your template via the implicit "target_name" + variable. This should also be the basis for how other targets that a template + expands to ensure uniqueness. + + A typical example would be a template that defines an action to generate some + source files, and a source_set to compile that source. Your template would + name the source_set "target_name" because that's what you want external + 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. +``` + +#### **Overriding builtin targets** + +``` + You can use template to redefine a built-in target in which case your template + takes a precedence over the built-in one. All uses of the target from within + the template definition will refer to the built-in target which makes it + possible to extend the behavior of the built-in target: + + template("shared_library") { + shared_library(shlib) { + forward_variables_from(invoker, [ "*" ]) + ... + } + } +``` + +#### **Example of defining a template** + +``` + template("my_idl") { + # Be nice and help callers debug problems by checking that the variables + # the template requires are defined. This gives a nice message rather than + # giving the user an error about an undefined variable in the file defining + # the template + # + # You can also use defined() to give default values to variables + # unspecified by the invoker. + assert(defined(invoker.sources), + "Need sources in $target_name listing the idl files.") + + # Name of the intermediate target that does the code gen. This must + # incorporate the target name so it's unique across template + # instantiations. + code_gen_target_name = target_name + "_code_gen" + + # Intermediate target to convert IDL to C source. Note that the name is + # based on the name the invoker of the template specified. This way, each + # time the template is invoked we get a unique intermediate action name + # (since all target names are in the global scope). + action_foreach(code_gen_target_name) { + # Access the scope defined by the invoker via the implicit "invoker" + # variable. + sources = invoker.sources + + # Note that we need an absolute path for our script file name. The + # current directory when executing this code will be that of the invoker + # (this is why we can use the "sources" directly above without having to + # rebase all of the paths). But if we need to reference a script relative + # to the template file, we'll need to use an absolute path instead. + script = "//tools/idl/idl_code_generator.py" + + # Tell GN how to expand output names given the sources. + # See "gn help source_expansion" for more. + outputs = [ "$target_gen_dir/{{source_name_part}}.cc", + "$target_gen_dir/{{source_name_part}}.h" ] + } + + # Name the source set the same as the template invocation so instancing + # this template produces something that other targets can link to in their + # deps. + source_set(target_name) { + # Generates the list of sources, we get these from the action_foreach + # above. + sources = get_target_outputs(":$code_gen_target_name") + + # This target depends on the files produced by the above code gen target. + deps = [ ":$code_gen_target_name" ] + } + } +``` + +#### **Example of invoking the resulting template** + +``` + # This calls the template code above, defining target_name to be + # "foo_idl_files" and "invoker" to be the set of stuff defined in the curly + # brackets. + my_idl("foo_idl_files") { + # Goes into the template as "invoker.sources". + sources = [ "foo.idl", "bar.idl" ] + } + + # Here is a target that depends on our template. + executable("my_exe") { + # Depend on the name we gave the template call above. Internally, this will + # produce a dependency from executable to the source_set inside the + # template (since it has this name), which will in turn depend on the code + # gen action. + deps = [ ":foo_idl_files" ] + } +``` +### <a name="tool"></a>**tool**: Specify arguments to a toolchain tool. + +#### **Usage** + +``` + tool(<tool type>) { + <tool variables...> + } +``` + +#### **Tool types** + +``` + Compiler tools: + "cc": C compiler + "cxx": C++ compiler + "objc": Objective C compiler + "objcxx": Objective C++ compiler + "rc": Resource compiler (Windows .rc files) + "asm": Assembler + + 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. +``` + +#### **Tool variables** + +``` + command [string with substitutions] + Valid for: all tools except "action" (required) + + The command to run. + + 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}}" + + 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 specify them. + If you specified: + lib_switch = "-l" + lib_dir_switch = "-L" + then the "{{libs}}" expansion for [ "freetype", "expat"] would be + "-lfreetype -lexpat". + + 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", + ] + + 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}}" + } + + 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. +``` + +#### **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. + + {{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). + + {{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". + + As a special case to support Mac, libraries with names ending in + ".framework" will be added to the {{libs}} with "-framework" preceding + it, and the lib prefix will be ignored. + + 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" + + 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. +``` + +#### **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}}" + } + }; +``` +### <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** + +``` + You can have more than one toolchain in use at once in a build and a target + can exist simultaneously in multiple toolchains. A build file is executed + once for each toolchain it is referenced in so the GN code can vary all + parameters of each target (or which targets exist) on a per-toolchain basis. + + When you have a simple build with only one toolchain, the build config file + is loaded only once at the beginning of the build. It must call + set_default_toolchain() (see "gn help set_default_toolchain") to tell GN the + label of the toolchain definition to use. The "toolchain_args" section of the + toolchain definition is ignored. + + When a target has a dependency on a target using different toolchain (see "gn + help labels" for how to specify this), GN will start a build using that + secondary toolchain to resolve the target. GN will load the build config file + with the build arguments overridden as specified in the toolchain_args. + Because the default toolchain is already known, calls to + set_default_toolchain() are ignored. + + To load a file in an alternate toolchain, GN does the following: + + 1. Loads the file with the toolchain definition in it (as determined by the + toolchain label). + 2. Re-runs the master build configuration file, applying the arguments + specified by the toolchain_args section of the toolchain definition. + 3. Loads the destination build file in the context of the configuration file + in the previous step. + + The toolchain configuration is two-way. In the default toolchain (i.e. the + main build target) the configuration flows from the build config file to the + toolchain. The build config file looks at the state of the build (OS type, + CPU architecture, etc.) and decides which toolchain to use (via + set_default_toolchain()). In secondary toolchains, the configuration flows + from the toolchain to the build config file: the "toolchain_args" in the + toolchain definition specifies the arguments to re-invoke the build. +``` + +#### **Functions and variables** + +``` + tool() + The tool() function call specifies the commands commands to run for a given + step. See "gn help tool". + + toolchain_args + Overrides for build arguments to pass to the toolchain when invoking it. + This is a variable of type "scope" where the variable names correspond to + variables in declare_args() blocks. + + When you specify a target using an alternate toolchain, the master build + configuration file is re-interpreted in the context of that toolchain. + toolchain_args allows you to control the arguments passed into this + alternate invocation of the build. + + Any default system arguments or arguments passed in via "gn args" will also + be passed to the alternate invocation unless explicitly overridden by + toolchain_args. + + The toolchain_args will be ignored when the toolchain being defined is the + default. In this case, it's expected you want the default argument values. + + See also "gn help buildargs" for an overview of these arguments. + + deps + Dependencies of this toolchain. These dependencies will be resolved before + any target in the toolchain is compiled. To avoid circular dependencies + these must be targets defined in another toolchain. + + This is expressed as a list of targets, and generally these targets will + always specify a toolchain: + deps = [ "//foo/bar:baz(//build/toolchain:bootstrap)" ] + + This concept is somewhat inefficient to express in Ninja (it requires a lot + of duplicate of rules) so should only be used when absolutely necessary. +``` + +#### **Example of defining a toolchain** + +``` + toolchain("32") { + tool("cc") { + command = "gcc {{source}}" + ... + } + + toolchain_args = { + use_doom_melon = true # Doom melon always required for 32-bit builds. + current_cpu = "x86" + } + } + + toolchain("64") { + tool("cc") { + command = "gcc {{source}}" + ... + } + + toolchain_args = { + # use_doom_melon is not overridden here, it will take the default. + current_cpu = "x64" + } + } +``` + +#### **Example of cross-toolchain dependencies** + +``` + If a 64-bit target wants to depend on a 32-bit binary, it would specify a + dependency using data_deps (data deps are like deps that are only needed at + runtime and aren't linked, since you can't link a 32-bit and a 64-bit + library). + + executable("my_program") { + ... + if (target_cpu == "x64") { + # The 64-bit build needs this 32-bit helper. + data_deps = [ ":helper(//toolchains:32)" ] + } + } + + if (target_cpu == "x86") { + # Our helper library is only compiled in 32-bits. + shared_library("helper") { + ... + } + } +``` +### <a name="write_file"></a>**write_file**: Write a file to disk. + +``` + write_file(filename, data) + + If data is a list, the list will be written one-item-per-line with no quoting + or brackets. + + If the file exists and the contents are identical to that being written, the + file will not be updated. This will prevent unnecessary rebuilds of targets + that depend on this file. + + One use for write_file is to write a list of inputs to an script that might + be too long for the command line. However, it is preferable to use response + files for this purpose. See "gn help response_file_contents". + + TODO(brettw) we probably need an optional third argument to control list + formatting. +``` + +#### **Arguments** + +``` + filename + Filename to write. This must be within the output directory. + + data + The list or string to write. +``` +## <a name="predefined_variables"></a>Built-in predefined variables + +### <a name="current_cpu"></a>**current_cpu**: The processor architecture of the current toolchain. + +``` + The build configuration usually sets this value based on the value of + "host_cpu" (see "gn help host_cpu") and then threads this through the + toolchain definitions to ensure that it always reflects the appropriate + value. + + This value is not used internally by GN for any purpose. It is set it to the + empty string ("") by default but is declared so that it can be overridden on + 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. + +``` + The build configuration usually sets this value based on the value of + "target_os" (see "gn help target_os"), and then threads this through the + toolchain definitions to ensure that it always reflects the appropriate + value. + + This value is not used internally by GN for any purpose. It is set it to the + empty string ("") by default but is declared so that it can be overridden on + the command line if so desired. + + See "gn help target_os" for a list of common values returned. +``` +### <a name="current_toolchain"></a>**current_toolchain**: Label of the current toolchain. + +``` + A fully-qualified label representing the current toolchain. You can use this + to make toolchain-related decisions in the build. See also + "default_toolchain". +``` + +#### **Example** + +``` + if (current_toolchain == "//build:64_bit_toolchain") { + executable("output_thats_64_bit_only") { + ... +``` +### <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. + +``` + This is value is exposed so that cross-compile toolchains can access the host + architecture when needed. + + The value should generally be considered read-only, but it can be overriden + in order to handle unusual cases where there might be multiple plausible + values for the host architecture (e.g., if you can do either 32-bit or 64-bit + builds). The value is not used internally by GN for any purpose. +``` + +#### **Some possible values** + +``` + - "x64" + - "x86" +``` +### <a name="host_os"></a>**host_os**: [string] The operating system that GN is running on. + +``` + This value is exposed so that cross-compiles can access the host build + system's settings. + + This value should generally be treated as read-only. It, however, is not used + internally by GN for any purpose. +``` + +#### **Some possible values** + +``` + - "linux" + - "mac" + - "win" +``` +### <a name="invoker"></a>**invoker**: [string] The invoking scope inside a template. + +``` + Inside a template invocation, this variable refers to the scope of the + invoker of the template. Outside of template invocations, this variable is + undefined. + + All of the variables defined inside the template invocation are accessible as + members of the "invoker" scope. This is the way that templates read values + set by the callers. + + This is often used with "defined" to see if a value is set on the invoking + scope. + + See "gn help template" for more examples. +``` + +#### **Example** + +``` + template("my_template") { + print(invoker.sources) # Prints [ "a.cc", "b.cc" ] + print(defined(invoker.foo)) # Prints false. + print(defined(invoker.bar)) # Prints true. + } + + my_template("doom_melon") { + sources = [ "a.cc", "b.cc" ] + bar = 123 + } +``` +### <a name="python_path"></a>**python_path**: Absolute path of Python. + +``` + Normally used in toolchain definitions if running some command requires + Python. You will normally not need this when invoking scripts since GN + automatically finds it for you. +``` +### <a name="root_build_dir"></a>**root_build_dir**: [string] Directory where build commands are run. + +``` + This is the root build output directory which will be the current directory + when executing all compilers and scripts. + + Most often this is used with rebase_path (see "gn help rebase_path") to + convert arguments to be relative to a script's current directory. +``` +### <a name="root_gen_dir"></a>**root_gen_dir**: Directory for the toolchain's generated files. + +``` + Absolute path to the root of the generated output directory tree for the + current toolchain. An example would be "//out/Debug/gen" for the default + toolchain, or "//out/Debug/arm/gen" for the "arm" toolchain. + + This is primarily useful for setting up include paths for generated files. If + you are passing this to a script, you will want to pass it through + rebase_path() (see "gn help rebase_path") to convert it to be relative to the + build directory. + + See also "target_gen_dir" which is usually a better location for generated + files. It will be inside the root generated dir. +``` +### <a name="root_out_dir"></a>**root_out_dir**: [string] Root directory for toolchain output files. + +``` + Absolute path to the root of the output directory tree for the current + toolchain. It will not have a trailing slash. + + For the default toolchain this will be the same as the root_build_dir. An + example would be "//out/Debug" for the default toolchain, or + "//out/Debug/arm" for the "arm" toolchain. + + This is primarily useful for setting up script calls. If you are passing this + to a script, you will want to pass it through rebase_path() (see "gn help + rebase_path") to convert it to be relative to the build directory. + + See also "target_out_dir" which is usually a better location for output + files. It will be inside the root output dir. +``` + +#### **Example** + +``` + action("myscript") { + # Pass the output dir to the script. + args = [ "-o", rebase_path(root_out_dir, root_build_dir) ] + } +``` +### <a name="target_cpu"></a>**target_cpu**: The desired cpu architecture for the build. + +``` + This value should be used to indicate the desired architecture for the + primary objects of the build. It will match the cpu architecture of the + default toolchain, but not necessarily the current toolchain. + + In many cases, this is the same as "host_cpu", but in the case of + cross-compiles, this can be set to something different. This value is + different from "current_cpu" in that it does not change based on the current + toolchain. When writing rules, "current_cpu" should be used rather than + "target_cpu" most of the time. + + This value is not used internally by GN for any purpose, so it may be set to + whatever value is needed for the build. GN defaults this value to the empty + 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** + +``` + - "x86" + - "x64" + - "arm" + - "arm64" + - "mipsel" +``` +### <a name="target_gen_dir"></a>**target_gen_dir**: Directory for a target's generated files. + +``` + Absolute path to the target's generated file directory. This will be the + "root_gen_dir" followed by the relative path to the current build file. If + your file is in "//tools/doom_melon" then target_gen_dir would be + "//out/Debug/gen/tools/doom_melon". It will not have a trailing slash. + + This is primarily useful for setting up include paths for generated files. If + you are passing this to a script, you will want to pass it through + rebase_path() (see "gn help rebase_path") to convert it to be relative to the + build directory. + + See also "gn help root_gen_dir". +``` + +#### **Example** + +``` + action("myscript") { + # Pass the generated output dir to the script. + args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]" + } +``` +### <a name="target_name"></a>**target_name**: [string] The name of the current target. + +``` + Inside a target or template invocation, this variable refers to the name + given to the target or template invocation. Outside of these, this variable + is undefined. + + This is most often used in template definitions to name targets defined in + the template based on the name of the invocation. This is necessary both to + ensure generated targets have unique names and to generate a target with the + exact name of the invocation that other targets can depend on. + + Be aware that this value will always reflect the innermost scope. So when + defining a target inside a template, target_name will refer to the target + rather than the template invocation. To get the name of the template + invocation in this case, you should save target_name to a temporary variable + outside of any target definitions. + + See "gn help template" for more examples. +``` + +#### **Example** + +``` + executable("doom_melon") { + print(target_name) # Prints "doom_melon". + } + + template("my_template") { + print(target_name) # Prints "space_ray" when invoked below. + + executable(target_name + "_impl") { + print(target_name) # Prints "space_ray_impl". + } + } + + my_template("space_ray") { + } +``` +### <a name="target_os"></a>**target_os**: The desired operating system for the build. + +``` + This value should be used to indicate the desired operating system for the + primary object(s) of the build. It will match the OS of the default + toolchain. + + In many cases, this is the same as "host_os", but in the case of + cross-compiles, it may be different. This variable differs from "current_os" + in that it can be referenced from inside any toolchain and will always return + the initial value. + + This should be set to the most specific value possible. So, "android" or + "chromeos" should be used instead of "linux" where applicable, even though + Android and ChromeOS are both Linux variants. This can mean that one needs to + write + + if (target_os == "android" || target_os == "linux") { + # ... + } + + and so forth. + + This value is not used internally by GN for any purpose, so it may be set to + whatever value is needed for the build. GN defaults this value to the empty + 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** + +``` + - "android" + - "chromeos" + - "ios" + - "linux" + - "nacl" + - "mac" + - "win" +``` +### <a name="target_out_dir"></a>**target_out_dir**: [string] Directory for target output files. + +``` + Absolute path to the target's generated file directory. If your current + target is in "//tools/doom_melon" then this value might be + "//out/Debug/obj/tools/doom_melon". It will not have a trailing slash. + + This is primarily useful for setting up arguments for calling scripts. If you + are passing this to a script, you will want to pass it through rebase_path() + (see "gn help rebase_path") to convert it to be relative to the build + directory. + + See also "gn help root_out_dir". +``` + +#### **Example** + +``` + action("myscript") { + # Pass the output dir to the script. + args = [ "-o", rebase_path(target_out_dir, root_build_dir) ]" + + } +``` +## <a name="target_variables"></a>Variables you set in targets + +### <a name="all_dependent_configs"></a>**all_dependent_configs**: Configs to be forced on dependents. + +``` + A list of config labels. + + All targets depending on this one, and recursively, all targets depending on + those, will have the configs listed in this variable added to them. These + configs will also apply to the current target. + + This addition happens in a second phase once a target and all of its + dependencies have been resolved. Therefore, a target will not see these + force-added configs in their "configs" variable while the script is running, + and they can not be removed. As a result, this capability should generally + only be used to add defines and include directories necessary to compile a + target's headers. + + See also "public_configs". +``` + +#### **Ordering of flags and values** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 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. + +``` + A list of target labels. Must be a subset of the target's "deps". These + targets will be permitted to include headers from the current target despite + the dependency going in the opposite direction. + + When you use this, both targets must be included in a final binary for it to + link. To keep linker errors from happening, it is good practice to have all + 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** + +``` + Normally, for a file in target A to include a file from target B, A must list + B as a dependency. This invariant is enforced by the "gn check" command (and + the --check flag to "gn gen" -- see "gn help check"). + + Sometimes, two targets might be the same unit for linking purposes (two + source sets or static libraries that would always be linked together in a + final executable or shared library) and they each include headers from the + other: you want A to be able to include B's headers, and B to include A's + headers. This is not an ideal situation but is sometimes unavoidable. + + This list, if specified, lists which of the dependencies of the current + target can include header files from the current target. That is, if A + depends on B, B can only include headers from A if it is in A's + allow_circular_includes_from list. Normally includes must follow the + direction of dependencies, this flag allows them to go in the opposite + direction. +``` + +#### **Danger** + +``` + In the above example, A's headers are likely to include headers from A's + dependencies. Those dependencies may have public_configs that apply flags, + defines, and include paths that make those headers work properly. + + With allow_circular_includes_from, B can include A's headers, and + transitively from A's dependencies, without having the dependencies that + would bring in the public_configs those headers need. The result may be + errors or inconsistent builds. + + So when you use allow_circular_includes_from, make sure that any compiler + settings, flags, and include directories are the same between both targets + (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** + +``` + source_set("a") { + deps = [ ":b", ":a_b_shared_deps" ] + allow_circular_includes_from = [ ":b" ] + ... + } + + source_set("b") { + deps = [ ":a_b_shared_deps" ] + # Sources here can include headers from a despite lack of deps. + ... + } + + group("a_b_shared_deps") { + public_deps = [ ":c" ] + } +``` +### <a name="arflags"></a>**arflags**: Arguments passed to static_library archiver. + +``` + A list of flags passed to the archive/lib command that creates static + libraries. + + arflags are NOT pushed to dependents, so applying arflags to source sets or + any other target type will be a no-op. As with ldflags, you could put the + arflags in a config and set that as a public or "all dependent" config, but + that will likely not be what you want. If you have a chain of static + libraries dependent on each other, this can cause the flags to propagate up + 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** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 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. + +``` + For action and action_foreach targets, args is the list of arguments to pass + to the script. Typically you would use source expansion (see "gn help + source_expansion") to insert the source file names. + + See also "gn help action" and "gn help action_foreach". +``` +### <a name="asmflags"></a>**asmflags**: Flags passed to the assembler. + +``` + A list of strings. + + "asmflags" are passed to any invocation of a tool that takes an .asm or .S + file as input. +``` + +#### **Ordering of flags and values** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 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. + +``` + A list of label patterns. + + This list is a list of patterns that must not match any of the transitive + dependencies of the target. These include all public, private, and data + dependencies, and cross shared library boundaries. This allows you to express + that undesirable code isn't accidentally added to downstream dependencies in + a way that might otherwise be difficult to notice. + + Checking does not cross executable boundaries. If a target depends on an + executable, it's assumed that the executable is a tool that is producing part + of the build rather than something that is linked and distributed. This + allows assert_no_deps to express what is distributed in the final target + rather than depend on the internal build steps (which may include + non-distributable code). + + See "gn help label_pattern" for the format of the entries in the list. These + patterns allow blacklisting individual targets or whole directory + hierarchies. + + Sometimes it is desirable to enforce that many targets have no dependencies + 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** + +``` + executable("doom_melon") { + deps = [ "//foo:bar" ] + ... + assert_no_deps = [ + "//evil/*", # Don't link any code from the evil directory. + "//foo:test_support", # This target is also disallowed. + ] + } +``` +### <a name="bundle_contents_dir"></a>**bundle_contents_dir**: Expansion of {{bundle_contents_dir}} in +``` + create_bundle. + + A string corresponding to a path in $root_build_dir. + + This string is used by the "create_bundle" target to expand the + {{bundle_contents_dir}} of the "bundle_data" target it depends on. This must + correspond to a path under "bundle_root_dir". + + See "gn help bundle_root_dir" for examples. +``` +### <a name="bundle_deps_filter"></a>**bundle_deps_filter**: [label list] A list of labels that are filtered out. + +``` + A list of target labels. + + This list contains target label patterns that should be filtered out when + creating the bundle. Any target matching one of those label will be removed + from the dependencies of the create_bundle target. + + This is mostly useful when creating application extension bundle as the + application extension has access to runtime resources from the application + bundle and thus do not require a second copy. + + See "gn help create_bundle" for more information. +``` + +#### **Example** + +``` + create_bundle("today_extension") { + deps = [ + "//base" + ] + bundle_root_dir = "$root_out_dir/today_extension.appex" + bundle_deps_filter = [ + # The extension uses //base but does not use any function calling into + # third_party/icu and thus does not need the icudtl.dat file. + "//third_party/icu:icudata", + ] + } +``` +### <a name="bundle_executable_dir"></a>**bundle_executable_dir**: Expansion of {{bundle_executable_dir}} in +``` + create_bundle. + + A string corresponding to a path in $root_build_dir. + + This string is used by the "create_bundle" target to expand the + {{bundle_executable_dir}} of the "bundle_data" target it depends on. This + must correspond to a path under "bundle_root_dir". + + See "gn help bundle_root_dir" for examples. +``` +### <a name="bundle_plugins_dir"></a>**bundle_plugins_dir**: Expansion of {{bundle_plugins_dir}} in create_bundle. + +``` + A string corresponding to a path in $root_build_dir. + + This string is used by the "create_bundle" target to expand the + {{bundle_plugins_dir}} of the "bundle_data" target it depends on. This must + correspond to a path under "bundle_root_dir". + + See "gn help bundle_root_dir" for examples. +``` +### <a name="bundle_resources_dir"></a>**bundle_resources_dir**: Expansion of {{bundle_resources_dir}} in +``` + create_bundle. + + A string corresponding to a path in $root_build_dir. + + This string is used by the "create_bundle" target to expand the + {{bundle_resources_dir}} of the "bundle_data" target it depends on. This must + correspond to a path under "bundle_root_dir". + + See "gn help bundle_root_dir" for examples. +``` +### <a name="bundle_root_dir"></a>**bundle_root_dir**: Expansion of {{bundle_root_dir}} in create_bundle. + +``` + A string corresponding to a path in root_build_dir. + + This string is used by the "create_bundle" target to expand the + {{bundle_root_dir}} of the "bundle_data" target it depends on. This must + correspond to a path under root_build_dir. +``` + +#### **Example** + +``` + bundle_data("info_plist") { + sources = [ "Info.plist" ] + outputs = [ "{{bundle_contents_dir}}/Info.plist" ] + } + + create_bundle("doom_melon.app") { + deps = [ ":info_plist" ] + bundle_root_dir = "${root_build_dir}/doom_melon.app" + bundle_contents_dir = "${bundle_root_dir}/Contents" + bundle_resources_dir = "${bundle_contents_dir}/Resources" + bundle_executable_dir = "${bundle_contents_dir}/MacOS" + bundle_plugins_dir = "${bundle_contents_dir}/PlugIns" + } +``` +### <a name="cflags*"></a>**cflags***: Flags passed to the C compiler. + +``` + A list of strings. + + "cflags" are passed to all invocations of the C, C++, Objective C, and + Objective C++ compilers. + + To target one of these variants individually, use "cflags_c", "cflags_cc", + "cflags_objc", and "cflags_objcc", respectively. These variant-specific + versions of cflags* will be appended on the compiler command line after + "cflags". + + See also "asmflags" for flags for assembly-language files. +``` + +#### **Ordering of flags and values** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 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. + +``` + A list of strings. + + "cflags" are passed to all invocations of the C, C++, Objective C, and + Objective C++ compilers. + + To target one of these variants individually, use "cflags_c", "cflags_cc", + "cflags_objc", and "cflags_objcc", respectively. These variant-specific + versions of cflags* will be appended on the compiler command line after + "cflags". + + See also "asmflags" for flags for assembly-language files. +``` + +#### **Ordering of flags and values** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 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. + +``` + A list of strings. + + "cflags" are passed to all invocations of the C, C++, Objective C, and + Objective C++ compilers. + + To target one of these variants individually, use "cflags_c", "cflags_cc", + "cflags_objc", and "cflags_objcc", respectively. These variant-specific + versions of cflags* will be appended on the compiler command line after + "cflags". + + See also "asmflags" for flags for assembly-language files. +``` + +#### **Ordering of flags and values** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 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. + +``` + A list of strings. + + "cflags" are passed to all invocations of the C, C++, Objective C, and + Objective C++ compilers. + + To target one of these variants individually, use "cflags_c", "cflags_cc", + "cflags_objc", and "cflags_objcc", respectively. These variant-specific + versions of cflags* will be appended on the compiler command line after + "cflags". + + See also "asmflags" for flags for assembly-language files. +``` + +#### **Ordering of flags and values** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 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. + +``` + A list of strings. + + "cflags" are passed to all invocations of the C, C++, Objective C, and + Objective C++ compilers. + + To target one of these variants individually, use "cflags_c", "cflags_cc", + "cflags_objc", and "cflags_objcc", respectively. These variant-specific + versions of cflags* will be appended on the compiler command line after + "cflags". + + See also "asmflags" for flags for assembly-language files. +``` + +#### **Ordering of flags and values** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 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. + +``` + When true (the default), the "gn check" command (as well as "gn gen" with the + --check flag) will check this target's sources and headers for proper + dependencies. + + When false, the files in this target will be skipped by default. This does + not affect other targets that depend on the current target, it just skips + checking the includes of the current target's files. + + If there are a few conditionally included headers that trip up checking, you + can exclude headers individually by annotating them with "nogncheck" (see "gn + help nogncheck"). + + The topic "gn help check" has general information on how checking works and + advice on how to pass a check in problematic cases. +``` + +#### **Example** + +``` + source_set("busted_includes") { + # This target's includes are messed up, exclude it from checking. + check_includes = false + ... + } +``` +### <a name="code_signing_args"></a>**code_signing_args**: [string list] Arguments passed to code signing script. + +``` + For create_bundle targets, code_signing_args is the list of arguments to pass + to the code signing script. Typically you would use source expansion (see "gn + help source_expansion") to insert the source file names. + + See also "gn help create_bundle". +``` +### <a name="code_signing_outputs"></a>**code_signing_outputs**: [file list] Output files for code signing step. + +``` + Outputs from the code signing step of a create_bundle target. Must refer to + files in the build directory. + + See also "gn help create_bundle". +``` +### <a name="code_signing_script"></a>**code_signing_script**: [file name] Script for code signing." + +``` + An absolute or buildfile-relative file name of a Python script to run for a + create_bundle target to perform code signing step. + + See also "gn help create_bundle". +``` +### <a name="code_signing_sources"></a>**code_signing_sources**: [file list] Sources for code signing step. + +``` + A list of files used as input for code signing script step of a create_bundle + target. Non-absolute paths will be resolved relative to the current build + file. + + See also "gn help create_bundle". +``` +### <a name="complete_static_lib"></a>**complete_static_lib**: [boolean] Links all deps into a static library. + +``` + A static library normally doesn't include code from dependencies, but instead + forwards the static libraries and source sets in its deps up the dependency + chain until a linkable target (an executable or shared library) is reached. + The final linkable target only links each static library once, even if it + appears more than once in its dependency graph. + + In some cases the static library might be the final desired output. For + example, you may be producing a static library for distribution to third + parties. In this case, the static library should include code for all + dependencies in one complete package. However, complete static libraries + themselves are never linked into other complete static libraries. All + complete static libraries are for distribution and linking them in would + cause code duplication in this case. If the static library is not for + distribution, it should not be complete. + + GN treats non-complete static libraries as source sets when they are linked + into complete static libraries. This is done because some tools like AR do + not handle dependent static libraries properly. This makes it easier to write + "alink" rules. + + 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** + +``` + static_library("foo") { + 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** + +``` + When used on a target, the include_dirs, defines, etc. in each config are + appended in the order they appear to the compile command for each file in the + target. They will appear after the include_dirs, defines, etc. that the + target sets directly. + + Since configs apply after the values set on a target, directly setting a + compiler flag will prepend it to the command line. If you want to append a + flag instead, you can put that flag in a one-off config and append that + config to the target's configs list. + + 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** + +``` + It is possible to create composite configs by specifying configs on a config. + One might do this to forward values, or to factor out blocks of settings from + very large configs into more manageable named chunks. + + In this case, the composite config is expanded to be the concatenation of its + own values, and in order, the values from its sub-configs *before* anything + else happens. This has some ramifications: + + - A target has no visibility into a config's sub-configs. Target code only + sees the name of the composite config. It can't remove sub-configs or opt + in to only parts of it. The composite config may not even be defined + before the target is. + + - You can get duplication of values if a config is listed twice, say, on a + target and in a sub-config that also applies. In other cases, the configs + applying to a target are de-duped. It's expected that if a config is + 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** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 6. public_configs pulled from dependencies, in the order of the + "deps" list. If a dependency is public, they will be applied + recursively. +``` + +#### **Example** + +``` + # Configs on a target. + source_set("foo") { + # Don't use the default RTTI config that BUILDCONFIG applied to us. + configs -= [ "//build:no_rtti" ] + + # Add some of our own settings. + configs += [ ":mysettings" ] + } + + # Create a default_optimization config that forwards to one of a set of more + # specialized configs depending on build flags. This pattern is useful + # because it allows a target to opt in to either a default set, or a more + # specific set, while avoid duplicating the settings in two places. + config("super_optimization") { + cflags = [ ... ] + } + config("default_optimization") { + if (optimize_everything) { + configs = [ ":super_optimization" ] + } else { + configs = [ ":no_optimization" ] + } + } +``` +### <a name="data"></a>**data**: Runtime data file dependencies. + +``` + Lists files or directories required to run the given target. These are + typically data files or directories of data files. The paths are interpreted + as being relative to the current build file. Since these are runtime + dependencies, they do not affect which targets are built or when. To declare + input files to a script, use "inputs". + + Appearing in the "data" section does not imply any special handling such as + copying them to the output directory. This is just used for declaring runtime + dependencies. Runtime dependencies can be queried using the "runtime_deps" + category of "gn desc" or written during build generation via + "--runtime-deps-list-file". + + GN doesn't require data files to exist at build-time. So actions that produce + files that are in turn runtime dependencies can list those generated files + both in the "outputs" list as well as the "data" list. + + By convention, directories are listed with a trailing slash: + data = [ "test/data/" ] + However, no verification is done on these so GN doesn't enforce this. The + paths are just rebased and passed along when requested. + + Note: On iOS and macOS, create_bundle targets will not be recursed into when + gathering data. See "gn help create_bundle" for details. + + See "gn help runtime_deps" for how these are used. +``` +### <a name="data_deps"></a>**data_deps**: Non-linked dependencies. + +``` + A list of target labels. + + Specifies dependencies of a target that are not actually linked into the + current target. Such dependencies will be built and will be available at + runtime. + + This is normally used for things like plugins or helper programs that a + target needs at runtime. + + Note: On iOS and macOS, create_bundle targets will not be recursed into when + gathering data_deps. See "gn help create_bundle" for details. + + See also "gn help deps" and "gn help data". +``` + +#### **Example** + +``` + executable("foo") { + deps = [ "//base" ] + data_deps = [ "//plugins:my_runtime_plugin" ] + } +``` +### <a name="defines"></a>**defines**: C preprocessor defines. + +``` + A list of strings + + These strings will be passed to the C/C++ compiler as #defines. The strings + may or may not include an "=" to assign a value. +``` + +#### **Ordering of flags and values** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 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. + +``` + If nonempty, this string specifies that the current action or action_foreach + target will generate the given ".d" file containing the dependencies of the + input. Empty or unset means that the script doesn't generate the files. + + A depfile should be used only when a target depends on files that are not + already specified by a target's inputs and sources. Likewise, depfiles should + specify only those dependencies not already included in sources or inputs. + + The .d file should go in the target output directory. If you have more than + one source file that the script is being run over, you can use the output + file expansions described in "gn help action_foreach" to name the .d file + according to the input." + + The format is that of a Makefile and all paths must be relative to the root + build directory. Only one output may be listed and it must match the first + output of the action. + + 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** + +``` + action_foreach("myscript_target") { + script = "myscript.py" + sources = [ ... ] + + # Locate the depfile in the output directory named like the + # inputs but with a ".d" appended. + depfile = "$relative_target_output_dir/{{source_name}}.d" + + # Say our script uses "-o <d file>" to indicate the depfile. + args = [ "{{source}}", "-o", depfile ] + } +``` +### <a name="deps"></a>**deps**: Private linked dependencies. + +``` + A list of target labels. + + Specifies private dependencies of a target. Private dependencies are + propagated up the dependency tree and linked to dependent targets, but do not + grant the ability to include headers from the dependency. Public configs are + not forwarded. +``` + +#### **Details of dependency propagation** + +``` + Source sets, shared libraries, and non-complete static libraries will be + propagated up the dependency tree across groups, non-complete static + libraries and source sets. + + Executables, shared libraries, and complete static libraries will link all + propagated targets and stop propagation. Actions and copy steps also stop + propagation, allowing them to take a library as an input but not force + dependents to link to it. + + Propagation of all_dependent_configs and public_configs happens independently + of target type. all_dependent_configs are always propagated across all types + of targets, and public_configs are always propagated across public deps of + all types of targets. + + Data dependencies are propagated differently. See "gn help data_deps" and + "gn help runtime_deps". + + See also "public_deps". +``` +### <a name="friend"></a>**friend**: Allow targets to include private headers. + +``` + A list of label patterns (see "gn help label_pattern") that allow dependent + targets to include private headers. Applies to all binary targets. + + Normally if a target lists headers in the "public" list (see "gn help + public"), other headers are implicitly marked as private. Private headers + can not be included by other targets, even with a public dependency path. + The "gn check" function performs this validation. + + A friend declaration allows one or more targets to include private headers. + This is useful for things like unit tests that are closely associated with a + target and require internal knowledge without opening up all headers to be + included by all dependents. + + A friend target does not allow that target to include headers when no + dependency exists. A public dependency path must still exist between two + targets to include any headers from a destination target. The friend + annotation merely allows the use of headers that would otherwise be + prohibited because they are private. + + The friend annotation is matched only against the target containing the file + with the include directive. Friend annotations are not propagated across + public or private dependencies. Friend annotations do not affect visibility. +``` + +#### **Example** + +``` + static_library("lib") { + # This target can include our private headers. + friend = [ ":unit_tests" ] + + public = [ + "public_api.h", # Normal public API for dependent targets. + ] + + # Private API and sources. + sources = [ + "a_source_file.cc", + + # Normal targets that depend on this one won't be able to include this + # because this target defines a list of "public" headers. Without the + # "public" list, all headers are implicitly public. + "private_api.h", + ] + } + + executable("unit_tests") { + sources = [ + # This can include "private_api.h" from the :lib target because it + # depends on that target and because of the friend annotation. + "my_test.cc", + ] + + deps = [ + ":lib", # Required for the include to be allowed. + ] + } +``` +### <a name="include_dirs"></a>**include_dirs**: Additional include directories. + +``` + A list of source directories. + + The directories in this list will be added to the include path for the files + in the affected target. +``` + +#### **Ordering of flags and values** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 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. + +``` + Inputs are compile-time dependencies of the current target. This means that + all inputs must be available before compiling any of the sources or executing + any actions. + + Inputs are typically only used for action and action_foreach targets. +``` + +#### **Inputs for actions** + +``` + For action and action_foreach targets, inputs should be the inputs to script + that don't vary. These should be all .py files that the script uses via + imports (the main script itself will be an implicit dependency of the action + so need not be listed). + + For action targets, inputs and sources are treated the same, but from a style + perspective, it's recommended to follow the same rule as action_foreach and + put helper files in the inputs, and the data used by the script (if any) in + sources. + + Note that another way to declare input dependencies from an action is to have + the action write a depfile (see "gn help depfile"). This allows the script to + dynamically write input dependencies, that might not be known until actually + 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** + +``` + It may be tempting to write a script that enumerates all files in a directory + as inputs. Don't do this! Even if you specify all the files in the inputs or + sources in the GN target (or worse, enumerate the files in an exec_script + call when running GN, which will be slow), the dependencies will be broken. + + The problem happens if a file is ever removed because the inputs are not + listed on the command line to the script. Because the script hasn't changed + and all inputs are up to date, the script will not re-run and you will get a + stale build. Instead, either list all inputs on the command line to the + 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** + +``` + Any input dependencies will be resolved before compiling any sources. + Normally, all actions that a target depends on will be run before any files + in a target are compiled. So if you depend on generated headers, you do not + typically need to list them in the inputs section. + + Inputs for binary targets will be treated as implicit dependencies, meaning + 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** + +``` + action("myscript") { + script = "domything.py" + inputs = [ "input.data" ] + } +``` +### <a name="ldflags"></a>**ldflags**: Flags passed to the linker. + +``` + A list of strings. + + These flags are passed on the command-line to the linker and generally + specify various linking options. Most targets will not need these and will + use "libs" and "lib_dirs" instead. + + ldflags are NOT pushed to dependents, so applying ldflags to source sets or + 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** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 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. + +``` + A list of directories. + + Specifies additional directories passed to the linker for searching for the + required libraries. If an item is not an absolute path, it will be treated as + being relative to the current build file. + + libs and lib_dirs work differently than other flags in two respects. + First, then are inherited across static library boundaries until a + 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** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 6. public_configs pulled from dependencies, in the order of the + "deps" list. If a dependency is public, they will be applied + recursively. + + 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. + +``` + A list of library names or library paths. + + These libraries will be linked into the final binary (executable or shared + library) containing the current target. + + libs and lib_dirs work differently than other flags in two respects. + First, then are inherited across static library boundaries until a + 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** + +``` + There are several different things that can be expressed in libs: + + File paths + Values containing '/' will be treated as references to files in the + checkout. They will be rebased to be relative to the build directory and + specified in the "libs" for linker tools. This facility should be used + for libraries that are checked in to the version control. For libraries + that are generated by the build, use normal GN deps to link them. + + System libraries + Values not containing '/' will be treated as system library names. These + will be passed unmodified to the linker and prefixed with the + "lib_switch" attribute of the linker tool. Generally you would set the + "lib_dirs" so the given library is found. Your BUILD.gn file should not + specify the switch (like "-l"): this will be encoded in the "lib_switch" + of the tool. + + Apple frameworks + System libraries ending in ".framework" will be special-cased: the switch + "-framework" will be prepended instead of the lib_switch, and the + ".framework" suffix will be trimmed. This is to support the way Mac links + framework dependencies. +``` + +#### **Ordering of flags and values** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 6. public_configs pulled from dependencies, in the order of the + "deps" list. If a dependency is public, they will be applied + recursively. + + 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** + +``` + On Windows: + libs = [ "ctl3d.lib" ] + + On Linux: + libs = [ "ld" ] +``` +### <a name="output_dir"></a>**output_dir**: [directory] Directory to put output file in. + +``` + For library and executable targets, overrides the directory for the final + output. This must be in the root_build_dir or a child thereof. + + This should generally be in the root_out_dir or a subdirectory thereof (the + root_out_dir will be the same as the root_build_dir for the default + toolchain, and will be a subdirectory for other toolchains). Not putting the + output in a subdirectory of root_out_dir can result in collisions between + different toolchains, so you will need to take steps to ensure that your + target is only present in one toolchain. + + Normally the toolchain specifies the output directory for libraries and + executables (see "gn help tool"). You will have to consult that for the + default location. The default location will be used if output_dir is + undefined or empty. +``` + +#### **Example** + +``` + shared_library("doom_melon") { + output_dir = "$root_out_dir/plugin_libs" + ... + } +``` +### <a name="output_extension"></a>**output_extension**: Value to use for the output's file extension. + +``` + Normally the file extension for a target is based on the target type and the + operating system, but in rare cases you will need to override the name (for + example to use "libfreetype.so.6" instead of libfreetype.so on Linux). + + This value should not include a leading dot. If undefined, the default + specified on the tool will be used. If set to the empty string, no output + extension will be used. + + 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** + +``` + shared_library("freetype") { + if (is_linux) { + # Call the output "libfreetype.so.6" + output_extension = "so.6" + } + ... + } + + # On Windows, generate a "mysettings.cpl" control panel applet. Control panel + # applets are actually special shared libraries. + if (is_win) { + shared_library("mysettings") { + output_extension = "cpl" + ... + } + } +``` +### <a name="output_name"></a>**output_name**: Define a name for the output file other than the default. + +``` + Normally the output name of a target will be based on the target name, so the + target "//foo/bar:bar_unittests" will generate an output file such as + "bar_unittests.exe" (using Windows as an example). + + Sometimes you will want an alternate name to avoid collisions or if the + internal name isn't appropriate for public distribution. + + The output name should have no extension or prefixes, these will be added + using the default system rules. For example, on Linux an output name of "foo" + will produce a shared library "libfoo.so". There is no way to override the + output prefix of a linker tool on a per- target basis. If you need more + flexibility, create a copy target to produce the file you want. + + This variable is valid for all binary output target types. +``` + +#### **Example** + +``` + static_library("doom_melon") { + output_name = "fluffy_bunny" + } +``` +### <a name="output_prefix_override"></a>**output_prefix_override**: Don't use prefix for output name. + +``` + A boolean that overrides the output prefix for a target. Defaults to false. + + Some systems use prefixes for the names of the final target output file. The + normal example is "libfoo.so" on Linux for a target named "foo". + + The output prefix for a given target type is specified on the linker tool + (see "gn help tool"). Sometimes this prefix is undesired. + + See also "gn help output_extension". +``` + +#### **Example** + +``` + shared_library("doom_melon") { + # Normally this will produce "libdoom_melon.so" on Linux. Setting this flag + # will produce "doom_melon.so". + output_prefix_override = true + ... + } +``` +### <a name="outputs"></a>**outputs**: Output files for actions and copy targets. + +``` + Outputs is valid for "copy", "action", and "action_foreach" target types and + indicates the resulting files. Outputs must always refer to files in the + build directory. + + copy + Copy targets should have exactly one entry in the outputs list. If there is + exactly one source, this can be a literal file name or a source expansion. + If there is more than one source, this must contain a source expansion to + map a single input name to a single output name. See "gn help copy". + + action_foreach + Action_foreach targets must always use source expansions to map input files + to output files. There can be more than one output, which means that each + invocation of the script will produce a set of files (presumably based on + the name of the input file). See "gn help action_foreach". + + action + Action targets (excluding action_foreach) must list literal output file(s) + with no source expansions. See "gn help action". +``` +### <a name="partial_info_plist"></a>**partial_info_plist**: [filename] Path plist from asset catalog compiler. + +``` + Valid for create_bundle target, corresponds to the path for the partial + Info.plist created by the asset catalog compiler that needs to be merged + with the application Info.plist (usually done by the code signing script). + + The file will be generated regardless of whether the asset compiler has + been invoked or not. See "gn help create_bundle". +``` +### <a name="pool"></a>**pool**: Label of the pool used by the action. + +``` + A fully-qualified label representing the pool that will be used for the + action. Pools are defined using the pool() {...} declaration. +``` + +#### **Example** + +``` + action("action") { + pool = "//build:custom_pool" + ... + } +``` +### <a name="precompiled_header"></a>**precompiled_header**: [string] Header file to precompile. + +``` + Precompiled headers will be used when a target specifies this value, or a + config applying to this target specifies this value. In addition, the tool + corresponding to the source files must also specify precompiled headers (see + "gn help tool"). The tool will also specify what type of precompiled headers + to use, by setting precompiled_header_type to either "gcc" or "msvc". + + The precompiled header/source variables can be specified on a target or a + config, but must be the same for all configs applying to a given target since + a target can only have one precompiled header. + + 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** + +``` + When using GCC-style precompiled headers, "precompiled_source" contains the + path of a .h file that is precompiled and then included by all source files + in targets that set "precompiled_source". + + The value of "precompiled_header" is not used with GCC-style precompiled + headers. +``` + +#### **MSVC precompiled headers** + +``` + When using MSVC-style precompiled headers, the "precompiled_header" value is + a string corresponding to the header. This is NOT a path to a file that GN + recognises, but rather the exact string that appears in quotes after + an #include line in source code. The compiler will match this string against + includes or forced includes (/FI). + + MSVC also requires a source file to compile the header with. This must be + specified by the "precompiled_source" value. In contrast to the header value, + this IS a GN-style file name, and tells GN which source file to compile to + make the .pch file used for subsequent compiles. + + For example, if the toolchain specifies MSVC headers: + + toolchain("vc_x64") { + ... + tool("cxx") { + precompiled_header_type = "msvc" + ... + + You might make a config like this: + + config("use_precompiled_headers") { + precompiled_header = "build/precompile.h" + precompiled_source = "//build/precompile.cc" + + # Either your source files should #include "build/precompile.h" + # first, or you can do this to force-include the header. + cflags = [ "/FI$precompiled_header" ] + } + + And then define a target that uses the config: + + 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. + +``` + 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. + +``` + Correspond to the type of the product of a create_bundle target. Only + meaningful to Xcode (used as part of the Xcode project generation). + + When generating Xcode project files, only create_bundle target with a + non-empty product_type will have a corresponding target in Xcode project. +``` +### <a name="public"></a>**public**: Declare public header files for a target. + +``` + A list of files that other targets can include. These permissions are checked + via the "check" command (see "gn help check"). + + If no public files are declared, other targets (assuming they have visibility + to depend on this target) can include any file in the sources list. If this + variable is defined on a target, dependent targets may only include files on + this whitelist unless that target is marked as a friend (see "gn help + friend"). + + Header file permissions are also subject to visibility. A target must be + visible to another target to include any files from it at all and the public + headers indicate which subset of those files are permitted. See "gn help + visibility" for more. + + Public files are inherited through the dependency tree. So if there is a + dependency A -> B -> C, then A can include C's public headers. However, the + same is NOT true of visibility, so unless A is in C's visibility list, the + include will be rejected. + + 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. + + It is common for test targets to need to include private headers for their + associated code. In this case, list the test target in the "friend" list of + the target that owns the private header to allow the inclusion. See + "gn help friend" for more. +``` + +#### **Examples** + +``` + These exact files are public: + public = [ "foo.h", "bar.h" ] + + 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. + +``` + A list of config labels. + + Targets directly depending on this one will have the configs listed in this + variable added to them. These configs will also apply to the current target. + + This addition happens in a second phase once a target and all of its + dependencies have been resolved. Therefore, a target will not see these + force-added configs in their "configs" variable while the script is running, + and they can not be removed. As a result, this capability should generally + only be used to add defines and include directories necessary to compile a + target's headers. + + See also "all_dependent_configs". +``` + +#### **Ordering of flags and values** + +``` + 1. Those set on the current target (not in a config). + 2. Those set on the "configs" on the target in order that the + configs appear in the list. + 3. Those set on the "all_dependent_configs" on the target in order + that the configs appear in the list. + 4. Those set on the "public_configs" on the target in order that + those configs appear in the list. + 5. all_dependent_configs pulled from dependencies, in the order of + the "deps" list. This is done recursively. If a config appears + more than once, only the first occurence will be used. + 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. + +``` + Public dependencies are like private dependencies (see "gn help deps") but + additionally express that the current target exposes the listed deps as part + of its public API. + + This has several ramifications: + + - public_configs that are part of the dependency are forwarded to direct + dependents. + + - Public headers in the dependency are usable by dependents (includes do + not require a direct dependency or visibility). + + - 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** + +``` + Say you have three targets: A -> B -> C. C's visibility may allow B to depend + on it but not A. Normally, this would prevent A from including any headers + from C, and C's public_configs would apply only to B. + + If B lists C in its public_deps instead of regular deps, A will now inherit + C's public_configs and the ability to include C's public headers. + + 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** + +``` + # This target can include files from "c" but not from + # "super_secret_implementation_details". + executable("a") { + deps = [ ":b" ] + } + + shared_library("b") { + deps = [ ":super_secret_implementation_details" ] + public_deps = [ ":c" ] + } +``` +### <a name="response_file_contents"></a>**response_file_contents**: Contents of a response file for actions. + +``` + Sometimes the arguments passed to a script can be too long for the system's + command-line capabilities. This is especially the case on Windows where the + maximum command-line length is less than 8K. A response file allows you to + pass an unlimited amount of data to a script in a temporary file for an + action or action_foreach target. + + If the response_file_contents variable is defined and non-empty, the list + will be treated as script args (including possibly substitution patterns) + that will be written to a temporary file at build time. The name of the + temporary file will be substituted for "{{response_file_name}}" in the script + args. + + 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** + +``` + action("process_lots_of_files") { + script = "process.py", + inputs = [ ... huge list of files ... ] + + # Write all the inputs to a response file for the script. Also, + # make the paths relative to the script working directory. + response_file_contents = rebase_path(inputs, root_build_dir) + + # The script expects the name of the response file in --file-list. + args = [ + "--enable-foo", + "--file-list={{response_file_name}}", + ] + } +``` +### <a name="script"></a>**script**: Script file for actions. + +``` + An absolute or buildfile-relative file name of a Python script to run for a + action and action_foreach targets (see "gn help action" and "gn help + action_foreach"). +``` +### <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** + +``` + For binary targets (source sets, executables, and libraries), the known file + types will be compiled with the associated tools. Unknown file types and + headers will be skipped. However, you should still list all C/C+ header files + so GN knows about the existence of those files for the purposes of include + checking. + + As a special case, a file ending in ".def" will be treated as a Windows + module definition file. It will be appended to the link line with a + preceding "/DEF:" string. There must be at most one .def file in a target + 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** + +``` + action_foreach + The sources are the set of files that the script will be executed over. The + script will run once per file. + + action + The sources will be treated the same as inputs. See "gn help inputs" for + more information and usage advice. + + copy + The source are the source files to copy. +``` +### <a name="testonly"></a>**testonly**: Declares a target must only be used for testing. + +``` + Boolean. Defaults to false. + + When a target is marked "testonly = true", it must only be depended on by + other test-only targets. Otherwise, GN will issue an error that the + depenedency is not allowed. + + This feature is intended to prevent accidentally shipping test code in a + final product. +``` + +#### **Example** + +``` + source_set("test_support") { + testonly = true + ... + } +``` +### <a name="visibility"></a>**visibility**: A list of labels that can depend on a target. + +``` + A list of labels and label patterns that define which targets can depend on + the current one. These permissions are checked via the "check" command (see + "gn help check"). + + If visibility is not defined, it defaults to public ("*"). + + If visibility is defined, only the targets with labels that match it can + depend on the current target. The empty list means no targets can depend on + the current target. + + 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** + +``` + See "gn help label_pattern" for more details on what types of patterns are + 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** + +``` + Only targets in the current buildfile ("private"): + visibility = [ ":*" ] + + No targets (used for targets that should be leaf nodes): + visibility = [] + + Any target ("public", the default): + visibility = [ "*" ] + + All targets in the current directory and any subdirectory: + visibility = [ "./*" ] + + Any target in "//bar/BUILD.gn": + visibility = [ "//bar:*" ] + + Any target in "//bar/" or any subdirectory thereof: + visibility = [ "//bar/*" ] + + Just these specific targets: + visibility = [ ":mything", "//foo:something_else" ] + + Any target in the current directory and any subdirectory thereof, plus + any targets in "//bar/" and any subdirectory thereof. + visibility = [ "./*", "//bar/*" ] +``` +### <a name="write_runtime_deps"></a>**write_runtime_deps**: Writes the target's runtime_deps to the given path. + +``` + Does not synchronously write the file, but rather schedules it to be written + at the end of generation. + + If the file exists and the contents are identical to that being written, the + file will not be updated. This will prevent unnecessary rebuilds of targets + that depend on this file. + + Path must be within the output directory. + + See "gn help runtime_deps" for how the runtime dependencies are computed. + + The format of this file will list one file per line with no escaping. The + files will be relative to the root_build_dir. The first line of the file will + be the main output file of the target itself. The file contents will be the + same as requesting the runtime deps be written on the command line (see "gn + help --runtime-deps-list-file"). +``` +### <a name="xcode_extra_attributes"></a>**xcode_extra_attributes**: [scope] Extra attributes for Xcode projects. + +``` + The value defined in this scope will be copied to the EXTRA_ATTRIBUTES + property of the generated Xcode project. They are only meaningful when + generating with --ide=xcode. + + See "gn help create_bundle" for more information. +``` +### <a name="test_application_name"></a>**test_application_name**: Test application name for unit or ui test target. + +``` + Each unit and ui test target must have a test application target, and this + value is used to specify the relationship. Only meaningful to Xcode (used as + part of the Xcode project generation). + + See "gn help create_bundle" for more information. +``` + +#### **Exmaple** + +``` + create_bundle("chrome_xctest") { + test_application_name = "chrome" + ... + } +``` +## <a name="other"></a>Other help topics + +### <a name="buildargs"></a>**Build Arguments Overview** + +``` + Build arguments are variables passed in from outside of the build that build + files can query to determine how the build works. +``` + +#### **How build arguments are set** + +``` + First, system default arguments are set based on the current system. The + built-in arguments are: + - host_cpu + - host_os + - current_cpu + - current_os + - target_cpu + - target_os + + Next, project-specific overrides are applied. These are specified inside + the default_args variable of //.gn. See "gn help dotfile" for more. + + If specified, arguments from the --args command line flag are used. If that + flag is not specified, args from previous builds in the build directory will + be used (this is in the file args.gn in the build directory). + + Last, for targets being compiled with a non-default toolchain, the toolchain + overrides are applied. These are specified in the toolchain_args section of a + toolchain definition. The use-case for this is that a toolchain may be + building code for a different platform, and that it may want to always + specify Posix, for example. See "gn help toolchain" for more. + + If you specify an override for a build argument that never appears in a + "declare_args" call, a nonfatal error will be displayed. +``` + +#### **Examples** + +``` + gn args out/FooBar + Create the directory out/FooBar and open an editor. You would type + something like this into that file: + enable_doom_melon=false + os="android" + + gn gen out/FooBar --args="enable_doom_melon=true os=\"android\"" + 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** + +``` + If you want to use an argument, you use declare_args() and specify default + values. These default values will apply if none of the steps listed in the + "How build arguments are set" section above apply to the given argument, but + the defaults will not override any of these. + + Often, the root build config file will declare global arguments that will be + 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** + +``` + When gn starts, it will search the current directory and parent directories + for a file called ".gn". This indicates the source root. You can override + this detection by using the --root command-line argument + + The .gn file in the source root will be executed. The syntax is the same as a + buildfile, but with very limited build setup-specific meaning. + + If you specify --root, by default GN will look for the file .gn in that + directory. If you want to specify a different file, you can additionally pass + --dotfile: + + gn gen out/Debug --root=/home/build --dotfile=/home/my_gn_file.gn +``` + +#### **Variables** + +``` + arg_file_template [optional] + Path to a file containing the text that should be used as the default + args.gn content when you run `gn args`. + + buildconfig [required] + Path to the build config file. This file will be used to set up the + build file execution environment for each toolchain. + + check_targets [optional] + A list of labels and label patterns that should be checked when running + "gn check" or "gn gen --check". If unspecified, all targets will be + checked. If it is the empty list, no targets will be checked. + + The format of this list is identical to that of "visibility" so see "gn + help visibility" for examples. + + exec_script_whitelist [optional] + A list of .gn/.gni files (not labels) that have permission to call the + exec_script function. If this list is defined, calls to exec_script will + be checked against this list and GN will fail if the current file isn't + in the list. + + This is to allow the use of exec_script to be restricted since is easy to + use inappropriately. Wildcards are not supported. Files in the + secondary_source tree (if defined) should be referenced by ignoring the + secondary tree and naming them as if they are in the main tree. + + If unspecified, the ability to call exec_script is unrestricted. + + Example: + exec_script_whitelist = [ + "//base/BUILD.gn", + "//build/my_config.gni", + ] + + root [optional] + Label of the root build target. The GN build will start by loading the + build file containing this target name. This defaults to "//:" which will + cause the file //BUILD.gn to be loaded. + + script_executable [optional] + Path to specific Python executable or potentially a different language + interpreter that is used to execute scripts in action targets and + exec_script calls. + + secondary_source [optional] + Label of an alternate directory tree to find input files. When searching + for a BUILD.gn file (or the build config file discussed above), the file + will first be looked for in the source root. If it's not found, the + secondary source root will be checked (which would contain a parallel + directory hierarchy). + + This behavior is intended to be used when BUILD.gn files can't be checked + in to certain source directories for whatever reason. + + The secondary source root must be inside the main source tree. + + default_args [optional] + Scope containing the default overrides for declared arguments. These + overrides take precedence over the default values specified in the + declare_args() block, but can be overriden using --args or the + args.gn file. + + 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** + +``` + buildconfig = "//build/config/BUILDCONFIG.gn" + + check_targets = [ + "//doom_melon/*", # Check everything in this subtree. + "//tools:mind_controlling_ant", # Check this specific target. + ] + + root = "//:root" + + secondary_source = "//build/config/temporary_buildfiles/" + + default_args = { + # Default to release builds for this project. + is_debug = false + is_component_build = false + } +``` +### <a name="execution"></a>**Build graph and execution overview** + +#### **Overall build flow** + +``` + 1. Look for ".gn" file (see "gn help dotfile") in the current directory and + walk up the directory tree until one is found. Set this directory to be + the "source root" and interpret this file to find the name of the build + config file. + + 2. Execute the build config file identified by .gn to set up the global + variables and default toolchain name. Any arguments, variables, defaults, + etc. set up in this file will be visible to all files in the build. + + 3. Load the //BUILD.gn (in the source root directory). + + 4. Recursively evaluate rules and load BUILD.gn in other directories as + necessary to resolve dependencies. If a BUILD file isn't found in the + specified location, GN will look in the corresponding location inside + the secondary_source defined in the dotfile (see "gn help dotfile"). + + 5. When a target's dependencies are resolved, write out the `.ninja` + file to disk. + + 6. When all targets are resolved, write out the root build.ninja file. +``` + +#### **Executing target definitions and templates** + +``` + Build files are loaded in parallel. This means it is impossible to + interrogate a target from GN code for any information not derivable from its + label (see "gn help label"). The exception is the get_target_outputs() + function which requires the target being interrogated to have been defined + previously in the same file. + + Targets are declared by their type and given a name: + + static_library("my_static_library") { + ... target parameter definitions ... + } + + There is also a generic "target" function for programmatically defined types + (see "gn help target"). You can define new types using templates (see "gn + help template"). A template defines some custom code that expands to one or + more other targets. + + Before executing the code inside the target's { }, the target defaults are + applied (see "gn help set_defaults"). It will inject implicit variable + definitions that can be overridden by the target code as necessary. Typically + this mechanism is used to inject a default set of configs that define the + global compiler and linker flags. +``` + +#### **Which targets are built** + +``` + All targets encountered in the default toolchain (see "gn help toolchain") + will have build rules generated for them, even if no other targets reference + them. Their dependencies must resolve and they will be added to the implicit + "all" rule (see "gn help ninja_rules"). + + Targets in non-default toolchains will only be generated when they are + required (directly or transitively) to build a target in the default + toolchain. + + See also "gn help ninja_rules". +``` + +#### **Dependencies** + +``` + The only difference between "public_deps" and "deps" except for pushing + configs around the build tree and allowing includes for the purposes of "gn + check". + + A target's "data_deps" are guaranteed to be built whenever the target is + built, but the ordering is not defined. The meaning of this is dependencies + required at runtime. Currently data deps will be complete before the target + is linked, but this is not semantically guaranteed and this is undesirable + from a build performance perspective. Since we hope to change this in the + future, do not rely on this behavior. +``` +### <a name="grammar"></a>**Language and grammar for GN build files** + +#### **Tokens** + +``` + GN build files are read as sequences of tokens. While splitting the file + into tokens, the next token is the longest sequence of characters that form a + valid token. +``` + +#### **White space and comments** + +``` + White space is comprised of spaces (U+0020), horizontal tabs (U+0009), + carriage returns (U+000D), and newlines (U+000A). + + Comments start at the character "#" and stop at the next newline. + + White space and comments are ignored except that they may separate tokens + that would otherwise combine into a single token. +``` + +#### **Identifiers** + +``` + Identifiers name variables and functions. + + identifier = letter { letter | digit } . + letter = "A" ... "Z" | "a" ... "z" | "_" . + digit = "0" ... "9" . +``` + +#### **Keywords** + +``` + The following keywords are reserved and may not be used as identifiers: + + else false if true +``` + +#### **Integer literals** + +``` + An integer literal represents a decimal integer value. + + integer = [ "-" ] digit { digit } . + + Leading zeros and negative zero are disallowed. +``` + +#### **String literals** + +``` + A string literal represents a string value consisting of the quoted + characters with possible escape sequences and variable expansions. + + string = `"` { char | escape | expansion } `"` . + escape = `\` ( "$" | `"` | char ) . + BracketExpansion = "{" ( identifier | ArrayAccess | ScopeAccess " + ") "}" . + Hex = "0x" [0-9A-Fa-f][0-9A-Fa-f] + expansion = "$" ( identifier | BracketExpansion | Hex ) . + char = /* any character except "$", `"`, or newline " + "*/ . + + After a backslash, certain sequences represent special characters: + + \" U+0022 quotation mark + \$ U+0024 dollar sign + \\ U+005C backslash + + All other backslashes represent themselves. + + To insert an arbitrary byte value, use $0xFF. For example, to insert a + newline character: "Line one$0x0ALine two". + + An expansion will evaluate the variable following the '$' and insert a + stringified version of it into the result. For example, to concat two path + components with a slash separating them: + "$var_one/$var_two" + Use the "${var_one}" format to be explicitly deliniate the variable for + otherwise-ambiguous cases. +``` + +#### **Punctuation** + +``` + The following character sequences represent punctuation: + + + += == != ( ) + - -= < <= [ ] + ! = > >= { } + && || . , +``` + +#### **Grammar** + +``` + The input tokens form a syntax tree following a context-free grammar: + + File = StatementList . + + Statement = Assignment | Call | Condition . + LValue = identifier | ArrayAccess | ScopeAccess . + Assignment = LValue AssignOp Expr . + Call = identifier "(" [ ExprList ] ")" [ Block ] . + Condition = "if" "(" Expr ")" Block + [ "else" ( Condition | Block ) ] . + Block = "{" StatementList "}" . + StatementList = { Statement } . + + ArrayAccess = identifier "[" Expr "]" . + ScopeAccess = identifier "." identifier . + Expr = UnaryExpr | Expr BinaryOp Expr . + UnaryExpr = PrimaryExpr | UnaryOp UnaryExpr . + PrimaryExpr = identifier | integer | string | Call + | ArrayAccess | ScopeAccess | Block + | "(" Expr ")" + | "[" [ ExprList [ "," ] ] "]" . + ExprList = Expr { "," Expr } . + + AssignOp = "=" | "+=" | "-=" . + UnaryOp = "!" . + BinaryOp = "+" | "-" // highest priority + | "<" | "<=" | ">" | ">=" + | "==" | "!=" + | "&&" + | "||" . // lowest priority + + All binary operators are left-associative. +``` + +#### **Types** + +``` + The GN language is dynamically typed. The following types are used: + + - Boolean: Uses the keywords "true" and "false". There is no implicit + conversion between booleans and integers. + + - Integers: All numbers in GN are signed 64-bit integers. + + - Strings: Strings are 8-bit with no enforced encoding. When a string is + used to interact with other systems with particular encodings (like the + Windows and Mac filesystems) it is assumed to be UTF-8. See "String + literals" above for more. + + - Lists: Lists are arbitrary-length ordered lists of values. See "Lists" + below for more. + + - Scopes: Scopes are like dictionaries that use variable names for keys. See + "Scopes" below for more. +``` + +#### **Lists** + +``` + Lists are created with [] and using commas to separate items: + + mylist = [ 0, 1, 2, "some string" ] + + A comma after the last item is optional. Lists are dereferenced using 0-based + indexing: + + mylist[0] += 1 + var = mylist[2] + + Lists can be concatenated using the '+' and '+=' operators. Bare values can + not be concatenated with lists, to add a single item, it must be put into a + list of length one. + + Items can be removed from lists using the '-' and '-=' operators. This will + remove all occurrences of every item in the right-hand list from the + left-hand list. It is an error to remove an item not in the list. This is to + prevent common typos and to detect dead code that is removing things that no + longer apply. + + It is an error to use '=' to replace a nonempty list with another nonempty + list. This is to prevent accidentally overwriting data when in most cases + '+=' was intended. To overwrite a list on purpose, first assign it to the + empty list: + + mylist = [] + mylist = otherlist + + 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** + +``` + All execution happens in the context of a scope which holds the current state + (like variables). With the exception of loops and conditions, '{' introduces + a new scope that has a parent reference to the old scope. + + Variable reads recursively search all nested scopes until the variable is + found or there are no more scopes. Variable writes always go into the current + scope. This means that after the closing '}' (again excepting loops and + conditions), all local variables will be restored to the previous values. + This also means that "foo = foo" can do useful work by copying a variable + into the current scope that was defined in a containing scope. + + Scopes can also be assigned to variables. Such scopes can be created by + functions like exec_script, when invoking a template (the template code + refers to the variables set by the invoking code by the implicitly-created + "invoker" scope), or explicitly like: + + empty_scope = {} + myvalues = { + foo = 21 + bar = "something" + } + + Inside such a scope definition can be any GN code including conditionals and + function calls. After the close of the scope, it will contain all variables + explicitly set by the code contained inside it. After this, the values can be + read, modified, or added to: + + myvalues.foo += 2 + empty_scope.new_thing = [ 1, 2, 3 ] +``` +### <a name="input_conversion"></a>**input_conversion**: Specifies how to transform input to a variable. + +``` + input_conversion is an argument to read_file and exec_script that specifies + how the result of the read operation should be converted into a variable. + + "" (the default) + Discard the result and return None. + + "list lines" + Return the file contents as a list, with a string for each line. The + newlines will not be present in the result. The last line may or may not + end in a newline. + + After splitting, each individual line will be trimmed of whitespace on + both ends. + + "scope" + Execute the block as GN code and return a scope with the resulting values + in it. If the input was: + a = [ "hello.cc", "world.cc" ] + b = 26 + and you read the result into a variable named "val", then you could + access contents the "." operator on "val": + sources = val.a + some_count = val.b + + "string" + Return the file contents into a single string. + + "value" + Parse the input as if it was a literal rvalue in a buildfile. Examples of + typical program output using this mode: + [ "foo", "bar" ] (result will be a list) + or + "foo bar" (result will be a string) + or + 5 (result will be an integer) + + Note that if the input is empty, the result will be a null value which + will produce an error if assigned to a variable. + + "json" + Parse the input as a JSON and convert it to equivalent GN rvalue. The data + type mapping is: + a string in JSON maps to string in GN + an integer in JSON maps to integer in GN + a float in JSON is unsupported and will result in an error + an object in JSON maps to scope in GN + an array in JSON maps to list in GN + a boolean in JSON maps to boolean in GN + a null in JSON is unsupported and will result in an error + + Nota that the dictionary keys have to be valid GN identifiers otherwise + they will produce an error. + + "trim ..." + Prefixing any of the other transformations with the word "trim" will + result in whitespace being trimmed from the beginning and end of the + result before processing. + + Examples: "trim string" or "trim list lines" + + Note that "trim value" is useless because the value parser skips + whitespace anyway. +``` +### <a name="label_pattern"></a>**Label patterns** + +``` + A label pattern is a way of expressing one or more labels in a portion of the + source tree. They are not general regular expressions. + + They can take the following forms only: + + - Explicit (no wildcard): + "//foo/bar:baz" + ":baz" + + - Wildcard target names: + "//foo/bar:*" (all targets in the //foo/bar/BUILD.gn file) + ":*" (all targets in the current build file) + + - Wildcard directory names ("*" is only supported at the end) + "*" (all targets) + "//foo/bar/*" (all targets in any subdir of //foo/bar) + "./*" (all targets in the current build file or sub dirs) + + Any of the above forms can additionally take an explicit toolchain. In this + case, the toolchain must be fully qualified (no wildcards are supported in + the toolchain name). + + "//foo:bar(//build/toochain:mac)" + An explicit target in an explicit toolchain. + + ":*(//build/toolchain/linux:32bit)" + All targets in the current build file using the 32-bit Linux toolchain. + + "//foo/*(//build/toolchain:win)" + All targets in //foo and any subdirectory using the Windows + toolchain. +``` +### <a name="labels"></a>**About labels** + +``` + Everything that can participate in the dependency graph (targets, configs, + and toolchains) are identified by labels. A common label looks like: + + //base/test:test_support + + This consists of a source-root-absolute path, a colon, and a name. This means + to look for the thing named "test_support" in "base/test/BUILD.gn". + + You can also specify system absolute paths if necessary. Typically such + paths would be specified via a build arg so the developer can specify where + the component is on their system. + + /usr/local/foo:bar (Posix) + /C:/Program Files/MyLibs:bar (Windows) +``` + +#### **Toolchains** + +``` + A canonical label includes the label of the toolchain being used. Normally, + the toolchain label is implicitly inherited from the current execution + context, but you can override this to specify cross-toolchain dependencies: + + //base/test:test_support(//build/toolchain/win:msvc) + + Here GN will look for the toolchain definition called "msvc" in the file + "//build/toolchain/win" to know how to compile this target. +``` + +#### **Relative labels** + +``` + If you want to refer to something in the same buildfile, you can omit + the path name and just start with a colon. This format is recommended for + all same-file references. + + :base + + Labels can be specified as being relative to the current directory. + Stylistically, we prefer to use absolute paths for all non-file-local + references unless a build file needs to be run in different contexts (like a + project needs to be both standalone and pulled into other projects in + difference places in the directory hierarchy). + + source/plugin:myplugin + ../net:url_request +``` + +#### **Implicit names** + +``` + If a name is unspecified, it will inherit the directory name. Stylistically, + we prefer to omit the colon and name when possible: + + //net -> //net:net + //tools/gn -> //tools/gn:gn +``` +### <a name="ninja_rules"></a>**Ninja build rules** + +#### **The "all" and "default" rules** + +``` + All generated targets (see "gn help execution") will be added to an implicit + build rule called "all" so "ninja all" will always compile everything. The + default rule will be used by Ninja if no specific target is specified (just + typing "ninja"). If there is a target named "default" in the root build file, + it will be the default build rule, otherwise the implicit "all" rule will be + used. +``` + +#### **Phony rules** + +``` + GN generates Ninja "phony" rules for targets in the default toolchain. The + phony rules can collide with each other and with the names of generated files + so are generated with the following priority: + + 1. Actual files generated by the build always take precedence. + + 2. Targets in the toplevel //BUILD.gn file. + + 3. Targets in toplevel directories matching the names of the directories. + So "ninja foo" can be used to compile "//foo:foo". This only applies to + the first level of directories since usually these are the most + important (so this won't apply to "//foo/bar:bar"). + + 4. The short names of executables if there is only one executable with that + short name. Use "ninja doom_melon" to compile the + "//tools/fruit:doom_melon" executable. + + 5. The short names of all targets if there is only one target with that + short name. + + 6. Full label name with no leading slashes. So you can use + "ninja tools/fruit:doom_melon" to build "//tools/fruit:doom_melon". + + 7. Labels with an implicit name part (when the short names match the + directory). So you can use "ninja foo/bar" to compile "//foo/bar:bar". + + These "phony" rules are provided only for running Ninja since this matches + people's historical expectations for building. For consistency with the rest + of the program, GN introspection commands accept explicit labels. + + To explicitly compile a target in a non-default toolchain, you must give + Ninja the exact name of the output file relative to the build directory. +``` +### <a name="nogncheck"></a>**nogncheck**: Skip an include line from checking. + +``` + GN's header checker helps validate that the includes match the build + dependency graph. Sometimes an include might be conditional or otherwise + problematic, but you want to specifically allow it. In this case, it can be + whitelisted. + + Include lines containing the substring "nogncheck" will be excluded from + header checking. The most common case is a conditional include: + + #if defined(ENABLE_DOOM_MELON) + #include "tools/doom_melon/doom_melon.h" // nogncheck + #endif + + If the build file has a conditional dependency on the corresponding target + that matches the conditional include, everything will always link correctly: + + source_set("mytarget") { + ... + if (enable_doom_melon) { + defines = [ "ENABLE_DOOM_MELON" ] + deps += [ "//tools/doom_melon" ] + } + + 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** + +``` + 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** + +``` + Runtime dependencies of a target are exposed via the "runtime_deps" category + of "gn desc" (see "gn help desc") or they can be written at build generation + time via write_runtime_deps(), or --runtime-deps-list-file (see "gn help + --runtime-deps-list-file"). + + To a first approximation, the runtime dependencies of a target are the set of + "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** + +``` + Executable targets and those executable targets' transitive dependencies are + 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** + +``` + Action and copy targets that are listed as "data_deps" will have all of their + outputs and data files considered as runtime dependencies. Action and copy + targets that are "deps" or "public_deps" will have only their data files + considered as runtime dependencies. These targets can list an output file in + both the "outputs" and "data" lists to force an output file as a runtime + dependency in all cases. + + The different rules for deps and data_deps are to express build-time (deps) + vs. run-time (data_deps) outputs. If GN counted all build-time copy steps as + data dependencies, there would be a lot of extra stuff, and if GN counted all + run-time dependencies as regular deps, the build's parallelism would be + unnecessarily constrained. + + This rule can sometimes lead to unintuitive results. For example, given the + three targets: + A --[data_deps]--> B --[deps]--> ACTION + GN would say that A does not have runtime deps on the result of the ACTION, + which is often correct. But the purpose of the B target might be to collect + many actions into one logic unit, and the "data"-ness of A's dependency is + lost. Solutions: + + - List the outputs of the action in its data section (if the results of + that action are always runtime files). + - Have B list the action in data_deps (if the outputs of the actions are + always runtime files). + - Have B list the action in both deps and data deps (if the outputs might be + used in both contexts and you don't care about unnecessary entries in the + 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** + +``` + The results of static_library or source_set targets are not considered + runtime dependencies since these are assumed to be intermediate targets only. + If you need to list a static library as a runtime dependency, you can + 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** + +``` + 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** + +``` + Source expansion is used for the action_foreach and copy target types to map + source file names to output file names or arguments. + + To perform source expansion in the outputs, GN maps every entry in the + sources to every entry in the outputs list, producing the cross product of + all combinations, expanding placeholders (see below). + + Source expansion in the args works similarly, but performing the placeholder + substitution produces a different set of arguments for each invocation of the + script. + + If no placeholders are found, the outputs or args list will be treated as a + static list of literal file names that do not depend on the sources. + + See "gn help copy" and "gn help action_foreach" for more on how this is + applied. +``` + +#### **Placeholders** + +``` + This section discusses only placeholders for actions. There are other + placeholders used in the definition of tools. See "gn help tool" for those. + + {{source}} + The name of the source file including directory (*). This will generally + be used for specifying inputs to a script in the "args" variable. + "//foo/bar/baz.txt" => "../../foo/bar/baz.txt" + + {{source_file_part}} + The file part of the source including the extension. + "//foo/bar/baz.txt" => "baz.txt" + + {{source_name_part}} + The filename part of the source file with no directory or extension. This + will generally be used for specifying a transformation from a source file + to a destination file with the same name but different extension. + "//foo/bar/baz.txt" => "baz" + + {{source_dir}} + The directory (*) containing the source file with no trailing slash. + "//foo/bar/baz.txt" => "../../foo/bar" + + {{source_root_relative_dir}} + The path to the source file's directory relative to the source root, with + no leading "//" or trailing slashes. If the path is system-absolute, + (beginning in a single slash) this will just return the path with no + trailing slash. This value will always be the same, regardless of whether + it appears in the "outputs" or "args" section. + "//foo/bar/baz.txt" => "foo/bar" + + {{source_gen_dir}} + The generated file directory (*) corresponding to the source file's path. + This will be different than the target's generated file directory if the + source file is in a different directory than the BUILD.gn file. + "//foo/bar/baz.txt" => "gen/foo/bar" + + {{source_out_dir}} + The object file directory (*) corresponding to the source file's path, + relative to the build directory. this us be different than the target's + out directory if the source file is in a different directory than the + build.gn file. + "//foo/bar/baz.txt" => "obj/foo/bar" + + {{source_target_relative}} + The path to the source file relative to the target's directory. This will + generally be used for replicating the source directory layout in the + 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** + +``` + Paths containing directories (except the source_root_relative_dir) will be + different depending on what context the expansion is evaluated in. Generally + it should "just work" but it means you can't concatenate strings containing + these values with reasonable results. + + Details: source expansions can be used in the "outputs" variable, the "args" + variable, and in calls to "process_file_template". The "args" are passed to a + script which is run from the build directory, so these directories will + 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** + +``` + Non-varying outputs: + action("hardcoded_outputs") { + sources = [ "input1.idl", "input2.idl" ] + outputs = [ "$target_out_dir/output1.dat", + "$target_out_dir/output2.dat" ] + } + The outputs in this case will be the two literal files given. + + Varying outputs: + action_foreach("varying_outputs") { + sources = [ "input1.idl", "input2.idl" ] + outputs = [ "{{source_gen_dir}}/{{source_name_part}}.h", + "{{source_gen_dir}}/{{source_name_part}}.cc" ] + } + Performing source expansion will result in the following output names: + //out/Debug/obj/mydirectory/input1.h + //out/Debug/obj/mydirectory/input1.cc + //out/Debug/obj/mydirectory/input2.h + //out/Debug/obj/mydirectory/input2.cc +``` +## <a name="switches"></a>Command Line Switches + +**Available global switches +** Do "gn help --the_switch_you_want_help_on" for more. Individual + commands may take command-specific switches not listed here. See the + help on your specific command for more. + +``` + * [--args: Specifies build arguments overrides.](#--args) + * [--color: Force colored output.](#--color) + * [--dotfile: Override the name of the ".gn" file.](#--dotfile) + * [--fail-on-unused-args: Treat unused build args as fatal errors.](#--fail-on-unused-args) + * [--markdown: Write help output in the Markdown format.](#--markdown) + * [--nocolor: Force non-colored output.](#--nocolor) + * [-q: Quiet mode. Don't print output on success.](#-q) + * [--root: Explicitly specify source root.](#--root) + * [--runtime-deps-list-file: Save runtime dependencies for targets in file.](#--runtime-deps-list-file) + * [--script-executable: Set the executable used to execute scripts.](#--script-executable) + * [--threads: Specify number of worker threads.](#--threads) + * [--time: Outputs a summary of how long everything took.](#--time) + * [--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) +``` +