Update GN docs about target_cpu to encourage use of current_cpu
BUG=616819
Review-Url: https://codereview.chromium.org/2038733003
Cr-Original-Commit-Position: refs/heads/master@{#398661}
Cr-Mirrored-From: https://chromium.googlesource.com/chromium/src
Cr-Mirrored-Commit: bfdee36d31a624d330b60b481fc26d10dff81b97
diff --git a/tools/gn/docs/cross_compiles.md b/tools/gn/docs/cross_compiles.md
index 68d9bcb..2d7e8a3 100644
--- a/tools/gn/docs/cross_compiles.md
+++ b/tools/gn/docs/cross_compiles.md
@@ -73,11 +73,42 @@
toolchains. You can do similar things for the `host_cpu` and `host_os`
variables, but should generally never need to.
+For the default toolchain, `target_cpu` and `current_cpu` are the same. For a
+secondary toolchain, `current_cpu` is set based on the toolchain definition
+and `target_cpu` remains the same. When writing rules, **`current_cpu` should
+be used rather than `target_cpu` most of the time**.
+
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](language.md#Labels).
+Here's an example of when to use `target_cpu` vs `current_cpu`:
+
+```
+declare_args() {
+ # Applies only to toolchains targeting target_cpu.
+ sysroot = ""
+}
+
+config("my_config") {
+ # Uses current_cpu because compile flags are toolchain-dependent.
+ if (current_cpu == "arm") {
+ defines = [ "CPU_IS_32_BIT" ]
+ } else {
+ defines = [ "CPU_IS_64_BIT" ]
+ }
+ # Compares current_cpu with target_cpu to see whether current_toolchain
+ # has the same architecture as target_toolchain.
+ if (sysroot != "" && current_cpu == target_cpu) {
+ cflags = [
+ "-isysroot",
+ sysroot,
+ ]
+ }
+}
+```
+
## As a //build/config or //build/toolchain author
As described in
diff --git a/tools/gn/variables.cc b/tools/gn/variables.cc
index 0eb5aab..8bafb68 100644
--- a/tools/gn/variables.cc
+++ b/tools/gn/variables.cc
@@ -52,13 +52,13 @@
"\n"
" This value should be used to indicate the desired architecture for\n"
" the primary objects of the build. It will match the cpu architecture\n"
- " of the default toolchain.\n"
+ " of the default toolchain, but not necessarily the current toolchain.\n"
"\n"
" In many cases, this is the same as \"host_cpu\", but in the case\n"
- " of cross-compiles, this can be set to something different. This \n"
- " value is different from \"current_cpu\" in that it can be referenced\n"
- " from inside any toolchain. This value can also be ignored if it is\n"
- " not needed or meaningful for a project.\n"
+ " of cross-compiles, this can be set to something different. This\n"
+ " value is different from \"current_cpu\" in that it does not change\n"
+ " based on the current toolchain. When writing rules, \"current_cpu\"\n"
+ " should be used rather than \"target_cpu\" most of the time.\n"
"\n"
" This value is not used internally by GN for any purpose, so it\n"
" may be set to whatever value is needed for the build.\n"
