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 |
11 changes are more focused. | 11 changes are more focused. |
12 | 12 |
13 ### Targets | 13 ### Targets |
14 | 14 |
15 * Most BUILD files should have a target with the same name of the | 15 * Most BUILD files should have a target with the same name of the |
16 directory. This target should be the first target. | 16 directory. This target should be the first target. |
17 * Other targets should be in "some order that makes sense." Usually | 17 * Other targets should be in "some order that makes sense." Usually |
18 more important targets will be first, and unit tests will follow the | 18 more important targets will be first, and unit tests will follow the |
19 corresponding target. If there's no clear ordering, consider | 19 corresponding target. If there's no clear ordering, consider |
20 alphabetical order. | 20 alphabetical order. |
21 * Test support libraries should be source sets named "test\_support". | 21 * Test support libraries should be static libraries named "test\_support". |
22 So "//ui/compositor:test\_support". Test support libraries should | 22 So "//ui/compositor:test\_support". Test support libraries should |
23 include as public deps the non-test-support version of the library | 23 include as public deps the non-test-support version of the library |
24 so tests need only depend on the test\_support target (rather than | 24 so tests need only depend on the test\_support target (rather than |
25 both). | 25 both). |
26 | 26 |
27 Naming advice | 27 Naming advice |
28 | 28 |
29 * Targets and configs should be named using lowercase with underscores | 29 * Targets and configs should be named using lowercase with underscores |
30 separating words, unless there is a strong reason to do otherwise. | 30 separating words, unless there is a strong reason to do otherwise. |
31 * Source sets, groups, and static libraries do not need globally unique names. | 31 * Source sets, groups, and static libraries do not need globally unique names. |
(...skipping 14 matching lines...) Expand all Loading... |
46 * A config associated with a single target should be named the same as | 46 * A config associated with a single target should be named the same as |
47 the target with `_config` following it. | 47 the target with `_config` following it. |
48 * A config should appear immediately before the corresponding target | 48 * A config should appear immediately before the corresponding target |
49 that uses it. | 49 that uses it. |
50 | 50 |
51 ### Example | 51 ### Example |
52 | 52 |
53 Example for the `src/foo/BUILD.gn` file: | 53 Example for the `src/foo/BUILD.gn` file: |
54 | 54 |
55 ``` | 55 ``` |
56 # Copyright 2013 The Chromium Authors. All rights reserved. | 56 # Copyright 2016 The Chromium Authors. All rights reserved. |
57 # Use of this source code is governed by a BSD-style license that can be | 57 # Use of this source code is governed by a BSD-style license that can be |
58 # found in the LICENSE file. | 58 # found in the LICENSE file. |
59 | 59 |
60 # Config for foo is named foo_config and immediately precedes it in the file. | 60 # Config for foo is named foo_config and immediately precedes it in the file. |
61 config("foo_config") { | 61 config("foo_config") { |
62 } | 62 } |
63 | 63 |
64 # Target matching path name is the first target. | 64 # Target matching path name is the first target. |
65 executable("foo") { | 65 executable("foo") { |
66 } | 66 } |
(...skipping 76 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
143 ### Import | 143 ### Import |
144 | 144 |
145 Use fully-qualified paths for imports: | 145 Use fully-qualified paths for imports: |
146 | 146 |
147 ``` | 147 ``` |
148 import("//foo/bar/baz.gni") # Even if this file is in the foo/bar directory | 148 import("//foo/bar/baz.gni") # Even if this file is in the foo/bar directory |
149 ``` | 149 ``` |
150 | 150 |
151 ## Usage | 151 ## Usage |
152 | 152 |
153 Use `source_set` rather than `static_library` unless you have a reason | 153 ### Source sets versus static libraries |
154 to do otherwise. A static library is a standalone library which can be | 154 |
155 slow to generate. A source set just links all the object files from that | 155 Source sets and static libraries can be used interchangeably in most cases. If |
156 target into the targets depending on it, which saves the "lib" step. | 156 you're unsure what to use, a source set is almost never wrong and is less likely |
| 157 to cause problems. |
| 158 |
| 159 Static libraries follow different linking rules. When a static library is |
| 160 included in a link, only the object files that contain unresolved symbols will |
| 161 be brought into the build. Source sets result in every object file being added |
| 162 to the link line of the final binary. |
| 163 |
| 164 * If you're eventually linking code into a component, shared library, or |
| 165 loadable module, you normally need to use source sets. This is because |
| 166 object files with no symbols referenced from within the shared library will |
| 167 not be linked into the final library at all. This omission will happen even |
| 168 if that object file has a symbol marked for export that targets dependant |
| 169 on that shared library need. This will result in undefined symbols when |
| 170 linking later targets. |
| 171 |
| 172 * Unit tests (and anything else with static initializers with side effects) |
| 173 must use source sets. The gtest TEST macros create static initializers |
| 174 that register the test. But since no code references symbols in the object |
| 175 file, linking a test into a static library and then into a test executable |
| 176 means the tests will get stripped. |
| 177 |
| 178 * Static libraries involve duplicating all of the data in the object files |
| 179 that comprise it. This takes more disk space and for certain very large |
| 180 libraries in configurations with very large object files can cause |
| 181 internal limits on the size of static libraries to be exceeded. Source |
| 182 sets do not have this limitation. Some targets switch between source sets |
| 183 and static libraries depending on the build configuration to avoid this |
| 184 problem. |
| 185 |
| 186 * In cases where a lot of the symbols are not needed for a particular link |
| 187 (this especially happens when linking test binaries), putting that code in |
| 188 a static library can dramatically increase linking performance. This is |
| 189 because the object files not needed for the link are never considered in |
| 190 the first place, rather than forcing the linker to strip the unused code |
| 191 in a later pass when nothing references it. |
| 192 |
| 193 ### Loadable modules versus shared libraries versus components |
| 194 |
| 195 A component is a Chrome primitive (rather than a built-in GN concept) that |
| 196 expands either to a shared library or a static library / source set depending |
| 197 on the value of the `is_component_build` variable. This allows release builds |
| 198 to be linked statically in a large binary, but for developers to use shared |
| 199 libraries for most operations. |
| 200 |
| 201 A shared library will be listed on the link line of dependant targets and will |
| 202 be loaded automatically by the operating system when the application starts |
| 203 and symbols automatically resolved. A loadable module will not be linked |
| 204 directly and the application must manually load it. |
| 205 |
| 206 On Windows and Linux shared libraries and loadable modules result in the same |
| 207 type of file (`.dll` and `.so`, respectively). The only difference is in how |
| 208 they are linked to dependant targets. On these platforms, having a `deps` |
| 209 dependency on a loadable module is the same as having a `data_deps` |
| 210 (non-linked) dependency on a shared library. |
| 211 |
| 212 On Mac, these targets have different formats: a shared library will generate a |
| 213 `.dylib` file and a loadable module will generate a `.so` file. |
| 214 |
| 215 Use loadable modules for things like plugins. Shared libraries should be |
| 216 seldom-used outside of components because most Chrome code is shipped to the |
| 217 end-user as a small number of large binaries. In the case of plugin-like |
| 218 libraries, it's good practice to use both a loadable module for the target type |
| 219 (even for platforms where it doesn't matter) and data deps for targets that |
| 220 depend on it so it's clear from both places that how the library will be linked |
| 221 and loaded. |
157 | 222 |
158 ## Build arguments | 223 ## Build arguments |
159 | 224 |
160 ### Scope | 225 ### Scope |
161 | 226 |
162 Build arguments should be scoped to a unit of behavior, e.g. enabling a feature. | 227 Build arguments should be scoped to a unit of behavior, e.g. enabling a feature. |
163 Typically an argument would be declared in an imported file to share it with | 228 Typically an argument would be declared in an imported file to share it with |
164 the subset of the build that could make use of it. | 229 the subset of the build that could make use of it. |
165 | 230 |
166 Chrome has many legacy flags in `//build/config/features.gni`, | 231 Chrome has many legacy flags in `//build/config/features.gni`, |
(...skipping 38 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
205 `enable_google_now`, `enable_nacl`, `enable_remoting`, `enable_pdf`) | 270 `enable_google_now`, `enable_nacl`, `enable_remoting`, `enable_pdf`) |
206 | 271 |
207 `disable_foo` - _NOT_ recommended, use `enable_foo` instead with swapped default | 272 `disable_foo` - _NOT_ recommended, use `enable_foo` instead with swapped default |
208 value | 273 value |
209 | 274 |
210 `is_foo` - usually a global state descriptor (e.g. `is_chrome_branded`, | 275 `is_foo` - usually a global state descriptor (e.g. `is_chrome_branded`, |
211 `is_desktop_linux`); poor choice for non-globals | 276 `is_desktop_linux`); poor choice for non-globals |
212 | 277 |
213 `foo_use_bar` - prefixes can be used to indicate a limited scope for an argument | 278 `foo_use_bar` - prefixes can be used to indicate a limited scope for an argument |
214 (e.g. `rtc_use_h264`, `v8_use_snapshot`) | 279 (e.g. `rtc_use_h264`, `v8_use_snapshot`) |
OLD | NEW |