| OLD | NEW |
|---|
| (Empty) |
| 1 # GYP->GN Conversion Cookbook | |
| 2 | |
| 3 [TOC] | |
| 4 | |
| 5 ## Targets | |
| 6 | |
| 7 | *GYP* | *GN*
| | |
| 8 |:-------------------------------------------------|:---------------------------
------------------------| | |
| 9 | `'type': 'static_library', 'name': 'foo',` | `static_library("foo") {` o
r `source_set("foo") {` | | |
| 10 | `'type': 'shared_library', 'name': 'foo',` | `shared_library("foo") {`
| | |
| 11 | `'type': 'loadable_module', 'name': 'foo',` | `loadable_module("foo") {`
| | |
| 12 | `'type': '<(component)', 'name': 'foo',` | `component("foo") {`
| | |
| 13 | `'type': 'executable', 'name': 'foo',` | `executable("foo") {`
| | |
| 14 | `'type': '<(gtest_target_type)', 'name': 'foo',` | `test("foo") {`
| | |
| 15 | `'type': 'none', 'name': 'foo',` | `group("foo") {`
| | |
| 16 | |
| 17 ### Note on static libraries | |
| 18 | |
| 19 A source\_set is basically a transparent static\_library. The source files | |
| 20 are compiled with the given options but not linked into anything. | |
| 21 Targets that depend on a source set get the source set's object files | |
| 22 linked into it. This saves the overhead of creating a static library on | |
| 23 disk, avoids weird linker issues when a static library has no source | |
| 24 files, and you can link source sets into shared libraries and have | |
| 25 symbols exported from the shared library. | |
| 26 | |
| 27 The last issue is a cause of a lot of headaches in the GYP build. If you | |
| 28 annotate a symbol as exported (i.e. `BASE_EXPORT`) then you can't have | |
| 29 it in a file that goes into a static library because the function might | |
| 30 be [stripped out](http://blogs.msdn.com/b/oldnewthing/archive/2014/03/21/1050967
0.aspx) | |
| 31 if it's not called from within the static library. This | |
| 32 prevents composing components of static libraries and exporting their | |
| 33 symbols. A source set avoids this issue and `EXPORT` has the desired | |
| 34 meaning of "export from the component this gets linked into" with no | |
| 35 surprising dead code stripping behavior. | |
| 36 | |
| 37 A disadvantage of source sets is that if an object file is completely | |
| 38 unused, it will still be linked into the result, which is not the case | |
| 39 for static libraries. A few places in the build depend on this behavior | |
| 40 (deliberately or accidentally). In general, small libraries that we | |
| 41 expect to be entirely used, test helpers, etc. can be source sets. There | |
| 42 is slightly less risk of subtle issues if you keep static libraries | |
| 43 static libraries, however. | |
| 44 | |
| 45 ### Actions | |
| 46 | |
| 47 GYP | |
| 48 | |
| 49 ``` | |
| 50 { | |
| 51 'action_name': 'foo', | |
| 52 'inputs': [ 'bar.py' ], | |
| 53 'outputs': [ '<(SHARED_INTERMEDIATE_DIR)/bar.out' ], | |
| 54 'action': ['python', 'bar.py', '--la_dee_da' ], | |
| 55 }, | |
| 56 ``` | |
| 57 | |
| 58 Unlike GYP, where an action is a part of a target, GN actions are | |
| 59 separate targets that you then depend on via deps from other targets: | |
| 60 | |
| 61 ``` | |
| 62 action("foo") { | |
| 63 script = "bar.py" | |
| 64 outputs = [ "$target_gen_dir/bar.out" ] | |
| 65 args = [ "--la_dee_da" ] | |
| 66 } | |
| 67 | |
| 68 executable("foo.exe") { | |
| 69 ... | |
| 70 deps = [ ":foo" ] # Depend on the action to make sure it runs. | |
| 71 } | |
| 72 ``` | |
| 73 | |
| 74 Rules in GYP become `action_foreach` in GN which work like actions but | |
| 75 iterate over a set of sources. | |
| 76 | |
| 77 ### Copies | |
| 78 | |
| 79 GYP | |
| 80 | |
| 81 ``` | |
| 82 'copies': [ | |
| 83 { | |
| 84 'destination': '<(PRODUCT_DIR)/', | |
| 85 'files': [ | |
| 86 '../build/win/dbghelp_xp/dbghelp.dll', | |
| 87 ], | |
| 88 }, | |
| 89 ], | |
| 90 ``` | |
| 91 | |
| 92 Unlike GYP, where copies are part of a target, GN copies are | |
| 93 separate targets that you then depend on via deps from other targets: | |
| 94 | |
| 95 ``` | |
| 96 copy("bar") { | |
| 97 sources = [ "../path/to/secret.dll" ] | |
| 98 outputs = [ "$root_out_dir/{{source_file_part}}" ] | |
| 99 } | |
| 100 | |
| 101 component("base") { | |
| 102 ... | |
| 103 deps = [ "bar" } # Depend on the copy to make sure it runs. | |
| 104 } | |
| 105 ``` | |
| 106 | |
| 107 ## Platform checking | |
| 108 | |
| 109 | *GYP* | *GN* | | |
| 110 |:-------------------------------------|:---------------------| | |
| 111 | `'conditions': [['OS=="win"', {` | `if (is_win) {` | | |
| 112 | `'conditions': [['OS=="linux"', {` | `if (is_linux) {` | | |
| 113 | `'conditions': [['OS=="android"', {` | `if (is_android) {` | | |
| 114 | `'conditions': [['OS=="mac"', {` | `if (is_mac) {` | | |
| 115 | `'conditions': [['OS=="ios"', {` | `if (is_ios) {` | | |
| 116 | `'conditions': [['chromeos==1', {` | `if (is_chromeos) {` | | |
| 117 | |
| 118 ## Typical sources and deps modifications | |
| 119 | |
| 120 ### GYP | |
| 121 | |
| 122 ``` | |
| 123 'sources': [ | |
| 124 'a.cc', | |
| 125 'b.cc', | |
| 126 'c.cc', | |
| 127 ], | |
| 128 'dependencies': [ | |
| 129 '<(DEPTH)/base/base.gyp:foo', | |
| 130 ], | |
| 131 'conditions': [ | |
| 132 ['OS=="win"': { | |
| 133 'sources!': [ | |
| 134 'a.cc', | |
| 135 ], | |
| 136 'sources': [ | |
| 137 'foo.cc', | |
| 138 ], | |
| 139 'dependencies': [ | |
| 140 '<(DEPTH)/base/base.gyp:bar', | |
| 141 ], | |
| 142 }, { | |
| 143 'sources/': [ | |
| 144 ['exclude', '^b\\.cc$'], | |
| 145 ], | |
| 146 }], | |
| 147 ], | |
| 148 ``` | |
| 149 | |
| 150 ### GN | |
| 151 | |
| 152 ``` | |
| 153 sources = [ | |
| 154 "c.cc", | |
| 155 ] | |
| 156 deps = [ | |
| 157 "//base:foo", | |
| 158 ] | |
| 159 | |
| 160 if (is_win) { | |
| 161 sources += [ | |
| 162 "b.cc", | |
| 163 "foo.cc', | |
| 164 ] | |
| 165 deps += [ "//base:bar" ] | |
| 166 } else { | |
| 167 sources += [ "a.cc" ] | |
| 168 } | |
| 169 ``` | |
| 170 | |
| 171 Note that in GN we prefer to only add files when needed, and don't add all of | |
| 172 them at first only to remove them later like in gyp. | |
| 173 | |
| 174 ## Variable mappings | |
| 175 | |
| 176 ### Build configuration | |
| 177 | |
| 178 Build configuration and feature flags are usually global in GYP. In GN | |
| 179 we try to limit global variables and instead put variables used by only | |
| 180 some files into `.gni` files. These files are then imported into your | |
| 181 buildfile by specifying at the top: | |
| 182 | |
| 183 ``` | |
| 184 import("//build/config/features.gni") | |
| 185 | |
| 186 # ... now you can use the variables declared in features.gni. | |
| 187 if (is_tsan) { | |
| 188 # ... | |
| 189 } | |
| 190 if (cld_version == 2) { | |
| 191 # ... | |
| 192 } | |
| 193 ``` | |
| 194 | |
| 195 Other flags only apply to one `BUILD.gn` file and those flags are | |
| 196 declared directly in that file (so other files can't use them). These | |
| 197 places are noted in the table below. | |
| 198 | |
| 199 | *GYP* | *GN*
| *GN import* | | |
| 200 |:------------------------------------------------|:----------------------------
---------------|:-----------------------------------------------| | |
| 201 | `arm_float_abi` | `arm_float_abi`
| `//build/config/arm.gni` | | |
| 202 | `arm_neon` (0/1) | `arm_use_neon` (true/false)
| `//build/config/arm.gni` | | |
| 203 | `arm_neon_optional` (0/1) | `arm_optionally_use_neon` (t
rue/false) | `//build/config/arm.gni` | | |
| 204 | `arm_version` | `arm_version`
| `//build/config/arm.gni` | | |
| 205 | `asan` (0/1) | `is_asan` (true/false)
| `//build/config/sanitizers/sanitizers.gni` | | |
| 206 | `branding` ("Chromium"/"Chrome") | `is_chrome_branded` (true/fa
lse) | `//build/config/chrome_build.gni` | | |
| 207 | `build_for_tool=="tsan"` | `enable_iterator_debugging=f
alse` | (internal to `//build/config/BUILD.gn`) | | |
| 208 | `buildtype` ("Official"/"Dev") | `is_official_build` (true/fa
lse) | `//build/config/chrome_build.gni` | | |
| 209 | `chrome_multiple_dll` (0/1) | `is_multi_dll_chrome` (true/
false) | `//build/config/chrome_build.gni` | | |
| 210 | `clang` (0/1) | `is_clang` (true/false)
| (global) | | |
| 211 | `clang_use_chrome_plugins` (0/1) | `clang_use_chrome_plugins` (
true/false) | (internal to `//build/config/clang/BUILD.gn`) | | |
| 212 | `component` ("shared_library"/"static_library") | `is_component_build` (true/f
alse) | (global) | | |
| 213 | `desktop_linux` (0/1) | `is_desktop_linux` (true/fal
se) | (global) | | |
| 214 | `disable_glibcxx_debug` (0/1) | `enable_iterator_debugging`
(true/false) | (internal to `//build/config/BUILD.gn`) | | |
| 215 | `fastbuild` (0/1/2) | `symbol_level` (2/1/0 — valu
es inverted) | `//build/config/compiler/compiler.gni` | | |
| 216 | `gomadir` | `goma_dir`
| `//build/toolchain/goma.gni` | | |
| 217 | `ios_deployment_target` (string) | `ios_deployment_target`
| `//build/config/ios/ios_sdk.gni` | | |
| 218 | `GYP_MSVS_OVERRIDE_PATH` environment variable | `visual_studio_path`
| `//build/config/win/visual_studio_version.gni` | | |
| 219 | `GYP_MSVS_VERSION` environment variable | (none)
| | | |
| 220 | `ios_sdk_path` | `ios_sdk_path` and `use_ios_
simulator` | `//build/config/ios/ios_sdk.gni` | | |
| 221 | `lsan` (0/1) | `is_lsan` (true/false)
| `//build/config/sanitizers/sanitizers.gni` | | |
| 222 | `mac_sdk_min` | `mac_sdk_min`
| `//build/config/mac/mac_sdk.gni` | | |
| 223 | `mac_sdk_path` | `mac_sdk_path`
| `//build/config/mac/mac_sdk.gni` | | |
| 224 | `mac_sdk` | `mac_sdk_version`
| `//build/config/mac/mac_sdk.gni` | | |
| 225 | `mac_strip_release` | `enable_stripping`
| `//build/config/mac/symbols.gni` | | |
| 226 | `mac_want_real_dsym` | `enable_dsyms`
| `//build/config/mac/symbols.gni` | | |
| 227 | `msan` (0/1) | `is_msan` (true/false)
| `//build/config/sanitizers/sanitizers.gni` | | |
| 228 | `SDKROOT` (Mac) | `sysroot`
| `//build/config/sysroot.gni` | | |
| 229 | `sysroot` | `sysroot`
| `//build/config/sysroot.gni` | | |
| 230 | `target_arch` ("ia32"/"x64"/"arm"/"mipsel") | `target_cpu` ("x86"/"x64"/"a
rm"/"mipsel") | (global) | | |
| 231 | `toolkit_views` (0/1) | `toolkit_views`
| `//build/config/ui.gni` | | |
| 232 | `tsan` (0/1) | `is_tsan` (true/false)
| `//build/config/sanitizers/sanitizers.gni` | | |
| 233 | `windows_sdk_path` | `windows_sdk_path`
| (internal to `//build/config/win/BUILD.gn`) | | |
| 234 | |
| 235 ### Feature flags | |
| 236 | |
| 237 | *GYP* | *GN*
| *GN import* | | |
| 238 |:----------------------------------------|:------------------------------------
-----------|:------------------------------| | |
| 239 | `cld_version` (number) | `cld_version` (number)
| `//build/config/features.gni` | | |
| 240 | `configuration_policy` (0/1) | `enable_configuration_policy` (true/
false) | `//build/config/features.gni` | | |
| 241 | `debug_devtools` (0/1) | `debug_devtools` (true/false)
| `//build/config/features.gni` | | |
| 242 | `disable_ftp_support` (0/1) | `disable_ftp_support` (true/false)
| `//build/config/features.gni` | | |
| 243 | `disable_nacl` (0/1) | `enable_nacl` (true/false)
| `//build/config/features.gni` | | |
| 244 | `enable_app_list` (0/1) | `enable_app_list` (true/false)
| `//build/config/features.gni` | | |
| 245 | `enable_autofill_dialog` (0/1) | `enable_autofill_dialog` (true/false
) | `//build/config/features.gni` | | |
| 246 | `enable_background` (0/1) | `enable_background` (true/false)
| `//build/config/features.gni` | | |
| 247 | `enable_captive_portal_detection` (0/1) | `enable_captive_portal_detection` (t
rue/false) | `//build/config/features.gni` | | |
| 248 | `enable_chromevox_next` (0/1) | `enable_chromevox_next` (true/false)
| `//build/config/features.gni` | | |
| 249 | `enable_extensions` (0/1) | `enable_extensions` (true/false)
| `//build/config/features.gni` | | |
| 250 | `enable_google_now` (0/1) | `enable_google_now` (true/false)
| `//build/config/features.gni` | | |
| 251 | `enable_hidpi` (0/1) | `enable_hidpi` (true/false)
| `//ui/base/ui_features.gni` | | |
| 252 | `enable_managed_users` (0/1) | `enable_managed_users` (true/false)
| `//build/config/features.gni` | | |
| 253 | `enable_mdns` (0/1) | `enable_mdns` (true/false)
| `//build/config/features.gni` | | |
| 254 | `enable_one_click_signin` (0/1) | `enable_one_click_signin` (true/fals
e) | `//chrome/common/features.gni` | | |
| 255 | `enable_pepper_cdms` (0/1) | `enable_pepper_cdms` (true/false)
| `//ppapi/features/features.gni` | | |
| 256 | `enable_plugins` (0/1) | `enable_plugins` (true/false)
| `//build/config/features.gni` | | |
| 257 | `enable_plugin_installation` (0/1) | `enable_plugin_installation` (true/f
alse) | `//build/config/features.gni` | | |
| 258 | `enable_basic_printing` (0/1) | `enable_basic_printing` (true/false)
| `//build/config/features.gni` | | |
| 259 | `enable_print_preview` (0/1) | `enable_print_preview` (true/false)
| `//build/config/features.gni` | | |
| 260 | `enable_rlz` (0/1) | `enable_rlz` (true/false)
| `//build/config/features.gni` | | |
| 261 | `enable_spellcheck` (0/1) | `enable_spellcheck` (true/false)
| `//build/config/features.gni` | | |
| 262 | `enable_session_service` (0/1) | `enable_session_service` (true/false
) | `//build/config/features.gni` | | |
| 263 | `enable_task_manager` (0/1) | `enable_task_manager` (true/false)
| `//build/config/features.gni` | | |
| 264 | `enable_themes` (0/1) | `enable_themes` (true/false)
| `//build/config/features.gni` | | |
| 265 | `enable_webrtc` (0/1) | `enable_webrtc` (true/false)
| `//build/config/features.gni` | | |
| 266 | `image_loader_extension` (0/1) | `enable_image_loader_extension` (tru
e/false) | `//build/config/features.gni` | | |
| 267 | `input_speech` (0/1) | `enable_speech_input` (true/false)
| `//build/config/features.gni` | | |
| 268 | `notifications` (0/1) | `enable_notifications` (true/false)
| `//build/config/features.gni` | | |
| 269 | `ozone_platform_dri` (0/1) | `ozone_platform_dri` (true/false)
| `//build/config/ui.gni` | | |
| 270 | `remoting` (0/1) | `enable_remoting` (true/false)
| `//build/config/features.gni` | | |
| 271 | `safe_browsing` (0/1/2) | `safe_browsing_mode` (0/1/2)
| `//build/config/features.gni` | | |
| 272 | `use_allocator` (`'none'`|`'tcmalloc'`) | `use_allocator` (`"none"`|`"tcmalloc
"`) | (See "Allocator" below) | | |
| 273 | `ui_compositor_image_transport` (0/1) | `ui_compositor_image_transport` (tru
e/false) | `//build/config/ui.gni` | | |
| 274 | `use_ash` (0/1) | `use_ash` (true/false)
| `//build/config/ui.gni` | | |
| 275 | `use_athena` (0/1) | `use_athena` (true/false)
| `//build/config/ui.gni` | | |
| 276 | `use_aura` (0/1) | `use_aura` (true/false)
| `//build/config/ui.gni` | | |
| 277 | `use_cairo` (0/1) | `use_cairo` (true/false)
| `//build/config/ui.gni` | | |
| 278 | `use_cups` (0/1) | `use_cups` (true/false)
| `//build/config/features.gni` | | |
| 279 | `use_dbus` (0/1) | `use_dbus` (true/false)
| `//build/config/features.gni` | | |
| 280 | `use_gconf` (0/1) | `use_gconf` (true/false)
| `//build/config/features.gni` | | |
| 281 | `use_glib` (0/1) | `is_linux` (true/false)
| (global) | | |
| 282 | `use_gnome_keyring` (0/1) | `use_gnome_keyring` (true/false)
| | | |
| 283 | `use_goma` (0/1) | `use_goma` (true/false)
| `//build/toolchain/goma.gni` | | |
| 284 | `use_nss_certs` (0/1) | `use_nss_certs` (true/false)
| `//build/config/crypto.gni` (Many of these conditions can be delete
d, see the "SSL" notes on targets below.) | | |
| 285 | `use_pango` (0/1) | `use_pango` (true/false)
| `//build/config/ui.gni` | | |
| 286 | `use_ozone` (0/1) | `use_ozone` (true/false)
| `//build/config/ui.gni` | | |
| 287 | `use_seccomp_bpf` (0/1) | `use_seccomp_bpf` (true/false)
| `//build/config/features.gni` | | |
| 288 | `use_udev` (0/1) | `use_udev` (true/false)
| `//build/config/features.gni` | | |
| 289 | `use_x11` (0/1) | `use_x11` (true/false)
| `//build/config/ui.gni` | | |
| 290 | `use_xi2_mt` (0/1) | `use_xi2_mt` (true/false)
| `//build/config/ui.gni` | | |
| 291 | `win_use_allocator_shim` (0/1) |
| (See "Allocator" below) | | |
| 292 | |
| 293 ### Common target conversion | |
| 294 | |
| 295 Some targets that lots of projects depend on and how the GN ones | |
| 296 correspond to GYP ones. (This is for commonly-depended-on or weird | |
| 297 targets only, don't add stuff here just because you converted it.) | |
| 298 | |
| 299 | *GYP*
| *GN* | *Notes* (see below) | | |
| 300 |:------------------------------------------------------------------------------
-----|:-----------------------------------------|:---------------------| | |
| 301 | `base/base.gyp:base`
| `//base` | | | |
| 302 | `base/base.gyp:base_i18n`
| `//base:i18n` | | | |
| 303 | `base/base.gyp:run_all_unittests`
| `//base/test:run_all_unittests` | | | |
| 304 | `base/base.gyp:test_support_base`
| `//base/test:test_support` | | | |
| 305 | `base/third_party/dynamic_annotations/dynamic_annotations.gyp:dynamic_annotati
ons` | `//base/third_party/dynamic_annotations` | | | |
| 306 | `build/linux/system.gyp:*` (except nss)
| `//build/config/linux:*` | Linux system targets | | |
| 307 | `build/linux/system.gyp:nss`
| `//crypto:platform` | SSL | | |
| 308 | `net/third_party/nss/ssl.gyp:libssl`
| `//crypto:platform` | SSL | | |
| 309 | `skia/skia.gyp:skia`
| `//skia` | | | |
| 310 | `testing/gmock.gyp:gmock`
| `//testing/gmock` | Secondary tree | | |
| 311 | `testing/gtest.gyp:gtest`
| `//testing/gtest` | Secondary treeo | | |
| 312 | `third_party/icu/icu.gyp:icui18n`
| `//third_party/icu` | Secondary tree, ICU | | |
| 313 | `third_party/icu/icu.gyp:icuuc`
| `//third_party/icu` | Secondary tree, ICU | | |
| 314 | `url/url.gyp:url_lib`
| `//url` || || | |
| 315 | |
| 316 Notes: | |
| 317 | |
| 318 * *ICU:* GN has separate `//third_party/icu:icuuc` and | |
| 319 `//third_party/icu:icui18n` targets just like GYP. You can use these | |
| 320 if you only need one of them. Most targets want both, so GN made a | |
| 321 meta target that's just `//third_party/icu` which you can use that | |
| 322 redirects to both "uc" and "i18n". | |
| 323 | |
| 324 * *Linux system targets:* Generally the names in GN patch the GYP | |
| 325 names for the Linux system-related stuff. However, most of them are | |
| 326 configs instead of actual targets (in GYP they're all targets). For | |
| 327 example, since "x11" is just a list of libraries and include | |
| 328 directories, and includes no sources it's a config that just adds | |
| 329 this configuration to your target. To use a config, do `configs += [ | |
| 330 "//build/config/linux:x11" ]` | |
| 331 | |
| 332 * *Secondary tree:* Some projects are DEPSed in and we want it to look | |
| 333 like a BUILD.gn file is in that directory without checking it in to | |
| 334 the upstream repo. The directory `build/secondary` mirrors the main | |
| 335 tree and is checked for BUILD.gn files if an expected file in the | |
| 336 main tree wasn't found. | |
| 337 | |
| 338 * *SSL:* In GYP there are lots of conditions around NSS vs. OpenSSL | |
| 339 and different platforms that determine which of the different SSL | |
| 340 libraries is linked. In GN, there is a meta-target | |
| 341 `//crypto:platform` that will "do the right thing" according to the | |
| 342 current build platform and flags. Generally its safe to replace any | |
| 343 conditional reference to a SSL library with this one. | |
| 344 | |
| 345 ## Visibility and header file issues | |
| 346 | |
| 347 GN is much more strict about header file checking. You may encounter | |
| 348 errors that your target doesn't depend on the target containing a | |
| 349 certain header file. The most common example is including | |
| 350 `base/macros.h` without having `//base` in your project's dependency | |
| 351 list. The solution is to just add the missing dependency. | |
| 352 | |
| 353 The dependency tree must be a DAG. Some components might share headers | |
| 354 between a number of internal targets that makes adding the "proper" | |
| 355 dependencies impossible. In this case, you can separate out a | |
| 356 `source_set` type target containing just the header(s) in question, and | |
| 357 make the targets that use that header depend on that source set to break | |
| 358 the cycle. | |
| 359 | |
| 360 ## Other stuff | |
| 361 | |
| 362 ### Target conditions | |
| 363 | |
| 364 `target_conditions` are like normal conditions but expanded in a | |
| 365 different phase of GYP. You can generally just convert the conditions | |
| 366 inside and not worry about the `conditions`/`target_conditions` | |
| 367 difference. | |
| 368 | |
| 369 ### xcode_settings | |
| 370 | |
| 371 Some xcode settings are obvious: | |
| 372 | |
| 373 ``` | |
| 374 'xcode_settings': {'OTHER_LDFLAGS': ['-foo']}, | |
| 375 ``` | |
| 376 | |
| 377 Should just expand to: | |
| 378 | |
| 379 ``` | |
| 380 ldflags = [ "-foo" ] | |
| 381 ``` | |
| 382 | |
| 383 Other flags are less obvious: | |
| 384 | |
| 385 ``` | |
| 386 'xcode_settings': { 'GCC_SYMBOLS_PRIVATE_EXTERN': 'NO', }, | |
| 387 ``` | |
| 388 | |
| 389 These all correspond to various flags that get passed to the compiler or | |
| 390 linker. You can use your favorite search engine to see what it | |
| 391 corresponds to, but many of them are not well documented. You can also | |
| 392 search for the string in | |
| 393 [tools/gyp/pylib/gyp/xcode_emulation.py](https://code.google.com/p/chromium/code
search#chromium/src/tools/gyp/pylib/gyp/xcode_emulation.py). GYP uses this file
to decode | |
| 394 the Xcode settings into command line flags for the ninja build. | |
| 395 | |
| 396 ### wexit-time destructors | |
| 397 | |
| 398 Replace | |
| 399 | |
| 400 ``` | |
| 401 'enable_wexit_time_destructors': 1, | |
| 402 ``` | |
| 403 | |
| 404 with | |
| 405 | |
| 406 ``` | |
| 407 configs += [ "//build/config/compiler:wexit_time_destructors" ] | |
| 408 ``` | |
| 409 | |
| 410 ### Chromium code | |
| 411 | |
| 412 In GYP code is "non-Chromium" by default, and you opt into higher warning levels
using: | |
| 413 | |
| 414 ``` | |
| 415 'chromium_code': 1, | |
| 416 ``` | |
| 417 | |
| 418 In GN, all code is Chromium code by default. If you're compiling a | |
| 419 static library that needs more lax warnings, opt out of the | |
| 420 Chromium-code settings with: | |
| 421 | |
| 422 ``` | |
| 423 configs -= [ "//build/config/compiler:chromium_code" ] | |
| 424 configs += [ "//build/config/compiler:no_chromium_code" ] | |
| 425 ``` | |
| 426 | |
| 427 ### -fvisibility | |
| 428 | |
| 429 All symbols in the build have "hidden" visibility by default (this means | |
| 430 that symbols aren't exported from shared libraries, a concept different | |
| 431 than GN's target visibility). If you needed to export all symbols (for a | |
| 432 third party library) by default in GYP you would do: | |
| 433 | |
| 434 ``` | |
| 435 'xcode_settings': [ | |
| 436 'GCC_SYMBOLS_PRIVATE_EXTERN': 'NO', # no -fvisibility=hidden | |
| 437 ], | |
| 438 'cflags!': [ | |
| 439 '-fvisibility=hidden', | |
| 440 ], | |
| 441 ``` | |
| 442 | |
| 443 In GN the equivalent is: | |
| 444 | |
| 445 ``` | |
| 446 if (!is_win) { | |
| 447 configs -= [ "//build/config/gcc:symbol_visibility_hidden" ] | |
| 448 } | |
| 449 ``` | |
| 450 | |
| 451 ### Dependent settings | |
| 452 | |
| 453 In GYP you'll see stuff like this, especially in third-party code. | |
| 454 | |
| 455 ``` | |
| 456 'direct_dependent_settings': { | |
| 457 'include_dirs': [ | |
| 458 '.', # This directory. | |
| 459 '../..', # Root "src" path. | |
| 460 ], | |
| 461 'defines': [ | |
| 462 'FOO', | |
| 463 ], | |
| 464 }, | |
| 465 ``` | |
| 466 | |
| 467 Note that many of the includes are trying to add the root "src" | |
| 468 directory to the include path. This is always present in GN so you can | |
| 469 remove these. | |
| 470 | |
| 471 GYP also requires you to duplicate these settings, once for the target | |
| 472 itself, and once for the direct/all dependent settings. In GN, | |
| 473 public/all dependent configs also apply to the current target so you | |
| 474 only need to specify it once. | |
| 475 | |
| 476 In GN, put the settings in a config (declared above your target), and | |
| 477 then reference that as a public config in your target: | |
| 478 | |
| 479 ``` | |
| 480 config("foo_config") { | |
| 481 include_dirs = [ "." ] | |
| 482 defines = [ "FOO" ] | |
| 483 } | |
| 484 | |
| 485 component("foo") { | |
| 486 ... | |
| 487 public_configs = [ ":foo_config" ] | |
| 488 } | |
| 489 ``` | |
| 490 | |
| 491 Targets that depend on `foo` will now get `foo_config` applied. | |
| 492 | |
| 493 GYP would say `export_dependent_settings` to forward | |
| 494 `direct_dependent_settings` up the dependency chain. In GN, put the | |
| 495 dependency in the `public_deps` section and this will happen | |
| 496 automatically. | |
| 497 | |
| 498 ### MSVS disabled warnings | |
| 499 | |
| 500 In GYP you'll see for third-party code: | |
| 501 | |
| 502 ``` | |
| 503 'msvs_disabled_warnings': [ 4018, 4244, 4267, ], | |
| 504 ``` | |
| 505 | |
| 506 At least half of the warnings in these blocks are already disabled | |
| 507 globally (we added more global ones later). From the command line, do: | |
| 508 | |
| 509 ``` | |
| 510 $ cd src/build/config | |
| 511 $ git grep 4018 | |
| 512 compiler/BUILD.gn: "/wd4018", # Comparing signed and unsigned values. | |
| 513 ``` | |
| 514 | |
| 515 tells us that warning 4018 is already disabled globally from the | |
| 516 `default_warning_flags` variable in `//build/config/compiler`, and the same | |
| 517 for 4244. So ignore these. | |
| 518 | |
| 519 Always comment what the warning is. Use your favorite search engine and | |
| 520 type "vc warning 4267" to look it up. You'll end up with: | |
| 521 | |
| 522 ``` | |
| 523 if (is_win) { | |
| 524 cflags += [ | |
| 525 "/wd4267", # Conversion from size_t to 'type'. | |
| 526 ] | |
| 527 } | |
| 528 ``` | |
| 529 | |
| 530 (Use `=` instead of `+=` is you haven't already defined a `cflags` variable.) | |
| 531 | |
| 532 ### Mac frameworks | |
| 533 | |
| 534 GN knows to convert `.framework` files in the `libs` list to the right | |
| 535 thing on Mac. You don't need to specify the directories either. So | |
| 536 convert this: | |
| 537 | |
| 538 ``` | |
| 539 'link_settings': { | |
| 540 'libraries': [ | |
| 541 '$(SDKROOT)/System/Library/Frameworks/Accelerate.framework', | |
| 542 ], | |
| 543 }, | |
| 544 ``` | |
| 545 | |
| 546 to this: | |
| 547 | |
| 548 ``` | |
| 549 libs = [ "Accelerate.framework" ] | |
| 550 ``` | |
| 551 | |
| 552 ### hard_dependency | |
| 553 | |
| 554 GYP code sometimes sets | |
| 555 | |
| 556 ``` | |
| 557 'hard_dependency': 1, | |
| 558 ``` | |
| 559 | |
| 560 to indicate that the current target must be build before its dependents. | |
| 561 GN can deduce this internally, so you can ignore this directive. | |
| 562 | |
| 563 ### Allocator | |
| 564 | |
| 565 GYP has `win_use_allocator_shim` and `use_allocator`. In GN, these are | |
| 566 merged into `use_allocator` which is defined in | |
| 567 `//build/config/allocator.gni`. _However_ you should almost never need | |
| 568 to use this flag. The `//base/allocator` target will change depending on | |
| 569 the current allocator flag, so you can unconditionally depend on this | |
| 570 target to pick up the current build defaults. | |
| 571 | |
| 572 This: | |
| 573 | |
| 574 ``` | |
| 575 ['use_allocator!='none'', { | |
| 576 'dependencies': [ '../base/allocator/allocator.gyp:allocator' ] | |
| 577 }], | |
| 578 ['win_use_allocator_shim==1', { | |
| 579 'dependencies': [ '<(allocator_target)' ], | |
| 580 }], | |
| 581 ``` | |
| 582 | |
| 583 Becomes: | |
| 584 | |
| 585 ``` | |
| 586 deps = [ "//base/allocator" ] | |
| 587 ``` | |
| 588 | |
| 589 As in GYP, the allocator should only be depended on by executables (and | |
| 590 tests). Libraries should not set the allocator. | |
| 591 | |
| 592 ### optimize: max | |
| 593 | |
| 594 In Gyp: | |
| 595 | |
| 596 ``` | |
| 597 'optimize': 'max', | |
| 598 ``` | |
| 599 | |
| 600 only affects Windows and will optimize for speed rather than size. To | |
| 601 get the same behavior in GN, do: | |
| 602 | |
| 603 ``` | |
| 604 if (!is_debug && is_win) { | |
| 605 configs -= [ "//build/config/compiler:default_optimization" ] | |
| 606 configs += [ "//build/config/compiler:optimize_max" ] | |
| 607 } | |
| 608 ``` | |
| 609 | |
| 610 The `is_win` check is needed because the `optimize_max` config also | |
| 611 affects Posix systems. Some components might additionally specify `-O2` | |
| 612 on Posix further optimize, in which case you can remove the `is_win` | |
| 613 check. | |
| 614 | |
| 615 ### Protobufs | |
| 616 | |
| 617 ``` | |
| 618 import("//third_party/protobuf/proto_library.gni") | |
| 619 | |
| 620 proto_library("myproto") { | |
| 621 sources = [ "foo.proto" ] | |
| 622 } | |
| 623 ``` | |
| 624 | |
| 625 See the `third_party/protobuf/proto_library.gni` file for full | |
| 626 documentation and extra flags. | |
| 627 | |
| 628 ### Java stuff | |
| 629 | |
| 630 JNI generator in GYP: | |
| 631 | |
| 632 ``` | |
| 633 { | |
| 634 'target_name': 'foo_headers', | |
| 635 'type': 'none', | |
| 636 'sources': [ <java files> ] | |
| 637 'variables': { 'jni_gen_package': 'foobar' } | |
| 638 'includes': [ 'build/jni_generator.gypi' ] | |
| 639 } | |
| 640 ``` | |
| 641 | |
| 642 JNI generator in GN: | |
| 643 | |
| 644 ``` | |
| 645 # At top of file: | |
| 646 if (is_android) { | |
| 647 import("//build/config/android/rules.gni") | |
| 648 } | |
| 649 | |
| 650 # Later: | |
| 651 if (is_android) { | |
| 652 generate_jni("foo_headers") { | |
| 653 sources = [ <java files> ] | |
| 654 jni_package = "foobar" | |
| 655 } | |
| 656 } | |
| 657 ``` | |
| 658 | |
| 659 ### Grit | |
| 660 | |
| 661 ``` | |
| 662 import("//tools/grit/grit_rule.gni") | |
| 663 | |
| 664 grit("resources") { | |
| 665 source = "my_resources.grd" | |
| 666 } | |
| 667 ``` | |
| 668 | |
| 669 See `src/build/secondary/tools/grit/grit_rule.gni` for more documentation. | |
| 670 | |
| 671 ### Mojo | |
| 672 | |
| 673 ``` | |
| 674 import("//mojo/public/tools/bindings/mojom.gni") | |
| 675 | |
| 676 mojom("mojo_bindings") { | |
| 677 sources = [ | |
| 678 "foo.mojom", | |
| 679 ] | |
| 680 } | |
| 681 ``` | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2505133004:
Remove the GN cookbook document. (Closed)
