1# GN Reference 2 3*This page is automatically generated from* `gn help --markdown all`. 4 5## Contents 6 7* [Commands](#commands) 8 * [analyze: Analyze which targets are affected by a list of files.](#cmd_analyze) 9 * [args: Display or configure arguments declared by the build.](#cmd_args) 10 * [check: Check header dependencies.](#cmd_check) 11 * [clean: Cleans the output directory.](#cmd_clean) 12 * [desc: Show lots of insightful information about a target or config.](#cmd_desc) 13 * [format: Format .gn files.](#cmd_format) 14 * [gen: Generate ninja files.](#cmd_gen) 15 * [help: Does what you think.](#cmd_help) 16 * [ls: List matching targets.](#cmd_ls) 17 * [meta: List target metadata collection results.](#cmd_meta) 18 * [outputs: Which files a source/target make.](#cmd_outputs) 19 * [path: Find paths between two targets.](#cmd_path) 20 * [refs: Find stuff referencing a target or file.](#cmd_refs) 21* [Target declarations](#targets) 22 * [action: Declare a target that runs a script a single time.](#func_action) 23 * [action_foreach: Declare a target that runs a script over a set of files.](#func_action_foreach) 24 * [bundle_data: [iOS/macOS] Declare a target without output.](#func_bundle_data) 25 * [copy: Declare a target that copies files.](#func_copy) 26 * [create_bundle: [iOS/macOS] Build an iOS or macOS bundle.](#func_create_bundle) 27 * [executable: Declare an executable target.](#func_executable) 28 * [generated_file: Declare a generated_file target.](#func_generated_file) 29 * [group: Declare a named group of targets.](#func_group) 30 * [loadable_module: Declare a loadable module target.](#func_loadable_module) 31 * [rust_library: Declare a Rust library target.](#func_rust_library) 32 * [rust_proc_macro: Declare a Rust procedural macro target.](#func_rust_proc_macro) 33 * [shared_library: Declare a shared library target.](#func_shared_library) 34 * [source_set: Declare a source set target.](#func_source_set) 35 * [static_library: Declare a static library target.](#func_static_library) 36 * [target: Declare an target with the given programmatic type.](#func_target) 37* [Buildfile functions](#functions) 38 * [assert: Assert an expression is true at generation time.](#func_assert) 39 * [config: Defines a configuration object.](#func_config) 40 * [declare_args: Declare build arguments.](#func_declare_args) 41 * [defined: Returns whether an identifier is defined.](#func_defined) 42 * [exec_script: Synchronously run a script and return the output.](#func_exec_script) 43 * [filter_exclude: Remove values that match a set of patterns.](#func_filter_exclude) 44 * [filter_include: Remove values that do not match a set of patterns.](#func_filter_include) 45 * [foreach: Iterate over a list.](#func_foreach) 46 * [forward_variables_from: Copies variables from a different scope.](#func_forward_variables_from) 47 * [get_label_info: Get an attribute from a target's label.](#func_get_label_info) 48 * [get_path_info: Extract parts of a file or directory name.](#func_get_path_info) 49 * [get_target_outputs: [file list] Get the list of outputs from a target.](#func_get_target_outputs) 50 * [getenv: Get an environment variable.](#func_getenv) 51 * [import: Import a file into the current scope.](#func_import) 52 * [not_needed: Mark variables from scope as not needed.](#func_not_needed) 53 * [pool: Defines a pool object.](#func_pool) 54 * [print: Prints to the console.](#func_print) 55 * [process_file_template: Do template expansion over a list of files.](#func_process_file_template) 56 * [read_file: Read a file into a variable.](#func_read_file) 57 * [rebase_path: Rebase a file or directory to another location.](#func_rebase_path) 58 * [set_default_toolchain: Sets the default toolchain name.](#func_set_default_toolchain) 59 * [set_defaults: Set default values for a target type.](#func_set_defaults) 60 * [set_sources_assignment_filter: Deprecated feature.](#func_set_sources_assignment_filter) 61 * [split_list: Splits a list into N different sub-lists.](#func_split_list) 62 * [string_join: Concatenates a list of strings with a separator.](#func_string_join) 63 * [string_replace: Replaces substring in the given string.](#func_string_replace) 64 * [string_split: Split string into a list of strings.](#func_string_split) 65 * [template: Define a template rule.](#func_template) 66 * [tool: Specify arguments to a toolchain tool.](#func_tool) 67 * [toolchain: Defines a toolchain.](#func_toolchain) 68 * [write_file: Write a file to disk.](#func_write_file) 69* [Built-in predefined variables](#predefined_variables) 70 * [current_cpu: [string] The processor architecture of the current toolchain.](#var_current_cpu) 71 * [current_os: [string] The operating system of the current toolchain.](#var_current_os) 72 * [current_toolchain: [string] Label of the current toolchain.](#var_current_toolchain) 73 * [default_toolchain: [string] Label of the default toolchain.](#var_default_toolchain) 74 * [gn_version: [number] The version of gn.](#var_gn_version) 75 * [host_cpu: [string] The processor architecture that GN is running on.](#var_host_cpu) 76 * [host_os: [string] The operating system that GN is running on.](#var_host_os) 77 * [invoker: [string] The invoking scope inside a template.](#var_invoker) 78 * [python_path: [string] Absolute path of Python.](#var_python_path) 79 * [root_build_dir: [string] Directory where build commands are run.](#var_root_build_dir) 80 * [root_gen_dir: [string] Directory for the toolchain's generated files.](#var_root_gen_dir) 81 * [root_out_dir: [string] Root directory for toolchain output files.](#var_root_out_dir) 82 * [target_cpu: [string] The desired cpu architecture for the build.](#var_target_cpu) 83 * [target_gen_dir: [string] Directory for a target's generated files.](#var_target_gen_dir) 84 * [target_name: [string] The name of the current target.](#var_target_name) 85 * [target_os: [string] The desired operating system for the build.](#var_target_os) 86 * [target_out_dir: [string] Directory for target output files.](#var_target_out_dir) 87* [Variables you set in targets](#target_variables) 88 * [aliased_deps: [scope] Set of crate-dependency pairs.](#var_aliased_deps) 89 * [all_dependent_configs: [label list] Configs to be forced on dependents.](#var_all_dependent_configs) 90 * [allow_circular_includes_from: [label list] Permit includes from deps.](#var_allow_circular_includes_from) 91 * [arflags: [string list] Arguments passed to static_library archiver.](#var_arflags) 92 * [args: [string list] Arguments passed to an action.](#var_args) 93 * [asmflags: [string list] Flags passed to the assembler.](#var_asmflags) 94 * [assert_no_deps: [label pattern list] Ensure no deps on these targets.](#var_assert_no_deps) 95 * [bridge_header: [string] Path to C/Objective-C compatibility header.](#var_bridge_header) 96 * [bundle_contents_dir: Expansion of {{bundle_contents_dir}} in create_bundle.](#var_bundle_contents_dir) 97 * [bundle_deps_filter: [label list] A list of labels that are filtered out.](#var_bundle_deps_filter) 98 * [bundle_executable_dir: Expansion of {{bundle_executable_dir}} in create_bundle](#var_bundle_executable_dir) 99 * [bundle_resources_dir: Expansion of {{bundle_resources_dir}} in create_bundle.](#var_bundle_resources_dir) 100 * [bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle.](#var_bundle_root_dir) 101 * [cflags: [string list] Flags passed to all C compiler variants.](#var_cflags) 102 * [cflags_c: [string list] Flags passed to the C compiler.](#var_cflags_c) 103 * [cflags_cc: [string list] Flags passed to the C++ compiler.](#var_cflags_cc) 104 * [cflags_objc: [string list] Flags passed to the Objective C compiler.](#var_cflags_objc) 105 * [cflags_objcc: [string list] Flags passed to the Objective C++ compiler.](#var_cflags_objcc) 106 * [check_includes: [boolean] Controls whether a target's files are checked.](#var_check_includes) 107 * [code_signing_args: [string list] Arguments passed to code signing script.](#var_code_signing_args) 108 * [code_signing_outputs: [file list] Output files for code signing step.](#var_code_signing_outputs) 109 * [code_signing_script: [file name] Script for code signing.](#var_code_signing_script) 110 * [code_signing_sources: [file list] Sources for code signing step.](#var_code_signing_sources) 111 * [complete_static_lib: [boolean] Links all deps into a static library.](#var_complete_static_lib) 112 * [configs: [label list] Configs applying to this target or config.](#var_configs) 113 * [contents: Contents to write to file.](#var_contents) 114 * [crate_name: [string] The name for the compiled crate.](#var_crate_name) 115 * [crate_root: [string] The root source file for a binary or library.](#var_crate_root) 116 * [crate_type: [string] The type of linkage to use on a shared_library.](#var_crate_type) 117 * [data: [file list] Runtime data file dependencies.](#var_data) 118 * [data_deps: [label list] Non-linked dependencies.](#var_data_deps) 119 * [data_keys: [string list] Keys from which to collect metadata.](#var_data_keys) 120 * [defines: [string list] C preprocessor defines.](#var_defines) 121 * [depfile: [string] File name for input dependencies for actions.](#var_depfile) 122 * [deps: [label list] Private linked dependencies.](#var_deps) 123 * [externs: [scope] Set of Rust crate-dependency pairs.](#var_externs) 124 * [framework_dirs: [directory list] Additional framework search directories.](#var_framework_dirs) 125 * [frameworks: [name list] Name of frameworks that must be linked.](#var_frameworks) 126 * [friend: [label pattern list] Allow targets to include private headers.](#var_friend) 127 * [include_dirs: [directory list] Additional include directories.](#var_include_dirs) 128 * [inputs: [file list] Additional compile-time dependencies.](#var_inputs) 129 * [ldflags: [string list] Flags passed to the linker.](#var_ldflags) 130 * [lib_dirs: [directory list] Additional library directories.](#var_lib_dirs) 131 * [libs: [string list] Additional libraries to link.](#var_libs) 132 * [metadata: [scope] Metadata of this target.](#var_metadata) 133 * [module_name: [string] The name for the compiled module.](#var_module_name) 134 * [output_conversion: Data format for generated_file targets.](#var_output_conversion) 135 * [output_dir: [directory] Directory to put output file in.](#var_output_dir) 136 * [output_extension: [string] Value to use for the output's file extension.](#var_output_extension) 137 * [output_name: [string] Name for the output file other than the default.](#var_output_name) 138 * [output_prefix_override: [boolean] Don't use prefix for output name.](#var_output_prefix_override) 139 * [outputs: [file list] Output files for actions and copy targets.](#var_outputs) 140 * [partial_info_plist: [filename] Path plist from asset catalog compiler.](#var_partial_info_plist) 141 * [pool: [string] Label of the pool used by the action.](#var_pool) 142 * [precompiled_header: [string] Header file to precompile.](#var_precompiled_header) 143 * [precompiled_header_type: [string] "gcc" or "msvc".](#var_precompiled_header_type) 144 * [precompiled_source: [file name] Source file to precompile.](#var_precompiled_source) 145 * [product_type: [string] Product type for Xcode projects.](#var_product_type) 146 * [public: [file list] Declare public header files for a target.](#var_public) 147 * [public_configs: [label list] Configs applied to dependents.](#var_public_configs) 148 * [public_deps: [label list] Declare public dependencies.](#var_public_deps) 149 * [rebase: [boolean] Rebase collected metadata as files.](#var_rebase) 150 * [response_file_contents: [string list] Contents of .rsp file for actions.](#var_response_file_contents) 151 * [script: [file name] Script file for actions.](#var_script) 152 * [sources: [file list] Source files for a target.](#var_sources) 153 * [swiftflags: [string list] Flags passed to the swift compiler.](#var_swiftflags) 154 * [testonly: [boolean] Declares a target must only be used for testing.](#var_testonly) 155 * [visibility: [label list] A list of labels that can depend on a target.](#var_visibility) 156 * [walk_keys: [string list] Key(s) for managing the metadata collection walk.](#var_walk_keys) 157 * [weak_frameworks: [name list] Name of frameworks that must be weak linked.](#var_weak_frameworks) 158 * [write_runtime_deps: Writes the target's runtime_deps to the given path.](#var_write_runtime_deps) 159 * [xcasset_compiler_flags: [string list] Flags passed to xcassets compiler](#var_xcasset_compiler_flags) 160 * [xcode_extra_attributes: [scope] Extra attributes for Xcode projects.](#var_xcode_extra_attributes) 161 * [xcode_test_application_name: [string] Name for Xcode test target.](#var_xcode_test_application_name) 162* [Other help topics](#other) 163 * all: Print all the help at once 164 * [buildargs: How build arguments work.](#buildargs) 165 * [dotfile: Info about the toplevel .gn file.](#dotfile) 166 * [execution: Build graph and execution overview.](#execution) 167 * [grammar: Language and grammar for GN build files.](#grammar) 168 * [input_conversion: Processing input from exec_script and read_file.](#io_conversion) 169 * [file_pattern: Matching more than one file.](#file_pattern) 170 * [label_pattern: Matching more than one label.](#label_pattern) 171 * [labels: About labels.](#labels) 172 * [metadata_collection: About metadata and its collection.](#metadata_collection) 173 * [ninja_rules: How Ninja build rules are named.](#ninja_rules) 174 * [nogncheck: Annotating includes for checking.](#nogncheck) 175 * [output_conversion: Specifies how to transform a value to output.](#io_conversion) 176 * [runtime_deps: How runtime dependency computation works.](#runtime_deps) 177 * [source_expansion: Map sources to outputs for scripts.](#source_expansion) 178 * [switches: Show available command-line switches.](#switch_list) 179 180## <a name="commands"></a>Commands 181 182### <a name="cmd_analyze"></a>**gn analyze <out_dir> <input_path> <output_path>** 183 184``` 185 Analyze which targets are affected by a list of files. 186 187 This command takes three arguments: 188 189 out_dir is the path to the build directory. 190 191 input_path is a path to a file containing a JSON object with three fields: 192 193 - "files": A list of the filenames to check. 194 195 - "test_targets": A list of the labels for targets that are needed to run 196 the tests we wish to run. 197 198 - "additional_compile_targets": A list of the labels for targets that we 199 wish to rebuild, but aren't necessarily needed for testing. The important 200 difference between this field and "test_targets" is that if an item in 201 the additional_compile_targets list refers to a group, then any 202 dependencies of that group will be returned if they are out of date, but 203 the group itself does not need to be. If the dependencies themselves are 204 groups, the same filtering is repeated. This filtering can be used to 205 avoid rebuilding dependencies of a group that are unaffected by the input 206 files. The list may also contain the string "all" to refer to a 207 pseudo-group that contains every root target in the build graph. 208 209 This filtering behavior is also known as "pruning" the list of compile 210 targets. 211 212 If input_path is -, input is read from stdin. 213 214 output_path is a path indicating where the results of the command are to be 215 written. The results will be a file containing a JSON object with one or more 216 of following fields: 217 218 - "compile_targets": A list of the labels derived from the input 219 compile_targets list that are affected by the input files. Due to the way 220 the filtering works for compile targets as described above, this list may 221 contain targets that do not appear in the input list. 222 223 - "test_targets": A list of the labels from the input test_targets list that 224 are affected by the input files. This list will be a proper subset of the 225 input list. 226 227 - "invalid_targets": A list of any names from the input that do not exist in 228 the build graph. If this list is non-empty, the "error" field will also be 229 set to "Invalid targets". 230 231 - "status": A string containing one of three values: 232 233 - "Found dependency" 234 - "No dependency" 235 - "Found dependency (all)" 236 237 In the first case, the lists returned in compile_targets and test_targets 238 should be passed to ninja to build. In the second case, nothing was 239 affected and no build is necessary. In the third case, GN could not 240 determine the correct answer and returned the input as the output in order 241 to be safe. 242 243 - "error": This will only be present if an error occurred, and will contain 244 a string describing the error. This includes cases where the input file is 245 not in the right format, or contains invalid targets. 246 247 If output_path is -, output is written to stdout. 248 249 The command returns 1 if it is unable to read the input file or write the 250 output file, or if there is something wrong with the build such that gen 251 would also fail, and 0 otherwise. In particular, it returns 0 even if the 252 "error" key is non-empty and a non-fatal error occurred. In other words, it 253 tries really hard to always write something to the output JSON and convey 254 errors that way rather than via return codes. 255``` 256### <a name="cmd_args"></a>**gn args**: (command-line tool) 257 258``` 259 Display or configure arguments declared by the build. 260 261 gn args <out_dir> [--list] [--short] [--args] [--overrides-only] 262 263 See also "gn help buildargs" for a more high-level overview of how 264 build arguments work. 265``` 266 267#### **Usage** 268 269``` 270 gn args <out_dir> 271 Open the arguments for the given build directory in an editor. If the 272 given build directory doesn't exist, it will be created and an empty args 273 file will be opened in the editor. You would type something like this 274 into that file: 275 enable_doom_melon=false 276 os="android" 277 278 To find your editor on Posix, GN will search the environment variables in 279 order: GN_EDITOR, VISUAL, and EDITOR. On Windows GN will open the command 280 associated with .txt files. 281 282 Note: you can edit the build args manually by editing the file "args.gn" 283 in the build directory and then running "gn gen <out_dir>". 284 285 gn args <out_dir> --list[=<exact_arg>] [--short] [--overrides-only] [--json] 286 Lists all build arguments available in the current configuration, or, if 287 an exact_arg is specified for the list flag, just that one build 288 argument. 289 290 The output will list the declaration location, current value for the 291 build, default value (if different than the current value), and comment 292 preceding the declaration. 293 294 If --short is specified, only the names and current values will be 295 printed. 296 297 If --overrides-only is specified, only the names and current values of 298 arguments that have been overridden (i.e. non-default arguments) will 299 be printed. Overrides come from the <out_dir>/args.gn file and //.gn 300 301 If --json is specified, the output will be emitted in json format. 302 JSON schema for output: 303 [ 304 { 305 "name": variable_name, 306 "current": { 307 "value": overridden_value, 308 "file": file_name, 309 "line": line_no 310 }, 311 "default": { 312 "value": default_value, 313 "file": file_name, 314 "line": line_no 315 }, 316 "comment": comment_string 317 }, 318 ... 319 ] 320``` 321 322#### **Examples** 323 324``` 325 gn args out/Debug 326 Opens an editor with the args for out/Debug. 327 328 gn args out/Debug --list --short 329 Prints all arguments with their default values for the out/Debug 330 build. 331 332 gn args out/Debug --list --short --overrides-only 333 Prints overridden arguments for the out/Debug build. 334 335 gn args out/Debug --list=target_cpu 336 Prints information about the "target_cpu" argument for the " 337 "out/Debug 338 build. 339 340 gn args --list --args="os=\"android\" enable_doom_melon=true" 341 Prints all arguments with the default values for a build with the 342 given arguments set (which may affect the values of other 343 arguments). 344``` 345### <a name="cmd_check"></a>**gn check <out_dir> [<label_pattern>] [\--force] [\--check-generated]** 346 347``` 348 GN's include header checker validates that the includes for C-like source 349 files match the build dependency graph. 350 351 "gn check" is the same thing as "gn gen" with the "--check" flag except that 352 this command does not write out any build files. It's intended to be an easy 353 way to manually trigger include file checking. 354 355 The <label_pattern> can take exact labels or patterns that match more than 356 one (although not general regular expressions). If specified, only those 357 matching targets will be checked. See "gn help label_pattern" for details. 358``` 359 360#### **Command-specific switches** 361 362``` 363 --check-generated 364 Generated files are normally not checked since they do not exist 365 until after a build. With this flag, those generated files that 366 can be found on disk are also checked. 367 368 --check-system 369 Check system style includes (using <angle brackets>) in addition to 370 "double quote" includes. 371 372 --default-toolchain 373 Normally wildcard targets are matched in all toolchains. This 374 switch makes wildcard labels with no explicit toolchain reference 375 only match targets in the default toolchain. 376 377 Non-wildcard inputs with no explicit toolchain specification will 378 always match only a target in the default toolchain if one exists. 379 380 --force 381 Ignores specifications of "check_includes = false" and checks all 382 target's files that match the target label. 383``` 384 385#### **What gets checked** 386 387``` 388 The .gn file may specify a list of targets to be checked in the list 389 check_targets (see "gn help dotfile"). Alternatively, the .gn file may 390 specify a list of targets not to be checked in no_check_targets. If a label 391 pattern is specified on the command line, neither check_targets or 392 no_check_targets is used. 393 394 Targets can opt-out from checking with "check_includes = false" (see 395 "gn help check_includes"). 396 397 For targets being checked: 398 399 - GN opens all C-like source files in the targets to be checked and scans 400 the top for includes. 401 402 - Generated files (that might not exist yet) are ignored unless 403 the --check-generated flag is provided. 404 405 - Includes with a "nogncheck" annotation are skipped (see 406 "gn help nogncheck"). 407 408 - Includes using "quotes" are always checked. 409 If system style checking is enabled, includes using <angle brackets> 410 are also checked. 411 412 - Include paths are assumed to be relative to any of the "include_dirs" for 413 the target (including the implicit current dir). 414 415 - GN does not run the preprocessor so will not understand conditional 416 includes. 417 418 - Only includes matching known files in the build are checked: includes 419 matching unknown paths are ignored. 420 421 For an include to be valid: 422 423 - The included file must be in the current target, or there must be a path 424 following only public dependencies to a target with the file in it 425 ("gn path" is a good way to diagnose problems). 426 427 - There can be multiple targets with an included file: only one needs to be 428 valid for the include to be allowed. 429 430 - If there are only "sources" in a target, all are considered to be public 431 and can be included by other targets with a valid public dependency path. 432 433 - If a target lists files as "public", only those files are able to be 434 included by other targets. Anything in the sources will be considered 435 private and will not be includable regardless of dependency paths. 436 437 - Outputs from actions are treated like public sources on that target. 438 439 - A target can include headers from a target that depends on it if the 440 other target is annotated accordingly. See "gn help 441 allow_circular_includes_from". 442``` 443 444#### **Advice on fixing problems** 445 446``` 447 If you have a third party project that is difficult to fix or doesn't care 448 about include checks it's generally best to exclude that target from checking 449 altogether via "check_includes = false". 450 451 If you have conditional includes, make sure the build conditions and the 452 preprocessor conditions match, and annotate the line with "nogncheck" (see 453 "gn help nogncheck" for an example). 454 455 If two targets are hopelessly intertwined, use the 456 "allow_circular_includes_from" annotation. Ideally each should have identical 457 dependencies so configs inherited from those dependencies are consistent (see 458 "gn help allow_circular_includes_from"). 459 460 If you have a standalone header file or files that need to be shared between 461 a few targets, you can consider making a source_set listing only those 462 headers as public sources. With only header files, the source set will be a 463 no-op from a build perspective, but will give a central place to refer to 464 those headers. That source set's files will still need to pass "gn check" in 465 isolation. 466 467 In rare cases it makes sense to list a header in more than one target if it 468 could be considered conceptually a member of both. 469``` 470 471#### **Examples** 472 473``` 474 gn check out/Debug 475 Check everything. 476 477 gn check out/Default //foo:bar 478 Check only the files in the //foo:bar target. 479 480 gn check out/Default "//foo/* 481 Check only the files in targets in the //foo directory tree. 482``` 483### <a name="cmd_clean"></a>**gn clean <out_dir>...** 484 485``` 486 Deletes the contents of the output directory except for args.gn and 487 creates a Ninja build environment sufficient to regenerate the build. 488``` 489### <a name="cmd_desc"></a>**gn desc** 490 491``` 492 gn desc <out_dir> <label or pattern> [<what to show>] [--blame] 493 [--format=json] 494 495 Displays information about a given target or config. The build parameters 496 will be taken for the build in the given <out_dir>. 497 498 The <label or pattern> can be a target label, a config label, or a label 499 pattern (see "gn help label_pattern"). A label pattern will only match 500 targets. 501``` 502 503#### **Possibilities for <what to show>** 504 505``` 506 (If unspecified an overall summary will be displayed.) 507 508 all_dependent_configs 509 allow_circular_includes_from 510 arflags [--blame] 511 args 512 cflags [--blame] 513 cflags_c [--blame] 514 cflags_cc [--blame] 515 check_includes 516 configs [--tree] (see below) 517 data_keys 518 defines [--blame] 519 depfile 520 deps [--all] [--tree] (see below) 521 framework_dirs 522 frameworks 523 include_dirs [--blame] 524 inputs 525 ldflags [--blame] 526 lib_dirs 527 libs 528 metadata 529 output_conversion 530 outputs 531 public_configs 532 public 533 rebase 534 script 535 sources 536 testonly 537 visibility 538 walk_keys 539 weak_frameworks 540 541 runtime_deps 542 Compute all runtime deps for the given target. This is a computed list 543 and does not correspond to any GN variable, unlike most other values 544 here. 545 546 The output is a list of file names relative to the build directory. See 547 "gn help runtime_deps" for how this is computed. This also works with 548 "--blame" to see the source of the dependency. 549``` 550 551#### **Shared flags** 552 553``` 554 --default-toolchain 555 Normally wildcard targets are matched in all toolchains. This 556 switch makes wildcard labels with no explicit toolchain reference 557 only match targets in the default toolchain. 558 559 Non-wildcard inputs with no explicit toolchain specification will 560 always match only a target in the default toolchain if one exists. 561 562 --format=json 563 Format the output as JSON instead of text. 564``` 565 566#### **Target flags** 567 568``` 569 --blame 570 Used with any value specified on a config, this will name the config that 571 causes that target to get the flag. This doesn't currently work for libs, 572 lib_dirs, frameworks, weak_frameworks and framework_dirs because those are 573 inherited and are more complicated to figure out the blame (patches 574 welcome). 575``` 576 577#### **Configs** 578 579``` 580 The "configs" section will list all configs that apply. For targets this will 581 include configs specified in the "configs" variable of the target, and also 582 configs pushed onto this target via public or "all dependent" configs. 583 584 Configs can have child configs. Specifying --tree will show the hierarchy. 585``` 586 587#### **Printing outputs** 588 589``` 590 The "outputs" section will list all outputs that apply, including the outputs 591 computed from the tool definition (eg for "executable", "static_library", ... 592 targets). 593``` 594 595#### **Printing deps** 596 597``` 598 Deps will include all public, private, and data deps (TODO this could be 599 clarified and enhanced) sorted in order applying. The following may be used: 600 601 --all 602 Collects all recursive dependencies and prints a sorted flat list. Also 603 usable with --tree (see below). 604 605 --as=(buildfile|label|output) 606 How to print targets. 607 608 buildfile 609 Prints the build files where the given target was declared as 610 file names. 611 label (default) 612 Prints the label of the target. 613 output 614 Prints the first output file for the target relative to the 615 root build directory. 616 617 --testonly=(true|false) 618 Restrict outputs to targets with the testonly flag set 619 accordingly. When unspecified, the target's testonly flags are 620 ignored. 621 622 --tree 623 Print a dependency tree. By default, duplicates will be elided with "..." 624 but when --all and -tree are used together, no eliding will be performed. 625 626 The "deps", "public_deps", and "data_deps" will all be included in the 627 tree. 628 629 Tree output can not be used with the filtering or output flags: --as, 630 --type, --testonly. 631 632 --type=(action|copy|executable|group|loadable_module|shared_library| 633 source_set|static_library) 634 Restrict outputs to targets matching the given type. If 635 unspecified, no filtering will be performed. 636``` 637 638#### **Note** 639 640``` 641 This command will show the full name of directories and source files, but 642 when directories and source paths are written to the build file, they will be 643 adjusted to be relative to the build directory. So the values for paths 644 displayed by this command won't match (but should mean the same thing). 645``` 646 647#### **Examples** 648 649``` 650 gn desc out/Debug //base:base 651 Summarizes the given target. 652 653 gn desc out/Foo :base_unittests deps --tree 654 Shows a dependency tree of the "base_unittests" project in 655 the current directory. 656 657 gn desc out/Debug //base defines --blame 658 Shows defines set for the //base:base target, annotated by where 659 each one was set from. 660``` 661### <a name="cmd_format"></a>**gn format [\--dump-tree] (\--stdin | <list of build_files...>)** 662 663``` 664 Formats .gn file to a standard format. 665 666 The contents of some lists ('sources', 'deps', etc.) will be sorted to a 667 canonical order. To suppress this, you can add a comment of the form "# 668 NOSORT" immediately preceding the assignment. e.g. 669 670 # NOSORT 671 sources = [ 672 "z.cc", 673 "a.cc", 674 ] 675``` 676 677#### **Arguments** 678 679``` 680 --dry-run 681 Does not change or output anything, but sets the process exit code based 682 on whether output would be different than what's on disk. This is useful 683 for presubmit/lint-type checks. 684 - Exit code 0: successful format, matches on disk. 685 - Exit code 1: general failure (parse error, etc.) 686 - Exit code 2: successful format, but differs from on disk. 687 688 --dump-tree[=( text | json )] 689 Dumps the parse tree to stdout and does not update the file or print 690 formatted output. If no format is specified, text format will be used. 691 692 --stdin 693 Read input from stdin and write to stdout rather than update a file 694 in-place. 695``` 696 697#### **Examples** 698``` 699 gn format //some/BUILD.gn //some/other/BUILD.gn //and/another/BUILD.gn 700 gn format some\\BUILD.gn 701 gn format /abspath/some/BUILD.gn 702 gn format --stdin 703``` 704### <a name="cmd_gen"></a>**gn gen [\--check] [<ide options>] <out_dir>** 705 706``` 707 Generates ninja files from the current tree and puts them in the given output 708 directory. 709 710 The output directory can be a source-repo-absolute path name such as: 711 //out/foo 712 Or it can be a directory relative to the current directory such as: 713 out/foo 714 715 "gn gen --check" is the same as running "gn check". "gn gen --check=system" is 716 the same as running "gn check --check-system". See "gn help check" for 717 documentation on that mode. 718 719 See "gn help switches" for the common command-line switches. 720``` 721 722#### **IDE options** 723 724``` 725 GN optionally generates files for IDE. Files won't be overwritten if their 726 contents don't change. Possibilities for <ide options> 727 728 --ide=<ide_name> 729 Generate files for an IDE. Currently supported values: 730 "eclipse" - Eclipse CDT settings file. 731 "vs" - Visual Studio project/solution files. 732 (default Visual Studio version: 2019) 733 "vs2013" - Visual Studio 2013 project/solution files. 734 "vs2015" - Visual Studio 2015 project/solution files. 735 "vs2017" - Visual Studio 2017 project/solution files. 736 "vs2019" - Visual Studio 2019 project/solution files. 737 "xcode" - Xcode workspace/solution files. 738 "qtcreator" - QtCreator project files. 739 "json" - JSON file containing target information 740 741 --filters=<path_prefixes> 742 Semicolon-separated list of label patterns used to limit the set of 743 generated projects (see "gn help label_pattern"). Only matching targets 744 and their dependencies will be included in the solution. Only used for 745 Visual Studio, Xcode and JSON. 746``` 747 748#### **Visual Studio Flags** 749 750``` 751 --sln=<file_name> 752 Override default sln file name ("all"). Solution file is written to the 753 root build directory. 754 755 --no-deps 756 Don't include targets dependencies to the solution. Changes the way how 757 --filters option works. Only directly matching targets are included. 758 759 --winsdk=<sdk_version> 760 Use the specified Windows 10 SDK version to generate project files. 761 As an example, "10.0.15063.0" can be specified to use Creators Update SDK 762 instead of the default one. 763 764 --ninja-extra-args=<string> 765 This string is passed without any quoting to the ninja invocation 766 command-line. Can be used to configure ninja flags, like "-j". 767``` 768 769#### **Xcode Flags** 770 771``` 772 --xcode-project=<file_name> 773 Override defaut Xcode project file name ("all"). The project file is 774 written to the root build directory. 775 776 --xcode-build-system=<value> 777 Configure the build system to use for the Xcode project. Supported 778 values are (default to "legacy"): 779 "legacy" - Legacy Build system 780 "new" - New Build System 781 782 --ninja-executable=<string> 783 Can be used to specify the ninja executable to use when building. 784 785 --ninja-extra-args=<string> 786 This string is passed without any quoting to the ninja invocation 787 command-line. Can be used to configure ninja flags, like "-j". 788 789 --ide-root-target=<target_name> 790 Name of the target corresponding to "All" target in Xcode. If unset, 791 "All" invokes ninja without any target and builds everything. 792``` 793 794#### **QtCreator Flags** 795 796``` 797 --ide-root-target=<target_name> 798 Name of the root target for which the QtCreator project will be generated 799 to contain files of it and its dependencies. If unset, the whole build 800 graph will be emitted. 801``` 802 803#### **Eclipse IDE Support** 804 805``` 806 GN DOES NOT generate Eclipse CDT projects. Instead, it generates a settings 807 file which can be imported into an Eclipse CDT project. The XML file contains 808 a list of include paths and defines. Because GN does not generate a full 809 .cproject definition, it is not possible to properly define includes/defines 810 for each file individually. Instead, one set of includes/defines is generated 811 for the entire project. This works fairly well but may still result in a few 812 indexer issues here and there. 813``` 814 815#### **Generic JSON Output** 816 817``` 818 Dumps target information to a JSON file and optionally invokes a 819 python script on the generated file. See the comments at the beginning 820 of json_project_writer.cc and desc_builder.cc for an overview of the JSON 821 file format. 822 823 --json-file-name=<json_file_name> 824 Overrides default file name (project.json) of generated JSON file. 825 826 --json-ide-script=<path_to_python_script> 827 Executes python script after the JSON file is generated or updated with 828 new content. Path can be project absolute (//), system absolute (/) or 829 relative, in which case the output directory will be base. Path to 830 generated JSON file will be first argument when invoking script. 831 832 --json-ide-script-args=<argument> 833 Optional second argument that will passed to executed script. 834``` 835 836#### **Compilation Database** 837 838``` 839 --export-rust-project 840 Produces a rust-project.json file in the root of the build directory 841 This is used for various tools in the Rust ecosystem allowing for the 842 replay of individual compilations independent of the build system. 843 This is an unstable format and likely to change without warning. 844 845 --export-compile-commands[=<target_name1,target_name2...>] 846 Produces a compile_commands.json file in the root of the build directory 847 containing an array of “command objects”, where each command object 848 specifies one way a translation unit is compiled in the project. If a list 849 of target_name is supplied, only targets that are reachable from the list 850 of target_name will be used for “command objects” generation, otherwise 851 all available targets will be used. This is used for various Clang-based 852 tooling, allowing for the replay of individual compilations independent 853 of the build system. 854``` 855### <a name="cmd_help"></a>**gn help <anything>** 856 857``` 858 Yo dawg, I heard you like help on your help so I put help on the help in the 859 help. 860 861 You can also use "all" as the parameter to get all help at once. 862``` 863 864#### **Switches** 865 866``` 867 --markdown 868 Format output in markdown syntax. 869``` 870 871#### **Example** 872 873``` 874 gn help --markdown all 875 Dump all help to stdout in markdown format. 876``` 877### <a name="cmd_ls"></a>**gn ls <out_dir> [<label_pattern>] [\--default-toolchain] [\--as=...]** 878``` 879 [--type=...] [--testonly=...] 880 881 Lists all targets matching the given pattern for the given build directory. 882 By default, only targets in the default toolchain will be matched unless a 883 toolchain is explicitly supplied. 884 885 If the label pattern is unspecified, list all targets. The label pattern is 886 not a general regular expression (see "gn help label_pattern"). If you need 887 more complex expressions, pipe the result through grep. 888``` 889 890#### **Options** 891 892``` 893 --as=(buildfile|label|output) 894 How to print targets. 895 896 buildfile 897 Prints the build files where the given target was declared as 898 file names. 899 label (default) 900 Prints the label of the target. 901 output 902 Prints the first output file for the target relative to the 903 root build directory. 904 905 --default-toolchain 906 Normally wildcard targets are matched in all toolchains. This 907 switch makes wildcard labels with no explicit toolchain reference 908 only match targets in the default toolchain. 909 910 Non-wildcard inputs with no explicit toolchain specification will 911 always match only a target in the default toolchain if one exists. 912 913 --testonly=(true|false) 914 Restrict outputs to targets with the testonly flag set 915 accordingly. When unspecified, the target's testonly flags are 916 ignored. 917 918 --type=(action|copy|executable|group|loadable_module|shared_library| 919 source_set|static_library) 920 Restrict outputs to targets matching the given type. If 921 unspecified, no filtering will be performed. 922``` 923 924#### **Examples** 925 926``` 927 gn ls out/Debug 928 Lists all targets in the default toolchain. 929 930 gn ls out/Debug "//base/*" 931 Lists all targets in the directory base and all subdirectories. 932 933 gn ls out/Debug "//base:*" 934 Lists all targets defined in //base/BUILD.gn. 935 936 gn ls out/Debug //base --as=output 937 Lists the build output file for //base:base 938 939 gn ls out/Debug --type=executable 940 Lists all executables produced by the build. 941 942 gn ls out/Debug "//base/*" --as=output | xargs ninja -C out/Debug 943 Builds all targets in //base and all subdirectories. 944``` 945### <a name="cmd_meta"></a>**gn meta** 946 947``` 948 gn meta <out_dir> <target>* --data=<key>[,<key>*]* [--walk=<key>[,<key>*]*] 949 [--rebase=<dest dir>] 950 951 Lists collected metaresults of all given targets for the given data key(s), 952 collecting metadata dependencies as specified by the given walk key(s). 953 954 See `gn help generated_file` for more information on the walk. 955``` 956 957#### **Arguments** 958 959``` 960 <target(s)> 961 A list of target labels from which to initiate the walk. 962 963 --data 964 A list of keys from which to extract data. In each target walked, its metadata 965 scope is checked for the presence of these keys. If present, the contents of 966 those variable in the scope are appended to the results list. 967 968 --walk (optional) 969 A list of keys from which to control the walk. In each target walked, its 970 metadata scope is checked for the presence of any of these keys. If present, 971 the contents of those variables is checked to ensure that it is a label of 972 a valid dependency of the target and then added to the set of targets to walk. 973 If the empty string ("") is present in any of these keys, all deps and data_deps 974 are added to the walk set. 975 976 --rebase (optional) 977 A destination directory onto which to rebase any paths found. If set, all 978 collected metadata will be rebased onto this path. This option will throw errors 979 if collected metadata is not a list of strings. 980``` 981 982#### **Examples** 983 984``` 985 gn meta out/Debug "//base/foo" --data=files 986 Lists collected metaresults for the `files` key in the //base/foo:foo 987 target and all of its dependency tree. 988 989 gn meta out/Debug "//base/foo" --data=files --data=other 990 Lists collected metaresults for the `files` and `other` keys in the 991 //base/foo:foo target and all of its dependency tree. 992 993 gn meta out/Debug "//base/foo" --data=files --walk=stop 994 Lists collected metaresults for the `files` key in the //base/foo:foo 995 target and all of the dependencies listed in the `stop` key (and so on). 996 997 gn meta out/Debug "//base/foo" --data=files --rebase="/" 998 Lists collected metaresults for the `files` key in the //base/foo:foo 999 target and all of its dependency tree, rebasing the strings in the `files` 1000 key onto the source directory of the target's declaration relative to "/". 1001``` 1002### <a name="cmd_outputs"></a>**gn outputs <out_dir> <list of target or file names...>** 1003 1004``` 1005 Lists the output files corresponding to the given target(s) or file name(s). 1006 There can be multiple outputs because there can be more than one output 1007 generated by a build step, and there can be more than one toolchain matched. 1008 You can also list multiple inputs which will generate a union of all the 1009 outputs from those inputs. 1010 1011 - The input target/file names are relative to the current directory. 1012 1013 - The output file names are relative to the root build directory. 1014 1015 This command is useful for finding a ninja command that will build only a 1016 portion of the build. 1017``` 1018 1019#### **Target outputs** 1020 1021``` 1022 If the parameter is a target name that includes a toolchain, it will match 1023 only that target in that toolchain. If no toolchain is specified, it will 1024 match all targets with that name in any toolchain. 1025 1026 The result will be the outputs specified by that target which could be a 1027 library, executable, output of an action, a stamp file, etc. 1028``` 1029 1030#### **File outputs** 1031 1032``` 1033 If the parameter is a file name it will compute the output for that compile 1034 step for all targets in all toolchains that contain that file as a source 1035 file. 1036 1037 If the source is not compiled (e.g. a header or text file), the command will 1038 produce no output. 1039 1040 If the source is listed as an "input" to a binary target or action will 1041 resolve to that target's outputs. 1042``` 1043 1044#### **Example** 1045 1046``` 1047 gn outputs out/debug some/directory:some_target 1048 Find the outputs of a given target. 1049 1050 gn outputs out/debug src/project/my_file.cc | xargs ninja -C out/debug 1051 Compiles just the given source file in all toolchains it's referenced in. 1052 1053 git diff --name-only | xargs gn outputs out/x64 | xargs ninja -C out/x64 1054 Compiles all files changed in git. 1055``` 1056### <a name="cmd_path"></a>**gn path <out_dir> <target_one> <target_two>** 1057 1058``` 1059 Finds paths of dependencies between two targets. Each unique path will be 1060 printed in one group, and groups will be separate by newlines. The two 1061 targets can appear in either order (paths will be found going in either 1062 direction). 1063 1064 By default, a single path will be printed. If there is a path with only 1065 public dependencies, the shortest public path will be printed. Otherwise, the 1066 shortest path using either public or private dependencies will be printed. If 1067 --with-data is specified, data deps will also be considered. If there are 1068 multiple shortest paths, an arbitrary one will be selected. 1069``` 1070 1071#### **Interesting paths** 1072 1073``` 1074 In a large project, there can be 100's of millions of unique paths between a 1075 very high level and a common low-level target. To make the output more useful 1076 (and terminate in a reasonable time), GN will not revisit sub-paths 1077 previously known to lead to the target. 1078``` 1079 1080#### **Options** 1081 1082``` 1083 --all 1084 Prints all "interesting" paths found rather than just the first one. 1085 Public paths will be printed first in order of increasing length, followed 1086 by non-public paths in order of increasing length. 1087 1088 --public 1089 Considers only public paths. Can't be used with --with-data. 1090 1091 --with-data 1092 Additionally follows data deps. Without this flag, only public and private 1093 linked deps will be followed. Can't be used with --public. 1094``` 1095 1096#### **Example** 1097 1098``` 1099 gn path out/Default //base //gn 1100``` 1101### <a name="cmd_refs"></a>**gn refs** 1102 1103``` 1104 gn refs <out_dir> (<label_pattern>|<label>|<file>|@<response_file>)* 1105 [--all] [--default-toolchain] [--as=...] [--testonly=...] [--type=...] 1106 1107 Finds reverse dependencies (which targets reference something). The input is 1108 a list containing: 1109 1110 - Target label: The result will be which targets depend on it. 1111 1112 - Config label: The result will be which targets list the given config in 1113 its "configs" or "public_configs" list. 1114 1115 - Label pattern: The result will be which targets depend on any target 1116 matching the given pattern. Patterns will not match configs. These are not 1117 general regular expressions, see "gn help label_pattern" for details. 1118 1119 - File name: The result will be which targets list the given file in its 1120 "inputs", "sources", "public", "data", or "outputs". Any input that does 1121 not contain wildcards and does not match a target or a config will be 1122 treated as a file. 1123 1124 - Response file: If the input starts with an "@", it will be interpreted as 1125 a path to a file containing a list of labels or file names, one per line. 1126 This allows us to handle long lists of inputs without worrying about 1127 command line limits. 1128``` 1129 1130#### **Options** 1131 1132``` 1133 --all 1134 When used without --tree, will recurse and display all unique 1135 dependencies of the given targets. For example, if the input is a target, 1136 this will output all targets that depend directly or indirectly on the 1137 input. If the input is a file, this will output all targets that depend 1138 directly or indirectly on that file. 1139 1140 When used with --tree, turns off eliding to show a complete tree. 1141 1142 --as=(buildfile|label|output) 1143 How to print targets. 1144 1145 buildfile 1146 Prints the build files where the given target was declared as 1147 file names. 1148 label (default) 1149 Prints the label of the target. 1150 output 1151 Prints the first output file for the target relative to the 1152 root build directory. 1153 1154 --default-toolchain 1155 Normally wildcard targets are matched in all toolchains. This 1156 switch makes wildcard labels with no explicit toolchain reference 1157 only match targets in the default toolchain. 1158 1159 Non-wildcard inputs with no explicit toolchain specification will 1160 always match only a target in the default toolchain if one exists. 1161 1162 -q 1163 Quiet. If nothing matches, don't print any output. Without this option, if 1164 there are no matches there will be an informational message printed which 1165 might interfere with scripts processing the output. 1166 1167 --testonly=(true|false) 1168 Restrict outputs to targets with the testonly flag set 1169 accordingly. When unspecified, the target's testonly flags are 1170 ignored. 1171 1172 --tree 1173 Outputs a reverse dependency tree from the given target. Duplicates will 1174 be elided. Combine with --all to see a full dependency tree. 1175 1176 Tree output can not be used with the filtering or output flags: --as, 1177 --type, --testonly. 1178 1179 --type=(action|copy|executable|group|loadable_module|shared_library| 1180 source_set|static_library) 1181 Restrict outputs to targets matching the given type. If 1182 unspecified, no filtering will be performed. 1183``` 1184 1185#### **Examples (target input)** 1186 1187``` 1188 gn refs out/Debug //gn:gn 1189 Find all targets depending on the given exact target name. 1190 1191 gn refs out/Debug //base:i18n --as=buildfiles | xargs gvim 1192 Edit all .gn files containing references to //base:i18n 1193 1194 gn refs out/Debug //base --all 1195 List all targets depending directly or indirectly on //base:base. 1196 1197 gn refs out/Debug "//base/*" 1198 List all targets depending directly on any target in //base or 1199 its subdirectories. 1200 1201 gn refs out/Debug "//base:*" 1202 List all targets depending directly on any target in 1203 //base/BUILD.gn. 1204 1205 gn refs out/Debug //base --tree 1206 Print a reverse dependency tree of //base:base 1207``` 1208 1209#### **Examples (file input)** 1210 1211``` 1212 gn refs out/Debug //base/macros.h 1213 Print target(s) listing //base/macros.h as a source. 1214 1215 gn refs out/Debug //base/macros.h --tree 1216 Display a reverse dependency tree to get to the given file. This 1217 will show how dependencies will reference that file. 1218 1219 gn refs out/Debug //base/macros.h //base/at_exit.h --all 1220 Display all unique targets with some dependency path to a target 1221 containing either of the given files as a source. 1222 1223 gn refs out/Debug //base/macros.h --testonly=true --type=executable 1224 --all --as=output 1225 Display the executable file names of all test executables 1226 potentially affected by a change to the given file. 1227``` 1228## <a name="targets"></a>Target declarations 1229 1230### <a name="func_action"></a>**action**: Declare a target that runs a script a single time. 1231 1232``` 1233 This target type allows you to run a script a single time to produce one or 1234 more output files. If you want to run a script once for each of a set of 1235 input files, see "gn help action_foreach". 1236``` 1237 1238#### **Inputs** 1239 1240``` 1241 In an action the "sources" and "inputs" are treated the same: they're both 1242 input dependencies on script execution with no special handling. If you want 1243 to pass the sources to your script, you must do so explicitly by including 1244 them in the "args". Note also that this means there is no special handling of 1245 paths since GN doesn't know which of the args are paths and not. You will 1246 want to use rebase_path() to convert paths to be relative to the 1247 root_build_dir. 1248 1249 You can dynamically write input dependencies (for incremental rebuilds if an 1250 input file changes) by writing a depfile when the script is run (see "gn help 1251 depfile"). This is more flexible than "inputs". 1252 1253 If the command line length is very long, you can use response files to pass 1254 args to your script. See "gn help response_file_contents". 1255 1256 It is recommended you put inputs to your script in the "sources" variable, 1257 and stuff like other Python files required to run your script in the "inputs" 1258 variable. 1259 1260 The "deps" and "public_deps" for an action will always be 1261 completed before any part of the action is run so it can depend on 1262 the output of previous steps. The "data_deps" will be built if the 1263 action is built, but may not have completed before all steps of the 1264 action are started. This can give additional parallelism in the build 1265 for runtime-only dependencies. 1266``` 1267 1268#### **Outputs** 1269 1270``` 1271 You should specify files created by your script by specifying them in the 1272 "outputs". 1273 1274 The script will be executed with the given arguments with the current 1275 directory being that of the root build directory. If you pass files 1276 to your script, see "gn help rebase_path" for how to convert 1277 file names to be relative to the build directory (file names in the 1278 sources, outputs, and inputs will be all treated as relative to the 1279 current build file and converted as needed automatically). 1280 1281 GN sets Ninja's flag 'restat = 1` for all action commands. This means 1282 that Ninja will check the timestamp of the output after the action 1283 completes. If output timestamp is unchanged, the step will be treated 1284 as if it never needed to be rebuilt, potentially eliminating some 1285 downstream steps for incremental builds. Scripts can improve build 1286 performance by taking care not to change the timstamp of the output 1287 file(s) if the contents have not changed. 1288``` 1289 1290#### **File name handling** 1291 1292``` 1293 All output files must be inside the output directory of the build. 1294 You would generally use |$target_out_dir| or |$target_gen_dir| to 1295 reference the output or generated intermediate file directories, 1296 respectively. 1297``` 1298 1299#### **Variables** 1300 1301``` 1302 args, data, data_deps, depfile, deps, inputs, metadata, outputs*, pool, 1303 response_file_contents, script*, sources 1304 * = required 1305``` 1306 1307#### **Example** 1308 1309``` 1310 action("run_this_guy_once") { 1311 script = "doprocessing.py" 1312 sources = [ "my_configuration.txt" ] 1313 outputs = [ "$target_gen_dir/insightful_output.txt" ] 1314 1315 # Our script imports this Python file so we want to rebuild if it changes. 1316 inputs = [ "helper_library.py" ] 1317 1318 # Note that we have to manually pass the sources to our script if the 1319 # script needs them as inputs. 1320 args = [ "--out", rebase_path(target_gen_dir, root_build_dir) ] + 1321 rebase_path(sources, root_build_dir) 1322 } 1323``` 1324### <a name="func_action_foreach"></a>**action_foreach**: Declare a target that runs a script over a set of files. 1325 1326``` 1327 This target type allows you to run a script once-per-file over a set of 1328 sources. If you want to run a script once that takes many files as input, see 1329 "gn help action". 1330``` 1331 1332#### **Inputs** 1333 1334``` 1335 The script will be run once per file in the "sources" variable. The "outputs" 1336 variable should specify one or more files with a source expansion pattern in 1337 it (see "gn help source_expansion"). The output file(s) for each script 1338 invocation should be unique. Normally you use "{{source_name_part}}" in each 1339 output file. 1340 1341 If your script takes additional data as input, such as a shared configuration 1342 file or a Python module it uses, those files should be listed in the "inputs" 1343 variable. These files are treated as dependencies of each script invocation. 1344 1345 If the command line length is very long, you can use response files to pass 1346 args to your script. See "gn help response_file_contents". 1347 1348 You can dynamically write input dependencies (for incremental rebuilds if an 1349 input file changes) by writing a depfile when the script is run (see "gn help 1350 depfile"). This is more flexible than "inputs". 1351 1352 The "deps" and "public_deps" for an action will always be 1353 completed before any part of the action is run so it can depend on 1354 the output of previous steps. The "data_deps" will be built if the 1355 action is built, but may not have completed before all steps of the 1356 action are started. This can give additional parallelism in the build 1357 for runtime-only dependencies. 1358``` 1359 1360#### **Outputs** 1361 1362``` 1363 The script will be executed with the given arguments with the current 1364 directory being that of the root build directory. If you pass files 1365 to your script, see "gn help rebase_path" for how to convert 1366 file names to be relative to the build directory (file names in the 1367 sources, outputs, and inputs will be all treated as relative to the 1368 current build file and converted as needed automatically). 1369 1370 GN sets Ninja's flag 'restat = 1` for all action commands. This means 1371 that Ninja will check the timestamp of the output after the action 1372 completes. If output timestamp is unchanged, the step will be treated 1373 as if it never needed to be rebuilt, potentially eliminating some 1374 downstream steps for incremental builds. Scripts can improve build 1375 performance by taking care not to change the timstamp of the output 1376 file(s) if the contents have not changed. 1377``` 1378 1379#### **File name handling** 1380 1381``` 1382 All output files must be inside the output directory of the build. 1383 You would generally use |$target_out_dir| or |$target_gen_dir| to 1384 reference the output or generated intermediate file directories, 1385 respectively. 1386``` 1387 1388#### **Variables** 1389 1390``` 1391 args, data, data_deps, depfile, deps, inputs, metadata, outputs*, pool, 1392 response_file_contents, script*, sources* 1393 * = required 1394``` 1395 1396#### **Example** 1397 1398``` 1399 # Runs the script over each IDL file. The IDL script will generate both a .cc 1400 # and a .h file for each input. 1401 action_foreach("my_idl") { 1402 script = "idl_processor.py" 1403 sources = [ "foo.idl", "bar.idl" ] 1404 1405 # Our script reads this file each time, so we need to list it as a 1406 # dependency so we can rebuild if it changes. 1407 inputs = [ "my_configuration.txt" ] 1408 1409 # Transformation from source file name to output file names. 1410 outputs = [ "$target_gen_dir/{{source_name_part}}.h", 1411 "$target_gen_dir/{{source_name_part}}.cc" ] 1412 1413 # Note that since "args" is opaque to GN, if you specify paths here, you 1414 # will need to convert it to be relative to the build directory using 1415 # rebase_path(). 1416 args = [ 1417 "{{source}}", 1418 "-o", 1419 rebase_path(relative_target_gen_dir, root_build_dir) + 1420 "/{{source_name_part}}.h" ] 1421 } 1422``` 1423### <a name="func_bundle_data"></a>**bundle_data**: [iOS/macOS] Declare a target without output. 1424 1425``` 1426 This target type allows to declare data that is required at runtime. It is 1427 used to inform "create_bundle" targets of the files to copy into generated 1428 bundle, see "gn help create_bundle" for help. 1429 1430 The target must define a list of files as "sources" and a single "outputs". 1431 If there are multiple files, source expansions must be used to express the 1432 output. The output must reference a file inside of {{bundle_root_dir}}. 1433 1434 This target can be used on all platforms though it is designed only to 1435 generate iOS/macOS bundle. In cross-platform projects, it is advised to put it 1436 behind iOS/macOS conditionals. 1437 1438 See "gn help create_bundle" for more information. 1439``` 1440 1441#### **Variables** 1442 1443``` 1444 sources*, outputs*, deps, data_deps, metadata, public_deps, visibility 1445 * = required 1446``` 1447 1448#### **Examples** 1449 1450``` 1451 bundle_data("icudata") { 1452 sources = [ "sources/data/in/icudtl.dat" ] 1453 outputs = [ "{{bundle_resources_dir}}/{{source_file_part}}" ] 1454 } 1455 1456 bundle_data("base_unittests_bundle_data]") { 1457 sources = [ "test/data" ] 1458 outputs = [ 1459 "{{bundle_resources_dir}}/{{source_root_relative_dir}}/" + 1460 "{{source_file_part}}" 1461 ] 1462 } 1463 1464 bundle_data("material_typography_bundle_data") { 1465 sources = [ 1466 "src/MaterialTypography.bundle/Roboto-Bold.ttf", 1467 "src/MaterialTypography.bundle/Roboto-Italic.ttf", 1468 "src/MaterialTypography.bundle/Roboto-Regular.ttf", 1469 "src/MaterialTypography.bundle/Roboto-Thin.ttf", 1470 ] 1471 outputs = [ 1472 "{{bundle_resources_dir}}/MaterialTypography.bundle/" 1473 "{{source_file_part}}" 1474 ] 1475 } 1476``` 1477### <a name="func_copy"></a>**copy**: Declare a target that copies files. 1478 1479#### **File name handling** 1480 1481``` 1482 All output files must be inside the output directory of the build. You would 1483 generally use |$target_out_dir| or |$target_gen_dir| to reference the output 1484 or generated intermediate file directories, respectively. 1485 1486 Both "sources" and "outputs" must be specified. Sources can include as many 1487 files as you want, but there can only be one item in the outputs list (plural 1488 is used for the name for consistency with other target types). 1489 1490 If there is more than one source file, your output name should specify a 1491 mapping from each source file to an output file name using source expansion 1492 (see "gn help source_expansion"). The placeholders will look like 1493 "{{source_name_part}}", for example. 1494``` 1495 1496#### **Examples** 1497 1498``` 1499 # Write a rule that copies a checked-in DLL to the output directory. 1500 copy("mydll") { 1501 sources = [ "mydll.dll" ] 1502 outputs = [ "$target_out_dir/mydll.dll" ] 1503 } 1504 1505 # Write a rule to copy several files to the target generated files directory. 1506 copy("myfiles") { 1507 sources = [ "data1.dat", "data2.dat", "data3.dat" ] 1508 1509 # Use source expansion to generate output files with the corresponding file 1510 # names in the gen dir. This will just copy each file. 1511 outputs = [ "$target_gen_dir/{{source_file_part}}" ] 1512 } 1513``` 1514### <a name="func_create_bundle"></a>**create_bundle**: [ios/macOS] Build an iOS or macOS bundle. 1515 1516``` 1517 This target generates an iOS or macOS bundle (which is a directory with a 1518 well-know structure). This target does not define any sources, instead they 1519 are computed from all "bundle_data" target this one depends on transitively 1520 (the recursion stops at "create_bundle" targets). 1521 1522 The "bundle_*_dir" are be used for the expansion of {{bundle_*_dir}} rules in 1523 "bundle_data" outputs. The properties are optional but must be defined if any 1524 of the "bundle_data" target use them. 1525 1526 This target can be used on all platforms though it is designed only to 1527 generate iOS or macOS bundle. In cross-platform projects, it is advised to put 1528 it behind iOS/macOS conditionals. 1529 1530 If a create_bundle is specified as a data_deps for another target, the bundle 1531 is considered a leaf, and its public and private dependencies will not 1532 contribute to any data or data_deps. Required runtime dependencies should be 1533 placed in the bundle. A create_bundle can declare its own explicit data and 1534 data_deps, however. 1535``` 1536 1537#### **Code signing** 1538 1539``` 1540 Some bundle needs to be code signed as part of the build (on iOS all 1541 application needs to be code signed to run on a device). The code signature 1542 can be configured via the code_signing_script variable. 1543 1544 If set, code_signing_script is the path of a script that invoked after all 1545 files have been moved into the bundle. The script must not change any file in 1546 the bundle, but may add new files. 1547 1548 If code_signing_script is defined, then code_signing_outputs must also be 1549 defined and non-empty to inform when the script needs to be re-run. The 1550 code_signing_args will be passed as is to the script (so path have to be 1551 rebased) and additional inputs may be listed with the variable 1552 code_signing_sources. 1553``` 1554 1555#### **Variables** 1556 1557``` 1558 bundle_root_dir, bundle_contents_dir, bundle_resources_dir, 1559 bundle_executable_dir, bundle_deps_filter, deps, data_deps, public_deps, 1560 visibility, product_type, code_signing_args, code_signing_script, 1561 code_signing_sources, code_signing_outputs, xcode_extra_attributes, 1562 xcode_test_application_name, partial_info_plist, metadata 1563``` 1564 1565#### **Example** 1566 1567``` 1568 # Defines a template to create an application. On most platform, this is just 1569 # an alias for an "executable" target, but on iOS/macOS, it builds an 1570 # application bundle. 1571 template("app") { 1572 if (!is_ios && !is_mac) { 1573 executable(target_name) { 1574 forward_variables_from(invoker, "*") 1575 } 1576 } else { 1577 app_name = target_name 1578 gen_path = target_gen_dir 1579 1580 action("${app_name}_generate_info_plist") { 1581 script = [ "//build/ios/ios_gen_plist.py" ] 1582 sources = [ "templates/Info.plist" ] 1583 outputs = [ "$gen_path/Info.plist" ] 1584 args = rebase_path(sources, root_build_dir) + 1585 rebase_path(outputs, root_build_dir) 1586 } 1587 1588 bundle_data("${app_name}_bundle_info_plist") { 1589 public_deps = [ ":${app_name}_generate_info_plist" ] 1590 sources = [ "$gen_path/Info.plist" ] 1591 outputs = [ "{{bundle_contents_dir}}/Info.plist" ] 1592 } 1593 1594 executable("${app_name}_generate_executable") { 1595 forward_variables_from(invoker, "*", [ 1596 "output_name", 1597 "visibility", 1598 ]) 1599 output_name = 1600 rebase_path("$gen_path/$app_name", root_build_dir) 1601 } 1602 1603 code_signing = 1604 defined(invoker.code_signing) && invoker.code_signing 1605 1606 if (!is_ios || !code_signing) { 1607 bundle_data("${app_name}_bundle_executable") { 1608 public_deps = [ ":${app_name}_generate_executable" ] 1609 sources = [ "$gen_path/$app_name" ] 1610 outputs = [ "{{bundle_executable_dir}}/$app_name" ] 1611 } 1612 } 1613 1614 create_bundle("$app_name.app") { 1615 product_type = "com.apple.product-type.application" 1616 1617 if (is_ios) { 1618 bundle_root_dir = "$root_build_dir/$target_name" 1619 bundle_contents_dir = bundle_root_dir 1620 bundle_resources_dir = bundle_contents_dir 1621 bundle_executable_dir = bundle_contents_dir 1622 1623 xcode_extra_attributes = { 1624 ONLY_ACTIVE_ARCH = "YES" 1625 DEBUG_INFORMATION_FORMAT = "dwarf" 1626 } 1627 } else { 1628 bundle_root_dir = "$root_build_dir/$target_name" 1629 bundle_contents_dir = "$bundle_root_dir/Contents" 1630 bundle_resources_dir = "$bundle_contents_dir/Resources" 1631 bundle_executable_dir = "$bundle_contents_dir/MacOS" 1632 } 1633 deps = [ ":${app_name}_bundle_info_plist" ] 1634 if (is_ios && code_signing) { 1635 deps += [ ":${app_name}_generate_executable" ] 1636 code_signing_script = "//build/config/ios/codesign.py" 1637 code_signing_sources = [ 1638 invoker.entitlements_path, 1639 "$target_gen_dir/$app_name", 1640 ] 1641 code_signing_outputs = [ 1642 "$bundle_root_dir/$app_name", 1643 "$bundle_root_dir/_CodeSignature/CodeResources", 1644 "$bundle_root_dir/embedded.mobileprovision", 1645 "$target_gen_dir/$app_name.xcent", 1646 ] 1647 code_signing_args = [ 1648 "-i=" + ios_code_signing_identity, 1649 "-b=" + rebase_path( 1650 "$target_gen_dir/$app_name", root_build_dir), 1651 "-e=" + rebase_path( 1652 invoker.entitlements_path, root_build_dir), 1653 "-e=" + rebase_path( 1654 "$target_gen_dir/$app_name.xcent", root_build_dir), 1655 rebase_path(bundle_root_dir, root_build_dir), 1656 ] 1657 } else { 1658 deps += [ ":${app_name}_bundle_executable" ] 1659 } 1660 } 1661 } 1662 } 1663``` 1664### <a name="func_executable"></a>**executable**: Declare an executable target. 1665 1666#### **Language and compilation** 1667 1668``` 1669 The tools and commands used to create this target type will be 1670 determined by the source files in its sources. Targets containing 1671 multiple compiler-incompatible languages are not allowed (e.g. a 1672 target containing both C and C++ sources is acceptable, but a 1673 target containing C and Rust sources is not). 1674``` 1675 1676#### **Variables** 1677 1678``` 1679 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, 1680 asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, 1681 libs, precompiled_header, precompiled_source, rustflags, 1682 rustenv, swiftflags 1683 Deps: data_deps, deps, public_deps 1684 Dependent configs: all_dependent_configs, public_configs 1685 General: check_includes, configs, data, friend, inputs, metadata, 1686 output_name, output_extension, public, sources, testonly, 1687 visibility 1688 Rust variables: aliased_deps, crate_root, crate_name 1689``` 1690### <a name="func_generated_file"></a>**generated_file**: Declare a generated_file target. 1691 1692``` 1693 Writes data value(s) to disk on resolution. This target type mirrors some 1694 functionality of the write_file() function, but also provides the ability to 1695 collect metadata from its dependencies on resolution rather than writing out 1696 at parse time. 1697 1698 The `outputs` variable is required to be a list with a single element, 1699 specifying the intended location of the output file. 1700 1701 The `output_conversion` variable specified the format to write the 1702 value. See `gn help output_conversion`. 1703 1704 One of `contents` or `data_keys` must be specified; use of `data` will write 1705 the contents of that value to file, while use of `data_keys` will trigger a 1706 metadata collection walk based on the dependencies of the target and the 1707 optional values of the `rebase` and `walk_keys` variables. See 1708 `gn help metadata`. 1709 1710 Collected metadata, if specified, will be returned in postorder of 1711 dependencies. See the example for details. 1712``` 1713 1714#### **Example (metadata collection)** 1715 1716``` 1717 Given the following targets defined in //base/BUILD.gn, where A depends on B 1718 and B depends on C and D: 1719 1720 group("a") { 1721 metadata = { 1722 doom_melon = [ "enable" ] 1723 my_files = [ "foo.cpp" ] 1724 1725 # Note: this is functionally equivalent to not defining `my_barrier` 1726 # at all in this target's metadata. 1727 my_barrier = [ "" ] 1728 } 1729 1730 deps = [ ":b" ] 1731 } 1732 1733 group("b") { 1734 metadata = { 1735 my_files = [ "bar.cpp" ] 1736 my_barrier = [ ":c" ] 1737 } 1738 1739 deps = [ ":c", ":d" ] 1740 } 1741 1742 group("c") { 1743 metadata = { 1744 doom_melon = [ "disable" ] 1745 my_files = [ "baz.cpp" ] 1746 } 1747 } 1748 1749 group("d") { 1750 metadata = { 1751 my_files = [ "missing.cpp" ] 1752 } 1753 } 1754 1755 If the following generated_file target is defined: 1756 1757 generated_file("my_files_metadata") { 1758 outputs = [ "$root_build_dir/my_files.json" ] 1759 data_keys = [ "my_files" ] 1760 1761 deps = [ "//base:a" ] 1762 } 1763 1764 The following will be written to "$root_build_dir/my_files.json" (less the 1765 comments): 1766 [ 1767 "baz.cpp", // from //base:c via //base:b 1768 "missing.cpp" // from //base:d via //base:b 1769 "bar.cpp", // from //base:b via //base:a 1770 "foo.cpp", // from //base:a 1771 ] 1772 1773 Alternatively, as an example of using walk_keys, if the following 1774 generated_file target is defined: 1775 1776 generated_file("my_files_metadata") { 1777 outputs = [ "$root_build_dir/my_files.json" ] 1778 data_keys = [ "my_files" ] 1779 walk_keys = [ "my_barrier" ] 1780 1781 deps = [ "//base:a" ] 1782 } 1783 1784 The following will be written to "$root_build_dir/my_files.json" (again less 1785 the comments): 1786 [ 1787 "baz.cpp", // from //base:c via //base:b 1788 "bar.cpp", // from //base:b via //base:a 1789 "foo.cpp", // from //base:a 1790 ] 1791 1792 If `rebase` is used in the following generated_file target: 1793 1794 generated_file("my_files_metadata") { 1795 outputs = [ "$root_build_dir/my_files.json" ] 1796 data_keys = [ "my_files" ] 1797 walk_keys = [ "my_barrier" ] 1798 rebase = root_build_dir 1799 1800 deps = [ "//base:a" ] 1801 } 1802 1803 The following will be written to "$root_build_dir/my_files.json" (again less 1804 the comments) (assuming root_build_dir = "//out"): 1805 [ 1806 "../base/baz.cpp", // from //base:c via //base:b 1807 "../base/bar.cpp", // from //base:b via //base:a 1808 "../base/foo.cpp", // from //base:a 1809 ] 1810``` 1811 1812#### **Variables** 1813 1814``` 1815 contents 1816 data_keys 1817 rebase 1818 walk_keys 1819 output_conversion 1820 Deps: data_deps, deps, public_deps 1821 Dependent configs: all_dependent_configs, public_configs 1822``` 1823### <a name="func_group"></a>**group**: Declare a named group of targets. 1824 1825``` 1826 This target type allows you to create meta-targets that just collect a set of 1827 dependencies into one named target. Groups can additionally specify configs 1828 that apply to their dependents. 1829``` 1830 1831#### **Variables** 1832 1833``` 1834 Deps: data_deps, deps, public_deps 1835 Dependent configs: all_dependent_configs, public_configs 1836``` 1837 1838#### **Example** 1839 1840``` 1841 group("all") { 1842 deps = [ 1843 "//project:runner", 1844 "//project:unit_tests", 1845 ] 1846 } 1847``` 1848### <a name="func_loadable_module"></a>**loadable_module**: Declare a loadable module target. 1849 1850``` 1851 This target type allows you to create an object file that is (and can only 1852 be) loaded and unloaded at runtime. 1853 1854 A loadable module will be specified on the linker line for targets listing 1855 the loadable module in its "deps". If you don't want this (if you don't need 1856 to dynamically load the library at runtime), then you should use a 1857 "shared_library" target type instead. 1858``` 1859 1860#### **Language and compilation** 1861 1862``` 1863 The tools and commands used to create this target type will be 1864 determined by the source files in its sources. Targets containing 1865 multiple compiler-incompatible languages are not allowed (e.g. a 1866 target containing both C and C++ sources is acceptable, but a 1867 target containing C and Rust sources is not). 1868``` 1869 1870#### **Variables** 1871 1872``` 1873 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, 1874 asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, 1875 libs, precompiled_header, precompiled_source, rustflags, 1876 rustenv, swiftflags 1877 Deps: data_deps, deps, public_deps 1878 Dependent configs: all_dependent_configs, public_configs 1879 General: check_includes, configs, data, friend, inputs, metadata, 1880 output_name, output_extension, public, sources, testonly, 1881 visibility 1882 Rust variables: aliased_deps, crate_root, crate_name, crate_type 1883``` 1884### <a name="func_rust_library"></a>**rust_library**: Declare a Rust library target. 1885 1886``` 1887 A Rust library is an archive containing additional rust-c provided metadata. 1888 These are the files produced by the rustc compiler with the `.rlib` 1889 extension, and are the intermediate step for most Rust-based binaries. 1890``` 1891 1892#### **Language and compilation** 1893 1894``` 1895 The tools and commands used to create this target type will be 1896 determined by the source files in its sources. Targets containing 1897 multiple compiler-incompatible languages are not allowed (e.g. a 1898 target containing both C and C++ sources is acceptable, but a 1899 target containing C and Rust sources is not). 1900``` 1901 1902#### **Variables** 1903 1904``` 1905 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, 1906 asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, 1907 libs, precompiled_header, precompiled_source, rustflags, 1908 rustenv, swiftflags 1909 Deps: data_deps, deps, public_deps 1910 Dependent configs: all_dependent_configs, public_configs 1911 General: check_includes, configs, data, friend, inputs, metadata, 1912 output_name, output_extension, public, sources, testonly, 1913 visibility 1914 Rust variables: aliased_deps, crate_root, crate_name 1915``` 1916### <a name="func_rust_proc_macro"></a>**rust_proc_macro**: Declare a Rust procedural macro target. 1917 1918``` 1919 A Rust procedural macro allows creating syntax extensions as execution of a 1920 function. They are compiled as dynamic libraries and used by the compiler at 1921 runtime. 1922 1923 Their use is the same as of other Rust libraries, but their build has some 1924 additional restrictions in terms of supported flags. 1925``` 1926 1927#### **Language and compilation** 1928 1929``` 1930 The tools and commands used to create this target type will be 1931 determined by the source files in its sources. Targets containing 1932 multiple compiler-incompatible languages are not allowed (e.g. a 1933 target containing both C and C++ sources is acceptable, but a 1934 target containing C and Rust sources is not). 1935``` 1936 1937#### **Variables** 1938 1939``` 1940 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, 1941 asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, 1942 libs, precompiled_header, precompiled_source, rustflags, 1943 rustenv, swiftflags 1944 Deps: data_deps, deps, public_deps 1945 Dependent configs: all_dependent_configs, public_configs 1946 General: check_includes, configs, data, friend, inputs, metadata, 1947 output_name, output_extension, public, sources, testonly, 1948 visibility 1949 Rust variables: aliased_deps, crate_root, crate_name 1950``` 1951### <a name="func_shared_library"></a>**shared_library**: Declare a shared library target. 1952 1953``` 1954 A shared library will be specified on the linker line for targets listing the 1955 shared library in its "deps". If you don't want this (say you dynamically 1956 load the library at runtime), then you should depend on the shared library 1957 via "data_deps" or, on Darwin platforms, use a "loadable_module" target type 1958 instead. 1959``` 1960 1961#### **Language and compilation** 1962 1963``` 1964 The tools and commands used to create this target type will be 1965 determined by the source files in its sources. Targets containing 1966 multiple compiler-incompatible languages are not allowed (e.g. a 1967 target containing both C and C++ sources is acceptable, but a 1968 target containing C and Rust sources is not). 1969``` 1970 1971#### **Variables** 1972 1973``` 1974 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, 1975 asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, 1976 libs, precompiled_header, precompiled_source, rustflags, 1977 rustenv, swiftflags 1978 Deps: data_deps, deps, public_deps 1979 Dependent configs: all_dependent_configs, public_configs 1980 General: check_includes, configs, data, friend, inputs, metadata, 1981 output_name, output_extension, public, sources, testonly, 1982 visibility 1983 Rust variables: aliased_deps, crate_root, crate_name, crate_type 1984``` 1985### <a name="func_source_set"></a>**source_set**: Declare a source set target. 1986 1987``` 1988 Only C-language source sets are supported at the moment. 1989``` 1990 1991#### **C-language source_sets** 1992 1993``` 1994 A source set is a collection of sources that get compiled, but are not linked 1995 to produce any kind of library. Instead, the resulting object files are 1996 implicitly added to the linker line of all targets that depend on the source 1997 set. 1998 1999 In most cases, a source set will behave like a static library, except no 2000 actual library file will be produced. This will make the build go a little 2001 faster by skipping creation of a large static library, while maintaining the 2002 organizational benefits of focused build targets. 2003 2004 The main difference between a source set and a static library is around 2005 handling of exported symbols. Most linkers assume declaring a function 2006 exported means exported from the static library. The linker can then do dead 2007 code elimination to delete code not reachable from exported functions. 2008 2009 A source set will not do this code elimination since there is no link step. 2010 This allows you to link many source sets into a shared library and have the 2011 "exported symbol" notation indicate "export from the final shared library and 2012 not from the intermediate targets." There is no way to express this concept 2013 when linking multiple static libraries into a shared library. 2014``` 2015 2016#### **Variables** 2017 2018``` 2019 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, 2020 asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, 2021 libs, precompiled_header, precompiled_source, rustflags, 2022 rustenv, swiftflags 2023 Deps: data_deps, deps, public_deps 2024 Dependent configs: all_dependent_configs, public_configs 2025 General: check_includes, configs, data, friend, inputs, metadata, 2026 output_name, output_extension, public, sources, testonly, 2027 visibility 2028``` 2029### <a name="func_static_library"></a>**static_library**: Declare a static library target. 2030 2031``` 2032 Make a ".a" / ".lib" file. 2033 2034 If you only need the static library for intermediate results in the build, 2035 you should consider a source_set instead since it will skip the (potentially 2036 slow) step of creating the intermediate library file. 2037``` 2038 2039#### **Variables** 2040 2041``` 2042 complete_static_lib 2043 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, 2044 asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, 2045 libs, precompiled_header, precompiled_source, rustflags, 2046 rustenv, swiftflags 2047 Deps: data_deps, deps, public_deps 2048 Dependent configs: all_dependent_configs, public_configs 2049 General: check_includes, configs, data, friend, inputs, metadata, 2050 output_name, output_extension, public, sources, testonly, 2051 visibility 2052 Rust variables: aliased_deps, crate_root, crate_name 2053 2054 The tools and commands used to create this target type will be 2055 determined by the source files in its sources. Targets containing 2056 multiple compiler-incompatible languages are not allowed (e.g. a 2057 target containing both C and C++ sources is acceptable, but a 2058 target containing C and Rust sources is not). 2059``` 2060### <a name="func_target"></a>**target**: Declare an target with the given programmatic type. 2061 2062``` 2063 target(target_type_string, target_name_string) { ... } 2064 2065 The target() function is a way to invoke a built-in target or template with a 2066 type determined at runtime. This is useful for cases where the type of a 2067 target might not be known statically. 2068 2069 Only templates and built-in target functions are supported for the 2070 target_type_string parameter. Arbitrary functions, configs, and toolchains 2071 are not supported. 2072 2073 The call: 2074 target("source_set", "doom_melon") { 2075 Is equivalent to: 2076 source_set("doom_melon") { 2077``` 2078 2079#### **Example** 2080 2081``` 2082 if (foo_build_as_shared) { 2083 my_type = "shared_library" 2084 } else { 2085 my_type = "source_set" 2086 } 2087 2088 target(my_type, "foo") { 2089 ... 2090 } 2091``` 2092## <a name="functions"></a>Buildfile functions 2093 2094### <a name="func_assert"></a>**assert**: Assert an expression is true at generation time. 2095 2096``` 2097 assert(<condition> [, <error string>]) 2098 2099 If the condition is false, the build will fail with an error. If the 2100 optional second argument is provided, that string will be printed 2101 with the error message. 2102``` 2103 2104#### **Examples** 2105 2106``` 2107 assert(is_win) 2108 assert(defined(sources), "Sources must be defined"); 2109``` 2110### <a name="func_config"></a>**config**: Defines a configuration object. 2111 2112``` 2113 Configuration objects can be applied to targets and specify sets of compiler 2114 flags, includes, defines, etc. They provide a way to conveniently group sets 2115 of this configuration information. 2116 2117 A config is referenced by its label just like a target. 2118 2119 The values in a config are additive only. If you want to remove a flag you 2120 need to remove the corresponding config that sets it. The final set of flags, 2121 defines, etc. for a target is generated in this order: 2122 2123 1. The values specified directly on the target (rather than using a config. 2124 2. The configs specified in the target's "configs" list, in order. 2125 3. Public_configs from a breadth-first traversal of the dependency tree in 2126 the order that the targets appear in "deps". 2127 4. All dependent configs from a breadth-first traversal of the dependency 2128 tree in the order that the targets appear in "deps". 2129``` 2130 2131#### **More background** 2132 2133``` 2134 Configs solve a problem where the build system needs to have a higher-level 2135 understanding of various compiler settings. For example, some compiler flags 2136 have to appear in a certain order relative to each other, some settings like 2137 defines and flags logically go together, and the build system needs to 2138 de-duplicate flags even though raw command-line parameters can't always be 2139 operated on in that way. 2140 2141 The config gives a name to a group of settings that can then be reasoned 2142 about by GN. GN can know that configs with the same label are the same thing 2143 so can be de-duplicated. It allows related settings to be grouped so they 2144 are added or removed as a unit. And it allows targets to refer to settings 2145 with conceptual names ("no_rtti", "enable_exceptions", etc.) rather than 2146 having to hard-coding every compiler's flags each time they are referred to. 2147``` 2148 2149#### **Variables valid in a config definition** 2150 2151``` 2152 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, 2153 asmflags, defines, include_dirs, inputs, ldflags, lib_dirs, 2154 libs, precompiled_header, precompiled_source, rustflags, 2155 rustenv, swiftflags 2156 Nested configs: configs 2157``` 2158 2159#### **Variables on a target used to apply configs** 2160 2161``` 2162 all_dependent_configs, configs, public_configs 2163``` 2164 2165#### **Example** 2166 2167``` 2168 config("myconfig") { 2169 include_dirs = [ "include/common" ] 2170 defines = [ "ENABLE_DOOM_MELON" ] 2171 } 2172 2173 executable("mything") { 2174 configs = [ ":myconfig" ] 2175 } 2176``` 2177### <a name="func_declare_args"></a>**declare_args**: Declare build arguments. 2178 2179``` 2180 Introduces the given arguments into the current scope. If they are not 2181 specified on the command line or in a toolchain's arguments, the default 2182 values given in the declare_args block will be used. However, these defaults 2183 will not override command-line values. 2184 2185 See also "gn help buildargs" for an overview. 2186 2187 The precise behavior of declare args is: 2188 2189 1. The declare_args() block executes. Any variable defined in the enclosing 2190 scope is available for reading, but any variable defined earlier in 2191 the current scope is not (since the overrides haven't been applied yet). 2192 2193 2. At the end of executing the block, any variables set within that scope 2194 are saved, with the values specified in the block used as the "default value" 2195 for that argument. Once saved, these variables are available for override 2196 via args.gn. 2197 2198 3. User-defined overrides are applied. Anything set in "gn args" now 2199 overrides any default values. The resulting set of variables is promoted 2200 to be readable from the following code in the file. 2201 2202 This has some ramifications that may not be obvious: 2203 2204 - You should not perform difficult work inside a declare_args block since 2205 this only sets a default value that may be discarded. In particular, 2206 don't use the result of exec_script() to set the default value. If you 2207 want to have a script-defined default, set some default "undefined" value 2208 like [], "", or -1, and after the declare_args block, call exec_script if 2209 the value is unset by the user. 2210 2211 - Because you cannot read the value of a variable defined in the same 2212 block, if you need to make the default value of one arg depend 2213 on the possibly-overridden value of another, write two separate 2214 declare_args() blocks: 2215 2216 declare_args() { 2217 enable_foo = true 2218 } 2219 declare_args() { 2220 # Bar defaults to same user-overridden state as foo. 2221 enable_bar = enable_foo 2222 } 2223``` 2224 2225#### **Example** 2226 2227``` 2228 declare_args() { 2229 enable_teleporter = true 2230 enable_doom_melon = false 2231 } 2232 2233 If you want to override the (default disabled) Doom Melon: 2234 gn --args="enable_doom_melon=true enable_teleporter=true" 2235 This also sets the teleporter, but it's already defaulted to on so it will 2236 have no effect. 2237``` 2238### <a name="func_defined"></a>**defined**: Returns whether an identifier is defined. 2239 2240``` 2241 Returns true if the given argument is defined. This is most useful in 2242 templates to assert that the caller set things up properly. 2243 2244 You can pass an identifier: 2245 defined(foo) 2246 which will return true or false depending on whether foo is defined in the 2247 current scope. 2248 2249 You can also check a named scope: 2250 defined(foo.bar) 2251 which will return true or false depending on whether bar is defined in the 2252 named scope foo. It will throw an error if foo is not defined or is not a 2253 scope. 2254``` 2255 2256#### **Example** 2257 2258``` 2259 template("mytemplate") { 2260 # To help users call this template properly... 2261 assert(defined(invoker.sources), "Sources must be defined") 2262 2263 # If we want to accept an optional "values" argument, we don't 2264 # want to dereference something that may not be defined. 2265 if (defined(invoker.values)) { 2266 values = invoker.values 2267 } else { 2268 values = "some default value" 2269 } 2270 } 2271``` 2272### <a name="func_exec_script"></a>**exec_script**: Synchronously run a script and return the output. 2273 2274``` 2275 exec_script(filename, 2276 arguments = [], 2277 input_conversion = "", 2278 file_dependencies = []) 2279 2280 Runs the given script, returning the stdout of the script. The build 2281 generation will fail if the script does not exist or returns a nonzero exit 2282 code. 2283 2284 The current directory when executing the script will be the root build 2285 directory. If you are passing file names, you will want to use the 2286 rebase_path() function to make file names relative to this path (see "gn help 2287 rebase_path"). 2288 2289 The default script interpreter is Python ("python" on POSIX, "python.exe" or 2290 "python.bat" on Windows). This can be configured by the script_executable 2291 variable, see "gn help dotfile". 2292``` 2293 2294#### **Arguments**: 2295 2296``` 2297 filename: 2298 File name of script to execute. Non-absolute names will be treated as 2299 relative to the current build file. 2300 2301 arguments: 2302 A list of strings to be passed to the script as arguments. May be 2303 unspecified or the empty list which means no arguments. 2304 2305 input_conversion: 2306 Controls how the file is read and parsed. See "gn help io_conversion". 2307 2308 If unspecified, defaults to the empty string which causes the script 2309 result to be discarded. exec script will return None. 2310 2311 dependencies: 2312 (Optional) A list of files that this script reads or otherwise depends 2313 on. These dependencies will be added to the build result such that if any 2314 of them change, the build will be regenerated and the script will be 2315 re-run. 2316 2317 The script itself will be an implicit dependency so you do not need to 2318 list it. 2319``` 2320 2321#### **Example** 2322 2323``` 2324 all_lines = exec_script( 2325 "myscript.py", [some_input], "list lines", 2326 [ rebase_path("data_file.txt", root_build_dir) ]) 2327 2328 # This example just calls the script with no arguments and discards the 2329 # result. 2330 exec_script("//foo/bar/myscript.py") 2331``` 2332### <a name="func_filter_exclude"></a>**filter_exclude**: Remove values that match a set of patterns. 2333 2334``` 2335 filter_exclude(values, exclude_patterns) 2336 2337 The argument values must be a list of strings. 2338 2339 The argument exclude_patterns must be a list of file patterns (see 2340 "gn help file_pattern"). Any elements in values matching at least one 2341 of those patterns will be excluded. 2342``` 2343 2344#### **Examples** 2345``` 2346 values = [ "foo.cc", "foo.h", "foo.proto" ] 2347 result = filter_exclude(values, [ "*.proto" ]) 2348 # result will be [ "foo.cc", "foo.h" ] 2349``` 2350### <a name="func_filter_include"></a>**filter_include**: Remove values that do not match a set of patterns. 2351 2352``` 2353 filter_include(values, include_patterns) 2354 2355 The argument values must be a list of strings. 2356 2357 The argument include_patterns must be a list of file patterns (see 2358 "gn help file_pattern"). Only elements from values matching at least 2359 one of the pattern will be included. 2360``` 2361 2362#### **Examples** 2363``` 2364 values = [ "foo.cc", "foo.h", "foo.proto" ] 2365 result = filter_include(values, [ "*.proto" ]) 2366 # result will be [ "foo.proto" ] 2367``` 2368### <a name="func_foreach"></a>**foreach**: Iterate over a list. 2369 2370``` 2371 foreach(<loop_var>, <list>) { 2372 <loop contents> 2373 } 2374 2375 Executes the loop contents block over each item in the list, assigning the 2376 loop_var to each item in sequence. The <loop_var> will be a copy so assigning 2377 to it will not mutate the list. The loop will iterate over a copy of <list> 2378 so mutating it inside the loop will not affect iteration. 2379 2380 The block does not introduce a new scope, so that variable assignments inside 2381 the loop will be visible once the loop terminates. 2382 2383 The loop variable will temporarily shadow any existing variables with the 2384 same name for the duration of the loop. After the loop terminates the loop 2385 variable will no longer be in scope, and the previous value (if any) will be 2386 restored. 2387``` 2388 2389#### **Example** 2390 2391``` 2392 mylist = [ "a", "b", "c" ] 2393 foreach(i, mylist) { 2394 print(i) 2395 } 2396 2397 Prints: 2398 a 2399 b 2400 c 2401``` 2402### <a name="func_forward_variables_from"></a>**forward_variables_from**: Copies variables from a different scope. 2403 2404``` 2405 forward_variables_from(from_scope, variable_list_or_star, 2406 variable_to_not_forward_list = []) 2407 2408 Copies the given variables from the given scope to the local scope if they 2409 exist. This is normally used in the context of templates to use the values of 2410 variables defined in the template invocation to a template-defined target. 2411 2412 The variables in the given variable_list will be copied if they exist in the 2413 given scope or any enclosing scope. If they do not exist, nothing will happen 2414 and they be left undefined in the current scope. 2415 2416 As a special case, if the variable_list is a string with the value of "*", 2417 all variables from the given scope will be copied. "*" only copies variables 2418 set directly on the from_scope, not enclosing ones. Otherwise it would 2419 duplicate all global variables. 2420 2421 When an explicit list of variables is supplied, if the variable exists in the 2422 current (destination) scope already, an error will be thrown. If "*" is 2423 specified, variables in the current scope will be clobbered (the latter is 2424 important because most targets have an implicit configs list, which means it 2425 wouldn't work at all if it didn't clobber). 2426 2427 If variables_to_not_forward_list is non-empty, then it must contains a list 2428 of variable names that will not be forwarded. This is mostly useful when 2429 variable_list_or_star has a value of "*". 2430``` 2431 2432#### **Examples** 2433 2434``` 2435 # forward_variables_from(invoker, ["foo"]) 2436 # is equivalent to: 2437 assert(!defined(foo)) 2438 if (defined(invoker.foo)) { 2439 foo = invoker.foo 2440 } 2441 2442 # This is a common action template. It would invoke a script with some given 2443 # parameters, and wants to use the various types of deps and the visibility 2444 # from the invoker if it's defined. It also injects an additional dependency 2445 # to all targets. 2446 template("my_test") { 2447 action(target_name) { 2448 forward_variables_from(invoker, [ "data_deps", "deps", 2449 "public_deps", "visibility"]) 2450 # Add our test code to the dependencies. 2451 # "deps" may or may not be defined at this point. 2452 if (defined(deps)) { 2453 deps += [ "//tools/doom_melon" ] 2454 } else { 2455 deps = [ "//tools/doom_melon" ] 2456 } 2457 } 2458 } 2459 2460 # This is a template around a target whose type depends on a global variable. 2461 # It forwards all values from the invoker. 2462 template("my_wrapper") { 2463 target(my_wrapper_target_type, target_name) { 2464 forward_variables_from(invoker, "*") 2465 } 2466 } 2467 2468 # A template that wraps another. It adds behavior based on one 2469 # variable, and forwards all others to the nested target. 2470 template("my_ios_test_app") { 2471 ios_test_app(target_name) { 2472 forward_variables_from(invoker, "*", ["test_bundle_name"]) 2473 if (!defined(extra_substitutions)) { 2474 extra_substitutions = [] 2475 } 2476 extra_substitutions += [ "BUNDLE_ID_TEST_NAME=$test_bundle_name" ] 2477 } 2478 } 2479``` 2480### <a name="func_get_label_info"></a>**get_label_info**: Get an attribute from a target's label. 2481 2482``` 2483 get_label_info(target_label, what) 2484 2485 Given the label of a target, returns some attribute of that target. The 2486 target need not have been previously defined in the same file, since none of 2487 the attributes depend on the actual target definition, only the label itself. 2488 2489 See also "gn help get_target_outputs". 2490``` 2491 2492#### **Possible values for the "what" parameter** 2493 2494``` 2495 "name" 2496 The short name of the target. This will match the value of the 2497 "target_name" variable inside that target's declaration. For the label 2498 "//foo/bar:baz" this will return "baz". 2499 2500 "dir" 2501 The directory containing the target's definition, with no slash at the 2502 end. For the label "//foo/bar:baz" this will return "//foo/bar". 2503 2504 "target_gen_dir" 2505 The generated file directory for the target. This will match the value of 2506 the "target_gen_dir" variable when inside that target's declaration. 2507 2508 "root_gen_dir" 2509 The root of the generated file tree for the target. This will match the 2510 value of the "root_gen_dir" variable when inside that target's 2511 declaration. 2512 2513 "target_out_dir 2514 The output directory for the target. This will match the value of the 2515 "target_out_dir" variable when inside that target's declaration. 2516 2517 "root_out_dir" 2518 The root of the output file tree for the target. This will match the 2519 value of the "root_out_dir" variable when inside that target's 2520 declaration. 2521 2522 "label_no_toolchain" 2523 The fully qualified version of this label, not including the toolchain. 2524 For the input ":bar" it might return "//foo:bar". 2525 2526 "label_with_toolchain" 2527 The fully qualified version of this label, including the toolchain. For 2528 the input ":bar" it might return "//foo:bar(//toolchain:x64)". 2529 2530 "toolchain" 2531 The label of the toolchain. This will match the value of the 2532 "current_toolchain" variable when inside that target's declaration. 2533``` 2534 2535#### **Examples** 2536 2537``` 2538 get_label_info(":foo", "name") 2539 # Returns string "foo". 2540 2541 get_label_info("//foo/bar:baz", "target_gen_dir") 2542 # Returns string "//out/Debug/gen/foo/bar". 2543``` 2544### <a name="func_get_path_info"></a>**get_path_info**: Extract parts of a file or directory name. 2545 2546``` 2547 get_path_info(input, what) 2548 2549 The first argument is either a string representing a file or directory name, 2550 or a list of such strings. If the input is a list the return value will be a 2551 list containing the result of applying the rule to each item in the input. 2552``` 2553 2554#### **Possible values for the "what" parameter** 2555 2556``` 2557 "file" 2558 The substring after the last slash in the path, including the name and 2559 extension. If the input ends in a slash, the empty string will be 2560 returned. 2561 "foo/bar.txt" => "bar.txt" 2562 "bar.txt" => "bar.txt" 2563 "foo/" => "" 2564 "" => "" 2565 2566 "name" 2567 The substring of the file name not including the extension. 2568 "foo/bar.txt" => "bar" 2569 "foo/bar" => "bar" 2570 "foo/" => "" 2571 2572 "extension" 2573 The substring following the last period following the last slash, or the 2574 empty string if not found. The period is not included. 2575 "foo/bar.txt" => "txt" 2576 "foo/bar" => "" 2577 2578 "dir" 2579 The directory portion of the name, not including the slash. 2580 "foo/bar.txt" => "foo" 2581 "//foo/bar" => "//foo" 2582 "foo" => "." 2583 2584 The result will never end in a slash, so if the resulting is empty, the 2585 system ("/") or source ("//") roots, a "." will be appended such that it 2586 is always legal to append a slash and a filename and get a valid path. 2587 2588 "out_dir" 2589 The output file directory corresponding to the path of the given file, 2590 not including a trailing slash. 2591 "//foo/bar/baz.txt" => "//out/Default/obj/foo/bar" 2592 2593 "gen_dir" 2594 The generated file directory corresponding to the path of the given file, 2595 not including a trailing slash. 2596 "//foo/bar/baz.txt" => "//out/Default/gen/foo/bar" 2597 2598 "abspath" 2599 The full absolute path name to the file or directory. It will be resolved 2600 relative to the current directory, and then the source- absolute version 2601 will be returned. If the input is system- absolute, the same input will 2602 be returned. 2603 "foo/bar.txt" => "//mydir/foo/bar.txt" 2604 "foo/" => "//mydir/foo/" 2605 "//foo/bar" => "//foo/bar" (already absolute) 2606 "/usr/include" => "/usr/include" (already absolute) 2607 2608 If you want to make the path relative to another directory, or to be 2609 system-absolute, see rebase_path(). 2610``` 2611 2612#### **Examples** 2613``` 2614 sources = [ "foo.cc", "foo.h" ] 2615 result = get_path_info(source, "abspath") 2616 # result will be [ "//mydir/foo.cc", "//mydir/foo.h" ] 2617 2618 result = get_path_info("//foo/bar/baz.cc", "dir") 2619 # result will be "//foo/bar" 2620 2621 # Extract the source-absolute directory name, 2622 result = get_path_info(get_path_info(path, "dir"), "abspath") 2623``` 2624### <a name="func_get_target_outputs"></a>**get_target_outputs**: [file list] Get the list of outputs from a target. 2625 2626``` 2627 get_target_outputs(target_label) 2628 2629 Returns a list of output files for the named target. The named target must 2630 have been previously defined in the current file before this function is 2631 called (it can't reference targets in other files because there isn't a 2632 defined execution order, and it obviously can't reference targets that are 2633 defined after the function call). 2634 2635 Only copy, generated_file, and action targets are supported. The outputs from 2636 binary targets will depend on the toolchain definition which won't 2637 necessarily have been loaded by the time a given line of code has run, and 2638 source sets and groups have no useful output file. 2639``` 2640 2641#### **Return value** 2642 2643``` 2644 The names in the resulting list will be absolute file paths (normally like 2645 "//out/Debug/bar.exe", depending on the build directory). 2646 2647 action, copy, and generated_file targets: this will just return the files 2648 specified in the "outputs" variable of the target. 2649 2650 action_foreach targets: this will return the result of applying the output 2651 template to the sources (see "gn help source_expansion"). This will be the 2652 same result (though with guaranteed absolute file paths), as 2653 process_file_template will return for those inputs (see "gn help 2654 process_file_template"). 2655 2656 source sets and groups: this will return a list containing the path of the 2657 "stamp" file that Ninja will produce once all outputs are generated. This 2658 probably isn't very useful. 2659``` 2660 2661#### **Example** 2662 2663``` 2664 # Say this action generates a bunch of C source files. 2665 action_foreach("my_action") { 2666 sources = [ ... ] 2667 outputs = [ ... ] 2668 } 2669 2670 # Compile the resulting source files into a source set. 2671 source_set("my_lib") { 2672 sources = get_target_outputs(":my_action") 2673 } 2674``` 2675### <a name="func_getenv"></a>**getenv**: Get an environment variable. 2676 2677``` 2678 value = getenv(env_var_name) 2679 2680 Returns the value of the given environment variable. If the value is not 2681 found, it will try to look up the variable with the "opposite" case (based on 2682 the case of the first letter of the variable), but is otherwise 2683 case-sensitive. 2684 2685 If the environment variable is not found, the empty string will be returned. 2686 Note: it might be nice to extend this if we had the concept of "none" in the 2687 language to indicate lookup failure. 2688``` 2689 2690#### **Example** 2691 2692``` 2693 home_dir = getenv("HOME") 2694``` 2695### <a name="func_import"></a>**import**: Import a file into the current scope. 2696 2697``` 2698 The import command loads the rules and variables resulting from executing the 2699 given file into the current scope. 2700 2701 By convention, imported files are named with a .gni extension. 2702 2703 An import is different than a C++ "include". The imported file is executed in 2704 a standalone environment from the caller of the import command. The results 2705 of this execution are cached for other files that import the same .gni file. 2706 2707 Note that you can not import a BUILD.gn file that's otherwise used in the 2708 build. Files must either be imported or implicitly loaded as a result of deps 2709 rules, but not both. 2710 2711 The imported file's scope will be merged with the scope at the point import 2712 was called. If there is a conflict (both the current scope and the imported 2713 file define some variable or rule with the same name but different value), a 2714 runtime error will be thrown. Therefore, it's good practice to minimize the 2715 stuff that an imported file defines. 2716 2717 Variables and templates beginning with an underscore '_' are considered 2718 private and will not be imported. Imported files can use such variables for 2719 internal computation without affecting other files. 2720``` 2721 2722#### **Examples** 2723 2724``` 2725 import("//build/rules/idl_compilation_rule.gni") 2726 2727 # Looks in the current directory. 2728 import("my_vars.gni") 2729``` 2730### <a name="func_not_needed"></a>**not_needed**: Mark variables from scope as not needed. 2731 2732``` 2733 not_needed(variable_list_or_star, variable_to_ignore_list = []) 2734 not_needed(from_scope, variable_list_or_star, 2735 variable_to_ignore_list = []) 2736 2737 Mark the variables in the current or given scope as not needed, which means 2738 you will not get an error about unused variables for these. The 2739 variable_to_ignore_list allows excluding variables from "all matches" if 2740 variable_list_or_star is "*". 2741``` 2742 2743#### **Example** 2744 2745``` 2746 not_needed("*", [ "config" ]) 2747 not_needed([ "data_deps", "deps" ]) 2748 not_needed(invoker, "*", [ "config" ]) 2749 not_needed(invoker, [ "data_deps", "deps" ]) 2750``` 2751### <a name="func_pool"></a>**pool**: Defines a pool object. 2752 2753``` 2754 Pool objects can be applied to a tool to limit the parallelism of the 2755 build. This object has a single property "depth" corresponding to 2756 the number of tasks that may run simultaneously. 2757 2758 As the file containing the pool definition may be executed in the 2759 context of more than one toolchain it is recommended to specify an 2760 explicit toolchain when defining and referencing a pool. 2761 2762 A pool named "console" defined in the root build file represents Ninja's 2763 console pool. Targets using this pool will have access to the console's 2764 stdin and stdout, and output will not be buffered. This special pool must 2765 have a depth of 1. Pools not defined in the root must not be named "console". 2766 The console pool can only be defined for the default toolchain. 2767 Refer to the Ninja documentation on the console pool for more info. 2768 2769 A pool is referenced by its label just like a target. 2770``` 2771 2772#### **Variables** 2773 2774``` 2775 depth* 2776 * = required 2777``` 2778 2779#### **Example** 2780 2781``` 2782 if (current_toolchain == default_toolchain) { 2783 pool("link_pool") { 2784 depth = 1 2785 } 2786 } 2787 2788 toolchain("toolchain") { 2789 tool("link") { 2790 command = "..." 2791 pool = ":link_pool($default_toolchain)" 2792 } 2793 } 2794``` 2795### <a name="func_print"></a>**print**: Prints to the console. 2796 2797``` 2798 Prints all arguments to the console separated by spaces. A newline is 2799 automatically appended to the end. 2800 2801 This function is intended for debugging. Note that build files are run in 2802 parallel so you may get interleaved prints. A buildfile may also be executed 2803 more than once in parallel in the context of different toolchains so the 2804 prints from one file may be duplicated or 2805 interleaved with itself. 2806``` 2807 2808#### **Examples** 2809 2810``` 2811 print("Hello world") 2812 2813 print(sources, deps) 2814``` 2815### <a name="func_process_file_template"></a>**process_file_template**: Do template expansion over a list of files. 2816 2817``` 2818 process_file_template(source_list, template) 2819 2820 process_file_template applies a template list to a source file list, 2821 returning the result of applying each template to each source. This is 2822 typically used for computing output file names from input files. 2823 2824 In most cases, get_target_outputs() will give the same result with shorter, 2825 more maintainable code. This function should only be used when that function 2826 can't be used (like there's no target or the target is defined in another 2827 build file). 2828``` 2829 2830#### **Arguments** 2831 2832``` 2833 The source_list is a list of file names. 2834 2835 The template can be a string or a list. If it is a list, multiple output 2836 strings are generated for each input. 2837 2838 The template should contain source expansions to which each name in the 2839 source list is applied. See "gn help source_expansion". 2840``` 2841 2842#### **Example** 2843 2844``` 2845 sources = [ 2846 "foo.idl", 2847 "bar.idl", 2848 ] 2849 myoutputs = process_file_template( 2850 sources, 2851 [ "$target_gen_dir/{{source_name_part}}.cc", 2852 "$target_gen_dir/{{source_name_part}}.h" ]) 2853 2854 The result in this case will be: 2855 [ "//out/Debug/foo.cc" 2856 "//out/Debug/foo.h" 2857 "//out/Debug/bar.cc" 2858 "//out/Debug/bar.h" ] 2859``` 2860### <a name="func_read_file"></a>**read_file**: Read a file into a variable. 2861 2862``` 2863 read_file(filename, input_conversion) 2864 2865 Whitespace will be trimmed from the end of the file. Throws an error if the 2866 file can not be opened. 2867``` 2868 2869#### **Arguments** 2870 2871``` 2872 filename 2873 Filename to read, relative to the build file. 2874 2875 input_conversion 2876 Controls how the file is read and parsed. See "gn help io_conversion". 2877``` 2878 2879#### **Example** 2880 2881``` 2882 lines = read_file("foo.txt", "list lines") 2883``` 2884### <a name="func_rebase_path"></a>**rebase_path**: Rebase a file or directory to another location. 2885 2886``` 2887 converted = rebase_path(input, 2888 new_base = "", 2889 current_base = ".") 2890 2891 Takes a string argument representing a file name, or a list of such strings 2892 and converts it/them to be relative to a different base directory. 2893 2894 When invoking the compiler or scripts, GN will automatically convert sources 2895 and include directories to be relative to the build directory. However, if 2896 you're passing files directly in the "args" array or doing other manual 2897 manipulations where GN doesn't know something is a file name, you will need 2898 to convert paths to be relative to what your tool is expecting. 2899 2900 The common case is to use this to convert paths relative to the current 2901 directory to be relative to the build directory (which will be the current 2902 directory when executing scripts). 2903 2904 If you want to convert a file path to be source-absolute (that is, beginning 2905 with a double slash like "//foo/bar"), you should use the get_path_info() 2906 function. This function won't work because it will always make relative 2907 paths, and it needs to support making paths relative to the source root, so 2908 it can't also generate source-absolute paths without more special-cases. 2909``` 2910 2911#### **Arguments** 2912 2913``` 2914 input 2915 A string or list of strings representing file or directory names. These 2916 can be relative paths ("foo/bar.txt"), system absolute paths 2917 ("/foo/bar.txt"), or source absolute paths ("//foo/bar.txt"). 2918 2919 new_base 2920 The directory to convert the paths to be relative to. This can be an 2921 absolute path or a relative path (which will be treated as being relative 2922 to the current BUILD-file's directory). 2923 2924 As a special case, if new_base is the empty string (the default), all 2925 paths will be converted to system-absolute native style paths with system 2926 path separators. This is useful for invoking external programs. 2927 2928 current_base 2929 Directory representing the base for relative paths in the input. If this 2930 is not an absolute path, it will be treated as being relative to the 2931 current build file. Use "." (the default) to convert paths from the 2932 current BUILD-file's directory. 2933``` 2934 2935#### **Return value** 2936 2937``` 2938 The return value will be the same type as the input value (either a string or 2939 a list of strings). All relative and source-absolute file names will be 2940 converted to be relative to the requested output System-absolute paths will 2941 be unchanged. 2942 2943 Whether an output path will end in a slash will match whether the 2944 corresponding input path ends in a slash. It will return "." or "./" 2945 (depending on whether the input ends in a slash) to avoid returning empty 2946 strings. This means if you want a root path ("//" or "/") not ending in a 2947 slash, you can add a dot ("//."). 2948``` 2949 2950#### **Example** 2951 2952``` 2953 # Convert a file in the current directory to be relative to the build 2954 # directory (the current dir when executing compilers and scripts). 2955 foo = rebase_path("myfile.txt", root_build_dir) 2956 # might produce "../../project/myfile.txt". 2957 2958 # Convert a file to be system absolute: 2959 foo = rebase_path("myfile.txt") 2960 # Might produce "D:\\source\\project\\myfile.txt" on Windows or 2961 # "/home/you/source/project/myfile.txt" on Linux. 2962 2963 # Typical usage for converting to the build directory for a script. 2964 action("myscript") { 2965 # Don't convert sources, GN will automatically convert these to be relative 2966 # to the build directory when it constructs the command line for your 2967 # script. 2968 sources = [ "foo.txt", "bar.txt" ] 2969 2970 # Extra file args passed manually need to be explicitly converted 2971 # to be relative to the build directory: 2972 args = [ 2973 "--data", 2974 rebase_path("//mything/data/input.dat", root_build_dir), 2975 "--rel", 2976 rebase_path("relative_path.txt", root_build_dir) 2977 ] + rebase_path(sources, root_build_dir) 2978 } 2979``` 2980### <a name="func_set_default_toolchain"></a>**set_default_toolchain**: Sets the default toolchain name. 2981 2982``` 2983 set_default_toolchain(toolchain_label) 2984 2985 The given label should identify a toolchain definition (see "gn help 2986 toolchain"). This toolchain will be used for all targets unless otherwise 2987 specified. 2988 2989 This function is only valid to call during the processing of the build 2990 configuration file. Since the build configuration file is processed 2991 separately for each toolchain, this function will be a no-op when called 2992 under any non-default toolchains. 2993 2994 For example, the default toolchain should be appropriate for the current 2995 environment. If the current environment is 32-bit and somebody references a 2996 target with a 64-bit toolchain, we wouldn't want processing of the build 2997 config file for the 64-bit toolchain to reset the default toolchain to 2998 64-bit, we want to keep it 32-bits. 2999``` 3000 3001#### **Argument** 3002 3003``` 3004 toolchain_label 3005 Toolchain name. 3006``` 3007 3008#### **Example** 3009 3010``` 3011 # Set default toolchain only has an effect when run in the context of the 3012 # default toolchain. Pick the right one according to the current CPU 3013 # architecture. 3014 if (target_cpu == "x64") { 3015 set_default_toolchain("//toolchains:64") 3016 } else if (target_cpu == "x86") { 3017 set_default_toolchain("//toolchains:32") 3018 } 3019``` 3020### <a name="func_set_defaults"></a>**set_defaults**: Set default values for a target type. 3021 3022``` 3023 set_defaults(<target_type_name>) { <values...> } 3024 3025 Sets the default values for a given target type. Whenever target_type_name is 3026 seen in the future, the values specified in set_default's block will be 3027 copied into the current scope. 3028 3029 When the target type is used, the variable copying is very strict. If a 3030 variable with that name is already in scope, the build will fail with an 3031 error. 3032 3033 set_defaults can be used for built-in target types ("executable", 3034 "shared_library", etc.) and custom ones defined via the "template" command. 3035 It can be called more than once and the most recent call in any scope will 3036 apply, but there is no way to refer to the previous defaults and modify them 3037 (each call to set_defaults must supply a complete list of all defaults it 3038 wants). If you want to share defaults, store them in a separate variable. 3039``` 3040 3041#### **Example** 3042 3043``` 3044 set_defaults("static_library") { 3045 configs = [ "//tools/mything:settings" ] 3046 } 3047 3048 static_library("mylib") { 3049 # The configs will be auto-populated as above. You can remove it if 3050 # you don't want the default for a particular default: 3051 configs -= [ "//tools/mything:settings" ] 3052 } 3053``` 3054### <a name="func_set_sources_assignment_filter"></a>**set_sources_assignment_filter**: Deprecated feature. 3055 3056``` 3057 This feature is deprecated. It will be removed once all usages have been 3058 removed. Only supports a single argument that needs to be an empty list. 3059``` 3060### <a name="func_split_list"></a>**split_list**: Splits a list into N different sub-lists. 3061 3062``` 3063 result = split_list(input, n) 3064 3065 Given a list and a number N, splits the list into N sub-lists of 3066 approximately equal size. The return value is a list of the sub-lists. The 3067 result will always be a list of size N. If N is greater than the number of 3068 elements in the input, it will be padded with empty lists. 3069 3070 The expected use is to divide source files into smaller uniform chunks. 3071``` 3072 3073#### **Example** 3074 3075``` 3076 The code: 3077 mylist = [1, 2, 3, 4, 5, 6] 3078 print(split_list(mylist, 3)) 3079 3080 Will print: 3081 [[1, 2], [3, 4], [5, 6] 3082``` 3083### <a name="func_string_join"></a>**string_join**: Concatenates a list of strings with a separator. 3084 3085``` 3086 result = string_join(separator, strings) 3087 3088 Concatenate a list of strings with intervening occurrences of separator. 3089``` 3090 3091#### **Examples** 3092 3093``` 3094 string_join("", ["a", "b", "c"]) --> "abc" 3095 string_join("|", ["a", "b", "c"]) --> "a|b|c" 3096 string_join(", ", ["a", "b", "c"]) --> "a, b, c" 3097 string_join("s", ["", ""]) --> "s" 3098``` 3099### <a name="func_string_replace"></a>**string_replace**: Replaces substring in the given string. 3100 3101``` 3102 result = string_replace(str, old, new[, max]) 3103 3104 Returns a copy of the string str in which the occurrences of old have been 3105 replaced with new, optionally restricting the number of replacements. The 3106 replacement is performed sequentially, so if new contains old, it won't be 3107 replaced. 3108``` 3109 3110#### **Example** 3111 3112``` 3113 The code: 3114 mystr = "Hello, world!" 3115 print(string_replace(mystr, "world", "GN")) 3116 3117 Will print: 3118 Hello, GN! 3119``` 3120### <a name="func_string_split"></a>**string_split**: Split string into a list of strings. 3121 3122``` 3123 result = string_split(str[, sep]) 3124 3125 Split string into all substrings separated by separator and returns a list 3126 of the substrings between those separators. 3127 3128 If the separator argument is omitted, the split is by any whitespace, and 3129 any leading/trailing whitespace is ignored; similar to Python's str.split(). 3130``` 3131 3132#### **Examples without a separator (split on whitespace)**: 3133 3134``` 3135 string_split("") --> [] 3136 string_split("a") --> ["a"] 3137 string_split(" aa bb") --> ["aa", "bb"] 3138``` 3139 3140#### **Examples with a separator (split on separators)**: 3141 3142``` 3143 string_split("", "|") --> [""] 3144 string_split(" a b ", " ") --> ["", "", "a", "b", "", ""] 3145 string_split("aa+-bb+-c", "+-") --> ["aa", "bb", "c"] 3146``` 3147### <a name="func_template"></a>**template**: Define a template rule. 3148 3149``` 3150 A template defines a custom name that acts like a function. It provides a way 3151 to add to the built-in target types. 3152 3153 The template() function is used to declare a template. To invoke the 3154 template, just use the name of the template like any other target type. 3155 3156 Often you will want to declare your template in a special file that other 3157 files will import (see "gn help import") so your template rule can be shared 3158 across build files. 3159``` 3160 3161#### **Variables and templates**: 3162 3163``` 3164 When you call template() it creates a closure around all variables currently 3165 in scope with the code in the template block. When the template is invoked, 3166 the closure will be executed. 3167 3168 When the template is invoked, the code in the caller is executed and passed 3169 to the template code as an implicit "invoker" variable. The template uses 3170 this to read state out of the invoking code. 3171 3172 One thing explicitly excluded from the closure is the "current directory" 3173 against which relative file names are resolved. The current directory will be 3174 that of the invoking code, since typically that code specifies the file 3175 names. This means all files internal to the template should use absolute 3176 names. 3177 3178 A template will typically forward some or all variables from the invoking 3179 scope to a target that it defines. Often, such variables might be optional. 3180 Use the pattern: 3181 3182 if (defined(invoker.deps)) { 3183 deps = invoker.deps 3184 } 3185 3186 The function forward_variables_from() provides a shortcut to forward one or 3187 more or possibly all variables in this manner: 3188 3189 forward_variables_from(invoker, ["deps", "public_deps"]) 3190``` 3191 3192#### **Target naming** 3193 3194``` 3195 Your template should almost always define a built-in target with the name the 3196 template invoker specified. For example, if you have an IDL template and 3197 somebody does: 3198 idl("foo") {... 3199 you will normally want this to expand to something defining a source_set or 3200 static_library named "foo" (among other things you may need). This way, when 3201 another target specifies a dependency on "foo", the static_library or 3202 source_set will be linked. 3203 3204 It is also important that any other targets your template expands to have 3205 unique names, or you will get collisions. 3206 3207 Access the invoking name in your template via the implicit "target_name" 3208 variable. This should also be the basis for how other targets that a template 3209 expands to ensure uniqueness. 3210 3211 A typical example would be a template that defines an action to generate some 3212 source files, and a source_set to compile that source. Your template would 3213 name the source_set "target_name" because that's what you want external 3214 targets to depend on to link your code. And you would name the action 3215 something like "${target_name}_action" to make it unique. The source set 3216 would have a dependency on the action to make it run. 3217``` 3218 3219#### **Overriding builtin targets** 3220 3221``` 3222 You can use template to redefine a built-in target in which case your template 3223 takes a precedence over the built-in one. All uses of the target from within 3224 the template definition will refer to the built-in target which makes it 3225 possible to extend the behavior of the built-in target: 3226 3227 template("shared_library") { 3228 shared_library(shlib) { 3229 forward_variables_from(invoker, "*") 3230 ... 3231 } 3232 } 3233``` 3234 3235#### **Example of defining a template** 3236 3237``` 3238 template("my_idl") { 3239 # Be nice and help callers debug problems by checking that the variables 3240 # the template requires are defined. This gives a nice message rather than 3241 # giving the user an error about an undefined variable in the file defining 3242 # the template 3243 # 3244 # You can also use defined() to give default values to variables 3245 # unspecified by the invoker. 3246 assert(defined(invoker.sources), 3247 "Need sources in $target_name listing the idl files.") 3248 3249 # Name of the intermediate target that does the code gen. This must 3250 # incorporate the target name so it's unique across template 3251 # instantiations. 3252 code_gen_target_name = target_name + "_code_gen" 3253 3254 # Intermediate target to convert IDL to C source. Note that the name is 3255 # based on the name the invoker of the template specified. This way, each 3256 # time the template is invoked we get a unique intermediate action name 3257 # (since all target names are in the global scope). 3258 action_foreach(code_gen_target_name) { 3259 # Access the scope defined by the invoker via the implicit "invoker" 3260 # variable. 3261 sources = invoker.sources 3262 3263 # Note that we need an absolute path for our script file name. The 3264 # current directory when executing this code will be that of the invoker 3265 # (this is why we can use the "sources" directly above without having to 3266 # rebase all of the paths). But if we need to reference a script relative 3267 # to the template file, we'll need to use an absolute path instead. 3268 script = "//tools/idl/idl_code_generator.py" 3269 3270 # Tell GN how to expand output names given the sources. 3271 # See "gn help source_expansion" for more. 3272 outputs = [ "$target_gen_dir/{{source_name_part}}.cc", 3273 "$target_gen_dir/{{source_name_part}}.h" ] 3274 } 3275 3276 # Name the source set the same as the template invocation so instancing 3277 # this template produces something that other targets can link to in their 3278 # deps. 3279 source_set(target_name) { 3280 # Generates the list of sources, we get these from the action_foreach 3281 # above. 3282 sources = get_target_outputs(":$code_gen_target_name") 3283 3284 # This target depends on the files produced by the above code gen target. 3285 deps = [ ":$code_gen_target_name" ] 3286 } 3287 } 3288``` 3289 3290#### **Example of invoking the resulting template** 3291 3292``` 3293 # This calls the template code above, defining target_name to be 3294 # "foo_idl_files" and "invoker" to be the set of stuff defined in the curly 3295 # brackets. 3296 my_idl("foo_idl_files") { 3297 # Goes into the template as "invoker.sources". 3298 sources = [ "foo.idl", "bar.idl" ] 3299 } 3300 3301 # Here is a target that depends on our template. 3302 executable("my_exe") { 3303 # Depend on the name we gave the template call above. Internally, this will 3304 # produce a dependency from executable to the source_set inside the 3305 # template (since it has this name), which will in turn depend on the code 3306 # gen action. 3307 deps = [ ":foo_idl_files" ] 3308 } 3309``` 3310### <a name="func_tool"></a>**tool**: Specify arguments to a toolchain tool. 3311 3312#### **Usage** 3313 3314``` 3315 tool(<tool type>) { 3316 <tool variables...> 3317 } 3318``` 3319 3320#### **Tool types** 3321 3322``` 3323 Compiler tools: 3324 "cc": C compiler 3325 "cxx": C++ compiler 3326 "cxx_module": C++ compiler used for Clang .modulemap files 3327 "objc": Objective C compiler 3328 "objcxx": Objective C++ compiler 3329 "rc": Resource compiler (Windows .rc files) 3330 "asm": Assembler 3331 "swift": Swift compiler driver 3332 3333 Linker tools: 3334 "alink": Linker for static libraries (archives) 3335 "solink": Linker for shared libraries 3336 "link": Linker for executables 3337 3338 Other tools: 3339 "stamp": Tool for creating stamp files 3340 "copy": Tool to copy files. 3341 "action": Defaults for actions 3342 3343 Platform specific tools: 3344 "copy_bundle_data": [iOS, macOS] Tool to copy files in a bundle. 3345 "compile_xcassets": [iOS, macOS] Tool to compile asset catalogs. 3346 3347 Rust tools: 3348 "rust_bin": Tool for compiling Rust binaries 3349 "rust_cdylib": Tool for compiling C-compatible dynamic libraries. 3350 "rust_dylib": Tool for compiling Rust dynamic libraries. 3351 "rust_macro": Tool for compiling Rust procedural macros. 3352 "rust_rlib": Tool for compiling Rust libraries. 3353 "rust_staticlib": Tool for compiling Rust static libraries. 3354``` 3355 3356#### **Tool variables** 3357 3358``` 3359 command [string with substitutions] 3360 Valid for: all tools except "action" (required) 3361 3362 The command to run. 3363 3364 command_launcher [string] 3365 Valid for: all tools except "action" (optional) 3366 3367 The prefix with which to launch the command (e.g. the path to a Goma or 3368 CCache compiler launcher). 3369 3370 Note that this prefix will not be included in the compilation database or 3371 IDE files generated from the build. 3372 3373 default_output_dir [string with substitutions] 3374 Valid for: linker tools 3375 3376 Default directory name for the output file relative to the 3377 root_build_dir. It can contain other substitution patterns. This will 3378 be the default value for the {{output_dir}} expansion (discussed below) 3379 but will be overridden by the "output_dir" variable in a target, if one 3380 is specified. 3381 3382 GN doesn't do anything with this string other than pass it along, 3383 potentially with target-specific overrides. It is the tool's job to use 3384 the expansion so that the files will be in the right place. 3385 3386 default_output_extension [string] 3387 Valid for: linker tools 3388 3389 Extension for the main output of a linkable tool. It includes the 3390 leading dot. This will be the default value for the 3391 {{output_extension}} expansion (discussed below) but will be overridden 3392 by by the "output extension" variable in a target, if one is specified. 3393 Empty string means no extension. 3394 3395 GN doesn't actually do anything with this extension other than pass it 3396 along, potentially with target-specific overrides. One would typically 3397 use the {{output_extension}} value in the "outputs" to read this value. 3398 3399 Example: default_output_extension = ".exe" 3400 3401 depfile [string with substitutions] 3402 Valid for: compiler tools (optional) 3403 3404 If the tool can write ".d" files, this specifies the name of the 3405 resulting file. These files are used to list header file dependencies 3406 (or other implicit input dependencies) that are discovered at build 3407 time. See also "depsformat". 3408 3409 Example: depfile = "{{output}}.d" 3410 3411 depsformat [string] 3412 Valid for: compiler tools (when depfile is specified) 3413 3414 Format for the deps outputs. This is either "gcc" or "msvc". See the 3415 ninja documentation for "deps" for more information. 3416 3417 Example: depsformat = "gcc" 3418 3419 description [string with substitutions, optional] 3420 Valid for: all tools 3421 3422 What to print when the command is run. 3423 3424 Example: description = "Compiling {{source}}" 3425 3426 exe_output_extension [string, optional, rust tools only] 3427 rlib_output_extension [string, optional, rust tools only] 3428 dylib_output_extension [string, optional, rust tools only] 3429 cdylib_output_extension [string, optional, rust tools only] 3430 rust_proc_macro_output_extension [string, optional, rust tools only] 3431 Valid for: Rust tools 3432 3433 These specify the default tool output for each of the crate types. 3434 The default is empty for executables, shared, and static libraries and 3435 ".rlib" for rlibs. Note that the Rust compiler complains with an error 3436 if external crates do not take the form `lib<name>.rlib` or 3437 `lib<name>.<shared_extension>`, where `<shared_extension>` is `.so`, 3438 `.dylib`, or `.dll` as appropriate for the platform. 3439 3440 lib_switch [string, optional, link tools only] 3441 lib_dir_switch [string, optional, link tools only] 3442 Valid for: Linker tools except "alink" 3443 3444 These strings will be prepended to the libraries and library search 3445 directories, respectively, because linkers differ on how to specify 3446 them. 3447 3448 If you specified: 3449 lib_switch = "-l" 3450 lib_dir_switch = "-L" 3451 then the "{{libs}}" expansion for 3452 [ "freetype", "expat" ] 3453 would be 3454 "-lfreetype -lexpat". 3455 3456 framework_switch [string, optional, link tools only] 3457 weak_framework_switch [string, optional, link tools only] 3458 framework_dir_switch [string, optional, link tools only] 3459 Valid for: Linker tools 3460 3461 These strings will be prepended to the frameworks and framework search 3462 path directories, respectively, because linkers differ on how to specify 3463 them. 3464 3465 If you specified: 3466 framework_switch = "-framework " 3467 weak_framework_switch = "-weak_framework " 3468 framework_dir_switch = "-F" 3469 and: 3470 framework_dirs = [ "$root_out_dir" ] 3471 frameworks = [ "UIKit.framework", "Foo.framework" ] 3472 weak_frameworks = [ "MediaPlayer.framework" ] 3473 would be: 3474 "-F. -framework UIKit -framework Foo -weak_framework MediaPlayer" 3475 3476 swiftmodule_switch [string, optional, link tools only] 3477 Valid for: Linker tools except "alink" 3478 3479 The string will be prependend to the path to the .swiftmodule files 3480 that are embedded in the linker output. 3481 3482 If you specified: 3483 swiftmodule_swift = "-Wl,-add_ast_path," 3484 then the "{{swiftmodules}}" expansion for 3485 [ "obj/foo/Foo.swiftmodule" ] 3486 would be 3487 "-Wl,-add_ast_path,obj/foo/Foo.swiftmodule" 3488 3489 outputs [list of strings with substitutions] 3490 Valid for: Linker and compiler tools (required) 3491 3492 An array of names for the output files the tool produces. These are 3493 relative to the build output directory. There must always be at least 3494 one output file. There can be more than one output (a linker might 3495 produce a library and an import library, for example). 3496 3497 This array just declares to GN what files the tool will produce. It is 3498 your responsibility to specify the tool command that actually produces 3499 these files. 3500 3501 If you specify more than one output for shared library links, you 3502 should consider setting link_output, depend_output, and 3503 runtime_outputs. 3504 3505 Example for a compiler tool that produces .obj files: 3506 outputs = [ 3507 "{{source_out_dir}}/{{source_name_part}}.obj" 3508 ] 3509 3510 Example for a linker tool that produces a .dll and a .lib. The use of 3511 {{target_output_name}}, {{output_extension}} and {{output_dir}} allows 3512 the target to override these values. 3513 outputs = [ 3514 "{{output_dir}}/{{target_output_name}}" 3515 "{{output_extension}}", 3516 "{{output_dir}}/{{target_output_name}}.lib", 3517 ] 3518 3519 partial_outputs [list of strings with substitutions] 3520 Valid for: "swift" only 3521 3522 An array of names for the partial outputs the tool produces. These 3523 are relative to the build output directory. The expansion will be 3524 evaluated for each file listed in the "sources" of the target. 3525 3526 This is used to deal with whole module optimization, allowing to 3527 list one object file per source file when whole module optimization 3528 is disabled. 3529 3530 pool [label, optional] 3531 Valid for: all tools (optional) 3532 3533 Label of the pool to use for the tool. Pools are used to limit the 3534 number of tasks that can execute concurrently during the build. 3535 3536 See also "gn help pool". 3537 3538 link_output [string with substitutions] 3539 depend_output [string with substitutions] 3540 Valid for: "solink" only (optional) 3541 3542 These two files specify which of the outputs from the solink tool 3543 should be used for linking and dependency tracking. These should match 3544 entries in the "outputs". If unspecified, the first item in the 3545 "outputs" array will be used for all. See "Separate linking and 3546 dependencies for shared libraries" below for more. 3547 3548 On Windows, where the tools produce a .dll shared library and a .lib 3549 import library, you will want the first two to be the import library 3550 and the third one to be the .dll file. On Linux, if you're not doing 3551 the separate linking/dependency optimization, all of these should be 3552 the .so output. 3553 3554 output_prefix [string] 3555 Valid for: Linker tools (optional) 3556 3557 Prefix to use for the output name. Defaults to empty. This prefix will 3558 be prepended to the name of the target (or the output_name if one is 3559 manually specified for it) if the prefix is not already there. The 3560 result will show up in the {{output_name}} substitution pattern. 3561 3562 Individual targets can opt-out of the output prefix by setting: 3563 output_prefix_override = true 3564 (see "gn help output_prefix_override"). 3565 3566 This is typically used to prepend "lib" to libraries on 3567 Posix systems: 3568 output_prefix = "lib" 3569 3570 precompiled_header_type [string] 3571 Valid for: "cc", "cxx", "objc", "objcxx" 3572 3573 Type of precompiled headers. If undefined or the empty string, 3574 precompiled headers will not be used for this tool. Otherwise use "gcc" 3575 or "msvc". 3576 3577 For precompiled headers to be used for a given target, the target (or a 3578 config applied to it) must also specify a "precompiled_header" and, for 3579 "msvc"-style headers, a "precompiled_source" value. If the type is 3580 "gcc", then both "precompiled_header" and "precompiled_source" must 3581 resolve to the same file, despite the different formats required for 3582 each." 3583 3584 See "gn help precompiled_header" for more. 3585 3586 restat [boolean] 3587 Valid for: all tools (optional, defaults to false) 3588 3589 Requests that Ninja check the file timestamp after this tool has run to 3590 determine if anything changed. Set this if your tool has the ability to 3591 skip writing output if the output file has not changed. 3592 3593 Normally, Ninja will assume that when a tool runs the output be new and 3594 downstream dependents must be rebuild. When this is set to trye, Ninja 3595 can skip rebuilding downstream dependents for input changes that don't 3596 actually affect the output. 3597 3598 Example: 3599 restat = true 3600 3601 rspfile [string with substitutions] 3602 Valid for: all tools except "action" (optional) 3603 3604 Name of the response file. If empty, no response file will be 3605 used. See "rspfile_content". 3606 3607 rspfile_content [string with substitutions] 3608 Valid for: all tools except "action" (required when "rspfile" is used) 3609 3610 The contents to be written to the response file. This may include all 3611 or part of the command to send to the tool which allows you to get 3612 around OS command-line length limits. 3613 3614 This example adds the inputs and libraries to a response file, but 3615 passes the linker flags directly on the command line: 3616 tool("link") { 3617 command = "link -o {{output}} {{ldflags}} @{{output}}.rsp" 3618 rspfile = "{{output}}.rsp" 3619 rspfile_content = "{{inputs}} {{solibs}} {{libs}} {{rlibs}}" 3620 } 3621 3622 runtime_outputs [string list with substitutions] 3623 Valid for: linker tools 3624 3625 If specified, this list is the subset of the outputs that should be 3626 added to runtime deps (see "gn help runtime_deps"). By default (if 3627 runtime_outputs is empty or unspecified), it will be the link_output. 3628``` 3629 3630#### **Expansions for tool variables** 3631 3632``` 3633 All paths are relative to the root build directory, which is the current 3634 directory for running all tools. These expansions are available to all tools: 3635 3636 {{label}} 3637 The label of the current target. This is typically used in the 3638 "description" field for link tools. The toolchain will be omitted from 3639 the label for targets in the default toolchain, and will be included 3640 for targets in other toolchains. 3641 3642 {{label_name}} 3643 The short name of the label of the target. This is the part after the 3644 colon. For "//foo/bar:baz" this will be "baz". Unlike 3645 {{target_output_name}}, this is not affected by the "output_prefix" in 3646 the tool or the "output_name" set on the target. 3647 3648 {{label_no_toolchain}} 3649 The label of the current target, never including the toolchain 3650 (otherwise, this is identical to {{label}}). This is used as the module 3651 name when using .modulemap files. 3652 3653 {{output}} 3654 The relative path and name of the output(s) of the current build step. 3655 If there is more than one output, this will expand to a list of all of 3656 them. Example: "out/base/my_file.o" 3657 3658 {{target_gen_dir}} 3659 {{target_out_dir}} 3660 The directory of the generated file and output directories, 3661 respectively, for the current target. There is no trailing slash. See 3662 also {{output_dir}} for linker tools. Example: "out/base/test" 3663 3664 {{target_output_name}} 3665 The short name of the current target with no path information, or the 3666 value of the "output_name" variable if one is specified in the target. 3667 This will include the "output_prefix" if any. See also {{label_name}}. 3668 3669 Example: "libfoo" for the target named "foo" and an output prefix for 3670 the linker tool of "lib". 3671 3672 Compiler tools have the notion of a single input and a single output, along 3673 with a set of compiler-specific flags. The following expansions are 3674 available: 3675 3676 {{asmflags}} 3677 {{cflags}} 3678 {{cflags_c}} 3679 {{cflags_cc}} 3680 {{cflags_objc}} 3681 {{cflags_objcc}} 3682 {{defines}} 3683 {{include_dirs}} 3684 Strings correspond that to the processed flags/defines/include 3685 directories specified for the target. 3686 Example: "--enable-foo --enable-bar" 3687 3688 Defines will be prefixed by "-D" and include directories will be 3689 prefixed by "-I" (these work with Posix tools as well as Microsoft 3690 ones). 3691 3692 {{module_deps}} 3693 {{module_deps_no_self}} 3694 Strings that correspond to the flags necessary to depend upon the Clang 3695 modules referenced by the current target. The "_no_self" version doesn't 3696 include the module for the current target, and can be used to compile 3697 the pcm itself. 3698 3699 {{source}} 3700 The relative path and name of the current input file. 3701 Example: "../../base/my_file.cc" 3702 3703 {{source_file_part}} 3704 The file part of the source including the extension (with no directory 3705 information). 3706 Example: "foo.cc" 3707 3708 {{source_name_part}} 3709 The filename part of the source file with no directory or extension. 3710 Example: "foo" 3711 3712 {{source_gen_dir}} 3713 {{source_out_dir}} 3714 The directory in the generated file and output directories, 3715 respectively, for the current input file. If the source file is in the 3716 same directory as the target is declared in, they will will be the same 3717 as the "target" versions above. Example: "gen/base/test" 3718 3719 Linker tools have multiple inputs and (potentially) multiple outputs. The 3720 static library tool ("alink") is not considered a linker tool. The following 3721 expansions are available: 3722 3723 {{inputs}} 3724 {{inputs_newline}} 3725 Expands to the inputs to the link step. This will be a list of object 3726 files and static libraries. 3727 Example: "obj/foo.o obj/bar.o obj/somelibrary.a" 3728 3729 The "_newline" version will separate the input files with newlines 3730 instead of spaces. This is useful in response files: some linkers can 3731 take a "-filelist" flag which expects newline separated files, and some 3732 Microsoft tools have a fixed-sized buffer for parsing each line of a 3733 response file. 3734 3735 {{ldflags}} 3736 Expands to the processed set of ldflags and library search paths 3737 specified for the target. 3738 Example: "-m64 -fPIC -pthread -L/usr/local/mylib" 3739 3740 {{libs}} 3741 Expands to the list of system libraries to link to. Each will be 3742 prefixed by the "lib_switch". 3743 3744 Example: "-lfoo -lbar" 3745 3746 {{output_dir}} 3747 The value of the "output_dir" variable in the target, or the the value 3748 of the "default_output_dir" value in the tool if the target does not 3749 override the output directory. This will be relative to the 3750 root_build_dir and will not end in a slash. Will be "." for output to 3751 the root_build_dir. 3752 3753 This is subtly different than {{target_out_dir}} which is defined by GN 3754 based on the target's path and not overridable. {{output_dir}} is for 3755 the final output, {{target_out_dir}} is generally for object files and 3756 other outputs. 3757 3758 Usually {{output_dir}} would be defined in terms of either 3759 {{target_out_dir}} or {{root_out_dir}} 3760 3761 {{output_extension}} 3762 The value of the "output_extension" variable in the target, or the 3763 value of the "default_output_extension" value in the tool if the target 3764 does not specify an output extension. 3765 Example: ".so" 3766 3767 {{solibs}} 3768 Extra libraries from shared library dependencies not specified in the 3769 {{inputs}}. This is the list of link_output files from shared libraries 3770 (if the solink tool specifies a "link_output" variable separate from 3771 the "depend_output"). 3772 3773 These should generally be treated the same as libs by your tool. 3774 3775 Example: "libfoo.so libbar.so" 3776 3777 {{rlibs}} 3778 Any Rust .rlibs which need to be linked into a final C++ target. 3779 These should be treated as {{inputs}} except that sometimes 3780 they might have different linker directives applied. 3781 3782 Example: "obj/foo/libfoo.rlib" 3783 3784 {{frameworks}} 3785 Shared libraries packaged as framework bundle. This is principally 3786 used on Apple's platforms (macOS and iOS). All name must be ending 3787 with ".framework" suffix; the suffix will be stripped when expanding 3788 {{frameworks}} and each item will be preceded by "-framework" or 3789 "-weak_framework". 3790 3791 {{swiftmodules}} 3792 Swift .swiftmodule files that needs to be embedded into the binary. 3793 This is necessary to correctly link with object generated by the 3794 Swift compiler (the .swiftmodule file cannot be embedded in object 3795 files directly). Those will be prefixed with "swiftmodule_switch" 3796 value. 3797 3798 The static library ("alink") tool allows {{arflags}} plus the common tool 3799 substitutions. 3800 3801 The copy tool allows the common compiler/linker substitutions, plus 3802 {{source}} which is the source of the copy. The stamp tool allows only the 3803 common tool substitutions. 3804 3805 The copy_bundle_data and compile_xcassets tools only allows the common tool 3806 substitutions. Both tools are required to create iOS/macOS bundles and need 3807 only be defined on those platforms. 3808 3809 The copy_bundle_data tool will be called with one source and needs to copy 3810 (optionally optimizing the data representation) to its output. It may be 3811 called with a directory as input and it needs to be recursively copied. 3812 3813 The compile_xcassets tool will be called with one or more source (each an 3814 asset catalog) that needs to be compiled to a single output. The following 3815 substitutions are available: 3816 3817 {{inputs}} 3818 Expands to the list of .xcassets to use as input to compile the asset 3819 catalog. 3820 3821 {{bundle_product_type}} 3822 Expands to the product_type of the bundle that will contain the 3823 compiled asset catalog. Usually corresponds to the product_type 3824 property of the corresponding create_bundle target. 3825 3826 {{bundle_partial_info_plist}} 3827 Expands to the path to the partial Info.plist generated by the 3828 assets catalog compiler. Usually based on the target_name of 3829 the create_bundle target. 3830 3831 {{xcasset_compiler_flags}} 3832 Expands to the list of flags specified in corresponding 3833 create_bundle target. 3834 3835 The Swift tool has multiple input and outputs. It must have exactly one 3836 output of .swiftmodule type, but can have one or more object file outputs, 3837 in addition to other type of ouputs. The following expansions are available: 3838 3839 {{module_name}} 3840 Expands to the string representing the module name of target under 3841 compilation (see "module_name" variable). 3842 3843 {{module_dirs}} 3844 Expands to the list of -I<path> for the target Swift module search 3845 path computed from target dependencies. 3846 3847 {{swiftflags}} 3848 Expands to the list of strings representing Swift compiler flags. 3849 3850 Rust tools have the notion of a single input and a single output, along 3851 with a set of compiler-specific flags. The following expansions are 3852 available: 3853 3854 {{crate_name}} 3855 Expands to the string representing the crate name of target under 3856 compilation. 3857 3858 {{crate_type}} 3859 Expands to the string representing the type of crate for the target 3860 under compilation. 3861 3862 {{externs}} 3863 Expands to the list of --extern flags needed to include addition Rust 3864 libraries in this target. Includes any specified renamed dependencies. 3865 3866 {{rustdeps}} 3867 Expands to the list of -Ldependency=<path> strings needed to compile 3868 this target. 3869 3870 {{rustenv}} 3871 Expands to the list of environment variables. 3872 3873 {{rustflags}} 3874 Expands to the list of strings representing Rust compiler flags. 3875``` 3876 3877#### **Separate linking and dependencies for shared libraries** 3878 3879``` 3880 Shared libraries are special in that not all changes to them require that 3881 dependent targets be re-linked. If the shared library is changed but no 3882 imports or exports are different, dependent code needn't be relinked, which 3883 can speed up the build. 3884 3885 If your link step can output a list of exports from a shared library and 3886 writes the file only if the new one is different, the timestamp of this file 3887 can be used for triggering re-links, while the actual shared library would be 3888 used for linking. 3889 3890 You will need to specify 3891 restat = true 3892 in the linker tool to make this work, so Ninja will detect if the timestamp 3893 of the dependency file has changed after linking (otherwise it will always 3894 assume that running a command updates the output): 3895 3896 tool("solink") { 3897 command = "..." 3898 outputs = [ 3899 "{{output_dir}}/{{target_output_name}}{{output_extension}}", 3900 "{{output_dir}}/{{target_output_name}}" 3901 "{{output_extension}}.TOC", 3902 ] 3903 link_output = 3904 "{{output_dir}}/{{target_output_name}}{{output_extension}}" 3905 depend_output = 3906 "{{output_dir}}/{{target_output_name}}" 3907 "{{output_extension}}.TOC" 3908 restat = true 3909 } 3910``` 3911 3912#### **Example** 3913 3914``` 3915 toolchain("my_toolchain") { 3916 # Put these at the top to apply to all tools below. 3917 lib_switch = "-l" 3918 lib_dir_switch = "-L" 3919 3920 tool("cc") { 3921 command = "gcc {{source}} -o {{output}}" 3922 outputs = [ "{{source_out_dir}}/{{source_name_part}}.o" ] 3923 description = "GCC {{source}}" 3924 } 3925 tool("cxx") { 3926 command = "g++ {{source}} -o {{output}}" 3927 outputs = [ "{{source_out_dir}}/{{source_name_part}}.o" ] 3928 description = "G++ {{source}}" 3929 } 3930 }; 3931``` 3932### <a name="func_toolchain"></a>**toolchain**: Defines a toolchain. 3933 3934``` 3935 A toolchain is a set of commands and build flags used to compile the source 3936 code. The toolchain() function defines these commands. 3937``` 3938 3939#### **Toolchain overview** 3940 3941``` 3942 You can have more than one toolchain in use at once in a build and a target 3943 can exist simultaneously in multiple toolchains. A build file is executed 3944 once for each toolchain it is referenced in so the GN code can vary all 3945 parameters of each target (or which targets exist) on a per-toolchain basis. 3946 3947 When you have a simple build with only one toolchain, the build config file 3948 is loaded only once at the beginning of the build. It must call 3949 set_default_toolchain() (see "gn help set_default_toolchain") to tell GN the 3950 label of the toolchain definition to use. The "toolchain_args" section of the 3951 toolchain definition is ignored. 3952 3953 When a target has a dependency on a target using different toolchain (see "gn 3954 help labels" for how to specify this), GN will start a build using that 3955 secondary toolchain to resolve the target. GN will load the build config file 3956 with the build arguments overridden as specified in the toolchain_args. 3957 Because the default toolchain is already known, calls to 3958 set_default_toolchain() are ignored. 3959 3960 To load a file in an alternate toolchain, GN does the following: 3961 3962 1. Loads the file with the toolchain definition in it (as determined by the 3963 toolchain label). 3964 2. Re-runs the master build configuration file, applying the arguments 3965 specified by the toolchain_args section of the toolchain definition. 3966 3. Loads the destination build file in the context of the configuration file 3967 in the previous step. 3968 3969 The toolchain configuration is two-way. In the default toolchain (i.e. the 3970 main build target) the configuration flows from the build config file to the 3971 toolchain. The build config file looks at the state of the build (OS type, 3972 CPU architecture, etc.) and decides which toolchain to use (via 3973 set_default_toolchain()). In secondary toolchains, the configuration flows 3974 from the toolchain to the build config file: the "toolchain_args" in the 3975 toolchain definition specifies the arguments to re-invoke the build. 3976``` 3977 3978#### **Functions and variables** 3979 3980``` 3981 tool() 3982 The tool() function call specifies the commands to run for a given step. See 3983 "gn help tool". 3984 3985 toolchain_args [scope] 3986 Overrides for build arguments to pass to the toolchain when invoking it. 3987 This is a variable of type "scope" where the variable names correspond to 3988 variables in declare_args() blocks. 3989 3990 When you specify a target using an alternate toolchain, the master build 3991 configuration file is re-interpreted in the context of that toolchain. 3992 toolchain_args allows you to control the arguments passed into this 3993 alternate invocation of the build. 3994 3995 Any default system arguments or arguments passed in via "gn args" will also 3996 be passed to the alternate invocation unless explicitly overridden by 3997 toolchain_args. 3998 3999 The toolchain_args will be ignored when the toolchain being defined is the 4000 default. In this case, it's expected you want the default argument values. 4001 4002 See also "gn help buildargs" for an overview of these arguments. 4003 4004 propagates_configs [boolean, default=false] 4005 Determines whether public_configs and all_dependent_configs in this 4006 toolchain propagate to targets in other toolchains. 4007 4008 When false (the default), this toolchain will not propagate any configs to 4009 targets in other toolchains that depend on it targets inside this 4010 toolchain. This matches the most common usage of toolchains where they 4011 represent different architectures or compilers and the settings that apply 4012 to one won't necessarily apply to others. 4013 4014 When true, configs (public and all-dependent) will cross the boundary out 4015 of this toolchain as if the toolchain boundary wasn't there. This only 4016 affects one direction of dependencies: a toolchain can't control whether 4017 it accepts such configs, only whether it pushes them. The build is 4018 responsible for ensuring that any external targets depending on targets in 4019 this toolchain are compatible with the compiler flags, etc. that may be 4020 propagated. 4021 4022 deps [string list] 4023 Dependencies of this toolchain. These dependencies will be resolved before 4024 any target in the toolchain is compiled. To avoid circular dependencies 4025 these must be targets defined in another toolchain. 4026 4027 This is expressed as a list of targets, and generally these targets will 4028 always specify a toolchain: 4029 deps = [ "//foo/bar:baz(//build/toolchain:bootstrap)" ] 4030 4031 This concept is somewhat inefficient to express in Ninja (it requires a lot 4032 of duplicate of rules) so should only be used when absolutely necessary. 4033``` 4034 4035#### **Example of defining a toolchain** 4036 4037``` 4038 toolchain("32") { 4039 tool("cc") { 4040 command = "gcc {{source}}" 4041 ... 4042 } 4043 4044 toolchain_args = { 4045 use_doom_melon = true # Doom melon always required for 32-bit builds. 4046 current_cpu = "x86" 4047 } 4048 } 4049 4050 toolchain("64") { 4051 tool("cc") { 4052 command = "gcc {{source}}" 4053 ... 4054 } 4055 4056 toolchain_args = { 4057 # use_doom_melon is not overridden here, it will take the default. 4058 current_cpu = "x64" 4059 } 4060 } 4061``` 4062 4063#### **Example of cross-toolchain dependencies** 4064 4065``` 4066 If a 64-bit target wants to depend on a 32-bit binary, it would specify a 4067 dependency using data_deps (data deps are like deps that are only needed at 4068 runtime and aren't linked, since you can't link a 32-bit and a 64-bit 4069 library). 4070 4071 executable("my_program") { 4072 ... 4073 if (target_cpu == "x64") { 4074 # The 64-bit build needs this 32-bit helper. 4075 data_deps = [ ":helper(//toolchains:32)" ] 4076 } 4077 } 4078 4079 if (target_cpu == "x86") { 4080 # Our helper library is only compiled in 32-bits. 4081 shared_library("helper") { 4082 ... 4083 } 4084 } 4085``` 4086### <a name="func_write_file"></a>**write_file**: Write a file to disk. 4087 4088``` 4089 write_file(filename, data, output_conversion = "") 4090 4091 If data is a list, the list will be written one-item-per-line with no quoting 4092 or brackets. 4093 4094 If the file exists and the contents are identical to that being written, the 4095 file will not be updated. This will prevent unnecessary rebuilds of targets 4096 that depend on this file. 4097 4098 One use for write_file is to write a list of inputs to an script that might 4099 be too long for the command line. However, it is preferable to use response 4100 files for this purpose. See "gn help response_file_contents". 4101``` 4102 4103#### **Arguments** 4104 4105``` 4106 filename 4107 Filename to write. This must be within the output directory. 4108 4109 data 4110 The list or string to write. 4111 4112 output_conversion 4113 Controls how the output is written. See "gn help io_conversion". 4114``` 4115## <a name="predefined_variables"></a>Built-in predefined variables 4116 4117### <a name="var_current_cpu"></a>**current_cpu**: The processor architecture of the current toolchain. 4118 4119``` 4120 The build configuration usually sets this value based on the value of 4121 "host_cpu" (see "gn help host_cpu") and then threads this through the 4122 toolchain definitions to ensure that it always reflects the appropriate 4123 value. 4124 4125 This value is not used internally by GN for any purpose. It is set to the 4126 empty string ("") by default but is declared so that it can be overridden on 4127 the command line if so desired. 4128 4129 See "gn help target_cpu" for a list of common values returned. 4130``` 4131### <a name="var_current_os"></a>**current_os**: The operating system of the current toolchain. 4132 4133``` 4134 The build configuration usually sets this value based on the value of 4135 "target_os" (see "gn help target_os"), and then threads this through the 4136 toolchain definitions to ensure that it always reflects the appropriate 4137 value. 4138 4139 This value is not used internally by GN for any purpose. It is set to the 4140 empty string ("") by default but is declared so that it can be overridden on 4141 the command line if so desired. 4142 4143 See "gn help target_os" for a list of common values returned. 4144``` 4145### <a name="var_current_toolchain"></a>**current_toolchain**: Label of the current toolchain. 4146 4147``` 4148 A fully-qualified label representing the current toolchain. You can use this 4149 to make toolchain-related decisions in the build. See also 4150 "default_toolchain". 4151``` 4152 4153#### **Example** 4154 4155``` 4156 if (current_toolchain == "//build:64_bit_toolchain") { 4157 executable("output_thats_64_bit_only") { 4158 ... 4159``` 4160### <a name="var_default_toolchain"></a>**default_toolchain**: [string] Label of the default toolchain. 4161 4162``` 4163 A fully-qualified label representing the default toolchain, which may not 4164 necessarily be the current one (see "current_toolchain"). 4165``` 4166### <a name="var_gn_version"></a>**gn_version**: [number] The version of gn. 4167 4168``` 4169 Corresponds to the number printed by `gn --version`. 4170``` 4171 4172#### **Example** 4173 4174``` 4175 assert(gn_version >= 1700, "need GN version 1700 for the frobulate feature") 4176``` 4177### <a name="var_host_cpu"></a>**host_cpu**: The processor architecture that GN is running on. 4178 4179``` 4180 This is value is exposed so that cross-compile toolchains can access the host 4181 architecture when needed. 4182 4183 The value should generally be considered read-only, but it can be overriden 4184 in order to handle unusual cases where there might be multiple plausible 4185 values for the host architecture (e.g., if you can do either 32-bit or 64-bit 4186 builds). The value is not used internally by GN for any purpose. 4187``` 4188 4189#### **Some possible values** 4190 4191``` 4192 - "x64" 4193 - "x86" 4194``` 4195### <a name="var_host_os"></a>**host_os**: [string] The operating system that GN is running on. 4196 4197``` 4198 This value is exposed so that cross-compiles can access the host build 4199 system's settings. 4200 4201 This value should generally be treated as read-only. It, however, is not used 4202 internally by GN for any purpose. 4203``` 4204 4205#### **Some possible values** 4206 4207``` 4208 - "linux" 4209 - "mac" 4210 - "win" 4211``` 4212### <a name="var_invoker"></a>**invoker**: [string] The invoking scope inside a template. 4213 4214``` 4215 Inside a template invocation, this variable refers to the scope of the 4216 invoker of the template. Outside of template invocations, this variable is 4217 undefined. 4218 4219 All of the variables defined inside the template invocation are accessible as 4220 members of the "invoker" scope. This is the way that templates read values 4221 set by the callers. 4222 4223 This is often used with "defined" to see if a value is set on the invoking 4224 scope. 4225 4226 See "gn help template" for more examples. 4227``` 4228 4229#### **Example** 4230 4231``` 4232 template("my_template") { 4233 print(invoker.sources) # Prints [ "a.cc", "b.cc" ] 4234 print(defined(invoker.foo)) # Prints false. 4235 print(defined(invoker.bar)) # Prints true. 4236 } 4237 4238 my_template("doom_melon") { 4239 sources = [ "a.cc", "b.cc" ] 4240 bar = 123 4241 } 4242``` 4243### <a name="var_python_path"></a>**python_path**: Absolute path of Python. 4244 4245``` 4246 Normally used in toolchain definitions if running some command requires 4247 Python. You will normally not need this when invoking scripts since GN 4248 automatically finds it for you. 4249``` 4250### <a name="var_root_build_dir"></a>**root_build_dir**: [string] Directory where build commands are run. 4251 4252``` 4253 This is the root build output directory which will be the current directory 4254 when executing all compilers and scripts. 4255 4256 Most often this is used with rebase_path (see "gn help rebase_path") to 4257 convert arguments to be relative to a script's current directory. 4258``` 4259### <a name="var_root_gen_dir"></a>**root_gen_dir**: Directory for the toolchain's generated files. 4260 4261``` 4262 Absolute path to the root of the generated output directory tree for the 4263 current toolchain. An example would be "//out/Debug/gen" for the default 4264 toolchain, or "//out/Debug/arm/gen" for the "arm" toolchain. 4265 4266 This is primarily useful for setting up include paths for generated files. If 4267 you are passing this to a script, you will want to pass it through 4268 rebase_path() (see "gn help rebase_path") to convert it to be relative to the 4269 build directory. 4270 4271 See also "target_gen_dir" which is usually a better location for generated 4272 files. It will be inside the root generated dir. 4273``` 4274### <a name="var_root_out_dir"></a>**root_out_dir**: [string] Root directory for toolchain output files. 4275 4276``` 4277 Absolute path to the root of the output directory tree for the current 4278 toolchain. It will not have a trailing slash. 4279 4280 For the default toolchain this will be the same as the root_build_dir. An 4281 example would be "//out/Debug" for the default toolchain, or 4282 "//out/Debug/arm" for the "arm" toolchain. 4283 4284 This is primarily useful for setting up script calls. If you are passing this 4285 to a script, you will want to pass it through rebase_path() (see "gn help 4286 rebase_path") to convert it to be relative to the build directory. 4287 4288 See also "target_out_dir" which is usually a better location for output 4289 files. It will be inside the root output dir. 4290``` 4291 4292#### **Example** 4293 4294``` 4295 action("myscript") { 4296 # Pass the output dir to the script. 4297 args = [ "-o", rebase_path(root_out_dir, root_build_dir) ] 4298 } 4299``` 4300### <a name="var_target_cpu"></a>**target_cpu**: The desired cpu architecture for the build. 4301 4302``` 4303 This value should be used to indicate the desired architecture for the 4304 primary objects of the build. It will match the cpu architecture of the 4305 default toolchain, but not necessarily the current toolchain. 4306 4307 In many cases, this is the same as "host_cpu", but in the case of 4308 cross-compiles, this can be set to something different. This value is 4309 different from "current_cpu" in that it does not change based on the current 4310 toolchain. When writing rules, "current_cpu" should be used rather than 4311 "target_cpu" most of the time. 4312 4313 This value is not used internally by GN for any purpose, so it may be set to 4314 whatever value is needed for the build. GN defaults this value to the empty 4315 string ("") and the configuration files should set it to an appropriate value 4316 (e.g., setting it to the value of "host_cpu") if it is not overridden on the 4317 command line or in the args.gn file. 4318``` 4319 4320#### **Possible values** 4321 4322``` 4323 - "x86" 4324 - "x64" 4325 - "arm" 4326 - "arm64" 4327 - "mipsel" 4328``` 4329### <a name="var_target_gen_dir"></a>**target_gen_dir**: Directory for a target's generated files. 4330 4331``` 4332 Absolute path to the target's generated file directory. This will be the 4333 "root_gen_dir" followed by the relative path to the current build file. If 4334 your file is in "//tools/doom_melon" then target_gen_dir would be 4335 "//out/Debug/gen/tools/doom_melon". It will not have a trailing slash. 4336 4337 This is primarily useful for setting up include paths for generated files. If 4338 you are passing this to a script, you will want to pass it through 4339 rebase_path() (see "gn help rebase_path") to convert it to be relative to the 4340 build directory. 4341 4342 See also "gn help root_gen_dir". 4343``` 4344 4345#### **Example** 4346 4347``` 4348 action("myscript") { 4349 # Pass the generated output dir to the script. 4350 args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]" 4351 } 4352``` 4353### <a name="var_target_name"></a>**target_name**: [string] The name of the current target. 4354 4355``` 4356 Inside a target or template invocation, this variable refers to the name 4357 given to the target or template invocation. Outside of these, this variable 4358 is undefined. 4359 4360 This is most often used in template definitions to name targets defined in 4361 the template based on the name of the invocation. This is necessary both to 4362 ensure generated targets have unique names and to generate a target with the 4363 exact name of the invocation that other targets can depend on. 4364 4365 Be aware that this value will always reflect the innermost scope. So when 4366 defining a target inside a template, target_name will refer to the target 4367 rather than the template invocation. To get the name of the template 4368 invocation in this case, you should save target_name to a temporary variable 4369 outside of any target definitions. 4370 4371 See "gn help template" for more examples. 4372``` 4373 4374#### **Example** 4375 4376``` 4377 executable("doom_melon") { 4378 print(target_name) # Prints "doom_melon". 4379 } 4380 4381 template("my_template") { 4382 print(target_name) # Prints "space_ray" when invoked below. 4383 4384 executable(target_name + "_impl") { 4385 print(target_name) # Prints "space_ray_impl". 4386 } 4387 } 4388 4389 my_template("space_ray") { 4390 } 4391``` 4392### <a name="var_target_os"></a>**target_os**: The desired operating system for the build. 4393 4394``` 4395 This value should be used to indicate the desired operating system for the 4396 primary object(s) of the build. It will match the OS of the default 4397 toolchain. 4398 4399 In many cases, this is the same as "host_os", but in the case of 4400 cross-compiles, it may be different. This variable differs from "current_os" 4401 in that it can be referenced from inside any toolchain and will always return 4402 the initial value. 4403 4404 This should be set to the most specific value possible. So, "android" or 4405 "chromeos" should be used instead of "linux" where applicable, even though 4406 Android and ChromeOS are both Linux variants. This can mean that one needs to 4407 write 4408 4409 if (target_os == "android" || target_os == "linux") { 4410 # ... 4411 } 4412 4413 and so forth. 4414 4415 This value is not used internally by GN for any purpose, so it may be set to 4416 whatever value is needed for the build. GN defaults this value to the empty 4417 string ("") and the configuration files should set it to an appropriate value 4418 (e.g., setting it to the value of "host_os") if it is not set via the command 4419 line or in the args.gn file. 4420``` 4421 4422#### **Possible values** 4423 4424``` 4425 - "android" 4426 - "chromeos" 4427 - "ios" 4428 - "linux" 4429 - "nacl" 4430 - "mac" 4431 - "win" 4432``` 4433### <a name="var_target_out_dir"></a>**target_out_dir**: [string] Directory for target output files. 4434 4435``` 4436 Absolute path to the target's generated file directory. If your current 4437 target is in "//tools/doom_melon" then this value might be 4438 "//out/Debug/obj/tools/doom_melon". It will not have a trailing slash. 4439 4440 This is primarily useful for setting up arguments for calling scripts. If you 4441 are passing this to a script, you will want to pass it through rebase_path() 4442 (see "gn help rebase_path") to convert it to be relative to the build 4443 directory. 4444 4445 See also "gn help root_out_dir". 4446``` 4447 4448#### **Example** 4449 4450``` 4451 action("myscript") { 4452 # Pass the output dir to the script. 4453 args = [ "-o", rebase_path(target_out_dir, root_build_dir) ]" 4454 } 4455``` 4456## <a name="target_variables"></a>Variables you set in targets 4457 4458### <a name="var_aliased_deps"></a>**aliased_deps**: [scope] Set of crate-dependency pairs. 4459 4460``` 4461 Valid for `rust_library` targets and `executable`, `static_library`, and 4462 `shared_library` targets that contain Rust sources. 4463 4464 A scope, each key indicating the renamed crate and the corresponding value 4465 specifying the label of the dependency producing the relevant binary. 4466 4467 All dependencies listed in this field *must* be listed as deps of the target. 4468 4469 executable("foo") { 4470 sources = [ "main.rs" ] 4471 deps = [ "//bar" ] 4472 } 4473 4474 This target would compile the `foo` crate with the following `extern` flag: 4475 `rustc ...command... --extern bar=<build_out_dir>/obj/bar` 4476 4477 executable("foo") { 4478 sources = [ "main.rs" ] 4479 deps = [ ":bar" ] 4480 aliased_deps = { 4481 bar_renamed = ":bar" 4482 } 4483 } 4484 4485 With the addition of `aliased_deps`, above target would instead compile with: 4486 `rustc ...command... --extern bar_renamed=<build_out_dir>/obj/bar` 4487``` 4488### <a name="var_all_dependent_configs"></a>**all_dependent_configs**: Configs to be forced on dependents. 4489 4490``` 4491 A list of config labels. 4492 4493 All targets depending on this one, and recursively, all targets depending on 4494 those, will have the configs listed in this variable added to them. These 4495 configs will also apply to the current target. 4496 4497 This addition happens in a second phase once a target and all of its 4498 dependencies have been resolved. Therefore, a target will not see these 4499 force-added configs in their "configs" variable while the script is running, 4500 and they can not be removed. As a result, this capability should generally 4501 only be used to add defines and include directories necessary to compile a 4502 target's headers. 4503 4504 See also "public_configs". 4505``` 4506 4507#### **Ordering of flags and values** 4508 4509``` 4510 1. Those set on the current target (not in a config). 4511 2. Those set on the "configs" on the target in order that the 4512 configs appear in the list. 4513 3. Those set on the "all_dependent_configs" on the target in order 4514 that the configs appear in the list. 4515 4. Those set on the "public_configs" on the target in order that 4516 those configs appear in the list. 4517 5. all_dependent_configs pulled from dependencies, in the order of 4518 the "deps" list. This is done recursively. If a config appears 4519 more than once, only the first occurence will be used. 4520 6. public_configs pulled from dependencies, in the order of the 4521 "deps" list. If a dependency is public, they will be applied 4522 recursively. 4523``` 4524### <a name="var_allow_circular_includes_from"></a>**allow_circular_includes_from**: Permit includes from deps. 4525 4526``` 4527 A list of target labels. Must be a subset of the target's "deps". These 4528 targets will be permitted to include headers from the current target despite 4529 the dependency going in the opposite direction. 4530 4531 When you use this, both targets must be included in a final binary for it to 4532 link. To keep linker errors from happening, it is good practice to have all 4533 external dependencies depend only on one of the two targets, and to set the 4534 visibility on the other to enforce this. Thus the targets will always be 4535 linked together in any output. 4536``` 4537 4538#### **Details** 4539 4540``` 4541 Normally, for a file in target A to include a file from target B, A must list 4542 B as a dependency. This invariant is enforced by the "gn check" command (and 4543 the --check flag to "gn gen" -- see "gn help check"). 4544 4545 Sometimes, two targets might be the same unit for linking purposes (two 4546 source sets or static libraries that would always be linked together in a 4547 final executable or shared library) and they each include headers from the 4548 other: you want A to be able to include B's headers, and B to include A's 4549 headers. This is not an ideal situation but is sometimes unavoidable. 4550 4551 This list, if specified, lists which of the dependencies of the current 4552 target can include header files from the current target. That is, if A 4553 depends on B, B can only include headers from A if it is in A's 4554 allow_circular_includes_from list. Normally includes must follow the 4555 direction of dependencies, this flag allows them to go in the opposite 4556 direction. 4557``` 4558 4559#### **Danger** 4560 4561``` 4562 In the above example, A's headers are likely to include headers from A's 4563 dependencies. Those dependencies may have public_configs that apply flags, 4564 defines, and include paths that make those headers work properly. 4565 4566 With allow_circular_includes_from, B can include A's headers, and 4567 transitively from A's dependencies, without having the dependencies that 4568 would bring in the public_configs those headers need. The result may be 4569 errors or inconsistent builds. 4570 4571 So when you use allow_circular_includes_from, make sure that any compiler 4572 settings, flags, and include directories are the same between both targets 4573 (consider putting such things in a shared config they can both reference). 4574 Make sure the dependencies are also the same (you might consider a group to 4575 collect such dependencies they both depend on). 4576``` 4577 4578#### **Example** 4579 4580``` 4581 source_set("a") { 4582 deps = [ ":b", ":a_b_shared_deps" ] 4583 allow_circular_includes_from = [ ":b" ] 4584 ... 4585 } 4586 4587 source_set("b") { 4588 deps = [ ":a_b_shared_deps" ] 4589 # Sources here can include headers from a despite lack of deps. 4590 ... 4591 } 4592 4593 group("a_b_shared_deps") { 4594 public_deps = [ ":c" ] 4595 } 4596``` 4597### <a name="var_arflags"></a>**arflags**: Arguments passed to static_library archiver. 4598 4599``` 4600 A list of flags passed to the archive/lib command that creates static 4601 libraries. 4602 4603 arflags are NOT pushed to dependents, so applying arflags to source sets or 4604 any other target type will be a no-op. As with ldflags, you could put the 4605 arflags in a config and set that as a public or "all dependent" config, but 4606 that will likely not be what you want. If you have a chain of static 4607 libraries dependent on each other, this can cause the flags to propagate up 4608 to other static libraries. Due to the nature of how arflags are typically 4609 used, you will normally want to apply them directly on static_library targets 4610 themselves. 4611``` 4612 4613#### **Ordering of flags and values** 4614 4615``` 4616 1. Those set on the current target (not in a config). 4617 2. Those set on the "configs" on the target in order that the 4618 configs appear in the list. 4619 3. Those set on the "all_dependent_configs" on the target in order 4620 that the configs appear in the list. 4621 4. Those set on the "public_configs" on the target in order that 4622 those configs appear in the list. 4623 5. all_dependent_configs pulled from dependencies, in the order of 4624 the "deps" list. This is done recursively. If a config appears 4625 more than once, only the first occurence will be used. 4626 6. public_configs pulled from dependencies, in the order of the 4627 "deps" list. If a dependency is public, they will be applied 4628 recursively. 4629``` 4630### <a name="var_args"></a>**args**: (target variable) Arguments passed to an action. 4631 4632``` 4633 For action and action_foreach targets, args is the list of arguments to pass 4634 to the script. Typically you would use source expansion (see "gn help 4635 source_expansion") to insert the source file names. 4636 4637 See also "gn help action" and "gn help action_foreach". 4638``` 4639### <a name="var_asmflags"></a>**asmflags**: Flags passed to the assembler. 4640 4641``` 4642 A list of strings. 4643 4644 "asmflags" are passed to any invocation of a tool that takes an .asm or .S 4645 file as input. 4646``` 4647 4648#### **Ordering of flags and values** 4649 4650``` 4651 1. Those set on the current target (not in a config). 4652 2. Those set on the "configs" on the target in order that the 4653 configs appear in the list. 4654 3. Those set on the "all_dependent_configs" on the target in order 4655 that the configs appear in the list. 4656 4. Those set on the "public_configs" on the target in order that 4657 those configs appear in the list. 4658 5. all_dependent_configs pulled from dependencies, in the order of 4659 the "deps" list. This is done recursively. If a config appears 4660 more than once, only the first occurence will be used. 4661 6. public_configs pulled from dependencies, in the order of the 4662 "deps" list. If a dependency is public, they will be applied 4663 recursively. 4664``` 4665### <a name="var_assert_no_deps"></a>**assert_no_deps**: Ensure no deps on these targets. 4666 4667``` 4668 A list of label patterns. 4669 4670 This list is a list of patterns that must not match any of the transitive 4671 dependencies of the target. These include all public, private, and data 4672 dependencies, and cross shared library boundaries. This allows you to express 4673 that undesirable code isn't accidentally added to downstream dependencies in 4674 a way that might otherwise be difficult to notice. 4675 4676 Checking does not cross executable boundaries. If a target depends on an 4677 executable, it's assumed that the executable is a tool that is producing part 4678 of the build rather than something that is linked and distributed. This 4679 allows assert_no_deps to express what is distributed in the final target 4680 rather than depend on the internal build steps (which may include 4681 non-distributable code). 4682 4683 See "gn help label_pattern" for the format of the entries in the list. These 4684 patterns allow blacklisting individual targets or whole directory 4685 hierarchies. 4686 4687 Sometimes it is desirable to enforce that many targets have no dependencies 4688 on a target or set of targets. One efficient way to express this is to create 4689 a group with the assert_no_deps rule on it, and make that group depend on all 4690 targets you want to apply that assertion to. 4691``` 4692 4693#### **Example** 4694 4695``` 4696 executable("doom_melon") { 4697 deps = [ "//foo:bar" ] 4698 ... 4699 assert_no_deps = [ 4700 "//evil/*", # Don't link any code from the evil directory. 4701 "//foo:test_support", # This target is also disallowed. 4702 ] 4703 } 4704``` 4705### <a name="var_bridge_header"></a>**bridge_header**: [string] Path to C/Objective-C compatibility header. 4706 4707``` 4708 Valid for binary targets that contain Swift sources. 4709 4710 Path to an header that includes C/Objective-C functions and types that 4711 needs to be made available to the Swift module. 4712``` 4713### <a name="var_bundle_contents_dir"></a>**bundle_contents_dir**: Expansion of {{bundle_contents_dir}} in 4714``` 4715 create_bundle. 4716 4717 A string corresponding to a path in $root_build_dir. 4718 4719 This string is used by the "create_bundle" target to expand the 4720 {{bundle_contents_dir}} of the "bundle_data" target it depends on. This must 4721 correspond to a path under "bundle_root_dir". 4722 4723 See "gn help bundle_root_dir" for examples. 4724``` 4725### <a name="var_bundle_deps_filter"></a>**bundle_deps_filter**: [label list] A list of labels that are filtered out. 4726 4727``` 4728 A list of target labels. 4729 4730 This list contains target label patterns that should be filtered out when 4731 creating the bundle. Any target matching one of those label will be removed 4732 from the dependencies of the create_bundle target. 4733 4734 This is mostly useful when creating application extension bundle as the 4735 application extension has access to runtime resources from the application 4736 bundle and thus do not require a second copy. 4737 4738 See "gn help create_bundle" for more information. 4739``` 4740 4741#### **Example** 4742 4743``` 4744 create_bundle("today_extension") { 4745 deps = [ 4746 "//base" 4747 ] 4748 bundle_root_dir = "$root_out_dir/today_extension.appex" 4749 bundle_deps_filter = [ 4750 # The extension uses //base but does not use any function calling into 4751 # third_party/icu and thus does not need the icudtl.dat file. 4752 "//third_party/icu:icudata", 4753 ] 4754 } 4755``` 4756### <a name="var_bundle_executable_dir"></a>**bundle_executable_dir** 4757 4758``` 4759 bundle_executable_dir: Expansion of {{bundle_executable_dir}} in 4760 create_bundle. 4761 4762 A string corresponding to a path in $root_build_dir. 4763 4764 This string is used by the "create_bundle" target to expand the 4765 {{bundle_executable_dir}} of the "bundle_data" target it depends on. This 4766 must correspond to a path under "bundle_root_dir". 4767 4768 See "gn help bundle_root_dir" for examples. 4769``` 4770### <a name="var_bundle_resources_dir"></a>**bundle_resources_dir** 4771 4772``` 4773 bundle_resources_dir: Expansion of {{bundle_resources_dir}} in 4774 create_bundle. 4775 4776 A string corresponding to a path in $root_build_dir. 4777 4778 This string is used by the "create_bundle" target to expand the 4779 {{bundle_resources_dir}} of the "bundle_data" target it depends on. This must 4780 correspond to a path under "bundle_root_dir". 4781 4782 See "gn help bundle_root_dir" for examples. 4783``` 4784### <a name="var_bundle_root_dir"></a>**bundle_root_dir**: Expansion of {{bundle_root_dir}} in create_bundle. 4785 4786``` 4787 A string corresponding to a path in root_build_dir. 4788 4789 This string is used by the "create_bundle" target to expand the 4790 {{bundle_root_dir}} of the "bundle_data" target it depends on. This must 4791 correspond to a path under root_build_dir. 4792``` 4793 4794#### **Example** 4795 4796``` 4797 bundle_data("info_plist") { 4798 sources = [ "Info.plist" ] 4799 outputs = [ "{{bundle_contents_dir}}/Info.plist" ] 4800 } 4801 4802 create_bundle("doom_melon.app") { 4803 deps = [ ":info_plist" ] 4804 bundle_root_dir = "${root_build_dir}/doom_melon.app" 4805 bundle_contents_dir = "${bundle_root_dir}/Contents" 4806 bundle_resources_dir = "${bundle_contents_dir}/Resources" 4807 bundle_executable_dir = "${bundle_contents_dir}/MacOS" 4808 } 4809``` 4810### <a name="var_cflags"></a>**cflags***: Flags passed to the C compiler. 4811 4812``` 4813 A list of strings. 4814 4815 "cflags" are passed to all invocations of the C, C++, Objective C, and 4816 Objective C++ compilers. 4817 4818 To target one of these variants individually, use "cflags_c", "cflags_cc", 4819 "cflags_objc", and "cflags_objcc", respectively. These variant-specific 4820 versions of cflags* will be appended on the compiler command line after 4821 "cflags". 4822 4823 See also "asmflags" for flags for assembly-language files and "swiftflags" 4824 for swift files. 4825``` 4826 4827#### **Ordering of flags and values** 4828 4829``` 4830 1. Those set on the current target (not in a config). 4831 2. Those set on the "configs" on the target in order that the 4832 configs appear in the list. 4833 3. Those set on the "all_dependent_configs" on the target in order 4834 that the configs appear in the list. 4835 4. Those set on the "public_configs" on the target in order that 4836 those configs appear in the list. 4837 5. all_dependent_configs pulled from dependencies, in the order of 4838 the "deps" list. This is done recursively. If a config appears 4839 more than once, only the first occurence will be used. 4840 6. public_configs pulled from dependencies, in the order of the 4841 "deps" list. If a dependency is public, they will be applied 4842 recursively. 4843``` 4844### <a name="var_cflags_c"></a>**cflags***: Flags passed to the C compiler. 4845 4846``` 4847 A list of strings. 4848 4849 "cflags" are passed to all invocations of the C, C++, Objective C, and 4850 Objective C++ compilers. 4851 4852 To target one of these variants individually, use "cflags_c", "cflags_cc", 4853 "cflags_objc", and "cflags_objcc", respectively. These variant-specific 4854 versions of cflags* will be appended on the compiler command line after 4855 "cflags". 4856 4857 See also "asmflags" for flags for assembly-language files and "swiftflags" 4858 for swift files. 4859``` 4860 4861#### **Ordering of flags and values** 4862 4863``` 4864 1. Those set on the current target (not in a config). 4865 2. Those set on the "configs" on the target in order that the 4866 configs appear in the list. 4867 3. Those set on the "all_dependent_configs" on the target in order 4868 that the configs appear in the list. 4869 4. Those set on the "public_configs" on the target in order that 4870 those configs appear in the list. 4871 5. all_dependent_configs pulled from dependencies, in the order of 4872 the "deps" list. This is done recursively. If a config appears 4873 more than once, only the first occurence will be used. 4874 6. public_configs pulled from dependencies, in the order of the 4875 "deps" list. If a dependency is public, they will be applied 4876 recursively. 4877``` 4878### <a name="var_cflags_cc"></a>**cflags***: Flags passed to the C compiler. 4879 4880``` 4881 A list of strings. 4882 4883 "cflags" are passed to all invocations of the C, C++, Objective C, and 4884 Objective C++ compilers. 4885 4886 To target one of these variants individually, use "cflags_c", "cflags_cc", 4887 "cflags_objc", and "cflags_objcc", respectively. These variant-specific 4888 versions of cflags* will be appended on the compiler command line after 4889 "cflags". 4890 4891 See also "asmflags" for flags for assembly-language files and "swiftflags" 4892 for swift files. 4893``` 4894 4895#### **Ordering of flags and values** 4896 4897``` 4898 1. Those set on the current target (not in a config). 4899 2. Those set on the "configs" on the target in order that the 4900 configs appear in the list. 4901 3. Those set on the "all_dependent_configs" on the target in order 4902 that the configs appear in the list. 4903 4. Those set on the "public_configs" on the target in order that 4904 those configs appear in the list. 4905 5. all_dependent_configs pulled from dependencies, in the order of 4906 the "deps" list. This is done recursively. If a config appears 4907 more than once, only the first occurence will be used. 4908 6. public_configs pulled from dependencies, in the order of the 4909 "deps" list. If a dependency is public, they will be applied 4910 recursively. 4911``` 4912### <a name="var_cflags_objc"></a>**cflags***: Flags passed to the C compiler. 4913 4914``` 4915 A list of strings. 4916 4917 "cflags" are passed to all invocations of the C, C++, Objective C, and 4918 Objective C++ compilers. 4919 4920 To target one of these variants individually, use "cflags_c", "cflags_cc", 4921 "cflags_objc", and "cflags_objcc", respectively. These variant-specific 4922 versions of cflags* will be appended on the compiler command line after 4923 "cflags". 4924 4925 See also "asmflags" for flags for assembly-language files and "swiftflags" 4926 for swift files. 4927``` 4928 4929#### **Ordering of flags and values** 4930 4931``` 4932 1. Those set on the current target (not in a config). 4933 2. Those set on the "configs" on the target in order that the 4934 configs appear in the list. 4935 3. Those set on the "all_dependent_configs" on the target in order 4936 that the configs appear in the list. 4937 4. Those set on the "public_configs" on the target in order that 4938 those configs appear in the list. 4939 5. all_dependent_configs pulled from dependencies, in the order of 4940 the "deps" list. This is done recursively. If a config appears 4941 more than once, only the first occurence will be used. 4942 6. public_configs pulled from dependencies, in the order of the 4943 "deps" list. If a dependency is public, they will be applied 4944 recursively. 4945``` 4946### <a name="var_cflags_objcc"></a>**cflags***: Flags passed to the C compiler. 4947 4948``` 4949 A list of strings. 4950 4951 "cflags" are passed to all invocations of the C, C++, Objective C, and 4952 Objective C++ compilers. 4953 4954 To target one of these variants individually, use "cflags_c", "cflags_cc", 4955 "cflags_objc", and "cflags_objcc", respectively. These variant-specific 4956 versions of cflags* will be appended on the compiler command line after 4957 "cflags". 4958 4959 See also "asmflags" for flags for assembly-language files and "swiftflags" 4960 for swift files. 4961``` 4962 4963#### **Ordering of flags and values** 4964 4965``` 4966 1. Those set on the current target (not in a config). 4967 2. Those set on the "configs" on the target in order that the 4968 configs appear in the list. 4969 3. Those set on the "all_dependent_configs" on the target in order 4970 that the configs appear in the list. 4971 4. Those set on the "public_configs" on the target in order that 4972 those configs appear in the list. 4973 5. all_dependent_configs pulled from dependencies, in the order of 4974 the "deps" list. This is done recursively. If a config appears 4975 more than once, only the first occurence will be used. 4976 6. public_configs pulled from dependencies, in the order of the 4977 "deps" list. If a dependency is public, they will be applied 4978 recursively. 4979``` 4980### <a name="var_check_includes"></a>**check_includes**: [boolean] Controls whether a target's files are checked. 4981 4982``` 4983 When true (the default), the "gn check" command (as well as "gn gen" with the 4984 --check flag) will check this target's sources and headers for proper 4985 dependencies. 4986 4987 When false, the files in this target will be skipped by default. This does 4988 not affect other targets that depend on the current target, it just skips 4989 checking the includes of the current target's files. 4990 4991 If there are a few conditionally included headers that trip up checking, you 4992 can exclude headers individually by annotating them with "nogncheck" (see "gn 4993 help nogncheck"). 4994 4995 The topic "gn help check" has general information on how checking works and 4996 advice on how to pass a check in problematic cases. 4997``` 4998 4999#### **Example** 5000 5001``` 5002 source_set("busted_includes") { 5003 # This target's includes are messed up, exclude it from checking. 5004 check_includes = false 5005 ... 5006 } 5007``` 5008### <a name="var_code_signing_args"></a>**code_signing_args**: [string list] Arguments passed to code signing script. 5009 5010``` 5011 For create_bundle targets, code_signing_args is the list of arguments to pass 5012 to the code signing script. Typically you would use source expansion (see "gn 5013 help source_expansion") to insert the source file names. 5014 5015 See also "gn help create_bundle". 5016``` 5017### <a name="var_code_signing_outputs"></a>**code_signing_outputs**: [file list] Output files for code signing step. 5018 5019``` 5020 Outputs from the code signing step of a create_bundle target. Must refer to 5021 files in the build directory. 5022 5023 See also "gn help create_bundle". 5024``` 5025### <a name="var_code_signing_script"></a>**code_signing_script**: [file name] Script for code signing." 5026 5027``` 5028 An absolute or buildfile-relative file name of a Python script to run for a 5029 create_bundle target to perform code signing step. 5030 5031 See also "gn help create_bundle". 5032``` 5033### <a name="var_code_signing_sources"></a>**code_signing_sources**: [file list] Sources for code signing step. 5034 5035``` 5036 A list of files used as input for code signing script step of a create_bundle 5037 target. Non-absolute paths will be resolved relative to the current build 5038 file. 5039 5040 See also "gn help create_bundle". 5041``` 5042### <a name="var_complete_static_lib"></a>**complete_static_lib**: [boolean] Links all deps into a static library. 5043 5044``` 5045 A static library normally doesn't include code from dependencies, but instead 5046 forwards the static libraries and source sets in its deps up the dependency 5047 chain until a linkable target (an executable or shared library) is reached. 5048 The final linkable target only links each static library once, even if it 5049 appears more than once in its dependency graph. 5050 5051 In some cases the static library might be the final desired output. For 5052 example, you may be producing a static library for distribution to third 5053 parties. In this case, the static library should include code for all 5054 dependencies in one complete package. However, complete static libraries 5055 themselves are never linked into other complete static libraries. All 5056 complete static libraries are for distribution and linking them in would 5057 cause code duplication in this case. If the static library is not for 5058 distribution, it should not be complete. 5059 5060 GN treats non-complete static libraries as source sets when they are linked 5061 into complete static libraries. This is done because some tools like AR do 5062 not handle dependent static libraries properly. This makes it easier to write 5063 "alink" rules. 5064 5065 In rare cases it makes sense to list a header in more than one target if it 5066 could be considered conceptually a member of both. libraries. 5067``` 5068 5069#### **Example** 5070 5071``` 5072 static_library("foo") { 5073 complete_static_lib = true 5074 deps = [ "bar" ] 5075 } 5076``` 5077### <a name="var_configs"></a>**configs**: Configs applying to this target or config. 5078 5079``` 5080 A list of config labels. 5081``` 5082 5083#### **Configs on a target** 5084 5085``` 5086 When used on a target, the include_dirs, defines, etc. in each config are 5087 appended in the order they appear to the compile command for each file in the 5088 target. They will appear after the include_dirs, defines, etc. that the 5089 target sets directly. 5090 5091 Since configs apply after the values set on a target, directly setting a 5092 compiler flag will prepend it to the command line. If you want to append a 5093 flag instead, you can put that flag in a one-off config and append that 5094 config to the target's configs list. 5095 5096 The build configuration script will generally set up the default configs 5097 applying to a given target type (see "set_defaults"). When a target is being 5098 defined, it can add to or remove from this list. 5099``` 5100 5101#### **Configs on a config** 5102 5103``` 5104 It is possible to create composite configs by specifying configs on a config. 5105 One might do this to forward values, or to factor out blocks of settings from 5106 very large configs into more manageable named chunks. 5107 5108 In this case, the composite config is expanded to be the concatenation of its 5109 own values, and in order, the values from its sub-configs *before* anything 5110 else happens. This has some ramifications: 5111 5112 - A target has no visibility into a config's sub-configs. Target code only 5113 sees the name of the composite config. It can't remove sub-configs or opt 5114 in to only parts of it. The composite config may not even be defined 5115 before the target is. 5116 5117 - You can get duplication of values if a config is listed twice, say, on a 5118 target and in a sub-config that also applies. In other cases, the configs 5119 applying to a target are de-duped. It's expected that if a config is 5120 listed as a sub-config that it is only used in that context. (Note that 5121 it's possible to fix this and de-dupe, but it's not normally relevant and 5122 complicates the implementation.) 5123``` 5124 5125#### **Ordering of flags and values** 5126 5127``` 5128 1. Those set on the current target (not in a config). 5129 2. Those set on the "configs" on the target in order that the 5130 configs appear in the list. 5131 3. Those set on the "all_dependent_configs" on the target in order 5132 that the configs appear in the list. 5133 4. Those set on the "public_configs" on the target in order that 5134 those configs appear in the list. 5135 5. all_dependent_configs pulled from dependencies, in the order of 5136 the "deps" list. This is done recursively. If a config appears 5137 more than once, only the first occurence will be used. 5138 6. public_configs pulled from dependencies, in the order of the 5139 "deps" list. If a dependency is public, they will be applied 5140 recursively. 5141``` 5142 5143#### **Example** 5144 5145``` 5146 # Configs on a target. 5147 source_set("foo") { 5148 # Don't use the default RTTI config that BUILDCONFIG applied to us. 5149 configs -= [ "//build:no_rtti" ] 5150 5151 # Add some of our own settings. 5152 configs += [ ":mysettings" ] 5153 } 5154 5155 # Create a default_optimization config that forwards to one of a set of more 5156 # specialized configs depending on build flags. This pattern is useful 5157 # because it allows a target to opt in to either a default set, or a more 5158 # specific set, while avoid duplicating the settings in two places. 5159 config("super_optimization") { 5160 cflags = [ ... ] 5161 } 5162 config("default_optimization") { 5163 if (optimize_everything) { 5164 configs = [ ":super_optimization" ] 5165 } else { 5166 configs = [ ":no_optimization" ] 5167 } 5168 } 5169``` 5170### <a name="var_contents"></a>**contents**: Contents to write to file. 5171 5172``` 5173 The contents of the file for a generated_file target. 5174 See "gn help generated_file". 5175``` 5176### <a name="var_crate_name"></a>**crate_name**: [string] The name for the compiled crate. 5177 5178``` 5179 Valid for `rust_library` targets and `executable`, `static_library`, 5180 `shared_library`, and `source_set` targets that contain Rust sources. 5181 5182 If crate_name is not set, then this rule will use the target name. 5183``` 5184### <a name="var_crate_root"></a>**crate_root**: [string] The root source file for a binary or library. 5185 5186``` 5187 Valid for `rust_library` targets and `executable`, `static_library`, 5188 `shared_library`, and `source_set` targets that contain Rust sources. 5189 5190 This file is usually the `main.rs` or `lib.rs` for binaries and libraries, 5191 respectively. 5192 5193 If crate_root is not set, then this rule will look for a lib.rs file (or 5194 main.rs for executable) or a single file in sources, if sources contains 5195 only one file. 5196``` 5197### <a name="var_crate_type"></a>**crate_type**: [string] The type of linkage to use on a shared_library. 5198 5199``` 5200 Valid for `rust_library` targets and `executable`, `static_library`, 5201 `shared_library`, and `source_set` targets that contain Rust sources. 5202 5203 Options for this field are "cdylib", "staticlib", "proc-macro", and "dylib". 5204 This field sets the `crate-type` attribute for the `rustc` tool on static 5205 libraries, as well as the appropiate output extension in the 5206 `rust_output_extension` attribute. Since outputs must be explicit, the `lib` 5207 crate type (where the Rust compiler produces what it thinks is the 5208 appropriate library type) is not supported. 5209 5210 It should be noted that the "dylib" crate type in Rust is unstable in the set 5211 of symbols it exposes, and most usages today are potentially wrong and will 5212 be broken in the future. 5213 5214 Static libraries, rust libraries, and executables have this field set 5215 automatically. 5216``` 5217### <a name="var_data"></a>**data**: Runtime data file dependencies. 5218 5219``` 5220 Lists files or directories required to run the given target. These are 5221 typically data files or directories of data files. The paths are interpreted 5222 as being relative to the current build file. Since these are runtime 5223 dependencies, they do not affect which targets are built or when. To declare 5224 input files to a script, use "inputs". 5225 5226 Appearing in the "data" section does not imply any special handling such as 5227 copying them to the output directory. This is just used for declaring runtime 5228 dependencies. Runtime dependencies can be queried using the "runtime_deps" 5229 category of "gn desc" or written during build generation via 5230 "--runtime-deps-list-file". 5231 5232 GN doesn't require data files to exist at build-time. So actions that produce 5233 files that are in turn runtime dependencies can list those generated files 5234 both in the "outputs" list as well as the "data" list. 5235 5236 By convention, directories are listed with a trailing slash: 5237 data = [ "test/data/" ] 5238 However, no verification is done on these so GN doesn't enforce this. The 5239 paths are just rebased and passed along when requested. 5240 5241 Note: On iOS and macOS, create_bundle targets will not be recursed into when 5242 gathering data. See "gn help create_bundle" for details. 5243 5244 See "gn help runtime_deps" for how these are used. 5245``` 5246### <a name="var_data_deps"></a>**data_deps**: Non-linked dependencies. 5247 5248``` 5249 A list of target labels. 5250 5251 Specifies dependencies of a target that are not actually linked into the 5252 current target. Such dependencies will be built and will be available at 5253 runtime. 5254 5255 This is normally used for things like plugins or helper programs that a 5256 target needs at runtime. 5257 5258 Note: On iOS and macOS, create_bundle targets will not be recursed into when 5259 gathering data_deps. See "gn help create_bundle" for details. 5260 5261 See also "gn help deps" and "gn help data". 5262``` 5263 5264#### **Example** 5265 5266``` 5267 executable("foo") { 5268 deps = [ "//base" ] 5269 data_deps = [ "//plugins:my_runtime_plugin" ] 5270 } 5271``` 5272### <a name="var_data_keys"></a>**data_keys**: Keys from which to collect metadata. 5273 5274``` 5275 These keys are used to identify metadata to collect. If a walked target 5276 defines this key in its metadata, its value will be appended to the resulting 5277 collection. 5278 5279 See "gn help generated_file". 5280``` 5281### <a name="var_defines"></a>**defines**: C preprocessor defines. 5282 5283``` 5284 A list of strings 5285 5286 These strings will be passed to the C/C++ compiler as #defines. The strings 5287 may or may not include an "=" to assign a value. 5288``` 5289 5290#### **Ordering of flags and values** 5291 5292``` 5293 1. Those set on the current target (not in a config). 5294 2. Those set on the "configs" on the target in order that the 5295 configs appear in the list. 5296 3. Those set on the "all_dependent_configs" on the target in order 5297 that the configs appear in the list. 5298 4. Those set on the "public_configs" on the target in order that 5299 those configs appear in the list. 5300 5. all_dependent_configs pulled from dependencies, in the order of 5301 the "deps" list. This is done recursively. If a config appears 5302 more than once, only the first occurence will be used. 5303 6. public_configs pulled from dependencies, in the order of the 5304 "deps" list. If a dependency is public, they will be applied 5305 recursively. 5306``` 5307 5308#### **Example** 5309 5310``` 5311 defines = [ "AWESOME_FEATURE", "LOG_LEVEL=3" ] 5312``` 5313### <a name="var_depfile"></a>**depfile**: [string] File name for input dependencies for actions. 5314 5315``` 5316 If nonempty, this string specifies that the current action or action_foreach 5317 target will generate the given ".d" file containing the dependencies of the 5318 input. Empty or unset means that the script doesn't generate the files. 5319 5320 A depfile should be used only when a target depends on files that are not 5321 already specified by a target's inputs and sources. Likewise, depfiles should 5322 specify only those dependencies not already included in sources or inputs. 5323 5324 The .d file should go in the target output directory. If you have more than 5325 one source file that the script is being run over, you can use the output 5326 file expansions described in "gn help action_foreach" to name the .d file 5327 according to the input." 5328 5329 The format is that of a Makefile and all paths must be relative to the root 5330 build directory. Only one output may be listed and it must match the first 5331 output of the action. 5332 5333 Although depfiles are created by an action, they should not be listed in the 5334 action's "outputs" unless another target will use the file as an input. 5335``` 5336 5337#### **Example** 5338 5339``` 5340 action_foreach("myscript_target") { 5341 script = "myscript.py" 5342 sources = [ ... ] 5343 5344 # Locate the depfile in the output directory named like the 5345 # inputs but with a ".d" appended. 5346 depfile = "$relative_target_output_dir/{{source_name}}.d" 5347 5348 # Say our script uses "-o <d file>" to indicate the depfile. 5349 args = [ "{{source}}", "-o", depfile ] 5350 } 5351``` 5352### <a name="var_deps"></a>**deps**: Private linked dependencies. 5353 5354``` 5355 A list of target labels. 5356 5357 Specifies private dependencies of a target. Private dependencies are 5358 propagated up the dependency tree and linked to dependent targets, but do not 5359 grant the ability to include headers from the dependency. Public configs are 5360 not forwarded. 5361``` 5362 5363#### **Details of dependency propagation** 5364 5365``` 5366 Source sets, shared libraries, and non-complete static libraries will be 5367 propagated up the dependency tree across groups, non-complete static 5368 libraries and source sets. 5369 5370 Executables, shared libraries, and complete static libraries will link all 5371 propagated targets and stop propagation. Actions and copy steps also stop 5372 propagation, allowing them to take a library as an input but not force 5373 dependents to link to it. 5374 5375 Propagation of all_dependent_configs and public_configs happens independently 5376 of target type. all_dependent_configs are always propagated across all types 5377 of targets, and public_configs are always propagated across public deps of 5378 all types of targets. 5379 5380 Data dependencies are propagated differently. See "gn help data_deps" and 5381 "gn help runtime_deps". 5382 5383 See also "public_deps". 5384``` 5385### <a name="var_externs"></a>**externs**: [scope] Set of Rust crate-dependency pairs. 5386 5387``` 5388 A list, each value being a scope indicating a pair of crate name and the path 5389 to the Rust library. 5390 5391 These libraries will be passed as `--extern crate_name=path` to compiler 5392 invocation containing the current target. 5393``` 5394 5395#### **Examples** 5396 5397``` 5398 executable("foo") { 5399 sources = [ "main.rs" ] 5400 externs = [{ 5401 crate_name = "bar", 5402 path = "path/to/bar.rlib" 5403 }] 5404 } 5405 5406 This target would compile the `foo` crate with the following `extern` flag: 5407 `--extern bar=path/to/bar.rlib`. 5408``` 5409### <a name="var_framework_dirs"></a>**framework_dirs**: [directory list] Additional framework search directories. 5410 5411``` 5412 A list of source directories. 5413 5414 The directories in this list will be added to the framework search path for 5415 the files in the affected target. 5416``` 5417 5418#### **Ordering of flags and values** 5419 5420``` 5421 1. Those set on the current target (not in a config). 5422 2. Those set on the "configs" on the target in order that the 5423 configs appear in the list. 5424 3. Those set on the "all_dependent_configs" on the target in order 5425 that the configs appear in the list. 5426 4. Those set on the "public_configs" on the target in order that 5427 those configs appear in the list. 5428 5. all_dependent_configs pulled from dependencies, in the order of 5429 the "deps" list. This is done recursively. If a config appears 5430 more than once, only the first occurence will be used. 5431 6. public_configs pulled from dependencies, in the order of the 5432 "deps" list. If a dependency is public, they will be applied 5433 recursively. 5434``` 5435 5436#### **Example** 5437 5438``` 5439 framework_dirs = [ "src/include", "//third_party/foo" ] 5440``` 5441### <a name="var_frameworks"></a>**frameworks**: [name list] Name of frameworks that must be linked. 5442 5443``` 5444 A list of framework names. 5445 5446 The frameworks named in that list will be linked with any dynamic link 5447 type target. 5448``` 5449 5450#### **Ordering of flags and values** 5451 5452``` 5453 1. Those set on the current target (not in a config). 5454 2. Those set on the "configs" on the target in order that the 5455 configs appear in the list. 5456 3. Those set on the "all_dependent_configs" on the target in order 5457 that the configs appear in the list. 5458 4. Those set on the "public_configs" on the target in order that 5459 those configs appear in the list. 5460 5. all_dependent_configs pulled from dependencies, in the order of 5461 the "deps" list. This is done recursively. If a config appears 5462 more than once, only the first occurence will be used. 5463 6. public_configs pulled from dependencies, in the order of the 5464 "deps" list. If a dependency is public, they will be applied 5465 recursively. 5466``` 5467 5468#### **Example** 5469 5470``` 5471 frameworks = [ "Foundation.framework", "Foo.framework" ] 5472``` 5473### <a name="var_friend"></a>**friend**: Allow targets to include private headers. 5474 5475``` 5476 A list of label patterns (see "gn help label_pattern") that allow dependent 5477 targets to include private headers. Applies to all binary targets. 5478 5479 Normally if a target lists headers in the "public" list (see "gn help 5480 public"), other headers are implicitly marked as private. Private headers 5481 can not be included by other targets, even with a public dependency path. 5482 The "gn check" function performs this validation. 5483 5484 A friend declaration allows one or more targets to include private headers. 5485 This is useful for things like unit tests that are closely associated with a 5486 target and require internal knowledge without opening up all headers to be 5487 included by all dependents. 5488 5489 A friend target does not allow that target to include headers when no 5490 dependency exists. A public dependency path must still exist between two 5491 targets to include any headers from a destination target. The friend 5492 annotation merely allows the use of headers that would otherwise be 5493 prohibited because they are private. 5494 5495 The friend annotation is matched only against the target containing the file 5496 with the include directive. Friend annotations are not propagated across 5497 public or private dependencies. Friend annotations do not affect visibility. 5498``` 5499 5500#### **Example** 5501 5502``` 5503 static_library("lib") { 5504 # This target can include our private headers. 5505 friend = [ ":unit_tests" ] 5506 5507 public = [ 5508 "public_api.h", # Normal public API for dependent targets. 5509 ] 5510 5511 # Private API and sources. 5512 sources = [ 5513 "a_source_file.cc", 5514 5515 # Normal targets that depend on this one won't be able to include this 5516 # because this target defines a list of "public" headers. Without the 5517 # "public" list, all headers are implicitly public. 5518 "private_api.h", 5519 ] 5520 } 5521 5522 executable("unit_tests") { 5523 sources = [ 5524 # This can include "private_api.h" from the :lib target because it 5525 # depends on that target and because of the friend annotation. 5526 "my_test.cc", 5527 ] 5528 5529 deps = [ 5530 ":lib", # Required for the include to be allowed. 5531 ] 5532 } 5533``` 5534### <a name="var_include_dirs"></a>**include_dirs**: Additional include directories. 5535 5536``` 5537 A list of source directories. 5538 5539 The directories in this list will be added to the include path for the files 5540 in the affected target. 5541``` 5542 5543#### **Ordering of flags and values** 5544 5545``` 5546 1. Those set on the current target (not in a config). 5547 2. Those set on the "configs" on the target in order that the 5548 configs appear in the list. 5549 3. Those set on the "all_dependent_configs" on the target in order 5550 that the configs appear in the list. 5551 4. Those set on the "public_configs" on the target in order that 5552 those configs appear in the list. 5553 5. all_dependent_configs pulled from dependencies, in the order of 5554 the "deps" list. This is done recursively. If a config appears 5555 more than once, only the first occurence will be used. 5556 6. public_configs pulled from dependencies, in the order of the 5557 "deps" list. If a dependency is public, they will be applied 5558 recursively. 5559``` 5560 5561#### **Example** 5562 5563``` 5564 include_dirs = [ "src/include", "//third_party/foo" ] 5565``` 5566### <a name="var_inputs"></a>**inputs**: Additional compile-time dependencies. 5567 5568``` 5569 Inputs are compile-time dependencies of the current target. This means that 5570 all inputs must be available before compiling any of the sources or executing 5571 any actions. 5572 5573 Inputs are typically only used for action and action_foreach targets. 5574``` 5575 5576#### **Inputs for actions** 5577 5578``` 5579 For action and action_foreach targets, inputs should be the inputs to script 5580 that don't vary. These should be all .py files that the script uses via 5581 imports (the main script itself will be an implicit dependency of the action 5582 so need not be listed). 5583 5584 For action targets, inputs and sources are treated the same, but from a style 5585 perspective, it's recommended to follow the same rule as action_foreach and 5586 put helper files in the inputs, and the data used by the script (if any) in 5587 sources. 5588 5589 Note that another way to declare input dependencies from an action is to have 5590 the action write a depfile (see "gn help depfile"). This allows the script to 5591 dynamically write input dependencies, that might not be known until actually 5592 executing the script. This is more efficient than doing processing while 5593 running GN to determine the inputs, and is easier to keep in-sync than 5594 hardcoding the list. 5595``` 5596 5597#### **Script input gotchas** 5598 5599``` 5600 It may be tempting to write a script that enumerates all files in a directory 5601 as inputs. Don't do this! Even if you specify all the files in the inputs or 5602 sources in the GN target (or worse, enumerate the files in an exec_script 5603 call when running GN, which will be slow), the dependencies will be broken. 5604 5605 The problem happens if a file is ever removed because the inputs are not 5606 listed on the command line to the script. Because the script hasn't changed 5607 and all inputs are up to date, the script will not re-run and you will get a 5608 stale build. Instead, either list all inputs on the command line to the 5609 script, or if there are many, create a separate list file that the script 5610 reads. As long as this file is listed in the inputs, the build will detect 5611 when it has changed in any way and the action will re-run. 5612``` 5613 5614#### **Inputs for binary targets** 5615 5616``` 5617 Any input dependencies will be resolved before compiling any sources or 5618 linking the target. Normally, all actions that a target depends on will be run 5619 before any files in a target are compiled. So if you depend on generated 5620 headers, you do not typically need to list them in the inputs section. 5621 5622 Inputs for binary targets will be treated as implicit dependencies, meaning 5623 that changes in any of the inputs will force all sources in the target to be 5624 recompiled. If an input only applies to a subset of source files, you may 5625 want to split those into a separate target to avoid unnecessary recompiles. 5626``` 5627 5628#### **Example** 5629 5630``` 5631 action("myscript") { 5632 script = "domything.py" 5633 inputs = [ "input.data" ] 5634 } 5635``` 5636### <a name="var_ldflags"></a>**ldflags**: Flags passed to the linker. 5637 5638``` 5639 A list of strings. 5640 5641 These flags are passed on the command-line to the linker and generally 5642 specify various linking options. Most targets will not need these and will 5643 use "libs" and "lib_dirs" instead. 5644 5645 ldflags are NOT pushed to dependents, so applying ldflags to source sets or 5646 static libraries will be a no-op. If you want to apply ldflags to dependent 5647 targets, put them in a config and set it in the all_dependent_configs or 5648 public_configs. 5649``` 5650 5651#### **Ordering of flags and values** 5652 5653``` 5654 1. Those set on the current target (not in a config). 5655 2. Those set on the "configs" on the target in order that the 5656 configs appear in the list. 5657 3. Those set on the "all_dependent_configs" on the target in order 5658 that the configs appear in the list. 5659 4. Those set on the "public_configs" on the target in order that 5660 those configs appear in the list. 5661 5. all_dependent_configs pulled from dependencies, in the order of 5662 the "deps" list. This is done recursively. If a config appears 5663 more than once, only the first occurence will be used. 5664 6. public_configs pulled from dependencies, in the order of the 5665 "deps" list. If a dependency is public, they will be applied 5666 recursively. 5667``` 5668### <a name="var_lib_dirs"></a>**lib_dirs**: Additional library directories. 5669 5670``` 5671 A list of directories. 5672 5673 Specifies additional directories passed to the linker for searching for the 5674 required libraries. If an item is not an absolute path, it will be treated as 5675 being relative to the current build file. 5676 5677 libs and lib_dirs work differently than other flags in two respects. 5678 First, they are inherited across static library boundaries until a 5679 shared library or executable target is reached. Second, they are 5680 uniquified so each one is only passed once (the first instance of it 5681 will be the one used). 5682``` 5683 5684#### **Ordering of flags and values** 5685 5686``` 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 5689 configs appear in the list. 5690 3. Those set on the "all_dependent_configs" on the target in order 5691 that the configs appear in the list. 5692 4. Those set on the "public_configs" on the target in order that 5693 those configs appear in the list. 5694 5. all_dependent_configs pulled from dependencies, in the order of 5695 the "deps" list. This is done recursively. If a config appears 5696 more than once, only the first occurence will be used. 5697 6. public_configs pulled from dependencies, in the order of the 5698 "deps" list. If a dependency is public, they will be applied 5699 recursively. 5700 5701 For "libs" and "lib_dirs" only, the values propagated from 5702 dependencies (as described above) are applied last assuming they 5703 are not already in the list. 5704``` 5705 5706#### **Example** 5707 5708``` 5709 lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ] 5710``` 5711### <a name="var_libs"></a>**libs**: Additional libraries to link. 5712 5713``` 5714 A list of library names or library paths. 5715 5716 These libraries will be linked into the final binary (executable or shared 5717 library) containing the current target. 5718 5719 libs and lib_dirs work differently than other flags in two respects. 5720 First, they are inherited across static library boundaries until a 5721 shared library or executable target is reached. Second, they are 5722 uniquified so each one is only passed once (the first instance of it 5723 will be the one used). 5724``` 5725 5726#### **Types of libs** 5727 5728``` 5729 There are several different things that can be expressed in libs: 5730 5731 File paths 5732 Values containing '/' will be treated as references to files in the 5733 checkout. They will be rebased to be relative to the build directory and 5734 specified in the "libs" for linker tools. This facility should be used 5735 for libraries that are checked in to the version control. For libraries 5736 that are generated by the build, use normal GN deps to link them. 5737 5738 System libraries 5739 Values not containing '/' will be treated as system library names. These 5740 will be passed unmodified to the linker and prefixed with the 5741 "lib_switch" attribute of the linker tool. Generally you would set the 5742 "lib_dirs" so the given library is found. Your BUILD.gn file should not 5743 specify the switch (like "-l"): this will be encoded in the "lib_switch" 5744 of the tool. 5745``` 5746 5747#### **Ordering of flags and values** 5748 5749``` 5750 1. Those set on the current target (not in a config). 5751 2. Those set on the "configs" on the target in order that the 5752 configs appear in the list. 5753 3. Those set on the "all_dependent_configs" on the target in order 5754 that the configs appear in the list. 5755 4. Those set on the "public_configs" on the target in order that 5756 those configs appear in the list. 5757 5. all_dependent_configs pulled from dependencies, in the order of 5758 the "deps" list. This is done recursively. If a config appears 5759 more than once, only the first occurence will be used. 5760 6. public_configs pulled from dependencies, in the order of the 5761 "deps" list. If a dependency is public, they will be applied 5762 recursively. 5763 5764 For "libs" and "lib_dirs" only, the values propagated from 5765 dependencies (as described above) are applied last assuming they 5766 are not already in the list. 5767``` 5768 5769#### **Examples** 5770 5771``` 5772 On Windows: 5773 libs = [ "ctl3d.lib" ] 5774 5775 On Linux: 5776 libs = [ "ld" ] 5777``` 5778### <a name="var_metadata"></a>**metadata**: Metadata of this target. 5779 5780``` 5781 Metadata is a collection of keys and values relating to a particular target. 5782 Values must be lists, allowing for sane and predictable collection behavior. 5783 Generally, these keys will include three types of lists: lists of ordinary 5784 strings, lists of filenames intended to be rebased according to their 5785 particular source directory, and lists of target labels intended to be used 5786 as barriers to the walk. Verfication of these categories occurs at walk time, 5787 not creation time (since it is not clear until the walk which values are 5788 intended for which purpose). 5789``` 5790 5791#### **Example** 5792 5793``` 5794 group("doom_melon") { 5795 metadata = { 5796 # These keys are not built in to GN but are interpreted when consuming 5797 # metadata. 5798 my_barrier = [] 5799 my_files = [ "a.txt", "b.txt" ] 5800 } 5801 } 5802``` 5803### <a name="var_module_name"></a>**module_name**: [string] The name for the compiled module. 5804 5805``` 5806 Valid for binary targets that contain Swift sources. 5807 5808 If module_name is not set, then this rule will use the target name. 5809``` 5810### <a name="var_output_conversion"></a>**output_conversion**: Data format for generated_file targets. 5811 5812``` 5813 Controls how the "contents" of a generated_file target is formatted. 5814 See "gn help io_conversion". 5815``` 5816### <a name="var_output_dir"></a>**output_dir**: [directory] Directory to put output file in. 5817 5818``` 5819 For library and executable targets, overrides the directory for the final 5820 output. This must be in the root_build_dir or a child thereof. 5821 5822 This should generally be in the root_out_dir or a subdirectory thereof (the 5823 root_out_dir will be the same as the root_build_dir for the default 5824 toolchain, and will be a subdirectory for other toolchains). Not putting the 5825 output in a subdirectory of root_out_dir can result in collisions between 5826 different toolchains, so you will need to take steps to ensure that your 5827 target is only present in one toolchain. 5828 5829 Normally the toolchain specifies the output directory for libraries and 5830 executables (see "gn help tool"). You will have to consult that for the 5831 default location. The default location will be used if output_dir is 5832 undefined or empty. 5833``` 5834 5835#### **Example** 5836 5837``` 5838 shared_library("doom_melon") { 5839 output_dir = "$root_out_dir/plugin_libs" 5840 ... 5841 } 5842``` 5843### <a name="var_output_extension"></a>**output_extension**: Value to use for the output's file extension. 5844 5845``` 5846 Normally the file extension for a target is based on the target type and the 5847 operating system, but in rare cases you will need to override the name (for 5848 example to use "libfreetype.so.6" instead of libfreetype.so on Linux). 5849 5850 This value should not include a leading dot. If undefined, the default 5851 specified on the tool will be used. If set to the empty string, no output 5852 extension will be used. 5853 5854 The output_extension will be used to set the "{{output_extension}}" expansion 5855 which the linker tool will generally use to specify the output file name. See 5856 "gn help tool". 5857``` 5858 5859#### **Example** 5860 5861``` 5862 shared_library("freetype") { 5863 if (is_linux) { 5864 # Call the output "libfreetype.so.6" 5865 output_extension = "so.6" 5866 } 5867 ... 5868 } 5869 5870 # On Windows, generate a "mysettings.cpl" control panel applet. Control panel 5871 # applets are actually special shared libraries. 5872 if (is_win) { 5873 shared_library("mysettings") { 5874 output_extension = "cpl" 5875 ... 5876 } 5877 } 5878``` 5879### <a name="var_output_name"></a>**output_name**: Define a name for the output file other than the default. 5880 5881``` 5882 Normally the output name of a target will be based on the target name, so the 5883 target "//foo/bar:bar_unittests" will generate an output file such as 5884 "bar_unittests.exe" (using Windows as an example). 5885 5886 Sometimes you will want an alternate name to avoid collisions or if the 5887 internal name isn't appropriate for public distribution. 5888 5889 The output name should have no extension or prefixes, these will be added 5890 using the default system rules. For example, on Linux an output name of "foo" 5891 will produce a shared library "libfoo.so". There is no way to override the 5892 output prefix of a linker tool on a per- target basis. If you need more 5893 flexibility, create a copy target to produce the file you want. 5894 5895 This variable is valid for all binary output target types. 5896``` 5897 5898#### **Example** 5899 5900``` 5901 static_library("doom_melon") { 5902 output_name = "fluffy_bunny" 5903 } 5904``` 5905### <a name="var_output_prefix_override"></a>**output_prefix_override**: Don't use prefix for output name. 5906 5907``` 5908 A boolean that overrides the output prefix for a target. Defaults to false. 5909 5910 Some systems use prefixes for the names of the final target output file. The 5911 normal example is "libfoo.so" on Linux for a target named "foo". 5912 5913 The output prefix for a given target type is specified on the linker tool 5914 (see "gn help tool"). Sometimes this prefix is undesired. 5915 5916 See also "gn help output_extension". 5917``` 5918 5919#### **Example** 5920 5921``` 5922 shared_library("doom_melon") { 5923 # Normally this will produce "libdoom_melon.so" on Linux. Setting this flag 5924 # will produce "doom_melon.so". 5925 output_prefix_override = true 5926 ... 5927 } 5928``` 5929### <a name="var_outputs"></a>**outputs**: Output files for actions and copy targets. 5930 5931``` 5932 Outputs is valid for "copy", "action", and "action_foreach" target types and 5933 indicates the resulting files. Outputs must always refer to files in the 5934 build directory. 5935 5936 copy 5937 Copy targets should have exactly one entry in the outputs list. If there is 5938 exactly one source, this can be a literal file name or a source expansion. 5939 If there is more than one source, this must contain a source expansion to 5940 map a single input name to a single output name. See "gn help copy". 5941 5942 action_foreach 5943 Action_foreach targets must always use source expansions to map input files 5944 to output files. There can be more than one output, which means that each 5945 invocation of the script will produce a set of files (presumably based on 5946 the name of the input file). See "gn help action_foreach". 5947 5948 action 5949 Action targets (excluding action_foreach) must list literal output file(s) 5950 with no source expansions. See "gn help action". 5951``` 5952### <a name="var_partial_info_plist"></a>**partial_info_plist**: [filename] Path plist from asset catalog compiler. 5953 5954``` 5955 Valid for create_bundle target, corresponds to the path for the partial 5956 Info.plist created by the asset catalog compiler that needs to be merged 5957 with the application Info.plist (usually done by the code signing script). 5958 5959 The file will be generated regardless of whether the asset compiler has 5960 been invoked or not. See "gn help create_bundle". 5961``` 5962### <a name="var_pool"></a>**pool**: Label of the pool used by the action. 5963 5964``` 5965 A fully-qualified label representing the pool that will be used for the 5966 action. Pools are defined using the pool() {...} declaration. 5967``` 5968 5969#### **Example** 5970 5971``` 5972 action("action") { 5973 pool = "//build:custom_pool" 5974 ... 5975 } 5976``` 5977### <a name="var_precompiled_header"></a>**precompiled_header**: [string] Header file to precompile. 5978 5979``` 5980 Precompiled headers will be used when a target specifies this value, or a 5981 config applying to this target specifies this value. In addition, the tool 5982 corresponding to the source files must also specify precompiled headers (see 5983 "gn help tool"). The tool will also specify what type of precompiled headers 5984 to use, by setting precompiled_header_type to either "gcc" or "msvc". 5985 5986 The precompiled header/source variables can be specified on a target or a 5987 config, but must be the same for all configs applying to a given target since 5988 a target can only have one precompiled header. 5989 5990 If you use both C and C++ sources, the precompiled header and source file 5991 will be compiled once per language. You will want to make sure to wrap C++ 5992 includes in __cplusplus #ifdefs so the file will compile in C mode. 5993``` 5994 5995#### **GCC precompiled headers** 5996 5997``` 5998 When using GCC-style precompiled headers, "precompiled_source" contains the 5999 path of a .h file that is precompiled and then included by all source files 6000 in targets that set "precompiled_source". 6001 6002 The value of "precompiled_header" is not used with GCC-style precompiled 6003 headers. 6004``` 6005 6006#### **MSVC precompiled headers** 6007 6008``` 6009 When using MSVC-style precompiled headers, the "precompiled_header" value is 6010 a string corresponding to the header. This is NOT a path to a file that GN 6011 recognises, but rather the exact string that appears in quotes after 6012 an #include line in source code. The compiler will match this string against 6013 includes or forced includes (/FI). 6014 6015 MSVC also requires a source file to compile the header with. This must be 6016 specified by the "precompiled_source" value. In contrast to the header value, 6017 this IS a GN-style file name, and tells GN which source file to compile to 6018 make the .pch file used for subsequent compiles. 6019 6020 For example, if the toolchain specifies MSVC headers: 6021 6022 toolchain("vc_x64") { 6023 ... 6024 tool("cxx") { 6025 precompiled_header_type = "msvc" 6026 ... 6027 6028 You might make a config like this: 6029 6030 config("use_precompiled_headers") { 6031 precompiled_header = "build/precompile.h" 6032 precompiled_source = "//build/precompile.cc" 6033 6034 # Either your source files should #include "build/precompile.h" 6035 # first, or you can do this to force-include the header. 6036 cflags = [ "/FI$precompiled_header" ] 6037 } 6038 6039 And then define a target that uses the config: 6040 6041 executable("doom_melon") { 6042 configs += [ ":use_precompiled_headers" ] 6043 ... 6044``` 6045### <a name="var_precompiled_header_type"></a>**precompiled_header_type**: [string] "gcc" or "msvc". 6046 6047``` 6048 See "gn help precompiled_header". 6049``` 6050### <a name="var_precompiled_source"></a>**precompiled_source**: [file name] Source file to precompile. 6051 6052``` 6053 The source file that goes along with the precompiled_header when using 6054 "msvc"-style precompiled headers. It will be implicitly added to the sources 6055 of the target. See "gn help precompiled_header". 6056``` 6057### <a name="var_product_type"></a>**product_type**: Product type for Xcode projects. 6058 6059``` 6060 Correspond to the type of the product of a create_bundle target. Only 6061 meaningful to Xcode (used as part of the Xcode project generation). 6062 6063 When generating Xcode project files, only create_bundle target with a 6064 non-empty product_type will have a corresponding target in Xcode project. 6065``` 6066### <a name="var_public"></a>**public**: Declare public header files for a target. 6067 6068``` 6069 A list of files that other targets can include. These permissions are checked 6070 via the "check" command (see "gn help check"). 6071 6072 If no public files are declared, other targets (assuming they have visibility 6073 to depend on this target) can include any file in the sources list. If this 6074 variable is defined on a target, dependent targets may only include files on 6075 this whitelist unless that target is marked as a friend (see "gn help 6076 friend"). 6077 6078 Header file permissions are also subject to visibility. A target must be 6079 visible to another target to include any files from it at all and the public 6080 headers indicate which subset of those files are permitted. See "gn help 6081 visibility" for more. 6082 6083 Public files are inherited through the dependency tree. So if there is a 6084 dependency A -> B -> C, then A can include C's public headers. However, the 6085 same is NOT true of visibility, so unless A is in C's visibility list, the 6086 include will be rejected. 6087 6088 GN only knows about files declared in the "sources" and "public" sections of 6089 targets. If a file is included that is not known to the build, it will be 6090 allowed. 6091 6092 It is common for test targets to need to include private headers for their 6093 associated code. In this case, list the test target in the "friend" list of 6094 the target that owns the private header to allow the inclusion. See 6095 "gn help friend" for more. 6096 6097 When a binary target has no explicit or implicit public headers (a "public" 6098 list is defined but is empty), GN assumes that the target can not propagate 6099 any compile-time dependencies up the dependency tree. In this case, the build 6100 can be parallelized more efficiently. 6101 Say there are dependencies: 6102 A (shared library) -> B (shared library) -> C (action). 6103 Normally C must complete before any source files in A can compile (because 6104 there might be generated includes). But when B explicitly declares no public 6105 headers, C can execute in parallel with A's compile steps. C must still be 6106 complete before any dependents link. 6107``` 6108 6109#### **Examples** 6110 6111``` 6112 These exact files are public: 6113 public = [ "foo.h", "bar.h" ] 6114 6115 No files are public (no targets may include headers from this one): 6116 # This allows starting compilation in dependent targets earlier. 6117 public = [] 6118``` 6119### <a name="var_public_configs"></a>**public_configs**: Configs to be applied on dependents. 6120 6121``` 6122 A list of config labels. 6123 6124 Targets directly depending on this one will have the configs listed in this 6125 variable added to them. These configs will also apply to the current target. 6126 Generally, public configs are used to apply defines and include directories 6127 necessary to compile this target's header files. 6128 6129 See also "gn help all_dependent_configs". 6130``` 6131 6132#### **Propagation of public configs** 6133 6134``` 6135 Public configs are applied to all targets that depend directly on this one. 6136 These dependant targets can further push this target's public configs 6137 higher in the dependency tree by depending on it via public_deps (see "gn 6138 help public_deps"). 6139 6140 static_library("toplevel") { 6141 # This target will get "my_config" applied to it. However, since this 6142 # target uses "deps" and not "public_deps", targets that depend on this 6143 # one won't get it. 6144 deps = [ ":intermediate" ] 6145 } 6146 6147 static_library("intermediate") { 6148 # Depending on "lower" in any way will apply "my_config" to this target. 6149 # Additionall, since this target depends on "lower" via public_deps, 6150 # targets that depend on this one will also get "my_config". 6151 public_deps = [ ":lower" ] 6152 } 6153 6154 static_library("lower") { 6155 # This will get applied to all targets that depend on this one. 6156 public_configs = [ ":my_config" ] 6157 } 6158 6159 Public config propagation happens in a second phase once a target and all of 6160 its dependencies have been resolved. Therefore, a target will not see these 6161 force-added configs in their "configs" variable while the script is running, 6162 and they can not be removed. As a result, this capability should generally 6163 only be used to add defines and include directories rather than setting 6164 complicated flags that some targets may not want. 6165 6166 Public configs may or may not be propagated across toolchain boundaries 6167 depending on the value of the propagates_configs flag (see "gn help 6168 toolchain") on the toolchain of the target declaring the public_config. 6169``` 6170 6171#### **Avoiding applying public configs to this target** 6172 6173``` 6174 If you want the config to apply to targets that depend on this one, but NOT 6175 this one, define an extra layer of indirection using a group: 6176 6177 # External targets depend on this group. 6178 group("my_target") { 6179 # Config to apply to all targets that depend on this one. 6180 public_configs = [ ":external_settings" ] 6181 deps = [ ":internal_target" ] 6182 } 6183 6184 # Internal target to actually compile the sources. 6185 static_library("internal_target") { 6186 # Force all external targets to depend on the group instead of directly 6187 # on this so the "external_settings" config will get applied. 6188 visibility = [ ":my_target" ] 6189 ... 6190 } 6191``` 6192 6193#### **Ordering of flags and values** 6194 6195``` 6196 1. Those set on the current target (not in a config). 6197 2. Those set on the "configs" on the target in order that the 6198 configs appear in the list. 6199 3. Those set on the "all_dependent_configs" on the target in order 6200 that the configs appear in the list. 6201 4. Those set on the "public_configs" on the target in order that 6202 those configs appear in the list. 6203 5. all_dependent_configs pulled from dependencies, in the order of 6204 the "deps" list. This is done recursively. If a config appears 6205 more than once, only the first occurence will be used. 6206 6. public_configs pulled from dependencies, in the order of the 6207 "deps" list. If a dependency is public, they will be applied 6208 recursively. 6209``` 6210### <a name="var_public_deps"></a>**public_deps**: Declare public dependencies. 6211 6212``` 6213 Public dependencies are like private dependencies (see "gn help deps") but 6214 additionally express that the current target exposes the listed deps as part 6215 of its public API. 6216 6217 This has several ramifications: 6218 6219 - public_configs that are part of the dependency are forwarded to direct 6220 dependents. 6221 6222 - Public headers in the dependency are usable by dependents (includes do 6223 not require a direct dependency or visibility). 6224 6225 - If the current target is a shared library, other shared libraries that it 6226 publicly depends on (directly or indirectly) are propagated up the 6227 dependency tree to dependents for linking. 6228 6229 See also "gn help public_configs". 6230``` 6231 6232#### **Discussion** 6233 6234``` 6235 Say you have three targets: A -> B -> C. C's visibility may allow B to depend 6236 on it but not A. Normally, this would prevent A from including any headers 6237 from C, and C's public_configs would apply only to B. 6238 6239 If B lists C in its public_deps instead of regular deps, A will now inherit 6240 C's public_configs and the ability to include C's public headers. 6241 6242 Generally if you are writing a target B and you include C's headers as part 6243 of B's public headers, or targets depending on B should consider B and C to 6244 be part of a unit, you should use public_deps instead of deps. 6245``` 6246 6247#### **Example** 6248 6249``` 6250 # This target can include files from "c" but not from 6251 # "super_secret_implementation_details". 6252 executable("a") { 6253 deps = [ ":b" ] 6254 } 6255 6256 shared_library("b") { 6257 deps = [ ":super_secret_implementation_details" ] 6258 public_deps = [ ":c" ] 6259 } 6260``` 6261### <a name="var_rebase"></a>**rebase**: Rebase collected metadata as files. 6262 6263``` 6264 A boolean that triggers a rebase of collected metadata strings based on their 6265 declared file. Defaults to false. 6266 6267 Metadata generally declares files as strings relative to the local build file. 6268 However, this data is often used in other contexts, and so setting this flag 6269 will force the metadata collection to be rebased according to the local build 6270 file's location and thus allow the filename to be used anywhere. 6271 6272 Setting this flag will raise an error if any target's specified metadata is 6273 not a string value. 6274 6275 See also "gn help generated_file". 6276``` 6277### <a name="var_response_file_contents"></a>**response_file_contents**: Contents of a response file for actions. 6278 6279``` 6280 Sometimes the arguments passed to a script can be too long for the system's 6281 command-line capabilities. This is especially the case on Windows where the 6282 maximum command-line length is less than 8K. A response file allows you to 6283 pass an unlimited amount of data to a script in a temporary file for an 6284 action or action_foreach target. 6285 6286 If the response_file_contents variable is defined and non-empty, the list 6287 will be treated as script args (including possibly substitution patterns) 6288 that will be written to a temporary file at build time. The name of the 6289 temporary file will be substituted for "{{response_file_name}}" in the script 6290 args. 6291 6292 The response file contents will always be quoted and escaped according to 6293 Unix shell rules. To parse the response file, the Python script should use 6294 "shlex.split(file_contents)". 6295``` 6296 6297#### **Example** 6298 6299``` 6300 action("process_lots_of_files") { 6301 script = "process.py", 6302 inputs = [ ... huge list of files ... ] 6303 6304 # Write all the inputs to a response file for the script. Also, 6305 # make the paths relative to the script working directory. 6306 response_file_contents = rebase_path(inputs, root_build_dir) 6307 6308 # The script expects the name of the response file in --file-list. 6309 args = [ 6310 "--enable-foo", 6311 "--file-list={{response_file_name}}", 6312 ] 6313 } 6314``` 6315### <a name="var_script"></a>**script**: Script file for actions. 6316 6317``` 6318 An absolute or buildfile-relative file name of a Python script to run for a 6319 action and action_foreach targets (see "gn help action" and "gn help 6320 action_foreach"). 6321``` 6322### <a name="var_sources"></a>**sources**: Source files for a target 6323 6324``` 6325 A list of files. Non-absolute paths will be resolved relative to the current 6326 build file. 6327``` 6328 6329#### **Sources for binary targets** 6330 6331``` 6332 For binary targets (source sets, executables, and libraries), the known file 6333 types will be compiled with the associated tools. Unknown file types and 6334 headers will be skipped. However, you should still list all C/C+ header files 6335 so GN knows about the existence of those files for the purposes of include 6336 checking. 6337 6338 As a special case, a file ending in ".def" will be treated as a Windows 6339 module definition file. It will be appended to the link line with a 6340 preceding "/DEF:" string. There must be at most one .def file in a target 6341 and they do not cross dependency boundaries (so specifying a .def file in a 6342 static library or source set will have no effect on the executable or shared 6343 library they're linked into). 6344 6345 For Rust targets that do not specify a crate_root, then the crate_root will 6346 look for a lib.rs file (or main.rs for executable) or a single file in 6347 sources, if sources contains only one file. 6348``` 6349 6350#### **Sources for non-binary targets** 6351 6352``` 6353 action_foreach 6354 The sources are the set of files that the script will be executed over. The 6355 script will run once per file. 6356 6357 action 6358 The sources will be treated the same as inputs. See "gn help inputs" for 6359 more information and usage advice. 6360 6361 copy 6362 The source are the source files to copy. 6363``` 6364### <a name="var_swiftflags"></a>**swiftflags**: Flags passed to the swift compiler. 6365 6366``` 6367 A list of strings. 6368 6369 "swiftflags" are passed to any invocation of a tool that takes an .swift 6370 file as input. 6371``` 6372 6373#### **Ordering of flags and values** 6374 6375``` 6376 1. Those set on the current target (not in a config). 6377 2. Those set on the "configs" on the target in order that the 6378 configs appear in the list. 6379 3. Those set on the "all_dependent_configs" on the target in order 6380 that the configs appear in the list. 6381 4. Those set on the "public_configs" on the target in order that 6382 those configs appear in the list. 6383 5. all_dependent_configs pulled from dependencies, in the order of 6384 the "deps" list. This is done recursively. If a config appears 6385 more than once, only the first occurence will be used. 6386 6. public_configs pulled from dependencies, in the order of the 6387 "deps" list. If a dependency is public, they will be applied 6388 recursively. 6389``` 6390### <a name="var_testonly"></a>**testonly**: Declares a target must only be used for testing. 6391 6392``` 6393 Boolean. Defaults to false. 6394 6395 When a target is marked "testonly = true", it must only be depended on by 6396 other test-only targets. Otherwise, GN will issue an error that the 6397 depenedency is not allowed. 6398 6399 This feature is intended to prevent accidentally shipping test code in a 6400 final product. 6401``` 6402 6403#### **Example** 6404 6405``` 6406 source_set("test_support") { 6407 testonly = true 6408 ... 6409 } 6410``` 6411### <a name="var_visibility"></a>**visibility**: A list of labels that can depend on a target. 6412 6413``` 6414 A list of labels and label patterns that define which targets can depend on 6415 the current one. These permissions are checked via the "check" command (see 6416 "gn help check"). 6417 6418 If visibility is not defined, it defaults to public ("*"). 6419 6420 If visibility is defined, only the targets with labels that match it can 6421 depend on the current target. The empty list means no targets can depend on 6422 the current target. 6423 6424 Tip: Often you will want the same visibility for all targets in a BUILD file. 6425 In this case you can just put the definition at the top, outside of any 6426 target, and the targets will inherit that scope and see the definition. 6427``` 6428 6429#### **Patterns** 6430 6431``` 6432 See "gn help label_pattern" for more details on what types of patterns are 6433 supported. If a toolchain is specified, only targets in that toolchain will 6434 be matched. If a toolchain is not specified on a pattern, targets in all 6435 toolchains will be matched. 6436``` 6437 6438#### **Examples** 6439 6440``` 6441 Only targets in the current buildfile ("private"): 6442 visibility = [ ":*" ] 6443 6444 No targets (used for targets that should be leaf nodes): 6445 visibility = [] 6446 6447 Any target ("public", the default): 6448 visibility = [ "*" ] 6449 6450 All targets in the current directory and any subdirectory: 6451 visibility = [ "./*" ] 6452 6453 Any target in "//bar/BUILD.gn": 6454 visibility = [ "//bar:*" ] 6455 6456 Any target in "//bar/" or any subdirectory thereof: 6457 visibility = [ "//bar/*" ] 6458 6459 Just these specific targets: 6460 visibility = [ ":mything", "//foo:something_else" ] 6461 6462 Any target in the current directory and any subdirectory thereof, plus 6463 any targets in "//bar/" and any subdirectory thereof. 6464 visibility = [ "./*", "//bar/*" ] 6465``` 6466### <a name="var_walk_keys"></a>**walk_keys**: Key(s) for managing the metadata collection walk. 6467 6468``` 6469 Defaults to [""]. 6470 6471 These keys are used to control the next step in a collection walk, acting as 6472 barriers. If a specified key is defined in a target's metadata, the walk will 6473 use the targets listed in that value to determine which targets are walked. 6474 6475 If no walk_keys are specified for a generated_file target (i.e. "[""]"), the 6476 walk will touch all deps and data_deps of the specified target recursively. 6477 6478 See "gn help generated_file". 6479``` 6480### <a name="var_weak_frameworks"></a>**weak_frameworks**: [name list] Name of frameworks that must be weak linked. 6481 6482``` 6483 A list of framework names. 6484 6485 The frameworks named in that list will be weak linked with any dynamic link 6486 type target. Weak linking instructs the dynamic loader to attempt to load 6487 the framework, but if it is not able to do so, it leaves any imported symbols 6488 unresolved. This is typically used when a framework is present in a new 6489 version of an SDK but not on older versions of the OS that the software runs 6490 on. 6491``` 6492 6493#### **Ordering of flags and values** 6494 6495``` 6496 1. Those set on the current target (not in a config). 6497 2. Those set on the "configs" on the target in order that the 6498 configs appear in the list. 6499 3. Those set on the "all_dependent_configs" on the target in order 6500 that the configs appear in the list. 6501 4. Those set on the "public_configs" on the target in order that 6502 those configs appear in the list. 6503 5. all_dependent_configs pulled from dependencies, in the order of 6504 the "deps" list. This is done recursively. If a config appears 6505 more than once, only the first occurence will be used. 6506 6. public_configs pulled from dependencies, in the order of the 6507 "deps" list. If a dependency is public, they will be applied 6508 recursively. 6509``` 6510 6511#### **Example** 6512 6513``` 6514 weak_frameworks = [ "OnlyOnNewerOSes.framework" ] 6515``` 6516### <a name="var_write_runtime_deps"></a>**write_runtime_deps**: Writes the target's runtime_deps to the given path. 6517 6518``` 6519 Does not synchronously write the file, but rather schedules it to be written 6520 at the end of generation. 6521 6522 If the file exists and the contents are identical to that being written, the 6523 file will not be updated. This will prevent unnecessary rebuilds of targets 6524 that depend on this file. 6525 6526 Path must be within the output directory. 6527 6528 See "gn help runtime_deps" for how the runtime dependencies are computed. 6529 6530 The format of this file will list one file per line with no escaping. The 6531 files will be relative to the root_build_dir. The first line of the file will 6532 be the main output file of the target itself. The file contents will be the 6533 same as requesting the runtime deps be written on the command line (see "gn 6534 help --runtime-deps-list-file"). 6535``` 6536### <a name="var_xcasset_compiler_flags"></a>**xcasset_compiler_flags**: Flags passed to xcassets compiler. 6537 6538``` 6539 A list of strings. 6540 6541 Valid for create_bundle target. Those flags are directly passed to 6542 xcassets compiler, corresponding to {{xcasset_compiler_flags}} substitution 6543 in compile_xcassets tool. 6544``` 6545### <a name="var_xcode_extra_attributes"></a>**xcode_extra_attributes**: [scope] Extra attributes for Xcode projects. 6546 6547``` 6548 The value defined in this scope will be copied to the EXTRA_ATTRIBUTES 6549 property of the generated Xcode project. They are only meaningful when 6550 generating with --ide=xcode. 6551 6552 See "gn help create_bundle" for more information. 6553``` 6554### <a name="var_xcode_test_application_name"></a>**xcode_test_application_name**: Name for Xcode test target. 6555 6556``` 6557 Each unit and ui test target must have a test application target, and this 6558 value is used to specify the relationship. Only meaningful to Xcode (used as 6559 part of the Xcode project generation). 6560 6561 See "gn help create_bundle" for more information. 6562``` 6563 6564#### **Example** 6565 6566``` 6567 create_bundle("chrome_xctest") { 6568 test_application_name = "chrome" 6569 ... 6570 } 6571``` 6572## <a name="other"></a>Other help topics 6573 6574### <a name="buildargs"></a>**Build Arguments Overview** 6575 6576``` 6577 Build arguments are variables passed in from outside of the build that build 6578 files can query to determine how the build works. 6579``` 6580 6581#### **How build arguments are set** 6582 6583``` 6584 First, system default arguments are set based on the current system. The 6585 built-in arguments are: 6586 - host_cpu 6587 - host_os 6588 - current_cpu 6589 - current_os 6590 - target_cpu 6591 - target_os 6592 6593 Next, project-specific overrides are applied. These are specified inside 6594 the default_args variable of //.gn. See "gn help dotfile" for more. 6595 6596 If specified, arguments from the --args command line flag are used. If that 6597 flag is not specified, args from previous builds in the build directory will 6598 be used (this is in the file args.gn in the build directory). 6599 6600 Last, for targets being compiled with a non-default toolchain, the toolchain 6601 overrides are applied. These are specified in the toolchain_args section of a 6602 toolchain definition. The use-case for this is that a toolchain may be 6603 building code for a different platform, and that it may want to always 6604 specify Posix, for example. See "gn help toolchain" for more. 6605 6606 If you specify an override for a build argument that never appears in a 6607 "declare_args" call, a nonfatal error will be displayed. 6608``` 6609 6610#### **Examples** 6611 6612``` 6613 gn args out/FooBar 6614 Create the directory out/FooBar and open an editor. You would type 6615 something like this into that file: 6616 enable_doom_melon=false 6617 os="android" 6618 6619 gn gen out/FooBar --args="enable_doom_melon=true os=\"android\"" 6620 This will overwrite the build directory with the given arguments. (Note 6621 that the quotes inside the args command will usually need to be escaped 6622 for your shell to pass through strings values.) 6623``` 6624 6625#### **How build arguments are used** 6626 6627``` 6628 If you want to use an argument, you use declare_args() and specify default 6629 values. These default values will apply if none of the steps listed in the 6630 "How build arguments are set" section above apply to the given argument, but 6631 the defaults will not override any of these. 6632 6633 Often, the root build config file will declare global arguments that will be 6634 passed to all buildfiles. Individual build files can also specify arguments 6635 that apply only to those files. It is also useful to specify build args in an 6636 "import"-ed file if you want such arguments to apply to multiple buildfiles. 6637``` 6638### <a name="dotfile"></a>**.gn file** 6639 6640``` 6641 When gn starts, it will search the current directory and parent directories 6642 for a file called ".gn". This indicates the source root. You can override 6643 this detection by using the --root command-line argument 6644 6645 The .gn file in the source root will be executed. The syntax is the same as a 6646 buildfile, but with very limited build setup-specific meaning. 6647 6648 If you specify --root, by default GN will look for the file .gn in that 6649 directory. If you want to specify a different file, you can additionally pass 6650 --dotfile: 6651 6652 gn gen out/Debug --root=/home/build --dotfile=/home/my_gn_file.gn 6653``` 6654 6655#### **Variables** 6656 6657``` 6658 arg_file_template [optional] 6659 Path to a file containing the text that should be used as the default 6660 args.gn content when you run `gn args`. 6661 6662 buildconfig [required] 6663 Path to the build config file. This file will be used to set up the 6664 build file execution environment for each toolchain. 6665 6666 check_targets [optional] 6667 A list of labels and label patterns that should be checked when running 6668 "gn check" or "gn gen --check". If neither check_targets or 6669 no_check_targets (see below) is specified, all targets will be checked. 6670 It is an error to specify both check_targets and no_check_targets. If it 6671 is the empty list, no targets will be checked. To bypass this list, 6672 request an explicit check of targets, like "//*". 6673 6674 The format of this list is identical to that of "visibility" so see "gn 6675 help visibility" for examples. 6676 6677 no_check_targets [optional] 6678 A list of labels and label patterns that should *not* be checked when 6679 running "gn check" or "gn gen --check". All other targets will be checked. 6680 If neither check_targets (see above) or no_check_targets is specified, all 6681 targets will be checked. It is an error to specify both check_targets and 6682 no_check_targets. 6683 6684 The format of this list is identical to that of "visibility" so see "gn 6685 help visibility" for examples. 6686 6687 check_system_includes [optional] 6688 Boolean to control whether system style includes are checked by default 6689 when running "gn check" or "gn gen --check". System style includes are 6690 includes that use angle brackets <> instead of double quotes "". If this 6691 setting is omitted or set to false, these includes will be ignored by 6692 default. They can be checked explicitly by running 6693 "gn check --check-system" or "gn gen --check=system" 6694 6695 exec_script_whitelist [optional] 6696 A list of .gn/.gni files (not labels) that have permission to call the 6697 exec_script function. If this list is defined, calls to exec_script will 6698 be checked against this list and GN will fail if the current file isn't 6699 in the list. 6700 6701 This is to allow the use of exec_script to be restricted since is easy to 6702 use inappropriately. Wildcards are not supported. Files in the 6703 secondary_source tree (if defined) should be referenced by ignoring the 6704 secondary tree and naming them as if they are in the main tree. 6705 6706 If unspecified, the ability to call exec_script is unrestricted. 6707 6708 Example: 6709 exec_script_whitelist = [ 6710 "//base/BUILD.gn", 6711 "//build/my_config.gni", 6712 ] 6713 6714 root [optional] 6715 Label of the root build target. The GN build will start by loading the 6716 build file containing this target name. This defaults to "//:" which will 6717 cause the file //BUILD.gn to be loaded. Note that build_file_extension 6718 applies to the default case as well. 6719 6720 script_executable [optional] 6721 Path to specific Python executable or other interpreter to use in 6722 action targets and exec_script calls. By default GN searches the 6723 PATH for Python to execute these scripts. 6724 6725 If set to the empty string, the path specified in action targets 6726 and exec_script calls will be executed directly. 6727 6728 secondary_source [optional] 6729 Label of an alternate directory tree to find input files. When searching 6730 for a BUILD.gn file (or the build config file discussed above), the file 6731 will first be looked for in the source root. If it's not found, the 6732 secondary source root will be checked (which would contain a parallel 6733 directory hierarchy). 6734 6735 This behavior is intended to be used when BUILD.gn files can't be checked 6736 in to certain source directories for whatever reason. 6737 6738 The secondary source root must be inside the main source tree. 6739 6740 default_args [optional] 6741 Scope containing the default overrides for declared arguments. These 6742 overrides take precedence over the default values specified in the 6743 declare_args() block, but can be overriden using --args or the 6744 args.gn file. 6745 6746 This is intended to be used when subprojects declare arguments with 6747 default values that need to be changed for whatever reason. 6748 6749 build_file_extension [optional] 6750 If set to a non-empty string, this is added to the name of all build files 6751 to load. 6752 GN will look for build files named "BUILD.$build_file_extension.gn". 6753 This is intended to be used during migrations or other situations where 6754 there are two independent GN builds in the same directories. 6755 6756 ninja_required_version [optional] 6757 When set specifies the minimum required version of Ninja. The default 6758 required version is 1.7.2. Specifying a higher version might enable the 6759 use of some of newer features that can make the build more efficient. 6760``` 6761 6762#### **Example .gn file contents** 6763 6764``` 6765 buildconfig = "//build/config/BUILDCONFIG.gn" 6766 6767 check_targets = [ 6768 "//doom_melon/*", # Check everything in this subtree. 6769 "//tools:mind_controlling_ant", # Check this specific target. 6770 ] 6771 6772 root = "//:root" 6773 6774 secondary_source = "//build/config/temporary_buildfiles/" 6775 6776 default_args = { 6777 # Default to release builds for this project. 6778 is_debug = false 6779 is_component_build = false 6780 } 6781``` 6782### <a name="execution"></a>**Build graph and execution overview** 6783 6784#### **Overall build flow** 6785 6786``` 6787 1. Look for ".gn" file (see "gn help dotfile") in the current directory and 6788 walk up the directory tree until one is found. Set this directory to be 6789 the "source root" and interpret this file to find the name of the build 6790 config file. 6791 6792 2. Execute the build config file identified by .gn to set up the global 6793 variables and default toolchain name. Any arguments, variables, defaults, 6794 etc. set up in this file will be visible to all files in the build. 6795 6796 3. Load the //BUILD.gn (in the source root directory). 6797 6798 4. Recursively evaluate rules and load BUILD.gn in other directories as 6799 necessary to resolve dependencies. If a BUILD file isn't found in the 6800 specified location, GN will look in the corresponding location inside 6801 the secondary_source defined in the dotfile (see "gn help dotfile"). 6802 6803 5. When a target's dependencies are resolved, write out the `.ninja` 6804 file to disk. 6805 6806 6. When all targets are resolved, write out the root build.ninja file. 6807 6808 Note that the BUILD.gn file name may be modulated by .gn arguments such as 6809 build_file_extension. 6810``` 6811 6812#### **Executing target definitions and templates** 6813 6814``` 6815 Build files are loaded in parallel. This means it is impossible to 6816 interrogate a target from GN code for any information not derivable from its 6817 label (see "gn help label"). The exception is the get_target_outputs() 6818 function which requires the target being interrogated to have been defined 6819 previously in the same file. 6820 6821 Targets are declared by their type and given a name: 6822 6823 static_library("my_static_library") { 6824 ... target parameter definitions ... 6825 } 6826 6827 There is also a generic "target" function for programmatically defined types 6828 (see "gn help target"). You can define new types using templates (see "gn 6829 help template"). A template defines some custom code that expands to one or 6830 more other targets. 6831 6832 Before executing the code inside the target's { }, the target defaults are 6833 applied (see "gn help set_defaults"). It will inject implicit variable 6834 definitions that can be overridden by the target code as necessary. Typically 6835 this mechanism is used to inject a default set of configs that define the 6836 global compiler and linker flags. 6837``` 6838 6839#### **Which targets are built** 6840 6841``` 6842 All targets encountered in the default toolchain (see "gn help toolchain") 6843 will have build rules generated for them, even if no other targets reference 6844 them. Their dependencies must resolve and they will be added to the implicit 6845 "all" rule (see "gn help ninja_rules"). 6846 6847 Targets in non-default toolchains will only be generated when they are 6848 required (directly or transitively) to build a target in the default 6849 toolchain. 6850 6851 See also "gn help ninja_rules". 6852``` 6853 6854#### **Dependencies** 6855 6856``` 6857 The only difference between "public_deps" and "deps" except for pushing 6858 configs around the build tree and allowing includes for the purposes of "gn 6859 check". 6860 6861 A target's "data_deps" are guaranteed to be built whenever the target is 6862 built, but the ordering is not defined. The meaning of this is dependencies 6863 required at runtime. Currently data deps will be complete before the target 6864 is linked, but this is not semantically guaranteed and this is undesirable 6865 from a build performance perspective. Since we hope to change this in the 6866 future, do not rely on this behavior. 6867``` 6868### <a name="grammar"></a>**Language and grammar for GN build files** 6869 6870#### **Tokens** 6871 6872``` 6873 GN build files are read as sequences of tokens. While splitting the file 6874 into tokens, the next token is the longest sequence of characters that form a 6875 valid token. 6876``` 6877 6878#### **White space and comments** 6879 6880``` 6881 White space is comprised of spaces (U+0020), horizontal tabs (U+0009), 6882 carriage returns (U+000D), and newlines (U+000A). 6883 6884 Comments start at the character "#" and stop at the next newline. 6885 6886 White space and comments are ignored except that they may separate tokens 6887 that would otherwise combine into a single token. 6888``` 6889 6890#### **Identifiers** 6891 6892``` 6893 Identifiers name variables and functions. 6894 6895 identifier = letter { letter | digit } . 6896 letter = "A" ... "Z" | "a" ... "z" | "_" . 6897 digit = "0" ... "9" . 6898``` 6899 6900#### **Keywords** 6901 6902``` 6903 The following keywords are reserved and may not be used as identifiers: 6904 6905 else false if true 6906``` 6907 6908#### **Integer literals** 6909 6910``` 6911 An integer literal represents a decimal integer value. 6912 6913 integer = [ "-" ] digit { digit } . 6914 6915 Leading zeros and negative zero are disallowed. 6916``` 6917 6918#### **String literals** 6919 6920``` 6921 A string literal represents a string value consisting of the quoted 6922 characters with possible escape sequences and variable expansions. 6923 6924 string = `"` { char | escape | expansion } `"` . 6925 escape = `\` ( "$" | `"` | char ) . 6926 BracketExpansion = "{" ( identifier | ArrayAccess | ScopeAccess " 6927 ") "}" . 6928 Hex = "0x" [0-9A-Fa-f][0-9A-Fa-f] 6929 expansion = "$" ( identifier | BracketExpansion | Hex ) . 6930 char = /* any character except "$", `"`, or newline " 6931 "*/ . 6932 6933 After a backslash, certain sequences represent special characters: 6934 6935 \" U+0022 quotation mark 6936 \$ U+0024 dollar sign 6937 \\ U+005C backslash 6938 6939 All other backslashes represent themselves. 6940 6941 To insert an arbitrary byte value, use $0xFF. For example, to insert a 6942 newline character: "Line one$0x0ALine two". 6943 6944 An expansion will evaluate the variable following the '$' and insert a 6945 stringified version of it into the result. For example, to concat two path 6946 components with a slash separating them: 6947 "$var_one/$var_two" 6948 Use the "${var_one}" format to be explicitly deliniate the variable for 6949 otherwise-ambiguous cases. 6950``` 6951 6952#### **Punctuation** 6953 6954``` 6955 The following character sequences represent punctuation: 6956 6957 + += == != ( ) 6958 - -= < <= [ ] 6959 ! = > >= { } 6960 && || . , 6961``` 6962 6963#### **Grammar** 6964 6965``` 6966 The input tokens form a syntax tree following a context-free grammar: 6967 6968 File = StatementList . 6969 6970 Statement = Assignment | Call | Condition . 6971 LValue = identifier | ArrayAccess | ScopeAccess . 6972 Assignment = LValue AssignOp Expr . 6973 Call = identifier "(" [ ExprList ] ")" [ Block ] . 6974 Condition = "if" "(" Expr ")" Block 6975 [ "else" ( Condition | Block ) ] . 6976 Block = "{" StatementList "}" . 6977 StatementList = { Statement } . 6978 6979 ArrayAccess = identifier "[" Expr "]" . 6980 ScopeAccess = identifier "." identifier . 6981 Expr = UnaryExpr | Expr BinaryOp Expr . 6982 UnaryExpr = PrimaryExpr | UnaryOp UnaryExpr . 6983 PrimaryExpr = identifier | integer | string | Call 6984 | ArrayAccess | ScopeAccess | Block 6985 | "(" Expr ")" 6986 | "[" [ ExprList [ "," ] ] "]" . 6987 ExprList = Expr { "," Expr } . 6988 6989 AssignOp = "=" | "+=" | "-=" . 6990 UnaryOp = "!" . 6991 BinaryOp = "+" | "-" // highest priority 6992 | "<" | "<=" | ">" | ">=" 6993 | "==" | "!=" 6994 | "&&" 6995 | "||" . // lowest priority 6996 6997 All binary operators are left-associative. 6998``` 6999 7000#### **Types** 7001 7002``` 7003 The GN language is dynamically typed. The following types are used: 7004 7005 - Boolean: Uses the keywords "true" and "false". There is no implicit 7006 conversion between booleans and integers. 7007 7008 - Integers: All numbers in GN are signed 64-bit integers. 7009 7010 - Strings: Strings are 8-bit with no enforced encoding. When a string is 7011 used to interact with other systems with particular encodings (like the 7012 Windows and Mac filesystems) it is assumed to be UTF-8. See "String 7013 literals" above for more. 7014 7015 - Lists: Lists are arbitrary-length ordered lists of values. See "Lists" 7016 below for more. 7017 7018 - Scopes: Scopes are like dictionaries that use variable names for keys. See 7019 "Scopes" below for more. 7020``` 7021 7022#### **Lists** 7023 7024``` 7025 Lists are created with [] and using commas to separate items: 7026 7027 mylist = [ 0, 1, 2, "some string" ] 7028 7029 A comma after the last item is optional. Lists are dereferenced using 0-based 7030 indexing: 7031 7032 mylist[0] += 1 7033 var = mylist[2] 7034 7035 Lists can be concatenated using the '+' and '+=' operators. Bare values can 7036 not be concatenated with lists, to add a single item, it must be put into a 7037 list of length one. 7038 7039 Items can be removed from lists using the '-' and '-=' operators. This will 7040 remove all occurrences of every item in the right-hand list from the 7041 left-hand list. It is an error to remove an item not in the list. This is to 7042 prevent common typos and to detect dead code that is removing things that no 7043 longer apply. 7044 7045 It is an error to use '=' to replace a nonempty list with another nonempty 7046 list. This is to prevent accidentally overwriting data when in most cases 7047 '+=' was intended. To overwrite a list on purpose, first assign it to the 7048 empty list: 7049 7050 mylist = [] 7051 mylist = otherlist 7052``` 7053 7054#### **Scopes** 7055 7056``` 7057 All execution happens in the context of a scope which holds the current state 7058 (like variables). With the exception of loops and conditions, '{' introduces 7059 a new scope that has a parent reference to the old scope. 7060 7061 Variable reads recursively search all nested scopes until the variable is 7062 found or there are no more scopes. Variable writes always go into the current 7063 scope. This means that after the closing '}' (again excepting loops and 7064 conditions), all local variables will be restored to the previous values. 7065 This also means that "foo = foo" can do useful work by copying a variable 7066 into the current scope that was defined in a containing scope. 7067 7068 Scopes can also be assigned to variables. Such scopes can be created by 7069 functions like exec_script, when invoking a template (the template code 7070 refers to the variables set by the invoking code by the implicitly-created 7071 "invoker" scope), or explicitly like: 7072 7073 empty_scope = {} 7074 myvalues = { 7075 foo = 21 7076 bar = "something" 7077 } 7078 7079 Inside such a scope definition can be any GN code including conditionals and 7080 function calls. After the close of the scope, it will contain all variables 7081 explicitly set by the code contained inside it. After this, the values can be 7082 read, modified, or added to: 7083 7084 myvalues.foo += 2 7085 empty_scope.new_thing = [ 1, 2, 3 ] 7086 7087 Scope equality is defined as single-level scopes identical within the current 7088 scope. That is, all values in the first scope must be present and identical 7089 within the second, and vice versa. Note that this means inherited scopes are 7090 always unequal by definition. 7091``` 7092### <a name="io_conversion"></a>**Input and output conversion** 7093 7094``` 7095 Input and output conversions are arguments to file and process functions 7096 that specify how to convert data to or from external formats. The possible 7097 values for parameters specifying conversions are: 7098 7099 "" (the default) 7100 input: Discard the result and return None. 7101 7102 output: If value is a list, then "list lines"; otherwise "value". 7103 7104 "list lines" 7105 input: 7106 Return the file contents as a list, with a string for each line. The 7107 newlines will not be present in the result. The last line may or may 7108 not end in a newline. 7109 7110 After splitting, each individual line will be trimmed of whitespace on 7111 both ends. 7112 7113 output: 7114 Renders the value contents as a list, with a string for each line. The 7115 newlines will not be present in the result. The last line will end in 7116 with a newline. 7117 7118 "scope" 7119 input: 7120 Execute the block as GN code and return a scope with the resulting 7121 values in it. If the input was: 7122 a = [ "hello.cc", "world.cc" ] 7123 b = 26 7124 and you read the result into a variable named "val", then you could 7125 access contents the "." operator on "val": 7126 sources = val.a 7127 some_count = val.b 7128 7129 output: 7130 Renders the value contents as a GN code block, reversing the input 7131 result above. 7132 7133 "string" 7134 input: Return the file contents into a single string. 7135 7136 output: 7137 Render the value contents into a single string. The output is: 7138 a string renders with quotes, e.g. "str" 7139 an integer renders as a stringified integer, e.g. "6" 7140 a boolean renders as the associated string, e.g. "true" 7141 a list renders as a representation of its contents, e.g. "[\"str\", 6]" 7142 a scope renders as a GN code block of its values. If the Value was: 7143 Value val; 7144 val.a = [ "hello.cc", "world.cc" ]; 7145 val.b = 26 7146 the resulting output would be: 7147 "{ 7148 a = [ \"hello.cc\", \"world.cc\" ] 7149 b = 26 7150 }" 7151 7152 "value" 7153 input: 7154 Parse the input as if it was a literal rvalue in a buildfile. Examples of 7155 typical program output using this mode: 7156 [ "foo", "bar" ] (result will be a list) 7157 or 7158 "foo bar" (result will be a string) 7159 or 7160 5 (result will be an integer) 7161 7162 Note that if the input is empty, the result will be a null value which 7163 will produce an error if assigned to a variable. 7164 7165 output: 7166 Render the value contents as a literal rvalue. Strings render with 7167 escaped quotes. 7168 7169 "json" 7170 input: Parse the input as a JSON and convert it to equivalent GN rvalue. 7171 7172 output: Convert the Value to equivalent JSON value. 7173 7174 The data type mapping is: 7175 a string in JSON maps to string in GN 7176 an integer in JSON maps to integer in GN 7177 a float in JSON is unsupported and will result in an error 7178 an object in JSON maps to scope in GN 7179 an array in JSON maps to list in GN 7180 a boolean in JSON maps to boolean in GN 7181 a null in JSON is unsupported and will result in an error 7182 7183 Nota that the input dictionary keys have to be valid GN identifiers 7184 otherwise they will produce an error. 7185 7186 "trim ..." (input only) 7187 Prefixing any of the other transformations with the word "trim" will 7188 result in whitespace being trimmed from the beginning and end of the 7189 result before processing. 7190 7191 Examples: "trim string" or "trim list lines" 7192 7193 Note that "trim value" is useless because the value parser skips 7194 whitespace anyway. 7195``` 7196### <a name="file_pattern"></a>**File patterns** 7197 7198``` 7199 File patterns are VERY limited regular expressions. They must match the 7200 entire input string to be counted as a match. In regular expression parlance, 7201 there is an implicit "^...$" surrounding your input. If you want to match a 7202 substring, you need to use wildcards at the beginning and end. 7203 7204 There are only two special tokens understood by the pattern matcher. 7205 Everything else is a literal. 7206 7207 - "*" Matches zero or more of any character. It does not depend on the 7208 preceding character (in regular expression parlance it is equivalent to 7209 ".*"). 7210 7211 - "\b" Matches a path boundary. This will match the beginning or end of a 7212 string, or a slash. 7213``` 7214 7215#### **Pattern examples** 7216 7217``` 7218 "*asdf*" 7219 Matches a string containing "asdf" anywhere. 7220 7221 "asdf" 7222 Matches only the exact string "asdf". 7223 7224 "*.cc" 7225 Matches strings ending in the literal ".cc". 7226 7227 "\bwin/*" 7228 Matches "win/foo" and "foo/win/bar.cc" but not "iwin/foo". 7229``` 7230### <a name="label_pattern"></a>**Label patterns** 7231 7232``` 7233 A label pattern is a way of expressing one or more labels in a portion of the 7234 source tree. They are not general regular expressions. 7235 7236 They can take the following forms only: 7237 7238 - Explicit (no wildcard): 7239 "//foo/bar:baz" 7240 ":baz" 7241 7242 - Wildcard target names: 7243 "//foo/bar:*" (all targets in the //foo/bar/BUILD.gn file) 7244 ":*" (all targets in the current build file) 7245 7246 - Wildcard directory names ("*" is only supported at the end) 7247 "*" (all targets) 7248 "//foo/bar/*" (all targets in any subdir of //foo/bar) 7249 "./*" (all targets in the current build file or sub dirs) 7250 7251 Any of the above forms can additionally take an explicit toolchain 7252 in parenthesis at the end of the label pattern. In this case, the 7253 toolchain must be fully qualified (no wildcards are supported in the 7254 toolchain name). 7255 7256 "//foo:bar(//build/toolchain:mac)" 7257 An explicit target in an explicit toolchain. 7258 7259 ":*(//build/toolchain/linux:32bit)" 7260 All targets in the current build file using the 32-bit Linux toolchain. 7261 7262 "//foo/*(//build/toolchain:win)" 7263 All targets in //foo and any subdirectory using the Windows 7264 toolchain. 7265``` 7266### <a name="labels"></a>**About labels** 7267 7268``` 7269 Everything that can participate in the dependency graph (targets, configs, 7270 and toolchains) are identified by labels. A common label looks like: 7271 7272 //base/test:test_support 7273 7274 This consists of a source-root-absolute path, a colon, and a name. This means 7275 to look for the thing named "test_support" in "base/test/BUILD.gn". 7276 7277 You can also specify system absolute paths if necessary. Typically such 7278 paths would be specified via a build arg so the developer can specify where 7279 the component is on their system. 7280 7281 /usr/local/foo:bar (Posix) 7282 /C:/Program Files/MyLibs:bar (Windows) 7283``` 7284 7285#### **Toolchains** 7286 7287``` 7288 A canonical label includes the label of the toolchain being used. Normally, 7289 the toolchain label is implicitly inherited from the current execution 7290 context, but you can override this to specify cross-toolchain dependencies: 7291 7292 //base/test:test_support(//build/toolchain/win:msvc) 7293 7294 Here GN will look for the toolchain definition called "msvc" in the file 7295 "//build/toolchain/win" to know how to compile this target. 7296``` 7297 7298#### **Relative labels** 7299 7300``` 7301 If you want to refer to something in the same buildfile, you can omit 7302 the path name and just start with a colon. This format is recommended for 7303 all same-file references. 7304 7305 :base 7306 7307 Labels can be specified as being relative to the current directory. 7308 Stylistically, we prefer to use absolute paths for all non-file-local 7309 references unless a build file needs to be run in different contexts (like a 7310 project needs to be both standalone and pulled into other projects in 7311 difference places in the directory hierarchy). 7312 7313 source/plugin:myplugin 7314 ../net:url_request 7315``` 7316 7317#### **Implicit names** 7318 7319``` 7320 If a name is unspecified, it will inherit the directory name. Stylistically, 7321 we prefer to omit the colon and name when possible: 7322 7323 //net -> //net:net 7324 //tools/gn -> //tools/gn:gn 7325``` 7326### <a name="metadata_collection"></a>**Metadata Collection** 7327 7328``` 7329 Metadata is information attached to targets throughout the dependency tree. GN 7330 allows for the collection of this data into files written during the generation 7331 step, enabling users to expose and aggregate this data based on the dependency 7332 tree. 7333``` 7334 7335#### **generated_file targets** 7336 7337``` 7338 Similar to the write_file() function, the generated_file target type 7339 creates a file in the specified location with the specified content. The 7340 primary difference between write_file() and this target type is that the 7341 write_file function does the file write at parse time, while the 7342 generated_file target type writes at target resolution time. See 7343 "gn help generated_file" for more detail. 7344 7345 When written at target resolution time, generated_file enables GN to 7346 collect and write aggregated metadata from dependents. 7347 7348 A generated_file target can declare either 'contents' to write statically 7349 known contents to a file or 'data_keys' to aggregate metadata and write the 7350 result to a file. It can also specify 'walk_keys' (to restrict the metadata 7351 collection), 'output_conversion', and 'rebase'. 7352``` 7353 7354#### **Collection and Aggregation** 7355 7356``` 7357 Targets can declare a 'metadata' variable containing a scope, and this 7358 metadata may be collected and written out to a file specified by 7359 generated_file aggregation targets. The 'metadata' scope must contain 7360 only list values since the aggregation step collects a list of these values. 7361 7362 During the target resolution, generated_file targets will walk their 7363 dependencies recursively, collecting metadata based on the specified 7364 'data_keys'. 'data_keys' is specified as a list of strings, used by the walk 7365 to identify which variables in dependencies' 'metadata' scopes to collect. 7366 7367 The walk begins with the listed dependencies of the 'generated_file' target. 7368 The 'metadata' scope for each dependency is inspected for matching elements 7369 of the 'generated_file' target's 'data_keys' list. If a match is found, the 7370 data from the dependent's matching key list is appended to the aggregate walk 7371 list. Note that this means that if more than one walk key is specified, the 7372 data in all of them will be aggregated into one list. From there, the walk 7373 will then recurse into the dependencies of each target it encounters, 7374 collecting the specified metadata for each. 7375 7376 For example: 7377 7378 group("a") { 7379 metadata = { 7380 doom_melon = [ "enable" ] 7381 my_files = [ "foo.cpp" ] 7382 my_extra_files = [ "bar.cpp" ] 7383 } 7384 7385 deps = [ ":b" ] 7386 } 7387 7388 group("b") { 7389 metadata = { 7390 my_files = [ "baz.cpp" ] 7391 } 7392 } 7393 7394 generated_file("metadata") { 7395 outputs = [ "$root_build_dir/my_files.json" ] 7396 data_keys = [ "my_files", "my_extra_files" ] 7397 7398 deps = [ ":a" ] 7399 } 7400 7401 The above will produce the following file data: 7402 7403 foo.cpp 7404 bar.cpp 7405 baz.cpp 7406 7407 The dependency walk can be limited by using the 'walk_keys'. This is a list of 7408 labels that should be included in the walk. All labels specified here should 7409 also be in one of the deps lists. These keys act as barriers, where the walk 7410 will only recurse into the targets listed. An empty list in all specified 7411 barriers will end that portion of the walk. 7412 7413 group("a") { 7414 metadata = { 7415 my_files = [ "foo.cpp" ] 7416 my_files_barrier = [ ":b" ] 7417 } 7418 7419 deps = [ ":b", ":c" ] 7420 } 7421 7422 group("b") { 7423 metadata = { 7424 my_files = [ "bar.cpp" ] 7425 } 7426 } 7427 7428 group("c") { 7429 metadata = { 7430 my_files = [ "doom_melon.cpp" ] 7431 } 7432 } 7433 7434 generated_file("metadata") { 7435 outputs = [ "$root_build_dir/my_files.json" ] 7436 data_keys = [ "my_files" ] 7437 walk_keys = [ "my_files_barrier" ] 7438 7439 deps = [ ":a" ] 7440 } 7441 7442 The above will produce the following file data (note that `doom_melon.cpp` is 7443 not included): 7444 7445 foo.cpp 7446 bar.cpp 7447 7448 A common example of this sort of barrier is in builds that have host tools 7449 built as part of the tree, but do not want the metadata from those host tools 7450 to be collected with the target-side code. 7451``` 7452 7453#### **Common Uses** 7454 7455``` 7456 Metadata can be used to collect information about the different targets in the 7457 build, and so a common use is to provide post-build tooling with a set of data 7458 necessary to do aggregation tasks. For example, if each test target specifies 7459 the output location of its binary to run in a metadata field, that can be 7460 collected into a single file listing the locations of all tests in the 7461 dependency tree. A local build tool (or continuous integration infrastructure) 7462 can then use that file to know which tests exist, and where, and run them 7463 accordingly. 7464 7465 Another use is in image creation, where a post-build image tool needs to know 7466 various pieces of information about the components it should include in order 7467 to put together the correct image. 7468``` 7469### <a name="ninja_rules"></a>**Ninja build rules** 7470 7471#### **The "all" and "default" rules** 7472 7473``` 7474 All generated targets (see "gn help execution") will be added to an implicit 7475 build rule called "all" so "ninja all" will always compile everything. The 7476 default rule will be used by Ninja if no specific target is specified (just 7477 typing "ninja"). If there is a target named "default" in the root build file, 7478 it will be the default build rule, otherwise the implicit "all" rule will be 7479 used. 7480``` 7481 7482#### **Phony rules** 7483 7484``` 7485 GN generates Ninja "phony" rules for targets in the default toolchain. The 7486 phony rules can collide with each other and with the names of generated files 7487 so are generated with the following priority: 7488 7489 1. Actual files generated by the build always take precedence. 7490 7491 2. Targets in the toplevel //BUILD.gn file. 7492 7493 3. Targets in toplevel directories matching the names of the directories. 7494 So "ninja foo" can be used to compile "//foo:foo". This only applies to 7495 the first level of directories since usually these are the most 7496 important (so this won't apply to "//foo/bar:bar"). 7497 7498 4. The short names of executables if there is only one executable with that 7499 short name. Use "ninja doom_melon" to compile the 7500 "//tools/fruit:doom_melon" executable. 7501 7502 5. The short names of all targets if there is only one target with that 7503 short name. 7504 7505 6. Full label name with no leading slashes. So you can use 7506 "ninja tools/fruit:doom_melon" to build "//tools/fruit:doom_melon". 7507 7508 7. Labels with an implicit name part (when the short names match the 7509 directory). So you can use "ninja foo/bar" to compile "//foo/bar:bar". 7510 7511 These "phony" rules are provided only for running Ninja since this matches 7512 people's historical expectations for building. For consistency with the rest 7513 of the program, GN introspection commands accept explicit labels. 7514 7515 To explicitly compile a target in a non-default toolchain, you must give 7516 Ninja the exact name of the output file relative to the build directory. 7517``` 7518### <a name="nogncheck"></a>**nogncheck**: Skip an include line from checking. 7519 7520``` 7521 GN's header checker helps validate that the includes match the build 7522 dependency graph. Sometimes an include might be conditional or otherwise 7523 problematic, but you want to specifically allow it. In this case, it can be 7524 whitelisted. 7525 7526 Include lines containing the substring "nogncheck" will be excluded from 7527 header checking. The most common case is a conditional include: 7528 7529 #if defined(ENABLE_DOOM_MELON) 7530 #include "tools/doom_melon/doom_melon.h" // nogncheck 7531 #endif 7532 7533 If the build file has a conditional dependency on the corresponding target 7534 that matches the conditional include, everything will always link correctly: 7535 7536 source_set("mytarget") { 7537 ... 7538 if (enable_doom_melon) { 7539 defines = [ "ENABLE_DOOM_MELON" ] 7540 deps += [ "//tools/doom_melon" ] 7541 } 7542 7543 But GN's header checker does not understand preprocessor directives, won't 7544 know it matches the build dependencies, and will flag this include as 7545 incorrect when the condition is false. 7546``` 7547 7548#### **More information** 7549 7550``` 7551 The topic "gn help check" has general information on how checking works and 7552 advice on fixing problems. Targets can also opt-out of checking, see 7553 "gn help check_includes". 7554``` 7555### <a name="runtime_deps"></a>**Runtime dependencies** 7556 7557``` 7558 Runtime dependencies of a target are exposed via the "runtime_deps" category 7559 of "gn desc" (see "gn help desc") or they can be written at build generation 7560 time via write_runtime_deps(), or --runtime-deps-list-file (see "gn help 7561 --runtime-deps-list-file"). 7562 7563 To a first approximation, the runtime dependencies of a target are the set of 7564 "data" files, data directories, and the shared libraries from all transitive 7565 dependencies. Executables, shared libraries, and loadable modules are 7566 considered runtime dependencies of themselves. 7567``` 7568 7569#### **Executables** 7570 7571``` 7572 Executable targets and those executable targets' transitive dependencies are 7573 not considered unless that executable is listed in "data_deps". Otherwise, GN 7574 assumes that the executable (and everything it requires) is a build-time 7575 dependency only. 7576``` 7577 7578#### **Actions and copies** 7579 7580``` 7581 Action and copy targets that are listed as "data_deps" will have all of their 7582 outputs and data files considered as runtime dependencies. Action and copy 7583 targets that are "deps" or "public_deps" will have only their data files 7584 considered as runtime dependencies. These targets can list an output file in 7585 both the "outputs" and "data" lists to force an output file as a runtime 7586 dependency in all cases. 7587 7588 The different rules for deps and data_deps are to express build-time (deps) 7589 vs. run-time (data_deps) outputs. If GN counted all build-time copy steps as 7590 data dependencies, there would be a lot of extra stuff, and if GN counted all 7591 run-time dependencies as regular deps, the build's parallelism would be 7592 unnecessarily constrained. 7593 7594 This rule can sometimes lead to unintuitive results. For example, given the 7595 three targets: 7596 A --[data_deps]--> B --[deps]--> ACTION 7597 GN would say that A does not have runtime deps on the result of the ACTION, 7598 which is often correct. But the purpose of the B target might be to collect 7599 many actions into one logic unit, and the "data"-ness of A's dependency is 7600 lost. Solutions: 7601 7602 - List the outputs of the action in its data section (if the results of 7603 that action are always runtime files). 7604 - Have B list the action in data_deps (if the outputs of the actions are 7605 always runtime files). 7606 - Have B list the action in both deps and data deps (if the outputs might be 7607 used in both contexts and you don't care about unnecessary entries in the 7608 list of files required at runtime). 7609 - Split B into run-time and build-time versions with the appropriate "deps" 7610 for each. 7611``` 7612 7613#### **Static libraries and source sets** 7614 7615``` 7616 The results of static_library or source_set targets are not considered 7617 runtime dependencies since these are assumed to be intermediate targets only. 7618 If you need to list a static library as a runtime dependency, you can 7619 manually compute the .a/.lib file name for the current platform and list it 7620 in the "data" list of a target (possibly on the static library target 7621 itself). 7622``` 7623 7624#### **Multiple outputs** 7625 7626``` 7627 Linker tools can specify which of their outputs should be considered when 7628 computing the runtime deps by setting runtime_outputs. If this is unset on 7629 the tool, the default will be the first output only. 7630``` 7631### <a name="source_expansion"></a>**How Source Expansion Works** 7632 7633``` 7634 Source expansion is used for the action_foreach and copy target types to map 7635 source file names to output file names or arguments. 7636 7637 To perform source expansion in the outputs, GN maps every entry in the 7638 sources to every entry in the outputs list, producing the cross product of 7639 all combinations, expanding placeholders (see below). 7640 7641 Source expansion in the args works similarly, but performing the placeholder 7642 substitution produces a different set of arguments for each invocation of the 7643 script. 7644 7645 If no placeholders are found, the outputs or args list will be treated as a 7646 static list of literal file names that do not depend on the sources. 7647 7648 See "gn help copy" and "gn help action_foreach" for more on how this is 7649 applied. 7650``` 7651 7652#### **Placeholders** 7653 7654``` 7655 This section discusses only placeholders for actions. There are other 7656 placeholders used in the definition of tools. See "gn help tool" for those. 7657 7658 {{source}} 7659 The name of the source file including directory (*). This will generally 7660 be used for specifying inputs to a script in the "args" variable. 7661 "//foo/bar/baz.txt" => "../../foo/bar/baz.txt" 7662 7663 {{source_file_part}} 7664 The file part of the source including the extension. 7665 "//foo/bar/baz.txt" => "baz.txt" 7666 7667 {{source_name_part}} 7668 The filename part of the source file with no directory or extension. This 7669 will generally be used for specifying a transformation from a source file 7670 to a destination file with the same name but different extension. 7671 "//foo/bar/baz.txt" => "baz" 7672 7673 {{source_dir}} 7674 The directory (*) containing the source file with no trailing slash. 7675 "//foo/bar/baz.txt" => "../../foo/bar" 7676 7677 {{source_root_relative_dir}} 7678 The path to the source file's directory relative to the source root, with 7679 no leading "//" or trailing slashes. If the path is system-absolute, 7680 (beginning in a single slash) this will just return the path with no 7681 trailing slash. This value will always be the same, regardless of whether 7682 it appears in the "outputs" or "args" section. 7683 "//foo/bar/baz.txt" => "foo/bar" 7684 7685 {{source_gen_dir}} 7686 The generated file directory (*) corresponding to the source file's path. 7687 This will be different than the target's generated file directory if the 7688 source file is in a different directory than the BUILD.gn file. 7689 "//foo/bar/baz.txt" => "gen/foo/bar" 7690 7691 {{source_out_dir}} 7692 The object file directory (*) corresponding to the source file's path, 7693 relative to the build directory. this us be different than the target's 7694 out directory if the source file is in a different directory than the 7695 build.gn file. 7696 "//foo/bar/baz.txt" => "obj/foo/bar" 7697 7698 {{source_target_relative}} 7699 The path to the source file relative to the target's directory. This will 7700 generally be used for replicating the source directory layout in the 7701 output directory. This can only be used in actions and bundle_data 7702 targets. It is an error to use in process_file_template where there is no 7703 "target". 7704 "//foo/bar/baz.txt" => "baz.txt" 7705``` 7706 7707#### **(*) Note on directories** 7708 7709``` 7710 Paths containing directories (except the source_root_relative_dir) will be 7711 different depending on what context the expansion is evaluated in. Generally 7712 it should "just work" but it means you can't concatenate strings containing 7713 these values with reasonable results. 7714 7715 Details: source expansions can be used in the "outputs" variable, the "args" 7716 variable, and in calls to "process_file_template". The "args" are passed to a 7717 script which is run from the build directory, so these directories will 7718 relative to the build directory for the script to find. In the other cases, 7719 the directories will be source- absolute (begin with a "//") because the 7720 results of those expansions will be handled by GN internally. 7721``` 7722 7723#### **Examples** 7724 7725``` 7726 Non-varying outputs: 7727 action("hardcoded_outputs") { 7728 sources = [ "input1.idl", "input2.idl" ] 7729 outputs = [ "$target_out_dir/output1.dat", 7730 "$target_out_dir/output2.dat" ] 7731 } 7732 The outputs in this case will be the two literal files given. 7733 7734 Varying outputs: 7735 action_foreach("varying_outputs") { 7736 sources = [ "input1.idl", "input2.idl" ] 7737 outputs = [ "{{source_gen_dir}}/{{source_name_part}}.h", 7738 "{{source_gen_dir}}/{{source_name_part}}.cc" ] 7739 } 7740 Performing source expansion will result in the following output names: 7741 //out/Debug/obj/mydirectory/input1.h 7742 //out/Debug/obj/mydirectory/input1.cc 7743 //out/Debug/obj/mydirectory/input2.h 7744 //out/Debug/obj/mydirectory/input2.cc 7745``` 7746### <a name="switch_list"></a>**Available global switches** 7747 7748``` 7749 Do "gn help --the_switch_you_want_help_on" for more. Individual commands may 7750 take command-specific switches not listed here. See the help on your specific 7751 command for more. 7752``` 7753``` 7754 * --args: Specifies build arguments overrides. 7755 * --color: Force colored output. 7756 * --dotfile: Override the name of the ".gn" file. 7757 * --fail-on-unused-args: Treat unused build args as fatal errors. 7758 * --markdown: Write help output in the Markdown format. 7759 * --nocolor: Force non-colored output. 7760 * -q: Quiet mode. Don't print output on success. 7761 * --root: Explicitly specify source root. 7762 * --runtime-deps-list-file: Save runtime dependencies for targets in file. 7763 * --script-executable: Set the executable used to execute scripts. 7764 * --threads: Specify number of worker threads. 7765 * --time: Outputs a summary of how long everything took. 7766 * --tracelog: Writes a Chrome-compatible trace log to the given file. 7767 * -v: Verbose logging. 7768 * --version: Prints the GN version number and exits. 7769``` 7770 7771