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