Index: tools/gn/docs/cookbook.md |
diff --git a/tools/gn/docs/cookbook.md b/tools/gn/docs/cookbook.md |
new file mode 100644 |
index 0000000000000000000000000000000000000000..94788a6d5fc13b998fe7b7a02c2e6ff728025258 |
--- /dev/null |
+++ b/tools/gn/docs/cookbook.md |
@@ -0,0 +1,653 @@ |
+# GYP->GN Conversion Cookbook |
+ |
+[TOC] |
+ |
+## Targets |
+ |
+| *GYP* | *GN* | |
+|:-------------------------------------------------|:---------------------------------------------------| |
+| `'type': 'static_library', 'name': 'foo',` | `static_library("foo") {` or `source_set("foo") {` | |
+| `'type': 'shared_library', 'name': 'foo',` | `shared_library("foo") {` | |
+| `'type': '<(component)', 'name': 'foo',` | `component("foo") {` | |
+| `'type': 'executable', 'name': 'foo',` | `executable("foo") {` | |
+| `'type': '<(gtest_target_type)', 'name': 'foo',` | `test("foo") {` | |
+| `'type': 'none', 'name': 'foo',` | `group("foo") {` | |
+ |
+### Note on static libraries |
+ |
+A source\_set is basically a transparent static\_library. The source files |
+are compiled with the given options but not linked into anything. |
+Targets that depend on a source set get the source set's object files |
+linked into it. This saves the overhead of creating a static library on |
+disk, avoids weird linker issues when a static library has no source |
+files, and you can link source sets into shared libraries and have |
+symbols exported from the shared library. |
+ |
+The last issue is a cause of a lot of headaches in the GYP build. If you |
+annotate a symbol as exported (i.e. `BASE_EXPORT`) then you can't have |
+it in a file that goes into a static library because the function might |
+be [http://blogs.msdn.com/b/oldnewthing/archive/2014/03/21/10509670.aspx |
+stripped out] if it's not called from within the static library. This |
+prevents composing components of static libraries and exporting their |
+symbols. A source set avoids this issue and `EXPORT` has the desired |
+meaning of "export from the component this gets linked into" with no |
+surprising dead code stripping behavior. |
+ |
+A disadvantage of source sets is that if an object file is completely |
+unused, it will still be linked into the result, which is not the case |
+for static libraries. A few places in the build depend on this behavior |
+(deliberately or accidentally). In general, small libraries that we |
+expect to be entirely used, test helpers, etc. can be source sets. There |
+is slightly less risk of subtle issues if you keep static libraries |
+static libraries, however. |
+ |
+### Actions |
+ |
+GYP |
+ |
+``` |
+{ |
+ 'action_name': 'foo', |
+ 'inputs': [ 'bar.py' ], |
+ 'outputs': [ '<(SHARED_INTERMEDIATE_DIR)/bar.out' ], |
+ 'action': ['python', 'bar.py', '--la_dee_da' ], |
+}, |
+``` |
+ |
+Unlike GYP, where an action is a part of a target, GN actions are |
+separate targets that you then depend on via deps from other targets: |
+ |
+``` |
+action("foo") { |
+ script = "bar.py" |
+ outputs = [ "$target_gen_dir/bar.out" ] |
+ args = [ "--la_dee_da" ] |
+} |
+ |
+executable('foo.exe') { |
+ ... |
+ deps = [ ":foo" ] # Depend on the action to make sure it runs. |
+} |
+``` |
+ |
+Rules in GYP become `action_foreach` in GN which work like actions but |
+iterate over a set of sources. |
+ |
+## Platform checking |
+ |
+| *GYP* | *GN* | |
+|:-------------------------------------|:---------------------| |
+| `'conditions': [['OS=="win"', {` | `if (is_win) {` | |
+| `'conditions': [['OS=="linux"', {` | `if (is_linux) {` | |
+| `'conditions': [['OS=="android"', {` | `if (is_android) {` | |
+| `'conditions': [['OS=="mac"', {` | `if (is_mac) {` | |
+| `'conditions': [['OS=="ios"', {` | `if (is_ios) {` | |
+| `'conditions': [['chromeos==1', {` | `if (is_chromeos) {` | |
+ |
+## Typical sources and deps modifications |
+ |
+### GYP |
+ |
+``` |
+'sources': [ |
+ 'a.cc', |
+ 'b.cc', |
+], |
+'dependencies': [ |
+ '<(DEPTH)/base/base.gyp:foo', |
+], |
+'conditions': [ |
+ ['OS=="win"': { |
+ 'sources!': [ |
+ 'a.cc', |
+ ], |
+ 'sources': [ |
+ 'foo.cc', |
+ ], |
+ 'dependencies': [ |
+ '<(DEPTH)/base/base.gyp:bar', |
+ ], |
+ }, { |
+ 'sources/': [ |
+ ['exclude', '^b\\.cc$'], |
+ ], |
+ }], |
+], |
+``` |
+ |
+### GN |
+ |
+``` |
+sources = [ |
+ "a.cc", |
+ "b.cc", |
+] |
+deps = [ |
+ "//base:foo", |
+] |
+ |
+if (is_win) { |
+ sources -= [ "a.cc" ] |
+ sources += [ "foo.cc" ] |
+ deps += [ "//base:bar" ] |
+} else { |
+ sources -= [ "b.cc" ] |
+} |
+``` |
+ |
+## Variable mappings |
+ |
+### Build configuration |
+ |
+Build configuration and feature flags are usually global in GYP. In GN |
+we try to limit global variables and instead put variables used by only |
+some files into `.gni` files. These files are then imported into your |
+buildfile by specifying at the top: |
+ |
+``` |
+import("//build/config/features.gni") |
+ |
+# ... now you can use the variables declared in features.gni. |
+if (is_tsan) { |
+ # ... |
+} |
+if (cld_version == 2) { |
+ # ... |
+} |
+``` |
+ |
+Other flags only apply to one `BUILD.gn` file and those flags are |
+declared directly in that file (so other files can't use them). These |
+places are noted in the table below. |
+ |
+| *GYP* | *GN* | *GN import* | |
+|:------------------------------------------------|:-------------------------------------------|:-----------------------------------------------| |
+| `android_src` | `android_src` | `//build/config/android/config.gni` | |
+| `android_webview_build` (0/1) | `is_android_webview_build` (true/false) | `//build/config/android/config.gni` | |
+| `arm_float_abi` | `arm_float_abi` | `//build/config/arm.gni` | |
+| `arm_neon` (0/1) | `arm_use_neon` (true/false) | `//build/config/arm.gni` | |
+| `arm_neon_optional` (0/1) | `arm_optionally_use_neon` (true/false) | `//build/config/arm.gni` | |
+| `arm_version` | `arm_version` | `//build/config/arm.gni` | |
+| `asan` (0/1) | `is_asan` (true/false) | (global) | |
+| `branding` ("Chromium"/"Chrome"") | `is_chrome_branded` (true/false) | (global) | |
+| `build_for_tool=="drmemory"` | `disable_iterator_debugging` (true/false) | (internal to `//build/config/BUILD.gn`) | |
+| `build_for_tool=="tsan"` | `disable_iterator_debugging` (true/false) | (internal to `//build/config/BUILD.gn`) | |
+| `buildtype` ("Official"/"Dev") | `is_official_build` (true/false) | (global) | |
+| `clang` (0/1) | `is_clang` (true/false) | (global) | |
+| `clang_use_chrome_plugins` (0/1) | `clang_use_chrome_plugins` (true/false) | (internal to `//build/config/clang/BUILD.gn`) | |
+| `component` ("shared_library"/"static_library") | `is_component_build` (true/false) | (global) | |
+| `desktop_linux` (0/1) | `is_desktop_linux` (true/false) | (global) | |
+| `disable_glibcxx_debug` (0/1) | `disable_iterator_debugging` (true/false) | (internal to `//build/config/BUILD.gn`) | |
+| `fastbuild` (0/1/2) | `symbol_level` (2/1/0 — values inverted) | (global) | |
+| `gomadir` | `goma_dir` | `//build/toolchain/goma.gni` | |
+| `ios_deployment_target` (string) | `ios_deployment_target` | `//build/config/ios/ios_sdk.gni` | |
+| `GYP_MSVS_OVERRIDE_PATH` environment variable | `visual_studio_path` | `//build/config/win/visual_studio_version.gni` | |
+| `GYP_MSVS_VERSION` environment variable | (none) | | |
+| `ios_sdk_path` | `ios_sdk_path` and `use_ios_simulator` | `//build/config/ios/ios_sdk.gni` | |
+| `lsan` (0/1) | `is_lsan` (true/false) | (global) | |
+| `mac_sdk_min` | `mac_sdk_min` | `//build/config/mac/mac_sdk.gni` | |
+| `mac_sdk_path` | `mac_sdk_path` | `//build/config/mac/mac_sdk.gni` | |
+| `mac_sdk` | `mac_sdk_version` | `//build/config/mac/mac_sdk.gni` | |
+| `msan` (0/1) | `is_msan` (true/false) | (global) | |
+| `SDKROOT` (Mac) | `sysroot` | `//build/config/sysroot.gni` | |
+| `sysroot` | `sysroot` | `//build/config/sysroot.gni` | |
+| `target_arch` ("ia32"/"x64"/"arm"/"mipsel") | `target_arch` ("x86"/"x64"/"arm"/"mipsel") | (global) | |
+| `toolkit_views` (0/1) | `toolkit_views` | `//build/config/ui.gni` | |
+| `tsan` (0/1) | `is_tsan` (true/false) | (global) | |
+| `windows_sdk_path` | `windows_sdk_path` | (internal to `//build/config/win/BUILD.gn`) | |
+ |
+### Feature flags |
+ |
+| *GYP* | *GN* | *GN import* | |
+|:----------------------------------------|:-----------------------------------------------|:------------------------------| |
+| `cld_version` (number) | `cld_version` (number) | `//build/config/features.gni` | |
+| `configuration_policy` (0/1) | `enable_configuration_policy` (true/false) | `//build/config/features.gni` | |
+| `debug_devtools` (0/1) | `debug_devtools` (true/false) | `//build/config/features.gni` | |
+| `disable_ftp_support` (0/1) | `disable_ftp_support` (true/false) | `//build/config/features.gni` | |
+| `disable_nacl` (0/1) | `enable_nacl` (true/false) | `//build/config/features.gni` | |
+| `enable_app_list` (0/1) | `enable_app_list` (true/false) | `//build/config/features.gni` | |
+| `enable_autofill_dialog` (0/1) | `enable_autofill_dialog` (true/false) | `//build/config/features.gni` | |
+| `enable_background` (0/1) | `enable_background` (true/false) | `//build/config/features.gni` | |
+| `enable_captive_portal_detection` (0/1) | `enable_captive_portal_detection` (true/false) | `//build/config/features.gni` | |
+| `enable_chromevox_next` (0/1) | `enable_chromevox_next` (true/false) | `//build/config/features.gni` | |
+| `enable_extensions` (0/1) | `enable_extensions` (true/false) | `//build/config/features.gni` | |
+| `enable_google_now` (0/1) | `enable_google_now` (true/false) | `//build/config/features.gni` | |
+| `enable_hidpi` (0/1) | `enable_hidpi` (true/false) | `//build/config/ui.gni` | |
+| `enable_managed_users` (0/1) | `enable_managed_users` (true/false) | `//build/config/features.gni` | |
+| `enable_mdns` (0/1) | `enable_mdns` (true/false) | `//build/config/features.gni` | |
+| `enable_one_click_signin` (0/1) | `enable_one_click_signin` (true/false) | `//build/config/features.gni` | |
+| `enable_pepper_cdms` (0/1) | `enable_pepper_cdms` (true/false) | `//build/config/features.gni` | |
+| `enable_plugins` (0/1) | `enable_plugins` (true/false) | `//build/config/features.gni` | |
+| `enable_plugin_installation` (0/1) | `enable_plugin_installation` (true/false) | `//build/config/features.gni` | |
+| `enable_basic_printing` (0/1) | `enable_basic_printing` (true/false) | `//build/config/features.gni` | |
+| `enable_print_preview` (0/1) | `enable_print_preview` (true/false) | `//build/config/features.gni` | |
+| `enable_rlz` (0/1) | `enable_rlz` (true/false) | `//build/config/features.gni` | |
+| `enable_service_discovery` (0/1) | `enable_service_discovery` (true/false) | `//build/config/features.gni` | |
+| `enable_spellcheck` (0/1) | `enable_spellcheck` (true/false) | `//build/config/features.gni` | |
+| `enable_session_service` (0/1) | `enable_session_service` (true/false) | `//build/config/features.gni` | |
+| `enable_settings_app` (0/1) | `enable_settings_app` (true/false) | `//build/config/features.gni` | |
+| `enable_task_manager` (0/1) | `enable_task_manager` (true/false) | `//build/config/features.gni` | |
+| `enable_themes` (0/1) | `enable_themes` (true/false) | `//build/config/features.gni` | |
+| `enable_webrtc` (0/1) | `enable_webrtc` (true/false) | `//build/config/features.gni` | |
+| `enable_wifi_bootstrapping` (0/1) | `enable_wifi_bootstrapping` (true/false) | `//build/config/features.gni` | |
+| `image_loader_extension` (0/1) | `enable_image_loader_extension` (true/false) | `//build/config/features.gni` | |
+| `input_speech` (0/1) | `enable_speech_input` (true/false) | `//build/config/features.gni` | |
+| `notifications` (0/1) | `enable_notifications` (true/false) | `//build/config/features.gni` | |
+| `ozone_platform_dri` (0/1) | `ozone_platform_dri` (true/false) | `//build/config/ui.gni` | |
+| `remoting` (0/1) | `enable_remoting` (true/false) | `//build/config/features.gni` | |
+| `safe_browsing` (0/1/2) | `safe_browsing_mode` (0/1/2) | `//build/config/features.gni` | |
+| `use_allocator` (`'none'`|`'tcmalloc'`) | `use_allocator` (`"none"`|`"tcmalloc"`) | (See "Allocator" below) | |
+| `ui_compositor_image_transport` (0/1) | `ui_compositor_image_transport` (true/false) | `//build/config/ui.gni` | |
+| `use_ash` (0/1) | `use_ash` (true/false) | `//build/config/ui.gni` | |
+| `use_athena` (0/1) | `use_athena` (true/false) | `//build/config/ui.gni` | |
+| `use_aura` (0/1) | `use_aura` (true/false) | `//build/config/ui.gni` | |
+| `use_brlapi` (0/1) | `use_brlapi` (true/false) | `//build/config/features.gni` | |
+| `use_cairo` (0/1) | `use_cairo` (true/false) | `//build/config/ui.gni` | |
+| `use_clipboard_aurax11` (0/1) | `use_aura && use_x11` | | |
+| `use_cups` (0/1) | `use_cups` (true/false) | `//build/config/features.gni` | |
+| `use_dbus` (0/1) | `use_dbus` (true/false) | `//build/config/features.gni` | |
+| `use_gconf` (0/1) | `use_gconf` (true/false) | `//build/config/features.gni` | |
+| `use_glib` (0/1) | `is_linux` (true/false) | (global) | |
+| `use_gnome_keyring` (0/1) | `is_desktop_linux` (true/false) | | |
+| `use_goma` (0/1) | `use_goma` (true/false) | `//build/toolchain/goma.gni` | |
+| `use_nss` (0/1) | `use_nss_certs` (true/false) | `//build/config/crypto.gni` (Many of these conditions can be deleted, see the "SSL" notes on targets below.) | |
+| `use_openssl` (0/1) | `use_openssl` (true/false) | `//build/config/crypto.gni` (Many of these conditions can be deleted, see the "SSL" notes on targets below.) | |
+| `use_pango` (0/1) | `use_pango` (true/false) | `//build/config/ui.gni` | |
+| `use_ozone` (0/1) | `use_ozone` (true/false) | `//build/config/ui.gni` | |
+| `use_seccomp_bpf` (0/1) | `use_seccomp_bpf` (true/false) | `//build/config/features.gni` | |
+| `use_udev` (0/1) | `use_udev` (true/false) | `//build/config/features.gni` | |
+| `use_x11` (0/1) | `use_x11` (true/false) | `//build/config/ui.gni` | |
+| `use_xi2_mt` (0/1) | `use_xi2_mt` (true/false) | `//build/config/ui.gni` | |
+| `win_pdf_metafile_for_printing` (0/1) | `win_pdf_metafile_for_printing` (true/false) | `//build/config/features.gni` | |
+| `win_use_allocator_shim` (0/1) | | (See "Allocator" below) | |
+ |
+### Common target conversion |
+ |
+Some targets that lots of projects depend on and how the GN ones |
+correspond to GYP ones. (This is for commonly-depended-on or weird |
+targets only, don't add stuff here just because you converted it.) |
+ |
+| *GYP* | *GN* | *Notes* (see below) | |
+|:-----------------------------------------------------------------------------------|:-----------------------------------------|:---------------------| |
+| `base/base.gyp:base` | `//base` | | |
+| `base/base.gyp:base_i18n` | `//base:i18n` | | |
+| `base/base.gyp:run_all_unittests` | `//base/test:run_all_unittests` | | |
+| `base/base.gyp:test_support_base` | `//base/test:test_support` | | |
+| `base/third_party/dynamic_annotations/dynamic_annotations.gyp:dynamic_annotations` | `//base/third_party/dynamic_annotations` | | |
+| `build/linux/system.gyp:*` (except ssl) | `//build/config/linux:*` | Linux system targets | |
+| `build/linux/system.gyp:ssl` | `//crypto:platform` | SSL | |
+| `net/third_party/nss/ssl.gyp:libssl` | `//crypto:platform` | SSL | |
+| `skia/skia.gyp:skia` | `//skia` | | |
+| `testing/gmock.gyp:gmock` | `//testing/gmock` | Secondary tree | |
+| `testing/gtest.gyp:gtest` | `//testing/gtest` | Secondary treeo | |
+| `third_party/icu/icu.gyp:icui18n` | `//third_party/icu` | Secondary tree, ICU | |
+| `third_party/icu/icu.gyp:icuuc` | `//third_party/icu` | Secondary tree, ICU | |
+| `url/url.gyp:url_lib` | `//url` || || |
+ |
+Notes: |
+ |
+ * *ICU:* GN has separate `//third_party/icu:icuuc` and |
+ `//third_party/icu:icui18n` targets just like GYP. You can use these |
+ if you only need one of them. Most targets want both, so GN made a |
+ meta target that's just `//third_party/icu` which you can use that |
+ redirects to both "uc" and "i18n". |
+ |
+ * *Linux system targets:* Generally the names in GN patch the GYP |
+ names for the Linux system-related stuff. However, most of them are |
+ configs instead of actual targets (in GYP they're all targets). For |
+ example, since "x11" is just a list of libraries and include |
+ directories, and includes no sources it's a config that just adds |
+ this configuration to your target. To use a config, do `configs += [ |
+ "//build/config/linux:x11" ]` |
+ |
+ * *Secondary tree:* Some projects are DEPSed in and we want it to look |
+ like a BUILD.gn file is in that directory without checking it in to |
+ the upstream repo. The directory `build/secondary` mirrors the main |
+ tree and is checked for BUILD.gn files if an expected file in the |
+ main tree wasn't found. |
+ |
+ * *SSL:* In GYP there are lots of conditions around NSS vs. OpenSSL |
+ and different platforms that determine which of the different SSL |
+ libraries is linked. In GN, there is a meta-target |
+ `//crypto:platform` that will "do the right thing" according to the |
+ current build platform and flags. Generally its safe to replace any |
+ conditional reference to a SSL library with this one. |
+ |
+## Visibility and header file issues |
+ |
+GN is much more strict about header file checking. You may encounter |
+errors that your target doesn't depend on the target containing a |
+certain header file. The most common example is including |
+`base/basictypes.h` without having `//base` in your project's dependency |
+list. The solution is to just add the missing dependency. |
+ |
+The dependency tree must be a DAG. Some components might share headers |
+between a number of internal targets that makes adding the "proper" |
+dependencies impossible. In this case, you can separate out a |
+`source_set` type target containing just the header(s) in question, and |
+make the targets that use that header depend on that source set to break |
+the cycle. |
+ |
+## Other stuff |
+ |
+### Target conditions |
+ |
+`target_conditions` are like normal conditions but expanded in a |
+different phase of GYP. You can generally just convert the conditions |
+inside and not worry about the `conditions`/`target_conditions` |
+difference. |
+ |
+### xcode_settings |
+ |
+Some xcode settings are obvious: |
+ |
+``` |
+ 'xcode_settings': {'OTHER_LDFLAGS': ['-foo']}, |
+``` |
+ |
+Should just expand to: |
+ |
+``` |
+ ldflags = [ "-foo" ] |
+``` |
+ |
+Other flags are less obvious: |
+ |
+``` |
+ 'xcode_settings': { 'GCC_SYMBOLS_PRIVATE_EXTERN': 'NO', }, |
+``` |
+ |
+These all correspond to various flags that get passed to the compiler or |
+linker. You can use your favorite search engine to see what it |
+corresponds to, but many of them are not well documented. You can also |
+search for the string in |
+[https://code.google.com/p/chromium/codesearch#chromium/src/tools/gyp/pylib/gyp/xcode_emulation.py |
+tools/gyp/pylib/gyp/xcode_emulation.py]. GYP uses this file to decode |
+the Xcode settings into command line flags for the ninja build. |
+ |
+### wexit-time destructors |
+ |
+Replace |
+ |
+``` |
+'enable_wexit_time_destructors': 1, |
+``` |
+ |
+with |
+ |
+``` |
+configs += [ "//build/config/compiler:wexit_time_destructors" ] |
+``` |
+ |
+### Chromium code |
+ |
+In GYP code is "non-Chromium" by default, and you opt into higher warning levels using: |
+ |
+``` |
+'chromium_code': 1, |
+``` |
+ |
+In GN, all code is Chromium code by default. If you're compiling a |
+static library that needs more lax warnings, opt out of the |
+Chromium-code settings with: |
+ |
+``` |
+configs -= [ "//build/config/compiler:chromium_code" ] |
+configs += [ "//build/config/compiler:no_chromium_code" ] |
+``` |
+ |
+### -fvisibility |
+ |
+All symbols in the build have "hidden" visibility by default (this means |
+that symbols aren't exported from shared libraries, a concept different |
+than GN's target visibility). If you needed to export all symbols (for a |
+third party library) by default in GYP you would do: |
+ |
+``` |
+'xcode_settings': [ |
+ 'GCC_SYMBOLS_PRIVATE_EXTERN': 'NO', # no -fvisibility=hidden |
+], |
+'cflags!': [ |
+ '-fvisibility=hidden', |
+], |
+``` |
+ |
+In GN the equivalent is: |
+ |
+``` |
+if (!is_win) { |
+ configs -= [ "//build/config/gcc:symbol_visibility_hidden" ] |
+} |
+``` |
+ |
+### Dependent settings |
+ |
+In GYP you'll see stuff like this, especially in third-party code. |
+ |
+``` |
+'direct_dependent_settings': { |
+ 'include_dirs': [ |
+ '.', # This directory. |
+ '../..', # Root "src" path. |
+ ], |
+ 'defines': [ |
+ 'FOO', |
+ ], |
+}, |
+``` |
+ |
+Note that many of the includes are trying to add the root "src" |
+directory to the include path. This is always present in GN so you can |
+remove these. |
+ |
+GYP also requires you do duplicate these settings, once for the target |
+itself, and once for the direct/all dependent settings. In GN, |
+public/all dependent configs also apply to the current target so you |
+only need to specify it once. |
+ |
+In GN, put the settings in a config (declared above your target), and |
+then reference that as a public config in your target: |
+ |
+``` |
+config("foo_config") { |
+ include_dirs = [ "." ] |
+ defines = [ "FOO" ] |
+} |
+ |
+component("foo") { |
+ ... |
+ public_configs = [ ":foo_config" ] |
+} |
+``` |
+ |
+Targets that depend on `foo` will now get `foo_config` applied. |
+ |
+GYP would say `export_dependent_settings` to forward |
+`direct_dependent_settings` up the dependency chain. In GN, put the |
+dependency in the `public_deps` section and this will happen |
+automatically. |
+ |
+### MSVS disabled warnings |
+ |
+In GYP you'll see for third-party code: |
+ |
+``` |
+'msvs_disabled_warnings': [ 4018, 4244, 4267, ], |
+``` |
+ |
+At least half of the warnings in these blocks are already disabled |
+globally (we added more global ones later). From the command line, do: |
+ |
+``` |
+$ cd src/build/config |
+$ git grep 4018 |
+compiler/BUILD.gn: "/wd4018", # Comparing signed and unsigned values. |
+``` |
+ |
+tells us that warning 4018 is already disabled globally from the |
+`//build/config/compiler:default_warnings` config, and the same for |
+4244. So ignore these. |
+ |
+Always comment what the warning is. Use your favorite search engine and |
+type "vc warning 4267" to look it up. You'll end up with: |
+ |
+``` |
+if (is_win) { |
+ cflags += [ |
+ "/wd4267", # Conversion from size_t to 'type'. |
+ ] |
+} |
+``` |
+ |
+(Use `=` instead of `+=` is you haven't already defined a `cflags` variable.) |
+ |
+### Mac frameworks |
+ |
+GN knows to convert `.framework` files in the `libs` list to the right |
+thing on Mac. You don't need to specify the directories either. So |
+convert this: |
+ |
+``` |
+'link_settings': { |
+ 'libraries': [ |
+ '$(SDKROOT)/System/Library/Frameworks/Accelerate.framework', |
+ ], |
+}, |
+``` |
+ |
+to this: |
+ |
+``` |
+libs = [ "Accelerate.framework" ] |
+``` |
+ |
+### hard_dependency |
+ |
+GYP code sometimes sets |
+ |
+``` |
+ 'hard_dependency': 1, |
+``` |
+ |
+to indicate that the current target must be build before its dependents. |
+GN can deduce this internally, so you can ignore this directive. |
+ |
+### Allocator |
+ |
+GYP has `win_use_allocator_shim` and `use_allocator`. In GN, these are |
+merged into `use_allocator` which is defined in |
+`//build/config/allocator.gni`. _However_ you should almost never need |
+to use this flag. The `//base/allocator` target will change depending on |
+the current allocator flag, so you can unconditionally depend on this |
+target to pick up the current build defaults. |
+ |
+This: |
+ |
+``` |
+ ['use_allocator!='none'', { |
+ 'dependencies': [ '../base/allocator/allocator.gyp:allocator' ] |
+ }], |
+ ['win_use_allocator_shim==1', { |
+ 'dependencies': [ '<(allocator_target)' ], |
+ }], |
+``` |
+ |
+Becomes: |
+ |
+``` |
+ deps = [ "//base/allocator" ] |
+``` |
+ |
+As in GYP, the allocator should only be depended on by executables (and |
+tests). Libraries should not set the allocator. |
+ |
+### optimize: max |
+ |
+In Gyp: |
+ |
+``` |
+'optimize': 'max', |
+``` |
+ |
+only affects Windows and will optimize for speed rather than size. To |
+get the same behavior in GN, do: |
+ |
+``` |
+if (!is_debug && is_win) { |
+ configs -= [ "//build/config/compiler:optimize" ] |
+ configs += [ "//build/config/compiler:optimize_max" ] |
+} |
+``` |
+ |
+The `is_win` check is needed because the `optimize_max` config also |
+affects Posix systems. Some components might additionally specify `-O2` |
+on Posix further optimize, in which case you can remove the `is_win` |
+check. |
+ |
+### Protobufs |
+ |
+``` |
+import("//third_party/protobuf/proto_library.gni") |
+ |
+proto_library("myproto") { |
+ sources = [ "foo.proto" ] |
+} |
+``` |
+ |
+See the `third_party/protobuf/proto_library.gni` file for full |
+documentation and extra flags. |
+ |
+### Java stuff |
+ |
+JNI generator in GYP: |
+ |
+``` |
+{ |
+ 'target_name': 'foo_headers', |
+ 'type': 'none', |
+ 'sources': [ <java files> ] |
+ 'variables': { 'jni_gen_package': 'foobar' } |
+ 'includes': [ 'build/jni_generator.gypi' ] |
+} |
+``` |
+ |
+JNI generator in GN: |
+ |
+``` |
+# At top of file: |
+if (is_android) { |
+ import("//build/config/android/rules.gni") |
+} |
+ |
+# Later: |
+if (is_android) { |
+ generate_jni("foo_headers") { |
+ sources = [ <java files> ] |
+ jni_package = "foobar" |
+ } |
+} |
+``` |
+ |
+### Grit |
+ |
+``` |
+import("//tools/grit/grit_rule.gni") |
+ |
+grit("resources") { |
+ source = "my_resources.grd" |
+} |
+``` |
+ |
+See `src/build/secondary/tools/grit/grit_rule.gni` for more documentation. |
+ |
+### Mojo |
+ |
+``` |
+import("//mojo/public/tools/bindings/mojom.gni") |
+ |
+mojom("mojo_bindings") { |
+ sources = [ |
+ "foo.mojom", |
+ ] |
+} |
+``` |