Migrate GN docs from the wiki to the repo.
Given that Google Code is shutting down, we need to figure out what to do with docs in the wiki. Gitiles (the tree browser for our Git repo) supports rendering markdown files that are checked in to the repo, so one obvious answer is to migrate the GN docs into the repo (and convert them to markdown); this would also make it easier to keep the docs versioned and in sync with the code.
This is a first pass at that. The content is unchanged from the wiki, just converted and manually reformatted to stay within 80 columns where possible (we can't do that for long URLs or wide tables).
R=brettw@chromium.org, scottmg@chromium.org
BUG=468851
Review URL: https://codereview.chromium.org/1052883002
Cr-Original-Commit-Position: refs/heads/master@{#323923}
Cr-Mirrored-From: https://chromium.googlesource.com/chromium/src
Cr-Mirrored-Commit: 12a4235cfacb206ffc7ba27dd14edd970e5b60e0
diff --git a/tools/gn/README.md b/tools/gn/README.md
new file mode 100644
index 0000000..3cf3336
--- /dev/null
+++ b/tools/gn/README.md
@@ -0,0 +1,101 @@
+# What is GN?
+
+GN is a meta-build system that generates [NinjaBuild](NinjaBuild.md)
+files. It's meant to be faster and simpler than GYP. It outputs only
+Ninja build files.
+
+## Why bother with GN?
+
+1. We believe GN files are more readable and more maintainable
+ than GYP files.
+2. GN is fast:
+ * GN is 20x faster than GYP (as of mid November, building 80%
+ of what GYP builds, in one configuration rather than two, takes 500ms
+ on a z620 running Ubuntu Trusty. GYP takes 20 seconds.
+ We see similar speedups on Mac and Windows).
+ * GN supports automatically re-running itself as needed by Ninja
+ as part of the build. This eliminates the need to remember to
+ re-run GN when you change a build file.
+3. GN gives us better tools for enforcing dependencies (see
+ `gn check` and the `visibility`, `public_deps`, and `data_deps`
+ options for some examples).
+4. GN gives us tools for querying the build graph; you can ask
+ "what does X depend on" and "who depends on Y", for example.
+
+## What's the status?
+
+_as of 8 Feb 2015:_
+
+Chrome and most of the major test suites link on Linux and ChromeOS.
+There's probably <1000 objects left to build, in a few test suites and a
+bunch of utillities and helper binaries. We will probably have
+everything converted in another couple weeks.
+
+Chrome also links on Android and Windows, and bringing up the remaining
+test suites should be mostly straightforward. There's some work left to
+enable NaCl on Windows but it should also be straightforward.
+
+Mac and iOS have not progressed much as attention has been focused on
+Linux and Windows; we still need support for bundles and frameworks
+before it can get to parity w/ the other platforms.
+
+## When are you going to be done?
+
+_as of 8 Feb 2015:_
+
+We're currently shooting for having the main developer configurations
+working and usable by the end of March 2015. There will probably be a
+fair amount of verification of flags, bug fixes, etc over the next
+couple months, but hopefully we will be flipping configurations from GYP
+to GN throughout Q2, targeting having everything done by the end of Q2.
+
+## What does "done" mean?
+
+Ideally we're done when all of the GYP files have been deleted from
+Chromium and no one misses them.
+
+We will be "mostly" done when the following are true:
+ * All of the bots maintained by the Chrome infra team for Chromium and
+ downstream of Chromium have been switched to GN. (Upstream projects
+ like Skia and V8 can choose to stay on GYP if they like).
+ * Any developer configurations we care about that don't have bots also
+ work (Generally speaking, we're aiming to not have any of these.
+ * Configurations we care about should have bots to ensure they don't
+ break). We have verified that all of the tests pass. We have
+ verified that the command lines match in the above configurations as
+ much as possible, and we accept any differences. We have reviewed
+ any binary differences that result in the official builds and
+ accepted them. The GN files are the "source of truth" for the
+ build, and normal chromium developers normally do not need to touch
+ GYP files to keep things working. We have replacements for the
+ hybrid "msvs-ninja" and "xcode-ninja" configurations that GYP can
+ currently build.
+
+The difference between "mostly done" and "done" exists to cover any
+issues we haven't yet identified :)
+
+We do not currently plan to support full native XCode or Visual Studio
+generation from GN. It is theoretically possible to support such things,
+so we would at least look at patches adding the functionality.
+
+## How can I help?
+
+Check to see if your targets build under GN yet. If they don't,
+volunteer to help convert them!
+
+_17 Nov 2014. We are updating the stuff we use to track progress. Watch
+this space and chromium-dev@ for more info!_.
+
+## I want more info on GN!
+
+Read these links:
+
+ * [Quick start](docs/quick_start.md)
+ * [FAQ](docs/faq.md)
+ * [GYP conversion cookbook](docs/cookbook.md)
+ * [Language and operation details](docs/language.md)
+ * [Style guide](docs/style_guide.md)
+ * [Cross compiling and toolchains](docs/cross_compiles.md)
+ * [Hacking on GN itself](docs/hacking.md)
+ * [GNStandalone](docs/standalone.md) Standalone GN projects
+ * [UpdateGNBinaries](docs/update_binaries.md) Pushing new binaries
diff --git a/tools/gn/README.txt b/tools/gn/README.txt
deleted file mode 100644
index b7f6051..0000000
--- a/tools/gn/README.txt
+++ /dev/null
@@ -1,11 +0,0 @@
-GN "Generate Ninja"
-
-GN is a meta-build system that generates ninja files. It's meant to be faster
-and simpler than GYP.
-
-Chromium uses binary versions of GN downloaded from Google Cloud Storage during
-gclient runhooks, so that we don't have to worry about bootstrapping a build
-of GN from scratch.
-
-Instructions for how to upload the .sha1 digests of the GN binaries can be
-found at https://code.google.com/p/chromium/wiki/UpdateGNBinaries.
diff --git a/tools/gn/docs/cookbook.md b/tools/gn/docs/cookbook.md
new file mode 100644
index 0000000..94788a6
--- /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",
+ ]
+}
+```
diff --git a/tools/gn/docs/cross_compiles.md b/tools/gn/docs/cross_compiles.md
new file mode 100644
index 0000000..1dc9eca
--- /dev/null
+++ b/tools/gn/docs/cross_compiles.md
@@ -0,0 +1,96 @@
+# How GN handles cross-compiling
+
+## As a GN user
+
+GN has robust support for doing cross compiles and building things for
+multiple architectures in a single build (e.g., to build some things to
+run locally and some things to run on an embedded device). In fact,
+there is no limit on the number of different architectures you can build
+at once; the Chromium build uses at least four in some configurations.
+
+To start, GN has the concepts of a _host_ and a _target_. The host is
+the platform that the build is run on, and the target is the platform
+where the code will actually run (This is different from
+[autotools](http://www.gnu.org/software/automake/manual/html_node/Cross_002dCompilation.html)'
+terminology, but uses the more common terminology for cross
+compiling**).**
+
+(Confusingly, GN also refers to each build artifact -- an executable,
+library, etc. -- as a target. On this page, we will use "target" only to
+refer to the system you want to run your code on, and use "rule" or some
+other synonym to refer to a specific build artifact).
+
+When GN starts up, the `host_os` and `host_cpu` variables are set
+automatically to match the operating system (they can be overridden in
+args files, which can be useful in weird corner cases). The user can
+specify that they want to do a cross-compile by setting either or both
+of `target_os` and `target_cpu`; if they are not set, the build config
+files will usually set them to the host's values, though the Chromium
+build will set target\_cpu to "arm" if target\_os is set to "android").
+
+So, for example, running on an x64 Linux machine:
+
+```
+gn gen out/Default
+```
+
+is equivalent to:
+
+```
+gn gen out/Default --args='target_os="linux" target_cpu="x64"'
+```
+
+To do an 32-bit ARM Android cross-compile, do:
+
+```
+gn gen out/Default --args='target_os="android"'
+```
+
+(We don't have to specify target\_cpu because of the conditionals
+mentioned above).
+
+And, to do a 64-bit MIPS ChromeOS cross-compile:
+
+```
+gn gen out/Default --args='target_os="chromeos" target_cpu="mips64el"'
+```
+
+## As a BUILD.gn author
+
+If you are editing build files outside of the //build directory (i.e.,
+not directly working on toolchains, compiler configs, etc.), generally
+you only need to worry about a few things:
+
+The `current_toolchain`, `current_cpu`, and `current_os` variables
+reflect the settings that are **currently** in effect in a given rule.
+The `is_linux`, `is_win` etc. variables are updated to reflect the
+current settings, and changes to `cflags`, `ldflags` and so forth also
+only apply to the current toolchain and the current thing being built.
+
+You can also refer to the `target_cpu` and `target_os` variables. This
+is useful if you need to do something different on the host depending on
+which target\_arch is requested; the values are constant across all
+toolchains. You can do similar things for the `host_cpu` and `host_os`
+variables, but should generally never need to.
+
+By default, dependencies listed in the `deps` variable of a rule use the
+same (currently active) toolchain. You may specify a different toolchain
+using the `foo(bar)` label notation as described in
+[GNLanguage#Labels](GNLanguage#Labels.md).
+
+## As a //build/config or //build/toolchain author
+
+As described in
+[GNLanguage#Overall\_build\_flow](GNLanguage#Overall_build_flow.md), the
+`default_toolchain` is declared in the //build/config/BUILDCONFIG.gn
+file. Usually the default\_toolchain should be the toolchain for the
+target\_os and target\_cpu. The `current_toolchain` reflects the
+toolchain that is currently in effect for a rule.
+
+Be sure you understand the differences between `host_cpu`, `target_cpu`,
+`current_cpu`, and `toolchain_cpu` (and the os equivalents). The first
+two are set as described above. You are responsible for making sure that
+`current_cpu` is set appropriately in your toolchain definitions; if you
+are using the stock templates like `gcc_toolchain` and `msvc_toolchain`,
+that means you are responsible for making sure that `toolchain_cpu` and
+`toolchain_os` are set as appropriate in the template invocations.
diff --git a/tools/gn/docs/faq.md b/tools/gn/docs/faq.md
new file mode 100644
index 0000000..b35fde8
--- /dev/null
+++ b/tools/gn/docs/faq.md
@@ -0,0 +1,124 @@
+# GN Frequently Asked Questions
+
+[TOC]
+
+## How will the build be converted?
+
+We intend to build a second independent build in parallel to the GYP
+build. Previous efforts to generate GYP as an intermediate stage proved
+difficult. There will be some smaller set of bots compiling this build,
+and we'll keep the GN build running on these configurations.
+
+## What is unsupported in GN?
+
+The main features not supported in GN yet are:
+ * Mac bundles
+ * Loadable module (this only matters on Mac where shared library !=
+ lodable module)
+ * Precompiled headers
+
+## Where is the GN documentation?
+
+Rather than on a separate wiki, it is versioned with the tool. Run `gn
+help`. See also the [quick start](quick_start.md) guide and the
+[language and operation details](language.md).
+
+## What is likely to break?
+
+Since common.gypi is not used for GN-generated GYP files, any rules
+there will no longer apply. There is a _lot_ of logic in there for many
+build configurations and various conditions where certain flags should
+or should not be used. Some of these build configurations aren't even
+supported any more. Some are run on other waterfalls or are used by
+individuals manually setting GYP\_DEFINES on their local system.
+
+## Will XCode/Visual Studio still be supported?
+
+They're not supported now.
+
+Long-term, if your use-case is to use Ninja for building but Visual
+Studio or XCode for debugging, there is desire to write a simple wrapper
+around Ninja that lists the files in Visual Studio or XCode format, and
+has a command to run ninja for when you press build. This setup should
+provide the type of interactive debugging experience people want (the
+iOS team currently uses a Ninja/XCode build like this with success).
+
+This project is not staffed. If you're interested, it probably isn't too
+hard. It won't get done unless somebody volunteers. There is a [spec for
+IDE
+integration](https://docs.google.com/document/d/1kwREU99u8GpRammLbbKwrfaDI6WV7nsMAaoF5dcuhOU/edit?usp=sharing).
+
+## I'm weird. Will my uncommon build mode be supported?
+
+One of the main benefits of the build changeover is that it will
+encourage us to refactor the build system. The project has generally not
+been as strict with build complexity and maintenance as we have with
+source code, and a lot of cruft has accumulated.
+
+In most cases, we will want to rethink how build flags are supported. We
+want to be more modular rather than throwing everything in the
+common.gypi equivalent. The bar for additions at this level will be very
+high, and we will need to figure out how to design certain build
+features. If you are interested in some weird configurations, this will
+likely make your life more difficult in the short term, but will
+hopefully bring long-term benefits for everybody.
+
+In some cases, we may decide that the overhead of supporting your build
+for BeOS running on a DEC Alpha is not in the interests of the project.
+There will likely be discussions about where to draw the line, and how
+to allow those who want to do weird things to do them cleanly without
+negatively affecting the rest of the Chromium community.
+
+## I'm only a little bit weird, will my development build flag be supported?
+
+Only if you do it yourself!
+
+Some features have build flags that turn on a debugging mode or switch
+between internal/external builds. This can be supported, but as with
+GYP, your team will have to add an maintain the support.
+
+## I use supplement.gypi, what's the GN equivalent?
+
+Some projects use files called `supplement.gypi` to set build flags. GYP
+looks in each directory under `src` and adds merges these files into the
+build. The model is that then adding something to your gclient to add
+something to your build (e.g `src-internal`) automatically sets flags.
+
+This behavior is fragile and mysterious. Some people get build flags and
+they don't know why. If you remove the entry from your `.gclient` and
+don't remove the directory you'll be stuck on an old version of the
+flags/code and not know why. You can't have builds in the same checkout
+with the corresponding flags on and off. Some people and projects were
+abusing this behavior.
+
+In GN, such things should be done with build arguments (`gn args`) and
+configured on your build directory when you set it up. For some people,
+this will be an extra step. But it is explicit and clear, and you can
+have multiple builds in the same checkout with different flags.
+
+## How do I generate common build variants?
+
+In GN, args go with a build directory rather than being global in the
+environment. To edit the args for your `out/Default` build directory:
+
+```
+gn args out/Default
+```
+
+You can set variables in that file:
+
+ * The default is a debug build. To do a release build add
+ `is_debug = false`
+ * The default is a static build. To do a component build add
+ `is_component_build = true`
+ * The default is a developer build. To do an official build, set
+ `is_official_build = true`
+ * The default is Chromium branding. To do Chrome branding, set
+ `is_chrome_branded = true`
+
+## How do I do cross-compiles?
+
+GN has robust support for doing cross compiles and building things for
+multiple architectures in a single build.
+
+See [GNCrossCompiles](GNCrossCompiles.md) for more info.
diff --git a/tools/gn/docs/hacking.md b/tools/gn/docs/hacking.md
new file mode 100644
index 0000000..ab94b58
--- /dev/null
+++ b/tools/gn/docs/hacking.md
@@ -0,0 +1,23 @@
+# Hacking on the GN binary itself
+
+## Building GN itself
+
+GN is part of the Chromium tree. If you have a Chromium checkout, you
+already have the source and you can do `ninja -C out/Debug gn` to
+build it.
+
+To build gn using gn, run (in the root `src` directory):
+
+```
+gn gen out/Default
+ninja -C out/Default gn
+```
+
+Change `out/Default` as necessary to put the build directory where you
+want.
+
+## Running GN's unit tests
+
+```
+ninja -C out/Default gn_unittests && out/Default/gn_unittests
+```
diff --git a/tools/gn/docs/language.md b/tools/gn/docs/language.md
new file mode 100644
index 0000000..3aabd79
--- /dev/null
+++ b/tools/gn/docs/language.md
@@ -0,0 +1,734 @@
+# GN Language and Operation
+
+[TOC]
+
+## Introduction
+
+This page describes many of the language details and behaviors.
+
+### Use the built-in help!
+
+GN has an extensive built-in help system which provides a reference for
+every function and built-in variable. This page is more high-level.
+
+```
+gn help
+```
+
+### Design philosophy
+
+ * Writing build files should not be a creative endeavour. Ideally two
+ people should produce the same buildfile given the same
+ requirements. There should be no flexibility unless it's absolutely
+ needed. As many things should be fatal errors as possible.
+
+ * The definition should read more like code than rules. I don't want
+ to write or debug Prolog. But everybody on our team can write and
+ debug C++ and Python.
+
+ * The build language should be opinionated as to how the build should
+ work. It should not necessarily be easy or even possible to express
+ arbitrary things. We should be changing source and tooling to make
+ the build simpler rather than making everything more complicated to
+ conform to external requirements (within reason).
+
+ * Be like Blaze when it makes sense (see "Differences and similarities
+ to Blaze" below).
+
+## Language
+
+GN uses an extremely simple, dynamically typed language. The types are:
+
+ * Boolean (`true`, `false`).
+ * 64-bit signed integers.
+ * Strings
+ * Lists (of any other types)
+ * Scopes (sort of like a dictionary, only for built-in stuff)
+
+There are some built-in variables whose values depend on the current
+environment. See `gn help` for more.
+
+There are purposefully many omissions in the language. There are no
+loops or function calls, for example. As per the above design
+philosophy, if you need this kind of thing you're probably doing it
+wrong.
+
+The variable `sources` has a special rule: when assigning to it, a list
+of exclusion patterns is applied to it. This is designed to
+automatically filter out some types of files. See `gn help
+set_sources_assignment_filter` and `gn help patterns` for more.
+
+### Strings
+
+Strings are enclosed in double-quotes and use backslash as the escape
+character. The only escape sequences supported are
+
+ * `\"` (for literal quote)
+ * `\$` (for literal dollars sign)
+ * `\\` (for literal backslash) Any other use of a backslash is treated
+ as a literal backslash. So, for example, `\b` used in patterns does
+ not need to be escaped, nor do most windows paths like
+ `"C:\foo\bar.h"`.
+
+Simple variable substitution is supported via `$`, where the word
+following the dollars sign is replaced with the value of the variable.
+You can optionally surround the name with `{}` if there is not a
+non-variable-name character to terminate the variable name. More complex
+expressions are not supported, only variable name substitution.
+
+```
+a = "mypath"
+b = "$a/foo.cc" # b -> "mypath/foo.cc"
+c = "foo${a}bar.cc" # c -> "foomypathbar.cc"
+```
+
+### Lists
+
+There is no way to get the length of a list. If you find yourself
+wanting to do this kind of thing, you're trying to do too much work in
+the build.
+
+Lists support appending:
+
+```
+a = [ "first" ]
+a += [ "second" ] # [ "first", "second" ]
+a += [ "third", "fourth" ] # [ "first", "second", "third", "fourth" ]
+b = a + [ "fifth" ] # [ "first", "second", "third", "fourth", "fifth" ]
+```
+
+Appending a list to another list appends the items in the second list
+rather than appending the list as a nested member.
+
+You can remove items from a list:
+
+```
+a = [ "first", "second", "third", "first" ]
+b = a - [ "first" ] # [ "second", "third" ]
+a -= [ "second" ] # [ "first", "third", "fourth" ]
+```
+
+The - operator on a list searches for matches and removes all matching
+items. Subtracting a list from another list will remove each item in the
+second list.
+
+If no matching items are found, an error will be thrown, so you need to
+know in advance that the item is there before removing it. Given that
+there is no way to test for inclusion, the main use-case is to set up a
+master list of files or flags, and to remove ones that don't apply to
+the current build based on various conditions.
+
+Lists support zero-based subscripting to extract values:
+
+```
+a = [ "first", "second", "third" ]
+b = a[1] # -> "second"
+```
+
+The \[\] operator is read-only and can not be used to mutate the
+list. This is of limited value absent the ability to iterate over a
+list. The primary use-case of this is when an external script returns
+several known values and you want to extract them.
+
+There are some cases where it's easy to overwrite a list when you mean
+to append to it instead. To help catch this case, it is an error to
+assign a nonempty list to a variable containing an existing nonempty
+list. If you want to get around this restriction, first assign the
+destination variable to the empty list.
+
+```
+a = [ "one" ]
+a = [ "two" ] # Error: overwriting nonempty list with a nonempty list.
+a = [] # OK
+a = [ "two" ] # OK
+```
+
+Note that execution of the build script is done without intrinsic
+knowledge of the meaning of the underlying data. This means that it
+doesn't know that `sources` is a list of file names, for example. So if
+you remove an item, it must match the literal string rather than
+specifying a different name that will resolve to the same file name.
+
+### Conditionals
+
+Conditionals look like C:
+
+```
+ if (is_linux || (is_win && target_cpu == "x86")) {
+ sources -= [ "something.cc" ]
+ } else if (...) {
+ ...
+ } else {
+ ...
+ }
+```
+
+You can use them in most places, even around entire targets if the
+target should only be declared in certain circumstances.
+
+### Functions
+
+Simple functions look like most other languages:
+
+```
+print("hello, world")
+assert(is_win, "This should only be executed on Windows")
+```
+
+Some functions take a block of code enclosed by `{ }` following them:
+
+```
+static_library("mylibrary") {
+ sources = [ "a.cc" ]
+}
+```
+
+This means that the block becomes an argument to the function for the
+function to execute. Most of the block-style functions execute the block
+and treat the resulting scope as a dictionary of variables to read.
+
+### Scoping and execution
+
+Files and `{ }` blocks introduce new scopes. Scoped are nested. When you
+read a variable, the containing scopes will be searched in reverse order
+until a matching name is found. Variable writes always go to the
+innermost scope.
+
+There is no way to modify any enclosing scope other than the innermost
+one. This means that when you define a target, for example, nothing you
+do inside of the block will "leak out" into the rest of the file.
+
+`if`/`else` statements, even though they use `{ }`, do not introduce a
+new scope so changes will persist outside of the statement.
+
+## Naming things
+
+### File and directory names
+
+File and directory names are strings and are interpreted as relative to
+the current build file's directory. There are three possible forms:
+
+Relative names:
+
+```
+"foo.cc"
+"src/foo.cc"
+"../src/foo.cc"
+```
+
+Source-tree absolute names:
+
+```
+"//net/foo.cc"
+"//base/test/foo.cc"
+```
+
+System absolute names (rare, normally used for include directories):
+
+```
+"/usr/local/include/"
+"/C:/Program Files/Windows Kits/Include"
+```
+
+### Labels
+
+Everything that can participate in the dependency graph (targets,
+configs, and toolchains) are identified by labels which are strings of a
+defined format. A common label looks like this:
+
+```
+"//base/test:test_support"
+```
+
+which consists of a source-root-absolute path, a colon, and a name. This
+means to look for the thing named "test\_support" in
+`src/base/test/BUILD.gn`.
+
+When loading a build file, if it doesn't exist in the given location
+relative to the source root, GN will look in the secondary tree in
+`tools/gn/secondary`. This structure of this tree mirrors the main
+repository and is a way to add build files for directories that may be
+pulled from other repositories where we can't easily check in BUILD
+files.
+
+A canonical label also includes the label of the toolchain being used.
+Normally, the toolchain label is implicitly inherited, but you can
+include it to specify cross-toolchain dependencies (see "Toolchains"
+below).
+
+```
+"//base/test:test_support(//build/toolchain/win:msvc)"
+```
+
+In this case it will look for the a toolchain definition called "msvc"
+in the file `//build/toolchain/win` to know how to compile this target.
+
+If you want to refer to something in the same buildfile, you can omit
+the path name and just start with a colon.
+
+```
+":base"
+```
+
+Labels can be specified as being relative to the current directory:
+
+```
+"source/plugin:myplugin"
+"../net:url_request"
+```
+
+If a name is unspecified, it will inherit the directory name:
+
+```
+"//net" = "//net:net"
+"//tools/gn" = "//tools/gn:gn"
+```
+
+## Build configuration
+
+### Overall build flow
+
+ 1. Look for `.gn` file in the current directory and walk up the
+ directory tree until one is found. Set this directory to be the
+ "source root" and interpret this file to find the name of the build
+ config file.
+ 2. Execute the build config file (this is the default toolchain).
+ 3. Load the `BUILD.gn` file in the root directory.
+ 4. Recursively load `BUILD.gn` in other directories to resolve all
+ current dependencies. If a BUILD file isn't found in the specified
+ location, GN will look in the corresponding location inside
+ `tools/gn/secondary`.
+ 5. When a target's dependencies are resolved, write out the `.ninja`
+ file to disk.
+ 6. When all targets are resolved, write out the root `build.ninja`
+ file.
+
+### The build config file
+
+The first file executed is the build config file. The name of this file
+is specified in the `.gn` file that marks the root of the repository. In
+Chrome it is `src/build/config/BUILDCONFIG.gn`. There is only one build
+config file.
+
+This file sets up the scope in which all other build files will execute.
+Any arguments, variables, defaults, etc. set up in this file will be
+visible to all files in the build.
+
+It is executed once for each toolchain (see "Toolchains").
+
+### Build arguments
+
+Arguments can be passed in from the command line (and from other
+toolchains, see "Toolchains" below). You declare which arguments you
+accept and specify default values via `declare_args`.
+
+See `gn help buildargs` for an overview of how this works. See `gn help
+declare_args` for specifics on declaring them.
+
+It is an error to declare a given argument more than once in a given
+scope. Typically arguments would be declared in an imported file (to
+share them among some subset of the build) or in the main build config
+file (to make them global).
+
+### Target defaults
+
+You can set up some default values for a given target type. This is
+normally done in the build config file to set a list of default configs
+that defines the build flags and other setup information for each target
+type.
+
+See `gn help set_defaults`.
+
+For example, when you declare a `static_library`, the target defaults
+for a static library are applied. These values can be overwritten,
+modified, or preserved by a target.
+
+```
+# This call is typically in the build config file (see above).
+set_defaults("static_library") {
+ configs = [ "//build:rtti_setup", "//build:extra_warnings" ]
+}
+
+# This would be in your directory's BUILD.gn file.
+static_library("mylib") {
+ # At this point configs is set to [ "//build:rtti_setup", "//build:extra_warnings" ]
+ # by default but may be modified.
+ configs -= "//build:extra_warnings" # Don't want these warnings.
+ configs += ":mylib_config" # Add some more configs.
+}
+```
+
+The other use-case for setting target defaults is when you define your
+own target type via `template` and want to specify certain default
+values.
+
+## Targets
+
+A target is a node in the build graph. It usually represents some kind
+of executable or library file that will be generated. Targets depend on
+other targets. The built-in target types (see `gn help <targettype>` for
+more help) are:
+
+ * `action`: Run a script to generate a file.
+ * `action_foreach`: Run a script once for each source file.
+ * `component`: Configurable to be another type of library.
+ * `executable`: Generates an executable file.
+ * `group`: A virtual dependency node that refers to one or more other
+ targets.
+ * `shared_library`: A .dll or .so.
+ * `source_set`: A lightweight virtual static library (usually
+ preferrable over a real static library since it will build faster).
+ * `static_library`: A .lib or .a file (normally you'll want a
+ source\_set instead).
+ * `test`: Generates an executable but annotates it as a test.
+
+You can extend this to make custom target types using templates (see below).
+
+## Configs
+
+Configs are named objects that specify sets of flags, include
+directories, and defines. They can be applied to a target and pushed to
+dependent targets.
+
+To define a config:
+
+```
+config("myconfig") {
+ includes = [ "src/include" ]
+ defines = [ "ENABLE_DOOM_MELON" ]
+}
+```
+
+To apply a config to a target:
+
+```
+executable("doom_melon") {
+ configs = [ ":myconfig" ]
+}
+```
+
+It is common for the build config file to specify target defaults that
+set a default list of configs. Targets can add or remove to this list as
+needed. So in practice you would usually use `configs += ":myconfig"` to
+append to the list of defaults.
+
+See `gn help config` for more information about how configs are declared
+and applied.
+
+### Public configs
+
+A target can apply settings to other targets that depend on it. The most
+common example is a third party target that requires some defines or
+include directories for its headers to compile properly. You want these
+settings to apply both to the compile of the third party library itself,
+as well as all targets that use the library.
+
+To do this, you write a config with the settings you want to apply:
+
+```
+config("my_external_library_config") {
+ includes = "."
+ defines = [ "DISABLE_JANK" ]
+}
+```
+
+Then this config is added to the target as a "public" config. It will
+apply both to the target as well as targets that directly depend on it.
+
+```
+shared_library("my_external_library") {
+ ...
+ # Targets that depend on this get this config applied.
+ public_configs = [ ":my_external_library_config" ]
+}
+```
+
+Dependent targets can in turn forward this up the dependency tree
+another level by adding your target as a "public" dependency.
+
+```
+static_library("intermediate_library") {
+ ...
+ # Targets that depend on this one also get the configs from "my external library".
+ public_deps = [ ":my_external_library" ]
+}
+```
+
+A target can forward a config to all dependents until a link boundary is
+reached by setting it as an `all_dependent_config`. This is strongly
+discouraged.
+
+## Toolchains
+
+A toolchain is a set of build commands to run for different types of
+input files and link tasks.
+
+You can have multiple toolchains in the build. It's easiest to think
+about each one as completely separate builds that can additionally have
+dependencies between them. This means, for example, that the 32-bit
+Windows build might depend on a 64-bit helper target. Each of them can
+depend on `"//base:base"` which will be the 32-bit base in the context
+of the 32-bit toolchain, and the 64-bit base in the context of the
+64-bit toolchain
+
+When a target specifies a dependency on another target, the current
+toolchain is inherited unless it is explicitly overridden (see "Labels"
+above).
+
+### Toolchains and the build configuration
+
+When you have a simple build with only one toolchain, the build config
+file is loaded only once at the beginning of the build. It must call
+`set_default_toolchain` to tell GN the label of the toolchain definition
+to use. This toolchain definition has the commands to use for the
+compiler and linker. The `toolchain_args` section of the toolchain
+definition is ignored.
+
+When a target has a dependency on a target using different toolchain, GN
+will start a build using that secondary toolchain to resolve the target.
+GN will load the build config file with the arguments specified in the
+toolchain definition. Since the toolchain is already known, calls to
+`set_default_toolchain` are ignored.
+
+So the toolchain configuration is two-way. In the default toolchain
+(i.e. the main build target) the configuration flows from the build
+config file to the toolchain: the build config file looks at the state
+of the build (OS type, CPU architecture, etc.) and decides which
+toolchain to use (via `set_default_toolchain`). In secondary toolchains,
+the configuration flows from the toolchain to the build config file: the
+`toolchain_args` in the toolchain definition specifies the arguments to
+re-invoke the build.
+
+### Toolchain example
+
+Say the default build is a 64-bit build. Either this is the default CPU
+architecture based on the current system, or the user has passed
+`target_cpu="x64"` on the command line. The build config file might look
+like this to set up the default toolchain:
+
+```
+# Set default toolchain only has an effect when run in the context of
+# the default toolchain. Pick the right one according to the current CPU
+# architecture.
+if (target_cpu == "x64") {
+ set_default_toolchain("//toolchains:64")
+} else if (target_cpu == "x86") {
+ set_default_toolchain("//toolchains:32")
+}
+```
+
+If a 64-bit target wants to depend on a 32-bit binary, it would specify
+a dependency using `datadeps` (data deps are like deps that are only
+needed at runtime and aren't linked, since you can't link a 32-bit and a
+64-bit library).
+
+```
+executable("my_program") {
+ ...
+ if (target_cpu == "x64") {
+ # The 64-bit build needs this 32-bit helper.
+ datadeps = [ ":helper(//toolchains:32)" ]
+ }
+}
+
+if (target_cpu == "x86") {
+ # Our helper library is only compiled in 32-bits.
+ shared_library("helper") {
+ ...
+ }
+}
+```
+
+The toolchain file referenced above (`toolchains/BUILD.gn`) would define
+two toolchains:
+
+```
+toolchain("32") {
+ tool("cc") {
+ ...
+ }
+ ... more tools ...
+
+ # Arguments to the build when re-invoking as a secondary toolchain.
+ toolchain_args() {
+ toolchain_cpu = "x86"
+ }
+}
+
+toolchain("64") {
+ tool("cc") {
+ ...
+ }
+ ... more tools ...
+
+ # Arguments to the build when re-invoking as a secondary toolchain.
+ toolchain_args() {
+ toolchain_cpu = "x64"
+ }
+}
+```
+
+The toolchain args specifies the CPU architecture explicitly, so if a
+target depends on something using that toolchain, that cpu architecture
+will be set when re-invoking the build. These args are ignored for the
+default toolchain since by the time they're known the build config has
+already been run. In general, the toolchain args and the conditions used
+to set the default toolchain should agree.
+
+The nice thing about the multiple-build setup is that you can write
+conditionals in your targets referencing the current toolchain state.
+The build files will be re-run with different state for each toolchain.
+For the `my_program` example above, you can see it queries the CPU
+architecture, adding a dependency only for the 64-bit build of the
+program. The 32-bit build would not get this dependency.
+
+### Declaring a toolchain
+
+Toolchains are declared with the `toolchain` command, which sets the
+commands to use for each compile and link operation. The toolchain also
+specifies a set of arguments to pass to the build config file when
+executing. This allows you to pass configuration information to the
+alternate toolchain.
+
+## Templates
+
+Templates are GN's primary way to re-use code. Typically, a template
+would expand to one or more other target types.
+
+```
+# Declares static library consisting of rules to build all of the IDL files into
+# compiled code.
+template("idl") {
+ source_set(target_name) {
+ ...
+ }
+}
+```
+
+Typically your template definition would go in a `.gni` file and users
+would import that file to see the template definition:
+
+```
+import("//tools/idl_compiler.gni")
+
+idl("my_interfaces") {
+ sources = [ "a.idl", "b.idl" ]
+}
+```
+
+Declaring a template creates a closure around the variables in scope at
+that time. When the template is invoked, the magic variable `invoker` is
+used to read variables out of the invoking scope. The template would
+generally copy the values its interested in into its own scope:
+
+```
+template("idl") {
+ source_set(target_name) {
+ sources = invoker.sources
+ }
+}
+```
+
+The current directory when a template executes will be that of the
+invoking build file rather than the template source file. This is so
+files passed in from the template invoker will be correct (this
+generally accounts for most file handling in a template). However, if
+the template has files itself (perhaps it generates an action that runs
+a script), you will want to use absolute paths ("//foo/...") to refer to
+these files to account for the fact that the current directory will be
+unpredictable during invocation. See `gn help template` for more
+information and more complete examples.
+
+## Other features
+
+### Imports
+
+You can import `.gni` files into the current scope with the `import`
+function. This is _not_ an include. The imported file is executed
+independently and the resulting scope is copied into the current file.
+This allows the results of the import to be cached, and also prevents
+some of the more "creative" uses of includes.
+
+Typically, a `.gni` would define build arguments and templates. See `gn
+help import` for more.
+
+### Path processing
+
+Often you will want to make a file name or a list of file names relative
+to a different directory. This is especially common when running
+scripts, which are executed with the build output directory as the
+current directory, while build files usually refer to files relative to
+their containing directory.
+
+You can use `rebase_path` to convert directories. See `gn help
+rebase_path` for more help and examples. Typical usage to convert a file
+name relative to the current directory to be relative to the root build
+directory would be: ``` new_paths = rebase_path("myfile.c",
+root_build_dir) ```
+
+### Patterns
+
+Patterns are used to generate the output file names for a given set of
+inputs for custom target types, and to automatically remove files from
+the `sources` variable (see `gn help set_sources_assignment_filter`).
+
+They are like simple regular expressions. See `gn help patterns` for more.
+
+### Executing scripts
+
+There are two ways to execute scripts. All external scripts in GN are in
+Python. The first way is as a build step. Such a script would take some
+input and generate some output as part of the build. Targets that invoke
+scripts are declared with the "action" target type (see `gn help
+action`).
+
+The second way to execute scripts is synchronously during build file
+execution. This is necessary in some cases to determine the set of files
+to compile, or to get certain system configurations that the build file
+might depend on. The build file can read the stdout of the script and
+act on it in different ways.
+
+Synchronous script execution is done by the `exec_script` function (see
+`gn help exec_script` for details and examples). Because synchronously
+executing a script requires that the current buildfile execution be
+suspended until a Python process completes execution, relying on
+external scripts is slow and should be minimized.
+
+You can synchronously read and write files which is occasionally
+necessary when synchronously running scripts. The typical use-case would
+be to pass a list of file names longer than the command-line limits of
+the current platform. See `gn help read_file` and `gn help write_file`
+for how to read and write files. These functions should be avoided if at
+all possible.
+
+# Differences and similarities to Blaze
+
+[Blaze](http://google-engtools.blogspot.com/2011/08/build-in-cloud-how-build-system-works.html)
+is Google's internal build system. It has inspired a number of other
+systems such as
+[Pants](https://github.com/twitter/commons/tree/master/src/python/twitter/pants)
+and [Buck](http://facebook.github.io/buck/).
+
+In Google's homogeneous environment, the need for conditionals is very
+low and they can get by with a few hacks (`abi_deps`). Chrome uses
+conditionals all over the place and the need to add these is the main
+reason for the files looking different.
+
+GN also adds the concept of "configs" to manage some of the trickier
+dependency and configuration problems which likewise don't arise on the
+server. Blaze has a concept of a "configuration" which is like a GN
+toolchain, but built into the tool itself. The way that toolchains work
+in GN is a result of trying to separate this concept out into the build
+files in a clean way.
+
+GN keeps some GYP concept like "all dependent" and "direct dependent"
+settings which work a bit differently in Blaze. This is partially to
+make conversion from the existing GYP code easier, and the GYP
+constructs generally offer more fine-grained control (which is either
+good or bad, depending on the situation).
+
+GN also uses GYP names like "sources" instead of "srcs" since
+abbreviating this seems needlessly obscure, although it uses Blaze's
+"deps" since "dependencies" is so hard to type. Chromium also compiles
+multiple languages in one target so specifying the language type on the
+target name prefix was dropped (e.g. from `cc_library`).
diff --git a/tools/gn/docs/quick_start.md b/tools/gn/docs/quick_start.md
new file mode 100644
index 0000000..49f16ae
--- /dev/null
+++ b/tools/gn/docs/quick_start.md
@@ -0,0 +1,329 @@
+# GN Quick Start guide
+
+[TOC]
+
+## Running GN
+
+You just run `gn` from the command line. There is a script in
+depot\_tools (which is presumably on your path) with this name. The
+script will find the binary in the source tree containing the current
+directory and run it.
+
+## Setting up a build
+
+In GYP, the system would generate `Debug` and `Release` build
+directories for you and configure them accordingly. GN doesn't do this.
+Instead, you set up whatever build directory you want with whatever
+configuration you want. The Ninja files will be automatically
+regenerated if they're out of date when you build in that directory.
+
+To make a build directory:
+
+```
+gn gen out/my_build
+```
+
+## Passing build arguments
+
+Set build arguments on your build directory by running:
+
+```
+gn args out/my_build
+```
+
+This will bring up an editor. Type build args into that file like this:
+
+```
+is_component_build = true
+is_debug = false
+```
+
+You can see the list of available arguments and their default values by
+typing
+
+```
+gn args --list out/my_build
+```
+
+on the command line. See "Taking build arguments" below for information
+on how to use these in your code. (Note that you have to specify the
+build directory for this command because the available arguments can
+change according to what's set.
+
+## Configuring goma
+
+
+Run `gn args out/Default` (substituting your build directory as needed).
+Add:
+
+```
+use_goma = true
+goma_dir = "~/foo/bar/goma"
+```
+
+If your goma is in the default location (`~/goma`) then you can omit the
+`goma_dir` line.
+
+## Configuring component mode
+
+This is a build arg like the goma flags. run `gn args out/Default` and add:
+
+```
+is_component_build = true
+```
+
+## Step-by-step
+
+### Adding a build file
+
+Create a `tools/gn/tutorial/BUILD.gn` file and enter the following:
+
+```
+executable("hello_world") {
+ sources = [
+ "hello_world.cc",
+ ]
+}
+```
+
+There should already be a `hello_world.cc` file in that directory,
+containing what you expect. That's it! Now we just need to tell the
+build about this file. Open the `BUILD.gn` file in the root directory
+and add the label of this target to the dependencies of the root group
+(a "group" target is a meta-target that is just a collection of other
+targets):
+
+```
+group("root") {
+ deps = [
+ ...
+ "//url",
+ "//tools/gn/tutorial:hello_world",
+ ]
+}
+```
+
+You can see the label of your target is "//" (indicating the source
+root), followed by the directory name, a colon, and the target name.
+
+### Testing your addition
+
+From the command line in the source root directory:
+
+```
+gn gen out/Default
+ninja -C out/Default hello_world
+out/Default/hello_world
+```
+
+GN encourages target names for static libraries that aren't globally
+unique. To build one of these, you can pass the label with no leading
+"//" to ninja:
+
+```
+ninja -C out/Default tools/gn/tutorial:hello_world
+```
+
+### Declaring dependencies
+
+Let's make a static library that has a function to say hello to random
+people. There is a source file `hello.cc` in that directory which has a
+function to do this. Open the `tools/gn/tutorial/BUILD.gn` file and add
+the static library to the bottom of the existing file:
+
+```
+static_library("hello") {
+ sources = [
+ "hello.cc",
+ ]
+}
+```
+
+Now let's add an executable that depends on this library:
+
+```
+executable("say_hello") {
+ sources = [
+ "say_hello.cc",
+ ]
+ deps = [
+ ":hello",
+ ]
+}
+```
+
+This executable includes one source file,and depends on the previous
+static library. The static library is referenced by its label in the
+`deps`. You could have used the full label `//tools/gn/tutorial:hello`
+but if you're referencing a target in the same build file, you can use
+the shortcut `:hello`.
+
+### Test the static library version
+
+From the command line in the source root directory:
+
+```
+ninja -C out/Default say_hello
+out/Default/say_hello
+```
+
+Note that you **didn't** need to re-run GN.GN will automatically rebuild
+the ninja files when any build file has changed. You know this happens
+when ninja prints `[1/1] Regenerating ninja files` at the beginning of
+execution.
+
+### Compiler settings
+
+Our hello library has a new feature, the ability to say hello to two
+people at once. This feature is controlled by defining `TWO_PEOPLE`. We
+can add defines like so:
+
+```
+static_library("hello") {
+ sources = [
+ "hello.cc",
+ ]
+ defines = [
+ "TWO_PEOPLE",
+ ]
+}
+```
+
+### Putting settings in a config
+
+However, users of the library also need to know about this define, and
+putting it in the static library target defines it only for the files
+there. If somebody else includes `hello.h`, they won't see the new
+definition. To see the new definition, everybody will have to define
+`TWO_PEOPLE`.
+
+GN has a concept called a "config" which encapsulates settings. Let's
+create one that defines our preprocessor define:
+
+```
+config("hello_config") {
+ defines = [
+ "TWO_PEOPLE",
+ ]
+}
+```
+
+To apply these settings to your target, you only need to add the
+config's label to the list of configs in the target:
+
+```
+static_library("hello") {
+ ...
+ configs += [
+ ":hello_config",
+ ]
+}
+```
+
+Note that you need "+=" here instead of "=" since the build
+configuration has a default set of configs applied to each target that
+set up the default build stuff. You want to add to this list rather than
+overwrite it. To see the default configs, you can use the `print`
+function in the build file or the `desc` command-line subcommand (see
+below for examples of both).
+
+### Dependent configs
+
+This nicely encapsulates our settings, but still requires everybody that
+uses our library to set the config on themselves. It would be nice if
+everybody that depends on our `hello` library can get this
+automatically. Change your library definition to:
+
+```
+static_library("hello") {
+ sources = [
+ "hello.cc",
+ ]
+ all_dependent_configs = [
+ ":hello_config"
+ ]
+}
+```
+
+This applies the `hello_config` to the `hello` target itself, plus all
+targets that depend on transitively depend on the current one. Now
+everybody that depends on us will get our settings. You can also set
+`direct_dependent_configs` which applies only to targets that directly
+depend on your target (not transitively).
+
+Now if you compile and run, you'll see the new version with two people:
+
+```
+> ninja -C out/Default say_hello
+ninja: Entering directory 'out/Default'
+[1/1] Regenerating ninja files
+[4/4] LINK say_hello
+> out/Default/say_hello
+Hello, Bill and Ted.
+```
+
+## Don't know what's going on?
+
+You can run GN in verbose mode to see lots of messages about what it's
+doing. Use `-v` for this.
+
+### Print debugging
+
+There is a `print` command which just writes to stdout:
+
+```
+static_library("hello") {
+ ...
+ print(configs)
+}
+```
+
+This will print all of the configs applying to your target (including
+the default ones).
+
+### The "desc" command
+
+You can run `gn desc <build_dir> <targetname>` to get information about
+a given target:
+
+```
+gn desc out/Default //tools/gn/tutorial:say_hello
+```
+
+will print out lots of exciting information. You can also print just one
+section. Lets say you wanted to know where your `TWO_PEOPLE` define
+came from on the `say_hello` target:
+
+```
+> gn desc out/Default //tools/gn/tutorial:say_hello defines --blame
+...lots of other stuff omitted...
+ From //tools/gn/tutorial:hello_config
+ (Added by //tools/gn/tutorial/BUILD.gn:12)
+ TWO_PEOPLE
+```
+
+You can see that `TWO_PEOPLE` was defined by a config, and you can also
+see the which like caused that config to be applied to your target (in
+this case, the `all_dependent_configs` line).
+
+Another particularly interesting variation:
+
+```
+gn desc out/Default //base:base_i18n deps --tree
+```
+
+See `gn help desc` for more.
+
+### Performance
+
+You can see what took a long time by running it with the --time command
+line flag. This will output a summary of timings for various things.
+
+You can also make a trace of how the build files were executed:
+
+```
+gn --tracelog=mylog.trace
+```
+
+and you can load the resulting file in Chrome's `about:tracing` page to
+look at everything.
diff --git a/tools/gn/docs/standalone.md b/tools/gn/docs/standalone.md
new file mode 100644
index 0000000..faeb426
--- /dev/null
+++ b/tools/gn/docs/standalone.md
@@ -0,0 +1,41 @@
+# Introduction
+
+This page is about how to design a project that can build independently
+with GN but also be brought into the Chrome build.
+
+GN is in principle no different than GYP in that there is some core
+configuration that must be the same between both the standalone build
+and the Chrome build. However, GN is much more explicit in its naming
+and configuration, so the similarities between the two builds are also
+much more explicit and there is less flexibility in how things are
+configured.
+
+# What you need for a minimal GN build
+
+Requirements:
+
+ * A master build config file. Chrome's is `//build/config/BUILDCONFIG.gn`
+ * A separate build file for the toolchain definition. It's not a good idea
+ to put these in a BUILD.gn file shared with any target definitions for
+ complex reasons. Chrome's are in `//build/toolchain/<platform>/BUILD.gn`.
+ * A `BUILD.gn` file in the root directory. This will be loaded after the
+ build config file to start the build.
+
+You may want a `.gn` file in the root directory. When you run GN it
+recursively looks up the directory tree until it finds this file, and it
+treats the containing directory as the "source root". This file also
+defines the location of the master build config file:
+
+ * See Chrome's `src/.gn` file.
+ * Unlike Chrome, you probably don't need to define a secondary root.
+ * see `gn help dotfile` for more.
+
+Adding a `.gn` file in a repository that is pulled into Chrome means
+that then running GN in your subdirectory will configure a build for
+your subproject rather than for all of Chrome. This could be an
+advantage or a disadvantage.
+
+If you would rather avoid using this file, you can use the command-line
+flags `--root` and `--dotfile` to set these values.
+
+# How the standalone and Chrome builds interact
diff --git a/tools/gn/docs/style_guide.md b/tools/gn/docs/style_guide.md
new file mode 100644
index 0000000..af4e902
--- /dev/null
+++ b/tools/gn/docs/style_guide.md
@@ -0,0 +1,184 @@
+# GN Style Guide
+
+[TOC]
+## Naming and ordering within the file
+
+### Location of build files
+
+It usually makes sense to have more build files closer to the code than
+fewer ones at the toplevel (this is in contrast with what we did with
+GYP). This makes things easier to find and owners reviews easier since
+changes are more focused.
+
+### Targets
+
+ * Most BUILD files should have a target with the same name of the
+ directory. This target should be the first target.
+ * Other targets should be in "some order that makes sense." Usually
+ more important targets will be first, and unit tests will follow the
+ corresponding target. If there's no clear ordering, consider
+ alphabetical order.
+ * Targets and configs should be named using lowercase with underscores
+ separating words, unless there is a strong reason to do otherwise.
+ * Test support libraries should be source sets named "test\_support".
+ So "//ui/compositor:test\_support". Test support libraries should
+ include as public deps the non-test-support version of the library
+ so tests need only depend on the test\_support target (rather than
+ both).
+
+Output names (the part after the colon in a label) of executables and
+shared libraries must be globally unique since they all go in the root
+directory. Prefer to do this by giving a target a short (possibly
+non-unique) name that makes writing dependencies clearer, and setting
+the `output_name` variable to something unique.
+
+For example, it looks much better to write a dependency as
+`"//mojo/public/bindings"` rather than
+`"//mojo/public/bindings:mojo_bindings"`. So in the file
+`//mojo/public/bindings/BUILD.gn`: ``` shared_library("bindings") { #
+Very non-unique name "bindings" makes the most sense in this context.
+output_name = "mojo_bindings" # Give target a unique output name to
+avoid collisions. ... } ``` This will produce a file
+`mojo_bindings.so` in the root build directory.
+
+### Configs
+
+ * A config associated with a single target should be named the same as
+ the target with `_config` following it.
+ * A config should appear immediately before the corresponding target
+ that uses it.
+
+### Example
+
+Example for the `src/foo/BUILD.gn` file:
+
+```
+# Copyright 2013 The Chromium Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+
+# Config for foo is named foo_config and immediately precedes it in the file.
+config("foo_config") {
+}
+
+# Target matching path name is the first target.
+executable("foo") {
+}
+
+# Test for foo follows it.
+test("foo_unittests") {
+}
+
+config("bar_config") {
+}
+
+source_set("bar") {
+}
+```
+
+## Ordering within a target
+
+ 1. `output_name` / `visibility` / `testonly`
+ 2. `sources`
+ 3. `cflags`, `include_dirs`, `defines`, `configs` etc. in whatever
+ order makes sense to you.
+ 4. `public_deps`
+ 5. `deps`
+
+### Conditions
+
+Simple conditions affecting just one variable (e.g. adding a single
+source or adding a flag for one particular OS) can go beneath the
+variable they affect. More complicated conditions affecting more than
+one thing should go at the bottom.
+
+Conditions should be written to minimize the number of conditional blocks.
+
+## Formatting and indenting
+
+ * Indents are two spaces, both for indented blocks and wrapped lines.
+ * Variables are `lower_case_with_underscores`
+ * Complicated conditions and if statements should generally follow the
+ Google C++ style guide for formatting.
+ * Comments should be complete sentences with periods at the end.
+ * End-of-line-comments should have two spaces separating them and the
+ code.
+ * Compiler flags and such should always be commented with what they do
+ and why the flag is needed.
+ * Try to keep lines under 80 columns. If a file name or similar string
+ puts you beyond 80 with reasonable indenting, it's OK, but most
+ things can be wrapped nicely under that for the code review tool.
+
+### List formatting
+
+```
+ deps = [
+ "afile.cc",
+ "bar.cc", # Note trailing comma on last element.
+ ]
+```
+
+Alphabetize the list elements unless there is a more obvious ordering.
+In some cases, it makes more sense to put more than one list member on a
+line if they clearly go together (for example, two short compiler flags
+that must go next to each other).
+
+Prefer use the multi-line style for lists of more than one elements.
+Lists with single-elements can be written on one line if desired:
+
+```
+ all_dependent_configs = [ ":foo_config" ] # No trailing comma.
+```
+
+### Sources
+
+ * Sources should always be alphabetized within a given list.
+ * List sources only once. It is OK to conditionally include sources
+ rather than listing them all at the top and then conditionally
+ excluding them when they don't apply. Conditional inclusion is often
+ clearer since a file is only listed once and it's easier to reason
+ about when reading.
+
+```
+ sources = [
+ "main.cc",
+ ]
+ if (use_aura) {
+ sources += [ "thing_aura.cc" ]
+ }
+ if (use_gtk) {
+ sources += [ "thing_gtk.cc" ]
+ }
+```
+
+### Deps
+
+ * Deps should be in alphabetical order.
+ * Deps within the current file should be written first and not
+ qualified with the file name (just `:foo`).
+ * Other deps should always use fully-qualified path names unless
+ relative ones are required for some reason.
+
+```
+ deps = [
+ ":a_thing",
+ ":mystatic",
+ "//foo/bar:other_thing",
+ "//foo/baz:that_thing",
+ ]
+```
+
+### Import
+
+Use fully-qualified paths for imports:
+
+```
+import("//foo/bar/baz.gni") # Even if this file is in the foo/bar directory
+```
+
+## Usage
+
+Use `source_set` rather than `static_library` unless you have a reason
+to do otherwise. A static library is a standalone library which can be
+slow to generate. A source set just links all the object files from that
+target into the targets depending on it, which saves the "lib" step.
diff --git a/tools/gn/docs/update_binaries.md b/tools/gn/docs/update_binaries.md
new file mode 100644
index 0000000..2ef502e
--- /dev/null
+++ b/tools/gn/docs/update_binaries.md
@@ -0,0 +1,35 @@
+# How to update the [GN binaries](gn.md) that Chromium uses.
+
+## Prerequisites
+
+You'll need a checkout of Chromium, and commit access to the
+`buildtools/` repo. Check with scottmg, thakis, brettw, dpranke, or a
+member of chrome-infra to get access to that repo.
+
+## Instructions
+
+_Hopefully there will be a script that does this all for you shortly._
+
+ 1. cd to your Chromium checkout.
+ 2. Create a whitespace change in DEPS and upload it to create a "dummy" CL
+ 3. Run the following commands:
+ 1. git-cl try -b linux\_chromium\_gn\_upload\_x86
+ -b linux\_chromium\_gn\_upload\_x64
+ -r $GIT\_REVISION\_YOU\_WANT\_TO\_BUILD
+ 2. git-cl try -b mac\_chromium\_gn\_upload
+ -r $GIT\_REVISION\_YOU\_WANT\_TO\_BUILD
+ 3. git-cl try -b win8\_chromium\_gn\_upload
+ -r $GIT\_REVISION\_YOU\_WANT\_TO\_BUILD
+ 4. Wait for the try jobs to finish.
+ 5. If they all ran successfully, copy the digests from the tryjob build
+ log output into `src/buildtools/{mac,linux32,linux64}gn.sha1` and
+ `src/buildtools/win/gn.exe.sha1` as appropriate.
+ 6. Upload a buildtools CL with the updated digests and get it reviewed
+ and committed. Make sure you note the revision of GN that you built
+ against in the commit message.
+ 7. Go back to your "dummy" CL w/ the change to the DEPS file in src/
+ and update the buildtools revision to your newly-committed
+ buildtools change.
+ 8. Get that reviewed and landed in Chromium. Make sure you note the
+ revision of GN that you built against in the commit message, along
+ with the revision of buildtools that you're rolling to.
