Lines Matching +full:include +full:- +full:all +full:- +full:sources
3 *This page is automatically generated from* `gn help --markdown all`.
58 * [split_list: Splits a list into N different sub-lists.](#func_split_list)
66 * [Built-in predefined variables](#predefined_variables)
85 * [aliased_deps: [scope] Set of crate-dependency pairs.](#var_aliased_deps)
97 * [cflags: [string list] Flags passed to all C compiler variants.](#var_cflags)
106 … * [code_signing_sources: [file list] Sources for code signing step.](#var_code_signing_sources)
107 …* [complete_static_lib: [boolean] Links all deps into a static library.](#var_complete_static_li…
114 * [data_deps: [label list] Non-linked dependencies.](#var_data_deps)
119 * [externs: [scope] Set of Rust crate-dependency pairs.](#var_externs)
122 * [friend: [label pattern list] Allow targets to include private headers.](#var_friend)
123 * [include_dirs: [directory list] Additional include directories.](#var_include_dirs)
124 * [inputs: [file list] Additional compile-time dependencies.](#var_inputs)
147 * [sources: [file list] Source files for a target.](#var_sources)
155 * all: Print all the help at once
168 * [source_expansion: Map sources to outputs for scripts.](#source_expansion)
169 * [switches: Show available command-line switches.](#switch_list)
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
197 files. The list may also contain the string "all" to refer to a
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) "
234 - "error": This will only be present if an error occurred, and will contain
238 If output_path is -, output is written to stdout.
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)
252 gn args <out_dir> [--list] [--short] [--args] [--overrides-only]
254 See also "gn help buildargs" for a more high-level overview of how
276 gn args <out_dir> --list[=<exact_arg>] [--short] [--overrides-only] [--json]
277 Lists all build arguments available in the current configuration, or, if
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
320 Prints all arguments with their default values for the out/Debug
323 gn args out/Debug --list --short --overrides-only
326 gn args out/Debug --list=target_cpu
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
342 "gn check" is the same thing as "gn gen" with the "--check" flag except that
344 way to manually trigger include file checking.
351 #### **Command-specific switches**
354 --force
355 Ignores specifications of "check_includes = false" and checks all
358 --check-generated
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
402 For an include to be valid:
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
409 valid for the include to be allowed.
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
415 included by other targets. Anything in the sources will be considered
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
429 about include checks it's generally best to exclude that target from checking
443 headers as public sources. With only header files, the source set will be a
444 no-op from a build perspective, but will give a central place to refer to
473 gn desc <out_dir> <label or pattern> [<what to show>] [--blame]
474 [--format=json]
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]
516 sources
522 Compute all runtime deps for the given target. This is a computed list
528 "--blame" to see the source of the dependency.
533 --all-toolchains
535 This switch will turn on matching all toolchains.
542 --format=json
549 --blame
559 The "configs" section will list all configs that apply. For targets this will
560 include configs specified in the "configs" variable of the target, and also
561 configs pushed onto this target via public or "all dependent" configs.
563 Configs can have child configs. Specifying --tree will show the hierarchy.
569 The "outputs" section will list all outputs that apply, including the outputs
577 Deps will include all public, private, and data deps (TODO this could be
580 --all
581 Collects all recursive dependencies and prints a sorted flat list. Also
582 usable with --tree (see below).
583 --as=(buildfile|label|output)
595 --testonly=(true|false)
600 --tree
602 but when --all and -tree are used together, no eliding will be performed.
604 The "deps", "public_deps", and "data_deps" will all be included in the
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|
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...>)…
643 The contents of some lists ('sources', 'deps', etc.) will be sorted to a
648 sources = [
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.
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>
728 Override default sln file name ("all"). Solution file is written to the
731 --no-deps
732 Don't include targets dependencies to the solution. Changes the way how
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>
749 Override defaut workspace file name ("all"). The workspace file is
752 --ninja-extra-args=<string>
754 command-line. Can be used to configure ninja flags, like "-j".
756 --root-target=<target_name>
757 Name of the target corresponding to "All" target in Xcode. If unset,
758 "All" invokes ninja without any target and builds everything.
764 --root-target=<target_name>
775 a list of include paths and defines. Because GN does not generate a full
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...>]
812 all available targets will be used. This is used for various Clang-based
822 You can also use "all" as the parameter to get all help at once.
828 --markdown
835 gn help --markdown all
836 Dump all help to stdout in markdown format.
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.
846 If the label pattern is unspecified, list all targets. The label pattern is
854 --as=(buildfile|label|output)
866 --all-toolchains
868 This switch will turn on matching all toolchains.
875 --testonly=(true|false)
880 --type=(action|copy|executable|group|loadable_module|shared_library|
890 Lists all targets in the default toolchain.
893 Lists all targets in the directory base and all subdirectories.
896 Lists all targets defined in //base/BUILD.gn.
898 gn ls out/Debug //base --as=output
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
905 Builds all targets in //base and all subdirectories.
907 gn ls out/Debug //base --all-toolchains
908 Lists all variants of the target //base:base (it may be referenced
914 gn meta <out_dir> <target>* --data=<key>[,<key>*]* [--walk=<key>[,<key>*]*]
915 [--rebase=<dest dir>]
917 Lists collected metaresults of all given targets for the given data key(s),
929 --data
934 --walk (optional)
939 If the empty string ("") is present in any of these keys, all deps and data_deps
942 --rebase (optional)
943 A destination directory onto which to rebase any paths found. If set, all
951 gn meta out/Debug "//base/foo" --data=files
953 target and all of its dependency tree.
955 gn meta out/Debug "//base/foo" --data=files --data=other
957 //base/foo:foo target and all of its dependency tree.
959 gn meta out/Debug "//base/foo" --data=files --walk=stop
961 target and all of the dependencies listed in the `stop` key (and so on).
963 gn meta out/Debug "//base/foo" --data=files --rebase="/"
965 target and all of its dependency tree, rebasing the strings in the `files`
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
996 Prints all "interesting" paths found rather than just the first one.
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
1032 "inputs", "sources", "public", "data", or "outputs". Any input that does
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
1048 this will output all targets that depend directly or indirectly on the
1049 input. If the input is a file, this will output all targets that depend
1052 When used with --tree, turns off eliding to show a complete tree.
1053 --all-toolchains
1055 This switch will turn on matching all toolchains.
1062 --as=(buildfile|label|output)
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|
1099 Find all targets depending on the given exact target name.
1101 gn refs out/Debug //base:i18n --as=buildfiles | xargs gvim
1102 Edit all .gn files containing references to //base:i18n
1104 gn refs out/Debug //base --all
1105 List all targets depending directly or indirectly on //base:base.
1108 List all targets depending directly on any target in //base or
1112 List all targets depending directly on any target in
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
1130 Display all unique targets with some dependency path to a target
1133 gn refs out/Debug //base/macros.h --testonly=true --type=executable
1134 --all --as=output
1135 Display the executable file names of all test executables
1151 In an action the "sources" and "inputs" are treated the same: they're both
1153 to pass the sources to your script, you must do so explicitly by including
1166 It is recommended you put inputs to your script in the "sources" variable,
1173 action is built, but may not have completed before all steps of the
1175 for runtime-only dependencies.
1188 sources, outputs, and inputs will be all treated as relative to the
1191 GN sets Ninja's flag 'restat = 1` for all action commands. This means
1203 All output files must be inside the output directory of the build.
1213 response_file_contents, script*, sources
1222 sources = [ "my_configuration.txt" ]
1228 # Note that we have to manually pass the sources to our script if the
1230 args = [ "--out", rebase_path(target_gen_dir, root_build_dir) ] +
1231 rebase_path(sources, root_build_dir)
1237 This target type allows you to run a script once-per-file over a set of
1238 sources. If you want to run a script once that takes many files as input, see
1245 The script will be run once per file in the "sources" variable. The "outputs"
1265 action is built, but may not have completed before all steps of the
1267 for runtime-only dependencies.
1277 sources, outputs, and inputs will be all treated as relative to the
1280 GN sets Ninja's flag 'restat = 1` for all action commands. This means
1292 All output files must be inside the output directory of the build.
1302 response_file_contents, script*, sources*
1313 sources = [ "foo.idl", "bar.idl" ]
1328 "-o",
1340 The target must define a list of files as "sources" and a single "outputs".
1344 This target can be used on all platforms though it is designed only to
1345 generate iOS/macOS bundle. In cross-platform projects, it is advised to put it
1354 sources*, outputs*, deps, data_deps, metadata, public_deps, visibility
1362 sources = [ "sources/data/in/icudtl.dat" ]
1367 sources = [ "test/data" ]
1375 sources = [
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
1396 Both "sources" and "outputs" must be specified. Sources can include as many
1409 # Write a rule that copies a checked-in DLL to the output directory.
1411 sources = [ "mydll.dll" ]
1417 sources = [ "data1.dat", "data2.dat", "data3.dat" ]
1428 well-know structure). This target does not define any sources, instead they
1429 are computed from all "bundle_data" target this one depends on transitively
1436 This target can be used on all platforms though it is designed only to
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
1454 If set, code_signing_script is the path of a script that invoked after all
1459 defined and non-empty to inform when the script needs to be re-run. The
1492 sources = [ "templates/Info.plist" ]
1494 args = rebase_path(sources, root_build_dir) +
1500 sources = [ "$gen_path/Info.plist" ]
1519 sources = [ "$gen_path/$app_name" ]
1525 product_type = "com.apple.product-type.application"
1558 "-i=" + ios_code_signing_identity,
1559 "-b=" + rebase_path(
1561 "-e=" + rebase_path(
1563 "-e=" + rebase_path(
1580 determined by the source files in its sources. Targets containing
1581 multiple compiler-incompatible languages are not allowed (e.g. a
1582 target containing both C and C++ sources is acceptable, but a
1583 target containing C and Rust sources is not).
1596 output_name, output_extension, public, sources, testonly,
1636 # at all in this target's metadata.
1736 This target type allows you to create meta-targets that just collect a set of
1751 group("all") {
1774 determined by the source files in its sources. Targets containing
1775 multiple compiler-incompatible languages are not allowed (e.g. a
1776 target containing both C and C++ sources is acceptable, but a
1777 target containing C and Rust sources is not).
1790 output_name, output_extension, public, sources, testonly,
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.
1806 determined by the source files in its sources. Targets containing
1807 multiple compiler-incompatible languages are not allowed (e.g. a
1808 target containing both C and C++ sources is acceptable, but a
1809 target containing C and Rust sources is not).
1822 output_name, output_extension, public, sources, testonly,
1841 determined by the source files in its sources. Targets containing
1842 multiple compiler-incompatible languages are not allowed (e.g. a
1843 target containing both C and C++ sources is acceptable, but a
1844 target containing C and Rust sources is not).
1857 output_name, output_extension, public, sources, testonly,
1875 determined by the source files in its sources. Targets containing
1876 multiple compiler-incompatible languages are not allowed (e.g. a
1877 target containing both C and C++ sources is acceptable, but a
1878 target containing C and Rust sources is not).
1891 output_name, output_extension, public, sources, testonly,
1899 in its sources.
1902 #### **C-language source_sets**
1905 A source set is a collection of sources that get compiled, but are not linked
1907 implicitly added to the linker line of all targets that depend on the source
1927 #### **Rust-language source_sets**
1930 A Rust source set is a collection of sources that get passed along to the
1946 output_name, output_extension, public, sources, testonly,
1970 output_name, output_extension, public, sources, testonly,
1975 determined by the source files in its sources. Targets containing
1976 multiple compiler-incompatible languages are not allowed (e.g. a
1977 target containing both C and C++ sources is acceptable, but a
1978 target containing C and Rust sources is not).
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
2028 assert(defined(sources), "Sources must be defined");
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
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.
2089 include_dirs = [ "include/common" ]
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"
2181 assert(defined(invoker.sources), "Sources must be defined")
2218 File name of script to execute. Non-absolute names will be treated as
2235 re-run.
2294 variables defined in the template invocation to a template-defined target.
2301 all variables from the given scope will be copied. "*" only copies variables
2303 duplicate all global variables.
2309 wouldn't work at all if it didn't clobber).
2311 The sources assignment filter (see "gn help set_sources_assignment_filter")
2313 was already done when sources was set on the from_scope.
2315 If variables_to_not_forward_list is non-empty, then it must contains a list
2333 # to all targets.
2349 # It forwards all values from the invoker.
2357 # variable, and forwards all others to the nested target.
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
2494 "/usr/include" => "/usr/include" (already absolute)
2497 system-absolute, see rebase_path().
2502 sources = [ "foo.cc", "foo.h" ]
2509 # Extract the source-absolute directory name,
2539 template to the sources (see "gn help source_expansion"). This will be the
2545 "stamp" file that Ninja will produce once all outputs are generated. This
2554 sources = [ ... ]
2560 sources = get_target_outputs(":my_action")
2571 case-sensitive.
2591 An import is different than a C++ "include". The imported file is executed in
2627 variable_to_ignore_list allows excluding variables from "all matches" if
2686 Prints all arguments to the console separated by spaces. A newline is
2701 print(sources, deps)
2733 sources = [
2738 sources,
2782 When invoking the compiler or scripts, GN will automatically convert sources
2783 and include directories to be relative to the build directory. However, if
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).
2812 As a special case, if new_base is the empty string (the default), all
2813 paths will be converted to system-absolute native style paths with system
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
2853 # Don't convert sources, GN will automatically convert these to be relative
2856 sources = [ "foo.txt", "bar.txt" ]
2861 "--data",
2863 "--rel",
2865 ] + rebase_path(sources, root_build_dir)
2874 toolchain"). This toolchain will be used for all targets unless otherwise
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.
2921 set_defaults can be used for built-in target types ("executable",
2925 (each call to set_defaults must supply a complete list of all defaults it
2937 # The configs will be auto-populated as above. You can remove it if
2939 configs -= [ "//tools/mything:settings" ]
2945 The sources assignment filter is a list of patterns that remove files from
2946 the list implicitly whenever the "sources" variable is assigned to. This will
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.
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
2997 #### **Sources assignment example**
3000 # Filter out all _win files.
3002 sources = [ "a.cc", "b_win.cc" ]
3003 print(sources)
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"
3071 Split string into all substrings separated by separator and returns a list
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.
3110 When you call template() it creates a closure around all variables currently
3121 names. This means all files internal to the template should use absolute
3124 A template will typically forward some or all variables from the invoking
3133 more or possibly all variables in this manner:
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:
3192 assert(defined(invoker.sources),
3193 "Need sources in $target_name listing the idl files.")
3203 # (since all target names are in the global scope).
3207 sources = invoker.sources
3211 # (this is why we can use the "sources" directly above without having to
3212 # rebase all of the paths). But if we need to reference a script relative
3216 # Tell GN how to expand output names given the sources.
3226 # Generates the list of sources, we get these from the action_foreach
3228 sources = get_target_outputs(":$code_gen_target_name")
3243 # Goes into the template as "invoker.sources".
3244 sources = [ "foo.idl", "bar.idl" ]
3293 "rust_cdylib": Tool for compiling C-compatible dynamic libraries.
3304 Valid for: all tools except "action" (required)
3309 Valid for: all tools except "action" (optional)
3327 potentially with target-specific overrides. It is the tool's job to use
3340 along, potentially with target-specific overrides. One would typically
3364 Valid for: all tools
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"
3447 Valid for: all tools (optional)
3461 "outputs" array will be used for all. See "Separate linking and
3467 the separate linking/dependency optimization, all of these should be
3478 Individual targets can opt-out of the output prefix by setting:
3495 "msvc"-style headers, a "precompiled_source" value. If the type is
3503 Valid for: all tools (optional, defaults to false)
3518 Valid for: all tools except "action" (optional)
3524 Valid for: all tools except "action" (required when "rspfile" is used)
3526 The contents to be written to the response file. This may include all
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
3550 directory for running all tools. These expansions are available to all tools:
3566 If there is more than one output, this will expand to a list of all of
3578 This will include the "output_prefix" if any. See also {{label_name}}.
3584 with a set of compiler-specific flags. The following expansions are
3595 Strings correspond that to the processed flags/defines/include
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"
3687 used on Apple's platforms (macOS and iOS). All name must be ending
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
3754 Shared libraries are special in that not all changes to them require that
3755 dependent targets be re-linked. If the shared library is changed but no
3761 can be used for triggering re-links, while the actual shared library would be
3790 # Put these at the top to apply to all tools below.
3791 lib_switch = "-l"
3792 lib_dir_switch = "-L"
3795 command = "gcc {{source}} -o {{output}}"
3800 command = "g++ {{source}} -o {{output}}"
3818 once for each toolchain it is referenced in so the GN code can vary all
3819 parameters of each target (or which targets exist) on a per-toolchain basis.
3838 2. Re-runs the master build configuration file, applying the arguments
3843 The toolchain configuration is two-way. In the default toolchain (i.e. the
3849 toolchain definition specifies the arguments to re-invoke the build.
3865 configuration file is re-interpreted in the context of that toolchain.
3888 When true, configs (public and all-dependent) will cross the boundary out
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
4022 A fully-qualified label representing the current toolchain. You can use this
4023 to make toolchain-related decisions in the build. See also
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"
4093 All of the variables defined inside the template invocation are accessible as
4107 print(invoker.sources) # Prints [ "a.cc", "b.cc" ]
4113 sources = [ "a.cc", "b.cc" ]
4128 when executing all compilers and scripts.
4140 This is primarily useful for setting up include paths for generated files. If
4171 args = [ "-o", rebase_path(root_out_dir, root_build_dir) ]
4182 cross-compiles, this can be set to something different. This value is
4197 - "x86"
4198 - "x64"
4199 - "arm"
4200 - "arm64"
4201 - "mipsel"
4211 This is primarily useful for setting up include paths for generated files. If
4224 args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]"
4274 cross-compiles, it may be different. This variable differs from "current_os"
4299 - "android"
4300 - "chromeos"
4301 - "ios"
4302 - "linux"
4303 - "nacl"
4304 - "mac"
4305 - "win"
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.
4336 `shared_library` targets that contain Rust sources.
4341 All dependencies listed in this field *must* be listed as deps of the target.
4344 sources = [ "main.rs" ]
4349 `rustc ...command... --extern bar=<build_out_dir>/obj/bar`
4352 sources = [ "main.rs" ]
4360 `rustc ...command... --extern bar_renamed=<build_out_dir>/obj/bar`
4367 All targets depending on this one, and recursively, all targets depending on
4371 This addition happens in a second phase once a target and all of its
4373 force-added configs in their "configs" variable while the script is running,
4375 only be used to add defines and include directories necessary to compile a
4402 targets will be permitted to include headers from the current target despite
4406 link. To keep linker errors from happening, it is good practice to have all
4415 Normally, for a file in target A to include a file from target B, A must list
4417 the --check flag to "gn gen" -- see "gn help check").
4421 final executable or shared library) and they each include headers from the
4422 other: you want A to be able to include B's headers, and B to include A's
4426 target can include header files from the current target. That is, if A
4427 depends on B, B can only include headers from A if it is in A's
4436 In the above example, A's headers are likely to include headers from A's
4438 defines, and include paths that make those headers work properly.
4440 With allow_circular_includes_from, B can include A's headers, and
4446 settings, flags, and include directories are the same between both targets
4463 # Sources here can include headers from a despite lack of deps.
4478 any other target type will be a no-op. As with ldflags, you could put the
4479 arflags in a config and set that as a public or "all dependent" config, but
4545 dependencies of the target. These include all public, private, and data
4554 rather than depend on the internal build steps (which may include
4555 non-distributable code).
4563 a group with the assert_no_deps rule on it, and make that group depend on all
4664 sources = [ "Info.plist" ]
4681 "cflags" are passed to all invocations of the C, C++, Objective C, and
4685 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
4689 See also "asmflags" for flags for assembly-language files.
4714 "cflags" are passed to all invocations of the C, C++, Objective C, and
4718 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
4722 See also "asmflags" for flags for assembly-language files.
4747 "cflags" are passed to all invocations of the C, C++, Objective C, and
4751 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
4755 See also "asmflags" for flags for assembly-language files.
4780 "cflags" are passed to all invocations of the C, C++, Objective C, and
4784 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
4788 See also "asmflags" for flags for assembly-language files.
4813 "cflags" are passed to all invocations of the C, C++, Objective C, and
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
4889 An absolute or buildfile-relative file name of a Python script to run for a
4894 ### <a name="var_code_signing_sources"></a>**code_signing_sources**: [file list] Sources for code s…
4898 target. Non-absolute paths will be resolved relative to the current build
4903 ### <a name="var_complete_static_lib"></a>**complete_static_lib**: [boolean] Links all deps into a …
4906 A static library normally doesn't include code from dependencies, but instead
4914 parties. In this case, the static library should include code for all
4916 themselves are never linked into other complete static libraries. All
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
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" ]
5041 `shared_library`, and `source_set` targets that contain Rust sources.
5049 `shared_library`, and `source_set` targets that contain Rust sources.
5055 main.rs for executable) or a single file in sources, if sources contains
5062 `shared_library`, and `source_set` targets that contain Rust sources.
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
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.
5148 may or may not include an "=" to assign a value.
5182 already specified by a target's inputs and sources. Likewise, depfiles should
5183 specify only those dependencies not already included in sources or inputs.
5190 The format is that of a Makefile and all paths must be relative to the root
5203 sources = [ ... ]
5209 # Say our script uses "-o <d file>" to indicate the depfile.
5210 args = [ "{{source}}", "-o", depfile ]
5220 grant the ability to include headers from the dependency. Public configs are
5227 Source sets, shared libraries, and non-complete static libraries will be
5228 propagated up the dependency tree across groups, non-complete static
5231 Executables, shared libraries, and complete static libraries will link all
5237 of target type. all_dependent_configs are always propagated across all types
5239 all types of targets.
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
5260 sources = [ "main.rs" ]
5268 `--extern bar=path/to/bar.rlib`.
5300 framework_dirs = [ "src/include", "//third_party/foo" ]
5334 ### <a name="var_friend"></a>**friend**: Allow targets to include private headers.
5338 targets to include private headers. Applies to all binary targets.
5345 A friend declaration allows one or more targets to include private headers.
5347 target and require internal knowledge without opening up all headers to be
5348 included by all dependents.
5350 A friend target does not allow that target to include headers when no
5352 targets to include any headers from a destination target. The friend
5357 with the include directive. Friend annotations are not propagated across
5365 # This target can include our private headers.
5372 # Private API and sources.
5373 sources = [
5376 # Normal targets that depend on this one won't be able to include this
5378 # "public" list, all headers are implicitly public.
5384 sources = [
5385 # This can include "private_api.h" from the :lib target because it
5391 ":lib", # Required for the include to be allowed.
5395 ### <a name="var_include_dirs"></a>**include_dirs**: Additional include directories.
5400 The directories in this list will be added to the include path for the files
5425 include_dirs = [ "src/include", "//third_party/foo" ]
5427 ### <a name="var_inputs"></a>**inputs**: Additional compile-time dependencies.
5430 Inputs are compile-time dependencies of the current target. This means that
5431 all inputs must be available before compiling any of the sources or executing
5441 that don't vary. These should be all .py files that the script uses via
5445 For action targets, inputs and sources are treated the same, but from a style
5448 sources.
5454 running GN to determine the inputs, and is easier to keep in-sync than
5461 It may be tempting to write a script that enumerates all files in a directory
5462 as inputs. Don't do this! Even if you specify all the files in the inputs or
5463 sources in the GN target (or worse, enumerate the files in an exec_script
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
5472 when it has changed in any way and the action will re-run.
5478 Any input dependencies will be resolved before compiling any sources or
5479 linking the target. Normally, all actions that a target depends on will be run
5484 that changes in any of the inputs will force all sources in the target to be
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
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
5650 Generally, these keys will include three types of lists: lists of ordinary
5710 This value should not include a leading dot. If undefined, the default
5752 output prefix of a linker tool on a per- target basis. If you need more
5755 This variable is valid for all binary output target types.
5825 A fully-qualified label representing the pool that will be used for the
5847 config, but must be the same for all configs applying to a given target since
5850 If you use both C and C++ sources, the precompiled header and source file
5858 When using GCC-style precompiled headers, "precompiled_source" contains the
5859 path of a .h file that is precompiled and then included by all source files
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
5872 an #include line in source code. The compiler will match this string against
5877 this IS a GN-style file name, and tells GN which source file to compile to
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.
5929 A list of files that other targets can include. These permissions are checked
5933 to depend on this target) can include any file in the sources list. If this
5934 variable is defined on a target, dependent targets may only include files on
5939 visible to another target to include any files from it at all and the public
5944 dependency A -> B -> C, then A can include C's public headers. However, the
5946 include will be rejected.
5948 GN only knows about files declared in the "sources" and "public" sections of
5952 It is common for test targets to need to include private headers for their
5959 any compile-time dependencies up the dependency tree. In this case, the build
5962 A (shared library) -> B (shared library) -> C (action).
5975 No files are public (no targets may include headers from this one):
5986 Generally, public configs are used to apply defines and include directories
5995 Public configs are applied to all targets that depend directly on this one.
6015 # This will get applied to all targets that depend on this one.
6019 Public config propagation happens in a second phase once a target and all of
6021 force-added configs in their "configs" variable while the script is running,
6023 only be used to add defines and include directories rather than setting
6039 # Config to apply to all targets that depend on this one.
6044 # Internal target to actually compile the sources.
6046 # Force all external targets to depend on the group instead of directly
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
6100 C's public_configs and the ability to include C's public headers.
6102 Generally if you are writing a target B and you include C's headers as part
6110 # This target can include files from "c" but not from
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
6164 # Write all the inputs to a response file for the script. Also,
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
6182 ### <a name="var_sources"></a>**sources**: Source files for a target
6185 A list of files. Non-absolute paths will be resolved relative to the current
6189 #### **Sources for binary targets**
6194 headers will be skipped. However, you should still list all C/C+ header files
6195 so GN knows about the existence of those files for the purposes of include
6207 sources, if sources contains only one file.
6210 #### **Sources for non-binary targets**
6214 The sources are the set of files that the script will be executed over. The
6218 The sources will be treated the same as inputs. See "gn help inputs" for
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.
6268 be matched. If a toolchain is not specified on a pattern, targets in all
6284 All targets in the current directory and any subdirectory:
6310 walk will touch all deps and data_deps of the specified target recursively.
6332 help --runtime-deps-list-file").
6339 generating with --ide=xcode.
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
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
6408 gn gen out/FooBar --args="enable_doom_melon=true os=\"android\""
6423 passed to all buildfiles. Individual build files can also specify arguments
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
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"
6519 declare_args() block, but can be overriden using --args or the
6558 etc. set up in this file will be visible to all files in the build.
6570 6. When all targets are resolved, write out the root build.ninja file.
6603 All targets encountered in the default toolchain (see "gn help toolchain")
6606 "all" rule (see "gn help ninja_rules").
6608 Targets in non-default toolchains will only be generated when they are
6674 integer = [ "-" ] digit { digit } .
6689 Hex = "0x" [0-9A-Fa-f][0-9A-Fa-f]
6700 All other backslashes represent themselves.
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
6814 When assigning to a list named 'sources' using '=' or '+=', list items may be
6822 All execution happens in the context of a scope which holds the current state
6826 Variable reads recursively search all nested scopes until the variable is
6829 conditions), all local variables will be restored to the previous values.
6835 refers to the variables set by the invoking code by the implicitly-created
6845 function calls. After the close of the scope, it will contain all variables
6852 Scope equality is defined as single-level scopes identical within the current
6853 scope. That is, all values in the first scope must be present and identical
6891 sources = val.a
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)
6978 "*" (all targets)
6979 "//foo/bar/*" (all targets in any subdir of //foo/bar)
6980 "./*" (all targets in the current build file or sub dirs)
6991 All targets in the current build file using the 32-bit Linux toolchain.
6994 All targets in //foo and any subdirectory using the Windows
7005 This consists of a source-root-absolute path, a colon, and a name. This means
7021 context, but you can override this to specify cross-toolchain dependencies:
7034 all same-file references.
7039 Stylistically, we prefer to use absolute paths for all non-file-local
7054 //net -> //net:net
7055 //tools/gn -> //tools/gn:gn
7103 data in all of them will be aggregated into one list. From there, the walk
7139 labels that should be included in the walk. All labels specified here should
7141 will only recurse into the targets listed. An empty list in all specified
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
7190 collected into a single file listing the locations of all tests in the
7195 Another use is in image creation, where a post-build image tool needs to know
7196 various pieces of information about the components it should include in order
7201 #### **The "all" and "default" rules**
7204 All generated targets (see "gn help execution") will be added to an implicit
7205 build rule called "all" so "ninja all" will always compile everything. The
7208 it will be the default build rule, otherwise the implicit "all" rule will be
7232 5. The short names of all targets if there is only one target with that
7245 To explicitly compile a target in a non-default toolchain, you must give
7248 ### <a name="nogncheck"></a>**nogncheck**: Skip an include line from checking.
7252 dependency graph. Sometimes an include might be conditional or otherwise
7256 Include lines containing the substring "nogncheck" will be excluded from
7257 header checking. The most common case is a conditional include:
7260 #include "tools/doom_melon/doom_melon.h" // nogncheck
7264 that matches the conditional include, everything will always link correctly:
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
7290 time via write_runtime_deps(), or --runtime-deps-list-file (see "gn help
7291 --runtime-deps-list-file").
7294 "data" files, data directories, and the shared libraries from all transitive
7304 assumes that the executable (and everything it requires) is a build-time
7311 Action and copy targets that are listed as "data_deps" will have all of their
7316 dependency in all cases.
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
7320 data dependencies, there would be a lot of extra stuff, and if GN counted all
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"
7368 sources to every entry in the outputs list, producing the cross product of
7369 all combinations, expanding placeholders (see below).
7376 static list of literal file names that do not depend on the sources.
7409 no leading "//" or trailing slashes. If the path is system-absolute,
7449 the directories will be source- absolute (begin with a "//") because the
7456 Non-varying outputs:
7458 sources = [ "input1.idl", "input2.idl" ]
7466 sources = [ "input1.idl", "input2.idl" ]
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.