Add more gn documentation

tools/gn/docs/language.md

 # GN Language and Operation
 
 [TOC]
 
 ## Introduction
 
 This page describes many of the language details and behaviors.
 
 ### Use the built-in help!
 
@@ skipping 245 matching lines @@
 "//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
-`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
 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.
   * `bundle_data`: Declare data to go into a Mac/iOS bundle.
@@ skipping 90 matching lines @@
 ```
 
 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 as it can spray flags and defines over more of the build than
 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
 would expand to one or more other target types.
 
 ```
 # Declares a script that compiles IDL files to source, and then compiles those
 # source files.
 template("idl") {
   # Always base helper targets on target_name so they're unique. Target name
@@ skipping 144 matching lines @@
 GN keeps some GYP concept like "all 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`).