Chromium Code Reviews| 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 |