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 418 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
429 | 429 |
430 ``` | 430 ``` |
431 ## **gn clean <out_dir>** | 431 ## **gn clean <out_dir>** |
432 | 432 |
433 ``` | 433 ``` |
434 Deletes the contents of the output directory except for args.gn and | 434 Deletes the contents of the output directory except for args.gn and |
435 creates a Ninja build environment sufficient to regenerate the build. | 435 creates a Ninja build environment sufficient to regenerate the build. |
436 | 436 |
437 | 437 |
438 ``` | 438 ``` |
439 ## **gn desc <out_dir> <target label> [<what to show>] [\--blame]** | 439 ## **gn desc <out_dir> <label or pattern> [<what to show>] [\--blame]** |
440 | 440 |
441 ``` | 441 ``` |
442 Displays information about a given labeled target for the given build. | 442 Displays information about a given target or config. The build |
443 The build parameters will be taken for the build in the given | 443 build parameters will be taken for the build in the given <out_dir>. |
444 <out_dir>. | 444 |
| 445 The <label or pattern> can be a target label, a config label, or a |
| 446 label pattern (see "gn help label_pattern"). A label pattern will |
| 447 only match targets. |
445 | 448 |
446 ``` | 449 ``` |
447 | 450 |
448 ### **Possibilities for <what to show>** | 451 ### **Possibilities for <what to show>** |
| 452 |
449 ``` | 453 ``` |
450 (If unspecified an overall summary will be displayed.) | 454 (If unspecified an overall summary will be displayed.) |
451 | 455 |
452 sources | 456 all_dependent_configs |
453 Source files. | 457 allow_circular_includes_from |
454 | 458 arflags [--blame] |
| 459 args |
| 460 cflags [--blame] |
| 461 cflags_cc [--blame] |
| 462 cflags_cxx [--blame] |
| 463 check_includes |
| 464 configs [--tree] (see below) |
| 465 defines [--blame] |
| 466 depfile |
| 467 deps [--all] [--tree] (see below) |
| 468 include_dirs [--blame] |
455 inputs | 469 inputs |
456 Additional input dependencies. | 470 ldflags [--blame] |
457 | |
458 public | |
459 Public header files. | |
460 | |
461 check_includes | |
462 Whether "gn check" checks this target for include usage. | |
463 | |
464 allow_circular_includes_from | |
465 Permit includes from these targets. | |
466 | |
467 visibility | |
468 Prints which targets can depend on this one. | |
469 | |
470 testonly | |
471 Whether this target may only be used in tests. | |
472 | |
473 configs | |
474 Shows configs applied to the given target, sorted in the order | |
475 they're specified. This includes both configs specified in the | |
476 "configs" variable, as well as configs pushed onto this target | |
477 via dependencies specifying "all" or "direct" dependent | |
478 configs. | |
479 | |
480 deps | |
481 Show immediate or recursive dependencies. See below for flags that | |
482 control deps printing. | |
483 | |
484 public_configs | |
485 all_dependent_configs | |
486 Shows the labels of configs applied to targets that depend on this | |
487 one (either directly or all of them). | |
488 | |
489 script | |
490 args | |
491 depfile | |
492 Actions only. The script and related values. | |
493 | |
494 outputs | |
495 Outputs for script and copy target types. | |
496 | |
497 defines [--blame] | |
498 include_dirs [--blame] | |
499 cflags [--blame] | |
500 cflags_cc [--blame] | |
501 cflags_cxx [--blame] | |
502 ldflags [--blame] | |
503 lib_dirs | 471 lib_dirs |
504 libs | 472 libs |
505 Shows the given values taken from the target and all configs | 473 outputs |
506 applying. See "--blame" below. | 474 public_configs |
| 475 public |
| 476 script |
| 477 sources |
| 478 testonly |
| 479 visibility |
507 | 480 |
508 runtime_deps | 481 runtime_deps |
509 Compute all runtime deps for the given target. This is a | 482 Compute all runtime deps for the given target. This is a |
510 computed list and does not correspond to any GN variable, unlike | 483 computed list and does not correspond to any GN variable, unlike |
511 most other values here. | 484 most other values here. |
512 | 485 |
513 The output is a list of file names relative to the build | 486 The output is a list of file names relative to the build |
514 directory. See "gn help runtime_deps" for how this is computed. | 487 directory. See "gn help runtime_deps" for how this is computed. |
515 This also works with "--blame" to see the source of the | 488 This also works with "--blame" to see the source of the |
516 dependency. | 489 dependency. |
517 | 490 |
518 ``` | 491 ``` |
519 | 492 |
520 ### **Shared flags** | 493 ### **Shared flags** |
521 | 494 |
522 ``` | 495 ``` |
523 --blame | 496 --all-toolchains |
524 Used with any value specified by a config, this will name | 497 Normally only inputs in the default toolchain will be included. |
525 the config that specified the value. This doesn't currently work | 498 This switch will turn on matching all toolchains. |
526 for libs and lib_dirs because those are inherited and are more | 499 |
527 complicated to figure out the blame (patches welcome). | 500 For example, a file is in a target might be compiled twice: |
| 501 once in the default toolchain and once in a secondary one. Without |
| 502 this flag, only the default toolchain one will be matched by |
| 503 wildcards. With this flag, both will be matched. |
528 | 504 |
529 ``` | 505 ``` |
530 | 506 |
531 ### **Flags that control how deps are printed** | 507 ### **Target flags** |
532 | 508 |
533 ``` | 509 ``` |
| 510 --blame |
| 511 Used with any value specified on a config, this will name |
| 512 the config that cause that target to get the flag. This doesn't |
| 513 currently work for libs and lib_dirs because those are inherited |
| 514 and are more complicated to figure out the blame (patches |
| 515 welcome). |
| 516 |
| 517 ``` |
| 518 |
| 519 ### **Configs** |
| 520 |
| 521 ``` |
| 522 The "configs" section will list all configs that apply. For targets |
| 523 this will include configs specified in the "configs" variable of |
| 524 the target, and also configs pushed onto this target via public |
| 525 or "all dependent" configs. |
| 526 |
| 527 Configs can have child configs. Specifying --tree will show the |
| 528 hierarchy. |
| 529 |
| 530 ``` |
| 531 |
| 532 ### **Printing deps** |
| 533 |
| 534 ``` |
| 535 Deps will include all public, private, and data deps (TODO this could |
| 536 be clarified and enhanced) sorted in order applying. The following |
| 537 may be used: |
| 538 |
534 --all | 539 --all |
535 Collects all recursive dependencies and prints a sorted flat list. | 540 Collects all recursive dependencies and prints a sorted flat list. |
536 Also usable with --tree (see below). | 541 Also usable with --tree (see below). |
537 | 542 |
538 --as=(buildfile|label|output) | 543 --as=(buildfile|label|output) |
539 How to print targets. | 544 How to print targets. |
540 | 545 |
541 buildfile | 546 buildfile |
542 Prints the build files where the given target was declared as | 547 Prints the build files where the given target was declared as |
543 file names. | 548 file names. |
(...skipping 209 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
753 buildfile | 758 buildfile |
754 Prints the build files where the given target was declared as | 759 Prints the build files where the given target was declared as |
755 file names. | 760 file names. |
756 label (default) | 761 label (default) |
757 Prints the label of the target. | 762 Prints the label of the target. |
758 output | 763 output |
759 Prints the first output file for the target relative to the | 764 Prints the first output file for the target relative to the |
760 root build directory. | 765 root build directory. |
761 | 766 |
762 --all-toolchains | 767 --all-toolchains |
763 Matches all toolchains. When set, if the label pattern does not | 768 Normally only inputs in the default toolchain will be included. |
764 specify an explicit toolchain, labels from all toolchains will be | 769 This switch will turn on matching all toolchains. |
765 matched. When unset, only targets in the default toolchain will | 770 |
766 be matched unless an explicit toolchain in the label is set. | 771 For example, a file is in a target might be compiled twice: |
| 772 once in the default toolchain and once in a secondary one. Without |
| 773 this flag, only the default toolchain one will be matched by |
| 774 wildcards. With this flag, both will be matched. |
767 | 775 |
768 --testonly=(true|false) | 776 --testonly=(true|false) |
769 Restrict outputs to targets with the testonly flag set | 777 Restrict outputs to targets with the testonly flag set |
770 accordingly. When unspecified, the target's testonly flags are | 778 accordingly. When unspecified, the target's testonly flags are |
771 ignored. | 779 ignored. |
772 | 780 |
773 --type=(action|copy|executable|group|loadable_module|shared_library| | 781 --type=(action|copy|executable|group|loadable_module|shared_library| |
774 source_set|static_library) | 782 source_set|static_library) |
775 Restrict outputs to targets matching the given type. If | 783 Restrict outputs to targets matching the given type. If |
776 unspecified, no filtering will be performed. | 784 unspecified, no filtering will be performed. |
(...skipping 108 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
885 all targets that depend directly or indirectly on that file. | 893 all targets that depend directly or indirectly on that file. |
886 | 894 |
887 When used with --tree, turns off eliding to show a complete tree. | 895 When used with --tree, turns off eliding to show a complete tree. |
888 | 896 |
889 --all-toolchains | 897 --all-toolchains |
890 Normally only inputs in the default toolchain will be included. | 898 Normally only inputs in the default toolchain will be included. |
891 This switch will turn on matching all toolchains. | 899 This switch will turn on matching all toolchains. |
892 | 900 |
893 For example, a file is in a target might be compiled twice: | 901 For example, a file is in a target might be compiled twice: |
894 once in the default toolchain and once in a secondary one. Without | 902 once in the default toolchain and once in a secondary one. Without |
895 this flag, only the default toolchain one will be matched and | 903 this flag, only the default toolchain one will be matched by |
896 printed (potentially with its recursive dependencies, depending on | 904 wildcards. With this flag, both will be matched. |
897 the other options). With this flag, both will be printed | |
898 (potentially with both of their recursive dependencies). | |
899 | 905 |
900 --as=(buildfile|label|output) | 906 --as=(buildfile|label|output) |
901 How to print targets. | 907 How to print targets. |
902 | 908 |
903 buildfile | 909 buildfile |
904 Prints the build files where the given target was declared as | 910 Prints the build files where the given target was declared as |
905 file names. | 911 file names. |
906 label (default) | 912 label (default) |
907 Prints the label of the target. | 913 Prints the label of the target. |
908 output | 914 output |
(...skipping 3248 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4157 A static library normally doesn't include code from dependencies, but | 4163 A static library normally doesn't include code from dependencies, but |
4158 instead forwards the static libraries and source sets in its deps up | 4164 instead forwards the static libraries and source sets in its deps up |
4159 the dependency chain until a linkable target (an executable or shared | 4165 the dependency chain until a linkable target (an executable or shared |
4160 library) is reached. The final linkable target only links each static | 4166 library) is reached. The final linkable target only links each static |
4161 library once, even if it appears more than once in its dependency | 4167 library once, even if it appears more than once in its dependency |
4162 graph. | 4168 graph. |
4163 | 4169 |
4164 In some cases the static library might be the final desired output. | 4170 In some cases the static library might be the final desired output. |
4165 For example, you may be producing a static library for distribution to | 4171 For example, you may be producing a static library for distribution to |
4166 third parties. In this case, the static library should include code | 4172 third parties. In this case, the static library should include code |
4167 for all dependencies in one complete package. Since GN does not unpack | 4173 for all dependencies in one complete package. However, complete static |
4168 static libraries to forward their contents up the dependency chain, | 4174 libraries themselves are never linked into other complete static |
4169 it is an error for complete static libraries to depend on other static | 4175 libraries. All complete static libraries are for distribution and |
| 4176 linking them in would cause code duplication in this case. If the |
| 4177 static library is not for distribution, it should not be complete. |
| 4178 |
| 4179 GN treats non-complete static libraries as source sets when they are |
| 4180 linked into complete static libraries. This is done because some tools |
| 4181 like AR do not handle dependent static libraries properly. This makes |
| 4182 it easier to write "alink" rules. |
4170 | 4183 |
4171 In rare cases it makes sense to list a header in more than one | 4184 In rare cases it makes sense to list a header in more than one |
4172 target if it could be considered conceptually a member of both. | 4185 target if it could be considered conceptually a member of both. |
4173 libraries. | 4186 libraries. |
4174 | 4187 |
4175 ``` | 4188 ``` |
4176 | 4189 |
4177 ### **Example** | 4190 ### **Example** |
4178 | 4191 |
4179 ``` | 4192 ``` |
(...skipping 143 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4323 such as copying them to the output directory. This is just used for | 4336 such as copying them to the output directory. This is just used for |
4324 declaring runtime dependencies. Runtime dependencies can be queried | 4337 declaring runtime dependencies. Runtime dependencies can be queried |
4325 using the "runtime_deps" category of "gn desc" or written during | 4338 using the "runtime_deps" category of "gn desc" or written during |
4326 build generation via "--runtime-deps-list-file". | 4339 build generation via "--runtime-deps-list-file". |
4327 | 4340 |
4328 GN doesn't require data files to exist at build-time. So actions that | 4341 GN doesn't require data files to exist at build-time. So actions that |
4329 produce files that are in turn runtime dependencies can list those | 4342 produce files that are in turn runtime dependencies can list those |
4330 generated files both in the "outputs" list as well as the "data" | 4343 generated files both in the "outputs" list as well as the "data" |
4331 list. | 4344 list. |
4332 | 4345 |
4333 By convention, directories are be listed with a trailing slash: | 4346 By convention, directories are listed with a trailing slash: |
4334 data = [ "test/data/" ] | 4347 data = [ "test/data/" ] |
4335 However, no verification is done on these so GN doesn't enforce this. | 4348 However, no verification is done on these so GN doesn't enforce this. |
4336 The paths are just rebased and passed along when requested. | 4349 The paths are just rebased and passed along when requested. |
4337 | 4350 |
4338 See "gn help runtime_deps" for how these are used. | 4351 See "gn help runtime_deps" for how these are used. |
4339 | 4352 |
4340 | 4353 |
4341 ``` | 4354 ``` |
4342 ## **data_deps**: Non-linked dependencies. | 4355 ## **data_deps**: Non-linked dependencies. |
4343 | 4356 |
(...skipping 1609 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5953 ** -q**: Quiet mode. Don't print output on success. | 5966 ** -q**: Quiet mode. Don't print output on success. |
5954 ** \--root**: Explicitly specify source root. | 5967 ** \--root**: Explicitly specify source root. |
5955 ** \--runtime-deps-list-file**: Save runtime dependencies for targets in file. | 5968 ** \--runtime-deps-list-file**: Save runtime dependencies for targets in file. |
5956 ** \--threads**: Specify number of worker threads. | 5969 ** \--threads**: Specify number of worker threads. |
5957 ** \--time**: Outputs a summary of how long everything took. | 5970 ** \--time**: Outputs a summary of how long everything took. |
5958 ** \--tracelog**: Writes a Chrome-compatible trace log to the given file. | 5971 ** \--tracelog**: Writes a Chrome-compatible trace log to the given file. |
5959 ** -v**: Verbose logging. | 5972 ** -v**: Verbose logging. |
5960 ** \--version**: Prints the GN version number and exits. | 5973 ** \--version**: Prints the GN version number and exits. |
5961 | 5974 |
5962 ``` | 5975 ``` |
OLD | NEW |