Index: tools/gn/function_toolchain.cc |
diff --git a/tools/gn/function_toolchain.cc b/tools/gn/function_toolchain.cc |
index f42be6cd5607d8d5ab2e5329918f2188f4149b7f..05c764bfbdf65ab5524c8c15ae48221b7a2d63dc 100644 |
--- a/tools/gn/function_toolchain.cc |
+++ b/tools/gn/function_toolchain.cc |
@@ -305,7 +305,44 @@ const char kToolchain_Help[] = |
R"*(toolchain: Defines a toolchain. |
A toolchain is a set of commands and build flags used to compile the source |
- code. You can have more than one toolchain in use at once in a build. |
+ code. The toolchain() function defines these commands. |
+ |
+Toolchain overview |
+ |
+ You can have more than one toolchain in use at once in a build and a target |
+ can exist simultaneously in multiple toolchains. A build file is executed |
+ once for each toolchain it is referenced in so the GN code can vary all |
+ parameters of each target (or which targets exist) on a per-toolchain basis. |
+ |
+ 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() (see "gn help set_default_toolchain") to tell GN the |
+ label of the toolchain definition to use. The "toolchain_args" section of the |
+ toolchain definition is ignored. |
+ |
+ When a target has a dependency on a target using different toolchain (see "gn |
+ help labels" for how to specify this), GN will start a build using that |
+ secondary toolchain to resolve the target. GN will load the build config file |
+ with the build arguements overridden as specified in the toolchain_args. |
+ Because the default toolchain is already known, calls to |
+ set_default_toolchain() are ignored. |
+ |
+ To load a file in an alternate toolchain, GN does the following: |
+ |
+ 1. Loads the file with the toolchain definition in it (as determined by the |
+ toolchain label). |
+ 2. Re-runs the master build configuration file, applying the arguments |
+ specified by the toolchain_args section of the toolchain definition. |
+ 3. Loads the destination build file in the context of the configuration file |
+ in the previous step. |
+ |
+ 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. |
Functions and variables |
@@ -344,40 +381,53 @@ Functions and variables |
This concept is somewhat inefficient to express in Ninja (it requires a lot |
of duplicate of rules) so should only be used when absolutely necessary. |
-Invoking targets in toolchains |
+Example of defining a toolchain |
- By default, when a target depends on another, there is an implicit toolchain |
- label that is inherited, so the dependee has the same one as the dependent. |
- |
- You can override this and refer to any other toolchain by explicitly |
- labeling the toolchain to use. For example: |
- data_deps = [ "//plugins:mine(//toolchains:plugin_toolchain)" ] |
- The string "//build/toolchains:plugin_toolchain" is a label that identifies |
- the toolchain declaration for compiling the sources. |
- |
- To load a file in an alternate toolchain, GN does the following: |
- |
- 1. Loads the file with the toolchain definition in it (as determined by the |
- toolchain label). |
- 2. Re-runs the master build configuration file, applying the arguments |
- specified by the toolchain_args section of the toolchain definition. |
- 3. Loads the destination build file in the context of the configuration file |
- in the previous step. |
+ toolchain("32") { |
+ tool("cc") { |
+ command = "gcc {{source}}" |
+ ... |
+ } |
-Example |
+ toolchain_args = { |
+ use_doom_melon = true # Doom melon always required for 32-bit builds. |
+ current_cpu = "x86" |
+ } |
+ } |
- toolchain("plugin_toolchain") { |
+ toolchain("64") { |
tool("cc") { |
command = "gcc {{source}}" |
... |
} |
toolchain_args = { |
- is_plugin = true |
- is_32bit = true |
- is_64bit = false |
+ # use_doom_melon is not overridden here, it will take the default. |
+ current_cpu = "x64" |
+ } |
+ } |
+ |
+Example of cross-toolchain dependencies |
+ |
+ 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") { |
+ ... |
+ } |
} |
- }; |
)*"; |
Value RunToolchain(Scope* scope, |