OLD | NEW |
1 # GN Reference | 1 # GN Reference |
2 | 2 |
3 *This page is automatically generated from* `gn help --markdown all`. | 3 *This page is automatically generated from* `gn help --markdown all`. |
4 | 4 |
5 ## **\--args**: Specifies build arguments overrides. | 5 ## **\--args**: Specifies build arguments overrides. |
6 | 6 |
7 ``` | 7 ``` |
8 See "gn help buildargs" for an overview of how build arguments work. | 8 See "gn help buildargs" for an overview of how build arguments work. |
9 | 9 |
10 Most operations take a build directory. The build arguments are taken | 10 Most operations take a build directory. The build arguments are taken |
(...skipping 263 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
274 gn args --list --args="os=\"android\" enable_doom_melon=true" | 274 gn args --list --args="os=\"android\" enable_doom_melon=true" |
275 Prints all arguments with the default values for a build with the | 275 Prints all arguments with the default values for a build with the |
276 given arguments set (which may affect the values of other | 276 given arguments set (which may affect the values of other |
277 arguments). | 277 arguments). |
278 | 278 |
279 | 279 |
280 ``` | 280 ``` |
281 ## **gn check <out_dir> [<label_pattern>] [\--force]** | 281 ## **gn check <out_dir> [<label_pattern>] [\--force]** |
282 | 282 |
283 ``` | 283 ``` |
| 284 GN's include header checker validates that the includes for C-like |
| 285 source files match the build dependency graph. |
| 286 |
284 "gn check" is the same thing as "gn gen" with the "--check" flag | 287 "gn check" is the same thing as "gn gen" with the "--check" flag |
285 except that this command does not write out any build files. It's | 288 except that this command does not write out any build files. It's |
286 intended to be an easy way to manually trigger include file checking. | 289 intended to be an easy way to manually trigger include file checking. |
287 | 290 |
288 The <label_pattern> can take exact labels or patterns that match more | 291 The <label_pattern> can take exact labels or patterns that match more |
289 than one (although not general regular expressions). If specified, | 292 than one (although not general regular expressions). If specified, |
290 only those matching targets will be checked. See | 293 only those matching targets will be checked. See |
291 "gn help label_pattern" for details. | 294 "gn help label_pattern" for details. |
292 | 295 |
293 The .gn file may specify a list of targets to be checked. Only these | |
294 targets will be checked if no label_pattern is specified on the | |
295 command line. Otherwise, the command-line list is used instead. See | |
296 "gn help dotfile". | |
297 | |
298 ``` | 296 ``` |
299 | 297 |
300 ### **Command-specific switches** | 298 ### **Command-specific switches** |
301 | 299 |
302 ``` | 300 ``` |
303 --force | 301 --force |
304 Ignores specifications of "check_includes = false" and checks | 302 Ignores specifications of "check_includes = false" and checks |
305 all target's files that match the target label. | 303 all target's files that match the target label. |
306 | 304 |
307 ``` | 305 ``` |
308 | 306 |
| 307 ### **What gets checked** |
| 308 |
| 309 ``` |
| 310 The .gn file may specify a list of targets to be checked. Only these |
| 311 targets will be checked if no label_pattern is specified on the |
| 312 command line. Otherwise, the command-line list is used instead. See |
| 313 "gn help dotfile". |
| 314 |
| 315 Targets can opt-out from checking with "check_includes = false" |
| 316 (see "gn help check_includes"). |
| 317 |
| 318 For targets being checked: |
| 319 |
| 320 - GN opens all C-like source files in the targets to be checked and |
| 321 scans the top for includes. |
| 322 |
| 323 - Includes with a "nogncheck" annotation are skipped (see |
| 324 "gn help nogncheck"). |
| 325 |
| 326 - Only includes using "quotes" are checked. <brackets> are assumed |
| 327 to be system includes. |
| 328 |
| 329 - Include paths are assumed to be relative to either the source root |
| 330 or the "root_gen_dir" and must include all the path components. |
| 331 (It might be nice in the future to incorporate GN's knowledge of |
| 332 the include path to handle other include styles.) |
| 333 |
| 334 - GN does not run the preprocessor so will not understand |
| 335 conditional includes. |
| 336 |
| 337 - Only includes matching known files in the build are checked: |
| 338 includes matching unknown paths are ignored. |
| 339 |
| 340 For an include to be valid: |
| 341 |
| 342 - The included file must be in the current target, or there must |
| 343 be a path following only public dependencies to a target with the |
| 344 file in it ("gn path" is a good way to diagnose problems). |
| 345 |
| 346 - There can be multiple targets with an included file: only one |
| 347 needs to be valid for the include to be allowed. |
| 348 |
| 349 - If there are only "sources" in a target, all are considered to |
| 350 be public and can be included by other targets with a valid public |
| 351 dependency path. |
| 352 |
| 353 - If a target lists files as "public", only those files are |
| 354 able to be included by other targets. Anything in the sources |
| 355 will be considered private and will not be includable regardless |
| 356 of dependency paths. |
| 357 |
| 358 - Ouptuts from actions are treated like public sources on that |
| 359 target. |
| 360 |
| 361 - A target can include headers from a target that depends on it |
| 362 if the other target is annotated accordingly. See |
| 363 "gn help allow_circular_includes_from". |
| 364 |
| 365 ``` |
| 366 |
| 367 ### **Advice on fixing problems** |
| 368 |
| 369 ``` |
| 370 If you have a third party project that uses relative includes, |
| 371 it's generally best to exclude that target from checking altogether |
| 372 via "check_includes = false". |
| 373 |
| 374 If you have conditional includes, make sure the build conditions |
| 375 and the preprocessor conditions match, and annotate the line with |
| 376 "nogncheck" (see "gn help nogncheck" for an example). |
| 377 |
| 378 If two targets are hopelessly intertwined, use the |
| 379 "allow_circular_includes_from" annotation. Ideally each should have |
| 380 identical dependencies so configs inherited from those dependencies |
| 381 are consistent (see "gn help allow_circular_includes_from"). |
| 382 |
| 383 If you have a standalone header file or files that need to be shared |
| 384 between a few targets, you can consider making a source_set listing |
| 385 only those headers as public sources. With only header files, the |
| 386 source set will be a no-op from a build perspective, but will give a |
| 387 central place to refer to those headers. That source set's files |
| 388 will still need to pass "gn check" in isolation. |
| 389 |
| 390 In rare cases it makes sense to list a header in more than one |
| 391 target if it could be considered conceptually a member of both. |
| 392 |
| 393 ``` |
| 394 |
309 ### **Examples** | 395 ### **Examples** |
310 | 396 |
311 ``` | 397 ``` |
312 gn check out/Debug | 398 gn check out/Debug |
313 Check everything. | 399 Check everything. |
314 | 400 |
315 gn check out/Default //foo:bar | 401 gn check out/Default //foo:bar |
316 Check only the files in the //foo:bar target. | 402 Check only the files in the //foo:bar target. |
317 | 403 |
318 gn check out/Default "//foo/* | 404 gn check out/Default "//foo/* |
(...skipping 168 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
487 Shows defines set for the //base:base target, annotated by where | 573 Shows defines set for the //base:base target, annotated by where |
488 each one was set from. | 574 each one was set from. |
489 | 575 |
490 | 576 |
491 ``` | 577 ``` |
492 ## **gn format [\--dump-tree] [\--in-place] [\--stdin] BUILD.gn** | 578 ## **gn format [\--dump-tree] [\--in-place] [\--stdin] BUILD.gn** |
493 | 579 |
494 ``` | 580 ``` |
495 Formats .gn file to a standard format. | 581 Formats .gn file to a standard format. |
496 | 582 |
| 583 The contents of some lists ('sources', 'deps', etc.) will be sorted to |
| 584 a canonical order. To suppress this, you can add a comment of the form |
| 585 "# NOSORT" immediately preceeding the assignment. e.g. |
| 586 |
| 587 # NOSORT |
| 588 sources = [ |
| 589 "z.cc", |
| 590 "a.cc", |
| 591 ] |
| 592 |
497 ``` | 593 ``` |
498 | 594 |
499 ### **Arguments** | 595 ### **Arguments** |
500 ``` | 596 ``` |
501 --dry-run | 597 --dry-run |
502 Does not change or output anything, but sets the process exit code | 598 Does not change or output anything, but sets the process exit code |
503 based on whether output would be different than what's on disk. | 599 based on whether output would be different than what's on disk. |
504 This is useful for presubmit/lint-type checks. | 600 This is useful for presubmit/lint-type checks. |
505 - Exit code 0: successful format, matches on disk. | 601 - Exit code 0: successful format, matches on disk. |
506 - Exit code 1: general failure (parse error, etc.) | 602 - Exit code 1: general failure (parse error, etc.) |
(...skipping 2989 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3496 | 3592 |
3497 | 3593 |
3498 ``` | 3594 ``` |
3499 ## **allow_circular_includes_from**: Permit includes from deps. | 3595 ## **allow_circular_includes_from**: Permit includes from deps. |
3500 | 3596 |
3501 ``` | 3597 ``` |
3502 A list of target labels. Must be a subset of the target's "deps". | 3598 A list of target labels. Must be a subset of the target's "deps". |
3503 These targets will be permitted to include headers from the current | 3599 These targets will be permitted to include headers from the current |
3504 target despite the dependency going in the opposite direction. | 3600 target despite the dependency going in the opposite direction. |
3505 | 3601 |
| 3602 When you use this, both targets must be included in a final binary |
| 3603 for it to link. To keep linker errors from happening, it is good |
| 3604 practice to have all external dependencies depend only on one of |
| 3605 the two targets, and to set the visibility on the other to enforce |
| 3606 this. Thus the targets will always be linked together in any output. |
| 3607 |
3506 ``` | 3608 ``` |
3507 | 3609 |
3508 ### **Tedious exposition** | 3610 ### **Details** |
3509 | 3611 |
3510 ``` | 3612 ``` |
3511 Normally, for a file in target A to include a file from target B, | 3613 Normally, for a file in target A to include a file from target B, |
3512 A must list B as a dependency. This invariant is enforced by the | 3614 A must list B as a dependency. This invariant is enforced by the |
3513 "gn check" command (and the --check flag to "gn gen"). | 3615 "gn check" command (and the --check flag to "gn gen" -- see |
| 3616 "gn help check"). |
3514 | 3617 |
3515 Sometimes, two targets might be the same unit for linking purposes | 3618 Sometimes, two targets might be the same unit for linking purposes |
3516 (two source sets or static libraries that would always be linked | 3619 (two source sets or static libraries that would always be linked |
3517 together in a final executable or shared library). In this case, | 3620 together in a final executable or shared library) and they each |
3518 you want A to be able to include B's headers, and B to include A's | 3621 include headers from the other: you want A to be able to include B's |
3519 headers. | 3622 headers, and B to include A's headers. This is not an ideal situation |
| 3623 but is sometimes unavoidable. |
3520 | 3624 |
3521 This list, if specified, lists which of the dependencies of the | 3625 This list, if specified, lists which of the dependencies of the |
3522 current target can include header files from the current target. | 3626 current target can include header files from the current target. |
3523 That is, if A depends on B, B can only include headers from A if it is | 3627 That is, if A depends on B, B can only include headers from A if it is |
3524 in A's allow_circular_includes_from list. | 3628 in A's allow_circular_includes_from list. Normally includes must |
| 3629 follow the direction of dependencies, this flag allows them to go |
| 3630 in the opposite direction. |
3525 | 3631 |
3526 ``` | 3632 ``` |
3527 | 3633 |
| 3634 ### **Danger** |
| 3635 |
| 3636 ``` |
| 3637 In the above example, A's headers are likely to include headers from |
| 3638 A's dependencies. Those dependencies may have public_configs that |
| 3639 apply flags, defines, and include paths that make those headers work |
| 3640 properly. |
| 3641 |
| 3642 With allow_circular_includes_from, B can include A's headers, and |
| 3643 transitively from A's dependencies, without having the dependencies |
| 3644 that would bring in the public_configs those headers need. The result |
| 3645 may be errors or inconsistent builds. |
| 3646 |
| 3647 So when you use allow_circular_includes_from, make sure that any |
| 3648 compiler settings, flags, and include directories are the same between |
| 3649 both targets (consider putting such things in a shared config they can |
| 3650 both reference). Make sure the dependencies are also the same (you |
| 3651 might consider a group to collect such dependencies they both |
| 3652 depend on). |
| 3653 |
| 3654 ``` |
| 3655 |
3528 ### **Example** | 3656 ### **Example** |
3529 | 3657 |
3530 ``` | 3658 ``` |
3531 source_set("a") { | 3659 source_set("a") { |
3532 deps = [ ":b", ":c" ] | 3660 deps = [ ":b", ":a_b_shared_deps" ] |
3533 allow_circular_includes_from = [ ":b" ] | 3661 allow_circular_includes_from = [ ":b" ] |
3534 ... | 3662 ... |
3535 } | 3663 } |
3536 | 3664 |
| 3665 source_set("b") { |
| 3666 deps = [ ":a_b_shared_deps" ] |
| 3667 # Sources here can include headers from a despite lack of deps. |
| 3668 ... |
| 3669 } |
| 3670 |
| 3671 group("a_b_shared_deps") { |
| 3672 public_deps = [ ":c" ] |
| 3673 } |
| 3674 |
3537 | 3675 |
3538 ``` | 3676 ``` |
3539 ## **args**: Arguments passed to an action. | 3677 ## **args**: Arguments passed to an action. |
3540 | 3678 |
3541 ``` | 3679 ``` |
3542 For action and action_foreach targets, args is the list of arguments | 3680 For action and action_foreach targets, args is the list of arguments |
3543 to pass to the script. Typically you would use source expansion (see | 3681 to pass to the script. Typically you would use source expansion (see |
3544 "gn help source_expansion") to insert the source file names. | 3682 "gn help source_expansion") to insert the source file names. |
3545 | 3683 |
3546 See also "gn help action" and "gn help action_foreach". | 3684 See also "gn help action" and "gn help action_foreach". |
(...skipping 326 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3873 | 4011 |
3874 ``` | 4012 ``` |
3875 When true (the default), the "gn check" command (as well as | 4013 When true (the default), the "gn check" command (as well as |
3876 "gn gen" with the --check flag) will check this target's sources | 4014 "gn gen" with the --check flag) will check this target's sources |
3877 and headers for proper dependencies. | 4015 and headers for proper dependencies. |
3878 | 4016 |
3879 When false, the files in this target will be skipped by default. | 4017 When false, the files in this target will be skipped by default. |
3880 This does not affect other targets that depend on the current target, | 4018 This does not affect other targets that depend on the current target, |
3881 it just skips checking the includes of the current target's files. | 4019 it just skips checking the includes of the current target's files. |
3882 | 4020 |
3883 ``` | 4021 If there are a few conditionally included headers that trip up |
| 4022 checking, you can exclude headers individually by annotating them with |
| 4023 "nogncheck" (see "gn help nogncheck"). |
3884 | 4024 |
3885 ### **Controlling includes individually** | 4025 The topic "gn help check" has general information on how checking |
3886 | 4026 works and advice on how to pass a check in problematic cases. |
3887 ``` | |
3888 If only certain includes are problematic, you can annotate them | |
3889 individually rather than disabling header checking on an entire | |
3890 target. Add the string "nogncheck" to the include line: | |
3891 | |
3892 #include "foo/something_weird.h" // nogncheck (bug 12345) | |
3893 | |
3894 It is good form to include a reference to a bug (if the include is | |
3895 improper, or some other comment expressing why the header checker | |
3896 doesn't work for this particular case. | |
3897 | |
3898 The most common reason to need "nogncheck" is conditional includes. | |
3899 The header checker does not understand the preprocessor, so may flag | |
3900 some includes as improper even if the dependencies and #defines are | |
3901 always matched correctly: | |
3902 | |
3903 #if defined(ENABLE_DOOM_MELON) | |
3904 #include "doom_melon/beam_controller.h" // nogncheck | |
3905 #endif | |
3906 | 4027 |
3907 ``` | 4028 ``` |
3908 | 4029 |
3909 ### **Example** | 4030 ### **Example** |
3910 | 4031 |
3911 ``` | 4032 ``` |
3912 source_set("busted_includes") { | 4033 source_set("busted_includes") { |
3913 # This target's includes are messed up, exclude it from checking. | 4034 # This target's includes are messed up, exclude it from checking. |
3914 check_includes = false | 4035 check_includes = false |
3915 ... | 4036 ... |
(...skipping 10 matching lines...) Expand all Loading... |
3926 library) is reached. The final linkable target only links each static | 4047 library) is reached. The final linkable target only links each static |
3927 library once, even if it appears more than once in its dependency | 4048 library once, even if it appears more than once in its dependency |
3928 graph. | 4049 graph. |
3929 | 4050 |
3930 In some cases the static library might be the final desired output. | 4051 In some cases the static library might be the final desired output. |
3931 For example, you may be producing a static library for distribution to | 4052 For example, you may be producing a static library for distribution to |
3932 third parties. In this case, the static library should include code | 4053 third parties. In this case, the static library should include code |
3933 for all dependencies in one complete package. Since GN does not unpack | 4054 for all dependencies in one complete package. Since GN does not unpack |
3934 static libraries to forward their contents up the dependency chain, | 4055 static libraries to forward their contents up the dependency chain, |
3935 it is an error for complete static libraries to depend on other static | 4056 it is an error for complete static libraries to depend on other static |
| 4057 |
| 4058 In rare cases it makes sense to list a header in more than one |
| 4059 target if it could be considered conceptually a member of both. |
3936 libraries. | 4060 libraries. |
3937 | 4061 |
3938 ``` | 4062 ``` |
3939 | 4063 |
3940 ### **Example** | 4064 ### **Example** |
3941 | 4065 |
3942 ``` | 4066 ``` |
3943 static_library("foo") { | 4067 static_library("foo") { |
3944 complete_static_lib = true | 4068 complete_static_lib = true |
3945 deps = [ "bar" ] | 4069 deps = [ "bar" ] |
(...skipping 1418 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5364 ":*(//build/toolchain/linux:32bit)" | 5488 ":*(//build/toolchain/linux:32bit)" |
5365 All targets in the current build file using the 32-bit Linux | 5489 All targets in the current build file using the 32-bit Linux |
5366 toolchain. | 5490 toolchain. |
5367 | 5491 |
5368 "//foo/*(//build/toolchain:win)" | 5492 "//foo/*(//build/toolchain:win)" |
5369 All targets in //foo and any subdirectory using the Windows | 5493 All targets in //foo and any subdirectory using the Windows |
5370 toolchain. | 5494 toolchain. |
5371 | 5495 |
5372 | 5496 |
5373 ``` | 5497 ``` |
| 5498 ## **nogncheck**: Skip an include line from checking. |
| 5499 |
| 5500 ``` |
| 5501 GN's header checker helps validate that the includes match the build |
| 5502 dependency graph. Sometimes an include might be conditional or |
| 5503 otherwise problematic, but you want to specifically allow it. In this |
| 5504 case, it can be whitelisted. |
| 5505 |
| 5506 Include lines containing the substring "nogncheck" will be excluded |
| 5507 from header checking. The most common case is a conditional include: |
| 5508 |
| 5509 #if defined(ENABLE_DOOM_MELON) |
| 5510 #include "tools/doom_melon/doom_melon.h" // nogncheck |
| 5511 #endif |
| 5512 |
| 5513 If the build file has a conditional dependency on the corresponding |
| 5514 target that matches the conditional include, everything will always |
| 5515 link correctly: |
| 5516 |
| 5517 source_set("mytarget") { |
| 5518 ... |
| 5519 if (enable_doom_melon) { |
| 5520 defines = [ "ENABLE_DOOM_MELON" ] |
| 5521 deps += [ "//tools/doom_melon" ] |
| 5522 } |
| 5523 |
| 5524 But GN's header checker does not understand preprocessor directives, |
| 5525 won't know it matches the build dependencies, and will flag this |
| 5526 include as incorrect when the condition is false. |
| 5527 |
| 5528 ``` |
| 5529 |
| 5530 ### **More information** |
| 5531 |
| 5532 ``` |
| 5533 The topic "gn help check" has general information on how checking |
| 5534 works and advice on fixing problems. Targets can also opt-out of |
| 5535 checking, see "gn help check_includes". |
| 5536 |
| 5537 |
| 5538 ``` |
5374 ## **Runtime dependencies** | 5539 ## **Runtime dependencies** |
5375 | 5540 |
5376 ``` | 5541 ``` |
5377 Runtime dependencies of a target are exposed via the "runtime_deps" | 5542 Runtime dependencies of a target are exposed via the "runtime_deps" |
5378 category of "gn desc" (see "gn help desc") or they can be written | 5543 category of "gn desc" (see "gn help desc") or they can be written |
5379 at build generation time via "--runtime-deps-list-file" | 5544 at build generation time via "--runtime-deps-list-file" |
5380 (see "gn help --runtime-deps-list-file"). | 5545 (see "gn help --runtime-deps-list-file"). |
5381 | 5546 |
5382 To a first approximation, the runtime dependencies of a target are | 5547 To a first approximation, the runtime dependencies of a target are |
5383 the set of "data" files, data directories, and the shared libraries | 5548 the set of "data" files, data directories, and the shared libraries |
(...skipping 202 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5586 ** -q**: Quiet mode. Don't print output on success. | 5751 ** -q**: Quiet mode. Don't print output on success. |
5587 ** \--root**: Explicitly specify source root. | 5752 ** \--root**: Explicitly specify source root. |
5588 ** \--runtime-deps-list-file**: Save runtime dependencies for targets in file. | 5753 ** \--runtime-deps-list-file**: Save runtime dependencies for targets in file. |
5589 ** \--threads**: Specify number of worker threads. | 5754 ** \--threads**: Specify number of worker threads. |
5590 ** \--time**: Outputs a summary of how long everything took. | 5755 ** \--time**: Outputs a summary of how long everything took. |
5591 ** \--tracelog**: Writes a Chrome-compatible trace log to the given file. | 5756 ** \--tracelog**: Writes a Chrome-compatible trace log to the given file. |
5592 ** -v**: Verbose logging. | 5757 ** -v**: Verbose logging. |
5593 ** \--version**: Prints the GN version number and exits. | 5758 ** \--version**: Prints the GN version number and exits. |
5594 | 5759 |
5595 ``` | 5760 ``` |
OLD | NEW |