Move all docs to toplevel docs/ folder. Change-Id: Icea0a02d4f43f591227056aea24cd863ed94c7c3 Reviewed-on: https://gn-review.googlesource.com/2420 Reviewed-by: Brett Wilson <brettw@chromium.org> Commit-Queue: Brett Wilson <brettw@chromium.org>
diff --git a/tools/gn/docs/cross_compiles.md b/docs/cross_compiles.md similarity index 100% rename from tools/gn/docs/cross_compiles.md rename to docs/cross_compiles.md
diff --git a/tools/gn/docs/faq.md b/docs/faq.md similarity index 100% rename from tools/gn/docs/faq.md rename to docs/faq.md
diff --git a/tools/gn/docs/hacking.md b/docs/hacking.md similarity index 100% rename from tools/gn/docs/hacking.md rename to docs/hacking.md
diff --git a/tools/gn/docs/language.md b/docs/language.md similarity index 100% rename from tools/gn/docs/language.md rename to docs/language.md
diff --git a/tools/gn/docs/quick_start.md b/docs/quick_start.md similarity index 100% rename from tools/gn/docs/quick_start.md rename to docs/quick_start.md
diff --git a/tools/gn/docs/standalone.md b/docs/standalone.md similarity index 100% rename from tools/gn/docs/standalone.md rename to docs/standalone.md
diff --git a/tools/gn/docs/style_guide.md b/docs/style_guide.md similarity index 100% rename from tools/gn/docs/style_guide.md rename to docs/style_guide.md
diff --git a/tools/gn/docs/update_binaries.md b/docs/update_binaries.md similarity index 100% rename from tools/gn/docs/update_binaries.md rename to docs/update_binaries.md
diff --git a/tools/gn/docs/reference.md b/tools/gn/docs/reference.md deleted file mode 100644 index b8169cd..0000000 --- a/tools/gn/docs/reference.md +++ /dev/null
@@ -1,6405 +0,0 @@ -# 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 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_c [--blame] - cflags_cc [--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 - causes 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 source 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 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 named "console" defined in the root build file represents Ninja's - console pool. Targets using this pool will have access to the console's - stdin and stdout, and output will not be buffered. This special pool must - have a depth of 1. Pools not defined in the root must not be named "console". - The console pool can only be defined for the default toolchain. - Refer to the Ninja documentation on the console pool for more info. - - 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 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 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 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 or - linking the target. 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. - - When a binary target has no explicit or implicit public headers (a "public" - list is defined but is empty), GN assumes that the target can not propagate - any compile-time dependencies up the dependency tree. In this case, the build - can be parallelized more efficiently. - Say there are dependencies: - A (shared library) -> B (shared library) -> C (action). - Normally C must complete before any source files in A can compile (because - there might be generated includes). But when B explicitly declares no public - headers, C can execute in parallel with A's compile steps. C must still be - complete before any dependents link. -``` - -#### **Examples** - -``` - These exact files are public: - public = [ "foo.h", "bar.h" ] - - No files are public (no targets may include headers from this one): - # This allows starting compile in dependent targets earlier. - 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. -``` - -#### **Example** - -``` - 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 parenthesis at the end of the label pattern. In this case, the - toolchain must be fully qualified (no wildcards are supported in the - toolchain name). - - "//foo:bar(//build/toolchain: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) -``` -