Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(7)

Unified Diff: tools/gn/docs/cookbook.md

Issue 1052883002: migrate GN docs from the wiki to the repo. (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master
Patch Set: split md_browser out into its own dir Created 5 years, 9 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View side-by-side diff with in-line comments
Download patch
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",
+ ]
+}
+```

Powered by Google App Engine
This is Rietveld 408576698