💹 Update GN docs about target_cpu to encourage use of current_cpu

tools/gn/docs/cross_compiles.md

 # How GN handles cross-compiling
 
 ## As a GN user
 
 GN has robust support for doing cross compiles and building things for
 multiple architectures in a single build (e.g., to build some things to
 run locally and some things to run on an embedded device). In fact,
 there is no limit on the number of different architectures you can build
 at once; the Chromium build uses at least four in some configurations.
 
@@ skipping 55 matching lines @@
 The `is_linux`, `is_win` etc. variables are updated to reflect the
 current settings, and changes to `cflags`, `ldflags` and so forth also
 only apply to the current toolchain and the current thing being built.
 
 You can also refer to the `target_cpu` and `target_os` variables. This
 is useful if you need to do something different on the host depending on
 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, **`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`:
+
+```
+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" ]
+  }
+}
+
+group("fat_bundle") {

[agrieve, 2016/06/08 17:43:56]

hmm, actually, I don't think this example is correct.

E.g., if target_cpu == "arm", and a target explicitly build
":fat_bundle(//build/toolchain/android:arm64)", it would do the wrong thing.

Only valid example I could find in our code was from here:
https://cs.chromium.org/chromium/src/build/config/sysroot.gni

So changed to this.

+  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
 [GNLanguage#Overall-build-flow](language.md#Overall-build-flow), the
 `default_toolchain` is declared in the `//build/config/BUILDCONFIG.gn`
 file. Usually the `default_toolchain` should be the toolchain for the
 `target_os` and `target_cpu`. The `current_toolchain` reflects the
 toolchain that is currently in effect for a rule.
 
 Be sure you understand the differences between `host_cpu`, `target_cpu`,
 `current_cpu`, and `toolchain_cpu` (and the os equivalents). The first
 two are set as described above. You are responsible for making sure that
 `current_cpu` is set appropriately in your toolchain definitions; if you
 are using the stock templates like `gcc_toolchain` and `msvc_toolchain`,
 that means you are responsible for making sure that `toolchain_cpu` and
 `toolchain_os` are set as appropriate in the template invocations.