Lines Matching +full:lint +full:- +full:py +full:- +full:build
3 *This page is automatically generated from* `gn help --markdown all`.
9 * [args: Display or configure arguments declared by the build.](#cmd_args)
25 * [create_bundle: [iOS/macOS] Build an iOS or macOS bundle.](#func_create_bundle)
39 * [declare_args: Declare build arguments.](#func_declare_args)
58 * [split_list: Splits a list into N different sub-lists.](#func_split_list)
66 * [Built-in predefined variables](#predefined_variables)
76 * [root_build_dir: [string] Directory where build commands are run.](#var_root_build_dir)
79 * [target_cpu: [string] The desired cpu architecture for the build.](#var_target_cpu)
82 * [target_os: [string] The desired operating system for the build.](#var_target_os)
85 * [aliased_deps: [scope] Set of crate-dependency pairs.](#var_aliased_deps)
114 * [data_deps: [label list] Non-linked dependencies.](#var_data_deps)
119 * [externs: [scope] Set of Rust crate-dependency pairs.](#var_externs)
124 * [inputs: [file list] Additional compile-time dependencies.](#var_inputs)
156 * [buildargs: How build arguments work.](#buildargs)
158 * [execution: Build graph and execution overview.](#execution)
159 * [grammar: Language and grammar for GN build files.](#grammar)
164 * [ninja_rules: How Ninja build rules are named.](#ninja_rules)
169 * [switches: Show available command-line switches.](#switch_list)
180 out_dir is the path to the build directory.
184 - "files": A list of the filenames to check.
186 - "test_targets": A list of the labels for targets that are needed to run
189 - "additional_compile_targets": A list of the labels for targets that we
198 pseudo-group that contains every root target in the build graph.
203 If input_path is -, input is read from stdin.
209 - "compile_targets": A list of the labels derived from the input
214 - "test_targets": A list of the labels from the input test_targets list that
218 - "invalid_targets": A list of any names from the input that do not exist in
219 the build graph. If this list is non-empty, the "error" field will also be
222 - "status": A string containing one of three values:
224 - "Found dependency"
225 - "No dependency"
226 - "Found dependency (all) "
229 should be passed to ninja to build. In the second case, nothing was
230 affected and no build is necessary. In the third case, GN could not
234 - "error": This will only be present if an error occurred, and will contain
238 If output_path is -, output is written to stdout.
241 output file, or if there is something wrong with the build such that gen
243 "error" key is non-empty and a non-fatal error occurred. In other words, it
247 ### <a name="cmd_args"></a>**gn args**: (command-line tool)
250 Display or configure arguments declared by the build.
252 gn args <out_dir> [--list] [--short] [--args] [--overrides-only]
254 See also "gn help buildargs" for a more high-level overview of how
255 build arguments work.
262 Open the arguments for the given build directory in an editor. If the
263 given build directory doesn't exist, it will be created and an empty args
273 Note: you can edit the build args manually by editing the file "args.gn"
274 in the build directory and then running "gn gen <out_dir>".
276 gn args <out_dir> --list[=<exact_arg>] [--short] [--overrides-only] [--json]
277 Lists all build arguments available in the current configuration, or, if
278 an exact_arg is specified for the list flag, just that one build
282 build, default value (if different than the current value), and comment
285 If --short is specified, only the names and current values will be
288 If --overrides-only is specified, only the names and current values of
289 arguments that have been overridden (i.e. non-default arguments) will
292 If --json is specified, the output will be emitted in json format.
319 gn args out/Debug --list --short
321 build.
323 gn args out/Debug --list --short --overrides-only
324 Prints overridden arguments for the out/Debug build.
326 gn args out/Debug --list=target_cpu
329 build.
331 gn args --list --args="os=\"android\" enable_doom_melon=true"
332 Prints all arguments with the default values for a build with the
336 …cmd_check"></a>**gn check <out_dir> [<label_pattern>] [\--force] [\--check-generated]**
339 GN's include header checker validates that the includes for C-like source
340 files match the build dependency graph.
342 "gn check" is the same thing as "gn gen" with the "--check" flag except that
343 this command does not write out any build files. It's intended to be an easy
351 #### **Command-specific switches**
354 --force
358 --check-generated
360 until after a build. With this flag, those generated files that
363 --check-system
375 Targets can opt-out from checking with "check_includes = false" (see
380 - GN opens all C-like source files in the targets to be checked and scans
383 - Generated files (that might not exist yet) are ignored unless
384 the --check-generated flag is provided.
386 - Includes with a "nogncheck" annotation are skipped (see
389 - Includes using "quotes" are always checked.
393 - Include paths are assumed to be relative to any of the "include_dirs" for
396 - GN does not run the preprocessor so will not understand conditional
399 - Only includes matching known files in the build are checked: includes
404 - The included file must be in the current target, or there must be a path
408 - There can be multiple targets with an included file: only one needs to be
411 - If there are only "sources" in a target, all are considered to be public
414 - If a target lists files as "public", only those files are able to be
418 - Outputs from actions are treated like public sources on that target.
420 - A target can include headers from a target that depends on it if the
432 If you have conditional includes, make sure the build conditions and the
444 no-op from a build perspective, but will give a central place to refer to
468 creates a Ninja build environment sufficient to regenerate the build.
473 gn desc <out_dir> <label or pattern> [<what to show>] [--blame]
474 [--format=json]
476 Displays information about a given target or config. The build parameters
477 will be taken for the build in the given <out_dir>.
491 arflags [--blame]
493 cflags [--blame]
494 cflags_c [--blame]
495 cflags_cc [--blame]
497 configs [--tree] (see below)
499 defines [--blame]
501 deps [--all] [--tree] (see below)
504 include_dirs [--blame]
506 ldflags [--blame]
526 The output is a list of file names relative to the build directory. See
528 "--blame" to see the source of the dependency.
533 --all-toolchains
542 --format=json
549 --blame
563 Configs can have child configs. Specifying --tree will show the hierarchy.
580 --all
582 usable with --tree (see below).
583 --as=(buildfile|label|output)
587 Prints the build files where the given target was declared as
593 root build directory.
595 --testonly=(true|false)
600 --tree
602 but when --all and -tree are used together, no eliding will be performed.
607 Tree output can not be used with the filtering or output flags: --as,
608 --type, --testonly.
609 --type=(action|copy|executable|group|loadable_module|shared_library|
619 when directories and source paths are written to the build file, they will be
620 adjusted to be relative to the build directory. So the values for paths
630 gn desc out/Foo :base_unittests deps --tree
634 gn desc out/Debug //base defines --blame
638 ### <a name="cmd_format"></a>**gn format [\--dump-tree] (\--stdin | <list of build_files...>)…
657 --dry-run
660 for presubmit/lint-type checks.
661 - Exit code 0: successful format, matches on disk.
662 - Exit code 1: general failure (parse error, etc.)
663 - Exit code 2: successful format, but differs from on disk.
665 --dump-tree[=( text | json )]
669 --stdin
671 in-place.
676 gn format //some/BUILD.gn //some/other/BUILD.gn //and/another/BUILD.gn
677 gn format some\\BUILD.gn
678 gn format /abspath/some/BUILD.gn
679 gn format --stdin
681 ### <a name="cmd_gen"></a>**gn gen [\--check] [<ide options>] <out_dir>**
687 The output directory can be a source-repo-absolute path name such as:
692 "gn gen --check" is the same as running "gn check". "gn gen --check=system" is
693 the same as running "gn check --check-system". See "gn help check" for
696 See "gn help switches" for the common command-line switches.
704 --ide=<ide_name>
706 "eclipse" - Eclipse CDT settings file.
707 "vs" - Visual Studio project/solution files.
709 "vs2013" - Visual Studio 2013 project/solution files.
710 "vs2015" - Visual Studio 2015 project/solution files.
711 "vs2017" - Visual Studio 2017 project/solution files.
712 "vs2019" - Visual Studio 2019 project/solution files.
713 "xcode" - Xcode workspace/solution files.
714 "qtcreator" - QtCreator project files.
715 "json" - JSON file containing target information
717 --filters=<path_prefixes>
718 Semicolon-separated list of label patterns used to limit the set of
727 --sln=<file_name>
729 root build directory.
731 --no-deps
733 --filters option works. Only directly matching targets are included.
735 --winsdk=<sdk_version>
740 --ninja-extra-args=<string>
742 command-line. Can be used to configure ninja flags, like "-j".
748 --workspace=<file_name>
750 written to the root build directory.
752 --ninja-extra-args=<string>
754 command-line. Can be used to configure ninja flags, like "-j".
756 --root-target=<target_name>
764 --root-target=<target_name>
766 to contain files of it and its dependencies. If unset, the whole build
790 --json-file-name=<json_file_name>
793 --json-ide-script=<path_to_python_script>
799 --json-ide-script-args=<argument>
806 --export-compile-commands[=<target_name1,target_name2...>]
807 Produces a compile_commands.json file in the root of the build directory
812 all available targets will be used. This is used for various Clang-based
814 of the build system.
828 --markdown
835 gn help --markdown all
838 ### <a name="cmd_ls"></a>**gn ls <out_dir> [<label_pattern>] [\--all-toolchains] [\--as…
840 [--type=...] [--testonly=...]
842 Lists all targets matching the given pattern for the given build directory.
854 --as=(buildfile|label|output)
858 Prints the build files where the given target was declared as
864 root build directory.
866 --all-toolchains
875 --testonly=(true|false)
880 --type=(action|copy|executable|group|loadable_module|shared_library|
896 Lists all targets defined in //base/BUILD.gn.
898 gn ls out/Debug //base --as=output
899 Lists the build output file for //base:base
901 gn ls out/Debug --type=executable
902 Lists all executables produced by the build.
904 gn ls out/Debug "//base/*" --as=output | xargs ninja -C out/Debug
907 gn ls out/Debug //base --all-toolchains
914 gn meta <out_dir> <target>* --data=<key>[,<key>*]* [--walk=<key>[,<key>*]*]
915 [--rebase=<dest dir>]
929 --data
934 --walk (optional)
942 --rebase (optional)
951 gn meta out/Debug "//base/foo" --data=files
955 gn meta out/Debug "//base/foo" --data=files --data=other
959 gn meta out/Debug "//base/foo" --data=files --walk=stop
963 gn meta out/Debug "//base/foo" --data=files --rebase="/"
979 --with-data is specified, data deps will also be considered. If there are
987 very high level and a common low-level target. To make the output more useful
988 (and terminate in a reasonable time), GN will not revisit sub-paths
995 --all
998 by non-public paths in order of increasing length.
1000 --public
1001 Considers only public paths. Can't be used with --with-data.
1003 --with-data
1005 linked deps will be followed. Can't be used with --public.
1017 [--all] [--all-toolchains] [--as=...] [--testonly=...] [--type=...]
1022 - Target label: The result will be which targets depend on it.
1024 - Config label: The result will be which targets list the given config in
1027 - Label pattern: The result will be which targets depend on any target
1031 - File name: The result will be which targets list the given file in its
1036 - Response file: If the input starts with an "@", it will be interpreted as
1045 --all
1046 When used without --tree, will recurse and display all unique
1052 When used with --tree, turns off eliding to show a complete tree.
1053 --all-toolchains
1062 --as=(buildfile|label|output)
1066 Prints the build files where the given target was declared as
1072 root build directory.
1074 -q
1078 --testonly=(true|false)
1083 --tree
1085 be elided. Combine with --all to see a full dependency tree.
1087 Tree output can not be used with the filtering or output flags: --as,
1088 --type, --testonly.
1089 --type=(action|copy|executable|group|loadable_module|shared_library|
1101 gn refs out/Debug //base:i18n --as=buildfiles | xargs gvim
1104 gn refs out/Debug //base --all
1113 //base/BUILD.gn.
1115 gn refs out/Debug //base --tree
1125 gn refs out/Debug //base/macros.h --tree
1129 gn refs out/Debug //base/macros.h //base/at_exit.h --all
1133 gn refs out/Debug //base/macros.h --testonly=true --type=executable
1134 --all --as=output
1174 action are started. This can give additional parallelism in the build
1175 for runtime-only dependencies.
1185 directory being that of the root build directory. If you pass files
1187 file names to be relative to the build directory (file names in the
1189 current build file and converted as needed automatically).
1195 downstream steps for incremental builds. Scripts can improve build
1203 All output files must be inside the output directory of the build.
1221 script = "doprocessing.py"
1226 inputs = [ "helper_library.py" ]
1230 args = [ "--out", rebase_path(target_gen_dir, root_build_dir) ] +
1237 This target type allows you to run a script once-per-file over a set of
1266 action are started. This can give additional parallelism in the build
1267 for runtime-only dependencies.
1274 directory being that of the root build directory. If you pass files
1276 file names to be relative to the build directory (file names in the
1278 current build file and converted as needed automatically).
1284 downstream steps for incremental builds. Scripts can improve build
1292 All output files must be inside the output directory of the build.
1312 script = "idl_processor.py"
1324 # will need to convert it to be relative to the build directory using
1328 "-o",
1345 generate iOS/macOS bundle. In cross-platform projects, it is advised to put it
1376 "src/MaterialTypography.bundle/Roboto-Bold.ttf",
1377 "src/MaterialTypography.bundle/Roboto-Italic.ttf",
1378 "src/MaterialTypography.bundle/Roboto-Regular.ttf",
1379 "src/MaterialTypography.bundle/Roboto-Thin.ttf",
1392 All output files must be inside the output directory of the build. You would
1409 # Write a rule that copies a checked-in DLL to the output directory.
1424 ### <a name="func_create_bundle"></a>**create_bundle**: [ios/macOS] Build an iOS or macOS bundle.
1428 well-know structure). This target does not define any sources, instead they
1437 generate iOS or macOS bundle. In cross-platform projects, it is advised to put
1450 Some bundle needs to be code signed as part of the build (on iOS all
1459 defined and non-empty to inform when the script needs to be re-run. The
1491 script = [ "//build/ios/ios_gen_plist.py" ]
1525 product_type = "com.apple.product-type.application"
1546 code_signing_script = "//build/config/ios/codesign.py"
1558 "-i=" + ios_code_signing_identity,
1559 "-b=" + rebase_path(
1561 "-e=" + rebase_path(
1563 "-e=" + rebase_path(
1581 multiple compiler-incompatible languages are not allowed (e.g. a
1627 Given the following targets defined in //base/BUILD.gn, where A depends on B
1736 This target type allows you to create meta-targets that just collect a set of
1775 multiple compiler-incompatible languages are not allowed (e.g. a
1797 A Rust library is an archive containing additional rust-c provided metadata.
1799 extension, and are the intermediate step for most Rust-based binaries.
1807 multiple compiler-incompatible languages are not allowed (e.g. a
1833 Their use is the same as of other Rust libraries, but their build has some
1842 multiple compiler-incompatible languages are not allowed (e.g. a
1876 multiple compiler-incompatible languages are not allowed (e.g. a
1902 #### **C-language source_sets**
1911 actual library file will be produced. This will make the build go a little
1913 organizational benefits of focused build targets.
1927 #### **Rust-language source_sets**
1954 If you only need the static library for intermediate results in the build,
1976 multiple compiler-incompatible languages are not allowed (e.g. a
1985 The target() function is a way to invoke a built-in target or template with a
1989 Only templates and built-in target functions are supported for the
2019 If the condition is false, the build will fail with an error. If the
2045 3. Public_configs from a breadth-first traversal of the dependency tree in
2047 4. All dependent configs from a breadth-first traversal of the dependency
2054 Configs solve a problem where the build system needs to have a higher-level
2057 defines and flags logically go together, and the build system needs to
2058 de-duplicate flags even though raw command-line parameters can't always be
2063 so can be de-duplicated. It allows related settings to be grouped so they
2066 having to hard-coding every compiler's flags each time they are referred to.
2097 ### <a name="func_declare_args"></a>**declare_args**: Declare build arguments.
2103 will not override command-line values.
2118 3. User-defined overrides are applied. Anything set in "gn args" now
2124 - You should not perform difficult work inside a declare_args block since
2127 want to have a script-defined default, set some default "undefined" value
2128 like [], "", or -1, and after the declare_args block, call exec_script if
2131 - Because you cannot read the value of a variable defined in the same
2133 on the possibly-overridden value of another, write two separate
2140 # Bar defaults to same user-overridden state as foo.
2154 gn --args="enable_doom_melon=true enable_teleporter=true"
2200 Runs the given script, returning the stdout of the script. The build
2204 The current directory when executing the script will be the root build
2218 File name of script to execute. Non-absolute names will be treated as
2219 relative to the current build file.
2233 on. These dependencies will be added to the build result such that if any
2234 of them change, the build will be regenerated and the script will be
2235 re-run.
2245 "myscript.py", [some_input], "list lines",
2250 exec_script("//foo/bar/myscript.py")
2294 variables defined in the template invocation to a template-defined target.
2315 If variables_to_not_forward_list is non-empty, then it must contains a list
2488 relative to the current directory, and then the source- absolute version
2489 will be returned. If the input is system- absolute, the same input will
2497 system-absolute, see rebase_path().
2509 # Extract the source-absolute directory name,
2533 "//out/Debug/bar.exe", depending on the build directory).
2571 case-sensitive.
2595 Note that you can not import a BUILD.gn file that's otherwise used in the
2596 build. Files must either be imported or implicitly loaded as a result of deps
2613 import("//build/rules/idl_compilation_rule.gni")
2643 build. This object has a single property "depth" corresponding to
2650 A pool named "console" defined in the root build file represents Ninja's
2689 This function is intended for debugging. Note that build files are run in
2715 build file).
2761 Filename to read, relative to the build file.
2783 and include directories to be relative to the build directory. However, if
2789 directory to be relative to the build directory (which will be the current
2792 If you want to convert a file path to be source-absolute (that is, beginning
2796 can't also generate source-absolute paths without more special-cases.
2810 to the current BUILD-file's directory).
2813 paths will be converted to system-absolute native style paths with system
2819 current build file. Use "." (the default) to convert paths from the
2820 current BUILD-file's directory.
2827 a list of strings). All relative and source-absolute file names will be
2828 converted to be relative to the requested output System-absolute paths will
2841 # Convert a file in the current directory to be relative to the build
2851 # Typical usage for converting to the build directory for a script.
2854 # to the build directory when it constructs the command line for your
2859 # to be relative to the build directory:
2861 "--data",
2863 "--rel",
2877 This function is only valid to call during the processing of the build
2878 configuration file. Since the build configuration file is processed
2879 separately for each toolchain, this function will be a no-op when called
2880 under any non-default toolchains.
2883 environment. If the current environment is 32-bit and somebody references a
2884 target with a 64-bit toolchain, we wouldn't want processing of the build
2885 config file for the 64-bit toolchain to reset the default toolchain to
2886 64-bit, we want to keep it 32-bits.
2918 variable with that name is already in scope, the build will fail with an
2921 set_defaults can be used for built-in target types ("executable",
2937 # The configs will be auto-populated as above. You can remove it if
2939 configs -= [ "//tools/mything:settings" ]
2947 do nothing for non-lists.
2950 platform-specific naming schemes when they don't apply, for example you may
2951 want to filter out all "*_win.cc" files on non-Windows platforms.
2953 Typically this will be called once in the master build config script to set
2973 - "*" Matches zero or more of any character. It does not depend on the
2977 - "\b" Matches a path boundary. This will match the beginning or end of a
3006 ### <a name="func_split_list"></a>**split_list**: Splits a list into N different sub-lists.
3011 Given a list and a number N, splits the list into N sub-lists of
3012 approximately equal size. The return value is a list of the sub-lists. The
3040 string_join("", ["a", "b", "c"]) --> "abc"
3041 string_join("|", ["a", "b", "c"]) --> "a|b|c"
3042 string_join(", ", ["a", "b", "c"]) --> "a, b, c"
3043 string_join("s", ["", ""]) --> "s"
3081 string_split("") --> []
3082 string_split("a") --> ["a"]
3083 string_split(" aa bb") --> ["aa", "bb"]
3089 string_split("", "|") --> [""]
3090 string_split(" a b ", " ") --> ["", "", "a", "b", "", ""]
3091 string_split("aa+-bb+-c", "+-") --> ["aa", "bb", "c"]
3097 to add to the built-in target types.
3104 across build files.
3141 Your template should almost always define a built-in target with the name the
3168 You can use template to redefine a built-in target in which case your template
3169 takes a precedence over the built-in one. All uses of the target from within
3170 the template definition will refer to the built-in target which makes it
3171 possible to extend the behavior of the built-in target:
3214 script = "//tools/idl/idl_code_generator.py"
3293 "rust_cdylib": Tool for compiling C-compatible dynamic libraries.
3315 IDE files generated from the build.
3327 potentially with target-specific overrides. It is the tool's job to use
3340 along, potentially with target-specific overrides. One would typically
3350 (or other implicit input dependencies) that are discovered at build
3393 lib_switch = "-l"
3394 lib_dir_switch = "-L"
3398 "-lfreetype -lexpat".
3409 framework_switch = "-framework "
3410 framework_dir_switch = "-F"
3414 "-framework UIKit -F. -framework Foo"
3420 relative to the build output directory. There must always be at least
3450 number of tasks that can execute concurrently during the build.
3478 Individual targets can opt-out of the output prefix by setting:
3495 "msvc"-style headers, a "precompiled_source" value. If the type is
3528 around OS command-line length limits.
3533 command = "link -o {{output}} {{ldflags}} @{{output}}.rsp"
3549 All paths are relative to the root build directory, which is the current
3565 The relative path and name of the output(s) of the current build step.
3584 with a set of compiler-specific flags. The following expansions are
3597 Example: "--enable-foo --enable-bar"
3599 Defines will be prefixed by "-D" and include directories will be
3600 prefixed by "-I" (these work with Posix tools as well as Microsoft
3635 take a "-filelist" flag which expects newline separated files, and some
3636 Microsoft tools have a fixed-sized buffer for parsing each line of a
3642 Example: "-m64 -fPIC -pthread -L/usr/local/mylib"
3649 ".framework" will be added to the {{libs}} with "-framework" preceding
3652 Example: "-lfoo -lbar"
3689 {{frameworks}} and each item will be preceded by "-framework".
3725 with a set of compiler-specific flags. The following expansions are
3737 Expands to the list of --extern flags needed to include addition Rust
3741 Expands to the list of -Ldependency=<path> strings needed to compile
3755 dependent targets be re-linked. If the shared library is changed but no
3757 can speed up the build.
3761 can be used for triggering re-links, while the actual shared library would be
3791 lib_switch = "-l"
3792 lib_dir_switch = "-L"
3795 command = "gcc {{source}} -o {{output}}"
3800 command = "g++ {{source}} -o {{output}}"
3809 A toolchain is a set of commands and build flags used to compile the source
3816 You can have more than one toolchain in use at once in a build and a target
3817 can exist simultaneously in multiple toolchains. A build file is executed
3819 parameters of each target (or which targets exist) on a per-toolchain basis.
3821 When you have a simple build with only one toolchain, the build config file
3822 is loaded only once at the beginning of the build. It must call
3828 help labels" for how to specify this), GN will start a build using that
3829 secondary toolchain to resolve the target. GN will load the build config file
3830 with the build arguments overridden as specified in the toolchain_args.
3838 2. Re-runs the master build configuration file, applying the arguments
3840 3. Loads the destination build file in the context of the configuration file
3843 The toolchain configuration is two-way. In the default toolchain (i.e. the
3844 main build target) the configuration flows from the build config file to the
3845 toolchain. The build config file looks at the state of the build (OS type,
3848 from the toolchain to the build config file: the "toolchain_args" in the
3849 toolchain definition specifies the arguments to re-invoke the build.
3860 Overrides for build arguments to pass to the toolchain when invoking it.
3864 When you specify a target using an alternate toolchain, the master build
3865 configuration file is re-interpreted in the context of that toolchain.
3867 alternate invocation of the build.
3888 When true, configs (public and all-dependent) will cross the boundary out
3891 it accepts such configs, only whether it pushes them. The build is
3903 deps = [ "//foo/bar:baz(//build/toolchain:bootstrap)" ]
3919 use_doom_melon = true # Doom melon always required for 32-bit builds.
3937 #### **Example of cross-toolchain dependencies**
3940 If a 64-bit target wants to depend on a 32-bit binary, it would specify a
3942 runtime and aren't linked, since you can't link a 32-bit and a 64-bit
3948 # The 64-bit build needs this 32-bit helper.
3954 # Our helper library is only compiled in 32-bits.
3965 If data is a list, the list will be written one-item-per-line with no quoting
3989 ## <a name="predefined_variables"></a>Built-in predefined variables
3994 The build configuration usually sets this value based on the value of
4008 The build configuration usually sets this value based on the value of
4022 A fully-qualified label representing the current toolchain. You can use this
4023 to make toolchain-related decisions in the build. See also
4030 if (current_toolchain == "//build:64_bit_toolchain") {
4037 A fully-qualified label representing the default toolchain, which may not
4043 Corresponds to the number printed by `gn --version`.
4054 This is value is exposed so that cross-compile toolchains can access the host
4057 The value should generally be considered read-only, but it can be overriden
4059 values for the host architecture (e.g., if you can do either 32-bit or 64-bit
4066 - "x64"
4067 - "x86"
4072 This value is exposed so that cross-compiles can access the host build
4075 This value should generally be treated as read-only. It, however, is not used
4082 - "linux"
4083 - "mac"
4084 - "win"
4124 ### <a name="var_root_build_dir"></a>**root_build_dir**: [string] Directory where build commands ar…
4127 This is the root build output directory which will be the current directory
4143 build directory.
4160 rebase_path") to convert it to be relative to the build directory.
4171 args = [ "-o", rebase_path(root_out_dir, root_build_dir) ]
4174 ### <a name="var_target_cpu"></a>**target_cpu**: The desired cpu architecture for the build.
4178 primary objects of the build. It will match the cpu architecture of the
4182 cross-compiles, this can be set to something different. This value is
4188 whatever value is needed for the build. GN defaults this value to the empty
4197 - "x86"
4198 - "x64"
4199 - "arm"
4200 - "arm64"
4201 - "mipsel"
4207 "root_gen_dir" followed by the relative path to the current build file. If
4214 build directory.
4224 args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]"
4266 ### <a name="var_target_os"></a>**target_os**: The desired operating system for the build.
4270 primary object(s) of the build. It will match the OS of the default
4274 cross-compiles, it may be different. This variable differs from "current_os"
4290 whatever value is needed for the build. GN defaults this value to the empty
4299 - "android"
4300 - "chromeos"
4301 - "ios"
4302 - "linux"
4303 - "nacl"
4304 - "mac"
4305 - "win"
4316 (see "gn help rebase_path") to convert it to be relative to the build
4327 args = [ "-o", rebase_path(target_out_dir, root_build_dir) ]"
4332 ### <a name="var_aliased_deps"></a>**aliased_deps**: [scope] Set of crate-dependency pairs.
4349 `rustc ...command... --extern bar=<build_out_dir>/obj/bar`
4360 `rustc ...command... --extern bar_renamed=<build_out_dir>/obj/bar`
4373 force-added configs in their "configs" variable while the script is running,
4417 the --check flag to "gn gen" -- see "gn help check").
4478 any other target type will be a no-op. As with ldflags, you could put the
4552 of the build rather than something that is linked and distributed. This
4554 rather than depend on the internal build steps (which may include
4555 non-distributable code).
4685 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
4689 See also "asmflags" for flags for assembly-language files.
4718 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
4722 See also "asmflags" for flags for assembly-language files.
4751 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
4755 See also "asmflags" for flags for assembly-language files.
4784 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
4788 See also "asmflags" for flags for assembly-language files.
4817 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
4821 See also "asmflags" for flags for assembly-language files.
4845 --check flag) will check this target's sources and headers for proper
4882 files in the build directory.
4889 An absolute or buildfile-relative file name of a Python script to run for a
4898 target. Non-absolute paths will be resolved relative to the current build
4921 GN treats non-complete static libraries as source sets when they are linked
4954 flag instead, you can put that flag in a one-off config and append that
4957 The build configuration script will generally set up the default configs
4970 own values, and in order, the values from its sub-configs *before* anything
4973 - A target has no visibility into a config's sub-configs. Target code only
4974 sees the name of the composite config. It can't remove sub-configs or opt
4978 - You can get duplication of values if a config is listed twice, say, on a
4979 target and in a sub-config that also applies. In other cases, the configs
4980 applying to a target are de-duped. It's expected that if a config is
4981 listed as a sub-config that it is only used in that context. (Note that
4982 it's possible to fix this and de-dupe, but it's not normally relevant and
5010 configs -= [ "//build:no_rtti" ]
5017 # specialized configs depending on build flags. This pattern is useful
5064 Options for this field are "cdylib", "staticlib", "proc-macro", and "dylib".
5065 This field sets the `crate-type` attribute for the `rustc` tool on static
5083 as being relative to the current build file. Since these are runtime
5090 category of "gn desc" or written during build generation via
5091 "--runtime-deps-list-file".
5093 GN doesn't require data files to exist at build-time. So actions that produce
5107 ### <a name="var_data_deps"></a>**data_deps**: Non-linked dependencies.
5191 build directory. Only one output may be listed and it must match the first
5202 script = "myscript.py"
5209 # Say our script uses "-o <d file>" to indicate the depfile.
5210 args = [ "{{source}}", "-o", depfile ]
5227 Source sets, shared libraries, and non-complete static libraries will be
5228 propagated up the dependency tree across groups, non-complete static
5246 ### <a name="var_externs"></a>**externs**: [scope] Set of Rust crate-dependency pairs.
5252 These libraries will be passed as `--extern crate_name=path` to compiler
5268 `--extern bar=path/to/bar.rlib`.
5427 ### <a name="var_inputs"></a>**inputs**: Additional compile-time dependencies.
5430 Inputs are compile-time dependencies of the current target. This means that
5441 that don't vary. These should be all .py files that the script uses via
5454 running GN to determine the inputs, and is easier to keep in-sync than
5468 and all inputs are up to date, the script will not re-run and you will get a
5469 stale build. Instead, either list all inputs on the command line to the
5471 reads. As long as this file is listed in the inputs, the build will detect
5472 when it has changed in any way and the action will re-run.
5493 script = "domything.py"
5502 These flags are passed on the command-line to the linker and generally
5507 static libraries will be a no-op. If you want to apply ldflags to dependent
5536 being relative to the current build file.
5594 checkout. They will be rebased to be relative to the build directory and
5597 that are generated by the build, use normal GN deps to link them.
5603 "lib_dirs" so the given library is found. Your BUILD.gn file should not
5604 specify the switch (like "-l"): this will be encoded in the "lib_switch"
5608 System libraries ending in ".framework" will be special-cased: the switch
5609 "-framework" will be prepended instead of the lib_switch, and the
5752 output prefix of a linker tool on a per- target basis. If you need more
5794 build directory.
5825 A fully-qualified label representing the pool that will be used for the
5833 pool = "//build:custom_pool"
5858 When using GCC-style precompiled headers, "precompiled_source" contains the
5862 The value of "precompiled_header" is not used with GCC-style precompiled
5869 When using MSVC-style precompiled headers, the "precompiled_header" value is
5877 this IS a GN-style file name, and tells GN which source file to compile to
5891 precompiled_header = "build/precompile.h"
5892 precompiled_source = "//build/precompile.cc"
5894 # Either your source files should #include "build/precompile.h"
5895 # first, or you can do this to force-include the header.
5914 "msvc"-style precompiled headers. It will be implicitly added to the sources
5924 non-empty product_type will have a corresponding target in Xcode project.
5944 dependency A -> B -> C, then A can include C's public headers. However, the
5949 targets. If a file is included that is not known to the build, it will be
5959 any compile-time dependencies up the dependency tree. In this case, the build
5962 A (shared library) -> B (shared library) -> C (action).
6021 force-added configs in their "configs" variable while the script is running,
6079 - public_configs that are part of the dependency are forwarded to direct
6082 - Public headers in the dependency are usable by dependents (includes do
6085 - If the current target is a shared library, other shared libraries that it
6095 Say you have three targets: A -> B -> C. C's visibility may allow B to depend
6127 Metadata generally declares files as strings relative to the local build file.
6129 will force the metadata collection to be rebased according to the local build
6141 command-line capabilities. This is especially the case on Windows where the
6142 maximum command-line length is less than 8K. A response file allows you to
6146 If the response_file_contents variable is defined and non-empty, the list
6148 that will be written to a temporary file at build time. The name of the
6161 script = "process.py",
6168 # The script expects the name of the response file in --file-list.
6170 "--enable-foo",
6171 "--file-list={{response_file_name}}",
6178 An absolute or buildfile-relative file name of a Python script to run for a
6185 A list of files. Non-absolute paths will be resolved relative to the current
6186 build file.
6210 #### **Sources for non-binary targets**
6230 other test-only targets. Otherwise, GN will issue an error that the
6258 Tip: Often you will want the same visibility for all targets in a BUILD file.
6287 Any target in "//bar/BUILD.gn":
6332 help --runtime-deps-list-file").
6339 generating with --ide=xcode.
6363 ### <a name="buildargs"></a>**Build Arguments Overview**
6366 Build arguments are variables passed in from outside of the build that build
6367 files can query to determine how the build works.
6370 #### **How build arguments are set**
6374 built-in arguments are:
6375 - host_cpu
6376 - host_os
6377 - current_cpu
6378 - current_os
6379 - target_cpu
6380 - target_os
6382 Next, project-specific overrides are applied. These are specified inside
6385 If specified, arguments from the --args command line flag are used. If that
6386 flag is not specified, args from previous builds in the build directory will
6387 be used (this is in the file args.gn in the build directory).
6389 Last, for targets being compiled with a non-default toolchain, the toolchain
6391 toolchain definition. The use-case for this is that a toolchain may be
6395 If you specify an override for a build argument that never appears in a
6408 gn gen out/FooBar --args="enable_doom_melon=true os=\"android\""
6409 This will overwrite the build directory with the given arguments. (Note
6414 #### **How build arguments are used**
6419 "How build arguments are set" section above apply to the given argument, but
6422 Often, the root build config file will declare global arguments that will be
6423 passed to all buildfiles. Individual build files can also specify arguments
6424 that apply only to those files. It is also useful to specify build args in an
6425 "import"-ed file if you want such arguments to apply to multiple buildfiles.
6432 this detection by using the --root command-line argument
6435 buildfile, but with very limited build setup-specific meaning.
6437 If you specify --root, by default GN will look for the file .gn in that
6439 --dotfile:
6441 gn gen out/Debug --root=/home/build --dotfile=/home/my_gn_file.gn
6452 Path to the build config file. This file will be used to set up the
6453 build file execution environment for each toolchain.
6457 "gn check" or "gn gen --check". If unspecified, all targets will be
6466 when running "gn check" or "gn gen --check". System style includes are
6470 "gn check --check-system" or "gn gen --check=system"
6487 "//base/BUILD.gn",
6488 "//build/my_config.gni",
6492 Label of the root build target. The GN build will start by loading the
6493 build file containing this target name. This defaults to "//:" which will
6494 cause the file //BUILD.gn to be loaded.
6506 for a BUILD.gn file (or the build config file discussed above), the file
6511 This behavior is intended to be used when BUILD.gn files can't be checked
6519 declare_args() block, but can be overriden using --args or the
6529 buildconfig = "//build/config/BUILDCONFIG.gn"
6538 secondary_source = "//build/config/temporary_buildfiles/"
6546 ### <a name="execution"></a>**Build graph and execution overview**
6548 #### **Overall build flow**
6553 the "source root" and interpret this file to find the name of the build
6556 2. Execute the build config file identified by .gn to set up the global
6558 etc. set up in this file will be visible to all files in the build.
6560 3. Load the //BUILD.gn (in the source root directory).
6562 4. Recursively evaluate rules and load BUILD.gn in other directories as
6563 necessary to resolve dependencies. If a BUILD file isn't found in the
6570 6. When all targets are resolved, write out the root build.ninja file.
6576 Build files are loaded in parallel. This means it is impossible to
6604 will have build rules generated for them, even if no other targets reference
6608 Targets in non-default toolchains will only be generated when they are
6609 required (directly or transitively) to build a target in the default
6619 configs around the build tree and allowing includes for the purposes of "gn
6626 from a build performance perspective. Since we hope to change this in the
6629 ### <a name="grammar"></a>**Language and grammar for GN build files**
6634 GN build files are read as sequences of tokens. While splitting the file
6674 integer = [ "-" ] digit { digit } .
6689 Hex = "0x" [0-9A-Fa-f][0-9A-Fa-f]
6710 otherwise-ambiguous cases.
6719 - -= < <= [ ]
6727 The input tokens form a syntax tree following a context-free grammar:
6750 AssignOp = "=" | "+=" | "-=" .
6752 BinaryOp = "+" | "-" // highest priority
6758 All binary operators are left-associative.
6766 - Boolean: Uses the keywords "true" and "false". There is no implicit
6769 - Integers: All numbers in GN are signed 64-bit integers.
6771 - Strings: Strings are 8-bit with no enforced encoding. When a string is
6773 Windows and Mac filesystems) it is assumed to be UTF-8. See "String
6776 - Lists: Lists are arbitrary-length ordered lists of values. See "Lists"
6779 - Scopes: Scopes are like dictionaries that use variable names for keys. See
6790 A comma after the last item is optional. Lists are dereferenced using 0-based
6800 Items can be removed from lists using the '-' and '-=' operators. This will
6801 remove all occurrences of every item in the right-hand list from the
6802 left-hand list. It is an error to remove an item not in the list. This is to
6835 refers to the variables set by the invoking code by the implicitly-created
6852 Scope equality is defined as single-level scopes identical within the current
6969 - Explicit (no wildcard):
6973 - Wildcard target names:
6974 "//foo/bar:*" (all targets in the //foo/bar/BUILD.gn file)
6975 ":*" (all targets in the current build file)
6977 - Wildcard directory names ("*" is only supported at the end)
6980 "./*" (all targets in the current build file or sub dirs)
6987 "//foo:bar(//build/toolchain:mac)"
6990 ":*(//build/toolchain/linux:32bit)"
6991 All targets in the current build file using the 32-bit Linux toolchain.
6993 "//foo/*(//build/toolchain:win)"
7005 This consists of a source-root-absolute path, a colon, and a name. This means
7006 to look for the thing named "test_support" in "base/test/BUILD.gn".
7009 paths would be specified via a build arg so the developer can specify where
7021 context, but you can override this to specify cross-toolchain dependencies:
7023 //base/test:test_support(//build/toolchain/win:msvc)
7026 "//build/toolchain/win" to know how to compile this target.
7034 all same-file references.
7039 Stylistically, we prefer to use absolute paths for all non-file-local
7040 references unless a build file needs to be run in different contexts (like a
7054 //net -> //net:net
7055 //tools/gn -> //tools/gn:gn
7180 to be collected with the target-side code.
7187 build, and so a common use is to provide post-build tooling with a set of data
7191 dependency tree. A local build tool (or continuous integration infrastructure)
7195 Another use is in image creation, where a post-build image tool needs to know
7199 ### <a name="ninja_rules"></a>**Ninja build rules**
7205 build rule called "all" so "ninja all" will always compile everything. The
7207 typing "ninja"). If there is a target named "default" in the root build file,
7208 it will be the default build rule, otherwise the implicit "all" rule will be
7219 1. Actual files generated by the build always take precedence.
7221 2. Targets in the toplevel //BUILD.gn file.
7236 "ninja tools/fruit:doom_melon" to build "//tools/fruit:doom_melon".
7245 To explicitly compile a target in a non-default toolchain, you must give
7246 Ninja the exact name of the output file relative to the build directory.
7251 GN's header checker helps validate that the includes match the build
7263 If the build file has a conditional dependency on the corresponding target
7274 know it matches the build dependencies, and will flag this include as
7282 advice on fixing problems. Targets can also opt-out of checking, see
7289 of "gn desc" (see "gn help desc") or they can be written at build generation
7290 time via write_runtime_deps(), or --runtime-deps-list-file (see "gn help
7291 --runtime-deps-list-file").
7304 assumes that the executable (and everything it requires) is a build-time
7318 The different rules for deps and data_deps are to express build-time (deps)
7319 vs. run-time (data_deps) outputs. If GN counted all build-time copy steps as
7321 run-time dependencies as regular deps, the build's parallelism would be
7326 A --[data_deps]--> B --[deps]--> ACTION
7329 many actions into one logic unit, and the "data"-ness of A's dependency is
7332 - List the outputs of the action in its data section (if the results of
7334 - Have B list the action in data_deps (if the outputs of the actions are
7336 - Have B list the action in both deps and data deps (if the outputs might be
7339 - Split B into run-time and build-time versions with the appropriate "deps"
7409 no leading "//" or trailing slashes. If the path is system-absolute,
7418 source file is in a different directory than the BUILD.gn file.
7423 relative to the build directory. this us be different than the target's
7425 build.gn file.
7447 script which is run from the build directory, so these directories will
7448 relative to the build directory for the script to find. In the other cases,
7449 the directories will be source- absolute (begin with a "//") because the
7456 Non-varying outputs:
7479 Do "gn help --the_switch_you_want_help_on" for more. Individual commands may
7480 take command-specific switches not listed here. See the help on your specific
7484 * --args: Specifies build arguments overrides.
7485 * --color: Force colored output.
7486 * --dotfile: Override the name of the ".gn" file.
7487 * --fail-on-unused-args: Treat unused build args as fatal errors.
7488 * --markdown: Write help output in the Markdown format.
7489 * --nocolor: Force non-colored output.
7490 * -q: Quiet mode. Don't print output on success.
7491 * --root: Explicitly specify source root.
7492 * --runtime-deps-list-file: Save runtime dependencies for targets in file.
7493 * --script-executable: Set the executable used to execute scripts.
7494 * --threads: Specify number of worker threads.
7495 * --time: Outputs a summary of how long everything took.
7496 * --tracelog: Writes a Chrome-compatible trace log to the given file.
7497 * -v: Verbose logging.
7498 * --version: Prints the GN version number and exits.