Rollup merge of #101340 - andrewpollack:fuchsia-zxdb-docs, r=tmandry

Adding Fuchsia zxdb debugging walkthrough to docs

Adding `zxdb` docs to walkthrough to show debugging steps

diff --combined src/doc/rustc/src/platform-support/fuchsia.md
index 1d5ad3cce1840bd44930b80f62e83642b88d84b1,470f065a655ca52bb4bb4c08855ae0752dfb5adb..1ff6003c121cd51f2b2079e2f106796a9f7297c1
--- 1/src/doc/rustc/src/platform-support/fuchsia.md
--- 2/src/doc/rustc/src/platform-support/fuchsia.md
+++ b/src/doc/rustc/src/platform-support/fuchsia.md
@@@ -42,6 -42,11 +42,11 @@@ authoritative if this occurs. Instead o
  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
  
@@@ -136,7 -141,7 +141,7 @@@ 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 kernel
+ * `-Lnative=${SDK_PATH}/arch/${ARCH}/sysroot/lib`: Link against Fuchsia sysroot
    libraries from the SDK
  
  In total, our new project will look like:
@@@ -253,7 -258,7 +258,7 @@@ the following options
    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
+ * `-Lnative ${SDK_PATH}/arch/${ARCH}/sysroot/lib`: Link against Fuchsia sysroot
    libraries from the SDK
  
  Putting it all together:
@@@ -422,7 -427,6 +427,7 @@@ Next, we'll build a package manifest a
  
  ```sh
  ${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 \
@@@ -639,6 -643,130 +644,130 @@@ available on the [Fuchsia devsite]
  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
@@@ -649,3 -777,7 +778,7 @@@
  [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/