OLD | NEW |
1 # GN Style Guide | 1 # GN Style Guide |
2 | 2 |
3 [TOC] | 3 [TOC] |
4 ## Naming and ordering within the file | 4 ## Naming and ordering within the file |
5 | 5 |
6 ### Location of build files | 6 ### Location of build files |
7 | 7 |
8 It usually makes sense to have more build files closer to the code than | 8 It usually makes sense to have more build files closer to the code than |
9 fewer ones at the toplevel (this is in contrast with what we did with | 9 fewer ones at the toplevel (this is in contrast with what we did with |
10 GYP). This makes things easier to find and owners reviews easier since | 10 GYP). This makes things easier to find and owners reviews easier since |
(...skipping 164 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
175 ``` | 175 ``` |
176 import("//foo/bar/baz.gni") # Even if this file is in the foo/bar directory | 176 import("//foo/bar/baz.gni") # Even if this file is in the foo/bar directory |
177 ``` | 177 ``` |
178 | 178 |
179 ## Usage | 179 ## Usage |
180 | 180 |
181 Use `source_set` rather than `static_library` unless you have a reason | 181 Use `source_set` rather than `static_library` unless you have a reason |
182 to do otherwise. A static library is a standalone library which can be | 182 to do otherwise. A static library is a standalone library which can be |
183 slow to generate. A source set just links all the object files from that | 183 slow to generate. A source set just links all the object files from that |
184 target into the targets depending on it, which saves the "lib" step. | 184 target into the targets depending on it, which saves the "lib" step. |
| 185 |
| 186 ## Build arguments |
| 187 |
| 188 ### Scope |
| 189 |
| 190 Build arguments should be scoped to a unit of behavior, e.g. enabling a feature. |
| 191 Typically an argument would be declared in an imported file to share it with |
| 192 the subset of the build that could make use of it. |
| 193 |
| 194 ### Type |
| 195 |
| 196 Arguments support all the [GN language types](language.md#Language). |
| 197 |
| 198 In the vast majority of cases `boolean` is the preferred type, since most |
| 199 arguments are enabling or disabling features or includes. |
| 200 |
| 201 `String`s are typically used for filepaths. They are also used for enumerated |
| 202 types, though `integer`s are sometimes used as well. |
| 203 |
| 204 ### Naming conventions |
| 205 |
| 206 While there are no hard and fast rules around argument naming there are |
| 207 many common conventions. If you ever want to see the current list of argument |
| 208 names and default values for your current checkout use |
| 209 `gn args out/Debug --list --short`. |
| 210 |
| 211 `use_foo` - indicates dependencies or major codepaths to include (e.g. |
| 212 `use_open_ssl`, `use_ozone`, `use_cups`) |
| 213 |
| 214 `enable_foo` - indicates feature or tools to be enabled (e.g. |
| 215 `enable_google_now`, `enable_nacl`, `enable_remoting`, `enable_pdf`) |
| 216 |
| 217 `disable_foo` - _NOT_ recommended, use `enable_foo` instead with swapped default |
| 218 value |
| 219 |
| 220 `is_foo` - usually a global state descriptor (e.g. `is_chrome_branded`, |
| 221 `is_desktop_linux`); poor choice for non-globals |
| 222 |
| 223 `foo_use_bar` - prefixes can be used to indicate a limited scope for an argument |
| 224 (e.g. `rtc_use_h264`, `v8_use_snapshot`) |
OLD | NEW |