Add --android_platforms to the user manual.

PiperOrigin-RevId: 583052277
Change-Id: I1d4d82386f09f6feb6465f9ca320e11fda1dde3b

site/en/docs/user-manual.md

@@ -500,29 +500,22 @@ to only apply to actions of which the owner's label contains '/bar/':
 This option specifies the name of the CPU architecture that should be
 used to build host tools.
 
-#### `--fat_apk_cpu={{ "<var>" }}cpu[,cpu]*{{ "</var>" }}` {:#fat-apk-cpu}
-
-The CPUs to build C/C++ libraries for in the transitive `deps` of
-`android_binary` rules. Other C/C++ rules are not affected. For example, if a
-`cc_library` appears in the transitive `deps` of an `android_binary` rule and a
-`cc_binary` rule, the `cc_library` will be built at least twice:
-once for each CPU specified with `--fat_apk_cpu` for the
-`android_binary` rule, and once for the CPU specified with
-`--cpu` for the `cc_binary` rule.
-
-The default is `armeabi-v7a`.
-
-One `.so` file is created and packaged in the APK for
-each CPU specified with `--fat_apk_cpu`. The `.so` file's name
-prefixes the name of the `android_binary` rule with "lib". For example, if the name of
-the `android_binary` is "foo", then the file is `libfoo.so`.
-
-Note: An Android-compatible crosstool must be selected.
-If an `android_ndk_repository` rule is defined in the
-WORKSPACE file, an Android-compatible crosstool is automatically selected.
-Otherwise, the crostool can be selected using the
-[`--android_crosstool_top`](#android-crosstool-top)
-or [`--crosstool_top`](#crosstool-top) flags.
+#### `--android_platforms={{ "<var>" }}platform[,platform]*{{ "</var>" }}` {:#android-platforms}
+
+The platforms to build the transitive `deps` of
+`android_binary` rules (specifically for native dependencies like C++). For
+example, if a `cc_library` appears in the transitive `deps` of an
+`android_binary` rule it is be built once for each platform specified with
+`--android_platforms` for the `android_binary` rule, and included in the final
+output.
+
+There is no default value for this flag: a custom Android platform must be
+defined and used.
+
+One `.so` file is created and packaged in the APK for each platform specified
+with `--android_platforms`. The `.so` file's name prefixes the name of the
+`android_binary` rule with "lib". For example, if the name of the
+`android_binary` is "foo", then the file is `libfoo.so`.
 
 #### `--per_file_copt={{ "<var>" }}[+-]regex[,[+-]regex]...@option[,option]...{{ "</var>" }}` {:#per-file-copt}
 
@@ -645,11 +638,13 @@ objc_*, ios__*, and apple_* rules. For those targets, this flag overwrites
 
 #### `--android_crosstool_top={{ "<var>" }}label{{ "</var>" }}` {:#android-crosstool-top}
 
+Warning: `--android_crosstool_top` is deprecated. There is no need to set this.
+
 The crosstool to use for compiling C/C++ rules in the transitive `deps` of
 `android_binary` rules. This is useful if other targets in the
 build require a different crosstool. The default is to use the crosstool
 generated by the `android_ndk_repository` rule in the WORKSPACE file.
-See also [`--fat_apk_cpu`](#fat-apk-cpu).
+See also [`--android_platforms`](#android-platforms).
 
 #### `--compiler={{ "<var>" }}version{{ "</var>" }}` {:#compiler}
 
@@ -663,6 +658,8 @@ and target CPU are allowed.
 
 #### `--android_sdk={{ "<var>" }}label{{ "</var>" }}` {:#android-sdk}
 
+Deprecated. This shouldn't be directly specified.
+
 This option specifies the Android SDK/platform toolchain
 and Android runtime library that will be used to build any Android-related
 rule.