💹 Update GN docs about target_cpu to encourage use of current_cpu

tools/gn/docs/cross_compiles.md

Index: tools/gn/docs/cross_compiles.md
diff --git a/tools/gn/docs/cross_compiles.md b/tools/gn/docs/cross_compiles.md
index 68d9bcb8570a3b623bb35ad0b1ecc2f426a64807..8770d0ad0b0169f2342e3ee0b6db31ad43731d63 100644
--- a/tools/gn/docs/cross_compiles.md
+++ b/tools/gn/docs/cross_compiles.md
@@ -73,11 +73,42 @@ which target\_arch is requested; the values are constant across all
 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, you **almost always want
+to use `current_cpu` rather than `target_cpu`**.

[Dirk Pranke, 2016/06/04 23:03:53]

I don't know if "almost always" is really right. Current usage looks like we use
current_cpu 3x as often as target_cpu, and I doubt that most of the target_cpu
uses are actually wrong.

So, that's definitely at least "most of the time" but maybe not "almost always".

[agrieve, 2016/06/08 17:21:48]

Done.

+
 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`:
+
+```
+config("my_config") {
+  # Uses current_cpu because compile flags are toolchain-dependent.
+  if (current_cpu == "arm") {
+    defines = ["CPU_IS_32_BIT"]

[brettw, 2016/06/03 20:50:40]

Style nit: spaces inside the []

[agrieve, 2016/06/08 17:21:48]

Done.

+  } else {
+    defines = ["CPU_IS_64_BIT"]
+  }
+}
+
+group("fat_bundle") {
+  deps = [
+    ":shared_library",
+  ]
+  # Uses target_cpu because 64 bit devices require both 64 bit and 32 bit
+  # libraries, but 32 bit devices require only 32 bit libraries.
+  if (target_cpu == "arm64") {
+    deps += [
+      ":shared_library(//build/toolchain/android:arm)",
+    ]
+  }
+}
+```
+
 ## As a //build/config or //build/toolchain author
 
 As described in