Lines Matching +full:target +full:- +full:file
3 *This page is automatically generated from* `gn help --markdown all`.
13 * [desc: Show lots of insightful information about a target or config.](#cmd_desc)
18 * [meta: List target metadata collection results.](#cmd_meta)
19 * [outputs: Which files a source/target make.](#cmd_outputs)
21 * [refs: Find stuff referencing a target or file.](#cmd_refs)
22 * [Target declarations](#targets)
23 * [action: Declare a target that runs a script a single time.](#func_action)
24 …* [action_foreach: Declare a target that runs a script over a set of files.](#func_action_foreac…
25 * [bundle_data: [iOS/macOS] Declare a target without output.](#func_bundle_data)
26 * [copy: Declare a target that copies files.](#func_copy)
28 * [executable: Declare an executable target.](#func_executable)
29 * [generated_file: Declare a generated_file target.](#func_generated_file)
31 * [loadable_module: Declare a loadable module target.](#func_loadable_module)
32 * [rust_library: Declare a Rust library target.](#func_rust_library)
33 * [rust_proc_macro: Declare a Rust procedural macro target.](#func_rust_proc_macro)
34 * [shared_library: Declare a shared library target.](#func_shared_library)
35 * [source_set: Declare a source set target.](#func_source_set)
36 * [static_library: Declare a static library target.](#func_static_library)
37 * [target: Declare a target with the given programmatic type.](#func_target)
50 * [get_label_info: Get an attribute from a target's label.](#func_get_label_info)
51 * [get_path_info: Extract parts of a file or directory name.](#func_get_path_info)
52 …* [get_target_outputs: [file list] Get the list of outputs from a target.](#func_get_target_outp…
54 * [import: Import a file into the current scope.](#func_import)
61 * [read_file: Read a file into a variable.](#func_read_file)
62 * [rebase_path: Rebase a file or directory to another location.](#func_rebase_path)
64 * [set_defaults: Set default values for a target type.](#func_set_defaults)
65 * [split_list: Splits a list into N different sub-lists.](#func_split_list)
72 * [write_file: Write a file to disk.](#func_write_file)
73 * [Built-in predefined variables](#predefined_variables)
87 * [target_gen_dir: [string] Directory for a target's generated files.](#var_target_gen_dir)
88 * [target_name: [string] The name of the current target.](#var_target_name)
90 * [target_out_dir: [string] Directory for target output files.](#var_target_out_dir)
92 * [aliased_deps: [scope] Set of crate-dependency pairs.](#var_aliased_deps)
99 * [bridge_header: [string] Path to C/Objective-C compatibility header.](#var_bridge_header)
110 …* [check_includes: [boolean] Controls whether a target's files are checked.](#var_check_includes)
111 …* [code_signing_args: [string list] [deprecated] Args for the post-processing script.](#var_code…
112 …* [code_signing_outputs: [file list] [deprecated] Outputs of the post-processing step.](#var_cod…
113 …* [code_signing_script: [file name] [deprecated] Script for the post-processing step.](#var_code…
114 …* [code_signing_sources: [file list] [deprecated] Sources for the post-processing step.](#var_co…
116 * [configs: [label list] Configs applying to this target or config.](#var_configs)
117 * [contents: Contents to write to file.](#var_contents)
119 * [crate_root: [string] The root source file for a binary or library.](#var_crate_root)
121 * [data: [file list] Runtime data file dependencies.](#var_data)
122 * [data_deps: [label list] Non-linked dependencies.](#var_data_deps)
125 * [depfile: [string] File name for input dependencies for actions.](#var_depfile)
127 * [externs: [scope] Set of Rust crate-dependency pairs.](#var_externs)
133 * [inputs: [file list] Additional compile-time dependencies.](#var_inputs)
137 * [metadata: [scope] Metadata of this target.](#var_metadata)
141 * [output_dir: [directory] Directory to put output file in.](#var_output_dir)
142 …* [output_extension: [string] Value to use for the output's file extension.](#var_output_extensi…
143 * [output_name: [string] Name for the output file other than the default.](#var_output_name)
145 * [outputs: [file list] Output files for actions and copy targets.](#var_outputs)
148 …* [post_processing_args: [string list] Args for the post-processing script.](#var_post_processin…
149 …* [post_processing_outputs: [file list] Outputs of the post-processing step.](#var_post_processi…
150 …* [post_processing_script: [file name] Script for the post-processing step.](#var_post_processin…
151 …* [post_processing_sources: [file list] Sources for the post-processing step.](#var_post_process…
152 * [precompiled_header: [string] Header file to precompile.](#var_precompiled_header)
154 * [precompiled_source: [file name] Source file to precompile.](#var_precompiled_source)
156 * [public: [file list] Declare public header files for a target.](#var_public)
160 …* [response_file_contents: [string list] Contents of .rsp file for actions.](#var_response_file_…
162 * [script: [file name] Script file for actions.](#var_script)
163 * [sources: [file list] Source files for a target.](#var_sources)
165 * [testonly: [boolean] Declares a target must only be used for testing.](#var_testonly)
167 * [visibility: [label list] A list of labels that can depend on a target.](#var_visibility)
170 …* [write_runtime_deps: Writes the target's runtime_deps to the given path.](#var_write_runtime_d…
173 …* [xcode_test_application_name: [string] Name for Xcode test target.](#var_xcode_test_applicatio…
177 * [dotfile: Info about the toplevel .gn file.](#dotfile)
181 * [file_pattern: Matching more than one file.](#file_pattern)
190 * [switches: Show available command-line switches.](#switch_list)
203 input_path is a path to a file containing a JSON object with three fields:
205 - "files": A list of the filenames to check.
207 - "test_targets": A list of the labels for targets that are needed to run
210 - "additional_compile_targets" (optional): A list of the labels for targets
219 pseudo-group that contains every root target in the build graph.
226 If input_path is -, input is read from stdin.
229 written. The results will be a file containing a JSON object with one or more
232 - "compile_targets": A list of the labels derived from the input
237 - "test_targets": A list of the labels from the input test_targets list that
241 - "invalid_targets": A list of any names from the input that do not exist in
242 the build graph. If this list is non-empty, the "error" field will also be
245 - "status": A string containing one of three values:
247 - "Found dependency"
248 - "No dependency"
249 - "Found dependency (all)"
257 - "error": This will only be present if an error occurred, and will contain
258 a string describing the error. This includes cases where the input file is
261 If output_path is -, output is written to stdout.
263 The command returns 1 if it is unable to read the input file or write the
264 output file, or if there is something wrong with the build such that gen
266 "error" key is non-empty and a non-fatal error occurred. In other words, it
270 ### <a name="cmd_args"></a>**gn args**: (command-line tool)
275 gn args <out_dir> [--list] [--short] [--args] [--overrides-only]
277 See also "gn help buildargs" for a more high-level overview of how
287 file will be opened in the editor. You would type something like this
288 into that file:
296 Note: you can edit the build args manually by editing the file "args.gn"
299 gn args <out_dir> --list[=<exact_arg>] [--short] [--overrides-only] [--json]
308 If --short is specified, only the names and current values will be
311 If --overrides-only is specified, only the names and current values of
312 arguments that have been overridden (i.e. non-default arguments) will
313 be printed. Overrides come from the <out_dir>/args.gn file and //.gn
315 If --json is specified, the output will be emitted in json format.
322 "file": file_name,
327 "file": file_name,
342 gn args out/Debug --list --short
346 gn args out/Debug --list --short --overrides-only
349 gn args out/Debug --list=target_cpu
354 gn args --list --args="os=\"android\" enable_doom_melon=true"
359 …cmd_check"></a>**gn check <out_dir> [<label_pattern>] [\--force] [\--check-generated]**
362 GN's include header checker validates that the includes for C-like source
365 "gn check" is the same thing as "gn gen" with the "--check" flag except that
367 way to manually trigger include file checking.
374 #### **Command-specific switches**
377 --check-generated
382 --check-system
386 --default-toolchain
391 Non-wildcard inputs with no explicit toolchain specification will
392 always match only a target in the default toolchain if one exists.
394 --force
396 target's files that match the target label.
402 The .gn file may specify a list of targets to be checked in the list
403 check_targets (see "gn help dotfile"). Alternatively, the .gn file may
408 Targets can opt-out from checking with "check_includes = false" (see
413 - GN opens all C-like source files in the targets to be checked and scans
416 - Generated files (that might not exist yet) are ignored unless
417 the --check-generated flag is provided.
419 - Includes with a "nogncheck" annotation are skipped (see
422 - Includes using "quotes" are always checked.
426 - Include paths are assumed to be relative to any of the "include_dirs" for
427 the target (including the implicit current dir).
429 - GN does not run the preprocessor so will not understand conditional
432 - Only includes matching known files in the build are checked: includes
437 - The included file must be in the current target, or there must be a path
438 following only public dependencies to a target with the file in it
441 - There can be multiple targets with an included file: only one needs to be
444 - If there are only "sources" in a target, all are considered to be public
447 - If a target lists files as "public", only those files are able to be
451 - Outputs from actions are treated like public sources on that target.
453 - A target can include headers from a target that depends on it if the
454 other target is annotated accordingly. See "gn help
462 about include checks it's generally best to exclude that target from checking
474 If you have a standalone header file or files that need to be shared between
477 no-op from a build perspective, but will give a central place to refer to
481 In rare cases it makes sense to list a header in more than one target if it
492 Check only the files in the //foo:bar target.
503 ### <a name="cmd_clean_stale"></a>**gn clean_stale [\--ninja-executable=...] <out_dir>...**
512 executable must be provided by the --ninja-executable switch.
518 --ninja-executable=<string>
524 gn desc <out_dir> <label or pattern> [<what to show>] [--blame]
525 [--format=json]
527 Displays information about a given target or config. The build parameters
530 The <label or pattern> can be a target label, a config label, or a label
542 arflags [--blame]
544 cflags [--blame]
545 cflags_c [--blame]
546 cflags_cc [--blame]
548 configs [--tree] (see below)
550 defines [--blame]
552 deps [--all] [--tree] (see below)
555 include_dirs [--blame]
557 ldflags [--blame]
574 Compute all runtime deps for the given target. This is a computed list
578 The output is a list of file names relative to the build directory. See
580 "--blame" to see the source of the dependency.
586 --default-toolchain
591 Non-wildcard inputs with no explicit toolchain specification will
592 always match only a target in the default toolchain if one exists.
594 --format=json
598 #### **Target flags**
601 --blame
603 causes that target to get the flag. This doesn't currently work for libs,
613 include configs specified in the "configs" variable of the target, and also
614 configs pushed onto this target via public or "all dependent" configs.
616 Configs can have child configs. Specifying --tree will show the hierarchy.
633 --all
635 usable with --tree (see below).
637 --as=(buildfile|label|output)
641 Prints the build files where the given target was declared as
642 file names.
644 Prints the label of the target.
646 Prints the first output file for the target relative to the
649 --testonly=(true|false)
651 accordingly. When unspecified, the target's testonly flags are
654 --tree
656 but when --all and -tree are used together, no eliding will be performed.
661 Tree output can not be used with the filtering or output flags: --as,
662 --type, --testonly.
664 --type=(action|copy|executable|group|loadable_module|shared_library|
674 when directories and source paths are written to the build file, they will be
683 Summarizes the given target.
685 gn desc out/Foo :base_unittests deps --tree
689 gn desc out/Debug //base defines --blame
690 Shows defines set for the //base:base target, annotated by where
693 ### <a name="cmd_format"></a>**gn format [\--dump-tree] (\--stdin | <list of build_files...>)…
696 Formats .gn file to a standard format.
712 --dry-run
714 anything to disk. This is useful for presubmit/lint-type checks.
715 - Exit code 0: successful format, matches on disk.
716 - Exit code 1: general failure (parse error, etc.)
717 - Exit code 2: successful format, but differs from on disk.
719 --dump-tree[=( text | json )]
720 Dumps the parse tree to stdout and does not update the file or print
723 --stdin
724 Read input from stdin and write to stdout rather than update a file
725 in-place.
727 --read-tree=json
728 Reads an AST from stdin in the format output by --dump-tree=json and
729 uses that as the parse tree. (The only read-tree format currently
730 supported is json.) The given .gn file will be overwritten. This can be
739 gn format --stdin
740 gn format --read-tree=json //rewritten/BUILD.gn
742 ### <a name="cmd_gen"></a>**gn gen [\--check] [<ide options>] <out_dir>**
748 The output directory can be a source-repo-absolute path name such as:
753 "gn gen --check" is the same as running "gn check". "gn gen --check=system" is
754 the same as running "gn check --check-system". See "gn help check" for
757 See "gn help switches" for the common command-line switches.
763 --ninja-executable=<string>
767 restat on generated ninja files and for use with --clean-stale.
769 --clean-stale
774 provided by the --ninja-executable switch. Also see "gn help clean_stale".
783 --ide=<ide_name>
785 "eclipse" - Eclipse CDT settings file.
786 "vs" - Visual Studio project/solution files.
788 "vs2013" - Visual Studio 2013 project/solution files.
789 "vs2015" - Visual Studio 2015 project/solution files.
790 "vs2017" - Visual Studio 2017 project/solution files.
791 "vs2019" - Visual Studio 2019 project/solution files.
792 "vs2022" - Visual Studio 2022 project/solution files.
793 "xcode" - Xcode workspace/solution files.
794 "qtcreator" - QtCreator project files.
795 "json" - JSON file containing target information
797 --filters=<path_prefixes>
798 Semicolon-separated list of label patterns used to limit the set of
807 --sln=<file_name>
808 Override default sln file name ("all"). Solution file is written to the
811 --no-deps
813 --filters option works. Only directly matching targets are included.
815 --winsdk=<sdk_version>
820 --ninja-executable=<string>
823 --ninja-extra-args=<string>
825 command-line. Can be used to configure ninja flags, like "-j".
831 --xcode-project=<file_name>
832 Override default Xcode project file name ("all"). The project file is
835 --xcode-build-system=<value>
838 "legacy" - Legacy Build system
839 "new" - New Build System
841 --xcode-configs=<config_name_list>
843 project. If specified, must be a list of semicolon-separated strings.
847 --xcode-config-build-dir=<string>
858 --xcode-additional-files-patterns=<pattern_list>
859 If present, must be a list of semicolon-separated file patterns. It
864 --xcode-additional-files-roots=<path_list>
865 If present, must be a list of semicolon-separated paths. It will be used
869 --ninja-executable=<string>
872 --ninja-extra-args=<string>
874 command-line. Can be used to configure ninja flags, like "-j".
876 --ide-root-target=<target_name>
877 Name of the target corresponding to "All" target in Xcode. If unset,
878 "All" invokes ninja without any target and builds everything.
884 --ide-root-target=<target_name>
885 Name of the root target for which the QtCreator project will be generated
894 file which can be imported into an Eclipse CDT project. The XML file contains
897 for each file individually. Instead, one set of includes/defines is generated
905 Dumps target information to a JSON file and optionally invokes a
906 python script on the generated file. See the comments at the beginning
908 file format.
910 --json-file-name=<json_file_name>
911 Overrides default file name (project.json) of generated JSON file.
913 --json-ide-script=<path_to_python_script>
914 Executes python script after the JSON file is generated or updated with
917 generated JSON file will be first argument when invoking script.
919 --json-ide-script-args=<argument>
926 The --ninja-outputs-file=<FILE> option dumps a JSON file that maps GN labels
941 --ninja-outputs-script=<path_to_python_script>
942 Executes python script after the outputs file is generated or updated
945 generated file will be first argument when invoking script.
947 --ninja-outputs-script-args=<argument>
954 --export-rust-project
955 Produces a rust-project.json file in the root of the build directory
960 --add-export-compile-commands=<label_pattern>
962 target to add to the compilation database. This pattern is appended to any
964 .gn file (see "gn help dotfile"). This allows the user to add additional
971 --add-export-compile-commands=//tools:my_tool
972 --add-export-compile-commands="//base/*"
974 --export-compile-commands[=<target_name1,target_name2...>]
976 Please use --add-export-compile-commands for per-user configuration, and
977 the "export_compile_commands" value in the project-level .gn file (see
978 "gn help dotfile") for per-project configuration.
980 Overrides the value of the export_compile_commands in the .gn file (see
981 "gn help dotfile") as well as the --add-export-compile-commands switch.
984 of target names that are matched in any directory. For example, "foo" will
986 - "//path/to/src:foo"
987 - "//other/path:foo"
988 - "//foo:foo"
990 - "//foo:bar"
1004 --markdown
1011 gn help --markdown all
1014 …e="cmd_ls"></a>**gn ls <out_dir> [<label_pattern>] [\--default-toolchain] [\--as=...]**
1016 [--type=...] [--testonly=...]
1030 --as=(buildfile|label|output)
1034 Prints the build files where the given target was declared as
1035 file names.
1037 Prints the label of the target.
1039 Prints the first output file for the target relative to the
1042 --default-toolchain
1047 Non-wildcard inputs with no explicit toolchain specification will
1048 always match only a target in the default toolchain if one exists.
1050 --testonly=(true|false)
1052 accordingly. When unspecified, the target's testonly flags are
1055 --type=(action|copy|executable|group|loadable_module|shared_library|
1073 gn ls out/Debug //base --as=output
1074 Lists the build output file for //base:base
1076 gn ls out/Debug --type=executable
1079 gn ls out/Debug "//base/*" --as=output | xargs ninja -C out/Debug
1085 gn meta <out_dir> <target>* --data=<key>[,<key>*]* [--walk=<key>[,<key>*]*]
1086 [--rebase=<dest dir>]
1097 <target(s)>
1098 A list of target labels from which to initiate the walk.
1100 --data
1101 A comma-separated list of keys from which to extract data. In each target
1106 --walk (optional)
1107 A comma-separated list of keys from which to control the walk. In each
1108 target walked, its metadata scope is checked for the presence of any of
1110 that it is a label of a valid dependency of the target and then added to the
1114 --rebase (optional)
1123 gn meta out/Debug "//base/foo" --data=files
1125 target and all of its dependency tree.
1127 gn meta out/Debug "//base/foo" --data=files,other
1129 //base/foo:foo target and all of its dependency tree.
1131 gn meta out/Debug "//base/foo" --data=files --walk=stop
1133 target and all of the dependencies listed in the `stop` key (and so on).
1135 gn meta out/Debug "//base/foo" --data=files --rebase="/"
1137 target and all of its dependency tree, rebasing the strings in the `files`
1138 key onto the source directory of the target's declaration relative to "/".
1140 ### <a name="cmd_outputs"></a>**gn outputs <out_dir> <list of target or file names...>**
1143 Lists the output files corresponding to the given target(s) or file name(s).
1149 - The input target/file names are relative to the current directory.
1151 - The output file names are relative to the root build directory.
1157 #### **Target outputs**
1160 If the parameter is a target name that includes a toolchain, it will match
1161 only that target in that toolchain. If no toolchain is specified, it will
1164 The result will be the outputs specified by that target which could be a
1165 library, executable, output of an action, a stamp file, etc.
1168 #### **File outputs**
1171 If the parameter is a file name it will compute the output for that compile
1172 step for all targets in all toolchains that contain that file as a source
1173 file.
1175 If the source is not compiled (e.g. a header or text file), the command will
1178 If the source is listed as an "input" to a binary target or action will
1179 resolve to that target's outputs.
1186 Find the outputs of a given target.
1188 gn outputs out/debug src/project/my_file.cc | xargs ninja -C out/debug
1189 Compiles just the given source file in all toolchains it's referenced in.
1191 git diff --name-only | xargs gn outputs out/x64 | xargs ninja -C out/x64
1205 --with-data is specified, data deps will also be considered. If there are
1213 very high level and a common low-level target. To make the output more useful
1214 (and terminate in a reasonable time), GN will not revisit sub-paths
1215 previously known to lead to the target.
1221 --all
1224 by non-public paths in order of increasing length.
1226 --public
1227 Considers only public paths. Can't be used with --with-data.
1229 --with-data
1231 linked deps will be followed. Can't be used with --public.
1242 gn refs <out_dir> (<label_pattern>|<label>|<file>|@<response_file>)* [--all]
1243 [--default-toolchain] [--as=...] [--testonly=...] [--type=...]
1248 - Target label: The result will be which targets depend on it.
1250 - Config label: The result will be which targets list the given config in
1253 - Label pattern: The result will be which targets depend on any target
1257 - File name: The result will be which targets list the given file in its
1259 not contain wildcards and does not match a target or a config will be
1260 treated as a file.
1262 - Response file: If the input starts with an "@", it will be interpreted as
1263 a path to a file containing a list of labels or file names, one per line.
1271 --all
1272 When used without --tree, will recurse and display all unique
1273 dependencies of the given targets. For example, if the input is a target,
1275 input. If the input is a file, this will output all targets that depend
1276 directly or indirectly on that file.
1278 When used with --tree, turns off eliding to show a complete tree.
1280 --as=(buildfile|label|output)
1284 Prints the build files where the given target was declared as
1285 file names.
1287 Prints the label of the target.
1289 Prints the first output file for the target relative to the
1292 --default-toolchain
1297 Non-wildcard inputs with no explicit toolchain specification will
1298 always match only a target in the default toolchain if one exists.
1300 -q
1305 --testonly=(true|false)
1307 accordingly. When unspecified, the target's testonly flags are
1310 --tree
1311 Outputs a reverse dependency tree from the given target. Duplicates will
1312 be elided. Combine with --all to see a full dependency tree.
1314 Tree output can not be used with the filtering or output flags: --as,
1315 --type, --testonly.
1317 --type=(action|copy|executable|group|loadable_module|shared_library|
1323 #### **Examples (target input)**
1327 Find all targets depending on the given exact target name.
1329 gn refs out/Debug //base:i18n --as=buildfile | xargs gvim
1332 gn refs out/Debug //base --all
1336 List all targets depending directly on any target in //base or
1340 List all targets depending directly on any target in
1343 gn refs out/Debug //base --tree
1347 #### **Examples (file input)**
1351 Print target(s) listing //base/macros.h as a source.
1353 gn refs out/Debug //base/macros.h --tree
1354 Display a reverse dependency tree to get to the given file. This
1355 will show how dependencies will reference that file.
1357 gn refs out/Debug //base/macros.h //base/at_exit.h --all
1358 Display all unique targets with some dependency path to a target
1361 gn refs out/Debug //base/macros.h --testonly=true --type=executable
1362 --all --as=output
1363 Display the executable file names of all test executables
1364 potentially affected by a change to the given file.
1366 ## <a name="targets"></a>Target declarations
1368 ### <a name="func_action"></a>**action**: Declare a target that runs a script a single time.
1371 This target type allows you to run a script a single time to produce one or
1388 input file changes) by writing a depfile when the script is run (see "gn help
1399 configs variables (defines, include_dirs, etc.) set directly on the target.
1400 These behave exactly as they would on a binary target and can be accessed
1402 implement custom compiler-like tools.
1409 for runtime-only dependencies.
1421 file names to be relative to the build directory (file names in the
1423 current build file and converted as needed automatically).
1431 file(s) if the contents have not changed.
1434 #### **File name handling**
1439 reference the output or generated intermediate file directories,
1471 # Our script imports this Python file so we want to rebuild if it changes.
1476 args = [ "--out", rebase_path(target_gen_dir, root_build_dir) ] +
1480 ### <a name="func_action_foreach"></a>**action_foreach**: Declare a target that runs a script over …
1483 This target type allows you to run a script once-per-file over a set of
1491 The script will be run once per file in the "sources" variable. The "outputs"
1493 it (see "gn help source_expansion"). The output file(s) for each script
1495 output file.
1498 file or a Python module it uses, those files should be listed in the "inputs"
1505 input file changes) by writing a depfile when the script is run (see "gn help
1513 for runtime-only dependencies.
1522 file names to be relative to the build directory (file names in the
1524 current build file and converted as needed automatically).
1532 file(s) if the contents have not changed.
1535 #### **File name handling**
1540 reference the output or generated intermediate file directories,
1567 # Runs the script over each IDL file. The IDL script will generate both a .cc
1568 # and a .h file for each input.
1577 # Our script reads this file each time, so we need to list it as a
1581 # Transformation from source file name to output file names.
1590 "-o",
1595 ### <a name="func_bundle_data"></a>**bundle_data**: [iOS/macOS] Declare a target without output.
1598 This target type allows one to declare data that is required at runtime. It is
1602 The target must define a list of files as "sources" and a single "outputs".
1604 output. The output must reference a file inside of {{bundle_root_dir}}.
1606 This target can be used on all platforms though it is designed only to
1607 generate iOS/macOS bundle. In cross-platform projects, it is advised to put it
1610 If any source files in a bundle_data target match `*/*.xcassets/*` then they
1627 Bundle-specific: sources*, outputs*
1649 "src/MaterialTypography.bundle/Roboto-Bold.ttf",
1650 "src/MaterialTypography.bundle/Roboto-Italic.ttf",
1651 "src/MaterialTypography.bundle/Roboto-Regular.ttf",
1652 "src/MaterialTypography.bundle/Roboto-Thin.ttf",
1660 ### <a name="func_copy"></a>**copy**: Declare a target that copies files.
1662 #### **File name handling**
1667 or generated intermediate file directories, respectively.
1671 is used for the name for consistency with other target types).
1673 If there is more than one source file, your output name should specify a
1674 mapping from each source file to an output file name using source expansion
1678 If you want to copy the output of a previous build step, the target that
1679 generates the file to copy must be reachable from the deps or public_deps of
1680 the copy target.
1699 # Write a rule that copies a checked-in DLL to the output directory.
1705 # Write a rule to copy several files to the target generated files directory.
1709 # Use source expansion to generate output files with the corresponding file
1710 # names in the gen dir. This will just copy each file.
1719 # In some cases (particularly actions defined previously in the same file)
1720 # you can use get_target_outputs() to get the input file which can eliminate
1721 # the assumptions about the output file name of the dependency.
1728 # Depend on the target to build the file before copying.
1735 This target generates an iOS or macOS bundle (which is a directory with a
1736 well-know structure). This target does not define any sources, instead they
1737 are computed from all "bundle_data" target this one depends on transitively
1742 of the "bundle_data" target use them.
1744 This target can be used on all platforms though it is designed only to
1745 generate iOS or macOS bundle. In cross-platform projects, it is advised to put
1748 If a create_bundle is specified as a data_deps for another target, the bundle
1755 #### **Post-processing**
1758 Some bundle needs to be post-processed as part of the build (e.g. on iOS all
1763 all files have been moved into the bundle. The script must not change any file
1767 be defined and non-empty to inform when the script needs to be re-run. The
1775 The post-processing step used to be limited to code-signing. The properties
1802 # an alias for an "executable" target, but on iOS/macOS, it builds an
1848 product_type = "com.apple.product-type.application"
1881 "-i=" + ios_post_processing_identity,
1882 "-b=" + rebase_path(
1884 "-e=" + rebase_path(
1886 "-e=" + rebase_path(
1897 ### <a name="func_executable"></a>**executable**: Declare an executable target.
1902 The tools and commands used to create this target type will be
1904 multiple compiler-incompatible languages are not allowed (e.g. a
1905 target containing both C and C++ sources is acceptable, but a
1906 target containing C and Rust sources is not).
1924 ### <a name="func_generated_file"></a>**generated_file**: Declare a generated_file target.
1927 Writes data value(s) to disk on resolution. This target type mirrors some
1933 specifying the intended location of the output file.
1939 write the contents of that value to file, while use of `data_keys` will
1940 trigger a metadata collection walk based on the dependencies of the target and
1957 Generated file: contents, data_keys, rebase, walk_keys, output_conversion
1972 # at all in this target's metadata.
2001 If the following generated_file target is defined:
2020 generated_file target is defined:
2038 If `rebase` is used in the following generated_file target:
2060 This target type allows you to create meta-targets that just collect a set of
2061 dependencies into one named target. Groups can additionally specify configs
2086 ### <a name="func_loadable_module"></a>**loadable_module**: Declare a loadable module target.
2089 This target type allows you to create an object file that is (and can only
2095 "shared_library" target type instead.
2101 The tools and commands used to create this target type will be
2103 multiple compiler-incompatible languages are not allowed (e.g. a
2104 target containing both C and C++ sources is acceptable, but a
2105 target containing C and Rust sources is not).
2123 ### <a name="func_rust_library"></a>**rust_library**: Declare a Rust library target.
2126 A Rust library is an archive containing additional rust-c provided metadata.
2128 extension, and are the intermediate step for most Rust-based binaries.
2134 The tools and commands used to create this target type will be
2136 multiple compiler-incompatible languages are not allowed (e.g. a
2137 target containing both C and C++ sources is acceptable, but a
2138 target containing C and Rust sources is not).
2156 ### <a name="func_rust_proc_macro"></a>**rust_proc_macro**: Declare a Rust procedural macro target.
2170 The tools and commands used to create this target type will be
2172 multiple compiler-incompatible languages are not allowed (e.g. a
2173 target containing both C and C++ sources is acceptable, but a
2174 target containing C and Rust sources is not).
2192 ### <a name="func_shared_library"></a>**shared_library**: Declare a shared library target.
2198 via "data_deps" or, on Darwin platforms, use a "loadable_module" target type
2205 The tools and commands used to create this target type will be
2207 multiple compiler-incompatible languages are not allowed (e.g. a
2208 target containing both C and C++ sources is acceptable, but a
2209 target containing C and Rust sources is not).
2227 ### <a name="func_source_set"></a>**source_set**: Declare a source set target.
2230 Only C-language source sets are supported at the moment.
2233 #### **C-language source_sets**
2242 actual library file will be produced. This will make the build go a little
2272 ### <a name="func_static_library"></a>**static_library**: Declare a static library target.
2275 Make a ".a" / ".lib" file.
2279 slow) step of creating the intermediate library file.
2298 The tools and commands used to create this target type will be
2300 multiple compiler-incompatible languages are not allowed (e.g. a
2301 target containing both C and C++ sources is acceptable, but a
2302 target containing C and Rust sources is not).
2304 ### <a name="func_target"></a>**target**: Declare a target with the given programmatic type.
2307 target(target_type_string, target_name_string) { ... }
2309 The target() function is a way to invoke a built-in target or template with a
2311 target might not be known statically.
2313 Only templates and built-in target functions are supported for the
2318 target("source_set", "doom_melon") {
2323 #### **Common target variables**
2346 target(my_type, "foo") {
2375 A config is referenced by its label just like a target.
2379 defines, etc. for a target is generated in this order:
2381 1. The values specified directly on the target (rather than using a config).
2382 2. The configs specified in the target's "configs" list, in order.
2383 3. Public_configs from a breadth-first traversal of the dependency tree in
2385 4. All dependent configs from a breadth-first traversal of the dependency
2392 Configs solve a problem where the build system needs to have a higher-level
2396 de-duplicate flags even though raw command-line parameters can't always be
2401 so can be de-duplicated. It allows related settings to be grouped so they
2404 having to hard-coding every compiler's flags each time they are referred to.
2418 #### **Variables on a target used to apply configs**
2442 will not override command-line values.
2457 3. User-defined overrides are applied. Anything set in "gn args" now
2459 to be readable from the following code in the file.
2463 - You should not perform difficult work inside a declare_args block since
2466 want to have a script-defined default, set some default "undefined" value
2467 like [], "", or -1, and after the declare_args block, call exec_script if
2470 - Because you cannot read the value of a variable defined in the same
2472 on the possibly-overridden value of another, write two separate
2479 # Bar defaults to same user-overridden state as foo.
2493 gn --args="enable_doom_melon=true enable_teleporter=true"
2551 directory. If you are passing file names, you will want to use the
2552 rebase_path() function to make file names relative to this path (see "gn help
2564 File name of script to execute. Non-absolute names will be treated as
2565 relative to the current build file.
2572 Controls how the file is read and parsed. See `gn help io_conversion`.
2581 re-run.
2605 The argument exclude_patterns must be a list of file patterns (see
2623 The argument include_patterns must be a list of file patterns (see
2712 variables defined in the template invocation to a template-defined target.
2729 If variables_to_not_forward_list is non-empty, then it must contains a list
2762 # This is a template around a target whose type depends on a global variable.
2765 target(my_wrapper_target_type, target_name) {
2771 # variable, and forwards all others to the nested target.
2782 ### <a name="func_get_label_info"></a>**get_label_info**: Get an attribute from a target's label.
2787 Given the label of a target, returns some attribute of that target. The
2788 target need not have been previously defined in the same file, since none of
2789 the attributes depend on the actual target definition, only the label itself.
2798 The short name of the target. This will match the value of the
2799 "target_name" variable inside that target's declaration. For the label
2803 The directory containing the target's definition, with no slash at the
2807 The generated file directory for the target. This will match the value of
2808 the "target_gen_dir" variable when inside that target's declaration.
2811 The root of the generated file tree for the target. This will match the
2812 value of the "root_gen_dir" variable when inside that target's
2816 The output directory for the target. This will match the value of the
2817 "target_out_dir" variable when inside that target's declaration.
2820 The root of the output file tree for the target. This will match the
2821 value of the "root_out_dir" variable when inside that target's
2834 "current_toolchain" variable when inside that target's declaration.
2846 ### <a name="func_get_path_info"></a>**get_path_info**: Extract parts of a file or directory name.
2851 The first argument is either a string representing a file or directory name,
2859 "file"
2869 The substring of the file name not including the extension.
2891 The output file directory corresponding to the path of the given file,
2896 The generated file directory corresponding to the path of the given file,
2901 The full absolute path name to the file or directory. It will be resolved
2902 relative to the current directory, and then the source- absolute version
2903 will be returned. If the input is system- absolute, the same input will
2911 system-absolute, see rebase_path().
2923 # Extract the source-absolute directory name,
2926 …nc_get_target_outputs"></a>**get_target_outputs**: [file list] Get the list of outputs from a targ…
2931 Returns a list of output files for the named target. The named target must
2932 have been previously defined in the current file before this function is
2940 source sets and groups have no useful output file.
2946 The names in the resulting list will be absolute file paths (normally like
2950 specified in the "outputs" variable of the target.
2954 same result (though with guaranteed absolute file paths), as
2959 "stamp" file that Ninja will produce once all outputs are generated. This
2985 case-sensitive.
2997 ### <a name="func_import"></a>**import**: Import a file into the current scope.
3001 given file into the current scope.
3005 An import is different than a C++ "include". The imported file is executed in
3007 of this execution are cached for other files that import the same .gni file.
3009 Note that you can not import a BUILD.gn file that's otherwise used in the
3013 The imported file's scope will be merged with the scope at the point import
3015 file define some variable or rule with the same name but different value), a
3017 stuff that an imported file defines.
3075 As the file containing the pool definition may be executed in the
3079 A pool named "console" defined in the root build file represents Ninja's
3086 A pool is referenced by its label just like a target.
3121 prints from one file may be duplicated or
3135 Prints the current file location, and all template invocations that led up to
3166 process_file_template applies a template list to a source file list,
3168 typically used for computing output file names from input files.
3172 can't be used (like there's no target or the target is defined in another
3173 build file).
3179 The source_list is a list of file names.
3206 ### <a name="func_read_file"></a>**read_file**: Read a file into a variable.
3211 Whitespace will be trimmed from the end of the file. Throws an error if the
3212 file can not be opened.
3219 Filename to read, relative to the build file.
3222 Controls how the file is read and parsed. See `gn help io_conversion`.
3230 ### <a name="func_rebase_path"></a>**rebase_path**: Rebase a file or directory to another location.
3237 Takes a string argument representing a file name, or a list of such strings
3243 manipulations where GN doesn't know something is a file name, you will need
3250 If you want to convert a file path to be source-absolute (that is, beginning
3254 it can't also generate source-absolute paths without more special-cases.
3261 A string or list of strings representing file or directory names. These
3268 to the current BUILD-file's directory).
3271 paths will be converted to system-absolute native style paths with system
3277 current build file. Use "." (the default) to convert paths from the
3278 current BUILD-file's directory.
3285 a list of strings). All relative and source-absolute file names will be
3286 converted to be relative to the requested output System-absolute paths will
3299 # Convert a file in the current directory to be relative to the build
3304 # Convert a file to be system absolute:
3316 # Extra file args passed manually need to be explicitly converted
3319 "--data",
3321 "--rel",
3336 configuration file. Since the build configuration file is processed
3337 separately for each toolchain, this function will be a no-op when called
3338 under any non-default toolchains.
3341 environment. If the current environment is 32-bit and somebody references a
3342 target with a 64-bit toolchain, we wouldn't want processing of the build
3343 config file for the 64-bit toolchain to reset the default toolchain to
3344 64-bit, we want to keep it 32-bits.
3366 ### <a name="func_set_defaults"></a>**set_defaults**: Set default values for a target type.
3371 Sets the default values for a given target type. Whenever target_type_name is
3375 When the target type is used, the variable copying is very strict. If a
3379 set_defaults can be used for built-in target types ("executable",
3395 # The configs will be auto-populated as above. You can remove it if
3397 configs -= [ "//tools/mything:settings" ]
3400 ### <a name="func_split_list"></a>**split_list**: Splits a list into N different sub-lists.
3405 Given a list and a number N, splits the list into N sub-lists of
3406 approximately equal size. The return value is a list of the sub-lists. The
3434 string_join("", ["a", "b", "c"]) --> "abc"
3435 string_join("|", ["a", "b", "c"]) --> "a|b|c"
3436 string_join(", ", ["a", "b", "c"]) --> "a, b, c"
3437 string_join("s", ["", ""]) --> "s"
3475 string_split("") --> []
3476 string_split("a") --> ["a"]
3477 string_split(" aa bb") --> ["aa", "bb"]
3483 string_split("", "|") --> [""]
3484 string_split(" a b ", " ") --> ["", "", "a", "b", "", ""]
3485 string_split("aa+-bb+-c", "+-") --> ["aa", "bb", "c"]
3491 to add to the built-in target types.
3494 template, just use the name of the template like any other target type.
3496 Often you will want to declare your template in a special file that other
3513 against which relative file names are resolved. The current directory will be
3514 that of the invoking code, since typically that code specifies the file
3519 scope to a target that it defines. Often, such variables might be optional.
3532 #### **Target naming**
3535 Your template should almost always define a built-in target with the name the
3541 another target specifies a dependency on "foo", the static_library or
3562 You can use template to redefine a built-in target in which case your template
3563 takes a precedence over the built-in one. All uses of the target from within
3564 the template definition will refer to the built-in target which makes it
3565 possible to extend the behavior of the built-in target:
3581 # giving the user an error about an undefined variable in the file defining
3589 # Name of the intermediate target that does the code gen. This must
3590 # incorporate the target name so it's unique across template
3594 # Intermediate target to convert IDL to C source. Note that the name is
3597 # (since all target names are in the global scope).
3603 # Note that we need an absolute path for our script file name. The
3607 # to the template file, we'll need to use an absolute path instead.
3624 # This target depends on the files produced by the above code gen target.
3641 # Here is a target that depends on our template.
3689 "rust_cdylib": Tool for compiling C-compatible dynamic libraries.
3716 Default directory name for the output file relative to the
3719 but will be overridden by the "output_dir" variable in a target, if one
3723 potentially with target-specific overrides. It is the tool's job to use
3732 by by the "output extension" variable in a target, if one is specified.
3736 along, potentially with target-specific overrides. One would typically
3745 resulting file. These files are used to list header file dependencies
3789 lib_switch = "-l"
3790 lib_dir_switch = "-L"
3794 "-lfreetype -lexpat".
3806 framework_switch = "-framework "
3807 weak_framework_switch = "-weak_framework "
3808 framework_dir_switch = "-F"
3814 "-F. -framework UIKit -framework Foo -weak_framework MediaPlayer"
3823 swiftmodule_swift = "-Wl,-add_ast_path,"
3827 "-Wl,-add_ast_path,obj/foo/Foo.swiftmodule"
3834 one output file. There can be more than one output (a linker might
3852 the target to override these values.
3863 evaluated for each file listed in the "sources" of the target.
3866 list one object file per source file when whole module optimization
3889 and the third one to be the .dll file. On Linux, if you're not doing
3897 be prepended to the name of the target (or the output_name if one is
3901 Individual targets can opt-out of the output prefix by setting:
3916 For precompiled headers to be used for a given target, the target (or a
3918 "msvc"-style headers, a "precompiled_source" value. If the type is
3920 resolve to the same file, despite the different formats required for
3928 Requests that Ninja check the file timestamp after this tool has run to
3930 skip writing output if the output file has not changed.
3943 Name of the response file. If empty, no response file will be
3949 The contents to be written to the response file. This may include all
3951 around OS command-line length limits.
3953 This example adds the inputs and libraries to a response file, but
3956 command = "link -o {{output}} {{ldflags}} @{{output}}.rsp"
3972 process, but may be used when generating metadata for rust-analyzer.
3973 (See --export-rust-project). It enables such metadata to include
3981 For ld-like linkers, -Clink-arg=-Bdynamic may be a good choice.
3983 listing any non-Rust dependencies. This may be necessary because
3998 The label of the current target. This is typically used in the
4004 The short name of the label of the target. This is the part after the
4007 the tool or the "output_name" set on the target.
4010 The label of the current target, never including the toolchain
4021 The directory of the generated file and output directories,
4022 respectively, for the current target. There is no trailing slash. See
4026 The short name of the current target with no path information, or the
4027 value of the "output_name" variable if one is specified in the target.
4030 Example: "libfoo" for the target named "foo" and an output prefix for
4034 with a set of compiler-specific flags. The following expansions are
4046 directories specified for the target.
4047 Example: "--enable-foo --enable-bar"
4049 Defines will be prefixed by "-D" and include directories will be
4050 prefixed by "-I" (these work with Posix tools as well as Microsoft
4056 modules referenced by the current target. The "_no_self" version doesn't
4057 include the module for the current target, and can be used to compile
4061 The relative path and name of the current input file.
4065 The file part of the source including the extension (with no directory
4070 The filename part of the source file with no directory or extension.
4075 The directory in the generated file and output directories,
4076 respectively, for the current input file. If the source file is in the
4077 same directory as the target is declared in, they will will be the same
4078 as the "target" versions above. Example: "gen/base/test"
4092 take a "-filelist" flag which expects newline separated files, and some
4093 Microsoft tools have a fixed-sized buffer for parsing each line of a
4094 response file.
4098 specified for the target.
4099 Example: "-m64 -fPIC -pthread -L/usr/local/mylib"
4105 Example: "-lfoo -lbar"
4108 The value of the "output_dir" variable in the target, or the the value
4109 of the "default_output_dir" value in the tool if the target does not
4115 based on the target's path and not overridable. {{output_dir}} is for
4123 The value of the "output_extension" variable in the target, or the
4124 value of the "default_output_extension" value in the tool if the target
4139 Any Rust .rlibs which need to be linked into a final C++ target.
4149 {{frameworks}} and each item will be preceded by "-framework" or
4150 "-weak_framework".
4155 Swift compiler (the .swiftmodule file cannot be embedded in object
4185 property of the corresponding create_bundle target.
4190 the create_bundle target.
4194 create_bundle target.
4197 dependencies by looking for any file matching "*/*.xcassets/*" pattern.
4201 output of .swiftmodule type, but can have one or more object file outputs,
4205 Expands to the string representing the module name of target under
4209 Expands to the list of -I<path> for the target Swift module search
4210 path computed from target dependencies.
4216 with a set of compiler-specific flags. The following expansions are
4220 Expands to the string representing the crate name of target under
4224 Expands to the string representing the type of crate for the target
4228 Expands to the list of --extern flags needed to include addition Rust
4229 libraries in this target. Includes any specified renamed dependencies.
4232 Expands to the list of -Ldependency=<path> strings needed to compile
4233 this target.
4246 dependent targets be re-linked. If the shared library is changed but no
4251 writes the file only if the new one is different, the timestamp of this file
4252 can be used for triggering re-links, while the actual shared library would be
4258 of the dependency file has changed after linking (otherwise it will always
4280 lib_switch = "-l"
4281 lib_dir_switch = "-L"
4284 command = "gcc {{source}} -o {{output}}"
4289 command = "g++ {{source}} -o {{output}}"
4305 You can have more than one toolchain in use at once in a build and a target
4306 can exist simultaneously in multiple toolchains. A build file is executed
4308 parameters of each target (or which targets exist) on a per-toolchain basis.
4310 When you have a simple build with only one toolchain, the build config file
4316 When a target has a dependency on a target using different toolchain (see "gn
4318 secondary toolchain to resolve the target. GN will load the build config file
4323 To load a file in an alternate toolchain, GN does the following:
4325 1. Loads the file with the toolchain definition in it (as determined by the
4327 2. Re-runs the master build configuration file, applying the arguments
4329 3. Loads the destination build file in the context of the configuration file
4332 The toolchain configuration is two-way. In the default toolchain (i.e. the
4333 main build target) the configuration flows from the build config file to the
4334 toolchain. The build config file looks at the state of the build (OS type,
4337 from the toolchain to the build config file: the "toolchain_args" in the
4338 toolchain definition specifies the arguments to re-invoke the build.
4353 When you specify a target using an alternate toolchain, the master build
4354 configuration file is re-interpreted in the context of that toolchain.
4377 When true, configs (public and all-dependent) will cross the boundary out
4387 any target in the toolchain is compiled. To avoid circular dependencies
4408 use_doom_melon = true # Doom melon always required for 32-bit builds.
4426 #### **Example of cross-toolchain dependencies**
4429 If a 64-bit target wants to depend on a 32-bit binary, it would specify a
4431 runtime and aren't linked, since you can't link a 32-bit and a 64-bit
4437 # The 64-bit build needs this 32-bit helper.
4443 # Our helper library is only compiled in 32-bits.
4449 ### <a name="func_write_file"></a>**write_file**: Write a file to disk.
4454 If data is a list, the list will be written one-item-per-line with no quoting
4457 If the file exists and the contents are identical to that being written, the
4458 file will not be updated. This will prevent unnecessary rebuilds of targets
4459 that depend on this file.
4478 ## <a name="predefined_variables"></a>Built-in predefined variables
4511 A fully-qualified label representing the current toolchain. You can use this
4512 to make toolchain-related decisions in the build. See also
4526 A fully-qualified label representing the default toolchain, which may not
4532 Corresponds to the number printed by `gn --version`.
4543 This is value is exposed so that cross-compile toolchains can access the host
4546 The value should generally be considered read-only, but it can be overridden
4548 values for the host architecture (e.g., if you can do either 32-bit or 64-bit
4555 - "x64"
4556 - "x86"
4561 This value is exposed so that cross-compiles can access the host build
4564 This value should generally be treated as read-only. It, however, is not used
4571 - "linux"
4572 - "mac"
4573 - "win"
4660 args = [ "-o", rebase_path(root_out_dir, root_build_dir) ]
4671 cross-compiles, this can be set to something different. This value is
4680 command line or in the args.gn file.
4686 - "x86"
4687 - "x64"
4688 - "arm"
4689 - "arm64"
4690 - "mipsel"
4691 - "mips64el"
4692 - "s390x"
4693 - "ppc64"
4694 - "riscv32"
4695 - "riscv64"
4696 - "e2k"
4697 - "loong64"
4699 ### <a name="var_target_gen_dir"></a>**target_gen_dir**: Directory for a target's generated files.
4702 Absolute path to the target's generated file directory. This will be the
4703 "root_gen_dir" followed by the relative path to the current build file. If
4704 your file is in "//tools/doom_melon" then target_gen_dir would be
4720 args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]
4723 ### <a name="var_target_name"></a>**target_name**: [string] The name of the current target.
4726 Inside a target or template invocation, this variable refers to the name
4727 given to the target or template invocation. Outside of these, this variable
4732 ensure generated targets have unique names and to generate a target with the
4736 defining a target inside a template, target_name will refer to the target
4739 outside of any target definitions.
4770 cross-compiles, it may be different. This variable differs from "current_os"
4789 line or in the args.gn file.
4795 - "android"
4796 - "chromeos"
4797 - "ios"
4798 - "linux"
4799 - "nacl"
4800 - "mac"
4801 - "win"
4803 ### <a name="var_target_out_dir"></a>**target_out_dir**: [string] Directory for target output files.
4806 Absolute path to the target's generated file directory. If your current
4807 target is in "//tools/doom_melon" then this value might be
4823 args = [ "-o", rebase_path(target_out_dir, root_build_dir) ]
4828 ### <a name="var_aliased_deps"></a>**aliased_deps**: [scope] Set of crate-dependency pairs.
4837 All dependencies listed in this field *must* be listed as deps of the target.
4844 This target would compile the `foo` crate with the following `extern` flag:
4845 `rustc ...command... --extern bar=<build_out_dir>/obj/bar`
4855 With the addition of `aliased_deps`, above target would instead compile with:
4856 `rustc ...command... --extern bar_renamed=<build_out_dir>/obj/bar`
4865 configs will also apply to the current target.
4867 This addition happens in a second phase once a target and all of its
4868 dependencies have been resolved. Therefore, a target will not see these
4869 force-added configs in their "configs" variable while the script is running,
4872 target's headers.
4880 1. Those set on the current target (not in a config).
4881 2. Those set on the "configs" on the target in order that the
4883 3. Those set on the "all_dependent_configs" on the target in order
4885 4. Those set on the "public_configs" on the target in order that
4897 A list of target labels. Must be a subset of the target's "deps". These
4898 targets will be permitted to include headers from the current target despite
4911 Normally, for a file in target A to include a file from target B, A must list
4913 the --check flag to "gn gen" -- see "gn help check").
4922 target can include header files from the current target. That is, if A
4974 any other target type will be a no-op. As with ldflags, you could put the
4986 1. Those set on the current target (not in a config).
4987 2. Those set on the "configs" on the target in order that the
4989 3. Those set on the "all_dependent_configs" on the target in order
4991 4. Those set on the "public_configs" on the target in order that
5000 ### <a name="var_args"></a>**args**: (target variable) Arguments passed to an action.
5005 source_expansion") to insert the source file names.
5009 allow actions that run compiler or compiler-like tools to access the results
5012 args = [ "{{defines}}", "{{include_dirs}}", "{{rustenv}}", "--input-file",
5023 file as input.
5029 1. Those set on the current target (not in a config).
5030 2. Those set on the "configs" on the target in order that the
5032 3. Those set on the "all_dependent_configs" on the target in order
5034 4. Those set on the "public_configs" on the target in order that
5049 dependencies of the target. These include all public, private, and data
5054 Checking does not cross executable boundaries. If a target depends on an
5057 allows assert_no_deps to express what is distributed in the final target
5059 non-distributable code).
5066 on a target or set of targets. One efficient way to express this is to create
5079 "//foo:test_support", # This target is also disallowed.
5083 ### <a name="var_bridge_header"></a>**bridge_header**: [string] Path to C/Objective-C compatibility…
5088 Path to an header that includes C/Objective-C functions and types that
5097 This string is used by the "create_bundle" target to expand the
5098 {{bundle_contents_dir}} of the "bundle_data" target it depends on. This must
5106 A list of target labels.
5108 This list contains target label patterns that should be filtered out when
5109 creating the bundle. Any target matching one of those label will be removed
5110 from the dependencies of the create_bundle target.
5129 # third_party/icu and thus does not need the icudtl.dat file.
5142 This string is used by the "create_bundle" target to expand the
5143 {{bundle_executable_dir}} of the "bundle_data" target it depends on. This
5156 This string is used by the "create_bundle" target to expand the
5157 {{bundle_resources_dir}} of the "bundle_data" target it depends on. This must
5167 This string is used by the "create_bundle" target to expand the
5168 {{bundle_root_dir}} of the "bundle_data" target it depends on. This must
5196 To target one of these variants individually, use "cflags_c", "cflags_cc",
5197 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
5201 See also "asmflags" for flags for assembly-language files, "swiftflags" for
5208 1. Those set on the current target (not in a config).
5209 2. Those set on the "configs" on the target in order that the
5211 3. Those set on the "all_dependent_configs" on the target in order
5213 4. Those set on the "public_configs" on the target in order that
5230 To target one of these variants individually, use "cflags_c", "cflags_cc",
5231 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
5235 See also "asmflags" for flags for assembly-language files, "swiftflags" for
5242 1. Those set on the current target (not in a config).
5243 2. Those set on the "configs" on the target in order that the
5245 3. Those set on the "all_dependent_configs" on the target in order
5247 4. Those set on the "public_configs" on the target in order that
5264 To target one of these variants individually, use "cflags_c", "cflags_cc",
5265 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
5269 See also "asmflags" for flags for assembly-language files, "swiftflags" for
5276 1. Those set on the current target (not in a config).
5277 2. Those set on the "configs" on the target in order that the
5279 3. Those set on the "all_dependent_configs" on the target in order
5281 4. Those set on the "public_configs" on the target in order that
5298 To target one of these variants individually, use "cflags_c", "cflags_cc",
5299 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
5303 See also "asmflags" for flags for assembly-language files, "swiftflags" for
5310 1. Those set on the current target (not in a config).
5311 2. Those set on the "configs" on the target in order that the
5313 3. Those set on the "all_dependent_configs" on the target in order
5315 4. Those set on the "public_configs" on the target in order that
5332 To target one of these variants individually, use "cflags_c", "cflags_cc",
5333 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
5337 See also "asmflags" for flags for assembly-language files, "swiftflags" for
5344 1. Those set on the current target (not in a config).
5345 2. Those set on the "configs" on the target in order that the
5347 3. Those set on the "all_dependent_configs" on the target in order
5349 4. Those set on the "public_configs" on the target in order that
5358 ### <a name="var_check_includes"></a>**check_includes**: [boolean] Controls whether a target's file…
5362 --check flag) will check this target's sources and headers for proper
5365 When false, the files in this target will be skipped by default. This does
5366 not affect other targets that depend on the current target, it just skips
5367 checking the includes of the current target's files.
5381 # This target's includes are messed up, exclude it from checking.
5386 …ng_args"></a>**code_signing_args**: [string list] [deprecated] Args for the post-processing script.
5390 pass to the post-processing script. Typically you would use source expansion
5391 (see "gn help source_expansion") to insert the source file names.
5394 the "create_bundle" target. It is still supported to avoid breaking existing
5399 …_code_signing_outputs"></a>**code_signing_outputs**: [file list] [deprecated] Outputs of the post-…
5402 Outputs from the post-processing step of a create_bundle target. Must refer to
5406 the "create_bundle" target. It is still supported to avoid breaking existing
5411 …ar_code_signing_script"></a>**code_signing_script**: [file name] [deprecated] Script for the post-…
5414 An absolute or buildfile-relative file name of a Python script to run for a
5415 create_bundle target to perform the post-processing step.
5418 the "create_bundle" target. It is still supported to avoid breaking existing
5423 …_code_signing_sources"></a>**code_signing_sources**: [file list] [deprecated] Sources for the post…
5426 A list of files used as input for the post-processing step of a create_bundle
5427 target. Non-absolute paths will be resolved relative to the current build
5428 file.
5431 the "create_bundle" target. It is still supported to avoid breaking existing
5441 chain until a linkable target (an executable or shared library) is reached.
5442 The final linkable target only links each static library once, even if it
5454 GN treats non-complete static libraries as source sets when they are linked
5459 In rare cases it makes sense to list a header in more than one target if it
5471 ### <a name="var_configs"></a>**configs**: Configs applying to this target or config.
5477 #### **Configs on a target**
5480 When used on a target, the include_dirs, defines, etc. in each config are
5481 appended in the order they appear to the compile command for each file in the
5482 target. They will appear after the include_dirs, defines, etc. that the
5483 target sets directly.
5485 Since configs apply after the values set on a target, directly setting a
5487 flag instead, you can put that flag in a one-off config and append that
5488 config to the target's configs list.
5491 applying to a given target type (see "set_defaults"). When a target is being
5503 own values, and in order, the values from its sub-configs *before* anything
5506 - A target has no visibility into a config's sub-configs. Target code only
5507 sees the name of the composite config. It can't remove sub-configs or opt
5509 before the target is.
5511 - You can get duplication of values if a config is listed twice, say, on a
5512 target and in a sub-config that also applies. In other cases, the configs
5513 applying to a target are de-duped. It's expected that if a config is
5514 listed as a sub-config that it is only used in that context. (Note that
5515 it's possible to fix this and de-dupe, but it's not normally relevant and
5522 1. Those set on the current target (not in a config).
5523 2. Those set on the "configs" on the target in order that the
5525 3. Those set on the "all_dependent_configs" on the target in order
5527 4. Those set on the "public_configs" on the target in order that
5540 # Configs on a target.
5543 configs -= [ "//build:no_rtti" ]
5551 # because it allows a target to opt in to either a default set, or a more
5564 ### <a name="var_contents"></a>**contents**: Contents to write to file.
5567 The contents of the file for a generated_file target.
5576 If crate_name is not set, then this rule will use the target name.
5578 ### <a name="var_crate_root"></a>**crate_root**: [string] The root source file for a binary or libr…
5584 This file is usually the `main.rs` or `lib.rs` for binaries and libraries,
5587 If crate_root is not set, then this rule will look for a lib.rs file (or
5588 main.rs for executable) or a single file in sources, if sources contains
5589 only one file.
5597 Options for this field are "cdylib", "staticlib", "proc-macro", and "dylib".
5598 This field sets the `crate-type` attribute for the `rustc` tool on static
5611 ### <a name="var_data"></a>**data**: Runtime data file dependencies.
5614 Lists files or directories required to run the given target. These are
5616 as being relative to the current build file. Since these are runtime
5624 "--runtime-deps-list-file".
5626 GN doesn't require data files to exist at build-time. So actions that produce
5640 ### <a name="var_data_deps"></a>**data_deps**: Non-linked dependencies.
5643 A list of target labels.
5645 Specifies dependencies of a target that are not actually linked into the
5646 current target. Such dependencies will be built and will be available at
5650 target needs at runtime.
5669 These keys are used to identify metadata to collect. If a walked target
5687 1. Those set on the current target (not in a config).
5688 2. Those set on the "configs" on the target in order that the
5690 3. Those set on the "all_dependent_configs" on the target in order
5692 4. Those set on the "public_configs" on the target in order that
5707 ### <a name="var_depfile"></a>**depfile**: [string] File name for input dependencies for actions.
5711 target will generate the given ".d" file containing the dependencies of the
5714 A depfile should be used only when a target depends on files that are not
5715 already specified by a target's inputs and sources. Likewise, depfiles should
5718 The .d file should go in the target output directory. If you have more than
5719 one source file that the script is being run over, you can use the output
5720 file expansions described in "gn help action_foreach" to name the .d file
5728 action's "outputs" unless another target will use the file as an input.
5742 # Say our script uses "-o <d file>" to indicate the depfile.
5743 args = [ "{{source}}", "-o", rebase_path(depfile, root_build_dir)]
5749 A list of target labels.
5751 Specifies private dependencies of a target. Private dependencies are
5760 Source sets, shared libraries, and non-complete static libraries will be
5761 propagated up the dependency tree across groups, non-complete static
5770 of target type. all_dependent_configs are always propagated across all types
5775 target. If the dependency is a C/C++ target, the path to that target will
5783 ### <a name="var_externs"></a>**externs**: [scope] Set of Rust crate-dependency pairs.
5789 These libraries will be passed as `--extern crate_name=path` to compiler
5790 invocation containing the current target.
5804 This target would compile the `foo` crate with the following `extern` flag:
5805 `--extern bar=path/to/bar.rlib`.
5813 the files in the affected target.
5819 1. Those set on the current target (not in a config).
5820 2. Those set on the "configs" on the target in order that the
5822 3. Those set on the "all_dependent_configs" on the target in order
5824 4. Those set on the "public_configs" on the target in order that
5845 type target.
5851 1. Those set on the current target (not in a config).
5852 2. Those set on the "configs" on the target in order that the
5854 3. Those set on the "all_dependent_configs" on the target in order
5856 4. Those set on the "public_configs" on the target in order that
5877 Normally if a target lists headers in the "public" list (see "gn help
5884 target and require internal knowledge without opening up all headers to be
5887 A friend target does not allow that target to include headers when no
5889 targets to include any headers from a destination target. The friend
5893 The friend annotation is matched only against the target containing the file
5902 # This target can include our private headers.
5914 # because this target defines a list of "public" headers. Without the
5922 # This can include "private_api.h" from the :lib target because it
5923 # depends on that target and because of the friend annotation.
5935 A list of target labels.
5938 (see "gn help execution"). If this target is generated, then any targets in
5950 in the affected target.
5956 1. Those set on the current target (not in a config).
5957 2. Those set on the "configs" on the target in order that the
5959 3. Those set on the "all_dependent_configs" on the target in order
5961 4. Those set on the "public_configs" on the target in order that
5976 ### <a name="var_inputs"></a>**inputs**: Additional compile-time dependencies.
5979 Inputs are compile-time dependencies of the current target. This means that
6003 running GN to determine the inputs, and is easier to keep in-sync than
6012 sources in the GN target (or worse, enumerate the files in an exec_script
6015 The problem happens if a file is ever removed because the inputs are not
6017 and all inputs are up to date, the script will not re-run and you will get a
6019 script, or if there are many, create a separate list file that the script
6020 reads. As long as this file is listed in the inputs, the build will detect
6021 when it has changed in any way and the action will re-run.
6028 linking the target. Normally, all actions that a target depends on will be run
6029 before any files in a target are compiled. So if you depend on generated
6033 that changes in any of the inputs will force all sources in the target to be
6035 want to split those into a separate target to avoid unnecessary recompiles.
6051 These flags are passed on the command-line to the linker and generally
6056 static libraries will be a no-op. If you want to apply ldflags to dependent
6064 1. Those set on the current target (not in a config).
6065 2. Those set on the "configs" on the target in order that the
6067 3. Those set on the "all_dependent_configs" on the target in order
6069 4. Those set on the "public_configs" on the target in order that
6085 being relative to the current build file.
6089 shared library or executable target is reached. Second, they are
6097 1. Those set on the current target (not in a config).
6098 2. Those set on the "configs" on the target in order that the
6100 3. Those set on the "all_dependent_configs" on the target in order
6102 4. Those set on the "public_configs" on the target in order that
6127 library) containing the current target.
6131 shared library or executable target is reached. Second, they are
6141 File paths
6152 "lib_dirs" so the given library is found. Your BUILD.gn file should not
6153 specify the switch (like "-l"): this will be encoded in the "lib_switch"
6160 1. Those set on the current target (not in a config).
6161 2. Those set on the "configs" on the target in order that the
6163 3. Those set on the "all_dependent_configs" on the target in order
6165 4. Those set on the "public_configs" on the target in order that
6188 ### <a name="var_metadata"></a>**metadata**: Metadata of this target.
6191 Metadata is a collection of keys and values relating to a particular target.
6195 particular source directory, and lists of target labels intended to be used
6217 building a target. These are commonly set with the format "CXX $output"
6229 If module_name is not set, then this rule will use the target name.
6234 Controls how the "contents" of a generated_file target is formatted.
6237 ### <a name="var_output_dir"></a>**output_dir**: [directory] Directory to put output file in.
6248 target is only present in one toolchain.
6264 ### <a name="var_output_extension"></a>**output_extension**: Value to use for the output's file ext…
6267 Normally the file extension for a target is based on the target type and the
6276 which the linker tool will generally use to specify the output file name. See
6300 ### <a name="var_output_name"></a>**output_name**: Define a name for the output file other than the…
6303 Normally the output name of a target will be based on the target name, so the
6304 target "//foo/bar:bar_unittests" will generate an output file such as
6313 output prefix of a linker tool on a per- target basis. If you need more
6314 flexibility, create a copy target to produce the file you want.
6316 This variable is valid for all binary output target types.
6329 A boolean that overrides the output prefix for a target. Defaults to false.
6331 Some systems use prefixes for the names of the final target output file. The
6332 normal example is "libfoo.so" on Linux for a target named "foo".
6334 The output prefix for a given target type is specified on the linker tool
6353 Outputs is valid for "copy", "action", and "action_foreach" target types and
6359 exactly one source, this can be a literal file name or a source expansion.
6367 the name of the input file). See "gn help action_foreach".
6370 Action targets (excluding action_foreach) must list literal output file(s)
6376 Valid for create_bundle target, corresponds to the path for the partial
6378 with the application Info.plist (usually done by the post-processing script).
6380 The file will be generated regardless of whether the asset compiler has
6386 A fully-qualified label representing the pool that will be used for binary
6403 …t_processing_args"></a>**post_processing_args**: [string list] Args for the post-processing script.
6407 pass to the post-processing script. Typically you would use source expansion
6408 (see "gn help source_expansion") to insert the source file names.
6412 …r_post_processing_outputs"></a>**post_processing_outputs**: [file list] Outputs of the post-proces…
6415 Outputs from the post-processing step of a create_bundle target. Must refer to
6420 …var_post_processing_script"></a>**post_processing_script**: [file name] Script for the post-proces…
6423 An absolute or buildfile-relative file name of a Python script to run for a
6424 create_bundle target to perform the post-processing step.
6428 …_post_processing_sources"></a>**post_processing_sources**: [file list] Sources for the post-proces…
6431 A list of files used as input for the post-processing step of a create_bundle
6432 target. Non-absolute paths will be resolved relative to the current build
6433 file.
6437 ### <a name="var_precompiled_header"></a>**precompiled_header**: [string] Header file to precompile.
6440 Precompiled headers will be used when a target specifies this value, or a
6441 config applying to this target specifies this value. In addition, the tool
6446 The precompiled header/source variables can be specified on a target or a
6447 config, but must be the same for all configs applying to a given target since
6448 a target can only have one precompiled header.
6450 If you use both C and C++ sources, the precompiled header and source file
6452 includes in __cplusplus #ifdefs so the file will compile in C mode.
6458 When using GCC-style precompiled headers, "precompiled_source" contains the
6459 path of a .h file that is precompiled and then included by all source files
6462 The value of "precompiled_header" is not used with GCC-style precompiled
6469 When using MSVC-style precompiled headers, the "precompiled_header" value is
6470 a string corresponding to the header. This is NOT a path to a file that GN
6475 MSVC also requires a source file to compile the header with. This must be
6477 this IS a GN-style file name, and tells GN which source file to compile to
6478 make the .pch file used for subsequent compiles.
6495 # first, or you can do this to force-include the header.
6499 And then define a target that uses the config:
6510 ### <a name="var_precompiled_source"></a>**precompiled_source**: [file name] Source file to precomp…
6513 The source file that goes along with the precompiled_header when using
6514 "msvc"-style precompiled headers. It will be implicitly added to the sources
6515 of the target. See "gn help precompiled_header".
6523 target to control whether a "bundle_data" needs to be propagated or not.
6526 "create_bundle" with a non-empty product_type will have a corresponding
6527 target in the project.
6529 ### <a name="var_public"></a>**public**: Declare public header files for a target.
6536 to depend on this target) can include any file in the sources list. If this
6537 variable is defined on a target, dependent targets may only include files on
6538 this whitelist unless that target is marked as a friend (see "gn help
6541 Header file permissions are also subject to visibility. A target must be
6542 visible to another target to include any files from it at all and the public
6547 dependency A -> B -> C, then A can include C's public headers. However, the
6552 targets. If a file is included that is not known to the build, it will be
6556 associated code. In this case, list the test target in the "friend" list of
6557 the target that owns the private header to allow the inclusion. See
6560 When a binary target has no explicit or implicit public headers (a "public"
6561 list is defined but is empty), GN assumes that the target can not propagate
6562 any compile-time dependencies up the dependency tree. In this case, the build
6565 A (shared library) -> B (shared library) -> C (action).
6588 variable added to them. These configs will also apply to the current target.
6590 necessary to compile this target's header files.
6599 These dependent targets can further push this target's public configs
6604 # This target will get "my_config" applied to it. However, since this
6605 # target uses "deps" and not "public_deps", targets that depend on this
6611 # Depending on "lower" in any way will apply "my_config" to this target.
6612 # Additionall, since this target depends on "lower" via public_deps,
6622 Public config propagation happens in a second phase once a target and all of
6623 its dependencies have been resolved. Therefore, a target will not see these
6624 force-added configs in their "configs" variable while the script is running,
6631 toolchain") on the toolchain of the target declaring the public_config.
6634 #### **Avoiding applying public configs to this target**
6647 # Internal target to actually compile the sources.
6659 1. Those set on the current target (not in a config).
6660 2. Those set on the "configs" on the target in order that the
6662 3. Those set on the "all_dependent_configs" on the target in order
6664 4. Those set on the "public_configs" on the target in order that
6677 additionally express that the current target exposes the listed deps as part
6682 - public_configs that are part of the dependency are forwarded to direct
6685 - Public headers in the dependency are usable by dependents (includes do
6688 - If the current target is a shared library, other shared libraries that it
6698 Say you have three targets: A -> B -> C. C's visibility may allow B to depend
6705 Generally if you are writing a target B and you include C's headers as part
6713 # This target can include files from "c" but not from
6728 declared file. Defaults to false.
6730 Metadata generally declares files as strings relative to the local build file.
6733 file's location and thus allow the filename to be used anywhere.
6735 Setting this flag will raise an error if any target's specified metadata is
6740 …ar_response_file_contents"></a>**response_file_contents**: Contents of a response file for actions.
6744 command-line capabilities. This is especially the case on Windows where the
6745 maximum command-line length is less than 8K. A response file allows you to
6746 pass an unlimited amount of data to a script in a temporary file for an
6747 action or action_foreach target.
6749 If the response_file_contents variable is defined and non-empty, the list
6751 that will be written to a temporary file at build time. The name of the
6752 temporary file will be substituted for "{{response_file_name}}" in the script
6755 The response file contents will always be quoted and escaped according to
6756 Unix shell rules. To parse the response file, the Python script should use
6767 # Write all the inputs to a response file for the script. Also,
6771 # The script expects the name of the response file in --file-list.
6773 "--enable-foo",
6774 "--file-list={{response_file_name}}",
6785 ### <a name="var_script"></a>**script**: Script file for actions.
6788 An absolute or buildfile-relative file name of a Python script to run for a
6792 ### <a name="var_sources"></a>**sources**: Source files for a target
6795 A list of files. Non-absolute paths will be resolved relative to the current
6796 build file.
6802 For binary targets (source sets, executables, and libraries), the known file
6803 types will be compiled with the associated tools. Unknown file types and
6808 As a special case, a file ending in ".def" will be treated as a Windows
6809 module definition file. It will be appended to the link line with a
6810 preceding "/DEF:" string. There must be at most one .def file in a target
6811 and they do not cross dependency boundaries (so specifying a .def file in a
6816 look for a lib.rs file (or main.rs for executable) or a single file in
6817 sources, if sources contains only one file.
6820 #### **Sources for non-binary targets**
6825 script will run once per file.
6840 file as input.
6846 1. Those set on the current target (not in a config).
6847 2. Those set on the "configs" on the target in order that the
6849 3. Those set on the "all_dependent_configs" on the target in order
6851 4. Those set on the "public_configs" on the target in order that
6860 ### <a name="var_testonly"></a>**testonly**: Declares a target must only be used for testing.
6865 When a target is marked "testonly = true", it must only be depended on by
6866 other test-only targets. Otherwise, GN will issue an error that the
6886 Valid for "create_bundle" target. If true, the "create_bundle" target will
6888 depends on it (unless the "bundle_data" target sets "product_type" to the
6889 same value as the "create_bundle" target).
6891 ### <a name="var_visibility"></a>**visibility**: A list of labels that can depend on a target.
6901 depend on the current target. The empty list means no targets can depend on
6902 the current target.
6904 Tip: Often you will want the same visibility for all targets in a BUILD file.
6906 target, and the targets will inherit that scope and see the definition.
6927 Any target ("public", the default):
6933 Any target in "//bar/BUILD.gn":
6936 Any target in "//bar/" or any subdirectory thereof:
6942 Any target in the current directory and any subdirectory thereof, plus
6952 barriers. If a specified key is defined in a target's metadata, the walk will
6955 If no walk_keys are specified for a generated_file target (i.e. "[""]"), the
6956 walk will touch all deps and data_deps of the specified target recursively.
6966 type target. Weak linking instructs the dynamic loader to attempt to load
6976 1. Those set on the current target (not in a config).
6977 2. Those set on the "configs" on the target in order that the
6979 3. Those set on the "all_dependent_configs" on the target in order
6981 4. Those set on the "public_configs" on the target in order that
6996 ### <a name="var_write_runtime_deps"></a>**write_runtime_deps**: Writes the target's runtime_deps t…
6999 Does not synchronously write the file, but rather schedules it to be written
7002 If the file exists and the contents are identical to that being written, the
7003 file will not be updated. This will prevent unnecessary rebuilds of targets
7004 that depend on this file.
7010 The format of this file will list one file per line with no escaping. The
7011 files will be relative to the root_build_dir. The first line of the file will
7012 be the main output file of the target itself. The file contents will be the
7014 help --runtime-deps-list-file").
7021 Valid for create_bundle target. Those flags are directly passed to
7030 generating with --ide=xcode.
7034 …="var_xcode_test_application_name"></a>**xcode_test_application_name**: Name for Xcode test target.
7037 Each unit and ui test target must have a test application target, and this
7065 built-in arguments are:
7066 - host_cpu
7067 - host_os
7068 - current_cpu
7069 - current_os
7070 - target_cpu
7071 - target_os
7073 Next, project-specific overrides are applied. These are specified inside
7076 If specified, arguments from the --args command line flag are used. If that
7078 be used (this is in the file args.gn in the build directory).
7080 Last, for targets being compiled with a non-default toolchain, the toolchain
7082 toolchain definition. The use-case for this is that a toolchain may be
7095 something like this into that file:
7099 gn gen out/FooBar --args="enable_doom_melon=true os=\"android\""
7113 Often, the root build config file will declare global arguments that will be
7116 "import"-ed file if you want such arguments to apply to multiple buildfiles.
7118 ### <a name="dotfile"></a>**.gn file**
7122 for a file called ".gn". This indicates the source root. You can override
7123 this detection by using the --root command-line argument
7125 The .gn file in the source root will be executed. The syntax is the same as a
7126 buildfile, but with very limited build setup-specific meaning.
7128 If you specify --root, by default GN will look for the file .gn in that
7129 directory. If you want to specify a different file, you can additionally pass
7130 --dotfile:
7132 gn gen out/Debug --root=/home/build --dotfile=/home/my_gn_file.gn
7139 Path to a file containing the text that should be used as the default
7143 Path to the build config file. This file will be used to set up the
7144 build file execution environment for each toolchain.
7148 "gn check" or "gn gen --check". If neither check_targets or
7159 running "gn check" or "gn gen --check". All other targets will be checked.
7169 when running "gn check" or "gn gen --check". System style includes are
7173 "gn check --check-system" or "gn gen --check=system"
7178 be checked against this list and GN will fail if the current file isn't
7198 When specified, GN will generate a compile_commands.json file in the root
7200 source file reachable from any label matching any pattern in the list.
7201 This is used for Clang-based tooling and some editor integration. See
7204 The switch --add-export-compile-commands to "gn gen" (see "gn help gen")
7205 appends to this value which provides a per-user way to customize it.
7207 The deprecated switch --export-compile-commands to "gn gen" (see "gn help
7208 gen") adds to the export target list using a different format.
7217 Label of the root build target. The GN build will start by loading the
7218 build file containing this target name. This defaults to "//:" which will
7219 cause the file //BUILD.gn to be loaded. Note that build_file_extension
7222 The command-line switch --root-target will override this value (see "gn
7223 help --root-target").
7234 The command-line switch --root-pattern will override this value (see
7235 "gn help --root-pattern")
7244 The command-line switch --script-executable will override this value (see
7245 "gn help --script-executable")
7249 for a BUILD.gn file (or the build config file discussed above), the file
7262 declare_args() block, but can be overridden using --args or the
7263 args.gn file.
7269 If set to a non-empty string, this is added to the name of all build files
7281 #### **Example .gn file contents**
7288 "//tools:mind_controlling_ant", # Check this specific target.
7306 1. Look for ".gn" file (see "gn help dotfile") in the current directory and
7308 the "source root" and interpret this file to find the name of the build
7309 config file.
7311 2. Execute the build config file identified by .gn to set up the global
7313 etc. set up in this file will be visible to all files in the build.
7318 necessary to resolve dependencies. If a BUILD file isn't found in the
7322 5. When a target's dependencies are resolved, write out the `.ninja`
7323 file to disk.
7325 6. When all targets are resolved, write out the root build.ninja file.
7327 Note that the BUILD.gn file name may be modulated by .gn arguments such as
7331 #### **Executing target definitions and templates**
7335 interrogate a target from GN code for any information not derivable from its
7337 function which requires the target being interrogated to have been defined
7338 previously in the same file.
7343 ... target parameter definitions ...
7346 There is also a generic "target" function for programmatically defined types
7347 (see "gn help target"). You can define new types using templates (see "gn
7351 Before executing the code inside the target's { }, the target defaults are
7353 definitions that can be overridden by the target code as necessary. Typically
7366 Targets in non-default toolchains will only be generated when they are
7367 required (directly or transitively) to build a target in the default
7371 example, related tools or optional variants). A target that is marked as
7372 "generated" can propagate its generated state to an associated target using
7374 generated in the same cases the source target has but without a build-time
7375 dependency and even in non-default toolchains.
7387 A target's "data_deps" are guaranteed to be built whenever the target is
7389 required at runtime. Currently data deps will be complete before the target
7399 GN build files are read as sequences of tokens. While splitting the file
7439 integer = [ "-" ] digit { digit } .
7453 Hex = "0x" [0-9A-Fa-f][0-9A-Fa-f]
7473 otherwise-ambiguous cases.
7482 - -= < <= [ ]
7490 The input tokens form a syntax tree following a context-free grammar:
7492 File = StatementList .
7513 AssignOp = "=" | "+=" | "-=" .
7515 BinaryOp = "+" | "-" // highest priority
7521 All binary operators are left-associative.
7529 - Boolean: Uses the keywords "true" and "false". There is no implicit
7532 - Integers: All numbers in GN are signed 64-bit integers.
7534 - Strings: Strings are 8-bit with no enforced encoding. When a string is
7536 Windows and Mac filesystems) it is assumed to be UTF-8. See "String
7539 - Lists: Lists are arbitrary-length ordered lists of values. See "Lists"
7542 - Scopes: Scopes are like dictionaries that use variable names for keys. See
7553 A comma after the last item is optional. Lists are dereferenced using 0-based
7563 Items can be removed from lists using the '-' and '-=' operators. This will
7564 remove all occurrences of every item in the right-hand list from the
7565 left-hand list. It is an error to remove an item not in the list. This is to
7594 implicitly-created "invoker" when invoking a template (which refers to the
7606 self-contained and do not "inherit" values from their defining scope.
7616 Scope equality is defined as single-level scopes identical within the current
7624 Input and output conversions are arguments to file and process functions
7635 Return the file contents as a list, with a string for each line. The
7663 input: Return the file contents into a single string.
7725 ### <a name="file_pattern"></a>**File patterns**
7728 File patterns are VERY limited regular expressions. They must match the
7736 - "*" Matches zero or more of any character. It does not depend on the
7740 - "\b" Matches a path boundary. This will match the beginning or end of a
7767 - Explicit (no wildcard):
7771 - Wildcard target names:
7772 "//foo/bar:*" (all targets in the //foo/bar/BUILD.gn file)
7773 ":*" (all targets in the current build file)
7775 - Wildcard directory names ("*" is only supported at the end)
7778 "./*" (all targets in the current build file or sub dirs)
7786 An explicit target in an explicit toolchain.
7789 All targets in the current build file using the 32-bit Linux toolchain.
7803 This consists of a source-root-absolute path, a colon, and a name. This means
7819 context, but you can override this to specify cross-toolchain dependencies:
7823 Here GN will look for the toolchain definition called "msvc" in the file
7824 "//build/toolchain/win" to know how to compile this target.
7832 all same-file references.
7837 Stylistically, we prefer to use absolute paths for all non-file-local
7838 references unless a build file needs to be run in different contexts (like a
7852 //net -> //net:net
7853 //tools/gn -> //tools/gn:gn
7867 Similar to the write_file() function, the generated_file target type
7868 creates a file in the specified location with the specified content. The
7869 primary difference between write_file() and this target type is that the
7870 write_file function does the file write at parse time, while the
7871 generated_file target type writes at target resolution time. See
7874 When written at target resolution time, generated_file enables GN to
7877 A generated_file target can declare either 'contents' to write statically
7878 known contents to a file or 'data_keys' to aggregate metadata and write the
7879 result to a file. It can also specify 'walk_keys' (to restrict the metadata
7887 metadata may be collected and written out to a file specified by
7891 During the target resolution, generated_file targets will walk their
7896 The walk begins with the listed dependencies of the 'generated_file' target.
7898 of the 'generated_file' target's 'data_keys' list. If a match is found, the
7902 will then recurse into the dependencies of each target it encounters,
7930 The above will produce the following file data:
7971 The above will produce the following file data (note that `doom_melon.cpp` is
7979 to be collected with the target-side code.
7986 build, and so a common use is to provide post-build tooling with a set of data
7987 necessary to do aggregation tasks. For example, if each test target specifies
7989 collected into a single file listing the locations of all tests in the
7991 can then use that file to know which tests exist, and where, and run them
7994 Another use is in image creation, where a post-build image tool needs to know
8005 default rule will be used by Ninja if no specific target is specified (just
8006 typing "ninja"). If there is a target named "default" in the root build file,
8020 2. Targets in the toplevel //BUILD.gn file.
8032 of "com.apple.product-type.application" are considered as executable
8035 5. The short names of all targets if there is only one target with that
8048 To explicitly compile a target in a non-default toolchain, you must give
8049 Ninja the exact name of the output file relative to the build directory.
8066 If the build file has a conditional dependency on the corresponding target
8085 advice on fixing problems. Targets can also opt-out of checking, see
8091 Runtime dependencies of a target are exposed via the "runtime_deps" category
8093 time via write_runtime_deps(), or --runtime-deps-list-file (see "gn help
8094 --runtime-deps-list-file").
8096 To a first approximation, the runtime dependencies of a target are the set of
8107 assumes that the executable (and everything it requires) is a build-time
8117 considered as runtime dependencies. These targets can list an output file in
8118 both the "outputs" and "data" lists to force an output file as a runtime
8121 The different rules for deps and data_deps are to express build-time (deps)
8122 vs. run-time (data_deps) outputs. If GN counted all build-time copy steps as
8124 run-time dependencies as regular deps, the build's parallelism would be
8129 A --[data_deps]--> B --[deps]--> ACTION
8131 which is often correct. But the purpose of the B target might be to collect
8132 many actions into one logic unit, and the "data"-ness of A's dependency is
8135 - List the outputs of the action in its data section (if the results of
8137 - Have B list the action in data_deps (if the outputs of the actions are
8139 - Have B list the action in both deps and data deps (if the outputs might be
8142 - Split B into run-time and build-time versions with the appropriate "deps"
8152 manually compute the .a/.lib file name for the current platform and list it
8153 in the "data" list of a target (possibly on the static library target
8167 Source expansion is used for the action_foreach and copy target types to map
8168 source file names to output file names or arguments.
8179 static list of literal file names that do not depend on the sources.
8192 The name of the source file including directory (*). This will generally
8197 The file part of the source including the extension.
8201 The filename part of the source file with no directory or extension. This
8202 will generally be used for specifying a transformation from a source file
8203 to a destination file with the same name but different extension.
8207 The directory (*) containing the source file with no trailing slash.
8211 The path to the source file's directory relative to the source root, with
8212 no leading "//" or trailing slashes. If the path is system-absolute,
8219 The generated file directory (*) corresponding to the source file's path.
8220 This will be different than the target's generated file directory if the
8221 source file is in a different directory than the BUILD.gn file.
8225 The object file directory (*) corresponding to the source file's path,
8226 relative to the build directory. this us be different than the target's
8227 out directory if the source file is in a different directory than the
8228 build.gn file.
8232 The path to the source file relative to the target's directory. This will
8236 "target".
8252 the directories will be source- absolute (begin with a "//") because the
8259 Non-varying outputs:
8282 Do "gn help --the_switch_you_want_help_on" for more. Individual commands may
8283 take command-specific switches not listed here. See the help on your specific
8287 * --args: Specifies build arguments overrides.
8288 * --color: Force colored output.
8289 * --dotfile: Override the name of the ".gn" file.
8290 * --fail-on-unused-args: Treat unused build args as fatal errors.
8291 * --markdown: Write help output in the Markdown format.
8292 * --ninja-executable: Set the Ninja executable.
8293 * --nocolor: Force non-colored output.
8294 * -q: Quiet mode. Don't print output on success.
8295 * --root: Explicitly specify source root.
8296 * --root-target: Override the root target.
8297 * --runtime-deps-list-file: Save runtime dependencies for targets in file.
8298 * --script-executable: Set the executable used to execute scripts.
8299 * --threads: Specify number of worker threads.
8300 * --time: Outputs a summary of how long everything took.
8301 * --tracelog: Writes a Chrome-compatible trace log to the given file.
8302 * -v: Verbose logging.
8303 * --version: Prints the GN version number and exits.