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 |