Restore missing Building with Platforms docs.

Also update to correct mailing lists.

Fixes #11581.

PiperOrigin-RevId: 315890712

site/docs/platforms-intro.md

@@ -302,12 +302,128 @@ If you're designing rules for a new language, we *strongly* encourage you to use
 platforms to select your language's toolchains. See
 the [toolchains documentation](toolchains.html) for a good walkthrough.
 
-[bazel-configurability@google.com](https://groups.google.com/a/google.com/g/bazel-configurability).
+### `select()`
+Projects can [`select()`](configurable-attributes.html) on
+[`constraint_value`](be/platform.html#constraint_value)s but not complete
+platforms. This is intentional: we want `select()`s to support as wide a variety
+of machines as possible. A library with `ARM`-specific sources should support
+*all* `ARM`-powered machines unless there's reason to be more specific.
+
+To select on one or more `constraint_value`s, use
+
+```python
+config_setting(
+    name = "is_arm",
+    constraint_values = [
+        "@platforms//cpu:arm",
+    ],
+)
+```
+
+This is equivalent to traditionally selecting on `--cpu`:
+
+```python
+config_setting(
+    name = "is_arm",
+    values = {
+        "cpu": "arm",
+    },
+)
+```
+
+More details [here](configurable-attributes.html#platforms).
+
+`select`s on `--cpu`, `--crosstool_top`, etc. don't understand `--platforms`. When
+migrating your project to platforms, you must either convert them to
+`constraint_values` or use [platform mappings](#platform-mappings) to support
+both styles through the migration window.
+
+### Transitions
+[Starlark transitions](skylark/config.html#user-defined-transitions) change
+flags down parts of your build graph. If your project uses a transition that
+sets `--cpu`, `--crossstool_top`, or other legacy flags, rules that read
+`--platforms` won't see these changes.
+
+When migrating your project to platforms, you must either convert changes like
+`return { "//command_line_option:cpu": "arm" }` to `return {
+"//command_line_options:platforms": "//:my_arm_platform" }` or use [platform
+mappings](#platform-mappings) to support both styles through the migration
+window.
+
+## How to use platforms today
+If you just want to build or cross-compile a project, you should follow the
+project's official documentation. It's up to language and project maintainers to
+determine how and when to integrate with platforms, and what value that offers.
+
+If you're a project, language, or toolchain maintainer and your build doesn't
+use platforms by default, you have three options (besides waiting for the global
+migration):
+
+1. Flip on the "use platforms" flag for your project's languages ([if they have
+   one](#status)) and do whatever testing you need to see if the projects you care
+   about work.
+
+1. If the projects you care about still depend on legacy flags like `--cpu` and
+   `--crosstool_top`, use these together with `--platforms`:
+
+
+   `$ bazel build //:my_mixed_project --platforms==//:myplatform
+   --cpu=... --crosstool_top=...`
+
+    This has some maintenance cost (you have to manually make sure the settings
+    match). But this should work in the absense of renegade
+    [transitions](#transitions).
+
+1. Write [platform mappings](#platform-mappings) to support both styles by
+   mapping `--cpu`-style settings to corresponding platforms and vice versa.
+
+### Platform mappings
+*Platform mappings* is a temporary API that lets platform-powered and
+legacy-powered logic co-exist in the same build through the latter's deprecation
+window.
+
+A platform mapping is a map of either a `platform()` to a
+corresponding set of legacy flags or the reverse. For example:
+
+```python
+platforms:
+  # Maps "--platforms=//platforms:ios" to "--cpu=ios_x86_64 --apple_platform_type=ios".
+  //platforms:ios
+    --cpu=ios_x86_64
+    --apple_platform_type=ios
+
+flags:
+  # Maps "--cpu=ios_x86_64 --apple_platform_type=ios" to "--platforms=//platforms:ios".
+  --cpu=ios_x86_64
+  --apple_platform_type=ios
+    //platforms:ios
+
+  # Maps "--cpu=darwin --apple_platform_type=macos" to "//platform:macos".
+  --cpu=darwin
+  --apple_platform_type=macos
+    //platforms:macos
+```
+
+Bazel uses this to guarantee all settings, both platform-based and
+legacy, are consistently applied throughout the build, including through
+[transitions](#transitions).
+
+By default Bazel reads mappings from the `platform_mappings` file in your
+workspace root. You can also set
+`--platform_mappings=//:my_custom_mapping`.
+
+See
+[here](https://docs.google.com/document/d/1Vg_tPgiZbSrvXcJ403vZVAGlsWhH9BUDrAxMOYnO0Ls/edit)
+for complete details.
+
+## Questions
+For general support and questions about the migration timeline, contact
+[bazel-discuss@googlegroups.com](https://groups.google.com/forum/#!forum/bazel-discuss)
 or the owners of the appropriate rules.
 
 For discussions on the design and evolution of the platform/toolchain APIs,
 contact
-[bazel-configurability@google.com](https://groups.google.com/a/google.com/g/bazel-configurability).
+[bazel-dev@googlegroups.com](https://groups.google.com/forum/#!forum/bazel-dev).
 
 ## See also