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