12 files changed, 770 insertions, 117 deletions
diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md
index d168af60c..d9d430c20 100644
--- a/src/doc/rustc/src/SUMMARY.md
+++ b/src/doc/rustc/src/SUMMARY.md
@@ -18,6 +18,8 @@
     - [aarch64-apple-ios-sim](platform-support/aarch64-apple-ios-sim.md)
     - [\*-apple-watchos\*](platform-support/apple-watchos.md)
     - [aarch64-nintendo-switch-freestanding](platform-support/aarch64-nintendo-switch-freestanding.md)
+    - [armeb-unknown-linux-gnueabi](platform-support/armeb-unknown-linux-gnueabi.md)
+    - [armv4t-none-eabi](platform-support/armv4t-none-eabi.md)
     - [armv6k-nintendo-3ds](platform-support/armv6k-nintendo-3ds.md)
     - [armv7-unknown-linux-uclibceabi](platform-support/armv7-unknown-linux-uclibceabi.md)
     - [armv7-unknown-linux-uclibceabihf](platform-support/armv7-unknown-linux-uclibceabihf.md)
diff --git a/src/doc/rustc/src/instrument-coverage.md b/src/doc/rustc/src/instrument-coverage.md
index 0ae9e53af..38fd5c969 100644
--- a/src/doc/rustc/src/instrument-coverage.md
+++ b/src/doc/rustc/src/instrument-coverage.md
@@ -97,7 +97,17 @@ $ echo "{some: 'thing'}" | target/debug/examples/formatjson5 -
 }
 ```
 
-After running this program, a new file, `default.profraw`, should be in the current working directory. It's often preferable to set a specific file name or path. You can change the output file using the environment variable `LLVM_PROFILE_FILE`:
+After running this program, a new file named like `default_11699812450447639123_0_20944` should be in the current working directory.
+A new, unique file name will be generated each time the program is run to avoid overwriting previous data.
+
+```shell
+$ echo "{some: 'thing'}" | target/debug/examples/formatjson5 -
+...
+$ ls default_*.profraw
+default_11699812450447639123_0_20944.profraw
+```
+
+You can also set a specific file name or path for the generated `.profraw` files by using the environment variable `LLVM_PROFILE_FILE`:
 
 ```shell
 $ echo "{some: 'thing'}" \
@@ -115,6 +125,9 @@ If `LLVM_PROFILE_FILE` contains a path to a non-existent directory, the missing
 -   `%Nm` - the instrumented binary’s signature: The runtime creates a pool of N raw profiles, used for on-line profile merging. The runtime takes care of selecting a raw profile from the pool, locking it, and updating it before the program exits. `N` must be between `1` and `9`, and defaults to `1` if omitted (with simply `%m`).
 -   `%c` - Does not add anything to the filename, but enables a mode (on some platforms, including Darwin) in which profile counter updates are continuously synced to a file. This means that if the instrumented program crashes, or is killed by a signal, perfect coverage information can still be recovered.
 
+In the first example above, the value `11699812450447639123_0` in the generated filename is the instrumented binary's signature,
+which replaced the `%m` pattern and the value `20944` is the process ID of the binary being executed.
+
 ## Installing LLVM coverage tools
 
 LLVM's supplies two tools—`llvm-profdata` and `llvm-cov`—that process coverage data and generate reports. There are several ways to find and/or install these tools, but note that the coverage mapping data generated by the Rust compiler requires LLVM version 12 or higher, and processing the *raw* data may require exactly the LLVM version used by the compiler. (`llvm-cov --version` typically shows the tool's LLVM version number, and `rustc --verbose --version` shows the version of LLVM used by the Rust compiler.)
@@ -181,11 +194,10 @@ A typical use case for coverage analysis is test coverage. Rust's source-based c
 
 The following example (using the [`json5format`] crate, for demonstration purposes) show how to generate and analyze coverage results for all tests in a crate.
 
-Since `cargo test` both builds and runs the tests, we set both the additional `RUSTFLAGS`, to add the `-C instrument-coverage` flag, and `LLVM_PROFILE_FILE`, to set a custom filename for the raw profiling data generated during the test runs. Since there may be more than one test binary, apply `%m` in the filename pattern. This generates unique names for each test binary. (Otherwise, each executed test binary would overwrite the coverage results from the previous binary.)
+Since `cargo test` both builds and runs the tests, we set the additional `RUSTFLAGS`, to add the `-C instrument-coverage` flag.
 
 ```shell
 $ RUSTFLAGS="-C instrument-coverage" \
-    LLVM_PROFILE_FILE="json5format-%m.profraw" \
     cargo test --tests
 ```
 
@@ -210,7 +222,7 @@ test result: ok. 31 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
 You should have one or more `.profraw` files now, one for each test binary. Run the `profdata` tool to merge them:
 
 ```shell
-$ llvm-profdata merge -sparse json5format-*.profraw -o json5format.profdata
+$ llvm-profdata merge -sparse default_*.profraw -o json5format.profdata
 ```
 
 Then run the `cov` tool, with the `profdata` file and all test binaries:
@@ -230,6 +242,8 @@ $ llvm-cov show \
     --Xdemangler=rustfilt | less -R
 ```
 
+> **Note**: If overriding the default `profraw` file name via the `LLVM_PROFILE_FILE` environment variable, it's highly recommended to use the `%m` and `%p` special pattern strings to generate unique file names in the case of more than a single test binary being executed.
+
 > **Note**: The command line option `--ignore-filename-regex=/.cargo/registry`, which excludes the sources for dependencies from the coverage results.\_
 
 ### Tips for listing the binaries automatically
@@ -271,9 +285,8 @@ To include doc tests in the coverage results, drop the `--tests` flag, and apply
 ```bash
 $ RUSTFLAGS="-C instrument-coverage" \
   RUSTDOCFLAGS="-C instrument-coverage -Z unstable-options --persist-doctests target/debug/doctestbins" \
-  LLVM_PROFILE_FILE="json5format-%m.profraw" \
     cargo test
