Update Bazel documentation to include information about Xcode selection.
In particular, add info about using the new xcode_config shape with dynamic execution.
@@ -56,3 +56,37 @@ when building your macOS and iOS projects:
* Providers:
* [`ObjcProvider`](skylark/lib/ObjcProvider.html)
+
+## Xcode selection
+
+If your build requires Xcode, Bazel will select an appropriate version based on
+the `--xcode_config` and `--xcode_version` flags. The `--xcode_config` consumes
+the set of available Xcode versions and sets a default version if
+`--xcode_version` is not passed. This default is overridden by the
+`--xcode_version` flag, as long as it is set to an Xcode version that is
+represented in the `--xcode_config` target.
+
+If you do not pass `--xcode_config`, Bazel will use the autogenerated
+[`XcodeVersionConfig`](skylark/lib/XcodeVersionConfig.html) that represents the
+Xcode versions available on your host machine. The default version is
+the newest available Xcode version. This is appropriate for local execution.
+
+If you are performing remote builds, you should set `--xcode_config` to an
+[`xcode_config`](https://docs.bazel.build/versions/master/be/workspace.html#xcode_config)
+target whose `versions` attribute is a list of remotely available
+[`xcode_version`](https://docs.bazel.build/versions/master/be/workspace.html#xcode_version)
+targets, and whose `default` attribute is one of these
+[`xcode_versions`](https://docs.bazel.build/versions/master/be/workspace.html#xcode_version).
+
+If you are using dynamic execution, you should set `--xcode_config` to an
+[`xcode_config`](https://docs.bazel.build/versions/master/be/workspace.html#xcode_config)
+target whose `remote_versions` attribute is an
+[`available_xcodes`](https://docs.bazel.build/versions/master/be/workspace.html#available_xcodes)
+target containing the remotely available Xcode versions, and whose
+`local_versions` attribute is an
+[`available_xcodes`](https://docs.bazel.build/versions/master/be/workspace.html#available_xcodes)
+target containing the locally available Xcode versions. For `local_versions`,
+you probably want to use the autogenerated
+`@local_config_xcode//:host_available_xcodes`. The default Xcode version is the
+newest mutually available version, if there is one, otherwise the default of the
+`local_versions` target.
