migrate GN docs from the wiki to the repo.

tools/gn/docs/cookbook.md

+# 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",
+  ]
+}
+```