Add more gn documentation

tools/gn/docs/language.md

Index: tools/gn/docs/language.md
diff --git a/tools/gn/docs/language.md b/tools/gn/docs/language.md
index 514541d25918e783ee7312acc62a611ae7fde9b6..0d60cb50c1e95b2ff8a217db66e09d4c835b1a98 100644
--- a/tools/gn/docs/language.md
+++ b/tools/gn/docs/language.md
@@ -263,148 +263,8 @@ System absolute names (rare, normally used for include directories):
 "/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
-`build/secondary`. The 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. The secondary tree is a fallback rather than an override, so a file in
-the normal location always takes precedence.
-
-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 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.
-Stylistically, we prefer to use absolute paths for all non-file-local
-references unless a build file needs to be run in different contexts (like
-a project needs to be both standalone and pulled into other projects in
-difference places in the directory hierarchy).
-
-```
-"source/plugin:myplugin"  # Prefer not to do these.
-"../net:url_request"
-```
-
-If a name is unspecified, it will inherit the directory name. Stylistically, we
-prefer to omit the colon and name in these cases.
-
-```
-"//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). In Chrome
-     this is `//build/config/BUILDCONFIG.gn`.
-  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
-     `build/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. If the top-level build file defines a group called "default"
-     (i.e., `//:default`), GN will tell Ninja to use that for the
-     default build target, rather than building everything. (You can
-     still use `ninja all` to build everything).
-
-### 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 `//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
@@ -515,138 +375,6 @@ necessary. Instead, use public_deps to control which flags apply where.
 In Chrome, prefer the build flag header system (`build/buildflag_header.gni`)
 for defines which prevents most screw-ups with compiler defines.
 
-## 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 `data_deps` (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.
-    data_deps = [ ":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 = {
-    current_cpu = "x86"
-  }
-}
-
-toolchain("64") {
-  tool("cc") {
-    ...
-  }
-  ... more tools ...
-
-  # Arguments to the build when re-invoking as a secondary toolchain.
-  toolchain_args = {
-    current_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