Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(175)

Side by Side Diff: tools/gn/docs/reference.md

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

Powered by Google App Engine
This is Rietveld 408576698