OLD | NEW |
1 # GN Language and Operation | 1 # GN Language and Operation |
2 | 2 |
3 [TOC] | 3 [TOC] |
4 | 4 |
5 ## Introduction | 5 ## Introduction |
6 | 6 |
7 This page describes many of the language details and behaviors. | 7 This page describes many of the language details and behaviors. |
8 | 8 |
9 ### Use the built-in help! | 9 ### Use the built-in help! |
10 | 10 |
11 GN has an extensive built-in help system which provides a reference for | 11 GN has an extensive built-in help system which provides a reference for |
12 every function and built-in variable. This page is more high-level. | 12 every function and built-in variable. This page is more high-level. |
13 | 13 |
14 ``` | 14 ``` |
15 gn help | 15 gn help |
16 ``` | 16 ``` |
17 | 17 |
| 18 You can also see the |
| 19 [slides](https://docs.google.com/presentation/d/15Zwb53JcncHfEwHpnG_PoIbbzQ3GQi_
cpujYwbpcbZo/edit?usp=sharing) |
| 20 from a March, 2016 introduction to GN. The speaker notes contain the full |
| 21 content. |
| 22 |
18 ### Design philosophy | 23 ### Design philosophy |
19 | 24 |
20 * Writing build files should not be a creative endeavour. Ideally two | 25 * Writing build files should not be a creative endeavour. Ideally two |
21 people should produce the same buildfile given the same | 26 people should produce the same buildfile given the same |
22 requirements. There should be no flexibility unless it's absolutely | 27 requirements. There should be no flexibility unless it's absolutely |
23 needed. As many things should be fatal errors as possible. | 28 needed. As many things should be fatal errors as possible. |
24 | 29 |
25 * The definition should read more like code than rules. I don't want | 30 * The definition should read more like code than rules. I don't want |
26 to write or debug Prolog. But everybody on our team can write and | 31 to write or debug Prolog. But everybody on our team can write and |
27 debug C++ and Python. | 32 debug C++ and Python. |
28 | 33 |
29 * The build language should be opinionated as to how the build should | 34 * The build language should be opinionated as to how the build should |
30 work. It should not necessarily be easy or even possible to express | 35 work. It should not necessarily be easy or even possible to express |
31 arbitrary things. We should be changing source and tooling to make | 36 arbitrary things. We should be changing source and tooling to make |
32 the build simpler rather than making everything more complicated to | 37 the build simpler rather than making everything more complicated to |
33 conform to external requirements (within reason). | 38 conform to external requirements (within reason). |
34 | 39 |
35 * Be like Blaze when it makes sense (see "Differences and similarities | 40 * Be like Blaze when it makes sense (see "Differences and similarities |
36 to Blaze" below). | 41 to Blaze" below). |
37 | 42 |
38 ## Language | 43 ## Language |
39 | 44 |
40 GN uses an extremely simple, dynamically typed language. The types are: | 45 GN uses an extremely simple, dynamically typed language. The types are: |
41 | 46 |
42 * Boolean (`true`, `false`). | 47 * Boolean (`true`, `false`). |
43 * 64-bit signed integers. | 48 * 64-bit signed integers. |
44 * Strings | 49 * Strings. |
45 * Lists (of any other types) | 50 * Lists (of any other types). |
46 * Scopes (sort of like a dictionary, only for built-in stuff) | 51 * Scopes (sort of like a dictionary, only for built-in stuff). |
47 | 52 |
48 There are some built-in variables whose values depend on the current | 53 There are some built-in variables whose values depend on the current |
49 environment. See `gn help` for more. | 54 environment. See `gn help` for more. |
50 | 55 |
51 There are purposefully many omissions in the language. There are no | 56 There are purposefully many omissions in the language. There are no |
52 loops or function calls, for example. As per the above design | 57 user-defined function calls, for example (templates are the closest thing). As |
53 philosophy, if you need this kind of thing you're probably doing it | 58 per the above design philosophy, if you need this kind of thing you're probably |
54 wrong. | 59 doing it wrong. |
55 | 60 |
56 The variable `sources` has a special rule: when assigning to it, a list | 61 The variable `sources` has a special rule: when assigning to it, a list |
57 of exclusion patterns is applied to it. This is designed to | 62 of exclusion patterns is applied to it. This is designed to |
58 automatically filter out some types of files. See `gn help | 63 automatically filter out some types of files. See `gn help |
59 set_sources_assignment_filter` and `gn help label_pattern` for more. | 64 set_sources_assignment_filter` and `gn help label_pattern` for more. |
60 | 65 |
| 66 The full grammar for language nerds is available in `gn help grammar`. |
| 67 |
61 ### Strings | 68 ### Strings |
62 | 69 |
63 Strings are enclosed in double-quotes and use backslash as the escape | 70 Strings are enclosed in double-quotes and use backslash as the escape |
64 character. The only escape sequences supported are | 71 character. The only escape sequences supported are: |
65 | 72 |
66 * `\"` (for literal quote) | 73 * `\"` (for literal quote) |
67 * `\$` (for literal dollars sign) | 74 * `\$` (for literal dollars sign) |
68 * `\\` (for literal backslash) Any other use of a backslash is treated | 75 * `\\` (for literal backslash) |
69 as a literal backslash. So, for example, `\b` used in patterns does | 76 |
70 not need to be escaped, nor do most windows paths like | 77 Any other use of a backslash is treated as a literal backslash. So, for |
71 `"C:\foo\bar.h"`. | 78 example, `\b` used in patterns does not need to be escaped, nor do most Windows |
| 79 paths like `"C:\foo\bar.h"`. |
72 | 80 |
73 Simple variable substitution is supported via `$`, where the word | 81 Simple variable substitution is supported via `$`, where the word |
74 following the dollars sign is replaced with the value of the variable. | 82 following the dollars sign is replaced with the value of the variable. |
75 You can optionally surround the name with `{}` if there is not a | 83 You can optionally surround the name with `{}` if there is not a |
76 non-variable-name character to terminate the variable name. More complex | 84 non-variable-name character to terminate the variable name. More complex |
77 expressions are not supported, only variable name substitution. | 85 expressions are not supported, only variable name substitution. |
78 | 86 |
79 ``` | 87 ``` |
80 a = "mypath" | 88 a = "mypath" |
81 b = "$a/foo.cc" # b -> "mypath/foo.cc" | 89 b = "$a/foo.cc" # b -> "mypath/foo.cc" |
82 c = "foo${a}bar.cc" # c -> "foomypathbar.cc" | 90 c = "foo${a}bar.cc" # c -> "foomypathbar.cc" |
83 ``` | 91 ``` |
84 | 92 |
| 93 You can encode 8-bit haracters using "$0xFF" syntax, so a string with newlines |
| 94 (hex 0A) would `"look$0x0Alike$0x0Athis" |
| 95 |
85 ### Lists | 96 ### Lists |
86 | 97 |
87 There is no way to get the length of a list. If you find yourself | 98 There is no way to get the length of a list. If you find yourself |
88 wanting to do this kind of thing, you're trying to do too much work in | 99 wanting to do this kind of thing, you're trying to do too much work in |
89 the build. | 100 the build. |
90 | 101 |
91 Lists support appending: | 102 Lists support appending: |
92 | 103 |
93 ``` | 104 ``` |
94 a = [ "first" ] | 105 a = [ "first" ] |
(...skipping 16 matching lines...) Expand all Loading... |
111 The - operator on a list searches for matches and removes all matching | 122 The - operator on a list searches for matches and removes all matching |
112 items. Subtracting a list from another list will remove each item in the | 123 items. Subtracting a list from another list will remove each item in the |
113 second list. | 124 second list. |
114 | 125 |
115 If no matching items are found, an error will be thrown, so you need to | 126 If no matching items are found, an error will be thrown, so you need to |
116 know in advance that the item is there before removing it. Given that | 127 know in advance that the item is there before removing it. Given that |
117 there is no way to test for inclusion, the main use-case is to set up a | 128 there is no way to test for inclusion, the main use-case is to set up a |
118 master list of files or flags, and to remove ones that don't apply to | 129 master list of files or flags, and to remove ones that don't apply to |
119 the current build based on various conditions. | 130 the current build based on various conditions. |
120 | 131 |
| 132 Stylistically, prefer to only add to lists and have each source file or |
| 133 dependency appear once. This is the opposite of the advice Chrome-team used to |
| 134 give for GYP (GYP would prefer to list all files, and then remove the ones you |
| 135 didn't want in conditionals). |
| 136 |
121 Lists support zero-based subscripting to extract values: | 137 Lists support zero-based subscripting to extract values: |
122 | 138 |
123 ``` | 139 ``` |
124 a = [ "first", "second", "third" ] | 140 a = [ "first", "second", "third" ] |
125 b = a[1] # -> "second" | 141 b = a[1] # -> "second" |
126 ``` | 142 ``` |
127 | 143 |
128 The \[\] operator is read-only and can not be used to mutate the | 144 The \[\] operator is read-only and can not be used to mutate the |
129 list. This is of limited value absent the ability to iterate over a | |
130 list. The primary use-case of this is when an external script returns | 145 list. The primary use-case of this is when an external script returns |
131 several known values and you want to extract them. | 146 several known values and you want to extract them. |
132 | 147 |
133 There are some cases where it's easy to overwrite a list when you mean | 148 There are some cases where it's easy to overwrite a list when you mean |
134 to append to it instead. To help catch this case, it is an error to | 149 to append to it instead. To help catch this case, it is an error to |
135 assign a nonempty list to a variable containing an existing nonempty | 150 assign a nonempty list to a variable containing an existing nonempty |
136 list. If you want to get around this restriction, first assign the | 151 list. If you want to get around this restriction, first assign the |
137 destination variable to the empty list. | 152 destination variable to the empty list. |
138 | 153 |
139 ``` | 154 ``` |
(...skipping 19 matching lines...) Expand all Loading... |
159 } else if (...) { | 174 } else if (...) { |
160 ... | 175 ... |
161 } else { | 176 } else { |
162 ... | 177 ... |
163 } | 178 } |
164 ``` | 179 ``` |
165 | 180 |
166 You can use them in most places, even around entire targets if the | 181 You can use them in most places, even around entire targets if the |
167 target should only be declared in certain circumstances. | 182 target should only be declared in certain circumstances. |
168 | 183 |
169 ### Functions | 184 ### Looping |
170 | 185 |
171 Simple functions look like most other languages: | 186 You can iterate over a list with `foreach`. This is discouraged. Most things |
| 187 the build should do can normally be expressed without doing this, and if you |
| 188 find it necessary it may be an indication you're doing too much work in the |
| 189 metabuild. |
| 190 |
| 191 ``` |
| 192 foreach(i, mylist) { |
| 193 print(i) # Note: i is a copy of each element, not a reference to it. |
| 194 } |
| 195 ``` |
| 196 |
| 197 ### Function calls |
| 198 |
| 199 Simple function calls look like most other languages: |
172 | 200 |
173 ``` | 201 ``` |
174 print("hello, world") | 202 print("hello, world") |
175 assert(is_win, "This should only be executed on Windows") | 203 assert(is_win, "This should only be executed on Windows") |
176 ``` | 204 ``` |
177 | 205 |
| 206 Such functions are built-in and the user can not define new ones. |
| 207 |
178 Some functions take a block of code enclosed by `{ }` following them: | 208 Some functions take a block of code enclosed by `{ }` following them: |
179 | 209 |
180 ``` | 210 ``` |
181 static_library("mylibrary") { | 211 static_library("mylibrary") { |
182 sources = [ "a.cc" ] | 212 sources = [ "a.cc" ] |
183 } | 213 } |
184 ``` | 214 ``` |
185 | 215 |
186 This means that the block becomes an argument to the function for the | 216 Most of these define targets. The user can define new functions like this |
187 function to execute. Most of the block-style functions execute the block | 217 with the template mechanism discussed below. |
188 and treat the resulting scope as a dictionary of variables to read. | 218 |
| 219 Precisely, this expression means that the block becomes an argument to the |
| 220 function for the function to execute. Most of the block-style functions execute |
| 221 the block and treat the resulting scope as a dictionary of variables to read. |
189 | 222 |
190 ### Scoping and execution | 223 ### Scoping and execution |
191 | 224 |
192 Files and `{ }` blocks introduce new scopes. Scoped are nested. When you | 225 Files and function calls followed by `{ }` blocks introduce new scopes. Scopes |
193 read a variable, the containing scopes will be searched in reverse order | 226 are nested. When you read a variable, the containing scopes will be searched in |
194 until a matching name is found. Variable writes always go to the | 227 reverse order until a matching name is found. Variable writes always go to the |
195 innermost scope. | 228 innermost scope. |
196 | 229 |
197 There is no way to modify any enclosing scope other than the innermost | 230 There is no way to modify any enclosing scope other than the innermost |
198 one. This means that when you define a target, for example, nothing you | 231 one. This means that when you define a target, for example, nothing you |
199 do inside of the block will "leak out" into the rest of the file. | 232 do inside of the block will "leak out" into the rest of the file. |
200 | 233 |
201 `if`/`else` statements, even though they use `{ }`, do not introduce a | 234 `if`/`else`/`foreach` statements, even though they use `{ }`, do not introduce |
202 new scope so changes will persist outside of the statement. | 235 a new scope so changes will persist outside of the statement. |
203 | 236 |
204 ## Naming things | 237 ## Naming things |
205 | 238 |
206 ### File and directory names | 239 ### File and directory names |
207 | 240 |
208 File and directory names are strings and are interpreted as relative to | 241 File and directory names are strings and are interpreted as relative to |
209 the current build file's directory. There are three possible forms: | 242 the current build file's directory. There are three possible forms: |
210 | 243 |
211 Relative names: | 244 Relative names: |
212 | 245 |
(...skipping 26 matching lines...) Expand all Loading... |
239 ``` | 272 ``` |
240 "//base/test:test_support" | 273 "//base/test:test_support" |
241 ``` | 274 ``` |
242 | 275 |
243 which consists of a source-root-absolute path, a colon, and a name. This | 276 which consists of a source-root-absolute path, a colon, and a name. This |
244 means to look for the thing named "test\_support" in | 277 means to look for the thing named "test\_support" in |
245 `src/base/test/BUILD.gn`. | 278 `src/base/test/BUILD.gn`. |
246 | 279 |
247 When loading a build file, if it doesn't exist in the given location | 280 When loading a build file, if it doesn't exist in the given location |
248 relative to the source root, GN will look in the secondary tree in | 281 relative to the source root, GN will look in the secondary tree in |
249 `tools/gn/secondary`. The structure of this tree mirrors the main | 282 `build/secondary`. The structure of this tree mirrors the main |
250 repository and is a way to add build files for directories that may be | 283 repository and is a way to add build files for directories that may be |
251 pulled from other repositories where we can't easily check in BUILD | 284 pulled from other repositories where we can't easily check in BUILD |
252 files. | 285 files. The secondary tree is a fallback rather than an override, so a file in |
| 286 the normal location always takes precedence. |
253 | 287 |
254 A canonical label also includes the label of the toolchain being used. | 288 A canonical label also includes the label of the toolchain being used. |
255 Normally, the toolchain label is implicitly inherited, but you can | 289 Normally, the toolchain label is implicitly inherited, but you can |
256 include it to specify cross-toolchain dependencies (see "Toolchains" | 290 include it to specify cross-toolchain dependencies (see "Toolchains" |
257 below). | 291 below). |
258 | 292 |
259 ``` | 293 ``` |
260 "//base/test:test_support(//build/toolchain/win:msvc)" | 294 "//base/test:test_support(//build/toolchain/win:msvc)" |
261 ``` | 295 ``` |
262 | 296 |
263 In this case it will look for the toolchain definition called "msvc" | 297 In this case it will look for the toolchain definition called "msvc" |
264 in the file `//build/toolchain/win` to know how to compile this target. | 298 in the file `//build/toolchain/win` to know how to compile this target. |
265 | 299 |
266 If you want to refer to something in the same buildfile, you can omit | 300 If you want to refer to something in the same buildfile, you can omit |
267 the path name and just start with a colon. | 301 the path name and just start with a colon. |
268 | 302 |
269 ``` | 303 ``` |
270 ":base" | 304 ":base" |
271 ``` | 305 ``` |
272 | 306 |
273 Labels can be specified as being relative to the current directory: | 307 Labels can be specified as being relative to the current directory. |
| 308 Stylistically, we prefer to use absolute paths for all non-file-local |
| 309 references unless a build file needs to be run in different contexts (like |
| 310 a project needs to be both standalone and pulled into other projects in |
| 311 difference places in the directory hierarchy). |
274 | 312 |
275 ``` | 313 ``` |
276 "source/plugin:myplugin" | 314 "source/plugin:myplugin" # Prefer not to do these. |
277 "../net:url_request" | 315 "../net:url_request" |
278 ``` | 316 ``` |
279 | 317 |
280 If a name is unspecified, it will inherit the directory name: | 318 If a name is unspecified, it will inherit the directory name. Stylistically, we |
| 319 prefer to omit the colon and name in these cases. |
281 | 320 |
282 ``` | 321 ``` |
283 "//net" = "//net:net" | 322 "//net" = "//net:net" |
284 "//tools/gn" = "//tools/gn:gn" | 323 "//tools/gn" = "//tools/gn:gn" |
285 ``` | 324 ``` |
286 | 325 |
287 ## Build configuration | 326 ## Build configuration |
288 | 327 |
289 ### Overall build flow | 328 ### Overall build flow |
290 | 329 |
291 1. Look for `.gn` file in the current directory and walk up the | 330 1. Look for `.gn` file in the current directory and walk up the |
292 directory tree until one is found. Set this directory to be the | 331 directory tree until one is found. Set this directory to be the |
293 "source root" and interpret this file to find the name of the build | 332 "source root" and interpret this file to find the name of the build |
294 config file. | 333 config file. |
295 2. Execute the build config file (this is the default toolchain). | 334 2. Execute the build config file (this is the default toolchain). In Chrome |
| 335 this is `//build/config/BUILDCONFIG.gn`. |
296 3. Load the `BUILD.gn` file in the root directory. | 336 3. Load the `BUILD.gn` file in the root directory. |
297 4. Recursively load `BUILD.gn` in other directories to resolve all | 337 4. Recursively load `BUILD.gn` in other directories to resolve all |
298 current dependencies. If a BUILD file isn't found in the specified | 338 current dependencies. If a BUILD file isn't found in the specified |
299 location, GN will look in the corresponding location inside | 339 location, GN will look in the corresponding location inside |
300 `tools/gn/secondary`. | 340 `build/secondary`. |
301 5. When a target's dependencies are resolved, write out the `.ninja` | 341 5. When a target's dependencies are resolved, write out the `.ninja` |
302 file to disk. | 342 file to disk. |
303 6. When all targets are resolved, write out the root `build.ninja` | 343 6. When all targets are resolved, write out the root `build.ninja` |
304 file. | 344 file. |
305 | 345 |
306 ### The build config file | 346 ### The build config file |
307 | 347 |
308 The first file executed is the build config file. The name of this file | 348 The first file executed is the build config file. The name of this file |
309 is specified in the `.gn` file that marks the root of the repository. In | 349 is specified in the `.gn` file that marks the root of the repository. In |
310 Chrome it is `src/build/config/BUILDCONFIG.gn`. There is only one build | 350 Chrome it is `//build/config/BUILDCONFIG.gn`. There is only one build |
311 config file. | 351 config file. |
312 | 352 |
313 This file sets up the scope in which all other build files will execute. | 353 This file sets up the scope in which all other build files will execute. |
314 Any arguments, variables, defaults, etc. set up in this file will be | 354 Any arguments, variables, defaults, etc. set up in this file will be |
315 visible to all files in the build. | 355 visible to all files in the build. |
316 | 356 |
317 It is executed once for each toolchain (see "Toolchains"). | 357 It is executed once for each toolchain (see "Toolchains"). |
318 | 358 |
319 ### Build arguments | 359 ### Build arguments |
320 | 360 |
(...skipping 43 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
364 | 404 |
365 ## Targets | 405 ## Targets |
366 | 406 |
367 A target is a node in the build graph. It usually represents some kind | 407 A target is a node in the build graph. It usually represents some kind |
368 of executable or library file that will be generated. Targets depend on | 408 of executable or library file that will be generated. Targets depend on |
369 other targets. The built-in target types (see `gn help <targettype>` for | 409 other targets. The built-in target types (see `gn help <targettype>` for |
370 more help) are: | 410 more help) are: |
371 | 411 |
372 * `action`: Run a script to generate a file. | 412 * `action`: Run a script to generate a file. |
373 * `action_foreach`: Run a script once for each source file. | 413 * `action_foreach`: Run a script once for each source file. |
374 * `component`: Configurable to be another type of library. | 414 * `bundle_data`: Declare data to go into a Mac/iOS bundle. |
| 415 * `create_bundle`: Creates a Mac/iOS bundle. |
375 * `executable`: Generates an executable file. | 416 * `executable`: Generates an executable file. |
376 * `group`: A virtual dependency node that refers to one or more other | 417 * `group`: A virtual dependency node that refers to one or more other |
377 targets. | 418 targets. |
378 * `shared_library`: A .dll or .so. | 419 * `shared_library`: A .dll or .so. |
379 * `loadable_module`: A .dll or .so loadable only at runtime. | 420 * `loadable_module`: A .dll or .so loadable only at runtime. |
380 * `source_set`: A lightweight virtual static library (usually | 421 * `source_set`: A lightweight virtual static library (usually |
381 preferrable over a real static library since it will build faster). | 422 preferrable over a real static library since it will build faster). |
382 * `static_library`: A .lib or .a file (normally you'll want a | 423 * `static_library`: A .lib or .a file (normally you'll want a |
383 `source_set` instead). | 424 `source_set` instead). |
384 | 425 |
385 You can extend this to make custom target types using templates (see below). | 426 You can extend this to make custom target types using templates (see below). In |
| 427 Chrome some of the more commonly-used templates are: |
| 428 |
| 429 * `component`: Either a source set or shared library, depending on the |
| 430 build type. |
| 431 * `test`: A test executable. On mobile this will create the appropritate |
| 432 native app type for tests. |
| 433 * `app`: Executable or Mac/iOS application. |
| 434 * `android_apk`: Make an APK. There are a _lot_ of other Android ones, see |
| 435 `//build/config/android/rules.gni`. |
386 | 436 |
387 ## Configs | 437 ## Configs |
388 | 438 |
389 Configs are named objects that specify sets of flags, include | 439 Configs are named objects that specify sets of flags, include |
390 directories, and defines. They can be applied to a target and pushed to | 440 directories, and defines. They can be applied to a target and pushed to |
391 dependent targets. | 441 dependent targets. |
392 | 442 |
393 To define a config: | 443 To define a config: |
394 | 444 |
395 ``` | 445 ``` |
(...skipping 53 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
449 ``` | 499 ``` |
450 static_library("intermediate_library") { | 500 static_library("intermediate_library") { |
451 ... | 501 ... |
452 # Targets that depend on this one also get the configs from "my external libra
ry". | 502 # Targets that depend on this one also get the configs from "my external libra
ry". |
453 public_deps = [ ":my_external_library" ] | 503 public_deps = [ ":my_external_library" ] |
454 } | 504 } |
455 ``` | 505 ``` |
456 | 506 |
457 A target can forward a config to all dependents until a link boundary is | 507 A target can forward a config to all dependents until a link boundary is |
458 reached by setting it as an `all_dependent_config`. This is strongly | 508 reached by setting it as an `all_dependent_config`. This is strongly |
459 discouraged. | 509 discouraged as it can spray flags and defines over more of the build than |
| 510 necessary. Instead, use public_deps to control which flags apply where. |
| 511 |
| 512 In Chrome, prefer the build flag header system (`build/buildflag_header.gni`) |
| 513 for defines which prevents most screw-ups with compiler defines. |
460 | 514 |
461 ## Toolchains | 515 ## Toolchains |
462 | 516 |
463 A toolchain is a set of build commands to run for different types of | 517 A toolchain is a set of build commands to run for different types of |
464 input files and link tasks. | 518 input files and link tasks. |
465 | 519 |
466 You can have multiple toolchains in the build. It's easiest to think | 520 You can have multiple toolchains in the build. It's easiest to think |
467 about each one as completely separate builds that can additionally have | 521 about each one as completely separate builds that can additionally have |
468 dependencies between them. This means, for example, that the 32-bit | 522 dependencies between them. This means, for example, that the 32-bit |
469 Windows build might depend on a 64-bit helper target. Each of them can | 523 Windows build might depend on a 64-bit helper target. Each of them can |
(...skipping 119 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
589 specifies a set of arguments to pass to the build config file when | 643 specifies a set of arguments to pass to the build config file when |
590 executing. This allows you to pass configuration information to the | 644 executing. This allows you to pass configuration information to the |
591 alternate toolchain. | 645 alternate toolchain. |
592 | 646 |
593 ## Templates | 647 ## Templates |
594 | 648 |
595 Templates are GN's primary way to re-use code. Typically, a template | 649 Templates are GN's primary way to re-use code. Typically, a template |
596 would expand to one or more other target types. | 650 would expand to one or more other target types. |
597 | 651 |
598 ``` | 652 ``` |
599 # Declares static library consisting of rules to build all of the IDL files into | 653 # Declares a script that compiles IDL files to source, and then compiles those |
600 # compiled code. | 654 # source files. |
601 template("idl") { | 655 template("idl") { |
| 656 # Always base helper targets on target_name so they're unique. Target name |
| 657 # will be the string passed as the name when the template is invoked. |
| 658 idl_target_name = "${target_name}_generate" |
| 659 action_foreach(idl_target_name) { |
| 660 ... |
| 661 } |
| 662 |
| 663 # Your template should always define a target with the name target_name. |
| 664 # When other targets depend on your template invocation, this will be the |
| 665 # destination of that dependency. |
602 source_set(target_name) { | 666 source_set(target_name) { |
603 ... | 667 ... |
| 668 deps = [ ":$idl_target_name" ] # Require the sources to be compiled. |
604 } | 669 } |
605 } | 670 } |
606 ``` | 671 ``` |
607 | 672 |
608 Typically your template definition would go in a `.gni` file and users | 673 Typically your template definition would go in a `.gni` file and users |
609 would import that file to see the template definition: | 674 would import that file to see the template definition: |
610 | 675 |
611 ``` | 676 ``` |
612 import("//tools/idl_compiler.gni") | 677 import("//tools/idl_compiler.gni") |
613 | 678 |
(...skipping 15 matching lines...) Expand all Loading... |
629 } | 694 } |
630 ``` | 695 ``` |
631 | 696 |
632 The current directory when a template executes will be that of the | 697 The current directory when a template executes will be that of the |
633 invoking build file rather than the template source file. This is so | 698 invoking build file rather than the template source file. This is so |
634 files passed in from the template invoker will be correct (this | 699 files passed in from the template invoker will be correct (this |
635 generally accounts for most file handling in a template). However, if | 700 generally accounts for most file handling in a template). However, if |
636 the template has files itself (perhaps it generates an action that runs | 701 the template has files itself (perhaps it generates an action that runs |
637 a script), you will want to use absolute paths ("//foo/...") to refer to | 702 a script), you will want to use absolute paths ("//foo/...") to refer to |
638 these files to account for the fact that the current directory will be | 703 these files to account for the fact that the current directory will be |
639 unpredictable during invocation. See `gn help template` for more | 704 unpredictable during invocation. See `gn help template` for more |
640 information and more complete examples. | 705 information and more complete examples. |
641 | 706 |
642 ## Other features | 707 ## Other features |
643 | 708 |
644 ### Imports | 709 ### Imports |
645 | 710 |
646 You can import `.gni` files into the current scope with the `import` | 711 You can import `.gni` files into the current scope with the `import` |
647 function. This is _not_ an include. The imported file is executed | 712 function. This is _not_ an include in the C++ sense. The imported file is |
648 independently and the resulting scope is copied into the current file. | 713 executed independently and the resulting scope is copied into the current file |
649 This allows the results of the import to be cached, and also prevents | 714 (C++ executes the included file in the current context of when the |
650 some of the more "creative" uses of includes. | 715 include directive appeared). This allows the results of the import to be |
| 716 cached, and also prevents some of the more "creative" uses of includes like |
| 717 multiply-included files. |
651 | 718 |
652 Typically, a `.gni` would define build arguments and templates. See `gn | 719 Typically, a `.gni` would define build arguments and templates. See `gn |
653 help import` for more. | 720 help import` for more. |
654 | 721 |
| 722 Your `.gni` file can define temporary variables that are not exported files |
| 723 that include it by using a preceding underscore in the name like `_this`. |
| 724 |
655 ### Path processing | 725 ### Path processing |
656 | 726 |
657 Often you will want to make a file name or a list of file names relative | 727 Often you will want to make a file name or a list of file names relative |
658 to a different directory. This is especially common when running | 728 to a different directory. This is especially common when running |
659 scripts, which are executed with the build output directory as the | 729 scripts, which are executed with the build output directory as the |
660 current directory, while build files usually refer to files relative to | 730 current directory, while build files usually refer to files relative to |
661 their containing directory. | 731 their containing directory. |
662 | 732 |
663 You can use `rebase_path` to convert directories. See `gn help | 733 You can use `rebase_path` to convert directories. See `gn help |
664 rebase_path` for more help and examples. Typical usage to convert a file | 734 rebase_path` for more help and examples. Typical usage to convert a file |
(...skipping 23 matching lines...) Expand all Loading... |
688 to compile, or to get certain system configurations that the build file | 758 to compile, or to get certain system configurations that the build file |
689 might depend on. The build file can read the stdout of the script and | 759 might depend on. The build file can read the stdout of the script and |
690 act on it in different ways. | 760 act on it in different ways. |
691 | 761 |
692 Synchronous script execution is done by the `exec_script` function (see | 762 Synchronous script execution is done by the `exec_script` function (see |
693 `gn help exec_script` for details and examples). Because synchronously | 763 `gn help exec_script` for details and examples). Because synchronously |
694 executing a script requires that the current buildfile execution be | 764 executing a script requires that the current buildfile execution be |
695 suspended until a Python process completes execution, relying on | 765 suspended until a Python process completes execution, relying on |
696 external scripts is slow and should be minimized. | 766 external scripts is slow and should be minimized. |
697 | 767 |
698 You can synchronously read and write files which is occasionally | 768 To prevent abuse, files permitted to call `exec_script` can be whitelisted in |
699 necessary when synchronously running scripts. The typical use-case would | 769 the toplevel `.gn` file. Chrome does this to require additional code review |
700 be to pass a list of file names longer than the command-line limits of | 770 for such additions. See `gn help dotfile`. |
701 the current platform. See `gn help read_file` and `gn help write_file` | 771 |
702 for how to read and write files. These functions should be avoided if at | 772 You can synchronously read and write files which is discouraged but |
703 all possible. | 773 occasionally necessary when synchronously running scripts. The typical use-case |
| 774 would be to pass a list of file names longer than the command-line limits of |
| 775 the current platform. See `gn help read_file` and `gn help write_file` for how |
| 776 to read and write files. These functions should be avoided if at all possible. |
| 777 |
| 778 Actions that exceed command-line length limits can use response files to |
| 779 get around this limitation without synchronously writing files. See |
| 780 `gn help response_file_contents`. |
704 | 781 |
705 # Differences and similarities to Blaze | 782 # Differences and similarities to Blaze |
706 | 783 |
707 [Blaze](http://google-engtools.blogspot.com/2011/08/build-in-cloud-how-build-sys
tem-works.html) | 784 Blaze is Google's internal build system, now publicly released as |
708 is Google's internal build system. It has inspired a number of other | 785 [Bazel](http://bazel.io/). It has inspired a number of other systems such as |
709 systems such as | |
710 [Pants](https://github.com/twitter/commons/tree/master/src/python/twitter/pants) | 786 [Pants](https://github.com/twitter/commons/tree/master/src/python/twitter/pants) |
711 and [Buck](http://facebook.github.io/buck/). | 787 and [Buck](http://facebook.github.io/buck/). |
712 | 788 |
713 In Google's homogeneous environment, the need for conditionals is very | 789 In Google's homogeneous environment, the need for conditionals is very |
714 low and they can get by with a few hacks (`abi_deps`). Chrome uses | 790 low and they can get by with a few hacks (`abi_deps`). Chrome uses |
715 conditionals all over the place and the need to add these is the main | 791 conditionals all over the place and the need to add these is the main |
716 reason for the files looking different. | 792 reason for the files looking different. |
717 | 793 |
718 GN also adds the concept of "configs" to manage some of the trickier | 794 GN also adds the concept of "configs" to manage some of the trickier |
719 dependency and configuration problems which likewise don't arise on the | 795 dependency and configuration problems which likewise don't arise on the |
720 server. Blaze has a concept of a "configuration" which is like a GN | 796 server. Blaze has a concept of a "configuration" which is like a GN |
721 toolchain, but built into the tool itself. The way that toolchains work | 797 toolchain, but built into the tool itself. The way that toolchains work |
722 in GN is a result of trying to separate this concept out into the build | 798 in GN is a result of trying to separate this concept out into the build |
723 files in a clean way. | 799 files in a clean way. |
724 | 800 |
725 GN keeps some GYP concept like "all dependent" and "direct dependent" | 801 GN keeps some GYP concept like "all dependent" settings which work a bit |
726 settings which work a bit differently in Blaze. This is partially to | 802 differently in Blaze. This is partially to make conversion from the existing |
727 make conversion from the existing GYP code easier, and the GYP | 803 GYP code easier, and the GYP constructs generally offer more fine-grained |
728 constructs generally offer more fine-grained control (which is either | 804 control (which is either good or bad, depending on the situation). |
729 good or bad, depending on the situation). | |
730 | 805 |
731 GN also uses GYP names like "sources" instead of "srcs" since | 806 GN also uses GYP names like "sources" instead of "srcs" since |
732 abbreviating this seems needlessly obscure, although it uses Blaze's | 807 abbreviating this seems needlessly obscure, although it uses Blaze's |
733 "deps" since "dependencies" is so hard to type. Chromium also compiles | 808 "deps" since "dependencies" is so hard to type. Chromium also compiles |
734 multiple languages in one target so specifying the language type on the | 809 multiple languages in one target so specifying the language type on the |
735 target name prefix was dropped (e.g. from `cc_library`). | 810 target name prefix was dropped (e.g. from `cc_library`). |
OLD | NEW |