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 |
(...skipping 38 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
49 environment. See `gn help` for more. | 49 environment. See `gn help` for more. |
50 | 50 |
51 There are purposefully many omissions in the language. There are no | 51 There are purposefully many omissions in the language. There are no |
52 loops or function calls, for example. As per the above design | 52 loops or function calls, for example. As per the above design |
53 philosophy, if you need this kind of thing you're probably doing it | 53 philosophy, if you need this kind of thing you're probably doing it |
54 wrong. | 54 wrong. |
55 | 55 |
56 The variable `sources` has a special rule: when assigning to it, a list | 56 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 | 57 of exclusion patterns is applied to it. This is designed to |
58 automatically filter out some types of files. See `gn help | 58 automatically filter out some types of files. See `gn help |
59 set_sources_assignment_filter` and `gn help patterns` for more. | 59 set_sources_assignment_filter` for more. |
eroman
2015/09/11 20:37:06
(gn help patterns doesn't exist)
brettw
2015/09/11 21:03:14
Ah, this should be `gn help label_pattern` instead
eroman
2015/09/11 21:08:11
Done.
| |
60 | 60 |
61 ### Strings | 61 ### Strings |
62 | 62 |
63 Strings are enclosed in double-quotes and use backslash as the escape | 63 Strings are enclosed in double-quotes and use backslash as the escape |
64 character. The only escape sequences supported are | 64 character. The only escape sequences supported are |
65 | 65 |
66 * `\"` (for literal quote) | 66 * `\"` (for literal quote) |
67 * `\$` (for literal dollars sign) | 67 * `\$` (for literal dollars sign) |
68 * `\\` (for literal backslash) Any other use of a backslash is treated | 68 * `\\` (for literal backslash) Any other use of a backslash is treated |
69 as a literal backslash. So, for example, `\b` used in patterns does | 69 as a literal backslash. So, for example, `\b` used in patterns does |
(...skipping 169 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
239 ``` | 239 ``` |
240 "//base/test:test_support" | 240 "//base/test:test_support" |
241 ``` | 241 ``` |
242 | 242 |
243 which consists of a source-root-absolute path, a colon, and a name. This | 243 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 | 244 means to look for the thing named "test\_support" in |
245 `src/base/test/BUILD.gn`. | 245 `src/base/test/BUILD.gn`. |
246 | 246 |
247 When loading a build file, if it doesn't exist in the given location | 247 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 | 248 relative to the source root, GN will look in the secondary tree in |
249 `tools/gn/secondary`. This structure of this tree mirrors the main | 249 `tools/gn/secondary`. The structure of this tree mirrors the main |
250 repository and is a way to add build files for directories that may be | 250 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 | 251 pulled from other repositories where we can't easily check in BUILD |
252 files. | 252 files. |
253 | 253 |
254 A canonical label also includes the label of the toolchain being used. | 254 A canonical label also includes the label of the toolchain being used. |
255 Normally, the toolchain label is implicitly inherited, but you can | 255 Normally, the toolchain label is implicitly inherited, but you can |
256 include it to specify cross-toolchain dependencies (see "Toolchains" | 256 include it to specify cross-toolchain dependencies (see "Toolchains" |
257 below). | 257 below). |
258 | 258 |
259 ``` | 259 ``` |
260 "//base/test:test_support(//build/toolchain/win:msvc)" | 260 "//base/test:test_support(//build/toolchain/win:msvc)" |
261 ``` | 261 ``` |
262 | 262 |
263 In this case it will look for the a toolchain definition called "msvc" | 263 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. | 264 in the file `//build/toolchain/win` to know how to compile this target. |
265 | 265 |
266 If you want to refer to something in the same buildfile, you can omit | 266 If you want to refer to something in the same buildfile, you can omit |
267 the path name and just start with a colon. | 267 the path name and just start with a colon. |
268 | 268 |
269 ``` | 269 ``` |
270 ":base" | 270 ":base" |
271 ``` | 271 ``` |
272 | 272 |
273 Labels can be specified as being relative to the current directory: | 273 Labels can be specified as being relative to the current directory: |
(...skipping 99 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
373 * `action_foreach`: Run a script once for each source file. | 373 * `action_foreach`: Run a script once for each source file. |
374 * `component`: Configurable to be another type of library. | 374 * `component`: Configurable to be another type of library. |
375 * `executable`: Generates an executable file. | 375 * `executable`: Generates an executable file. |
376 * `group`: A virtual dependency node that refers to one or more other | 376 * `group`: A virtual dependency node that refers to one or more other |
377 targets. | 377 targets. |
378 * `shared_library`: A .dll or .so. | 378 * `shared_library`: A .dll or .so. |
379 * `source_set`: A lightweight virtual static library (usually | 379 * `source_set`: A lightweight virtual static library (usually |
380 preferrable over a real static library since it will build faster). | 380 preferrable over a real static library since it will build faster). |
381 * `static_library`: A .lib or .a file (normally you'll want a | 381 * `static_library`: A .lib or .a file (normally you'll want a |
382 source\_set instead). | 382 source\_set instead). |
383 * `test`: Generates an executable but annotates it as a test. | |
eroman
2015/09/11 20:37:06
"test" does not appear to be a built-in (rather is
brettw
2015/09/11 21:03:14
Yeah, I moved this a while ago to being a template
| |
384 | 383 |
385 You can extend this to make custom target types using templates (see below). | 384 You can extend this to make custom target types using templates (see below). |
386 | 385 |
387 ## Configs | 386 ## Configs |
388 | 387 |
389 Configs are named objects that specify sets of flags, include | 388 Configs are named objects that specify sets of flags, include |
390 directories, and defines. They can be applied to a target and pushed to | 389 directories, and defines. They can be applied to a target and pushed to |
391 dependent targets. | 390 dependent targets. |
392 | 391 |
393 To define a config: | 392 To define a config: |
(...skipping 271 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
665 name relative to the current directory to be relative to the root build | 664 name relative to the current directory to be relative to the root build |
666 directory would be: ``` new_paths = rebase_path("myfile.c", | 665 directory would be: ``` new_paths = rebase_path("myfile.c", |
667 root_build_dir) ``` | 666 root_build_dir) ``` |
668 | 667 |
669 ### Patterns | 668 ### Patterns |
670 | 669 |
671 Patterns are used to generate the output file names for a given set of | 670 Patterns are used to generate the output file names for a given set of |
672 inputs for custom target types, and to automatically remove files from | 671 inputs for custom target types, and to automatically remove files from |
673 the `sources` variable (see `gn help set_sources_assignment_filter`). | 672 the `sources` variable (see `gn help set_sources_assignment_filter`). |
674 | 673 |
675 They are like simple regular expressions. See `gn help patterns` for more. | 674 They are like simple regular expressions. See `gn help set_sources_assignment_fi lter` for more. |
eroman
2015/09/11 20:37:06
Is this right? Do I need to wrap this?
brettw
2015/09/11 21:03:14
label_pattern instead.
| |
676 | 675 |
677 ### Executing scripts | 676 ### Executing scripts |
678 | 677 |
679 There are two ways to execute scripts. All external scripts in GN are in | 678 There are two ways to execute scripts. All external scripts in GN are in |
680 Python. The first way is as a build step. Such a script would take some | 679 Python. The first way is as a build step. Such a script would take some |
681 input and generate some output as part of the build. Targets that invoke | 680 input and generate some output as part of the build. Targets that invoke |
682 scripts are declared with the "action" target type (see `gn help | 681 scripts are declared with the "action" target type (see `gn help |
683 action`). | 682 action`). |
684 | 683 |
685 The second way to execute scripts is synchronously during build file | 684 The second way to execute scripts is synchronously during build file |
(...skipping 39 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
725 settings which work a bit differently in Blaze. This is partially to | 724 settings which work a bit differently in Blaze. This is partially to |
726 make conversion from the existing GYP code easier, and the GYP | 725 make conversion from the existing GYP code easier, and the GYP |
727 constructs generally offer more fine-grained control (which is either | 726 constructs generally offer more fine-grained control (which is either |
728 good or bad, depending on the situation). | 727 good or bad, depending on the situation). |
729 | 728 |
730 GN also uses GYP names like "sources" instead of "srcs" since | 729 GN also uses GYP names like "sources" instead of "srcs" since |
731 abbreviating this seems needlessly obscure, although it uses Blaze's | 730 abbreviating this seems needlessly obscure, although it uses Blaze's |
732 "deps" since "dependencies" is so hard to type. Chromium also compiles | 731 "deps" since "dependencies" is so hard to type. Chromium also compiles |
733 multiple languages in one target so specifying the language type on the | 732 multiple languages in one target so specifying the language type on the |
734 target name prefix was dropped (e.g. from `cc_library`). | 733 target name prefix was dropped (e.g. from `cc_library`). |
OLD | NEW |