Rollup merge of #104465 - djkoloski:improve_fuchsia_testing_docs, r=tmandry

Document more settings for building rustc for Fuchsia

This documents that you need to link for Fuchsia with `lld` and provides configuration settings for both `clang` and `lld`. It also adjusts the documentation for running the test suite to recommend installing to a prefix.

r? ``@tmandry``

2 files changed, 60 insertions, 23 deletions

diff --git a/src/ci/docker/scripts/fuchsia-test-runner.py b/src/ci/docker/scripts/fuchsia-test-runner.py
index a2708d16947..a2708d16947 100644..100755
--- a/src/ci/docker/scripts/fuchsia-test-runner.py
+++ b/src/ci/docker/scripts/fuchsia-test-runner.py
diff --git a/src/doc/rustc/src/platform-support/fuchsia.md b/src/doc/rustc/src/platform-support/fuchsia.md
index 5de29b35e6b..fbf999f9715 100644
--- a/src/doc/rustc/src/platform-support/fuchsia.md
+++ b/src/doc/rustc/src/platform-support/fuchsia.md
@@ -189,17 +189,45 @@ Fuchsia as well. A recent version (14+) of clang should be sufficient to compile
 Rust for Fuchsia.
 
 x86-64 and AArch64 Fuchsia targets can be enabled using the following
-configuration.
-
-In `config.toml`, add:
+configuration in `config.toml`:
 
 ```toml
 [build]
 target = ["<host_platform>", "aarch64-fuchsia", "x86_64-fuchsia"]
+
+[rust]
+lld = true
+
+[target.x86_64-fuchsia]
+cc = "clang"
+cxx = "clang++"
+
+[target.aarch64-fuchsia]
+cc = "clang"
+cxx = "clang++"
+```
+
+Though not strictly required, you may also want to use `clang` for your host
+target as well:
+
+```toml
+[target.<host_platform>]
+cc = "clang"
+cxx = "clang++"
+```
+
+By default, the Rust compiler installs itself to `/usr/local` on most UNIX
+systems. You may want to install it to another location (e.g. a local `install`
+directory) by setting a custom prefix in `config.toml`:
+
+```toml
+[install]
+# Make sure to use the absolute path to your install directory
+prefix = "<RUST_SRC_PATH>/install"
 ```
 
-Additionally, the following environment variables must be configured (for
-example, using a script like `config-env.sh`):
+Next, the following environment variables must be configured. For example, using
+a script we name `config-env.sh`:
 
 ```sh
 # Configure this environment variable to be the path to the downloaded SDK
@@ -215,8 +243,11 @@ export LDFLAGS_x86_64_fuchsia="--target=x86_64-fuchsia --sysroot=${SDK_PATH}/arc
 export CARGO_TARGET_X86_64_FUCHSIA_RUSTFLAGS="-C link-arg=--sysroot=${SDK_PATH}/arch/x64/sysroot -Lnative=${SDK_PATH}/arch/x64/sysroot/lib -Lnative=${SDK_PATH}/arch/x64/lib"
 ```
 
-These can be run together in a shell environment by executing
-`(source config-env.sh && ./x.py install)`.
+Finally, the Rust compiler can be built and installed:
+
+```sh
+(source config-env.sh && ./x.py install)
+```
 
 Once `rustc` is installed, we can create a new working directory to work from,
 `hello_fuchsia` along with `hello_fuchsia/src`:
@@ -641,31 +672,38 @@ available on the [Fuchsia devsite].
 
 ### Running the compiler test suite
 
-Pre-requisites for running the Rust test suite on Fuchsia are:
-1. Checkout of Rust source.
-1. Setup of `config-env.sh` and `config.toml` from "[Targeting Fuchsia with a compiler built from source](#targeting-fuchsia-with-a-compiler-built-from-source)".
-1. Download of the Fuchsia SDK. Minimum supported SDK version is [9.20220726.1.1](https://chrome-infra-packages.appspot.com/p/fuchsia/sdk/core/linux-amd64/+/version:9.20220726.1.1)
+The commands in this section assume that they are being run from inside your
+local Rust source checkout:
+
+```sh
+cd ${RUST_SRC_PATH}
+```
+
+To run the Rust test suite on an emulated Fuchsia device, you must install the
+Rust compiler locally. See "[Targeting Fuchsia with a compiler built from source](#targeting-fuchsia-with-a-compiler-built-from-source)"
+for the steps to build locally.
 
-Interfacing with the Fuchsia emulator is handled by our test runner script located
-at `${RUST_SRC_PATH}/src/ci/docker/scripts/fuchsia-test-runner.py`.
+You'll also need to download a copy of the Fuchsia SDK. The current minimum
+supported SDK version is [9.20220726.1.1](https://chrome-infra-packages.appspot.com/p/fuchsia/sdk/core/linux-amd64/+/version:9.20220726.1.1).
 
-We start by activating our Fuchsia test environment. From a terminal:
+Fuchsia's test runner interacts with the Fuchsia emulator and is located at
+`src/ci/docker/scripts/fuchsia-test-runner.py`. We can use it to start our
+test environment with:
 
-**Issue command from ${RUST_SRC_PATH}**
 ```sh
 src/ci/docker/scripts/fuchsia-test-runner.py start
-    --rust .
+    --rust ${RUST_SRC_PATH}/install
     --sdk ${SDK_PATH}
     --target-arch {x64,arm64}
 ```
 
-Next, for ease of commands, we copy `config-env.sh` and `config.toml` into our Rust source
-code path, `${RUST_SRC_PATH}`.
+Where `${RUST_SRC_PATH}/install` is the `prefix` set in `config.toml` and
+`${SDK_PATH}` is the path to the downloaded and unzipped SDK.
 
-From there, we utilize `x.py` to run our tests, using the test runner script to
-run the tests on our emulator. To run the full `src/test/ui` test suite:
+Once our environment is started, we can run our tests using `x.py` as usual. The
+test runner script will run the compiled tests on an emulated Fuchsia device. To
+run the full `src/test/ui` test suite:
 
-**Run from ${RUST_SRC_PATH}**
 ```sh
 ( \
     source config-env.sh &&                                                   \
@@ -695,9 +733,8 @@ run the tests on our emulator. To run the full `src/test/ui` test suite:
 *Note: The test suite cannot be run in parallel at the moment, so `x.py`
 must be run with `--jobs 1` to ensure only one test runs at a time.*
 
-When finished, stop the test environment:
+When finished, the test runner can be used to stop the test environment:
 
-**Issue command from ${RUST_SRC_PATH}**
 ```sh
 src/ci/docker/scripts/fuchsia-test-runner.py stop
 ```