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 from | 10 Most operations take a build directory. The build arguments are taken from |
(...skipping 19 matching lines...) Expand all Loading... |
30 ``` | 30 ``` |
31 gn gen out/Default --args="foo=\"bar\"" | 31 gn gen out/Default --args="foo=\"bar\"" |
32 | 32 |
33 gn gen out/Default --args='foo="bar" enable=true blah=7' | 33 gn gen out/Default --args='foo="bar" enable=true blah=7' |
34 | 34 |
35 gn check out/Default --args="" | 35 gn check out/Default --args="" |
36 Clears existing build args from the directory. | 36 Clears existing build args from the directory. |
37 | 37 |
38 gn desc out/Default --args="some_list=[1, false, \"foo\"]" | 38 gn desc out/Default --args="some_list=[1, false, \"foo\"]" |
39 | 39 |
| 40 |
40 ``` | 41 ``` |
41 ## **\--[no]color**: Forces colored output on or off. | 42 ## **\--[no]color**: Forces colored output on or off. |
42 | 43 |
43 ``` | 44 ``` |
44 Normally GN will try to detect whether it is outputting to a terminal | 45 Normally GN will try to detect whether it is outputting to a terminal |
45 and will enable or disable color accordingly. Use of these switches | 46 and will enable or disable color accordingly. Use of these switches |
46 will override the default. | 47 will override the default. |
47 | 48 |
48 ``` | 49 ``` |
49 | 50 |
50 ### **Examples** | 51 ### **Examples** |
51 | 52 |
52 ``` | 53 ``` |
53 gn gen out/Default --color | 54 gn gen out/Default --color |
54 | 55 |
55 gn gen out/Default --nocolor | 56 gn gen out/Default --nocolor |
56 | 57 |
57 | 58 |
58 ``` | 59 ``` |
59 ## **\--dotfile**: Override the name of the ".gn" file. | 60 ## **\--dotfile**: Override the name of the ".gn" file. |
60 | 61 |
61 ``` | 62 ``` |
62 Normally GN loads the ".gn"file from the source root for some basic | 63 Normally GN loads the ".gn"file from the source root for some basic |
63 configuration (see "gn help dotfile"). This flag allows you to | 64 configuration (see "gn help dotfile"). This flag allows you to |
64 use a different file. | 65 use a different file. |
65 | 66 |
66 Note that this interacts with "--root" in a possibly incorrect way. | 67 Note that this interacts with "--root" in a possibly incorrect way. |
67 It would be nice to test the edge cases and document or fix. | 68 It would be nice to test the edge cases and document or fix. |
68 | 69 |
| 70 |
69 ``` | 71 ``` |
70 ## **\--fail-on-unused-args**: Treat unused build args as fatal errors. | 72 ## **\--fail-on-unused-args**: Treat unused build args as fatal errors. |
71 | 73 |
72 ``` | 74 ``` |
73 If you set a value in a build's "gn args" and never use it in the build (in | 75 If you set a value in a build's "gn args" and never use it in the build (in |
74 a declare_args() block), GN will normally print an error but not fail the | 76 a declare_args() block), GN will normally print an error but not fail the |
75 build. | 77 build. |
76 | 78 |
77 In many cases engineers would use build args to enable or disable features | 79 In many cases engineers would use build args to enable or disable features |
78 that would sometimes get removed. It would by annoying to block work for | 80 that would sometimes get removed. It would by annoying to block work for |
79 typically benign problems. In Chrome in particular, flags might be configured | 81 typically benign problems. In Chrome in particular, flags might be configured |
80 for build bots in a separate infrastructure repository, or a declare_args | 82 for build bots in a separate infrastructure repository, or a declare_args |
81 block might be changed in a third party repository. Treating these errors as | 83 block might be changed in a third party repository. Treating these errors as |
82 blocking forced complex multi- way patches to land what would otherwise be | 84 blocking forced complex multi- way patches to land what would otherwise be |
83 simple changes. | 85 simple changes. |
84 | 86 |
85 In some cases, such concerns are not as important, and a mismatch in build | 87 In some cases, such concerns are not as important, and a mismatch in build |
86 flags between the invoker of the build and the build files represents a | 88 flags between the invoker of the build and the build files represents a |
87 critical mismatch that should be immediately fixed. Such users can set this | 89 critical mismatch that should be immediately fixed. Such users can set this |
88 flag to force GN to fail in that case. | 90 flag to force GN to fail in that case. |
89 | 91 |
| 92 |
90 ``` | 93 ``` |
91 ## **\--markdown**: Write help output in the Markdown format. | 94 ## **\--markdown**: Write help output in the Markdown format. |
92 | 95 |
93 ## **\--[no]color**: Forces colored output on or off. | 96 ## **\--[no]color**: Forces colored output on or off. |
94 | 97 |
95 ``` | 98 ``` |
96 Normally GN will try to detect whether it is outputting to a terminal | 99 Normally GN will try to detect whether it is outputting to a terminal |
97 and will enable or disable color accordingly. Use of these switches | 100 and will enable or disable color accordingly. Use of these switches |
98 will override the default. | 101 will override the default. |
99 | 102 |
100 ``` | 103 ``` |
101 | 104 |
102 ### **Examples** | 105 ### **Examples** |
103 | 106 |
104 ``` | 107 ``` |
105 gn gen out/Default --color | 108 gn gen out/Default --color |
106 | 109 |
107 gn gen out/Default --nocolor | 110 gn gen out/Default --nocolor |
108 | 111 |
109 | 112 |
110 ``` | 113 ``` |
111 ## **-q**: Quiet mode. Don't print output on success. | 114 ## **-q**: Quiet mode. Don't print output on success. |
112 | 115 |
113 ``` | 116 ``` |
114 This is useful when running as a part of another script. | 117 This is useful when running as a part of another script. |
115 | 118 |
| 119 |
116 ``` | 120 ``` |
117 ## **\--root**: Explicitly specify source root. | 121 ## **\--root**: Explicitly specify source root. |
118 | 122 |
119 ``` | 123 ``` |
120 Normally GN will look up in the directory tree from the current directory to | 124 Normally GN will look up in the directory tree from the current directory to |
121 find a ".gn" file. The source root directory specifies the meaning of "//" | 125 find a ".gn" file. The source root directory specifies the meaning of "//" |
122 beginning with paths, and the BUILD.gn file in that directory will be the | 126 beginning with paths, and the BUILD.gn file in that directory will be the |
123 first thing loaded. | 127 first thing loaded. |
124 | 128 |
125 Specifying --root allows GN to do builds in a specific directory regardless | 129 Specifying --root allows GN to do builds in a specific directory regardless |
126 of the current directory. | 130 of the current directory. |
127 | 131 |
128 ``` | 132 ``` |
129 | 133 |
130 ### **Examples** | 134 ### **Examples** |
131 | 135 |
132 ``` | 136 ``` |
133 gn gen //out/Default --root=/home/baracko/src | 137 gn gen //out/Default --root=/home/baracko/src |
134 | 138 |
135 gn desc //out/Default --root="C:\Users\BObama\My Documents\foo" | 139 gn desc //out/Default --root="C:\Users\BObama\My Documents\foo" |
136 | 140 |
| 141 |
137 ``` | 142 ``` |
138 ## **\--runtime-deps-list-file**: Save runtime dependencies for targets in file. | 143 ## **\--runtime-deps-list-file**: Save runtime dependencies for targets in file. |
139 | 144 |
140 ``` | 145 ``` |
141 --runtime-deps-list-file=<filename> | 146 --runtime-deps-list-file=<filename> |
142 | 147 |
143 Where <filename> is a text file consisting of the labels, one per line, of | 148 Where <filename> is a text file consisting of the labels, one per line, of |
144 the targets for which runtime dependencies are desired. | 149 the targets for which runtime dependencies are desired. |
145 | 150 |
146 See "gn help runtime_deps" for a description of how runtime dependencies are | 151 See "gn help runtime_deps" for a description of how runtime dependencies are |
(...skipping 13 matching lines...) Expand all Loading... |
160 | 165 |
161 If a source set, action, copy, or group is listed, the runtime deps file will | 166 If a source set, action, copy, or group is listed, the runtime deps file will |
162 correspond to the .stamp file corresponding to that target. This is probably | 167 correspond to the .stamp file corresponding to that target. This is probably |
163 not useful; the use-case for this feature is generally executable targets. | 168 not useful; the use-case for this feature is generally executable targets. |
164 | 169 |
165 The runtime dependency file will list one file per line, with no escaping. | 170 The runtime dependency file will list one file per line, with no escaping. |
166 The files will be relative to the root_build_dir. The first line of the file | 171 The files will be relative to the root_build_dir. The first line of the file |
167 will be the main output file of the target itself (in the above example, | 172 will be the main output file of the target itself (in the above example, |
168 "bar.so"). | 173 "bar.so"). |
169 | 174 |
| 175 |
170 ``` | 176 ``` |
171 ## **\--script-executable**: Set the executable used to execute scripts. | 177 ## **\--script-executable**: Set the executable used to execute scripts. |
172 | 178 |
173 ``` | 179 ``` |
174 By default GN searches the PATH for Python to execute scripts in action | 180 By default GN searches the PATH for Python to execute scripts in action |
175 targets and exec_script calls. This flag allows the specification of a | 181 targets and exec_script calls. This flag allows the specification of a |
176 specific Python executable or potentially a different language | 182 specific Python executable or potentially a different language |
177 interpreter. | 183 interpreter. |
178 | 184 |
| 185 |
179 ``` | 186 ``` |
180 ## **\--threads**: Specify number of worker threads. | 187 ## **\--threads**: Specify number of worker threads. |
181 | 188 |
182 ``` | 189 ``` |
183 GN runs many threads to load and run build files. This can make debugging | 190 GN runs many threads to load and run build files. This can make debugging |
184 challenging. Or you may want to experiment with different values to see how | 191 challenging. Or you may want to experiment with different values to see how |
185 it affects performance. | 192 it affects performance. |
186 | 193 |
187 The parameter is the number of worker threads. This does not count the main | 194 The parameter is the number of worker threads. This does not count the main |
188 thread (so there are always at least two). | 195 thread (so there are always at least two). |
189 | 196 |
190 ``` | 197 ``` |
191 | 198 |
192 ### **Examples** | 199 ### **Examples** |
193 | 200 |
194 ``` | 201 ``` |
195 gen gen out/Default --threads=1 | 202 gen gen out/Default --threads=1 |
196 | 203 |
| 204 |
197 ``` | 205 ``` |
198 ## **\--time**: Outputs a summary of how long everything took. | 206 ## **\--time**: Outputs a summary of how long everything took. |
199 | 207 |
200 ``` | 208 ``` |
201 Hopefully self-explanatory. | 209 Hopefully self-explanatory. |
202 | 210 |
203 ``` | 211 ``` |
204 | 212 |
205 ### **Examples** | 213 ### **Examples** |
206 | 214 |
207 ``` | 215 ``` |
208 gn gen out/Default --time | 216 gn gen out/Default --time |
209 | 217 |
| 218 |
210 ``` | 219 ``` |
211 ## **\--tracelog**: Writes a Chrome-compatible trace log to the given file. | 220 ## **\--tracelog**: Writes a Chrome-compatible trace log to the given file. |
212 | 221 |
213 ``` | 222 ``` |
214 The trace log will show file loads, executions, scripts, and writes. This | 223 The trace log will show file loads, executions, scripts, and writes. This |
215 allows performance analysis of the generation step. | 224 allows performance analysis of the generation step. |
216 | 225 |
217 To view the trace, open Chrome and navigate to "chrome://tracing/", then | 226 To view the trace, open Chrome and navigate to "chrome://tracing/", then |
218 press "Load" and specify the file you passed to this parameter. | 227 press "Load" and specify the file you passed to this parameter. |
219 | 228 |
220 ``` | 229 ``` |
221 | 230 |
222 ### **Examples** | 231 ### **Examples** |
223 | 232 |
224 ``` | 233 ``` |
225 gn gen out/Default --tracelog=mytrace.trace | 234 gn gen out/Default --tracelog=mytrace.trace |
226 | 235 |
| 236 |
227 ``` | 237 ``` |
228 ## **-v**: Verbose logging. | 238 ## **-v**: Verbose logging. |
229 | 239 |
230 ``` | 240 ``` |
231 This will spew logging events to the console for debugging issues. | 241 This will spew logging events to the console for debugging issues. |
232 | 242 |
233 Good luck! | 243 Good luck! |
234 | 244 |
| 245 |
235 ``` | 246 ``` |
236 ## **gn analyze <out_dir> <input_path> <output_path>** | 247 ## **gn analyze <out_dir> <input_path> <output_path>** |
237 | 248 |
238 ``` | 249 ``` |
239 Analyze which targets are affected by a list of files. | 250 Analyze which targets are affected by a list of files. |
240 | 251 |
241 This command takes three arguments: | 252 This command takes three arguments: |
242 | 253 |
243 out_dir is the path to the build directory. | 254 out_dir is the path to the build directory. |
244 | 255 |
(...skipping 51 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
296 a string describing the error. This includes cases where the input file is | 307 a string describing the error. This includes cases where the input file is |
297 not in the right format, or contains invalid targets. | 308 not in the right format, or contains invalid targets. |
298 | 309 |
299 The command returns 1 if it is unable to read the input file or write the | 310 The command returns 1 if it is unable to read the input file or write the |
300 output file, or if there is something wrong with the build such that gen | 311 output file, or if there is something wrong with the build such that gen |
301 would also fail, and 0 otherwise. In particular, it returns 0 even if the | 312 would also fail, and 0 otherwise. In particular, it returns 0 even if the |
302 "error" key is non-empty and a non-fatal error occurred. In other words, it | 313 "error" key is non-empty and a non-fatal error occurred. In other words, it |
303 tries really hard to always write something to the output JSON and convey | 314 tries really hard to always write something to the output JSON and convey |
304 errors that way rather than via return codes. | 315 errors that way rather than via return codes. |
305 | 316 |
| 317 |
306 ``` | 318 ``` |
307 ## **gn args <out_dir> [\--list] [\--short] [\--args]** | 319 ## **gn args <out_dir> [\--list] [\--short] [\--args]** |
308 | 320 |
309 ``` | 321 ``` |
310 See also "gn help buildargs" for a more high-level overview of how | 322 See also "gn help buildargs" for a more high-level overview of how |
311 build arguments work. | 323 build arguments work. |
312 | 324 |
313 ``` | 325 ``` |
314 | 326 |
315 ### **Usage** | 327 ### **Usage** |
(...skipping 45 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
361 gn args out/Debug --list=target_cpu | 373 gn args out/Debug --list=target_cpu |
362 Prints information about the "target_cpu" argument for the " | 374 Prints information about the "target_cpu" argument for the " |
363 "out/Debug | 375 "out/Debug |
364 build. | 376 build. |
365 | 377 |
366 gn args --list --args="os=\"android\" enable_doom_melon=true" | 378 gn args --list --args="os=\"android\" enable_doom_melon=true" |
367 Prints all arguments with the default values for a build with the | 379 Prints all arguments with the default values for a build with the |
368 given arguments set (which may affect the values of other | 380 given arguments set (which may affect the values of other |
369 arguments). | 381 arguments). |
370 | 382 |
| 383 |
371 ``` | 384 ``` |
372 ## **gn check <out_dir> [<label_pattern>] [\--force]** | 385 ## **gn check <out_dir> [<label_pattern>] [\--force]** |
373 | 386 |
374 ``` | 387 ``` |
375 GN's include header checker validates that the includes for C-like source | 388 GN's include header checker validates that the includes for C-like source |
376 files match the build dependency graph. | 389 files match the build dependency graph. |
377 | 390 |
378 "gn check" is the same thing as "gn gen" with the "--check" flag except that | 391 "gn check" is the same thing as "gn gen" with the "--check" flag except that |
379 this command does not write out any build files. It's intended to be an easy | 392 this command does not write out any build files. It's intended to be an easy |
380 way to manually trigger include file checking. | 393 way to manually trigger include file checking. |
(...skipping 102 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
483 ``` | 496 ``` |
484 gn check out/Debug | 497 gn check out/Debug |
485 Check everything. | 498 Check everything. |
486 | 499 |
487 gn check out/Default //foo:bar | 500 gn check out/Default //foo:bar |
488 Check only the files in the //foo:bar target. | 501 Check only the files in the //foo:bar target. |
489 | 502 |
490 gn check out/Default "//foo/* | 503 gn check out/Default "//foo/* |
491 Check only the files in targets in the //foo directory tree. | 504 Check only the files in targets in the //foo directory tree. |
492 | 505 |
| 506 |
493 ``` | 507 ``` |
494 ## **gn clean <out_dir>** | 508 ## **gn clean <out_dir>** |
495 | 509 |
496 ``` | 510 ``` |
497 Deletes the contents of the output directory except for args.gn and | 511 Deletes the contents of the output directory except for args.gn and |
498 creates a Ninja build environment sufficient to regenerate the build. | 512 creates a Ninja build environment sufficient to regenerate the build. |
499 | 513 |
500 | 514 |
501 ``` | 515 ``` |
502 ## **gn desc <out_dir> <label or pattern> [<what to show>] [\--blame] "** | 516 ## **gn desc <out_dir> <label or pattern> [<what to show>] [\--blame] "** |
(...skipping 155 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
658 Summarizes the given target. | 672 Summarizes the given target. |
659 | 673 |
660 gn desc out/Foo :base_unittests deps --tree | 674 gn desc out/Foo :base_unittests deps --tree |
661 Shows a dependency tree of the "base_unittests" project in | 675 Shows a dependency tree of the "base_unittests" project in |
662 the current directory. | 676 the current directory. |
663 | 677 |
664 gn desc out/Debug //base defines --blame | 678 gn desc out/Debug //base defines --blame |
665 Shows defines set for the //base:base target, annotated by where | 679 Shows defines set for the //base:base target, annotated by where |
666 each one was set from. | 680 each one was set from. |
667 | 681 |
| 682 |
668 ``` | 683 ``` |
669 ## **gn format [\--dump-tree] (\--stdin | <build_file>)** | 684 ## **gn format [\--dump-tree] (\--stdin | <build_file>)** |
670 | 685 |
671 ``` | 686 ``` |
672 Formats .gn file to a standard format. | 687 Formats .gn file to a standard format. |
673 | 688 |
674 The contents of some lists ('sources', 'deps', etc.) will be sorted to a | 689 The contents of some lists ('sources', 'deps', etc.) will be sorted to a |
675 canonical order. To suppress this, you can add a comment of the form "# | 690 canonical order. To suppress this, you can add a comment of the form "# |
676 NOSORT" immediately preceeding the assignment. e.g. | 691 NOSORT" immediately preceeding the assignment. e.g. |
677 | 692 |
(...skipping 26 matching lines...) Expand all Loading... |
704 | 719 |
705 ``` | 720 ``` |
706 | 721 |
707 ### **Examples** | 722 ### **Examples** |
708 ``` | 723 ``` |
709 gn format //some/BUILD.gn | 724 gn format //some/BUILD.gn |
710 gn format some\\BUILD.gn | 725 gn format some\\BUILD.gn |
711 gn format /abspath/some/BUILD.gn | 726 gn format /abspath/some/BUILD.gn |
712 gn format --stdin | 727 gn format --stdin |
713 | 728 |
| 729 |
714 ``` | 730 ``` |
715 ## **gn gen**: Generate ninja files. | 731 ## **gn gen**: Generate ninja files. |
716 | 732 |
717 ``` | 733 ``` |
718 gn gen [<ide options>] <out_dir> | 734 gn gen [<ide options>] <out_dir> |
719 | 735 |
720 Generates ninja files from the current tree and puts them in the given output | 736 Generates ninja files from the current tree and puts them in the given output |
721 directory. | 737 directory. |
722 | 738 |
723 The output directory can be a source-repo-absolute path name such as: | 739 The output directory can be a source-repo-absolute path name such as: |
(...skipping 96 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
820 | 836 |
821 --json-ide-script=<path_to_python_script> | 837 --json-ide-script=<path_to_python_script> |
822 Executes python script after the JSON file is generated. Path can be | 838 Executes python script after the JSON file is generated. Path can be |
823 project absolute (//), system absolute (/) or relative, in which case the | 839 project absolute (//), system absolute (/) or relative, in which case the |
824 output directory will be base. Path to generated JSON file will be first | 840 output directory will be base. Path to generated JSON file will be first |
825 argument when invoking script. | 841 argument when invoking script. |
826 | 842 |
827 --json-ide-script-args=<argument> | 843 --json-ide-script-args=<argument> |
828 Optional second argument that will passed to executed script. | 844 Optional second argument that will passed to executed script. |
829 | 845 |
| 846 |
830 ``` | 847 ``` |
831 ## **gn help <anything>** | 848 ## **gn help <anything>** |
832 | 849 |
833 ``` | 850 ``` |
834 Yo dawg, I heard you like help on your help so I put help on the help in the | 851 Yo dawg, I heard you like help on your help so I put help on the help in the |
835 help. | 852 help. |
836 | 853 |
837 You can also use "all" as the parameter to get all help at once. | 854 You can also use "all" as the parameter to get all help at once. |
838 | 855 |
839 ``` | 856 ``` |
840 | 857 |
841 ### **Switches** | 858 ### **Switches** |
842 | 859 |
843 ``` | 860 ``` |
844 --markdown | 861 --markdown |
845 Format output in markdown syntax. | 862 Format output in markdown syntax. |
846 | 863 |
847 ``` | 864 ``` |
848 | 865 |
849 ### **Example** | 866 ### **Example** |
850 | 867 |
851 ``` | 868 ``` |
852 gn help --markdown all | 869 gn help --markdown all |
853 Dump all help to stdout in markdown format. | 870 Dump all help to stdout in markdown format. |
854 | 871 |
| 872 |
855 ``` | 873 ``` |
856 ## **gn ls <out_dir> [<label_pattern>] [\--all-toolchains] [\--as=...]** | 874 ## **gn ls <out_dir> [<label_pattern>] [\--all-toolchains] [\--as=...]** |
857 ``` | 875 ``` |
858 [--type=...] [--testonly=...] | 876 [--type=...] [--testonly=...] |
859 | 877 |
860 Lists all targets matching the given pattern for the given build directory. | 878 Lists all targets matching the given pattern for the given build directory. |
861 By default, only targets in the default toolchain will be matched unless a | 879 By default, only targets in the default toolchain will be matched unless a |
862 toolchain is explicitly supplied. | 880 toolchain is explicitly supplied. |
863 | 881 |
864 If the label pattern is unspecified, list all targets. The label pattern is | 882 If the label pattern is unspecified, list all targets. The label pattern is |
(...skipping 56 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
921 gn ls out/Debug --type=executable | 939 gn ls out/Debug --type=executable |
922 Lists all executables produced by the build. | 940 Lists all executables produced by the build. |
923 | 941 |
924 gn ls out/Debug "//base/*" --as=output | xargs ninja -C out/Debug | 942 gn ls out/Debug "//base/*" --as=output | xargs ninja -C out/Debug |
925 Builds all targets in //base and all subdirectories. | 943 Builds all targets in //base and all subdirectories. |
926 | 944 |
927 gn ls out/Debug //base --all-toolchains | 945 gn ls out/Debug //base --all-toolchains |
928 Lists all variants of the target //base:base (it may be referenced | 946 Lists all variants of the target //base:base (it may be referenced |
929 in multiple toolchains). | 947 in multiple toolchains). |
930 | 948 |
| 949 |
931 ``` | 950 ``` |
932 ## **gn path <out_dir> <target_one> <target_two>** | 951 ## **gn path <out_dir> <target_one> <target_two>** |
933 | 952 |
934 ``` | 953 ``` |
935 Finds paths of dependencies between two targets. Each unique path will be | 954 Finds paths of dependencies between two targets. Each unique path will be |
936 printed in one group, and groups will be separate by newlines. The two | 955 printed in one group, and groups will be separate by newlines. The two |
937 targets can appear in either order (paths will be found going in either | 956 targets can appear in either order (paths will be found going in either |
938 direction). | 957 direction). |
939 | 958 |
940 By default, a single path will be printed. If there is a path with only | 959 By default, a single path will be printed. If there is a path with only |
(...skipping 29 matching lines...) Expand all Loading... |
970 Additionally follows data deps. Without this flag, only public and private | 989 Additionally follows data deps. Without this flag, only public and private |
971 linked deps will be followed. Can't be used with --public. | 990 linked deps will be followed. Can't be used with --public. |
972 | 991 |
973 ``` | 992 ``` |
974 | 993 |
975 ### **Example** | 994 ### **Example** |
976 | 995 |
977 ``` | 996 ``` |
978 gn path out/Default //base //tools/gn | 997 gn path out/Default //base //tools/gn |
979 | 998 |
| 999 |
980 ``` | 1000 ``` |
981 ## **gn refs <out_dir> (<label_pattern>|<label>|<file>|@<response_file>)* [\--al
l]** | 1001 ## **gn refs <out_dir> (<label_pattern>|<label>|<file>|@<response_file>)*** |
982 ``` | 1002 ``` |
983 [--all-toolchains] [--as=...] [--testonly=...] [--type=...] | 1003 [--all] [--all-toolchains] [--as=...] [--testonly=...] [--type=...] |
984 | 1004 |
985 Finds reverse dependencies (which targets reference something). The input is | 1005 Finds reverse dependencies (which targets reference something). The input is |
986 a list containing: | 1006 a list containing: |
987 | 1007 |
988 - Target label: The result will be which targets depend on it. | 1008 - Target label: The result will be which targets depend on it. |
989 | 1009 |
990 - Config label: The result will be which targets list the given config in | 1010 - Config label: The result will be which targets list the given config in |
991 its "configs" or "public_configs" list. | 1011 its "configs" or "public_configs" list. |
992 | 1012 |
993 - Label pattern: The result will be which targets depend on any target | 1013 - Label pattern: The result will be which targets depend on any target |
(...skipping 104 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1098 | 1118 |
1099 gn refs out/Debug //base/macros.h //base/at_exit.h --all | 1119 gn refs out/Debug //base/macros.h //base/at_exit.h --all |
1100 Display all unique targets with some dependency path to a target | 1120 Display all unique targets with some dependency path to a target |
1101 containing either of the given files as a source. | 1121 containing either of the given files as a source. |
1102 | 1122 |
1103 gn refs out/Debug //base/macros.h --testonly=true --type=executable | 1123 gn refs out/Debug //base/macros.h --testonly=true --type=executable |
1104 --all --as=output | 1124 --all --as=output |
1105 Display the executable file names of all test executables | 1125 Display the executable file names of all test executables |
1106 potentially affected by a change to the given file. | 1126 potentially affected by a change to the given file. |
1107 | 1127 |
| 1128 |
1108 ``` | 1129 ``` |
1109 ## **action**: Declare a target that runs a script a single time. | 1130 ## **action**: Declare a target that runs a script a single time. |
1110 | 1131 |
1111 ``` | 1132 ``` |
1112 This target type allows you to run a script a single time to produce one or | 1133 This target type allows you to run a script a single time to produce one or |
1113 more output files. If you want to run a script once for each of a set of | 1134 more output files. If you want to run a script once for each of a set of |
1114 input files, see "gn help action_foreach". | 1135 input files, see "gn help action_foreach". |
1115 | 1136 |
1116 ``` | 1137 ``` |
1117 | 1138 |
(...skipping 69 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1187 | 1208 |
1188 # Our script imports this Python file so we want to rebuild if it changes. | 1209 # Our script imports this Python file so we want to rebuild if it changes. |
1189 inputs = [ "helper_library.py" ] | 1210 inputs = [ "helper_library.py" ] |
1190 | 1211 |
1191 # Note that we have to manually pass the sources to our script if the | 1212 # Note that we have to manually pass the sources to our script if the |
1192 # script needs them as inputs. | 1213 # script needs them as inputs. |
1193 args = [ "--out", rebase_path(target_gen_dir, root_build_dir) ] + | 1214 args = [ "--out", rebase_path(target_gen_dir, root_build_dir) ] + |
1194 rebase_path(sources, root_build_dir) | 1215 rebase_path(sources, root_build_dir) |
1195 } | 1216 } |
1196 | 1217 |
| 1218 |
1197 ``` | 1219 ``` |
1198 ## **action_foreach**: Declare a target that runs a script over a set of files. | 1220 ## **action_foreach**: Declare a target that runs a script over a set of files. |
1199 | 1221 |
1200 ``` | 1222 ``` |
1201 This target type allows you to run a script once-per-file over a set of | 1223 This target type allows you to run a script once-per-file over a set of |
1202 sources. If you want to run a script once that takes many files as input, see | 1224 sources. If you want to run a script once that takes many files as input, see |
1203 "gn help action". | 1225 "gn help action". |
1204 | 1226 |
1205 ``` | 1227 ``` |
1206 | 1228 |
(...skipping 74 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1281 # Note that since "args" is opaque to GN, if you specify paths here, you | 1303 # Note that since "args" is opaque to GN, if you specify paths here, you |
1282 # will need to convert it to be relative to the build directory using | 1304 # will need to convert it to be relative to the build directory using |
1283 # rebase_path(). | 1305 # rebase_path(). |
1284 args = [ | 1306 args = [ |
1285 "{{source}}", | 1307 "{{source}}", |
1286 "-o", | 1308 "-o", |
1287 rebase_path(relative_target_gen_dir, root_build_dir) + | 1309 rebase_path(relative_target_gen_dir, root_build_dir) + |
1288 "/{{source_name_part}}.h" ] | 1310 "/{{source_name_part}}.h" ] |
1289 } | 1311 } |
1290 | 1312 |
| 1313 |
1291 ``` | 1314 ``` |
1292 ## **assert**: Assert an expression is true at generation time. | 1315 ## **assert**: Assert an expression is true at generation time. |
1293 | 1316 |
1294 ``` | 1317 ``` |
1295 assert(<condition> [, <error string>]) | 1318 assert(<condition> [, <error string>]) |
1296 | 1319 |
1297 If the condition is false, the build will fail with an error. If the | 1320 If the condition is false, the build will fail with an error. If the |
1298 optional second argument is provided, that string will be printed | 1321 optional second argument is provided, that string will be printed |
1299 with the error message. | 1322 with the error message. |
1300 | 1323 |
1301 ``` | 1324 ``` |
1302 | 1325 |
1303 ### **Examples** | 1326 ### **Examples** |
1304 | 1327 |
1305 ``` | 1328 ``` |
1306 assert(is_win) | 1329 assert(is_win) |
1307 assert(defined(sources), "Sources must be defined"); | 1330 assert(defined(sources), "Sources must be defined"); |
1308 | 1331 |
| 1332 |
1309 ``` | 1333 ``` |
1310 ## **bundle_data**: [iOS/OS X] Declare a target without output. | 1334 ## **bundle_data**: [iOS/OS X] Declare a target without output. |
1311 | 1335 |
1312 ``` | 1336 ``` |
1313 This target type allows to declare data that is required at runtime. It is | 1337 This target type allows to declare data that is required at runtime. It is |
1314 used to inform "create_bundle" targets of the files to copy into generated | 1338 used to inform "create_bundle" targets of the files to copy into generated |
1315 bundle, see "gn help create_bundle" for help. | 1339 bundle, see "gn help create_bundle" for help. |
1316 | 1340 |
1317 The target must define a list of files as "sources" and a single "outputs". | 1341 The target must define a list of files as "sources" and a single "outputs". |
1318 If there are multiple files, source expansions must be used to express the | 1342 If there are multiple files, source expansions must be used to express the |
(...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1356 "src/MaterialTypography.bundle/Roboto-Italic.ttf", | 1380 "src/MaterialTypography.bundle/Roboto-Italic.ttf", |
1357 "src/MaterialTypography.bundle/Roboto-Regular.ttf", | 1381 "src/MaterialTypography.bundle/Roboto-Regular.ttf", |
1358 "src/MaterialTypography.bundle/Roboto-Thin.ttf", | 1382 "src/MaterialTypography.bundle/Roboto-Thin.ttf", |
1359 ] | 1383 ] |
1360 outputs = [ | 1384 outputs = [ |
1361 "{{bundle_resources_dir}}/MaterialTypography.bundle/" | 1385 "{{bundle_resources_dir}}/MaterialTypography.bundle/" |
1362 "{{source_file_part}}" | 1386 "{{source_file_part}}" |
1363 ] | 1387 ] |
1364 } | 1388 } |
1365 | 1389 |
| 1390 |
1366 ``` | 1391 ``` |
1367 ## **config**: Defines a configuration object. | 1392 ## **config**: Defines a configuration object. |
1368 | 1393 |
1369 ``` | 1394 ``` |
1370 Configuration objects can be applied to targets and specify sets of compiler | 1395 Configuration objects can be applied to targets and specify sets of compiler |
1371 flags, includes, defines, etc. They provide a way to conveniently group sets | 1396 flags, includes, defines, etc. They provide a way to conveniently group sets |
1372 of this configuration information. | 1397 of this configuration information. |
1373 | 1398 |
1374 A config is referenced by its label just like a target. | 1399 A config is referenced by its label just like a target. |
1375 | 1400 |
(...skipping 31 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1407 ``` | 1432 ``` |
1408 config("myconfig") { | 1433 config("myconfig") { |
1409 includes = [ "include/common" ] | 1434 includes = [ "include/common" ] |
1410 defines = [ "ENABLE_DOOM_MELON" ] | 1435 defines = [ "ENABLE_DOOM_MELON" ] |
1411 } | 1436 } |
1412 | 1437 |
1413 executable("mything") { | 1438 executable("mything") { |
1414 configs = [ ":myconfig" ] | 1439 configs = [ ":myconfig" ] |
1415 } | 1440 } |
1416 | 1441 |
| 1442 |
1417 ``` | 1443 ``` |
1418 ## **copy**: Declare a target that copies files. | 1444 ## **copy**: Declare a target that copies files. |
1419 | 1445 |
1420 ### **File name handling** | 1446 ### **File name handling** |
1421 | 1447 |
1422 ``` | 1448 ``` |
1423 All output files must be inside the output directory of the build. You would | 1449 All output files must be inside the output directory of the build. You would |
1424 generally use |$target_out_dir| or |$target_gen_dir| to reference the output | 1450 generally use |$target_out_dir| or |$target_gen_dir| to reference the output |
1425 or generated intermediate file directories, respectively. | 1451 or generated intermediate file directories, respectively. |
1426 | 1452 |
(...skipping 19 matching lines...) Expand all Loading... |
1446 | 1472 |
1447 # Write a rule to copy several files to the target generated files directory. | 1473 # Write a rule to copy several files to the target generated files directory. |
1448 copy("myfiles") { | 1474 copy("myfiles") { |
1449 sources = [ "data1.dat", "data2.dat", "data3.dat" ] | 1475 sources = [ "data1.dat", "data2.dat", "data3.dat" ] |
1450 | 1476 |
1451 # Use source expansion to generate output files with the corresponding file | 1477 # Use source expansion to generate output files with the corresponding file |
1452 # names in the gen dir. This will just copy each file. | 1478 # names in the gen dir. This will just copy each file. |
1453 outputs = [ "$target_gen_dir/{{source_file_part}}" ] | 1479 outputs = [ "$target_gen_dir/{{source_file_part}}" ] |
1454 } | 1480 } |
1455 | 1481 |
| 1482 |
1456 ``` | 1483 ``` |
1457 ## **create_bundle**: [iOS/OS X] Build an OS X / iOS bundle. | 1484 ## **create_bundle**: [iOS/OS X] Build an OS X / iOS bundle. |
1458 | 1485 |
1459 ``` | 1486 ``` |
1460 This target generates an iOS/OS X bundle (which is a directory with a | 1487 This target generates an iOS/OS X bundle (which is a directory with a |
1461 well-know structure). This target does not define any sources, instead they | 1488 well-know structure). This target does not define any sources, instead they |
1462 are computed from all "bundle_data" target this one depends on transitively | 1489 are computed from all "bundle_data" target this one depends on transitively |
1463 (the recursion stops at "create_bundle" targets). | 1490 (the recursion stops at "create_bundle" targets). |
1464 | 1491 |
1465 The "bundle_*_dir" properties must be defined. They will be used for the | 1492 The "bundle_*_dir" properties must be defined. They will be used for the |
(...skipping 127 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1593 "$target_gen_dir/$app_name.xcent", root_build_dir), | 1620 "$target_gen_dir/$app_name.xcent", root_build_dir), |
1594 rebase_path(bundle_root_dir, root_build_dir), | 1621 rebase_path(bundle_root_dir, root_build_dir), |
1595 ] | 1622 ] |
1596 } else { | 1623 } else { |
1597 deps += [ ":${app_name}_bundle_executable" ] | 1624 deps += [ ":${app_name}_bundle_executable" ] |
1598 } | 1625 } |
1599 } | 1626 } |
1600 } | 1627 } |
1601 } | 1628 } |
1602 | 1629 |
| 1630 |
1603 ``` | 1631 ``` |
1604 ## **declare_args**: Declare build arguments. | 1632 ## **declare_args**: Declare build arguments. |
1605 | 1633 |
1606 ``` | 1634 ``` |
1607 Introduces the given arguments into the current scope. If they are not | 1635 Introduces the given arguments into the current scope. If they are not |
1608 specified on the command line or in a toolchain's arguments, the default | 1636 specified on the command line or in a toolchain's arguments, the default |
1609 values given in the declare_args block will be used. However, these defaults | 1637 values given in the declare_args block will be used. However, these defaults |
1610 will not override command-line values. | 1638 will not override command-line values. |
1611 | 1639 |
1612 See also "gn help buildargs" for an overview. | 1640 See also "gn help buildargs" for an overview. |
(...skipping 43 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1656 declare_args() { | 1684 declare_args() { |
1657 enable_teleporter = true | 1685 enable_teleporter = true |
1658 enable_doom_melon = false | 1686 enable_doom_melon = false |
1659 } | 1687 } |
1660 | 1688 |
1661 If you want to override the (default disabled) Doom Melon: | 1689 If you want to override the (default disabled) Doom Melon: |
1662 gn --args="enable_doom_melon=true enable_teleporter=false" | 1690 gn --args="enable_doom_melon=true enable_teleporter=false" |
1663 This also sets the teleporter, but it's already defaulted to on so it will | 1691 This also sets the teleporter, but it's already defaulted to on so it will |
1664 have no effect. | 1692 have no effect. |
1665 | 1693 |
| 1694 |
1666 ``` | 1695 ``` |
1667 ## **defined**: Returns whether an identifier is defined. | 1696 ## **defined**: Returns whether an identifier is defined. |
1668 | 1697 |
1669 ``` | 1698 ``` |
1670 Returns true if the given argument is defined. This is most useful in | 1699 Returns true if the given argument is defined. This is most useful in |
1671 templates to assert that the caller set things up properly. | 1700 templates to assert that the caller set things up properly. |
1672 | 1701 |
1673 You can pass an identifier: | 1702 You can pass an identifier: |
1674 defined(foo) | 1703 defined(foo) |
1675 which will return true or false depending on whether foo is defined in the | 1704 which will return true or false depending on whether foo is defined in the |
(...skipping 16 matching lines...) Expand all Loading... |
1692 | 1721 |
1693 # If we want to accept an optional "values" argument, we don't | 1722 # If we want to accept an optional "values" argument, we don't |
1694 # want to dereference something that may not be defined. | 1723 # want to dereference something that may not be defined. |
1695 if (defined(invoker.values)) { | 1724 if (defined(invoker.values)) { |
1696 values = invoker.values | 1725 values = invoker.values |
1697 } else { | 1726 } else { |
1698 values = "some default value" | 1727 values = "some default value" |
1699 } | 1728 } |
1700 } | 1729 } |
1701 | 1730 |
| 1731 |
1702 ``` | 1732 ``` |
1703 ## **exec_script**: Synchronously run a script and return the output. | 1733 ## **exec_script**: Synchronously run a script and return the output. |
1704 | 1734 |
1705 ``` | 1735 ``` |
1706 exec_script(filename, | 1736 exec_script(filename, |
1707 arguments = [], | 1737 arguments = [], |
1708 input_conversion = "", | 1738 input_conversion = "", |
1709 file_dependencies = []) | 1739 file_dependencies = []) |
1710 | 1740 |
1711 Runs the given script, returning the stdout of the script. The build | 1741 Runs the given script, returning the stdout of the script. The build |
(...skipping 39 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1751 | 1781 |
1752 ``` | 1782 ``` |
1753 all_lines = exec_script( | 1783 all_lines = exec_script( |
1754 "myscript.py", [some_input], "list lines", | 1784 "myscript.py", [some_input], "list lines", |
1755 [ rebase_path("data_file.txt", root_build_dir) ]) | 1785 [ rebase_path("data_file.txt", root_build_dir) ]) |
1756 | 1786 |
1757 # This example just calls the script with no arguments and discards the | 1787 # This example just calls the script with no arguments and discards the |
1758 # result. | 1788 # result. |
1759 exec_script("//foo/bar/myscript.py") | 1789 exec_script("//foo/bar/myscript.py") |
1760 | 1790 |
| 1791 |
1761 ``` | 1792 ``` |
1762 ## **executable**: Declare an executable target. | 1793 ## **executable**: Declare an executable target. |
1763 | 1794 |
1764 ### **Variables** | 1795 ### **Variables** |
| 1796 |
1765 ``` | 1797 ``` |
1766 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, | 1798 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, |
1767 asmflags, defines, include_dirs, ldflags, lib_dirs, libs, | 1799 asmflags, defines, include_dirs, ldflags, lib_dirs, libs, |
1768 precompiled_header, precompiled_source | 1800 precompiled_header, precompiled_source |
1769 Deps: data_deps, deps, public_deps | 1801 Deps: data_deps, deps, public_deps |
1770 Dependent configs: all_dependent_configs, public_configs | 1802 Dependent configs: all_dependent_configs, public_configs |
1771 General: check_includes, configs, data, inputs, output_name, | 1803 General: check_includes, configs, data, inputs, output_name, |
1772 output_extension, public, sources, testonly, visibility | 1804 output_extension, public, sources, testonly, visibility |
1773 | 1805 |
1774 | 1806 |
(...skipping 25 matching lines...) Expand all Loading... |
1800 mylist = [ "a", "b", "c" ] | 1832 mylist = [ "a", "b", "c" ] |
1801 foreach(i, mylist) { | 1833 foreach(i, mylist) { |
1802 print(i) | 1834 print(i) |
1803 } | 1835 } |
1804 | 1836 |
1805 Prints: | 1837 Prints: |
1806 a | 1838 a |
1807 b | 1839 b |
1808 c | 1840 c |
1809 | 1841 |
| 1842 |
1810 ``` | 1843 ``` |
1811 ## **forward_variables_from**: Copies variables from a different scope. | 1844 ## **forward_variables_from**: Copies variables from a different scope. |
1812 | 1845 |
1813 ``` | 1846 ``` |
1814 forward_variables_from(from_scope, variable_list_or_star, | 1847 forward_variables_from(from_scope, variable_list_or_star, |
1815 variable_to_not_forward_list = []) | 1848 variable_to_not_forward_list = []) |
1816 | 1849 |
1817 Copies the given variables from the given scope to the local scope if they | 1850 Copies the given variables from the given scope to the local scope if they |
1818 exist. This is normally used in the context of templates to use the values of | 1851 exist. This is normally used in the context of templates to use the values of |
1819 variables defined in the template invocation to a template-defined target. | 1852 variables defined in the template invocation to a template-defined target. |
(...skipping 59 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1879 template("my_ios_test_app") { | 1912 template("my_ios_test_app") { |
1880 ios_test_app(target_name) { | 1913 ios_test_app(target_name) { |
1881 forward_variables_from(invoker, "*", ["test_bundle_name"]) | 1914 forward_variables_from(invoker, "*", ["test_bundle_name"]) |
1882 if (!defined(extra_substitutions)) { | 1915 if (!defined(extra_substitutions)) { |
1883 extra_substitutions = [] | 1916 extra_substitutions = [] |
1884 } | 1917 } |
1885 extra_substitutions += [ "BUNDLE_ID_TEST_NAME=$test_bundle_name" ] | 1918 extra_substitutions += [ "BUNDLE_ID_TEST_NAME=$test_bundle_name" ] |
1886 } | 1919 } |
1887 } | 1920 } |
1888 | 1921 |
| 1922 |
1889 ``` | 1923 ``` |
1890 ## **get_label_info**: Get an attribute from a target's label. | 1924 ## **get_label_info**: Get an attribute from a target's label. |
1891 | 1925 |
1892 ``` | 1926 ``` |
1893 get_label_info(target_label, what) | 1927 get_label_info(target_label, what) |
1894 | 1928 |
1895 Given the label of a target, returns some attribute of that target. The | 1929 Given the label of a target, returns some attribute of that target. The |
1896 target need not have been previously defined in the same file, since none of | 1930 target need not have been previously defined in the same file, since none of |
1897 the attributes depend on the actual target definition, only the label itself. | 1931 the attributes depend on the actual target definition, only the label itself. |
1898 | 1932 |
(...skipping 47 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1946 | 1980 |
1947 ### **Examples** | 1981 ### **Examples** |
1948 | 1982 |
1949 ``` | 1983 ``` |
1950 get_label_info(":foo", "name") | 1984 get_label_info(":foo", "name") |
1951 # Returns string "foo". | 1985 # Returns string "foo". |
1952 | 1986 |
1953 get_label_info("//foo/bar:baz", "gen_dir") | 1987 get_label_info("//foo/bar:baz", "gen_dir") |
1954 # Returns string "//out/Debug/gen/foo/bar". | 1988 # Returns string "//out/Debug/gen/foo/bar". |
1955 | 1989 |
| 1990 |
1956 ``` | 1991 ``` |
1957 ## **get_path_info**: Extract parts of a file or directory name. | 1992 ## **get_path_info**: Extract parts of a file or directory name. |
1958 | 1993 |
1959 ``` | 1994 ``` |
1960 get_path_info(input, what) | 1995 get_path_info(input, what) |
1961 | 1996 |
1962 The first argument is either a string representing a file or directory name, | 1997 The first argument is either a string representing a file or directory name, |
1963 or a list of such strings. If the input is a list the return value will be a | 1998 or a list of such strings. If the input is a list the return value will be a |
1964 list containing the result of applying the rule to each item in the input. | 1999 list containing the result of applying the rule to each item in the input. |
1965 | 2000 |
(...skipping 63 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2029 sources = [ "foo.cc", "foo.h" ] | 2064 sources = [ "foo.cc", "foo.h" ] |
2030 result = get_path_info(source, "abspath") | 2065 result = get_path_info(source, "abspath") |
2031 # result will be [ "//mydir/foo.cc", "//mydir/foo.h" ] | 2066 # result will be [ "//mydir/foo.cc", "//mydir/foo.h" ] |
2032 | 2067 |
2033 result = get_path_info("//foo/bar/baz.cc", "dir") | 2068 result = get_path_info("//foo/bar/baz.cc", "dir") |
2034 # result will be "//foo/bar" | 2069 # result will be "//foo/bar" |
2035 | 2070 |
2036 # Extract the source-absolute directory name, | 2071 # Extract the source-absolute directory name, |
2037 result = get_path_info(get_path_info(path, "dir"), "abspath" | 2072 result = get_path_info(get_path_info(path, "dir"), "abspath" |
2038 | 2073 |
| 2074 |
2039 ``` | 2075 ``` |
2040 ## **get_target_outputs**: [file list] Get the list of outputs from a target. | 2076 ## **get_target_outputs**: [file list] Get the list of outputs from a target. |
2041 | 2077 |
2042 ``` | 2078 ``` |
2043 get_target_outputs(target_label) | 2079 get_target_outputs(target_label) |
2044 | 2080 |
2045 Returns a list of output files for the named target. The named target must | 2081 Returns a list of output files for the named target. The named target must |
2046 have been previously defined in the current file before this function is | 2082 have been previously defined in the current file before this function is |
2047 called (it can't reference targets in other files because there isn't a | 2083 called (it can't reference targets in other files because there isn't a |
2048 defined execution order, and it obviously can't reference targets that are | 2084 defined execution order, and it obviously can't reference targets that are |
(...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2089 action_foreach("my_action") { | 2125 action_foreach("my_action") { |
2090 sources = [ ... ] | 2126 sources = [ ... ] |
2091 outputs = [ ... ] | 2127 outputs = [ ... ] |
2092 } | 2128 } |
2093 | 2129 |
2094 # Compile the resulting source files into a source set. | 2130 # Compile the resulting source files into a source set. |
2095 source_set("my_lib") { | 2131 source_set("my_lib") { |
2096 sources = get_target_outputs(":my_action") | 2132 sources = get_target_outputs(":my_action") |
2097 } | 2133 } |
2098 | 2134 |
| 2135 |
2099 ``` | 2136 ``` |
2100 ## **getenv**: Get an environment variable. | 2137 ## **getenv**: Get an environment variable. |
2101 | 2138 |
2102 ``` | 2139 ``` |
2103 value = getenv(env_var_name) | 2140 value = getenv(env_var_name) |
2104 | 2141 |
2105 Returns the value of the given enironment variable. If the value is not | 2142 Returns the value of the given enironment variable. If the value is not |
2106 found, it will try to look up the variable with the "opposite" case (based on | 2143 found, it will try to look up the variable with the "opposite" case (based on |
2107 the case of the first letter of the variable), but is otherwise | 2144 the case of the first letter of the variable), but is otherwise |
2108 case-sensitive. | 2145 case-sensitive. |
2109 | 2146 |
2110 If the environment variable is not found, the empty string will be returned. | 2147 If the environment variable is not found, the empty string will be returned. |
2111 Note: it might be nice to extend this if we had the concept of "none" in the | 2148 Note: it might be nice to extend this if we had the concept of "none" in the |
2112 language to indicate lookup failure. | 2149 language to indicate lookup failure. |
2113 | 2150 |
2114 ``` | 2151 ``` |
2115 | 2152 |
2116 ### **Example** | 2153 ### **Example** |
2117 | 2154 |
2118 ``` | 2155 ``` |
2119 home_dir = getenv("HOME") | 2156 home_dir = getenv("HOME") |
2120 | 2157 |
| 2158 |
2121 ``` | 2159 ``` |
2122 ## **group**: Declare a named group of targets. | 2160 ## **group**: Declare a named group of targets. |
2123 | 2161 |
2124 ``` | 2162 ``` |
2125 This target type allows you to create meta-targets that just collect a set of | 2163 This target type allows you to create meta-targets that just collect a set of |
2126 dependencies into one named target. Groups can additionally specify configs | 2164 dependencies into one named target. Groups can additionally specify configs |
2127 that apply to their dependents. | 2165 that apply to their dependents. |
2128 | 2166 |
2129 ``` | 2167 ``` |
2130 | 2168 |
2131 ### **Variables** | 2169 ### **Variables** |
| 2170 |
2132 ``` | 2171 ``` |
2133 Deps: data_deps, deps, public_deps | 2172 Deps: data_deps, deps, public_deps |
2134 Dependent configs: all_dependent_configs, public_configs | 2173 Dependent configs: all_dependent_configs, public_configs |
2135 | 2174 |
2136 ``` | 2175 ``` |
2137 | 2176 |
2138 ### **Example** | 2177 ### **Example** |
2139 | 2178 |
2140 ``` | 2179 ``` |
2141 group("all") { | 2180 group("all") { |
2142 deps = [ | 2181 deps = [ |
2143 "//project:runner", | 2182 "//project:runner", |
2144 "//project:unit_tests", | 2183 "//project:unit_tests", |
2145 ] | 2184 ] |
2146 } | 2185 } |
2147 | 2186 |
| 2187 |
2148 ``` | 2188 ``` |
2149 ## **import**: Import a file into the current scope. | 2189 ## **import**: Import a file into the current scope. |
2150 | 2190 |
2151 ``` | 2191 ``` |
2152 The import command loads the rules and variables resulting from executing the | 2192 The import command loads the rules and variables resulting from executing the |
2153 given file into the current scope. | 2193 given file into the current scope. |
2154 | 2194 |
2155 By convention, imported files are named with a .gni extension. | 2195 By convention, imported files are named with a .gni extension. |
2156 | 2196 |
2157 An import is different than a C++ "include". The imported file is executed in | 2197 An import is different than a C++ "include". The imported file is executed in |
(...skipping 17 matching lines...) Expand all Loading... |
2175 ``` | 2215 ``` |
2176 | 2216 |
2177 ### **Examples** | 2217 ### **Examples** |
2178 | 2218 |
2179 ``` | 2219 ``` |
2180 import("//build/rules/idl_compilation_rule.gni") | 2220 import("//build/rules/idl_compilation_rule.gni") |
2181 | 2221 |
2182 # Looks in the current directory. | 2222 # Looks in the current directory. |
2183 import("my_vars.gni") | 2223 import("my_vars.gni") |
2184 | 2224 |
| 2225 |
2185 ``` | 2226 ``` |
2186 ## **loadable_module**: Declare a loadable module target. | 2227 ## **loadable_module**: Declare a loadable module target. |
2187 | 2228 |
2188 ``` | 2229 ``` |
2189 This target type allows you to create an object file that is (and can only | 2230 This target type allows you to create an object file that is (and can only |
2190 be) loaded and unloaded at runtime. | 2231 be) loaded and unloaded at runtime. |
2191 | 2232 |
2192 A loadable module will be specified on the linker line for targets listing | 2233 A loadable module will be specified on the linker line for targets listing |
2193 the loadable module in its "deps". If you don't want this (if you don't need | 2234 the loadable module in its "deps". If you don't want this (if you don't need |
2194 to dynamically load the library at runtime), then you should use a | 2235 to dynamically load the library at runtime), then you should use a |
2195 "shared_library" target type instead. | 2236 "shared_library" target type instead. |
2196 | 2237 |
2197 ``` | 2238 ``` |
2198 | 2239 |
2199 ### **Variables** | 2240 ### **Variables** |
| 2241 |
2200 ``` | 2242 ``` |
2201 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, | 2243 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, |
2202 asmflags, defines, include_dirs, ldflags, lib_dirs, libs, | 2244 asmflags, defines, include_dirs, ldflags, lib_dirs, libs, |
2203 precompiled_header, precompiled_source | 2245 precompiled_header, precompiled_source |
2204 Deps: data_deps, deps, public_deps | 2246 Deps: data_deps, deps, public_deps |
2205 Dependent configs: all_dependent_configs, public_configs | 2247 Dependent configs: all_dependent_configs, public_configs |
2206 General: check_includes, configs, data, inputs, output_name, | 2248 General: check_includes, configs, data, inputs, output_name, |
2207 output_extension, public, sources, testonly, visibility | 2249 output_extension, public, sources, testonly, visibility |
2208 | 2250 |
2209 | 2251 |
(...skipping 30 matching lines...) Expand all Loading... |
2240 } | 2282 } |
2241 } | 2283 } |
2242 | 2284 |
2243 toolchain("toolchain") { | 2285 toolchain("toolchain") { |
2244 tool("link") { | 2286 tool("link") { |
2245 command = "..." | 2287 command = "..." |
2246 pool = ":link_pool($default_toolchain)") | 2288 pool = ":link_pool($default_toolchain)") |
2247 } | 2289 } |
2248 } | 2290 } |
2249 | 2291 |
| 2292 |
2250 ``` | 2293 ``` |
2251 ## **print**: Prints to the console. | 2294 ## **print**: Prints to the console. |
2252 | 2295 |
2253 ``` | 2296 ``` |
2254 Prints all arguments to the console separated by spaces. A newline is | 2297 Prints all arguments to the console separated by spaces. A newline is |
2255 automatically appended to the end. | 2298 automatically appended to the end. |
2256 | 2299 |
2257 This function is intended for debugging. Note that build files are run in | 2300 This function is intended for debugging. Note that build files are run in |
2258 parallel so you may get interleaved prints. A buildfile may also be executed | 2301 parallel so you may get interleaved prints. A buildfile may also be executed |
2259 more than once in parallel in the context of different toolchains so the | 2302 more than once in parallel in the context of different toolchains so the |
2260 prints from one file may be duplicated or | 2303 prints from one file may be duplicated or |
2261 interleaved with itself. | 2304 interleaved with itself. |
2262 | 2305 |
2263 ``` | 2306 ``` |
2264 | 2307 |
2265 ### **Examples** | 2308 ### **Examples** |
2266 | 2309 |
2267 ``` | 2310 ``` |
2268 print("Hello world") | 2311 print("Hello world") |
2269 | 2312 |
2270 print(sources, deps) | 2313 print(sources, deps) |
2271 | 2314 |
| 2315 |
2272 ``` | 2316 ``` |
2273 ## **process_file_template**: Do template expansion over a list of files. | 2317 ## **process_file_template**: Do template expansion over a list of files. |
2274 | 2318 |
2275 ``` | 2319 ``` |
2276 process_file_template(source_list, template) | 2320 process_file_template(source_list, template) |
2277 | 2321 |
2278 process_file_template applies a template list to a source file list, | 2322 process_file_template applies a template list to a source file list, |
2279 returning the result of applying each template to each source. This is | 2323 returning the result of applying each template to each source. This is |
2280 typically used for computing output file names from input files. | 2324 typically used for computing output file names from input files. |
2281 | 2325 |
(...skipping 28 matching lines...) Expand all Loading... |
2310 sources, | 2354 sources, |
2311 [ "$target_gen_dir/{{source_name_part}}.cc", | 2355 [ "$target_gen_dir/{{source_name_part}}.cc", |
2312 "$target_gen_dir/{{source_name_part}}.h" ]) | 2356 "$target_gen_dir/{{source_name_part}}.h" ]) |
2313 | 2357 |
2314 The result in this case will be: | 2358 The result in this case will be: |
2315 [ "//out/Debug/foo.cc" | 2359 [ "//out/Debug/foo.cc" |
2316 "//out/Debug/foo.h" | 2360 "//out/Debug/foo.h" |
2317 "//out/Debug/bar.cc" | 2361 "//out/Debug/bar.cc" |
2318 "//out/Debug/bar.h" ] | 2362 "//out/Debug/bar.h" ] |
2319 | 2363 |
| 2364 |
2320 ``` | 2365 ``` |
2321 ## **read_file**: Read a file into a variable. | 2366 ## **read_file**: Read a file into a variable. |
2322 | 2367 |
2323 ``` | 2368 ``` |
2324 read_file(filename, input_conversion) | 2369 read_file(filename, input_conversion) |
2325 | 2370 |
2326 Whitespace will be trimmed from the end of the file. Throws an error if the | 2371 Whitespace will be trimmed from the end of the file. Throws an error if the |
2327 file can not be opened. | 2372 file can not be opened. |
2328 | 2373 |
2329 ``` | 2374 ``` |
2330 | 2375 |
2331 ### **Arguments** | 2376 ### **Arguments** |
2332 | 2377 |
2333 ``` | 2378 ``` |
2334 filename | 2379 filename |
2335 Filename to read, relative to the build file. | 2380 Filename to read, relative to the build file. |
2336 | 2381 |
2337 input_conversion | 2382 input_conversion |
2338 Controls how the file is read and parsed. See "gn help input_conversion". | 2383 Controls how the file is read and parsed. See "gn help input_conversion". |
2339 | 2384 |
2340 ``` | 2385 ``` |
2341 | 2386 |
2342 ### **Example** | 2387 ### **Example** |
2343 | 2388 |
2344 ``` | 2389 ``` |
2345 lines = read_file("foo.txt", "list lines") | 2390 lines = read_file("foo.txt", "list lines") |
2346 | 2391 |
| 2392 |
2347 ``` | 2393 ``` |
2348 ## **rebase_path**: Rebase a file or directory to another location. | 2394 ## **rebase_path**: Rebase a file or directory to another location. |
2349 | 2395 |
2350 ``` | 2396 ``` |
2351 converted = rebase_path(input, | 2397 converted = rebase_path(input, |
2352 new_base = "", | 2398 new_base = "", |
2353 current_base = ".") | 2399 current_base = ".") |
2354 | 2400 |
2355 Takes a string argument representing a file name, or a list of such strings | 2401 Takes a string argument representing a file name, or a list of such strings |
2356 and converts it/them to be relative to a different base directory. | 2402 and converts it/them to be relative to a different base directory. |
(...skipping 80 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2437 # Extra file args passed manually need to be explicitly converted | 2483 # Extra file args passed manually need to be explicitly converted |
2438 # to be relative to the build directory: | 2484 # to be relative to the build directory: |
2439 args = [ | 2485 args = [ |
2440 "--data", | 2486 "--data", |
2441 rebase_path("//mything/data/input.dat", root_build_dir), | 2487 rebase_path("//mything/data/input.dat", root_build_dir), |
2442 "--rel", | 2488 "--rel", |
2443 rebase_path("relative_path.txt", root_build_dir) | 2489 rebase_path("relative_path.txt", root_build_dir) |
2444 ] + rebase_path(sources, root_build_dir) | 2490 ] + rebase_path(sources, root_build_dir) |
2445 } | 2491 } |
2446 | 2492 |
| 2493 |
2447 ``` | 2494 ``` |
2448 ## **set_default_toolchain**: Sets the default toolchain name. | 2495 ## **set_default_toolchain**: Sets the default toolchain name. |
2449 | 2496 |
2450 ``` | 2497 ``` |
2451 set_default_toolchain(toolchain_label) | 2498 set_default_toolchain(toolchain_label) |
2452 | 2499 |
2453 The given label should identify a toolchain definition (see "gn help | 2500 The given label should identify a toolchain definition (see "gn help |
2454 toolchain"). This toolchain will be used for all targets unless otherwise | 2501 toolchain"). This toolchain will be used for all targets unless otherwise |
2455 specified. | 2502 specified. |
2456 | 2503 |
(...skipping 14 matching lines...) Expand all Loading... |
2471 | 2518 |
2472 ``` | 2519 ``` |
2473 toolchain_label | 2520 toolchain_label |
2474 Toolchain name. | 2521 Toolchain name. |
2475 | 2522 |
2476 ``` | 2523 ``` |
2477 | 2524 |
2478 ### **Example** | 2525 ### **Example** |
2479 | 2526 |
2480 ``` | 2527 ``` |
2481 set_default_toolchain("//build/config/win:vs32") | 2528 # Set default toolchain only has an effect when run in the context of the |
| 2529 # default toolchain. Pick the right one according to the current CPU |
| 2530 # architecture. |
| 2531 if (target_cpu == "x64") { |
| 2532 set_default_toolchain("//toolchains:64") |
| 2533 } else if (target_cpu == "x86") { |
| 2534 set_default_toolchain("//toolchains:32") |
| 2535 } |
| 2536 |
2482 | 2537 |
2483 ``` | 2538 ``` |
2484 ## **set_defaults**: Set default values for a target type. | 2539 ## **set_defaults**: Set default values for a target type. |
2485 | 2540 |
2486 ``` | 2541 ``` |
2487 set_defaults(<target_type_name>) { <values...> } | 2542 set_defaults(<target_type_name>) { <values...> } |
2488 | 2543 |
2489 Sets the default values for a given target type. Whenever target_type_name is | 2544 Sets the default values for a given target type. Whenever target_type_name is |
2490 seen in the future, the values specified in set_default's block will be | 2545 seen in the future, the values specified in set_default's block will be |
2491 copied into the current scope. | 2546 copied into the current scope. |
(...skipping 17 matching lines...) Expand all Loading... |
2509 set_defaults("static_library") { | 2564 set_defaults("static_library") { |
2510 configs = [ "//tools/mything:settings" ] | 2565 configs = [ "//tools/mything:settings" ] |
2511 } | 2566 } |
2512 | 2567 |
2513 static_library("mylib") | 2568 static_library("mylib") |
2514 # The configs will be auto-populated as above. You can remove it if | 2569 # The configs will be auto-populated as above. You can remove it if |
2515 # you don't want the default for a particular default: | 2570 # you don't want the default for a particular default: |
2516 configs -= [ "//tools/mything:settings" ] | 2571 configs -= [ "//tools/mything:settings" ] |
2517 } | 2572 } |
2518 | 2573 |
| 2574 |
2519 ``` | 2575 ``` |
2520 ## **set_sources_assignment_filter**: Set a pattern to filter source files. | 2576 ## **set_sources_assignment_filter**: Set a pattern to filter source files. |
2521 | 2577 |
2522 ``` | 2578 ``` |
2523 The sources assignment filter is a list of patterns that remove files from | 2579 The sources assignment filter is a list of patterns that remove files from |
2524 the list implicitly whenever the "sources" variable is assigned to. This will | 2580 the list implicitly whenever the "sources" variable is assigned to. This will |
2525 do nothing for non-lists. | 2581 do nothing for non-lists. |
2526 | 2582 |
2527 This is intended to be used to globally filter out files with | 2583 This is intended to be used to globally filter out files with |
2528 platform-specific naming schemes when they don't apply, for example you may | 2584 platform-specific naming schemes when they don't apply, for example you may |
(...skipping 48 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2577 | 2633 |
2578 ### **Sources assignment example** | 2634 ### **Sources assignment example** |
2579 | 2635 |
2580 ``` | 2636 ``` |
2581 # Filter out all _win files. | 2637 # Filter out all _win files. |
2582 set_sources_assignment_filter([ "*_win.cc", "*_win.h" ]) | 2638 set_sources_assignment_filter([ "*_win.cc", "*_win.h" ]) |
2583 sources = [ "a.cc", "b_win.cc" ] | 2639 sources = [ "a.cc", "b_win.cc" ] |
2584 print(sources) | 2640 print(sources) |
2585 # Will print [ "a.cc" ]. b_win one was filtered out. | 2641 # Will print [ "a.cc" ]. b_win one was filtered out. |
2586 | 2642 |
| 2643 |
2587 ``` | 2644 ``` |
2588 ## **shared_library**: Declare a shared library target. | 2645 ## **shared_library**: Declare a shared library target. |
2589 | 2646 |
2590 ``` | 2647 ``` |
2591 A shared library will be specified on the linker line for targets listing the | 2648 A shared library will be specified on the linker line for targets listing the |
2592 shared library in its "deps". If you don't want this (say you dynamically | 2649 shared library in its "deps". If you don't want this (say you dynamically |
2593 load the library at runtime), then you should depend on the shared library | 2650 load the library at runtime), then you should depend on the shared library |
2594 via "data_deps" or, on Darwin platforms, use a "loadable_module" target type | 2651 via "data_deps" or, on Darwin platforms, use a "loadable_module" target type |
2595 instead. | 2652 instead. |
2596 | 2653 |
2597 ``` | 2654 ``` |
2598 | 2655 |
2599 ### **Variables** | 2656 ### **Variables** |
| 2657 |
2600 ``` | 2658 ``` |
2601 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, | 2659 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, |
2602 asmflags, defines, include_dirs, ldflags, lib_dirs, libs, | 2660 asmflags, defines, include_dirs, ldflags, lib_dirs, libs, |
2603 precompiled_header, precompiled_source | 2661 precompiled_header, precompiled_source |
2604 Deps: data_deps, deps, public_deps | 2662 Deps: data_deps, deps, public_deps |
2605 Dependent configs: all_dependent_configs, public_configs | 2663 Dependent configs: all_dependent_configs, public_configs |
2606 General: check_includes, configs, data, inputs, output_name, | 2664 General: check_includes, configs, data, inputs, output_name, |
2607 output_extension, public, sources, testonly, visibility | 2665 output_extension, public, sources, testonly, visibility |
2608 | 2666 |
2609 | 2667 |
(...skipping 18 matching lines...) Expand all Loading... |
2628 | 2686 |
2629 A source set will not do this code elimination since there is no link step. | 2687 A source set will not do this code elimination since there is no link step. |
2630 This allows you to link many sources sets into a shared library and have the | 2688 This allows you to link many sources sets into a shared library and have the |
2631 "exported symbol" notation indicate "export from the final shared library and | 2689 "exported symbol" notation indicate "export from the final shared library and |
2632 not from the intermediate targets." There is no way to express this concept | 2690 not from the intermediate targets." There is no way to express this concept |
2633 when linking multiple static libraries into a shared library. | 2691 when linking multiple static libraries into a shared library. |
2634 | 2692 |
2635 ``` | 2693 ``` |
2636 | 2694 |
2637 ### **Variables** | 2695 ### **Variables** |
| 2696 |
2638 ``` | 2697 ``` |
2639 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, | 2698 Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc, |
2640 asmflags, defines, include_dirs, ldflags, lib_dirs, libs, | 2699 asmflags, defines, include_dirs, ldflags, lib_dirs, libs, |
2641 precompiled_header, precompiled_source | 2700 precompiled_header, precompiled_source |
2642 Deps: data_deps, deps, public_deps | 2701 Deps: data_deps, deps, public_deps |
2643 Dependent configs: all_dependent_configs, public_configs | 2702 Dependent configs: all_dependent_configs, public_configs |
2644 General: check_includes, configs, data, inputs, output_name, | 2703 General: check_includes, configs, data, inputs, output_name, |
2645 output_extension, public, sources, testonly, visibility | 2704 output_extension, public, sources, testonly, visibility |
2646 | 2705 |
2647 | 2706 |
(...skipping 15 matching lines...) Expand all Loading... |
2663 ### **Example** | 2722 ### **Example** |
2664 | 2723 |
2665 ``` | 2724 ``` |
2666 The code: | 2725 The code: |
2667 mylist = [1, 2, 3, 4, 5, 6] | 2726 mylist = [1, 2, 3, 4, 5, 6] |
2668 print(split_list(mylist, 3)) | 2727 print(split_list(mylist, 3)) |
2669 | 2728 |
2670 Will print: | 2729 Will print: |
2671 [[1, 2], [3, 4], [5, 6] | 2730 [[1, 2], [3, 4], [5, 6] |
2672 | 2731 |
| 2732 |
2673 ``` | 2733 ``` |
2674 ## **static_library**: Declare a static library target. | 2734 ## **static_library**: Declare a static library target. |
2675 | 2735 |
2676 ``` | 2736 ``` |
2677 Make a ".a" / ".lib" file. | 2737 Make a ".a" / ".lib" file. |
2678 | 2738 |
2679 If you only need the static library for intermediate results in the build, | 2739 If you only need the static library for intermediate results in the build, |
2680 you should consider a source_set instead since it will skip the (potentially | 2740 you should consider a source_set instead since it will skip the (potentially |
2681 slow) step of creating the intermediate library file. | 2741 slow) step of creating the intermediate library file. |
2682 | 2742 |
(...skipping 39 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2722 if (foo_build_as_shared) { | 2782 if (foo_build_as_shared) { |
2723 my_type = "shared_library" | 2783 my_type = "shared_library" |
2724 } else { | 2784 } else { |
2725 my_type = "source_set" | 2785 my_type = "source_set" |
2726 } | 2786 } |
2727 | 2787 |
2728 target(my_type, "foo") { | 2788 target(my_type, "foo") { |
2729 ... | 2789 ... |
2730 } | 2790 } |
2731 | 2791 |
| 2792 |
2732 ``` | 2793 ``` |
2733 ## **template**: Define a template rule. | 2794 ## **template**: Define a template rule. |
2734 | 2795 |
2735 ``` | 2796 ``` |
2736 A template defines a custom name that acts like a function. It provides a way | 2797 A template defines a custom name that acts like a function. It provides a way |
2737 to add to the built-in target types. | 2798 to add to the built-in target types. |
2738 | 2799 |
2739 The template() function is used to declare a template. To invoke the | 2800 The template() function is used to declare a template. To invoke the |
2740 template, just use the name of the template like any other target type. | 2801 template, just use the name of the template like any other target type. |
2741 | 2802 |
(...skipping 132 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2874 | 2935 |
2875 # Here is a target that depends on our template. | 2936 # Here is a target that depends on our template. |
2876 executable("my_exe") { | 2937 executable("my_exe") { |
2877 # Depend on the name we gave the template call above. Internally, this will | 2938 # Depend on the name we gave the template call above. Internally, this will |
2878 # produce a dependency from executable to the source_set inside the | 2939 # produce a dependency from executable to the source_set inside the |
2879 # template (since it has this name), which will in turn depend on the code | 2940 # template (since it has this name), which will in turn depend on the code |
2880 # gen action. | 2941 # gen action. |
2881 deps = [ ":foo_idl_files" ] | 2942 deps = [ ":foo_idl_files" ] |
2882 } | 2943 } |
2883 | 2944 |
| 2945 |
2884 ``` | 2946 ``` |
2885 ## **tool**: Specify arguments to a toolchain tool. | 2947 ## **tool**: Specify arguments to a toolchain tool. |
2886 | 2948 |
2887 ### **Usage** | 2949 ### **Usage** |
2888 | 2950 |
2889 ``` | 2951 ``` |
2890 tool(<tool type>) { | 2952 tool(<tool type>) { |
2891 <tool variables...> | 2953 <tool variables...> |
2892 } | 2954 } |
2893 | 2955 |
(...skipping 446 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3340 outputs = [ "{{source_out_dir}}/{{source_name_part}}.o" ] | 3402 outputs = [ "{{source_out_dir}}/{{source_name_part}}.o" ] |
3341 description = "GCC {{source}}" | 3403 description = "GCC {{source}}" |
3342 } | 3404 } |
3343 tool("cxx") { | 3405 tool("cxx") { |
3344 command = "g++ {{source}} -o {{output}}" | 3406 command = "g++ {{source}} -o {{output}}" |
3345 outputs = [ "{{source_out_dir}}/{{source_name_part}}.o" ] | 3407 outputs = [ "{{source_out_dir}}/{{source_name_part}}.o" ] |
3346 description = "G++ {{source}}" | 3408 description = "G++ {{source}}" |
3347 } | 3409 } |
3348 }; | 3410 }; |
3349 | 3411 |
| 3412 |
3350 ``` | 3413 ``` |
3351 ## **toolchain**: Defines a toolchain. | 3414 ## **toolchain**: Defines a toolchain. |
3352 | 3415 |
3353 ``` | 3416 ``` |
3354 A toolchain is a set of commands and build flags used to compile the source | 3417 A toolchain is a set of commands and build flags used to compile the source |
3355 code. You can have more than one toolchain in use at once in a build. | 3418 code. The toolchain() function defines these commands. |
3356 | 3419 |
3357 ``` | 3420 ``` |
3358 | 3421 |
| 3422 ### **Toolchain overview** |
| 3423 |
| 3424 ``` |
| 3425 You can have more than one toolchain in use at once in a build and a target |
| 3426 can exist simultaneously in multiple toolchains. A build file is executed |
| 3427 once for each toolchain it is referenced in so the GN code can vary all |
| 3428 parameters of each target (or which targets exist) on a per-toolchain basis. |
| 3429 |
| 3430 When you have a simple build with only one toolchain, the build config file |
| 3431 is loaded only once at the beginning of the build. It must call |
| 3432 set_default_toolchain() (see "gn help set_default_toolchain") to tell GN the |
| 3433 label of the toolchain definition to use. The "toolchain_args" section of the |
| 3434 toolchain definition is ignored. |
| 3435 |
| 3436 When a target has a dependency on a target using different toolchain (see "gn |
| 3437 help labels" for how to specify this), GN will start a build using that |
| 3438 secondary toolchain to resolve the target. GN will load the build config file |
| 3439 with the build arguements overridden as specified in the toolchain_args. |
| 3440 Because the default toolchain is already known, calls to |
| 3441 set_default_toolchain() are ignored. |
| 3442 |
| 3443 To load a file in an alternate toolchain, GN does the following: |
| 3444 |
| 3445 1. Loads the file with the toolchain definition in it (as determined by the |
| 3446 toolchain label). |
| 3447 2. Re-runs the master build configuration file, applying the arguments |
| 3448 specified by the toolchain_args section of the toolchain definition. |
| 3449 3. Loads the destination build file in the context of the configuration file |
| 3450 in the previous step. |
| 3451 |
| 3452 The toolchain configuration is two-way. In the default toolchain (i.e. the |
| 3453 main build target) the configuration flows from the build config file to the |
| 3454 toolchain. The build config file looks at the state of the build (OS type, |
| 3455 CPU architecture, etc.) and decides which toolchain to use (via |
| 3456 set_default_toolchain()). In secondary toolchains, the configuration flows |
| 3457 from the toolchain to the build config file: the "toolchain_args" in the |
| 3458 toolchain definition specifies the arguments to re-invoke the build. |
| 3459 |
| 3460 ``` |
| 3461 |
3359 ### **Functions and variables** | 3462 ### **Functions and variables** |
3360 | 3463 |
3361 ``` | 3464 ``` |
3362 tool() | 3465 tool() |
3363 The tool() function call specifies the commands commands to run for a given | 3466 The tool() function call specifies the commands commands to run for a given |
3364 step. See "gn help tool". | 3467 step. See "gn help tool". |
3365 | 3468 |
3366 toolchain_args | 3469 toolchain_args |
3367 Overrides for build arguments to pass to the toolchain when invoking it. | 3470 Overrides for build arguments to pass to the toolchain when invoking it. |
3368 This is a variable of type "scope" where the variable names correspond to | 3471 This is a variable of type "scope" where the variable names correspond to |
(...skipping 20 matching lines...) Expand all Loading... |
3389 | 3492 |
3390 This is expressed as a list of targets, and generally these targets will | 3493 This is expressed as a list of targets, and generally these targets will |
3391 always specify a toolchain: | 3494 always specify a toolchain: |
3392 deps = [ "//foo/bar:baz(//build/toolchain:bootstrap)" ] | 3495 deps = [ "//foo/bar:baz(//build/toolchain:bootstrap)" ] |
3393 | 3496 |
3394 This concept is somewhat inefficient to express in Ninja (it requires a lot | 3497 This concept is somewhat inefficient to express in Ninja (it requires a lot |
3395 of duplicate of rules) so should only be used when absolutely necessary. | 3498 of duplicate of rules) so should only be used when absolutely necessary. |
3396 | 3499 |
3397 ``` | 3500 ``` |
3398 | 3501 |
3399 ### **Invoking targets in toolchains** | 3502 ### **Example of defining a toolchain** |
3400 | 3503 |
3401 ``` | 3504 ``` |
3402 By default, when a target depends on another, there is an implicit toolchain | 3505 toolchain("32") { |
3403 label that is inherited, so the dependee has the same one as the dependent. | |
3404 | |
3405 You can override this and refer to any other toolchain by explicitly | |
3406 labeling the toolchain to use. For example: | |
3407 data_deps = [ "//plugins:mine(//toolchains:plugin_toolchain)" ] | |
3408 The string "//build/toolchains:plugin_toolchain" is a label that identifies | |
3409 the toolchain declaration for compiling the sources. | |
3410 | |
3411 To load a file in an alternate toolchain, GN does the following: | |
3412 | |
3413 1. Loads the file with the toolchain definition in it (as determined by the | |
3414 toolchain label). | |
3415 2. Re-runs the master build configuration file, applying the arguments | |
3416 specified by the toolchain_args section of the toolchain definition. | |
3417 3. Loads the destination build file in the context of the configuration file | |
3418 in the previous step. | |
3419 | |
3420 ``` | |
3421 | |
3422 ### **Example** | |
3423 | |
3424 ``` | |
3425 toolchain("plugin_toolchain") { | |
3426 tool("cc") { | 3506 tool("cc") { |
3427 command = "gcc {{source}}" | 3507 command = "gcc {{source}}" |
3428 ... | 3508 ... |
3429 } | 3509 } |
3430 | 3510 |
3431 toolchain_args = { | 3511 toolchain_args = { |
3432 is_plugin = true | 3512 use_doom_melon = true # Doom melon always required for 32-bit builds. |
3433 is_32bit = true | 3513 current_cpu = "x86" |
3434 is_64bit = false | |
3435 } | 3514 } |
3436 }; | 3515 } |
| 3516 |
| 3517 toolchain("64") { |
| 3518 tool("cc") { |
| 3519 command = "gcc {{source}}" |
| 3520 ... |
| 3521 } |
| 3522 |
| 3523 toolchain_args = { |
| 3524 # use_doom_melon is not overridden here, it will take the default. |
| 3525 current_cpu = "x64" |
| 3526 } |
| 3527 } |
| 3528 |
| 3529 ``` |
| 3530 |
| 3531 ### **Example of cross-toolchain dependencies** |
| 3532 |
| 3533 ``` |
| 3534 If a 64-bit target wants to depend on a 32-bit binary, it would specify a |
| 3535 dependency using data_deps (data deps are like deps that are only needed at |
| 3536 runtime and aren't linked, since you can't link a 32-bit and a 64-bit |
| 3537 library). |
| 3538 |
| 3539 executable("my_program") { |
| 3540 ... |
| 3541 if (target_cpu == "x64") { |
| 3542 # The 64-bit build needs this 32-bit helper. |
| 3543 data_deps = [ ":helper(//toolchains:32)" ] |
| 3544 } |
| 3545 } |
| 3546 |
| 3547 if (target_cpu == "x86") { |
| 3548 # Our helper library is only compiled in 32-bits. |
| 3549 shared_library("helper") { |
| 3550 ... |
| 3551 } |
| 3552 } |
| 3553 |
3437 | 3554 |
3438 ``` | 3555 ``` |
3439 ## **write_file**: Write a file to disk. | 3556 ## **write_file**: Write a file to disk. |
3440 | 3557 |
3441 ``` | 3558 ``` |
3442 write_file(filename, data) | 3559 write_file(filename, data) |
3443 | 3560 |
3444 If data is a list, the list will be written one-item-per-line with no quoting | 3561 If data is a list, the list will be written one-item-per-line with no quoting |
3445 or brackets. | 3562 or brackets. |
3446 | 3563 |
(...skipping 12 matching lines...) Expand all Loading... |
3459 | 3576 |
3460 ### **Arguments** | 3577 ### **Arguments** |
3461 | 3578 |
3462 ``` | 3579 ``` |
3463 filename | 3580 filename |
3464 Filename to write. This must be within the output directory. | 3581 Filename to write. This must be within the output directory. |
3465 | 3582 |
3466 data | 3583 data |
3467 The list or string to write. | 3584 The list or string to write. |
3468 | 3585 |
| 3586 |
3469 ``` | 3587 ``` |
3470 ## **current_cpu**: The processor architecture of the current toolchain. | 3588 ## **current_cpu**: The processor architecture of the current toolchain. |
3471 | 3589 |
3472 ``` | 3590 ``` |
3473 The build configuration usually sets this value based on the value of | 3591 The build configuration usually sets this value based on the value of |
3474 "host_cpu" (see "gn help host_cpu") and then threads this through the | 3592 "host_cpu" (see "gn help host_cpu") and then threads this through the |
3475 toolchain definitions to ensure that it always reflects the appropriate | 3593 toolchain definitions to ensure that it always reflects the appropriate |
3476 value. | 3594 value. |
3477 | 3595 |
3478 This value is not used internally by GN for any purpose. It is set it to the | 3596 This value is not used internally by GN for any purpose. It is set it to the |
(...skipping 10 matching lines...) Expand all Loading... |
3489 "target_os" (see "gn help target_os"), and then threads this through the | 3607 "target_os" (see "gn help target_os"), and then threads this through the |
3490 toolchain definitions to ensure that it always reflects the appropriate | 3608 toolchain definitions to ensure that it always reflects the appropriate |
3491 value. | 3609 value. |
3492 | 3610 |
3493 This value is not used internally by GN for any purpose. It is set it to the | 3611 This value is not used internally by GN for any purpose. It is set it to the |
3494 empty string ("") by default but is declared so that it can be overridden on | 3612 empty string ("") by default but is declared so that it can be overridden on |
3495 the command line if so desired. | 3613 the command line if so desired. |
3496 | 3614 |
3497 See "gn help target_os" for a list of common values returned. | 3615 See "gn help target_os" for a list of common values returned. |
3498 | 3616 |
| 3617 |
3499 ``` | 3618 ``` |
3500 ## **current_toolchain**: Label of the current toolchain. | 3619 ## **current_toolchain**: Label of the current toolchain. |
3501 | 3620 |
3502 ``` | 3621 ``` |
3503 A fully-qualified label representing the current toolchain. You can use this | 3622 A fully-qualified label representing the current toolchain. You can use this |
3504 to make toolchain-related decisions in the build. See also | 3623 to make toolchain-related decisions in the build. See also |
3505 "default_toolchain". | 3624 "default_toolchain". |
3506 | 3625 |
3507 ``` | 3626 ``` |
3508 | 3627 |
3509 ### **Example** | 3628 ### **Example** |
3510 | 3629 |
3511 ``` | 3630 ``` |
3512 if (current_toolchain == "//build:64_bit_toolchain") { | 3631 if (current_toolchain == "//build:64_bit_toolchain") { |
3513 executable("output_thats_64_bit_only") { | 3632 executable("output_thats_64_bit_only") { |
3514 ... | 3633 ... |
3515 | 3634 |
| 3635 |
3516 ``` | 3636 ``` |
3517 ## **default_toolchain**: [string] Label of the default toolchain. | 3637 ## **default_toolchain**: [string] Label of the default toolchain. |
3518 | 3638 |
3519 ``` | 3639 ``` |
3520 A fully-qualified label representing the default toolchain, which may not | 3640 A fully-qualified label representing the default toolchain, which may not |
3521 necessarily be the current one (see "current_toolchain"). | 3641 necessarily be the current one (see "current_toolchain"). |
3522 | 3642 |
| 3643 |
3523 ``` | 3644 ``` |
3524 ## **host_cpu**: The processor architecture that GN is running on. | 3645 ## **host_cpu**: The processor architecture that GN is running on. |
3525 | 3646 |
3526 ``` | 3647 ``` |
3527 This is value is exposed so that cross-compile toolchains can access the host | 3648 This is value is exposed so that cross-compile toolchains can access the host |
3528 architecture when needed. | 3649 architecture when needed. |
3529 | 3650 |
3530 The value should generally be considered read-only, but it can be overriden | 3651 The value should generally be considered read-only, but it can be overriden |
3531 in order to handle unusual cases where there might be multiple plausible | 3652 in order to handle unusual cases where there might be multiple plausible |
3532 values for the host architecture (e.g., if you can do either 32-bit or 64-bit | 3653 values for the host architecture (e.g., if you can do either 32-bit or 64-bit |
3533 builds). The value is not used internally by GN for any purpose. | 3654 builds). The value is not used internally by GN for any purpose. |
3534 | 3655 |
3535 ``` | 3656 ``` |
3536 | 3657 |
3537 ### **Some possible values** | 3658 ### **Some possible values** |
3538 | 3659 |
3539 ``` | 3660 ``` |
3540 - "x64" | 3661 - "x64" |
3541 - "x86" | 3662 - "x86" |
3542 | 3663 |
| 3664 |
3543 ``` | 3665 ``` |
3544 ## **host_os**: [string] The operating system that GN is running on. | 3666 ## **host_os**: [string] The operating system that GN is running on. |
3545 | 3667 |
3546 ``` | 3668 ``` |
3547 This value is exposed so that cross-compiles can access the host build | 3669 This value is exposed so that cross-compiles can access the host build |
3548 system's settings. | 3670 system's settings. |
3549 | 3671 |
3550 This value should generally be treated as read-only. It, however, is not used | 3672 This value should generally be treated as read-only. It, however, is not used |
3551 internally by GN for any purpose. | 3673 internally by GN for any purpose. |
3552 | 3674 |
3553 ``` | 3675 ``` |
3554 | 3676 |
3555 ### **Some possible values** | 3677 ### **Some possible values** |
3556 | 3678 |
3557 ``` | 3679 ``` |
3558 - "linux" | 3680 - "linux" |
3559 - "mac" | 3681 - "mac" |
3560 - "win" | 3682 - "win" |
3561 | 3683 |
| 3684 |
3562 ``` | 3685 ``` |
3563 ## **invoker**: [string] The invoking scope inside a template. | 3686 ## **invoker**: [string] The invoking scope inside a template. |
3564 | 3687 |
3565 ``` | 3688 ``` |
3566 Inside a template invocation, this variable refers to the scope of the | 3689 Inside a template invocation, this variable refers to the scope of the |
3567 invoker of the template. Outside of template invocations, this variable is | 3690 invoker of the template. Outside of template invocations, this variable is |
3568 undefined. | 3691 undefined. |
3569 | 3692 |
3570 All of the variables defined inside the template invocation are accessible as | 3693 All of the variables defined inside the template invocation are accessible as |
3571 members of the "invoker" scope. This is the way that templates read values | 3694 members of the "invoker" scope. This is the way that templates read values |
(...skipping 13 matching lines...) Expand all Loading... |
3585 print(invoker.sources) # Prints [ "a.cc", "b.cc" ] | 3708 print(invoker.sources) # Prints [ "a.cc", "b.cc" ] |
3586 print(defined(invoker.foo)) # Prints false. | 3709 print(defined(invoker.foo)) # Prints false. |
3587 print(defined(invoker.bar)) # Prints true. | 3710 print(defined(invoker.bar)) # Prints true. |
3588 } | 3711 } |
3589 | 3712 |
3590 my_template("doom_melon") { | 3713 my_template("doom_melon") { |
3591 sources = [ "a.cc", "b.cc" ] | 3714 sources = [ "a.cc", "b.cc" ] |
3592 bar = 123 | 3715 bar = 123 |
3593 } | 3716 } |
3594 | 3717 |
| 3718 |
3595 ``` | 3719 ``` |
3596 ## **python_path**: Absolute path of Python. | 3720 ## **python_path**: Absolute path of Python. |
3597 | 3721 |
3598 ``` | 3722 ``` |
3599 Normally used in toolchain definitions if running some command requires | 3723 Normally used in toolchain definitions if running some command requires |
3600 Python. You will normally not need this when invoking scripts since GN | 3724 Python. You will normally not need this when invoking scripts since GN |
3601 automatically finds it for you. | 3725 automatically finds it for you. |
3602 | 3726 |
| 3727 |
3603 ``` | 3728 ``` |
3604 ## **root_build_dir**: [string] Directory where build commands are run. | 3729 ## **root_build_dir**: [string] Directory where build commands are run. |
3605 | 3730 |
3606 ``` | 3731 ``` |
3607 This is the root build output directory which will be the current directory | 3732 This is the root build output directory which will be the current directory |
3608 when executing all compilers and scripts. | 3733 when executing all compilers and scripts. |
3609 | 3734 |
3610 Most often this is used with rebase_path (see "gn help rebase_path") to | 3735 Most often this is used with rebase_path (see "gn help rebase_path") to |
3611 convert arguments to be relative to a script's current directory. | 3736 convert arguments to be relative to a script's current directory. |
3612 | 3737 |
| 3738 |
3613 ``` | 3739 ``` |
3614 ## **root_gen_dir**: Directory for the toolchain's generated files. | 3740 ## **root_gen_dir**: Directory for the toolchain's generated files. |
3615 | 3741 |
3616 ``` | 3742 ``` |
3617 Absolute path to the root of the generated output directory tree for the | 3743 Absolute path to the root of the generated output directory tree for the |
3618 current toolchain. An example would be "//out/Debug/gen" for the default | 3744 current toolchain. An example would be "//out/Debug/gen" for the default |
3619 toolchain, or "//out/Debug/arm/gen" for the "arm" toolchain. | 3745 toolchain, or "//out/Debug/arm/gen" for the "arm" toolchain. |
3620 | 3746 |
3621 This is primarily useful for setting up include paths for generated files. If | 3747 This is primarily useful for setting up include paths for generated files. If |
3622 you are passing this to a script, you will want to pass it through | 3748 you are passing this to a script, you will want to pass it through |
3623 rebase_path() (see "gn help rebase_path") to convert it to be relative to the | 3749 rebase_path() (see "gn help rebase_path") to convert it to be relative to the |
3624 build directory. | 3750 build directory. |
3625 | 3751 |
3626 See also "target_gen_dir" which is usually a better location for generated | 3752 See also "target_gen_dir" which is usually a better location for generated |
3627 files. It will be inside the root generated dir. | 3753 files. It will be inside the root generated dir. |
3628 | 3754 |
| 3755 |
3629 ``` | 3756 ``` |
3630 ## **root_out_dir**: [string] Root directory for toolchain output files. | 3757 ## **root_out_dir**: [string] Root directory for toolchain output files. |
3631 | 3758 |
3632 ``` | 3759 ``` |
3633 Absolute path to the root of the output directory tree for the current | 3760 Absolute path to the root of the output directory tree for the current |
3634 toolchain. It will not have a trailing slash. | 3761 toolchain. It will not have a trailing slash. |
3635 | 3762 |
3636 For the default toolchain this will be the same as the root_build_dir. An | 3763 For the default toolchain this will be the same as the root_build_dir. An |
3637 example would be "//out/Debug" for the default toolchain, or | 3764 example would be "//out/Debug" for the default toolchain, or |
3638 "//out/Debug/arm" for the "arm" toolchain. | 3765 "//out/Debug/arm" for the "arm" toolchain. |
3639 | 3766 |
3640 This is primarily useful for setting up script calls. If you are passing this | 3767 This is primarily useful for setting up script calls. If you are passing this |
3641 to a script, you will want to pass it through rebase_path() (see "gn help | 3768 to a script, you will want to pass it through rebase_path() (see "gn help |
3642 rebase_path") to convert it to be relative to the build directory. | 3769 rebase_path") to convert it to be relative to the build directory. |
3643 | 3770 |
3644 See also "target_out_dir" which is usually a better location for output | 3771 See also "target_out_dir" which is usually a better location for output |
3645 files. It will be inside the root output dir. | 3772 files. It will be inside the root output dir. |
3646 | 3773 |
3647 ``` | 3774 ``` |
3648 | 3775 |
3649 ### **Example** | 3776 ### **Example** |
3650 | 3777 |
3651 ``` | 3778 ``` |
3652 action("myscript") { | 3779 action("myscript") { |
3653 # Pass the output dir to the script. | 3780 # Pass the output dir to the script. |
3654 args = [ "-o", rebase_path(root_out_dir, root_build_dir) ] | 3781 args = [ "-o", rebase_path(root_out_dir, root_build_dir) ] |
3655 } | 3782 } |
3656 | 3783 |
| 3784 |
3657 ``` | 3785 ``` |
3658 ## **target_cpu**: The desired cpu architecture for the build. | 3786 ## **target_cpu**: The desired cpu architecture for the build. |
3659 | 3787 |
3660 ``` | 3788 ``` |
3661 This value should be used to indicate the desired architecture for the | 3789 This value should be used to indicate the desired architecture for the |
3662 primary objects of the build. It will match the cpu architecture of the | 3790 primary objects of the build. It will match the cpu architecture of the |
3663 default toolchain, but not necessarily the current toolchain. | 3791 default toolchain, but not necessarily the current toolchain. |
3664 | 3792 |
3665 In many cases, this is the same as "host_cpu", but in the case of | 3793 In many cases, this is the same as "host_cpu", but in the case of |
3666 cross-compiles, this can be set to something different. This value is | 3794 cross-compiles, this can be set to something different. This value is |
(...skipping 11 matching lines...) Expand all Loading... |
3678 | 3806 |
3679 ### **Possible values** | 3807 ### **Possible values** |
3680 | 3808 |
3681 ``` | 3809 ``` |
3682 - "x86" | 3810 - "x86" |
3683 - "x64" | 3811 - "x64" |
3684 - "arm" | 3812 - "arm" |
3685 - "arm64" | 3813 - "arm64" |
3686 - "mipsel" | 3814 - "mipsel" |
3687 | 3815 |
| 3816 |
3688 ``` | 3817 ``` |
3689 ## **target_gen_dir**: Directory for a target's generated files. | 3818 ## **target_gen_dir**: Directory for a target's generated files. |
3690 | 3819 |
3691 ``` | 3820 ``` |
3692 Absolute path to the target's generated file directory. This will be the | 3821 Absolute path to the target's generated file directory. This will be the |
3693 "root_gen_dir" followed by the relative path to the current build file. If | 3822 "root_gen_dir" followed by the relative path to the current build file. If |
3694 your file is in "//tools/doom_melon" then target_gen_dir would be | 3823 your file is in "//tools/doom_melon" then target_gen_dir would be |
3695 "//out/Debug/gen/tools/doom_melon". It will not have a trailing slash. | 3824 "//out/Debug/gen/tools/doom_melon". It will not have a trailing slash. |
3696 | 3825 |
3697 This is primarily useful for setting up include paths for generated files. If | 3826 This is primarily useful for setting up include paths for generated files. If |
3698 you are passing this to a script, you will want to pass it through | 3827 you are passing this to a script, you will want to pass it through |
3699 rebase_path() (see "gn help rebase_path") to convert it to be relative to the | 3828 rebase_path() (see "gn help rebase_path") to convert it to be relative to the |
3700 build directory. | 3829 build directory. |
3701 | 3830 |
3702 See also "gn help root_gen_dir". | 3831 See also "gn help root_gen_dir". |
3703 | 3832 |
3704 ``` | 3833 ``` |
3705 | 3834 |
3706 ### **Example** | 3835 ### **Example** |
3707 | 3836 |
3708 ``` | 3837 ``` |
3709 action("myscript") { | 3838 action("myscript") { |
3710 # Pass the generated output dir to the script. | 3839 # Pass the generated output dir to the script. |
3711 args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]" | 3840 args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]" |
3712 } | 3841 } |
3713 | 3842 |
| 3843 |
3714 ``` | 3844 ``` |
3715 ## **target_name**: [string] The name of the current target. | 3845 ## **target_name**: [string] The name of the current target. |
3716 | 3846 |
3717 ``` | 3847 ``` |
3718 Inside a target or template invocation, this variable refers to the name | 3848 Inside a target or template invocation, this variable refers to the name |
3719 given to the target or template invocation. Outside of these, this variable | 3849 given to the target or template invocation. Outside of these, this variable |
3720 is undefined. | 3850 is undefined. |
3721 | 3851 |
3722 This is most often used in template definitions to name targets defined in | 3852 This is most often used in template definitions to name targets defined in |
3723 the template based on the name of the invocation. This is necessary both to | 3853 the template based on the name of the invocation. This is necessary both to |
(...skipping 21 matching lines...) Expand all Loading... |
3745 print(target_name) # Prints "space_ray" when invoked below. | 3875 print(target_name) # Prints "space_ray" when invoked below. |
3746 | 3876 |
3747 executable(target_name + "_impl") { | 3877 executable(target_name + "_impl") { |
3748 print(target_name) # Prints "space_ray_impl". | 3878 print(target_name) # Prints "space_ray_impl". |
3749 } | 3879 } |
3750 } | 3880 } |
3751 | 3881 |
3752 my_template("space_ray") { | 3882 my_template("space_ray") { |
3753 } | 3883 } |
3754 | 3884 |
| 3885 |
3755 ``` | 3886 ``` |
3756 ## **target_os**: The desired operating system for the build. | 3887 ## **target_os**: The desired operating system for the build. |
3757 | 3888 |
3758 ``` | 3889 ``` |
3759 This value should be used to indicate the desired operating system for the | 3890 This value should be used to indicate the desired operating system for the |
3760 primary object(s) of the build. It will match the OS of the default | 3891 primary object(s) of the build. It will match the OS of the default |
3761 toolchain. | 3892 toolchain. |
3762 | 3893 |
3763 In many cases, this is the same as "host_os", but in the case of | 3894 In many cases, this is the same as "host_os", but in the case of |
3764 cross-compiles, it may be different. This variable differs from "current_os" | 3895 cross-compiles, it may be different. This variable differs from "current_os" |
(...skipping 23 matching lines...) Expand all Loading... |
3788 | 3919 |
3789 ``` | 3920 ``` |
3790 - "android" | 3921 - "android" |
3791 - "chromeos" | 3922 - "chromeos" |
3792 - "ios" | 3923 - "ios" |
3793 - "linux" | 3924 - "linux" |
3794 - "nacl" | 3925 - "nacl" |
3795 - "mac" | 3926 - "mac" |
3796 - "win" | 3927 - "win" |
3797 | 3928 |
| 3929 |
3798 ``` | 3930 ``` |
3799 ## **target_out_dir**: [string] Directory for target output files. | 3931 ## **target_out_dir**: [string] Directory for target output files. |
3800 | 3932 |
3801 ``` | 3933 ``` |
3802 Absolute path to the target's generated file directory. If your current | 3934 Absolute path to the target's generated file directory. If your current |
3803 target is in "//tools/doom_melon" then this value might be | 3935 target is in "//tools/doom_melon" then this value might be |
3804 "//out/Debug/obj/tools/doom_melon". It will not have a trailing slash. | 3936 "//out/Debug/obj/tools/doom_melon". It will not have a trailing slash. |
3805 | 3937 |
3806 This is primarily useful for setting up arguments for calling scripts. If you | 3938 This is primarily useful for setting up arguments for calling scripts. If you |
3807 are passing this to a script, you will want to pass it through rebase_path() | 3939 are passing this to a script, you will want to pass it through rebase_path() |
3808 (see "gn help rebase_path") to convert it to be relative to the build | 3940 (see "gn help rebase_path") to convert it to be relative to the build |
3809 directory. | 3941 directory. |
3810 | 3942 |
3811 See also "gn help root_out_dir". | 3943 See also "gn help root_out_dir". |
3812 | 3944 |
3813 ``` | 3945 ``` |
3814 | 3946 |
3815 ### **Example** | 3947 ### **Example** |
3816 | 3948 |
3817 ``` | 3949 ``` |
3818 action("myscript") { | 3950 action("myscript") { |
3819 # Pass the output dir to the script. | 3951 # Pass the output dir to the script. |
3820 args = [ "-o", rebase_path(target_out_dir, root_build_dir) ]" | 3952 args = [ "-o", rebase_path(target_out_dir, root_build_dir) ]" |
3821 | 3953 |
3822 } | 3954 } |
3823 | 3955 |
| 3956 |
3824 ``` | 3957 ``` |
3825 ## **all_dependent_configs**: Configs to be forced on dependents. | 3958 ## **all_dependent_configs**: Configs to be forced on dependents. |
3826 | 3959 |
3827 ``` | 3960 ``` |
3828 A list of config labels. | 3961 A list of config labels. |
3829 | 3962 |
3830 All targets depending on this one, and recursively, all targets depending on | 3963 All targets depending on this one, and recursively, all targets depending on |
3831 those, will have the configs listed in this variable added to them. These | 3964 those, will have the configs listed in this variable added to them. These |
3832 configs will also apply to the current target. | 3965 configs will also apply to the current target. |
3833 | 3966 |
(...skipping 96 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3930 source_set("b") { | 4063 source_set("b") { |
3931 deps = [ ":a_b_shared_deps" ] | 4064 deps = [ ":a_b_shared_deps" ] |
3932 # Sources here can include headers from a despite lack of deps. | 4065 # Sources here can include headers from a despite lack of deps. |
3933 ... | 4066 ... |
3934 } | 4067 } |
3935 | 4068 |
3936 group("a_b_shared_deps") { | 4069 group("a_b_shared_deps") { |
3937 public_deps = [ ":c" ] | 4070 public_deps = [ ":c" ] |
3938 } | 4071 } |
3939 | 4072 |
| 4073 |
3940 ``` | 4074 ``` |
3941 ## **arflags**: Arguments passed to static_library archiver. | 4075 ## **arflags**: Arguments passed to static_library archiver. |
3942 | 4076 |
3943 ``` | 4077 ``` |
3944 A list of flags passed to the archive/lib command that creates static | 4078 A list of flags passed to the archive/lib command that creates static |
3945 libraries. | 4079 libraries. |
3946 | 4080 |
3947 arflags are NOT pushed to dependents, so applying arflags to source sets or | 4081 arflags are NOT pushed to dependents, so applying arflags to source sets or |
3948 any other target type will be a no-op. As with ldflags, you could put the | 4082 any other target type will be a no-op. As with ldflags, you could put the |
3949 arflags in a config and set that as a public or "all dependent" config, but | 4083 arflags in a config and set that as a public or "all dependent" config, but |
(...skipping 26 matching lines...) Expand all Loading... |
3976 ``` | 4110 ``` |
3977 ## **args**: Arguments passed to an action. | 4111 ## **args**: Arguments passed to an action. |
3978 | 4112 |
3979 ``` | 4113 ``` |
3980 For action and action_foreach targets, args is the list of arguments to pass | 4114 For action and action_foreach targets, args is the list of arguments to pass |
3981 to the script. Typically you would use source expansion (see "gn help | 4115 to the script. Typically you would use source expansion (see "gn help |
3982 source_expansion") to insert the source file names. | 4116 source_expansion") to insert the source file names. |
3983 | 4117 |
3984 See also "gn help action" and "gn help action_foreach". | 4118 See also "gn help action" and "gn help action_foreach". |
3985 | 4119 |
| 4120 |
3986 ``` | 4121 ``` |
3987 ## **asmflags**: Flags passed to the assembler. | 4122 ## **asmflags**: Flags passed to the assembler. |
3988 | 4123 |
3989 ``` | 4124 ``` |
3990 A list of strings. | 4125 A list of strings. |
3991 | 4126 |
3992 "asmflags" are passed to any invocation of a tool that takes an .asm or .S | 4127 "asmflags" are passed to any invocation of a tool that takes an .asm or .S |
3993 file as input. | 4128 file as input. |
3994 | 4129 |
3995 ``` | 4130 ``` |
(...skipping 51 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4047 ``` | 4182 ``` |
4048 executable("doom_melon") { | 4183 executable("doom_melon") { |
4049 deps = [ "//foo:bar" ] | 4184 deps = [ "//foo:bar" ] |
4050 ... | 4185 ... |
4051 assert_no_deps = [ | 4186 assert_no_deps = [ |
4052 "//evil/*", # Don't link any code from the evil directory. | 4187 "//evil/*", # Don't link any code from the evil directory. |
4053 "//foo:test_support", # This target is also disallowed. | 4188 "//foo:test_support", # This target is also disallowed. |
4054 ] | 4189 ] |
4055 } | 4190 } |
4056 | 4191 |
| 4192 |
4057 ``` | 4193 ``` |
4058 ## **bundle_deps_filter**: [label list] A list of labels that are filtered out. | 4194 ## **bundle_deps_filter**: [label list] A list of labels that are filtered out. |
4059 | 4195 |
4060 ``` | 4196 ``` |
4061 A list of target labels. | 4197 A list of target labels. |
4062 | 4198 |
4063 This list contains target label patterns that should be filtered out when | 4199 This list contains target label patterns that should be filtered out when |
4064 creating the bundle. Any target matching one of those label will be removed | 4200 creating the bundle. Any target matching one of those label will be removed |
4065 from the dependencies of the create_bundle target. | 4201 from the dependencies of the create_bundle target. |
4066 | 4202 |
(...skipping 13 matching lines...) Expand all Loading... |
4080 "//base" | 4216 "//base" |
4081 ] | 4217 ] |
4082 bundle_root_dir = "$root_out_dir/today_extension.appex" | 4218 bundle_root_dir = "$root_out_dir/today_extension.appex" |
4083 bundle_deps_filter = [ | 4219 bundle_deps_filter = [ |
4084 # The extension uses //base but does not use any function calling into | 4220 # The extension uses //base but does not use any function calling into |
4085 # third_party/icu and thus does not need the icudtl.dat file. | 4221 # third_party/icu and thus does not need the icudtl.dat file. |
4086 "//third_party/icu:icudata", | 4222 "//third_party/icu:icudata", |
4087 ] | 4223 ] |
4088 } | 4224 } |
4089 | 4225 |
4090 ``` | |
4091 ## **bundle_executable_dir**: Expansion of {{bundle_executable_dir}} in create_b
undle. | |
4092 | 4226 |
4093 ``` | 4227 ``` |
| 4228 ## **bundle_executable_dir**: Expansion of {{bundle_executable_dir}} in |
| 4229 ``` |
| 4230 create_bundle. |
| 4231 |
4094 A string corresponding to a path in $root_build_dir. | 4232 A string corresponding to a path in $root_build_dir. |
4095 | 4233 |
4096 This string is used by the "create_bundle" target to expand the | 4234 This string is used by the "create_bundle" target to expand the |
4097 {{bundle_executable_dir}} of the "bundle_data" target it depends on. This | 4235 {{bundle_executable_dir}} of the "bundle_data" target it depends on. This |
4098 must correspond to a path under "bundle_root_dir". | 4236 must correspond to a path under "bundle_root_dir". |
4099 | 4237 |
4100 See "gn help bundle_root_dir" for examples. | 4238 See "gn help bundle_root_dir" for examples. |
4101 | 4239 |
| 4240 |
4102 ``` | 4241 ``` |
4103 ## **bundle_plugins_dir**: Expansion of {{bundle_plugins_dir}} in create_bundle. | 4242 ## **bundle_plugins_dir**: Expansion of {{bundle_plugins_dir}} in create_bundle. |
4104 | 4243 |
4105 ``` | 4244 ``` |
4106 A string corresponding to a path in $root_build_dir. | 4245 A string corresponding to a path in $root_build_dir. |
4107 | 4246 |
4108 This string is used by the "create_bundle" target to expand the | 4247 This string is used by the "create_bundle" target to expand the |
4109 {{bundle_plugins_dir}} of the "bundle_data" target it depends on. This must | 4248 {{bundle_plugins_dir}} of the "bundle_data" target it depends on. This must |
4110 correspond to a path under "bundle_root_dir". | 4249 correspond to a path under "bundle_root_dir". |
4111 | 4250 |
4112 See "gn help bundle_root_dir" for examples. | 4251 See "gn help bundle_root_dir" for examples. |
4113 | 4252 |
4114 ``` | |
4115 ## **bundle_resources_dir**: Expansion of {{bundle_resources_dir}} in create_bun
dle. | |
4116 | 4253 |
4117 ``` | 4254 ``` |
| 4255 ## **bundle_resources_dir**: Expansion of {{bundle_resources_dir}} in |
| 4256 ``` |
| 4257 create_bundle. |
| 4258 |
4118 A string corresponding to a path in $root_build_dir. | 4259 A string corresponding to a path in $root_build_dir. |
4119 | 4260 |
4120 This string is used by the "create_bundle" target to expand the | 4261 This string is used by the "create_bundle" target to expand the |
4121 {{bundle_resources_dir}} of the "bundle_data" target it depends on. This must | 4262 {{bundle_resources_dir}} of the "bundle_data" target it depends on. This must |
4122 correspond to a path under "bundle_root_dir". | 4263 correspond to a path under "bundle_root_dir". |
4123 | 4264 |
4124 See "gn help bundle_root_dir" for examples. | 4265 See "gn help bundle_root_dir" for examples. |
4125 | 4266 |
| 4267 |
4126 ``` | 4268 ``` |
4127 ## **bundle_root_dir**: Expansion of {{bundle_root_dir}} in create_bundle. | 4269 ## **bundle_root_dir**: Expansion of {{bundle_root_dir}} in create_bundle. |
4128 | 4270 |
4129 ``` | 4271 ``` |
4130 A string corresponding to a path in root_build_dir. | 4272 A string corresponding to a path in root_build_dir. |
4131 | 4273 |
4132 This string is used by the "create_bundle" target to expand the | 4274 This string is used by the "create_bundle" target to expand the |
4133 {{bundle_root_dir}} of the "bundle_data" target it depends on. This must | 4275 {{bundle_root_dir}} of the "bundle_data" target it depends on. This must |
4134 correspond to a path under root_build_dir. | 4276 correspond to a path under root_build_dir. |
4135 | 4277 |
4136 ``` | 4278 ``` |
4137 | 4279 |
4138 ### **Example** | 4280 ### **Example** |
4139 | 4281 |
4140 ``` | 4282 ``` |
4141 bundle_data("info_plist") { | 4283 bundle_data("info_plist") { |
4142 sources = [ "Info.plist" ] | 4284 sources = [ "Info.plist" ] |
4143 outputs = [ "{{bundle_root_dir}}/Info.plist" ] | 4285 outputs = [ "{{bundle_root_dir}}/Info.plist" ] |
4144 } | 4286 } |
4145 | 4287 |
4146 create_bundle("doom_melon.app") { | 4288 create_bundle("doom_melon.app") { |
4147 deps = [ ":info_plist" ] | 4289 deps = [ ":info_plist" ] |
4148 bundle_root_dir = root_build_dir + "/doom_melon.app/Contents" | 4290 bundle_root_dir = root_build_dir + "/doom_melon.app/Contents" |
4149 bundle_resources_dir = bundle_root_dir + "/Resources" | 4291 bundle_resources_dir = bundle_root_dir + "/Resources" |
4150 bundle_executable_dir = bundle_root_dir + "/MacOS" | 4292 bundle_executable_dir = bundle_root_dir + "/MacOS" |
4151 bundle_plugins_dir = bundle_root_dir + "/PlugIns" | 4293 bundle_plugins_dir = bundle_root_dir + "/PlugIns" |
4152 } | 4294 } |
4153 | 4295 |
| 4296 |
4154 ``` | 4297 ``` |
4155 ## **cflags***: Flags passed to the C compiler. | 4298 ## **cflags***: Flags passed to the C compiler. |
4156 | 4299 |
4157 ``` | 4300 ``` |
4158 A list of strings. | 4301 A list of strings. |
4159 | 4302 |
4160 "cflags" are passed to all invocations of the C, C++, Objective C, and | 4303 "cflags" are passed to all invocations of the C, C++, Objective C, and |
4161 Objective C++ compilers. | 4304 Objective C++ compilers. |
4162 | 4305 |
4163 To target one of these variants individually, use "cflags_c", "cflags_cc", | 4306 To target one of these variants individually, use "cflags_c", "cflags_cc", |
(...skipping 190 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4354 | 4497 |
4355 ### **Example** | 4498 ### **Example** |
4356 | 4499 |
4357 ``` | 4500 ``` |
4358 source_set("busted_includes") { | 4501 source_set("busted_includes") { |
4359 # This target's includes are messed up, exclude it from checking. | 4502 # This target's includes are messed up, exclude it from checking. |
4360 check_includes = false | 4503 check_includes = false |
4361 ... | 4504 ... |
4362 } | 4505 } |
4363 | 4506 |
| 4507 |
4364 ``` | 4508 ``` |
4365 ## **code_signing_args**: [string list] Arguments passed to code signing script. | 4509 ## **code_signing_args**: [string list] Arguments passed to code signing script. |
4366 | 4510 |
4367 ``` | 4511 ``` |
4368 For create_bundle targets, code_signing_args is the list of arguments to pass | 4512 For create_bundle targets, code_signing_args is the list of arguments to pass |
4369 to the code signing script. Typically you would use source expansion (see "gn | 4513 to the code signing script. Typically you would use source expansion (see "gn |
4370 help source_expansion") to insert the source file names. | 4514 help source_expansion") to insert the source file names. |
4371 | 4515 |
4372 See also "gn help create_bundle". | 4516 See also "gn help create_bundle". |
4373 | 4517 |
| 4518 |
4374 ``` | 4519 ``` |
4375 ## **code_signing_outputs**: [file list] Output files for code signing step. | 4520 ## **code_signing_outputs**: [file list] Output files for code signing step. |
4376 | 4521 |
4377 ``` | 4522 ``` |
4378 Outputs from the code signing step of a create_bundle target. Must refer to | 4523 Outputs from the code signing step of a create_bundle target. Must refer to |
4379 files in the build directory. | 4524 files in the build directory. |
4380 | 4525 |
4381 See also "gn help create_bundle". | 4526 See also "gn help create_bundle". |
4382 | 4527 |
| 4528 |
4383 ``` | 4529 ``` |
4384 ## **code_signing_script**: [file name] Script for code signing." | 4530 ## **code_signing_script**: [file name] Script for code signing." |
4385 | 4531 |
4386 ``` | 4532 ``` |
4387 An absolute or buildfile-relative file name of a Python script to run for a | 4533 An absolute or buildfile-relative file name of a Python script to run for a |
4388 create_bundle target to perform code signing step. | 4534 create_bundle target to perform code signing step. |
4389 | 4535 |
4390 See also "gn help create_bundle". | 4536 See also "gn help create_bundle". |
4391 | 4537 |
| 4538 |
4392 ``` | 4539 ``` |
4393 ## **code_signing_sources**: [file list] Sources for code signing step. | 4540 ## **code_signing_sources**: [file list] Sources for code signing step. |
4394 | 4541 |
4395 ``` | 4542 ``` |
4396 A list of files used as input for code signing script step of a create_bundle | 4543 A list of files used as input for code signing script step of a create_bundle |
4397 target. Non-absolute paths will be resolved relative to the current build | 4544 target. Non-absolute paths will be resolved relative to the current build |
4398 file. | 4545 file. |
4399 | 4546 |
4400 See also "gn help create_bundle". | 4547 See also "gn help create_bundle". |
4401 | 4548 |
| 4549 |
4402 ``` | 4550 ``` |
4403 ## **complete_static_lib**: [boolean] Links all deps into a static library. | 4551 ## **complete_static_lib**: [boolean] Links all deps into a static library. |
4404 | 4552 |
4405 ``` | 4553 ``` |
4406 A static library normally doesn't include code from dependencies, but instead | 4554 A static library normally doesn't include code from dependencies, but instead |
4407 forwards the static libraries and source sets in its deps up the dependency | 4555 forwards the static libraries and source sets in its deps up the dependency |
4408 chain until a linkable target (an executable or shared library) is reached. | 4556 chain until a linkable target (an executable or shared library) is reached. |
4409 The final linkable target only links each static library once, even if it | 4557 The final linkable target only links each static library once, even if it |
4410 appears more than once in its dependency graph. | 4558 appears more than once in its dependency graph. |
4411 | 4559 |
(...skipping 17 matching lines...) Expand all Loading... |
4429 ``` | 4577 ``` |
4430 | 4578 |
4431 ### **Example** | 4579 ### **Example** |
4432 | 4580 |
4433 ``` | 4581 ``` |
4434 static_library("foo") { | 4582 static_library("foo") { |
4435 complete_static_lib = true | 4583 complete_static_lib = true |
4436 deps = [ "bar" ] | 4584 deps = [ "bar" ] |
4437 } | 4585 } |
4438 | 4586 |
| 4587 |
4439 ``` | 4588 ``` |
4440 ## **configs**: Configs applying to this target or config. | 4589 ## **configs**: Configs applying to this target or config. |
4441 | 4590 |
4442 ``` | 4591 ``` |
4443 A list of config labels. | 4592 A list of config labels. |
4444 | 4593 |
4445 ``` | 4594 ``` |
4446 | 4595 |
4447 ### **Configs on a target** | 4596 ### **Configs on a target** |
4448 | 4597 |
(...skipping 78 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4527 cflags = [ ... ] | 4676 cflags = [ ... ] |
4528 } | 4677 } |
4529 config("default_optimization") { | 4678 config("default_optimization") { |
4530 if (optimize_everything) { | 4679 if (optimize_everything) { |
4531 configs = [ ":super_optimization" ] | 4680 configs = [ ":super_optimization" ] |
4532 } else { | 4681 } else { |
4533 configs = [ ":no_optimization" ] | 4682 configs = [ ":no_optimization" ] |
4534 } | 4683 } |
4535 } | 4684 } |
4536 | 4685 |
| 4686 |
4537 ``` | 4687 ``` |
4538 ## **console**: Run this action in the console pool. | 4688 ## **console**: Run this action in the console pool. |
4539 | 4689 |
4540 ``` | 4690 ``` |
4541 Boolean. Defaults to false. | 4691 Boolean. Defaults to false. |
4542 | 4692 |
4543 Actions marked "console = true" will be run in the built-in ninja "console" | 4693 Actions marked "console = true" will be run in the built-in ninja "console" |
4544 pool. They will have access to real stdin and stdout, and output will not be | 4694 pool. They will have access to real stdin and stdout, and output will not be |
4545 buffered by ninja. This can be useful for long-running actions with progress | 4695 buffered by ninja. This can be useful for long-running actions with progress |
4546 logs, or actions that require user input. | 4696 logs, or actions that require user input. |
4547 | 4697 |
4548 Only one console pool target can run at any one time in Ninja. Refer to the | 4698 Only one console pool target can run at any one time in Ninja. Refer to the |
4549 Ninja documentation on the console pool for more info. | 4699 Ninja documentation on the console pool for more info. |
4550 | 4700 |
4551 ``` | 4701 ``` |
4552 | 4702 |
4553 ### **Example** | 4703 ### **Example** |
4554 | 4704 |
4555 ``` | 4705 ``` |
4556 action("long_action_with_progress_logs") { | 4706 action("long_action_with_progress_logs") { |
4557 console = true | 4707 console = true |
4558 } | 4708 } |
4559 | 4709 |
| 4710 |
4560 ``` | 4711 ``` |
4561 ## **data**: Runtime data file dependencies. | 4712 ## **data**: Runtime data file dependencies. |
4562 | 4713 |
4563 ``` | 4714 ``` |
4564 Lists files or directories required to run the given target. These are | 4715 Lists files or directories required to run the given target. These are |
4565 typically data files or directories of data files. The paths are interpreted | 4716 typically data files or directories of data files. The paths are interpreted |
4566 as being relative to the current build file. Since these are runtime | 4717 as being relative to the current build file. Since these are runtime |
4567 dependencies, they do not affect which targets are built or when. To declare | 4718 dependencies, they do not affect which targets are built or when. To declare |
4568 input files to a script, use "inputs". | 4719 input files to a script, use "inputs". |
4569 | 4720 |
(...skipping 10 matching lines...) Expand all Loading... |
4580 By convention, directories are listed with a trailing slash: | 4731 By convention, directories are listed with a trailing slash: |
4581 data = [ "test/data/" ] | 4732 data = [ "test/data/" ] |
4582 However, no verification is done on these so GN doesn't enforce this. The | 4733 However, no verification is done on these so GN doesn't enforce this. The |
4583 paths are just rebased and passed along when requested. | 4734 paths are just rebased and passed along when requested. |
4584 | 4735 |
4585 Note: On iOS and OS X, create_bundle targets will not be recursed into when | 4736 Note: On iOS and OS X, create_bundle targets will not be recursed into when |
4586 gathering data. See "gn help create_bundle" for details. | 4737 gathering data. See "gn help create_bundle" for details. |
4587 | 4738 |
4588 See "gn help runtime_deps" for how these are used. | 4739 See "gn help runtime_deps" for how these are used. |
4589 | 4740 |
| 4741 |
4590 ``` | 4742 ``` |
4591 ## **data_deps**: Non-linked dependencies. | 4743 ## **data_deps**: Non-linked dependencies. |
4592 | 4744 |
4593 ``` | 4745 ``` |
4594 A list of target labels. | 4746 A list of target labels. |
4595 | 4747 |
4596 Specifies dependencies of a target that are not actually linked into the | 4748 Specifies dependencies of a target that are not actually linked into the |
4597 current target. Such dependencies will be built and will be available at | 4749 current target. Such dependencies will be built and will be available at |
4598 runtime. | 4750 runtime. |
4599 | 4751 |
4600 This is normally used for things like plugins or helper programs that a | 4752 This is normally used for things like plugins or helper programs that a |
4601 target needs at runtime. | 4753 target needs at runtime. |
4602 | 4754 |
4603 Note: On iOS and OS X, create_bundle targets will not be recursed into when | 4755 Note: On iOS and OS X, create_bundle targets will not be recursed into when |
4604 gathering data_deps. See "gn help create_bundle" for details. | 4756 gathering data_deps. See "gn help create_bundle" for details. |
4605 | 4757 |
4606 See also "gn help deps" and "gn help data". | 4758 See also "gn help deps" and "gn help data". |
4607 | 4759 |
4608 ``` | 4760 ``` |
4609 | 4761 |
4610 ### **Example** | 4762 ### **Example** |
4611 | 4763 |
4612 ``` | 4764 ``` |
4613 executable("foo") { | 4765 executable("foo") { |
4614 deps = [ "//base" ] | 4766 deps = [ "//base" ] |
4615 data_deps = [ "//plugins:my_runtime_plugin" ] | 4767 data_deps = [ "//plugins:my_runtime_plugin" ] |
4616 } | 4768 } |
4617 | 4769 |
| 4770 |
4618 ``` | 4771 ``` |
4619 ## **defines**: C preprocessor defines. | 4772 ## **defines**: C preprocessor defines. |
4620 | 4773 |
4621 ``` | 4774 ``` |
4622 A list of strings | 4775 A list of strings |
4623 | 4776 |
4624 These strings will be passed to the C/C++ compiler as #defines. The strings | 4777 These strings will be passed to the C/C++ compiler as #defines. The strings |
4625 may or may not include an "=" to assign a value. | 4778 may or may not include an "=" to assign a value. |
4626 | 4779 |
4627 ``` | 4780 ``` |
(...skipping 15 matching lines...) Expand all Loading... |
4643 "deps" list. If a dependency is public, they will be applied | 4796 "deps" list. If a dependency is public, they will be applied |
4644 recursively. | 4797 recursively. |
4645 | 4798 |
4646 ``` | 4799 ``` |
4647 | 4800 |
4648 ### **Example** | 4801 ### **Example** |
4649 | 4802 |
4650 ``` | 4803 ``` |
4651 defines = [ "AWESOME_FEATURE", "LOG_LEVEL=3" ] | 4804 defines = [ "AWESOME_FEATURE", "LOG_LEVEL=3" ] |
4652 | 4805 |
| 4806 |
4653 ``` | 4807 ``` |
4654 ## **depfile**: [string] File name for input dependencies for actions. | 4808 ## **depfile**: [string] File name for input dependencies for actions. |
4655 | 4809 |
4656 ``` | 4810 ``` |
4657 If nonempty, this string specifies that the current action or action_foreach | 4811 If nonempty, this string specifies that the current action or action_foreach |
4658 target will generate the given ".d" file containing the dependencies of the | 4812 target will generate the given ".d" file containing the dependencies of the |
4659 input. Empty or unset means that the script doesn't generate the files. | 4813 input. Empty or unset means that the script doesn't generate the files. |
4660 | 4814 |
4661 A depfile should be used only when a target depends on files that are not | 4815 A depfile should be used only when a target depends on files that are not |
4662 already specified by a target's inputs and sources. Likewise, depfiles should | 4816 already specified by a target's inputs and sources. Likewise, depfiles should |
(...skipping 21 matching lines...) Expand all Loading... |
4684 sources = [ ... ] | 4838 sources = [ ... ] |
4685 | 4839 |
4686 # Locate the depfile in the output directory named like the | 4840 # Locate the depfile in the output directory named like the |
4687 # inputs but with a ".d" appended. | 4841 # inputs but with a ".d" appended. |
4688 depfile = "$relative_target_output_dir/{{source_name}}.d" | 4842 depfile = "$relative_target_output_dir/{{source_name}}.d" |
4689 | 4843 |
4690 # Say our script uses "-o <d file>" to indicate the depfile. | 4844 # Say our script uses "-o <d file>" to indicate the depfile. |
4691 args = [ "{{source}}", "-o", depfile ] | 4845 args = [ "{{source}}", "-o", depfile ] |
4692 } | 4846 } |
4693 | 4847 |
| 4848 |
4694 ``` | 4849 ``` |
4695 ## **deps**: Private linked dependencies. | 4850 ## **deps**: Private linked dependencies. |
4696 | 4851 |
4697 ``` | 4852 ``` |
4698 A list of target labels. | 4853 A list of target labels. |
4699 | 4854 |
4700 Specifies private dependencies of a target. Private dependencies are | 4855 Specifies private dependencies of a target. Private dependencies are |
4701 propagated up the dependency tree and linked to dependant targets, but do not | 4856 propagated up the dependency tree and linked to dependant targets, but do not |
4702 grant the ability to include headers from the dependency. Public configs are | 4857 grant the ability to include headers from the dependency. Public configs are |
4703 not forwarded. | 4858 not forwarded. |
(...skipping 15 matching lines...) Expand all Loading... |
4719 Propagation of all_dependent_configs and public_configs happens independently | 4874 Propagation of all_dependent_configs and public_configs happens independently |
4720 of target type. all_dependent_configs are always propagated across all types | 4875 of target type. all_dependent_configs are always propagated across all types |
4721 of targets, and public_configs are always propagated across public deps of | 4876 of targets, and public_configs are always propagated across public deps of |
4722 all types of targets. | 4877 all types of targets. |
4723 | 4878 |
4724 Data dependencies are propagated differently. See "gn help data_deps" and | 4879 Data dependencies are propagated differently. See "gn help data_deps" and |
4725 "gn help runtime_deps". | 4880 "gn help runtime_deps". |
4726 | 4881 |
4727 See also "public_deps". | 4882 See also "public_deps". |
4728 | 4883 |
| 4884 |
4729 ``` | 4885 ``` |
4730 ## **include_dirs**: Additional include directories. | 4886 ## **include_dirs**: Additional include directories. |
4731 | 4887 |
4732 ``` | 4888 ``` |
4733 A list of source directories. | 4889 A list of source directories. |
4734 | 4890 |
4735 The directories in this list will be added to the include path for the files | 4891 The directories in this list will be added to the include path for the files |
4736 in the affected target. | 4892 in the affected target. |
4737 | 4893 |
4738 ``` | 4894 ``` |
(...skipping 15 matching lines...) Expand all Loading... |
4754 "deps" list. If a dependency is public, they will be applied | 4910 "deps" list. If a dependency is public, they will be applied |
4755 recursively. | 4911 recursively. |
4756 | 4912 |
4757 ``` | 4913 ``` |
4758 | 4914 |
4759 ### **Example** | 4915 ### **Example** |
4760 | 4916 |
4761 ``` | 4917 ``` |
4762 include_dirs = [ "src/include", "//third_party/foo" ] | 4918 include_dirs = [ "src/include", "//third_party/foo" ] |
4763 | 4919 |
| 4920 |
4764 ``` | 4921 ``` |
4765 ## **inputs**: Additional compile-time dependencies. | 4922 ## **inputs**: Additional compile-time dependencies. |
4766 | 4923 |
4767 ``` | 4924 ``` |
4768 Inputs are compile-time dependencies of the current target. This means that | 4925 Inputs are compile-time dependencies of the current target. This means that |
4769 all inputs must be available before compiling any of the sources or executing | 4926 all inputs must be available before compiling any of the sources or executing |
4770 any actions. | 4927 any actions. |
4771 | 4928 |
4772 Inputs are typically only used for action and action_foreach targets. | 4929 Inputs are typically only used for action and action_foreach targets. |
4773 | 4930 |
(...skipping 55 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4829 ``` | 4986 ``` |
4830 | 4987 |
4831 ### **Example** | 4988 ### **Example** |
4832 | 4989 |
4833 ``` | 4990 ``` |
4834 action("myscript") { | 4991 action("myscript") { |
4835 script = "domything.py" | 4992 script = "domything.py" |
4836 inputs = [ "input.data" ] | 4993 inputs = [ "input.data" ] |
4837 } | 4994 } |
4838 | 4995 |
| 4996 |
4839 ``` | 4997 ``` |
4840 ## **ldflags**: Flags passed to the linker. | 4998 ## **ldflags**: Flags passed to the linker. |
4841 | 4999 |
4842 ``` | 5000 ``` |
4843 A list of strings. | 5001 A list of strings. |
4844 | 5002 |
4845 These flags are passed on the command-line to the linker and generally | 5003 These flags are passed on the command-line to the linker and generally |
4846 specify various linking options. Most targets will not need these and will | 5004 specify various linking options. Most targets will not need these and will |
4847 use "libs" and "lib_dirs" instead. | 5005 use "libs" and "lib_dirs" instead. |
4848 | 5006 |
(...skipping 61 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4910 dependencies (as described above) are applied last assuming they | 5068 dependencies (as described above) are applied last assuming they |
4911 are not already in the list. | 5069 are not already in the list. |
4912 | 5070 |
4913 ``` | 5071 ``` |
4914 | 5072 |
4915 ### **Example** | 5073 ### **Example** |
4916 | 5074 |
4917 ``` | 5075 ``` |
4918 lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ] | 5076 lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ] |
4919 | 5077 |
| 5078 |
4920 ``` | 5079 ``` |
4921 ## **libs**: Additional libraries to link. | 5080 ## **libs**: Additional libraries to link. |
4922 | 5081 |
4923 ``` | 5082 ``` |
4924 A list of library names or library paths. | 5083 A list of library names or library paths. |
4925 | 5084 |
4926 These libraries will be linked into the final binary (executable or shared | 5085 These libraries will be linked into the final binary (executable or shared |
4927 library) containing the current target. | 5086 library) containing the current target. |
4928 | 5087 |
4929 libs and lib_dirs work differently than other flags in two respects. | 5088 libs and lib_dirs work differently than other flags in two respects. |
(...skipping 57 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4987 | 5146 |
4988 ### **Examples** | 5147 ### **Examples** |
4989 | 5148 |
4990 ``` | 5149 ``` |
4991 On Windows: | 5150 On Windows: |
4992 libs = [ "ctl3d.lib" ] | 5151 libs = [ "ctl3d.lib" ] |
4993 | 5152 |
4994 On Linux: | 5153 On Linux: |
4995 libs = [ "ld" ] | 5154 libs = [ "ld" ] |
4996 | 5155 |
| 5156 |
4997 ``` | 5157 ``` |
4998 ## **output_dir**: [directory] Directory to put output file in. | 5158 ## **output_dir**: [directory] Directory to put output file in. |
4999 | 5159 |
5000 ``` | 5160 ``` |
5001 For library and executable targets, overrides the directory for the final | 5161 For library and executable targets, overrides the directory for the final |
5002 output. This must be in the root_build_dir or a child thereof. | 5162 output. This must be in the root_build_dir or a child thereof. |
5003 | 5163 |
5004 This should generally be in the root_out_dir or a subdirectory thereof (the | 5164 This should generally be in the root_out_dir or a subdirectory thereof (the |
5005 root_out_dir will be the same as the root_build_dir for the default | 5165 root_out_dir will be the same as the root_build_dir for the default |
5006 toolchain, and will be a subdirectory for other toolchains). Not putting the | 5166 toolchain, and will be a subdirectory for other toolchains). Not putting the |
5007 output in a subdirectory of root_out_dir can result in collisions between | 5167 output in a subdirectory of root_out_dir can result in collisions between |
5008 different toolchains, so you will need to take steps to ensure that your | 5168 different toolchains, so you will need to take steps to ensure that your |
5009 target is only present in one toolchain. | 5169 target is only present in one toolchain. |
5010 | 5170 |
5011 Normally the toolchain specifies the output directory for libraries and | 5171 Normally the toolchain specifies the output directory for libraries and |
5012 executables (see "gn help tool"). You will have to consult that for the | 5172 executables (see "gn help tool"). You will have to consult that for the |
5013 default location. The default location will be used if output_dir is | 5173 default location. The default location will be used if output_dir is |
5014 undefined or empty. | 5174 undefined or empty. |
5015 | 5175 |
5016 ``` | 5176 ``` |
5017 | 5177 |
5018 ### **Example** | 5178 ### **Example** |
5019 | 5179 |
5020 ``` | 5180 ``` |
5021 shared_library("doom_melon") { | 5181 shared_library("doom_melon") { |
5022 output_dir = "$root_out_dir/plugin_libs" | 5182 output_dir = "$root_out_dir/plugin_libs" |
5023 ... | 5183 ... |
5024 } | 5184 } |
5025 | 5185 |
| 5186 |
5026 ``` | 5187 ``` |
5027 ## **output_extension**: Value to use for the output's file extension. | 5188 ## **output_extension**: Value to use for the output's file extension. |
5028 | 5189 |
5029 ``` | 5190 ``` |
5030 Normally the file extension for a target is based on the target type and the | 5191 Normally the file extension for a target is based on the target type and the |
5031 operating system, but in rare cases you will need to override the name (for | 5192 operating system, but in rare cases you will need to override the name (for |
5032 example to use "libfreetype.so.6" instead of libfreetype.so on Linux). | 5193 example to use "libfreetype.so.6" instead of libfreetype.so on Linux). |
5033 | 5194 |
5034 This value should not include a leading dot. If undefined, the default | 5195 This value should not include a leading dot. If undefined, the default |
5035 specified on the tool will be used. If set to the empty string, no output | 5196 specified on the tool will be used. If set to the empty string, no output |
(...skipping 18 matching lines...) Expand all Loading... |
5054 | 5215 |
5055 # On Windows, generate a "mysettings.cpl" control panel applet. Control panel | 5216 # On Windows, generate a "mysettings.cpl" control panel applet. Control panel |
5056 # applets are actually special shared libraries. | 5217 # applets are actually special shared libraries. |
5057 if (is_win) { | 5218 if (is_win) { |
5058 shared_library("mysettings") { | 5219 shared_library("mysettings") { |
5059 output_extension = "cpl" | 5220 output_extension = "cpl" |
5060 ... | 5221 ... |
5061 } | 5222 } |
5062 } | 5223 } |
5063 | 5224 |
| 5225 |
5064 ``` | 5226 ``` |
5065 ## **output_name**: Define a name for the output file other than the default. | 5227 ## **output_name**: Define a name for the output file other than the default. |
5066 | 5228 |
5067 ``` | 5229 ``` |
5068 Normally the output name of a target will be based on the target name, so the | 5230 Normally the output name of a target will be based on the target name, so the |
5069 target "//foo/bar:bar_unittests" will generate an output file such as | 5231 target "//foo/bar:bar_unittests" will generate an output file such as |
5070 "bar_unittests.exe" (using Windows as an example). | 5232 "bar_unittests.exe" (using Windows as an example). |
5071 | 5233 |
5072 Sometimes you will want an alternate name to avoid collisions or if the | 5234 Sometimes you will want an alternate name to avoid collisions or if the |
5073 internal name isn't appropriate for public distribution. | 5235 internal name isn't appropriate for public distribution. |
5074 | 5236 |
5075 The output name should have no extension or prefixes, these will be added | 5237 The output name should have no extension or prefixes, these will be added |
5076 using the default system rules. For example, on Linux an output name of "foo" | 5238 using the default system rules. For example, on Linux an output name of "foo" |
5077 will produce a shared library "libfoo.so". There is no way to override the | 5239 will produce a shared library "libfoo.so". There is no way to override the |
5078 output prefix of a linker tool on a per- target basis. If you need more | 5240 output prefix of a linker tool on a per- target basis. If you need more |
5079 flexibility, create a copy target to produce the file you want. | 5241 flexibility, create a copy target to produce the file you want. |
5080 | 5242 |
5081 This variable is valid for all binary output target types. | 5243 This variable is valid for all binary output target types. |
5082 | 5244 |
5083 ``` | 5245 ``` |
5084 | 5246 |
5085 ### **Example** | 5247 ### **Example** |
5086 | 5248 |
5087 ``` | 5249 ``` |
5088 static_library("doom_melon") { | 5250 static_library("doom_melon") { |
5089 output_name = "fluffy_bunny" | 5251 output_name = "fluffy_bunny" |
5090 } | 5252 } |
5091 | 5253 |
| 5254 |
5092 ``` | 5255 ``` |
5093 ## **output_prefix_override**: Don't use prefix for output name. | 5256 ## **output_prefix_override**: Don't use prefix for output name. |
5094 | 5257 |
5095 ``` | 5258 ``` |
5096 A boolean that overrides the output prefix for a target. Defaults to false. | 5259 A boolean that overrides the output prefix for a target. Defaults to false. |
5097 | 5260 |
5098 Some systems use prefixes for the names of the final target output file. The | 5261 Some systems use prefixes for the names of the final target output file. The |
5099 normal example is "libfoo.so" on Linux for a target named "foo". | 5262 normal example is "libfoo.so" on Linux for a target named "foo". |
5100 | 5263 |
5101 The output prefix for a given target type is specified on the linker tool | 5264 The output prefix for a given target type is specified on the linker tool |
5102 (see "gn help tool"). Sometimes this prefix is undesired. | 5265 (see "gn help tool"). Sometimes this prefix is undesired. |
5103 | 5266 |
5104 See also "gn help output_extension". | 5267 See also "gn help output_extension". |
5105 | 5268 |
5106 ``` | 5269 ``` |
5107 | 5270 |
5108 ### **Example** | 5271 ### **Example** |
5109 | 5272 |
5110 ``` | 5273 ``` |
5111 shared_library("doom_melon") { | 5274 shared_library("doom_melon") { |
5112 # Normally this will produce "libdoom_melon.so" on Linux. Setting this flag | 5275 # Normally this will produce "libdoom_melon.so" on Linux. Setting this flag |
5113 # will produce "doom_melon.so". | 5276 # will produce "doom_melon.so". |
5114 output_prefix_override = true | 5277 output_prefix_override = true |
5115 ... | 5278 ... |
5116 } | 5279 } |
5117 | 5280 |
| 5281 |
5118 ``` | 5282 ``` |
5119 ## **outputs**: Output files for actions and copy targets. | 5283 ## **outputs**: Output files for actions and copy targets. |
5120 | 5284 |
5121 ``` | 5285 ``` |
5122 Outputs is valid for "copy", "action", and "action_foreach" target types and | 5286 Outputs is valid for "copy", "action", and "action_foreach" target types and |
5123 indicates the resulting files. Outputs must always refer to files in the | 5287 indicates the resulting files. Outputs must always refer to files in the |
5124 build directory. | 5288 build directory. |
5125 | 5289 |
5126 copy | 5290 copy |
5127 Copy targets should have exactly one entry in the outputs list. If there is | 5291 Copy targets should have exactly one entry in the outputs list. If there is |
5128 exactly one source, this can be a literal file name or a source expansion. | 5292 exactly one source, this can be a literal file name or a source expansion. |
5129 If there is more than one source, this must contain a source expansion to | 5293 If there is more than one source, this must contain a source expansion to |
5130 map a single input name to a single output name. See "gn help copy". | 5294 map a single input name to a single output name. See "gn help copy". |
5131 | 5295 |
5132 action_foreach | 5296 action_foreach |
5133 Action_foreach targets must always use source expansions to map input files | 5297 Action_foreach targets must always use source expansions to map input files |
5134 to output files. There can be more than one output, which means that each | 5298 to output files. There can be more than one output, which means that each |
5135 invocation of the script will produce a set of files (presumably based on | 5299 invocation of the script will produce a set of files (presumably based on |
5136 the name of the input file). See "gn help action_foreach". | 5300 the name of the input file). See "gn help action_foreach". |
5137 | 5301 |
5138 action | 5302 action |
5139 Action targets (excluding action_foreach) must list literal output file(s) | 5303 Action targets (excluding action_foreach) must list literal output file(s) |
5140 with no source expansions. See "gn help action". | 5304 with no source expansions. See "gn help action". |
5141 | 5305 |
| 5306 |
5142 ``` | 5307 ``` |
5143 ## **precompiled_header**: [string] Header file to precompile. | 5308 ## **precompiled_header**: [string] Header file to precompile. |
5144 | 5309 |
5145 ``` | 5310 ``` |
5146 Precompiled headers will be used when a target specifies this value, or a | 5311 Precompiled headers will be used when a target specifies this value, or a |
5147 config applying to this target specifies this value. In addition, the tool | 5312 config applying to this target specifies this value. In addition, the tool |
5148 corresponding to the source files must also specify precompiled headers (see | 5313 corresponding to the source files must also specify precompiled headers (see |
5149 "gn help tool"). The tool will also specify what type of precompiled headers | 5314 "gn help tool"). The tool will also specify what type of precompiled headers |
5150 to use. | 5315 to use. |
5151 | 5316 |
(...skipping 48 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5200 | 5365 |
5201 | 5366 |
5202 ``` | 5367 ``` |
5203 ## **precompiled_source**: [file name] Source file to precompile. | 5368 ## **precompiled_source**: [file name] Source file to precompile. |
5204 | 5369 |
5205 ``` | 5370 ``` |
5206 The source file that goes along with the precompiled_header when using | 5371 The source file that goes along with the precompiled_header when using |
5207 "msvc"-style precompiled headers. It will be implicitly added to the sources | 5372 "msvc"-style precompiled headers. It will be implicitly added to the sources |
5208 of the target. See "gn help precompiled_header". | 5373 of the target. See "gn help precompiled_header". |
5209 | 5374 |
| 5375 |
5210 ``` | 5376 ``` |
5211 ## **product_type**: Product type for Xcode projects. | 5377 ## **product_type**: Product type for Xcode projects. |
5212 | 5378 |
5213 ``` | 5379 ``` |
5214 Correspond to the type of the product of a create_bundle target. Only | 5380 Correspond to the type of the product of a create_bundle target. Only |
5215 meaningful to Xcode (used as part of the Xcode project generation). | 5381 meaningful to Xcode (used as part of the Xcode project generation). |
5216 | 5382 |
5217 When generating Xcode project files, only create_bundle target with a | 5383 When generating Xcode project files, only create_bundle target with a |
5218 non-empty product_type will have a corresponding target in Xcode project. | 5384 non-empty product_type will have a corresponding target in Xcode project. |
5219 | 5385 |
| 5386 |
5220 ``` | 5387 ``` |
5221 ## **public**: Declare public header files for a target. | 5388 ## **public**: Declare public header files for a target. |
5222 | 5389 |
5223 ``` | 5390 ``` |
5224 A list of files that other targets can include. These permissions are checked | 5391 A list of files that other targets can include. These permissions are checked |
5225 via the "check" command (see "gn help check"). | 5392 via the "check" command (see "gn help check"). |
5226 | 5393 |
5227 If no public files are declared, other targets (assuming they have visibility | 5394 If no public files are declared, other targets (assuming they have visibility |
5228 to depend on this target can include any file in the sources list. If this | 5395 to depend on this target can include any file in the sources list. If this |
5229 variable is defined on a target, dependent targets may only include files on | 5396 variable is defined on a target, dependent targets may only include files on |
(...skipping 17 matching lines...) Expand all Loading... |
5247 | 5414 |
5248 ### **Examples** | 5415 ### **Examples** |
5249 | 5416 |
5250 ``` | 5417 ``` |
5251 These exact files are public: | 5418 These exact files are public: |
5252 public = [ "foo.h", "bar.h" ] | 5419 public = [ "foo.h", "bar.h" ] |
5253 | 5420 |
5254 No files are public (no targets may include headers from this one): | 5421 No files are public (no targets may include headers from this one): |
5255 public = [] | 5422 public = [] |
5256 | 5423 |
| 5424 |
5257 ``` | 5425 ``` |
5258 ## **public_configs**: Configs to be applied on dependents. | 5426 ## **public_configs**: Configs to be applied on dependents. |
5259 | 5427 |
5260 ``` | 5428 ``` |
5261 A list of config labels. | 5429 A list of config labels. |
5262 | 5430 |
5263 Targets directly depending on this one will have the configs listed in this | 5431 Targets directly depending on this one will have the configs listed in this |
5264 variable added to them. These configs will also apply to the current target. | 5432 variable added to them. These configs will also apply to the current target. |
5265 | 5433 |
5266 This addition happens in a second phase once a target and all of its | 5434 This addition happens in a second phase once a target and all of its |
(...skipping 70 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5337 # "super_secret_implementation_details". | 5505 # "super_secret_implementation_details". |
5338 executable("a") { | 5506 executable("a") { |
5339 deps = [ ":b" ] | 5507 deps = [ ":b" ] |
5340 } | 5508 } |
5341 | 5509 |
5342 shared_library("b") { | 5510 shared_library("b") { |
5343 deps = [ ":super_secret_implementation_details" ] | 5511 deps = [ ":super_secret_implementation_details" ] |
5344 public_deps = [ ":c" ] | 5512 public_deps = [ ":c" ] |
5345 } | 5513 } |
5346 | 5514 |
| 5515 |
5347 ``` | 5516 ``` |
5348 ## **response_file_contents**: Contents of a response file for actions. | 5517 ## **response_file_contents**: Contents of a response file for actions. |
5349 | 5518 |
5350 ``` | 5519 ``` |
5351 Sometimes the arguments passed to a script can be too long for the system's | 5520 Sometimes the arguments passed to a script can be too long for the system's |
5352 command-line capabilities. This is especially the case on Windows where the | 5521 command-line capabilities. This is especially the case on Windows where the |
5353 maximum command-line length is less than 8K. A response file allows you to | 5522 maximum command-line length is less than 8K. A response file allows you to |
5354 pass an unlimited amount of data to a script in a temporary file for an | 5523 pass an unlimited amount of data to a script in a temporary file for an |
5355 action or action_foreach target. | 5524 action or action_foreach target. |
5356 | 5525 |
(...skipping 20 matching lines...) Expand all Loading... |
5377 # make the paths relative to the script working directory. | 5546 # make the paths relative to the script working directory. |
5378 response_file_contents = rebase_path(inputs, root_build_dir) | 5547 response_file_contents = rebase_path(inputs, root_build_dir) |
5379 | 5548 |
5380 # The script expects the name of the response file in --file-list. | 5549 # The script expects the name of the response file in --file-list. |
5381 args = [ | 5550 args = [ |
5382 "--enable-foo", | 5551 "--enable-foo", |
5383 "--file-list={{response_file_name}}", | 5552 "--file-list={{response_file_name}}", |
5384 ] | 5553 ] |
5385 } | 5554 } |
5386 | 5555 |
| 5556 |
5387 ``` | 5557 ``` |
5388 ## **script**: Script file for actions. | 5558 ## **script**: Script file for actions. |
5389 | 5559 |
5390 ``` | 5560 ``` |
5391 An absolute or buildfile-relative file name of a Python script to run for a | 5561 An absolute or buildfile-relative file name of a Python script to run for a |
5392 action and action_foreach targets (see "gn help action" and "gn help | 5562 action and action_foreach targets (see "gn help action" and "gn help |
5393 action_foreach"). | 5563 action_foreach"). |
5394 | 5564 |
| 5565 |
5395 ``` | 5566 ``` |
5396 ## **sources**: Source files for a target | 5567 ## **sources**: Source files for a target |
5397 | 5568 |
5398 ``` | 5569 ``` |
5399 A list of files. Non-absolute paths will be resolved relative to the current | 5570 A list of files. Non-absolute paths will be resolved relative to the current |
5400 build file. | 5571 build file. |
5401 | 5572 |
5402 ``` | 5573 ``` |
5403 | 5574 |
5404 ### **Sources for binary targets** | 5575 ### **Sources for binary targets** |
(...skipping 21 matching lines...) Expand all Loading... |
5426 The sources are the set of files that the script will be executed over. The | 5597 The sources are the set of files that the script will be executed over. The |
5427 script will run once per file. | 5598 script will run once per file. |
5428 | 5599 |
5429 action | 5600 action |
5430 The sources will be treated the same as inputs. See "gn help inputs" for | 5601 The sources will be treated the same as inputs. See "gn help inputs" for |
5431 more information and usage advice. | 5602 more information and usage advice. |
5432 | 5603 |
5433 copy | 5604 copy |
5434 The source are the source files to copy. | 5605 The source are the source files to copy. |
5435 | 5606 |
| 5607 |
5436 ``` | 5608 ``` |
5437 ## **testonly**: Declares a target must only be used for testing. | 5609 ## **testonly**: Declares a target must only be used for testing. |
5438 | 5610 |
5439 ``` | 5611 ``` |
5440 Boolean. Defaults to false. | 5612 Boolean. Defaults to false. |
5441 | 5613 |
5442 When a target is marked "testonly = true", it must only be depended on by | 5614 When a target is marked "testonly = true", it must only be depended on by |
5443 other test-only targets. Otherwise, GN will issue an error that the | 5615 other test-only targets. Otherwise, GN will issue an error that the |
5444 depenedency is not allowed. | 5616 depenedency is not allowed. |
5445 | 5617 |
5446 This feature is intended to prevent accidentally shipping test code in a | 5618 This feature is intended to prevent accidentally shipping test code in a |
5447 final product. | 5619 final product. |
5448 | 5620 |
5449 ``` | 5621 ``` |
5450 | 5622 |
5451 ### **Example** | 5623 ### **Example** |
5452 | 5624 |
5453 ``` | 5625 ``` |
5454 source_set("test_support") { | 5626 source_set("test_support") { |
5455 testonly = true | 5627 testonly = true |
5456 ... | 5628 ... |
5457 } | 5629 } |
5458 | 5630 |
| 5631 |
5459 ``` | 5632 ``` |
5460 ## **visibility**: A list of labels that can depend on a target. | 5633 ## **visibility**: A list of labels that can depend on a target. |
5461 | 5634 |
5462 ``` | 5635 ``` |
5463 A list of labels and label patterns that define which targets can depend on | 5636 A list of labels and label patterns that define which targets can depend on |
5464 the current one. These permissions are checked via the "check" command (see | 5637 the current one. These permissions are checked via the "check" command (see |
5465 "gn help check"). | 5638 "gn help check"). |
5466 | 5639 |
5467 If visibility is not defined, it defaults to public ("*"). | 5640 If visibility is not defined, it defaults to public ("*"). |
5468 | 5641 |
(...skipping 38 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5507 Any target in "//bar/" or any subdirectory thereof: | 5680 Any target in "//bar/" or any subdirectory thereof: |
5508 visibility = [ "//bar/*" ] | 5681 visibility = [ "//bar/*" ] |
5509 | 5682 |
5510 Just these specific targets: | 5683 Just these specific targets: |
5511 visibility = [ ":mything", "//foo:something_else" ] | 5684 visibility = [ ":mything", "//foo:something_else" ] |
5512 | 5685 |
5513 Any target in the current directory and any subdirectory thereof, plus | 5686 Any target in the current directory and any subdirectory thereof, plus |
5514 any targets in "//bar/" and any subdirectory thereof. | 5687 any targets in "//bar/" and any subdirectory thereof. |
5515 visibility = [ "./*", "//bar/*" ] | 5688 visibility = [ "./*", "//bar/*" ] |
5516 | 5689 |
| 5690 |
5517 ``` | 5691 ``` |
5518 ## **write_runtime_deps**: Writes the target's runtime_deps to the given path. | 5692 ## **write_runtime_deps**: Writes the target's runtime_deps to the given path. |
5519 | 5693 |
5520 ``` | 5694 ``` |
5521 Does not synchronously write the file, but rather schedules it to be written | 5695 Does not synchronously write the file, but rather schedules it to be written |
5522 at the end of generation. | 5696 at the end of generation. |
5523 | 5697 |
5524 If the file exists and the contents are identical to that being written, the | 5698 If the file exists and the contents are identical to that being written, the |
5525 file will not be updated. This will prevent unnecessary rebuilds of targets | 5699 file will not be updated. This will prevent unnecessary rebuilds of targets |
5526 that depend on this file. | 5700 that depend on this file. |
5527 | 5701 |
5528 Path must be within the output directory. | 5702 Path must be within the output directory. |
5529 | 5703 |
5530 See "gn help runtime_deps" for how the runtime dependencies are computed. | 5704 See "gn help runtime_deps" for how the runtime dependencies are computed. |
5531 | 5705 |
5532 The format of this file will list one file per line with no escaping. The | 5706 The format of this file will list one file per line with no escaping. The |
5533 files will be relative to the root_build_dir. The first line of the file will | 5707 files will be relative to the root_build_dir. The first line of the file will |
5534 be the main output file of the target itself. The file contents will be the | 5708 be the main output file of the target itself. The file contents will be the |
5535 same as requesting the runtime deps be written on the command line (see "gn | 5709 same as requesting the runtime deps be written on the command line (see "gn |
5536 help --runtime-deps-list-file"). | 5710 help --runtime-deps-list-file"). |
5537 | 5711 |
| 5712 |
5538 ``` | 5713 ``` |
5539 ## **Build Arguments Overview** | 5714 ## **Build Arguments Overview** |
5540 | 5715 |
5541 ``` | 5716 ``` |
5542 Build arguments are variables passed in from outside of the build that build | 5717 Build arguments are variables passed in from outside of the build that build |
5543 files can query to determine how the build works. | 5718 files can query to determine how the build works. |
5544 | 5719 |
5545 ``` | 5720 ``` |
5546 | 5721 |
5547 ### **How build arguments are set** | 5722 ### **How build arguments are set** |
(...skipping 132 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5680 | 5855 |
5681 check_targets = [ | 5856 check_targets = [ |
5682 "//doom_melon/*", # Check everything in this subtree. | 5857 "//doom_melon/*", # Check everything in this subtree. |
5683 "//tools:mind_controlling_ant", # Check this specific target. | 5858 "//tools:mind_controlling_ant", # Check this specific target. |
5684 ] | 5859 ] |
5685 | 5860 |
5686 root = "//:root" | 5861 root = "//:root" |
5687 | 5862 |
5688 secondary_source = "//build/config/temporary_buildfiles/" | 5863 secondary_source = "//build/config/temporary_buildfiles/" |
5689 | 5864 |
| 5865 |
| 5866 ``` |
| 5867 ## **Build graph and execution overview** |
| 5868 |
| 5869 ### **Overall build flow** |
| 5870 |
| 5871 ``` |
| 5872 1. Look for ".gn" file (see "gn help dotfile") in the current directory and |
| 5873 walk up the directory tree until one is found. Set this directory to be |
| 5874 the "source root" and interpret this file to find the name of the build |
| 5875 config file. |
| 5876 |
| 5877 2. Execute the build config file identified by .gn to set up the global |
| 5878 variables and default toolchain name. Any arguments, variables, defaults, |
| 5879 etc. set up in this file will be visible to all files in the build. |
| 5880 |
| 5881 3. Load the //BUILD.gn (in the source root directory). |
| 5882 |
| 5883 4. Recursively evaluate rules and load BUILD.gn in other directories as |
| 5884 necessary to resolve dependencies. If a BUILD file isn't found in the |
| 5885 specified location, GN will look in the corresponding location inside |
| 5886 the secondary_source defined in the dotfile (see "gn help dotfile"). |
| 5887 |
| 5888 5. When a target's dependencies are resolved, write out the `.ninja` |
| 5889 file to disk. |
| 5890 |
| 5891 6. When all targets are resolved, write out the root build.ninja file. |
| 5892 |
| 5893 ``` |
| 5894 |
| 5895 ### **Executing target definitions and templates** |
| 5896 |
| 5897 ``` |
| 5898 Build files are loaded in parallel. This means it is impossible to |
| 5899 interrogate a target from GN code for any information not derivable from its |
| 5900 label (see "gn help label"). The exception is the get_target_outputs() |
| 5901 function which requires the target being interrogated to have been defined |
| 5902 previously in the same file. |
| 5903 |
| 5904 Targets are declared by their type and given a name: |
| 5905 |
| 5906 static_library("my_static_library") { |
| 5907 ... target parameter definitions ... |
| 5908 } |
| 5909 |
| 5910 There is also a generic "target" function for programatically defined types |
| 5911 (see "gn help target"). You can define new types using templates (see "gn |
| 5912 help template"). A template defines some custom code that expands to one or |
| 5913 more other targets. |
| 5914 |
| 5915 Before executing the code inside the target's { }, the target defaults are |
| 5916 applied (see "gn help set_defaults"). It will inject implicit variable |
| 5917 definitions that can be overridden by the target code as necessary. Typically |
| 5918 this mechanism is used to inject a default set of configs that define the |
| 5919 global compiler and linker flags. |
| 5920 |
| 5921 ``` |
| 5922 |
| 5923 ### **Which targets are built** |
| 5924 |
| 5925 ``` |
| 5926 All targets encountered in the default toolchain (see "gn help toolchain") |
| 5927 will have build rules generated for them, even if no other targets reference |
| 5928 them. Their dependencies must resolve and they will be added to the implicit |
| 5929 "all" rule (see "gn help ninja_rules"). |
| 5930 |
| 5931 Targets in non-default toolchains will only be generated when they are |
| 5932 required (directly or transitively) to build a target in the default |
| 5933 toolchain. |
| 5934 |
| 5935 See also "gn help ninja_rules". |
| 5936 |
| 5937 ``` |
| 5938 |
| 5939 ### **Dependencies** |
| 5940 |
| 5941 ``` |
| 5942 The only difference between "public_deps" and "deps" except for pushing |
| 5943 configs around the build tree and allowing includes for the purposes of "gn |
| 5944 check". |
| 5945 |
| 5946 A target's "data_deps" are guaranteed to be built whenever the target is |
| 5947 built, but the ordering is not defined. The meaning of this is dependencies |
| 5948 required at runtime. Currently data deps will be complete before the target |
| 5949 is linked, but this is not semantically guaranteed and this is undesirable |
| 5950 from a build performance perspective. Since we hope to change this in the |
| 5951 future, do not rely on this behavior. |
| 5952 |
| 5953 |
5690 ``` | 5954 ``` |
5691 ## **Language and grammar for GN build files** | 5955 ## **Language and grammar for GN build files** |
5692 | 5956 |
5693 ### **Tokens** | 5957 ### **Tokens** |
5694 | 5958 |
5695 ``` | 5959 ``` |
5696 GN build files are read as sequences of tokens. While splitting the file | 5960 GN build files are read as sequences of tokens. While splitting the file |
5697 into tokens, the next token is the longest sequence of characters that form a | 5961 into tokens, the next token is the longest sequence of characters that form a |
5698 valid token. | 5962 valid token. |
5699 | 5963 |
(...skipping 214 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5914 } | 6178 } |
5915 | 6179 |
5916 Inside such a scope definition can be any GN code including conditionals and | 6180 Inside such a scope definition can be any GN code including conditionals and |
5917 function calls. After the close of the scope, it will contain all variables | 6181 function calls. After the close of the scope, it will contain all variables |
5918 explicitly set by the code contained inside it. After this, the values can be | 6182 explicitly set by the code contained inside it. After this, the values can be |
5919 read, modified, or added to: | 6183 read, modified, or added to: |
5920 | 6184 |
5921 myvalues.foo += 2 | 6185 myvalues.foo += 2 |
5922 empty_scope.new_thing = [ 1, 2, 3 ] | 6186 empty_scope.new_thing = [ 1, 2, 3 ] |
5923 | 6187 |
| 6188 |
5924 ``` | 6189 ``` |
5925 ## **input_conversion**: Specifies how to transform input to a variable. | 6190 ## **input_conversion**: Specifies how to transform input to a variable. |
5926 | 6191 |
5927 ``` | 6192 ``` |
5928 input_conversion is an argument to read_file and exec_script that specifies | 6193 input_conversion is an argument to read_file and exec_script that specifies |
5929 how the result of the read operation should be converted into a variable. | 6194 how the result of the read operation should be converted into a variable. |
5930 | 6195 |
5931 "" (the default) | 6196 "" (the default) |
5932 Discard the result and return None. | 6197 Discard the result and return None. |
5933 | 6198 |
(...skipping 33 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5967 "trim ..." | 6232 "trim ..." |
5968 Prefixing any of the other transformations with the word "trim" will | 6233 Prefixing any of the other transformations with the word "trim" will |
5969 result in whitespace being trimmed from the beginning and end of the | 6234 result in whitespace being trimmed from the beginning and end of the |
5970 result before processing. | 6235 result before processing. |
5971 | 6236 |
5972 Examples: "trim string" or "trim list lines" | 6237 Examples: "trim string" or "trim list lines" |
5973 | 6238 |
5974 Note that "trim value" is useless because the value parser skips | 6239 Note that "trim value" is useless because the value parser skips |
5975 whitespace anyway. | 6240 whitespace anyway. |
5976 | 6241 |
| 6242 |
5977 ``` | 6243 ``` |
5978 ## **Label patterns** | 6244 ## **Label patterns** |
5979 | 6245 |
5980 ``` | 6246 ``` |
5981 A label pattern is a way of expressing one or more labels in a portion of the | 6247 A label pattern is a way of expressing one or more labels in a portion of the |
5982 source tree. They are not general regular expressions. | 6248 source tree. They are not general regular expressions. |
5983 | 6249 |
5984 They can take the following forms only: | 6250 They can take the following forms only: |
5985 | 6251 |
5986 - Explicit (no wildcard): | 6252 - Explicit (no wildcard): |
(...skipping 16 matching lines...) Expand all Loading... |
6003 "//foo:bar(//build/toochain:mac)" | 6269 "//foo:bar(//build/toochain:mac)" |
6004 An explicit target in an explicit toolchain. | 6270 An explicit target in an explicit toolchain. |
6005 | 6271 |
6006 ":*(//build/toolchain/linux:32bit)" | 6272 ":*(//build/toolchain/linux:32bit)" |
6007 All targets in the current build file using the 32-bit Linux toolchain. | 6273 All targets in the current build file using the 32-bit Linux toolchain. |
6008 | 6274 |
6009 "//foo/*(//build/toolchain:win)" | 6275 "//foo/*(//build/toolchain:win)" |
6010 All targets in //foo and any subdirectory using the Windows | 6276 All targets in //foo and any subdirectory using the Windows |
6011 toolchain. | 6277 toolchain. |
6012 | 6278 |
| 6279 |
| 6280 ``` |
| 6281 ## **About labels** |
| 6282 |
| 6283 ``` |
| 6284 Everything that can participate in the dependency graph (targets, configs, |
| 6285 and toolchains) are identified by labels. A common label looks like: |
| 6286 |
| 6287 //base/test:test_support |
| 6288 |
| 6289 This consists of a source-root-absolute path, a colon, and a name. This means |
| 6290 to look for the thing named "test_support" in "base/test/BUILD.gn". |
| 6291 |
| 6292 You can also specify system absolute paths if necessary. Typically such |
| 6293 paths would be specified via a build arg so the developer can specify where |
| 6294 the component is on their system. |
| 6295 |
| 6296 /usr/local/foo:bar (Posix) |
| 6297 /C:/Program Files/MyLibs:bar (Windows) |
| 6298 |
| 6299 ``` |
| 6300 |
| 6301 ### **Toolchains** |
| 6302 |
| 6303 ``` |
| 6304 A canonical label includes the label of the toolchain being used. Normally, |
| 6305 the toolchain label is implicitly inherited from the current execution |
| 6306 context, but you can override this to specify cross-toolchain dependencies: |
| 6307 |
| 6308 //base/test:test_support(//build/toolchain/win:msvc) |
| 6309 |
| 6310 Here GN will look for the toolchain definition called "msvc" in the file |
| 6311 "//build/toolchain/win" to know how to compile this target. |
| 6312 |
| 6313 ``` |
| 6314 |
| 6315 ### **Relative labels** |
| 6316 |
| 6317 ``` |
| 6318 If you want to refer to something in the same buildfile, you can omit |
| 6319 the path name and just start with a colon. This format is recommended for |
| 6320 all same-file references. |
| 6321 |
| 6322 :base |
| 6323 |
| 6324 Labels can be specified as being relative to the current directory. |
| 6325 Stylistically, we prefer to use absolute paths for all non-file-local |
| 6326 references unless a build file needs to be run in different contexts (like a |
| 6327 project needs to be both standalone and pulled into other projects in |
| 6328 difference places in the directory hierarchy). |
| 6329 |
| 6330 source/plugin:myplugin |
| 6331 ../net:url_request |
| 6332 |
| 6333 ``` |
| 6334 |
| 6335 ### **Implicit names** |
| 6336 |
| 6337 ``` |
| 6338 If a name is unspecified, it will inherit the directory name. Stylistically, |
| 6339 we prefer to omit the colon and name when possible: |
| 6340 |
| 6341 //net -> //net:net |
| 6342 //tools/gn -> //tools/gn:gn |
| 6343 |
| 6344 |
| 6345 ``` |
| 6346 ## **Ninja build rules** |
| 6347 |
| 6348 ### **The "all" and "default" rules** |
| 6349 |
| 6350 ``` |
| 6351 All generated targets (see "gn help execution") will be added to an implicit |
| 6352 build rule called "all" so "ninja all" will always compile everything. The |
| 6353 default rule will be used by Ninja if no specific target is specified (just |
| 6354 typing "ninja"). If there is a target named "//:default" it will be the |
| 6355 default build rule, otherwise the implicit "all" rule will be used. |
| 6356 |
| 6357 ``` |
| 6358 |
| 6359 ### **Phony rules** |
| 6360 |
| 6361 ``` |
| 6362 GN generates Ninja "phony" rules for targets in the default toolchain. The |
| 6363 phony rules can collide with each other and with the names of generated files |
| 6364 so are generated with the following priority: |
| 6365 |
| 6366 1. Actual files generated by the build always take precedence. |
| 6367 |
| 6368 2. Targets in the toplevel //BUILD.gn file. |
| 6369 |
| 6370 3. Targets in toplevel directories matching the names of the directories. |
| 6371 So "ninja foo" can be used to compile "//foo:foo". This only applies to |
| 6372 the first level of directories since usually these are the most |
| 6373 important (so this won't apply to "//foo/bar:bar"). |
| 6374 |
| 6375 4. The short names of executables if there is only one executable with that |
| 6376 short name. Use "ninja doom_melon" to compile the |
| 6377 "//tools/fruit:doom_melon" executable. |
| 6378 |
| 6379 5. The short names of all targets if there is only one target with that |
| 6380 short name. |
| 6381 |
| 6382 6. Full label name with no leading slashes. So you can use |
| 6383 "ninja tools/fruit:doom_melon" to build "//tools/fruit:doom_melon". |
| 6384 |
| 6385 7. Labels with an implicit name part (when the short names match the |
| 6386 directory). So you can use "ninja foo/bar" to compile "//foo/bar:bar". |
| 6387 |
| 6388 These "phony" rules are provided only for running Ninja since this matches |
| 6389 people's historical expectations for building. For consistency with the rest |
| 6390 of the program, GN introspection commands accept explicit labels. |
| 6391 |
| 6392 To explicitly compile a target in a non-default toolchain, you must give |
| 6393 Ninja the exact name of the output file relative to the build directory. |
| 6394 |
| 6395 |
6013 ``` | 6396 ``` |
6014 ## **nogncheck**: Skip an include line from checking. | 6397 ## **nogncheck**: Skip an include line from checking. |
6015 | 6398 |
6016 ``` | 6399 ``` |
6017 GN's header checker helps validate that the includes match the build | 6400 GN's header checker helps validate that the includes match the build |
6018 dependency graph. Sometimes an include might be conditional or otherwise | 6401 dependency graph. Sometimes an include might be conditional or otherwise |
6019 problematic, but you want to specifically allow it. In this case, it can be | 6402 problematic, but you want to specifically allow it. In this case, it can be |
6020 whitelisted. | 6403 whitelisted. |
6021 | 6404 |
6022 Include lines containing the substring "nogncheck" will be excluded from | 6405 Include lines containing the substring "nogncheck" will be excluded from |
(...skipping 19 matching lines...) Expand all Loading... |
6042 | 6425 |
6043 ``` | 6426 ``` |
6044 | 6427 |
6045 ### **More information** | 6428 ### **More information** |
6046 | 6429 |
6047 ``` | 6430 ``` |
6048 The topic "gn help check" has general information on how checking works and | 6431 The topic "gn help check" has general information on how checking works and |
6049 advice on fixing problems. Targets can also opt-out of checking, see | 6432 advice on fixing problems. Targets can also opt-out of checking, see |
6050 "gn help check_includes". | 6433 "gn help check_includes". |
6051 | 6434 |
| 6435 |
6052 ``` | 6436 ``` |
6053 ## **Runtime dependencies** | 6437 ## **Runtime dependencies** |
6054 | 6438 |
6055 ``` | 6439 ``` |
6056 Runtime dependencies of a target are exposed via the "runtime_deps" category | 6440 Runtime dependencies of a target are exposed via the "runtime_deps" category |
6057 of "gn desc" (see "gn help desc") or they can be written at build generation | 6441 of "gn desc" (see "gn help desc") or they can be written at build generation |
6058 time via write_runtime_deps(), or --runtime-deps-list-file (see "gn help | 6442 time via write_runtime_deps(), or --runtime-deps-list-file (see "gn help |
6059 --runtime-deps-list-file"). | 6443 --runtime-deps-list-file"). |
6060 | 6444 |
6061 To a first approximation, the runtime dependencies of a target are the set of | 6445 To a first approximation, the runtime dependencies of a target are the set of |
(...skipping 61 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6123 | 6507 |
6124 ``` | 6508 ``` |
6125 | 6509 |
6126 ### **Multiple outputs** | 6510 ### **Multiple outputs** |
6127 | 6511 |
6128 ``` | 6512 ``` |
6129 Linker tools can specify which of their outputs should be considered when | 6513 Linker tools can specify which of their outputs should be considered when |
6130 computing the runtime deps by setting runtime_outputs. If this is unset on | 6514 computing the runtime deps by setting runtime_outputs. If this is unset on |
6131 the tool, the default will be the first output only. | 6515 the tool, the default will be the first output only. |
6132 | 6516 |
| 6517 |
6133 ``` | 6518 ``` |
6134 ## **How Source Expansion Works** | 6519 ## **How Source Expansion Works** |
6135 | 6520 |
6136 ``` | 6521 ``` |
6137 Source expansion is used for the action_foreach and copy target types to map | 6522 Source expansion is used for the action_foreach and copy target types to map |
6138 source file names to output file names or arguments. | 6523 source file names to output file names or arguments. |
6139 | 6524 |
6140 To perform source expansion in the outputs, GN maps every entry in the | 6525 To perform source expansion in the outputs, GN maps every entry in the |
6141 sources to every entry in the outputs list, producing the cross product of | 6526 sources to every entry in the outputs list, producing the cross product of |
6142 all combinations, expanding placeholders (see below). | 6527 all combinations, expanding placeholders (see below). |
(...skipping 91 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6234 sources = [ "input1.idl", "input2.idl" ] | 6619 sources = [ "input1.idl", "input2.idl" ] |
6235 outputs = [ "{{source_gen_dir}}/{{source_name_part}}.h", | 6620 outputs = [ "{{source_gen_dir}}/{{source_name_part}}.h", |
6236 "{{source_gen_dir}}/{{source_name_part}}.cc" ] | 6621 "{{source_gen_dir}}/{{source_name_part}}.cc" ] |
6237 } | 6622 } |
6238 Performing source expansion will result in the following output names: | 6623 Performing source expansion will result in the following output names: |
6239 //out/Debug/obj/mydirectory/input1.h | 6624 //out/Debug/obj/mydirectory/input1.h |
6240 //out/Debug/obj/mydirectory/input1.cc | 6625 //out/Debug/obj/mydirectory/input1.cc |
6241 //out/Debug/obj/mydirectory/input2.h | 6626 //out/Debug/obj/mydirectory/input2.h |
6242 //out/Debug/obj/mydirectory/input2.cc | 6627 //out/Debug/obj/mydirectory/input2.cc |
6243 | 6628 |
| 6629 |
6244 ``` | 6630 ``` |
6245 **Available global switches | 6631 **Available global switches |
6246 ** Do "gn help --the_switch_you_want_help_on" for more. Individual | 6632 ** Do "gn help --the_switch_you_want_help_on" for more. Individual |
6247 commands may take command-specific switches not listed here. See the | 6633 commands may take command-specific switches not listed here. See the |
6248 help on your specific command for more. | 6634 help on your specific command for more. |
6249 | 6635 |
6250 ``` | 6636 ``` |
6251 | 6637 |
6252 ** \--args**: Specifies build arguments overrides. | 6638 ** \--args**: Specifies build arguments overrides. |
6253 ** \--color**: Force colored output. | 6639 ** \--color**: Force colored output. |
6254 ** \--dotfile**: Override the name of the ".gn" file. | 6640 ** \--dotfile**: Override the name of the ".gn" file. |
6255 ** \--fail-on-unused-args**: Treat unused build args as fatal errors. | 6641 ** \--fail-on-unused-args**: Treat unused build args as fatal errors. |
6256 ** \--markdown**: Write help output in the Markdown format. | 6642 ** \--markdown**: Write help output in the Markdown format. |
6257 ** \--nocolor**: Force non-colored output. | 6643 ** \--nocolor**: Force non-colored output. |
6258 ** -q**: Quiet mode. Don't print output on success. | 6644 ** -q**: Quiet mode. Don't print output on success. |
6259 ** \--root**: Explicitly specify source root. | 6645 ** \--root**: Explicitly specify source root. |
6260 ** \--runtime-deps-list-file**: Save runtime dependencies for targets in file. | 6646 ** \--runtime-deps-list-file**: Save runtime dependencies for targets in file. |
6261 ** \--script-executable**: Set the executable used to execute scripts. | 6647 ** \--script-executable**: Set the executable used to execute scripts. |
6262 ** \--threads**: Specify number of worker threads. | 6648 ** \--threads**: Specify number of worker threads. |
6263 ** \--time**: Outputs a summary of how long everything took. | 6649 ** \--time**: Outputs a summary of how long everything took. |
6264 ** \--tracelog**: Writes a Chrome-compatible trace log to the given file. | 6650 ** \--tracelog**: Writes a Chrome-compatible trace log to the given file. |
6265 ** -v**: Verbose logging. | 6651 ** -v**: Verbose logging. |
6266 ** \--version**: Prints the GN version number and exits. | 6652 ** \--version**: Prints the GN version number and exits. |
6267 | 6653 |
6268 ``` | 6654 ``` |
OLD | NEW |