From e5d25bc2169bc3ec14a4771cb75ec95dbe6479e2 Mon Sep 17 00:00:00 2001
From: Andrew Brown <andrew.brown@intel.com>
Date: Thu, 8 Jul 2021 18:09:29 -0700
Subject: [PATCH] [doc] Add some documentation for debugging

The previous documentation only covers how to enable debug info when
embedding Wasmtime. This change should cover the commonly-asked
question: how do I debug in Wasmtime?
---
 docs/SUMMARY.md            |  1 +
 docs/examples-debugging.md | 24 ++++++++++++++++++++++++
 2 files changed, 25 insertions(+)
 create mode 100644 docs/examples-debugging.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index de377d2032..5da2ba403b 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -6,6 +6,7 @@
   - [Running `hello-world.wasm`](./tutorial-run-hello-world.md)
 - [Examples](./examples.md)
   - [Markdown Parser](./examples-markdown.md)
+  - [Debugging WebAssembly](./examples-debugging.md)
   - [Profiling WebAssembly](./examples-profiling.md)
     - [Profiling with Perf](./examples-profiling-perf.md)
     - [Profiling with VTune](./examples-profiling-vtune.md)
diff --git a/docs/examples-debugging.md b/docs/examples-debugging.md
new file mode 100644
index 0000000000..c8b4733d5d
--- /dev/null
+++ b/docs/examples-debugging.md
@@ -0,0 +1,24 @@
+# Debugging WebAssembly
+
+The following steps describe a common way to debug a WebAssembly module in
+Wasmtime:
+
+1. Compile your WebAssembly with debug info enabled, usually `-g`; for
+   example: 
+
+    ```sh
+    clang foo.c -g -o foo.wasm
+    ```
+
+2. Run Wasmtime with the debug info enabled; this is `-g` from the CLI and
+   `Config::debug_info(true)` in an embedding (e.g. see [debugging in a Rust
+   embedding](./examples-rust-debugging.md))
+
+3. Use a supported debugger:
+
+    ```sh
+    lldb -- wasmtime run -g foo.wasm
+    ```
+    ```sh
+    gdb --args wasmtime run -g foo.wasm
+    ```