# GN Reference *This page is automatically generated from* `gn help --markdown all`. ## **\--args**: Specifies build arguments overrides. ``` See "gn help buildargs" for an overview of how build arguments work. Most operations take a build directory. The build arguments are taken from the previous build done in that directory. If a command specifies --args, it will override the previous arguments stored in the build directory, and use the specified ones. The args specified will be saved to the build directory for subsequent commands. Specifying --args="" will clear all build arguments. ``` ### **Formatting** ``` The value of the switch is interpreted in GN syntax. For typical usage of string arguments, you will need to be careful about escaping of quotes. ``` ### **Examples** ``` gn gen out/Default --args="foo=\"bar\"" gn gen out/Default --args='foo="bar" enable=true blah=7' gn check out/Default --args="" Clears existing build args from the directory. gn desc out/Default --args="some_list=[1, false, \"foo\"]" ``` ## **\--[no]color**: Forces colored output on or off. ``` Normally GN will try to detect whether it is outputting to a terminal and will enable or disable color accordingly. Use of these switches will override the default. ``` ### **Examples** ``` gn gen out/Default --color gn gen out/Default --nocolor ``` ## **\--dotfile**: Override the name of the ".gn" file. ``` Normally GN loads the ".gn"file from the source root for some basic configuration (see "gn help dotfile"). This flag allows you to use a different file. Note that this interacts with "--root" in a possibly incorrect way. It would be nice to test the edge cases and document or fix. ``` ## **\--markdown**: write the output in the Markdown format. ## **\--[no]color**: Forces colored output on or off. ``` Normally GN will try to detect whether it is outputting to a terminal and will enable or disable color accordingly. Use of these switches will override the default. ``` ### **Examples** ``` gn gen out/Default --color gn gen out/Default --nocolor ``` ## **-q**: Quiet mode. Don't print output on success. ``` This is useful when running as a part of another script. ``` ## **\--root**: Explicitly specify source root. ``` Normally GN will look up in the directory tree from the current directory to find a ".gn" file. The source root directory specifies the meaning of "//" beginning with paths, and the BUILD.gn file in that directory will be the first thing loaded. Specifying --root allows GN to do builds in a specific directory regardless of the current directory. ``` ### **Examples** ``` gn gen //out/Default --root=/home/baracko/src gn desc //out/Default --root="C:\Users\BObama\My Documents\foo" ``` ## **\--runtime-deps-list-file**: Save runtime dependencies for targets in file. ``` --runtime-deps-list-file= Where is a text file consisting of the labels, one per line, of the targets for which runtime dependencies are desired. See "gn help runtime_deps" for a description of how runtime dependencies are computed. ``` ### **Runtime deps output file** ``` For each target requested, GN will write a separate runtime dependency file. The runtime dependency file will be in the output directory alongside the output file of the target, with a ".runtime_deps" extension. For example, if the target "//foo:bar" is listed in the input file, and that target produces an output file "bar.so", GN will create a file "bar.so.runtime_deps" in the build directory. If a source set, action, copy, or group is listed, the runtime deps file will correspond to the .stamp file corresponding to that target. This is probably not useful; the use-case for this feature is generally executable targets. The runtime dependency file will list one file per line, with no escaping. The files will be relative to the root_build_dir. The first line of the file will be the main output file of the target itself (in the above example, "bar.so"). ``` ## **\--threads**: Specify number of worker threads. ``` GN runs many threads to load and run build files. This can make debugging challenging. Or you may want to experiment with different values to see how it affects performance. The parameter is the number of worker threads. This does not count the main thread (so there are always at least two). ``` ### **Examples** ``` gen gen out/Default --threads=1 ``` ## **\--time**: Outputs a summary of how long everything took. ``` Hopefully self-explanatory. ``` ### **Examples** ``` gn gen out/Default --time ``` ## **\--tracelog**: Writes a Chrome-compatible trace log to the given file. ``` The trace log will show file loads, executions, scripts, and writes. This allows performance analysis of the generation step. To view the trace, open Chrome and navigate to "chrome://tracing/", then press "Load" and specify the file you passed to this parameter. ``` ### **Examples** ``` gn gen out/Default --tracelog=mytrace.trace ``` ## **-v**: Verbose logging. ``` This will spew logging events to the console for debugging issues. Good luck! ``` ## **gn args [\--list] [\--short] [\--args]** ``` See also "gn help buildargs" for a more high-level overview of how build arguments work. ``` ### **Usage** ``` gn args Open the arguments for the given build directory in an editor (as specified by the EDITOR environment variable). If the given build directory doesn't exist, it will be created and an empty args file will be opened in the editor. You would type something like this into that file: enable_doom_melon=false os="android" Note: you can edit the build args manually by editing the file "args.gn" in the build directory and then running "gn gen ". gn args --list[=] [--short] Lists all build arguments available in the current configuration, or, if an exact_arg is specified for the list flag, just that one build argument. The output will list the declaration location, default value, and comment preceeding the declaration. If --short is specified, only the names and values will be printed. If the out_dir is specified, the build configuration will be taken from that build directory. The reason this is needed is that the definition of some arguments is dependent on the build configuration, so setting some values might add, remove, or change the default values for other arguments. Specifying your exact configuration allows the proper arguments to be displayed. Instead of specifying the out_dir, you can also use the command-line flag to specify the build configuration: --args= ``` ### **Examples** ``` gn args out/Debug Opens an editor with the args for out/Debug. gn args out/Debug --list --short Prints all arguments with their default values for the out/Debug build. gn args out/Debug --list=target_cpu Prints information about the "target_cpu" argument for the out/Debug build. gn args --list --args="os=\"android\" enable_doom_melon=true" Prints all arguments with the default values for a build with the given arguments set (which may affect the values of other arguments). ``` ## **gn check [] [\--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 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. are assumed to be system includes. - Include paths are assumed to be relative to either the source root or the "root_gen_dir" and must include all the path components. (It might be nice in the future to incorporate GN's knowledge of the include path to handle other include styles.) - 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. - Ouptuts 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 uses relative includes, 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. ``` ## **gn clean ** ``` Deletes the contents of the output directory except for args.gn and creates a Ninja build environment sufficient to regenerate the build. ``` ## **gn desc [] [\--blame]** ``` Displays information about a given labeled target for the given build. The build parameters will be taken for the build in the given . ``` ### **Possibilities for ** ``` (If unspecified an overall summary will be displayed.) sources Source files. inputs Additional input dependencies. public Public header files. check_includes Whether "gn check" checks this target for include usage. allow_circular_includes_from Permit includes from these targets. visibility Prints which targets can depend on this one. testonly Whether this target may only be used in tests. configs Shows configs applied to the given target, sorted in the order they're specified. This includes both configs specified in the "configs" variable, as well as configs pushed onto this target via dependencies specifying "all" or "direct" dependent configs. deps Show immediate or recursive dependencies. See below for flags that control deps printing. public_configs all_dependent_configs Shows the labels of configs applied to targets that depend on this one (either directly or all of them). script args depfile Actions only. The script and related values. outputs Outputs for script and copy target types. defines [--blame] include_dirs [--blame] cflags [--blame] cflags_cc [--blame] cflags_cxx [--blame] ldflags [--blame] lib_dirs libs Shows the given values taken from the target and all configs applying. See "--blame" below. runtime_deps Compute all runtime deps for the given target. This is a computed list and does not correspond to any GN variable, unlike most other values here. The output is a list of file names relative to the build directory. See "gn help runtime_deps" for how this is computed. This also works with "--blame" to see the source of the dependency. ``` ### **Shared flags** ``` --blame Used with any value specified by a config, this will name the config that specified the value. This doesn't currently work for libs and lib_dirs because those are inherited and are more complicated to figure out the blame (patches welcome). ``` ### **Flags that control how deps are printed** ``` --all Collects all recursive dependencies and prints a sorted flat list. Also usable with --tree (see below). --as=(buildfile|label|output) How to print targets. buildfile Prints the build files where the given target was declared as file names. label (default) Prints the label of the target. output Prints the first output file for the target relative to the 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. ``` ## **gn format [\--dump-tree] [\--in-place] [\--stdin] BUILD.gn** ``` 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 preceeding 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 only, dumps the parse tree. --in-place Instead of writing the formatted file to stdout, replace the input file with the formatted output. If no reformatting is required, the input file will not be touched, and nothing printed. --stdin Read input from stdin (and write to stdout). Not compatible with --in-place of course. ``` ### **Examples** ``` gn format //some/BUILD.gn gn format some\BUILD.gn gn format /abspath/some/BUILD.gn gn format --stdin ``` ## **gn gen**: Generate ninja files. ``` gn gen [] Generates ninja files from the current tree and puts them in the given output directory. The output directory can be a source-repo-absolute path name such as: //out/foo Or it can be a directory relative to the current directory such as: out/foo See "gn help switches" for the common command-line switches. ``` ### **IDE options** ``` GN optionally generates files for IDE. Possibilities for --ide= Generate files for an IDE. Currently supported values: "eclipse" - Eclipse CDT settings file. "vs" - Visual Studio project/solution files. (default Visual Studio version: 2015) "vs2013" - Visual Studio 2013 project/solution files. "vs2015" - Visual Studio 2015 project/solution files. --sln= Override default sln file name ("all"). Solution file is written to the root build directory. Only for Visual Studio. --filters= Semicolon-separated list of label patterns used to limit the set of generated projects (see "gn help label_pattern"). Only matching targets will be included to the solution. Only for Visual Studio. ``` ### **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. ``` ## **gn help ** ``` 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. ``` ## **gn ls [] [\--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 Matches all toolchains. When set, if the label pattern does not specify an explicit toolchain, labels from all toolchains will be matched. When unset, only targets in the default toolchain will be matched unless an explicit toolchain in the label is set. --testonly=(true|false) Restrict outputs to targets with the testonly flag set accordingly. When unspecified, the target's testonly flags are ignored. --type=(action|copy|executable|group|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). ``` ## **gn path ** ``` 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. ``` ### **Options** ``` --all Prints all 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 ``` ## **gn refs (|