-$ llvm-profdata merge -sparse json5format-*.profraw -o json5format.profdata
+$ llvm-profdata merge -sparse default_*.profraw -o json5format.profdata
 ```
 
 The `-Z unstable-options --persist-doctests` flag is required, to save the test binaries
@@ -302,8 +315,7 @@ $ llvm-cov report \
 > version without doc tests, include:
 
 -   The `cargo test ... --no-run` command is updated with the same environment variables
-    and flags used to _build_ the tests, _including_ the doc tests. (`LLVM_PROFILE_FILE`
-    is only used when _running_ the tests.)
+    and flags used to _build_ the tests, _including_ the doc tests.
 -   The file glob pattern `target/debug/doctestbins/*/rust_out` adds the `rust_out`
     binaries generated for doc tests (note, however, that some `rust_out` files may not
     be executable binaries).
diff --git a/src/doc/rustc/src/linker-plugin-lto.md b/src/doc/rustc/src/linker-plugin-lto.md
index 9c644dd40..b1854b22a 100644
--- a/src/doc/rustc/src/linker-plugin-lto.md
+++ b/src/doc/rustc/src/linker-plugin-lto.md
@@ -30,7 +30,7 @@ Using `rustc` directly:
 # Compile the Rust staticlib
 rustc --crate-type=staticlib -Clinker-plugin-lto -Copt-level=2 ./lib.rs
 # Compile the C code with `-flto=thin`
-clang -c -O2 -flto=thin -o main.o ./main.c
+clang -c -O2 -flto=thin -o cmain.o ./cmain.c
 # Link everything, making sure that we use an appropriate linker
 clang -flto=thin -fuse-ld=lld -L . -l"name-of-your-rust-lib" -o main -O2 ./cmain.o
 ```
@@ -41,7 +41,7 @@ Using `cargo`:
 # Compile the Rust staticlib
 RUSTFLAGS="-Clinker-plugin-lto" cargo build --release
 # Compile the C code with `-flto=thin`
-clang -c -O2 -flto=thin -o main.o ./main.c
+clang -c -O2 -flto=thin -o cmain.o ./cmain.c
 # Link everything, making sure that we use an appropriate linker
 clang -flto=thin -fuse-ld=lld -L . -l"name-of-your-rust-lib" -o main -O2 ./cmain.o
 ```
diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md
index 01489e9aa..3a6963ebc 100644
--- a/src/doc/rustc/src/platform-support.md
+++ b/src/doc/rustc/src/platform-support.md
@@ -213,7 +213,7 @@ target | std | host | notes
 [`aarch64-pc-windows-gnullvm`](platform-support/pc-windows-gnullvm.md) | ✓ | ✓ |
 `aarch64-unknown-freebsd` | ✓ | ✓ | ARM64 FreeBSD
 `aarch64-unknown-hermit` | ✓ |  | ARM64 HermitCore
-`aarch64-unknown-uefi` | * |  | ARM64 UEFI
+[`aarch64-unknown-uefi`](platform-support/unknown-uefi.md) | * |  | ARM64 UEFI
 `aarch64-unknown-linux-gnu_ilp32` | ✓ | ✓ | ARM64 Linux (ILP32 ABI)
 `aarch64-unknown-netbsd` | ✓ | ✓ |
 [`aarch64-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | ARM64 OpenBSD
@@ -223,6 +223,8 @@ target | std | host | notes
 `aarch64_be-unknown-linux-gnu_ilp32` | ✓ | ✓ | ARM64 Linux (big-endian, ILP32 ABI)
 `aarch64_be-unknown-linux-gnu` | ✓ | ✓ | ARM64 Linux (big-endian)
 [`arm64_32-apple-watchos`](platform-support/apple-watchos.md) | ✓ | | ARM Apple WatchOS 64-bit with 32-bit pointers
+[`armeb-unknown-linux-gnueabi`](platform-support/armeb-unknown-linux-gnueabi.md) | ✓ | ? | ARM BE8 the default ARM big-endian architecture since [ARMv6](https://developer.arm.com/documentation/101754/0616/armlink-Reference/armlink-Command-line-Options/--be8?lang=en).
+`armv4t-none-eabi` | * |  | ARMv4T A32
 `armv4t-unknown-linux-gnueabi` | ? |  |
 `armv5te-unknown-linux-uclibceabi` | ? |  | ARMv5TE Linux with uClibc
 `armv6-unknown-freebsd` | ✓ | ✓ | ARMv6 FreeBSD
@@ -249,7 +251,7 @@ target | std | host | notes
 `i686-unknown-haiku` | ✓ | ✓ | 32-bit Haiku
 `i686-unknown-netbsd` | ✓ | ✓ | NetBSD/i386 with SSE2
 [`i686-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | 32-bit OpenBSD
-`i686-unknown-uefi` | * |  | 32-bit UEFI
+[`i686-unknown-uefi`](platform-support/unknown-uefi.md) | * |  | 32-bit UEFI
 `i686-uwp-windows-gnu` | ? |  |
 `i686-uwp-windows-msvc` | ? |  |
 `i686-wrs-vxworks` | ? |  |
@@ -276,6 +278,7 @@ target | std | host | notes
 `powerpc64-unknown-linux-musl` | ? |  |
 `powerpc64-wrs-vxworks` | ? |  |
 `powerpc64le-unknown-linux-musl` | ? |  |
+[`powerpc64-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | OpenBSD/powerpc64
 `riscv32gc-unknown-linux-gnu` |   |   | RISC-V Linux (kernel 5.4, glibc 2.33)
 `riscv32gc-unknown-linux-musl` |   |   | RISC-V Linux (kernel 5.4, musl + RISCV32 support patches)
 `riscv32im-unknown-none-elf` | * |  | Bare RISC-V (RV32IM ISA)
@@ -283,6 +286,7 @@ target | std | host | notes
 `riscv32imc-esp-espidf` | ✓ |  | RISC-V ESP-IDF
 `riscv64gc-unknown-freebsd` |   |   | RISC-V FreeBSD
 `riscv64gc-unknown-linux-musl` |   |   | RISC-V Linux (kernel 4.20, musl 1.2.0)
+[`riscv64gc-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | OpenBSD/riscv64
 `s390x-unknown-linux-musl` |  |  | S390x Linux (kernel 3.2, MUSL)
 `sparc-unknown-linux-gnu` | ✓ |  | 32-bit SPARC Linux
 `sparc64-unknown-netbsd` | ✓ | ✓ | NetBSD/sparc64
@@ -304,7 +308,7 @@ target | std | host | notes
 `x86_64-unknown-l4re-uclibc` | ? |  |
 `x86_64-unknown-none-linuxkernel` | * |  | Linux kernel modules
 [`x86_64-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | 64-bit OpenBSD
-`x86_64-unknown-uefi` | * |  | 64-bit UEFI
+[`x86_64-unknown-uefi`](platform-support/unknown-uefi.md) | * |  | 64-bit UEFI
 `x86_64-uwp-windows-gnu` | ✓ |  |
 `x86_64-uwp-windows-msvc` | ✓ |  |
 `x86_64-wrs-vxworks` | ? |  |
diff --git a/src/doc/rustc/src/platform-support/armeb-unknown-linux-gnueabi.md b/src/doc/rustc/src/platform-support/armeb-unknown-linux-gnueabi.md
new file mode 100644
index 000000000..507631cdc
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/armeb-unknown-linux-gnueabi.md
@@ -0,0 +1,74 @@
+# armeb-unknown-linux-gnueabi
+**Tier: 3**
+
+Target for cross-compiling Linux user-mode applications targetting the ARM BE8 architecture.
+
+## Overview
+BE8 architecture retains the same little-endian ordered code-stream used by conventional little endian ARM systems, however the data accesses are in big-endian. BE8 is used primarily in high-performance networking applications where the ability to read packets in their native "Network Byte Order" is important (many network protocols transmit data in big-endian byte order for their wire formats).
+
+## History
+BE8 architecture is the default big-endian architecture for ARM since [ARMv6](https://developer.arm.com/documentation/101754/0616/armlink-Reference/armlink-Command-line-Options/--be8?lang=en). It's predecessor, used for ARMv4 and ARMv5 devices was [BE32](https://developer.arm.com/documentation/dui0474/j/linker-command-line-options/--be32). On ARMv6 architecture, endianness can be configured via [system registers](https://developer.arm.com/documentation/ddi0290/g/unaligned-and-mixed-endian-data-access-support/mixed-endian-access-support/interaction-between-the-bus-protocol-and-the-core-endianness). However, BE32 was withdrawn for [ARMv7](https://developer.arm.com/documentation/ddi0406/cb/Appendixes/Deprecated-and-Obsolete-Features/Obsolete-features/Support-for-BE-32-endianness-model) onwards.
+
+## Target Maintainers
+* [@WorksButNotTested](https://github.com/WorksButNotTested)
+
+## Requirements
+The target is cross-compiled. This target supports `std` in the normal way (indeed only nominal changes are required from the standard ARM configuration).
+
+## Target definition
+The target definition can be seen [here](https://github.com/rust-lang/rust/tree/master/compiler/rustc_target/src/spec/armeb_unknown_linux_gnueabi.rs). In particular, it should be noted that the `features` specify that this target is built for the ARMv8 core. Though this can likely be modified as required.
+
+## Building the target
+Because it is Tier 3, rust does not yet ship pre-compiled artifacts for this target.
+
+Therefore, you can build Rust with support for the target by adding it to the target list in config.toml, a sample configuration is shown below. It is expected that the user already have a working GNU compiler toolchain and update the paths accordingly.
+
+```toml
+[llvm]
+download-ci-llvm = false
+skip-rebuild = true
+optimize = true
+ninja = true
+targets = "ARM;X86"
+clang = false
+
+[build]
+target = ["x86_64-unknown-linux-gnu", "armeb-unknown-linux-gnueabi"]
+docs = false
+docs-minification = false
+compiler-docs = false
+[install]
+prefix = "/home/user/x-tools/rust/"
+
+[rust]
+debug-logging=true
+backtrace = true
+incremental = true
+
+[target.x86_64-unknown-linux-gnu]
+
+[dist]
+
+[target.armeb-unknown-linux-gnueabi]
+cc = "/home/user/x-tools/armeb-unknown-linux-gnueabi/bin/armeb-unknown-linux-gnueabi-gcc"
+cxx = "/home/user/x-tools/armeb-unknown-linux-gnueabi/bin/armeb-unknown-linux-gnueabi-g++"
+ar = "/home/user/x-tools/armeb-unknown-linux-gnueabi/bin/armeb-unknown-linux-gnueabi-ar"
+ranlib = "/home/user/x-tools/armeb-unknown-linux-gnueabi/bin/armeb-unknown-linux-gnueabi-ranlib"
+linker = "/home/user/x-tools/armeb-unknown-linux-gnueabi/bin/armeb-unknown-linux-gnueabi-gcc"
+llvm-config = "/home/user/x-tools/clang/bin/llvm-config"
+llvm-filecheck = "/home/user/x-tools/clang/bin/FileCheck"
+```
+
+## Building Rust programs
+
+The following `.cargo/config` is needed inside any project directory to build for the BE8 target:
+
+```toml
+[build]
+target = "armeb-unknown-linux-gnueabi"
+
+[target.armeb-unknown-linux-gnueabi]
+linker = "armeb-unknown-linux-gnueabi-gcc"
+```
+
+Note that it is expected that the user has a suitable linker from the GNU toolchain.
diff --git a/src/doc/rustc/src/platform-support/armv4t-none-eabi.md b/src/doc/rustc/src/platform-support/armv4t-none-eabi.md
new file mode 100644
index 000000000..cf831e159
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/armv4t-none-eabi.md
@@ -0,0 +1,70 @@
+# armv4t-none-eabi
+
+Tier 3
+
+Bare-metal target for any cpu in the ARMv4T architecture family, supporting
+ARM/Thumb code interworking (aka `a32`/`t32`), with ARM code as the default code
+generation.
+
+In particular this supports the Gameboy Advance (GBA), but there's nothing GBA
+specific with this target, so any ARMv4T device should work fine.
+
+## Target Maintainers
+
+* [@Lokathor](https://github.com/lokathor)
+
+## Requirements
+
+The target is cross-compiled, and uses static linking.
+
+The linker that comes with rustc cannot link for this platform (the platform is
+too old). You will need the `arm-none-eabi-ld` linker from a GNU Binutils
+targeting ARM. This can be obtained for Windows/Mac/Linux from the [ARM
+Developer Website][arm-dev], or possibly from your OS's package manager.
+
+[arm-dev]: https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain
+
+This target doesn't provide a linker script, you'll need to bring your own
+according to the specific device you want to target. Pass
+`-Clink-arg=-Tyour_script.ld` as a rustc argument to make the linker use
+`your_script.ld` during linking.
+
+## Building Rust Programs
+
+Because it is Tier 3, rust does not yet ship pre-compiled artifacts for this target.
+
+Just use the `build-std` nightly cargo feature to build the `core` library. You
+can pass this as a command line argument to cargo, or your `.cargo/config.toml`
+file might include the following lines:
+
+```toml
+[unstable]
+build-std = ["core"]
+```
+
+Most of `core` should work as expected, with the following notes:
+* the target is "soft float", so `f32` and `f64` operations are emulated in
+  software.
+* integer division is also emulated in software.
+* the target is old enough that it doesn't have atomic instructions.
+
+Rust programs are output as ELF files.
+
+For running on hardware, you'll generally need to extract the "raw" program code
+out of the ELF and into a file of its own. The `objcopy` program provided as
+part of the GNU Binutils can do this:
+
+```shell
+arm-none-eabi-objcopy --output-target binary [in_file] [out_file]
+```
+
+## Testing
+
+This is a cross-compiled target that you will need to emulate during testing.
+
+Because this is a device-agnostic target, and the exact emulator that you'll
+need depends on the specific device you want to run your code on.
+
+For example, when programming for the Gameboy Advance, the
+[mgba-test-runner](https://github.com/agbrs/agb) program could be used to make a
+normal set of rust tests be run within the `mgba` emulator.
diff --git a/src/doc/rustc/src/platform-support/fuchsia.md b/src/doc/rustc/src/platform-support/fuchsia.md
index 61bd1b425..1ff6003c1 100644
--- a/src/doc/rustc/src/platform-support/fuchsia.md
+++ b/src/doc/rustc/src/platform-support/fuchsia.md
@@ -5,14 +5,10 @@
 [Fuchsia] is a modern open source operating system that's simple, secure,
 updatable, and performant.
 
-[Fuchsia]: https://fuchsia.dev/
-
 ## Target maintainers
 
 The [Fuchsia team]:
 
-[Fuchsia team]: https://team-api.infra.rust-lang.org/v1/teams/fuchsia.json
-
 - Tyler Mandry ([@tmandry](https://github.com/tmandry))
 - Dan Johnson ([@computerdruid](https://github.com/computerdruid))
 - David Koloski ([@djkoloski](https://github.com/djkoloski))
@@ -24,27 +20,174 @@ the members reported by the API. The API should be considered to be
 authoritative if this occurs. Instead of pinging individual members, use
 `@rustbot ping fuchsia` to contact the team on GitHub.
 
+## Table of contents
+
+1. [Requirements](#requirements)
+1. [Walkthrough structure](#walkthrough-structure)
+1. [Compiling a Rust binary targeting Fuchsia](#compiling-a-rust-binary-targeting-fuchsia)
+    1. [Targeting Fuchsia with rustup and cargo](#targeting-fuchsia-with-rustup-and-cargo)
+    1. [Targeting Fuchsia with a compiler built from source](#targeting-fuchsia-with-a-compiler-built-from-source)
+1. [Creating a Fuchsia package](#creating-a-fuchsia-package)
+    1. [Creating a Fuchsia component](#creating-a-fuchsia-component)
+    1. [Building a Fuchsia package](#building-a-fuchsia-package)
+1. [Publishing a Fuchsia package](#publishing-a-fuchsia-package)
+    1. [Creating a Fuchsia package repository](#creating-a-fuchsia-package-repository)
+    1. [Publishing Fuchsia package to repository](#publishing-fuchsia-package-to-repository)
+1. [Running a Fuchsia component on an emulator](#running-a-fuchsia-component-on-an-emulator)
+    1. [Starting the Fuchsia emulator](#starting-the-fuchsia-emulator)
+    1. [Watching emulator logs](#watching-emulator-logs)
+    1. [Serving a Fuchsia package](#serving-a-fuchsia-package)
+    1. [Running a Fuchsia component](#running-a-fuchsia-component)
+1. [`.gitignore` extensions](#gitignore-extensions)
+1. [Testing](#testing)
+    1. [Running unit tests](#running-unit-tests)
+    1. [Running the compiler test suite](#running-the-compiler-test-suite)
+1. [Debugging](#debugging)
+    1. [`zxdb`](#zxdb)
+    1. [Attaching `zxdb`](#attaching-zxdb)
+    1. [Using `zxdb`](#using-zxdb)
+    1. [Displaying source code in `zxdb`](#displaying-source-code-in-zxdb)
+
 ## Requirements
 
-This target is cross-compiled from a host environment. Development may be done
-from the [source tree] or using the Fuchsia SDK.
+This target is cross-compiled from a host environment. You will need a recent
+copy of the [Fuchsia SDK], which provides the tools, libraries, and binaries
+required to build and link programs for Fuchsia.
 
-[source tree]: https://fuchsia.dev/fuchsia-src/get-started/learn/build
+Development may also be done from the [source tree].
 
-Fuchsia targets support std and follow the `sysv64` calling convention on
+Fuchsia targets support `std` and follow the `sysv64` calling convention on
 x86_64. Fuchsia binaries use the ELF file format.
 
-## Building the target
+## Walkthrough structure
+
+This walkthrough will cover:
+
+1. Compiling a Rust binary targeting Fuchsia.
+1. Building a Fuchsia package.
+1. Publishing and running a Fuchsia package to a Fuchsia emulator.
+
+For the purposes of this walkthrough, we will only target `x86_64-fuchsia`.
+
+## Compiling a Rust binary targeting Fuchsia
+
+Today, there are two main ways to build a Rust binary targeting Fuchsia
+using the Fuchsia SDK:
+1. Allow [rustup] to handle the installation of Fuchsia targets for you.
+1. Build a toolchain locally that can target Fuchsia.
+
+### Targeting Fuchsia with rustup and cargo
+
+The easiest way to build a Rust binary targeting Fuchsia is by allowing [rustup]
+to handle the installation of Fuchsia targets for you. This can be done by issuing
+the following commands:
+
+```sh
+rustup target add x86_64-fuchsia
+rustup target add aarch64-fuchsia
+```
+
+After installing our Fuchsia targets, we can now compile a Rust binary that targets
+Fuchsia.
+
+To create our Rust project, we can issue a standard `cargo` command as follows:
+
+**From base working directory**
+```sh
+cargo new hello_fuchsia
+```
+
+The rest of this walkthrough will take place from `hello_fuchsia`, so we can
+change into that directory now:
+
+```sh
+cd hello_fuchsia
+```
+
+*Note: From this point onwards, all commands will be issued from the `hello_fuchsia/`
+directory, and all `hello_fuchsia/` prefixes will be removed from references for sake of brevity.*
+
+We can edit our `src/main.rs` to include a test as follows:
+
+**`src/main.rs`**
+```rust
+fn main() {
+    println!("Hello Fuchsia!");
+}
+
+#[test]
+fn it_works() {
+    assert_eq!(2 + 2, 4);
+}
+```
+
+In addition to the standard workspace created, we will want to create a
+`.cargo/config.toml` file to link necessary libraries
+during compilation:
+
+**`.cargo/config.toml`**
+```txt
+[target.x86_64-fuchsia]
+
+rustflags = [
+    "-Lnative=<SDK_PATH>/arch/x64/lib",
+    "-Lnative=<SDK_PATH>/arch/x64/sysroot/lib"
+]
+```
+
+*Note: Make sure to fill out `<SDK_PATH>` with the path to the downloaded [Fuchsia SDK].*
+
+These options configure the following:
+
+* `-Lnative=${SDK_PATH}/arch/${ARCH}/lib`: Link against Fuchsia libraries from
+  the SDK
+* `-Lnative=${SDK_PATH}/arch/${ARCH}/sysroot/lib`: Link against Fuchsia sysroot
+  libraries from the SDK
+
+In total, our new project will look like:
+
+**Current directory structure**
+```txt
+hello_fuchsia/
+┣━ src/
+┃  ┗━ main.rs
+┣━ Cargo.toml
+┗━ .cargo/
+   ┗━ config.toml
+```
+
+Finally, we can build our rust binary as:
+
+```sh
+cargo build --target x86_64-fuchsia
+```
+
+Now we have a Rust binary at `target/x86_64-fuchsia/debug/hello_fuchsia`,
+targeting our desired Fuchsia target.
+
+**Current directory structure**
+```txt
+hello_fuchsia/
+┣━ src/
+┃  ┗━ main.rs
+┣━ target/
+┃  ┗━ x86_64-fuchsia/
+┃     ┗━ debug/
+┃        ┗━ hello_fuchsia
+┣━ Cargo.toml
+┗━ .cargo/
+   ┗━ config.toml
+```
+
+### Targeting Fuchsia with a compiler built from source
+
+An alternative to the first workflow is to target Fuchsia by using
+`rustc` built from source.
 
 Before building Rust for Fuchsia, you'll need a clang toolchain that supports
 Fuchsia as well. A recent version (14+) of clang should be sufficient to compile
 Rust for Fuchsia.
 
-You'll also need a recent copy of the [Fuchsia SDK], which provides the tools
-and binaries required to build and link programs for Fuchsia.
-
-[Fuchsia SDK]: https://chrome-infra-packages.appspot.com/p/fuchsia/sdk/core
-
 x86-64 and AArch64 Fuchsia targets can be enabled using the following
 configuration.
 
@@ -53,12 +196,6 @@ In `config.toml`, add:
 ```toml
 [build]
 target = ["<host_platform>", "aarch64-fuchsia", "x86_64-fuchsia"]
-
-[target.x86_64-fuchsia]
-llvm-libunwind = "in-tree"
-
-[target.aarch64-fuchsia]
-llvm-libunwind = "in-tree"
 ```
 
 Additionally, the following environment variables must be configured (for
@@ -81,15 +218,21 @@ export CARGO_TARGET_X86_64_FUCHSIA_RUSTFLAGS="-C link-arg=--sysroot=${SDK_PATH}/
 These can be run together in a shell environment by executing
 `(source config-env.sh && ./x.py install)`.
 
-## Building Rust programs
+Once `rustc` is installed, we can create a new working directory to work from,
+`hello_fuchsia` along with `hello_fuchsia/src`:
 
-After compiling Rust binaries, you'll need to build a component, package it, and
-serve it to a Fuchsia device or emulator. All of this can be done using the
-Fuchsia SDK.
+```sh
+mkdir hello_fuchsia
+cd hello_fuchsia
+mkdir src
+```
+
+*Note: From this point onwards, all commands will be issued from the `hello_fuchsia/`
+directory, and all `hello_fuchsia/` prefixes will be removed from references for sake of brevity.*
 
-As an example, we'll compile and run this simple program on a Fuchsia emulator:
+There, we can create a new file named `src/hello_fuchsia.rs`:
 
-**`hello_fuchsia.rs`**
+**`src/hello_fuchsia.rs`**
 ```rust
 fn main() {
     println!("Hello Fuchsia!");
@@ -101,45 +244,113 @@ fn it_works() {
 }
 ```
 
-Create a new file named `hello_fuchsia.rs` and fill out its contents with that
-code.
+**Current directory structure**
+```txt
+hello_fuchsia/
+┗━ src/
+    ┗━ hello_fuchsia.rs
+```
+
+Using your freshly installed `rustc`, you can compile a binary for Fuchsia using
+the following options:
+
+* `--target x86_64-fuchsia`/`--target aarch64-fuchsia`: Targets the Fuchsia
+  platform of your choice
+* `-Lnative ${SDK_PATH}/arch/${ARCH}/lib`: Link against Fuchsia libraries from
+  the SDK
+* `-Lnative ${SDK_PATH}/arch/${ARCH}/sysroot/lib`: Link against Fuchsia sysroot
+  libraries from the SDK
 
-### Create a package
+Putting it all together:
 
+```sh
+# Configure these for the Fuchsia target of your choice
+TARGET_ARCH="<x86_64-fuchsia|aarch64-fuchsia>"
+ARCH="<x64|aarch64>"
+
+rustc \
+    --target ${TARGET_ARCH} \
+    -Lnative=${SDK_PATH}/arch/${ARCH}/lib \
+    -Lnative=${SDK_PATH}/arch/${ARCH}/sysroot/lib \
+    --out-dir bin src/hello_fuchsia.rs
+```
+
+**Current directory structure**
+```txt
+hello_fuchsia/
+┣━ src/
+┃   ┗━ hello_fuchsia.rs
+┗━ bin/
+   ┗━ hello_fuchsia
+```
+
+## Creating a Fuchsia package
+
+Before moving on, double check your directory structure:
+
+**Current directory structure**
+```txt
+hello_fuchsia/
+┣━ src/                     (if using rustc)
+┃   ┗━ hello_fuchsia.rs     ...
+┣━ bin/                     ...
+┃  ┗━ hello_fuchsia         ...
+┣━ src/                     (if using cargo)
+┃  ┗━ main.rs               ...
+┗━ target/                  ...
+   ┗━ x86_64-fuchsia/       ...
+      ┗━ debug/             ...
+         ┗━ hello_fuchsia   ...
+```
+
+With our Rust binary built, we can move to creating a Fuchsia package.
 On Fuchsia, a package is the unit of distribution for software. We'll need to
 create a new package directory where we will place files like our finished
-binary and any data it may need. The working directory will have this layout:
+binary and any data it may need.
+
+To start, make the `pkg`, and `pkg/meta` directories:
+
+```sh
+mkdir pkg
+mkdir pkg/meta
+```
 
+**Current directory structure**
 ```txt
-hello_fuchsia.rs
-hello_fuchsia.cml
-package
-┣━ bin
-┃  ┗━ hello_fuchsia
-┣━ meta
-┃  ┣━ package
-┃  ┗━ hello_fuchsia.cm
-┗━ hello_fuchsia.manifest
+hello_fuchsia/
+┗━ pkg/
+   ┗━ meta/
 ```
 
-Make the `package`, `package/bin`, and `package/meta` directories and create the
-following files inside:
+Now, create the following files inside:
 
-**`package/meta/package`**
+**`pkg/meta/package`**
 ```json
-{"name":"hello_fuchsia","version":0}
+{
+  "name": "hello_fuchsia",
+  "version": "0"
+}
 ```
 
 The `package` file describes our package's name and version number. Every
 package must contain one.
 
-**`package/hello_fuchsia.manifest`**
+**`pkg/hello_fuchsia.manifest` if using cargo**
+```txt
+bin/hello_fuchsia=target/x86_64-fuchsia/debug/hello_fuchsia
+lib/ld.so.1=<SDK_PATH>/arch/x64/sysroot/dist/lib/ld.so.1
+lib/libfdio.so=<SDK_PATH>/arch/x64/dist/libfdio.so
+meta/package=pkg/meta/package
+meta/hello_fuchsia.cm=pkg/meta/hello_fuchsia.cm
+```
+
+**`pkg/hello_fuchsia.manifest` if using rustc**
 ```txt
-bin/hello_fuchsia=package/bin/hello_fuchsia
+bin/hello_fuchsia=bin/hello_fuchsia
 lib/ld.so.1=<SDK_PATH>/arch/x64/sysroot/dist/lib/ld.so.1
 lib/libfdio.so=<SDK_PATH>/arch/x64/dist/libfdio.so
-meta/package=package/meta/package
-meta/hello_fuchsia.cm=package/meta/hello_fuchsia.cm
+meta/package=pkg/meta/package
+meta/hello_fuchsia.cm=pkg/meta/hello_fuchsia.cm
 ```
 
 *Note: Relative manifest paths are resolved starting from the working directory
@@ -147,42 +358,26 @@ of `pm`. Make sure to fill out `<SDK_PATH>` with the path to the downloaded
 SDK.*
 
 The `.manifest` file will be used to describe the contents of the package by
-relating their location when installed to their location on the file system. You
-can use this to make a package pull files from other places, but for this
-example we'll just be placing everything in the `package` directory.
-
-### Compiling a binary
-
-Using your freshly compiled `rustc`, you can compile a binary for Fuchsia using
-the following options:
+relating their location when installed to their location on the file system. The
+`bin/hello_fuchsia=` entry will be different depending on how your Rust binary
+was built, so choose accordingly.
 
-* `--target x86_64-fuchsia`/`--target aarch64-fuchsia`: Targets the Fuchsia
-  platform of your choice
-* `-Lnative ${SDK_PATH}/arch/${ARCH}/lib`: Link against Fuchsia libraries from
-  the SDK
-* `-Lnative ${SDK_PATH}/arch/${ARCH}/sysroot/lib`: Link against Fuchsia kernel
-  libraries from the SDK
-
-Putting it all together:
-
-```sh
-# Configure these for the Fuchsia target of your choice
-TARGET_ARCH="<x86_64-fuchsia|aarch64-fuchsia>"
-ARCH="<x64|aarch64>"
-
-rustc --target ${TARGET_ARCH} -Lnative=${SDK_PATH}/arch/${ARCH}/lib -Lnative=${SDK_PATH}/arch/${ARCH}/sysroot/lib -o package/bin/hello_fuchsia hello_fuchsia.rs
+**Current directory structure**
+```txt
+hello_fuchsia/
+┗━ pkg/
+   ┣━ meta/
+   ┃  ┗━ package
+   ┗━ hello_fuchsia.manifest
 ```
 
-### Bulding a component
+### Creating a Fuchsia component
 
-On Fuchsia, components require a component manifest written in Fuchia's markup
+On Fuchsia, components require a component manifest written in Fuchsia's markup
 language called CML. The Fuchsia devsite contains an [overview of CML] and a
 [reference for the file format]. Here's a basic one that can run our single binary:
 
-[overview of CML]: https://fuchsia.dev/fuchsia-src/concepts/components/v2/component_manifests
-[reference for the file format]: https://fuchsia.dev/reference/cml
-
-**`hello_fuchsia.cml`**
+**`pkg/hello_fuchsia.cml`**
 ```txt
 {
     include: [ "syslog/client.shard.cml" ],
@@ -193,43 +388,154 @@ language called CML. The Fuchsia devsite contains an [overview of CML] and a
 }
 ```
 
+**Current directory structure**
+```txt
+hello_fuchsia/
+┗━ pkg/
+   ┣━ meta/
+   ┃  ┗━ package
+   ┣━ hello_fuchsia.manifest
+   ┗━ hello_fuchsia.cml
+```
+
 Now we can compile that CML into a component manifest:
 
 ```sh
-${SDK_PATH}/tools/${ARCH}/cmc compile hello_fuchsia.cml --includepath ${SDK_PATH}/pkg -o package/meta/hello_fuchsia.cm
+${SDK_PATH}/tools/${ARCH}/cmc compile \
+    pkg/hello_fuchsia.cml \
+    --includepath ${SDK_PATH}/pkg \
+    -o pkg/meta/hello_fuchsia.cm
 ```
 
-`--includepath` tells the compiler where to look for `include`s from our CML.
-In our case, we're only using `syslog/client.shard.cml`.
+*Note: `--includepath` tells the compiler where to look for `include`s from our CML.
+In our case, we're only using `syslog/client.shard.cml`.*
 
-### Building and publishing a package
+**Current directory structure**
+```txt
+hello_fuchsia/
+┗━ pkg/
+   ┣━ meta/
+   ┃  ┣━ package
+   ┃  ┗━ hello_fuchsia.cm
+   ┣━ hello_fuchsia.manifest
+   ┗━ hello_fuchsia.cml
+```
 
-Next, we'll build our package as defined by our manifest:
+### Building a Fuchsia package
+
+Next, we'll build a package manifest as defined by our manifest:
 
 ```sh
-${SDK_PATH}/tools/${ARCH}/pm -o hello_fuchsia -m package/hello_fuchsia.manifest build -output-package-manifest hello_fuchsia_manifest
+${SDK_PATH}/tools/${ARCH}/pm \
+    -api-level $(${SDK_PATH}/tools/${ARCH}/ffx version -v | grep "api-level" | head -1 |  awk -F ' ' '{print $2}') \
+    -o pkg/hello_fuchsia_manifest \
+    -m pkg/hello_fuchsia.manifest \
+    build \
+    -output-package-manifest pkg/hello_fuchsia_package_manifest
+```
+
+This will produce `pkg/hello_fuchsia_manifest/` which is a package manifest we can
+publish directly to a repository.
+
+**Current directory structure**
+```txt
+hello_fuchsia/
+┗━ pkg/
+   ┣━ meta/
+   ┃  ┣━ package
+   ┃  ┗━ hello_fuchsia.cm
+   ┣━ hello_fuchsia_manifest/
+   ┃  ┗━ ...
+   ┣━ hello_fuchsia.manifest
+   ┣━ hello_fuchsia.cml
+   ┗━ hello_fuchsia_package_manifest
 ```
 
-This will produce `hello_fuchsia_manifest` which is a package manifest we can
-publish directly to a repository. We can set up that repository with:
+We are now ready to publish the package.
+
+## Publishing a Fuchsia package
+
+With our package and component manifests setup,
+we can now publish our package. The first step will
+be to create a Fuchsia package repository to publish
+to.
+
+### Creating a Fuchsia package repository
+
+We can set up our repository with:
 
 ```sh
-${SDK_PATH}/tools/${ARCH}/pm newrepo -repo repo
+${SDK_PATH}/tools/${ARCH}/pm newrepo \
+    -repo pkg/repo
 ```
 
-And then publish our new package to that repository with:
+**Current directory structure**
+```txt
+hello_fuchsia/
+┗━ pkg/
+   ┣━ meta/
+   ┃  ┣━ package
+   ┃  ┗━ hello_fuchsia.cm
+   ┣━ hello_fuchsia_manifest/
+   ┃  ┗━ ...
+   ┣━ repo/
+   ┃  ┗━ ...
+   ┣━ hello_fuchsia.manifest
+   ┣━ hello_fuchsia.cml
+   ┗━ hello_fuchsia_package_manifest
+```
+
+## Publishing Fuchsia package to repository
+
+We can publish our new package to that repository with:
 
 ```sh
-${SDK_PATH}/tools/${ARCH}/pm publish -repo repo -lp -f <(echo "hello_fuchsia_manifest")
+${SDK_PATH}/tools/${ARCH}/pm publish \
+    -repo pkg/repo \
+    -lp -f <(echo "pkg/hello_fuchsia_package_manifest")
 ```
 
-Then we can add it to `ffx`'s package server as `hello-fuchsia` using:
+Then we can add the repository to `ffx`'s package server as `hello-fuchsia` using:
 
 ```sh
-${SDK_PATH}/tools/${ARCH}/ffx repository add-from-pm repo -r hello-fuchsia
+${SDK_PATH}/tools/${ARCH}/ffx repository add-from-pm \
+    pkg/repo \
+    -r hello-fuchsia
+```
+
+## Running a Fuchsia component on an emulator
+
+At this point, we are ready to run our Fuchsia
+component. For reference, our final directory
+structure will look like:
+
+**Final directory structure**
+```txt
+hello_fuchsia/
+┣━ src/                     (if using rustc)
+┃   ┗━ hello_fuchsia.rs     ...
+┣━ bin/                     ...
+┃  ┗━ hello_fuchsia         ...
+┣━ src/                     (if using cargo)
+┃  ┗━ main.rs               ...
+┣━ target/                  ...
+┃  ┗━ x86_64-fuchsia/       ...
+┃     ┗━ debug/             ...
+┃        ┗━ hello_fuchsia   ...
+┗━ pkg/
+   ┣━ meta/
+   ┃  ┣━ package
+   ┃  ┗━ hello_fuchsia.cm
+   ┣━ hello_fuchsia_manifest/
+   ┃  ┗━ ...
+   ┣━ repo/
+   ┃  ┗━ ...
+   ┣━ hello_fuchsia.manifest
+   ┣━ hello_fuchsia.cml
+   ┗━ hello_fuchsia_package_manifest
 ```
 
-### Starting the emulator
+### Starting the Fuchsia emulator
 
 Start a Fuchsia emulator in a new terminal using:
 
@@ -238,39 +544,85 @@ ${SDK_PATH}/tools/${ARCH}/ffx product-bundle get workstation_eng.qemu-${ARCH}
 ${SDK_PATH}/tools/${ARCH}/ffx emu start workstation_eng.qemu-${ARCH} --headless
 ```
 
-Then, once the emulator has been started:
+### Watching emulator logs
+
+Once the emulator is running, open a separate terminal to watch the emulator logs:
+
+**In separate terminal**
+```sh
+${SDK_PATH}/tools/${ARCH}/ffx log \
+    --since now
+```
+
+### Serving a Fuchsia package
+
+Now, start a package repository server to serve our
+package to the emulator:
 
 ```sh
-${SDK_PATH}/tools/${ARCH}/ffx target repository register
+${SDK_PATH}/tools/${ARCH}/ffx repository server start
 ```
 
-And watch the logs from the emulator in a separate terminal:
+Once the repository server is up and running, register it with the target Fuchsia system running in the emulator:
 
 ```sh
-${SDK_PATH}/tools/${ARCH}/ffx log --since now
+${SDK_PATH}/tools/${ARCH}/ffx target repository register \
+    --repository hello-fuchsia
 ```
 
+### Running a Fuchsia component
+
 Finally, run the component:
 
 ```sh
-${SDK_PATH}/tools/${ARCH}/ffx component run fuchsia-pkg://hello-fuchsia/hello_fuchsia#meta/hello_fuchsia.cm
+${SDK_PATH}/tools/${ARCH}/ffx component run \
+    /core/ffx-laboratory:hello_fuchsia \
+    fuchsia-pkg://hello-fuchsia/hello_fuchsia_manifest#meta/hello_fuchsia.cm
 ```
 
 On reruns of the component, the `--recreate` argument may also need to be
 passed.
 
+```sh
+${SDK_PATH}/tools/${ARCH}/ffx component run \
+    --recreate \
+    /core/ffx-laboratory:hello_fuchsia \
+    fuchsia-pkg://hello-fuchsia/hello_fuchsia_manifest#meta/hello_fuchsia.cm
+```
+
+## `.gitignore` extensions
+
+Optionally, we can create/extend our `.gitignore` file to ignore files and
+directories that are not helpful to track:
+
+```txt
+pkg/repo
+pkg/meta/hello_fuchsia.cm
+pkg/hello_fuchsia_manifest
+pkg/hello_fuchsia_package_manifest
+```
+
 ## Testing
 
 ### Running unit tests
 
-Tests can be run in the same way as a regular binary, simply by passing `--test`
-to the `rustc` invocation and then repackaging and rerunning. The test harness
-will run the applicable unit tests.
+Tests can be run in the same way as a regular binary.
+
+* If using `cargo`, you can simply pass `test --no-run`
+to the `cargo` invocation and then repackage and rerun the Fuchsia package. From our previous example,
+this would look like `cargo test --target x86_64-fuchsia --no-run`, and moving the executable
+binary path found from the line `Executable unittests src/main.rs (target/x86_64-fuchsia/debug/deps/hello_fuchsia-<HASH>)`
+into `pkg/hello_fuchsia.manifest`.
+
+* If using the compiled `rustc`, you can simply pass `--test`
+to the `rustc` invocation and then repackage and rerun the Fuchsia package.
+
+The test harness will run the applicable unit tests.
 
 Often when testing, you may want to pass additional command line arguments to
 your binary. Additional arguments can be set in the component manifest:
 
-**`hello_fuchsia.cml`**
+**`pkg/hello_fuchsia.cml`**
 ```txt
 {
     include: [ "syslog/client.shard.cml" ],
@@ -285,11 +637,148 @@ your binary. Additional arguments can be set in the component manifest:
 This will pass the argument `it_works` to the binary, filtering the tests to
 only those tests that match the pattern. There are many more configuration
 options available in CML including environment variables. More documentation is
-available on the [Fuchsia devsite](https://fuchsia.dev/reference/cml).
+available on the [Fuchsia devsite].
 
 ### Running the compiler test suite
 
 Running the Rust test suite on Fuchsia is [not currently supported], but work is
 underway to enable it.
 
+## Debugging
+
+### `zxdb`
+
+Debugging components running on a Fuchsia emulator can be done using the
+console-mode debugger: [zxdb]. We will demonstrate attaching necessary symbol
+paths to debug our `hello-fuchsia` component.
+
+### Attaching `zxdb`
+
+In a separate terminal, issue the following command from our `hello_fuchsia`
+directory to launch `zxdb`:
+
+**In separate terminal**
+```sh
+${SDK_PATH}/tools/${ARCH}/ffx debug connect -- \
+    --symbol-path target/x86_64-fuchsia/debug
+```
+
+* `--symbol-path` gets required symbol paths, which are
+necessary for stepping through your program.
+
+The "[displaying source code in `zxdb`](#displaying-source-code-in-zxdb)" section describes how you can
+display Rust and/or Fuchsia source code in your debugging session.
+
+### Using `zxdb`
+
+Once launched, you will be presented with the window:
+
+```sh
+Connecting (use "disconnect" to cancel)...
+Connected successfully.
+👉 To get started, try "status" or "help".
+[zxdb]
+```
+
+To attach to our program, we can run:
+
+```sh
+[zxdb] attach hello_fuchsia
+```
+
+**Expected output**
+```sh
+Waiting for process matching "hello_fuchsia".
+Type "filter" to see the current filters.
+```
+
+Next, we can create a breakpoint at main using "b main":
+
+```sh
+[zxdb] b main
+```
+
+**Expected output**
+```sh
+Created Breakpoint 1 @ main
+```
+
+Finally, we can re-run the "hello_fuchsia" component from our original
+terminal:
+
+```sh
+${SDK_PATH}/tools/${ARCH}/ffx component run \
+    --recreate \
+    fuchsia-pkg://hello-fuchsia/hello_fuchsia_manifest#meta/hello_fuchsia.cm
+```
+
+Once our component is running, our `zxdb` window will stop execution
+in our main as desired:
+
+**Expected output**
+```txt
+Breakpoint 1 now matching 1 addrs for main
+🛑 on bp 1 hello_fuchsia::main() • main.rs:2
+   1 fn main() {
+ ▶ 2     println!("Hello Fuchsia!");
+   3 }
+   4
+[zxdb]
+```
+
+`zxdb` has similar commands to other debuggers like [gdb].
+To list the available commands, run "help" in the
+`zxdb` window or visit [the zxdb documentation].
+
+```sh
+[zxdb] help
+```
+
+**Expected output**
+```sh
+Help!
+
+  Type "help <command>" for command-specific help.
+
+Other help topics (see "help <topic>")
+...
+```
+
+### Displaying source code in `zxdb`
+
+By default, the debugger will not be able to display
+source code while debugging. For our user code, we displayed
+source code by pointing our debugger to our debug binary via
+the `--symbol-path` arg. To display library source code in
+the debugger, you must provide paths to the source using
+`--build-dir`. For example, to display the Rust and Fuchsia
+source code:
+
+```sh
+${SDK_PATH}/tools/${ARCH}/ffx debug connect -- \
+    --symbol-path target/x86_64-fuchsia/debug \
+    --build-dir ${RUST_SRC_PATH}/rust \
+    --build-dir ${FUCHSIA_SRC_PATH}/fuchsia/out/default
+```
+
+ * `--build-dir` links against source code paths, which
+ are not strictly necessary for debugging, but is a nice-to-have
+ for displaying source code in `zxdb`.
+
+ Linking to a Fuchsia checkout can help with debugging Fuchsia libraries,
+ such as [fdio].
+
+[Fuchsia team]: https://team-api.infra.rust-lang.org/v1/teams/fuchsia.json
+[Fuchsia]: https://fuchsia.dev/
+[source tree]: https://fuchsia.dev/fuchsia-src/get-started/learn/build
+[rustup]: https://rustup.rs/
+[cargo]: https://doc.rust-lang.org/cargo/
+[Fuchsia SDK]: https://chrome-infra-packages.appspot.com/p/fuchsia/sdk/core
+[overview of CML]: https://fuchsia.dev/fuchsia-src/concepts/components/v2/component_manifests
+[reference for the file format]: https://fuchsia.dev/reference/cml
+[Fuchsia devsite]: https://fuchsia.dev/reference/cml
 [not currently supported]: https://fxbug.dev/105393
+[zxdb]: https://fuchsia.dev/fuchsia-src/development/debugger
+[gdb]: https://www.sourceware.org/gdb/
+[the zxdb documentation]: https://fuchsia.dev/fuchsia-src/development/debugger
+[fdio]: https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/lib/fdio/
diff --git a/src/doc/rustc/src/platform-support/m68k-unknown-linux-gnu.md b/src/doc/rustc/src/platform-support/m68k-unknown-linux-gnu.md
index d325ba334..b18a125f3 100644
--- a/src/doc/rustc/src/platform-support/m68k-unknown-linux-gnu.md
+++ b/src/doc/rustc/src/platform-support/m68k-unknown-linux-gnu.md
@@ -87,7 +87,7 @@ Rust programs can be built for that target:
 rustc --target m68k-unknown-linux-gnu your-code.rs
 ```
 
-Very simple progams can be run using the `qemu-m68k-static` program:
+Very simple programs can be run using the `qemu-m68k-static` program:
 
 ```text
 $ qemu-m68k-static your-code
diff --git a/src/doc/rustc/src/platform-support/openbsd.md b/src/doc/rustc/src/platform-support/openbsd.md
index b2ac776ea..4ce80157d 100644
--- a/src/doc/rustc/src/platform-support/openbsd.md
+++ b/src/doc/rustc/src/platform-support/openbsd.md
@@ -12,6 +12,8 @@ The target names follow this format: `$ARCH-unknown-openbsd`, where `$ARCH` spec
 |--------------------------------|-------------|------------------|
 | `aarch64-unknown-openbsd`      | libc++      | [64-bit ARM systems](https://www.openbsd.org/arm64.html)  |
 | `i686-unknown-openbsd`         | libc++      | [Standard PC and clones based on the Intel i386 architecture and compatible processors](https://www.openbsd.org/i386.html) |
+| `powerpc64-unknown-openbsd`    | libc++      | [IBM POWER-based PowerNV systems](https://www.openbsd.org/powerpc64.html) |
+| `riscv64gc-unknown-openbsd`    | libc++      | [64-bit RISC-V systems](https://www.openbsd.org/riscv64.html) |
 | `sparc64-unknown-openbsd`      | estdc++     | [Sun UltraSPARC and Fujitsu SPARC64 systems](https://www.openbsd.org/sparc64.html) |
 | `x86_64-unknown-openbsd`       | libc++      | [AMD64-based systems](https://www.openbsd.org/amd64.html) |
 
diff --git a/src/doc/rustc/src/platform-support/pc-windows-gnullvm.md b/src/doc/rustc/src/platform-support/pc-windows-gnullvm.md
index 721c234c6..fb0cea05d 100644
--- a/src/doc/rustc/src/platform-support/pc-windows-gnullvm.md
+++ b/src/doc/rustc/src/platform-support/pc-windows-gnullvm.md
@@ -25,7 +25,7 @@ Like with any other Windows target created binaries are in PE format.
 
 ## Building the target
 
-For cross-compilation I recommend using [llvm-mingw](https://github.com/mstorsjo/llvm-mingw) toolchain, one change that seems necessary beside configuring corss compilers is disabling experimental `m86k` target. Otherwise LLVM build fails with `multiple definition ...` errors.
+For cross-compilation I recommend using [llvm-mingw](https://github.com/mstorsjo/llvm-mingw) toolchain, one change that seems necessary beside configuring cross compilers is disabling experimental `m86k` target. Otherwise LLVM build fails with `multiple definition ...` errors.
 Native bootstrapping builds require rather fragile hacks until host artifacts are available so I won't describe them here.
 
 ## Building Rust programs
diff --git a/src/doc/rustc/src/platform-support/unknown-uefi.md b/src/doc/rustc/src/platform-support/unknown-uefi.md
index 8f90d9c74..295dec0f0 100644
--- a/src/doc/rustc/src/platform-support/unknown-uefi.md
+++ b/src/doc/rustc/src/platform-support/unknown-uefi.md
@@ -133,7 +133,7 @@ There are 3 common ways to compile native C code for UEFI targets:
 - Use native Windows targets. This means compiling your C code for the Windows
   platform as if it was the UEFI platform. This works for static libraries, but
   needs adjustments when linking into an UEFI executable. You can, however,
-  link such static libraries seemlessly into rust code compiled for UEFI
+  link such static libraries seamlessly into rust code compiled for UEFI
   targets. Be wary of any includes that are not specifically suitable for UEFI
   targets (especially the C standard library includes are not always
   compatible). Freestanding compilations are recommended to avoid
diff --git a/src/doc/rustc/src/platform-support/wasm64-unknown-unknown.md b/src/doc/rustc/src/platform-support/wasm64-unknown-unknown.md
index 021b904de..6932e6a57 100644
--- a/src/doc/rustc/src/platform-support/wasm64-unknown-unknown.md
+++ b/src/doc/rustc/src/platform-support/wasm64-unknown-unknown.md
@@ -30,7 +30,7 @@ is 8-bytes large as well as pointers. The tradeoff, though, is that the maximum
 memory size is now the full 64-bit address space instead of the 4GB as limited
 by the 32-bit address space for `wasm32-unknown-unknown`.
 
-This target is not a stable target. The [memory64] WebAssembly proposal is stil
+This target is not a stable target. The [memory64] WebAssembly proposal is still
 in-progress and not standardized. This means that there are not many engines
 which implement the `memory64` feature and if they do they're likely behind a
 flag, for example: