Expand --help output for addr2line command (#2329)

catamorphism · web-flow · commit 3d53e00981d6 · 2025-10-03T15:45:39.000Z
Add example usage section.
diff --git a/src/bin/wasm-tools/addr2line.rs b/src/bin/wasm-tools/addr2line.rs
@@ -19,6 +19,55 @@ use wasm_tools::addr2line::Addr2lineModules;
 /// address is an inlined function into another function. Frames are printed
 /// innermost or youngest first.
 #[derive(clap::Parser)]
+#[clap(after_help = "\
+Examples:
+
+Suppose foo.wat is as follows:
+
+(module
+  (func $\"dwarf(name)\"
+(;@18;)  i32.const 0
+(;@1a;)  drop
+  )
+
+  (func $another-function
+(;@1e;)  i32.const 0
+(;@20;)  drop
+  )
+)
+
+    # Parse foo.wat to binary form and then print filename
+    # and line number information for four addresses in the binary
+    # (that is, byte offsets).
+    # Each line of output shows the requested address, then the name of
+    # the function enclosing this address, then the source filename and
+    # beginning and endling line numbers.
+    $ wasm-tools addr2line --generate-dwarf lines foo.wat 0x18 0x1a 0x1e 0x20
+0x18: dwarf(name) foo.wat:3:10
+0x1a: dwarf(name) foo.wat:4:10
+0x1e: another-function foo.wat:8:10
+0x20: another-function foo.wat:9:10
+
+Suppose foo.c was compiled to a .wasm file called foo.wasm. (foo.c not shown.)
+
+    # Print filename and line number information for two addresses.
+    $ target/debug/wasm-tools addr2line --generate-dwarf lines foo.wasm 0xff 0x200
+0xff: main foo.c:14:0
+0x200: main foo.c:22:9
+
+The output shows that both offsets are in the `main()` function, but at different
+line numbers.
+
+    # Print filename and line number information for two addresses (specified as decimals),
+    # interpreting the addresses relative to the beginning of the code section.
+    $ target/debug/wasm-tools addr2line --generate-dwarf lines --code-section-relative foo.wasm 255 512
+0xff: main foo.c:21:9
+0x200: main foo.c:25:9
+
+The output shows how the addresses correspond to different source locations
+if interpreted relative to the beginning of the code section.
+
+")]
 pub struct Opts {
     #[clap(flatten)]
     generate_dwarf: wasm_tools::GenerateDwarfArg,
diff --git a/tests/cli/help-addr2line-short.wat b/tests/cli/help-addr2line-short.wat
@@ -0,0 +1 @@
+;; RUN: addr2line -h
diff --git a/tests/cli/help-addr2line-short.wat.stdout b/tests/cli/help-addr2line-short.wat.stdout
@@ -0,0 +1,78 @@
+Translate a WebAssembly address to a filename and line number using DWARF
+debugging information
+
+Usage: wasm-tools addr2line [OPTIONS] [INPUT] [ADDRESSES]...
+
+Arguments:
+  [INPUT]         Input file to process
+  [ADDRESSES]...  Addresses to convert to filenames and line numbers
+
+Options:
+      --generate-dwarf <lines|full>
+          Optionally generate DWARF debugging information from WebAssembly text
+          files
+  -g
+          Shorthand for `--generate-dwarf full`
+  -o, --output <OUTPUT>
+          Where to place output
+  -v, --verbose...
+          Use verbose output (-v info, -vv debug, -vvv trace)
+      --color <COLOR>
+          Configuration over whether terminal colors are used in output
+          [default: auto]
+      --code-section-relative
+          Indicates that addresses are code-section-relative instead of offsets
+          from the beginning of the module
+  -h, --help
+          Print help (see more with '--help')
+
+Examples:
+
+Suppose foo.wat is as follows:
+
+(module
+  (func $"dwarf(name)"
+(;@18;)  i32.const 0
+(;@1a;)  drop
+  )
+
+  (func $another-function
+(;@1e;)  i32.const 0
+(;@20;)  drop
+  )
+)
+
+    # Parse foo.wat to binary form and then print filename
+    # and line number information for four addresses in the binary
+    # (that is, byte offsets).
+    # Each line of output shows the requested address, then the name of
+    # the function enclosing this address, then the source filename and
+    # beginning and endling line numbers.
+    $ wasm-tools addr2line --generate-dwarf lines foo.wat 0x18 0x1a 0x1e 0x20
+0x18: dwarf(name) foo.wat:3:10
+0x1a: dwarf(name) foo.wat:4:10
+0x1e: another-function foo.wat:8:10
+0x20: another-function foo.wat:9:10
+
+Suppose foo.c was compiled to a .wasm file called foo.wasm. (foo.c not shown.)
+
+    # Print filename and line number information for two addresses.
+    $ target/debug/wasm-tools addr2line --generate-dwarf lines foo.wasm 0xff
+    0x200
+0xff: main foo.c:14:0
+0x200: main foo.c:22:9
+
+The output shows that both offsets are in the `main()` function, but at
+different
+line numbers.
+
+    # Print filename and line number information for two addresses (specified as
+    decimals),
+    # interpreting the addresses relative to the beginning of the code section.
+    $ target/debug/wasm-tools addr2line --generate-dwarf lines
+    --code-section-relative foo.wasm 255 512
+0xff: main foo.c:21:9
+0x200: main foo.c:25:9
+
+The output shows how the addresses correspond to different source locations
+if interpreted relative to the beginning of the code section.
diff --git a/tests/cli/help-addr2line.wat b/tests/cli/help-addr2line.wat
@@ -0,0 +1 @@
+;; RUN: addr2line --help
diff --git a/tests/cli/help-addr2line.wat.stdout b/tests/cli/help-addr2line.wat.stdout
@@ -0,0 +1,125 @@
+Translate a WebAssembly address to a filename and line number using DWARF
+debugging information.
+
+WebAssembly binaries compiled with Clang can have DWARF debug information
+inserted into them to map from WebAssembly instruction offsets to original
+filenames and line numbers. For example when compiling C the `-g` argument can
+be used or when compiling Rust the `-Cdebuginfo=1` argument can be used (or the
+default `dev` profile for Cargo). This subcommand will parse the DWARF debugging
+information and translate a list of addresses to their original filenames and
+line numbers.
+
+Each address may have multiple lines printed for it indicating that the address
+is an inlined function into another function. Frames are printed innermost or
+youngest first.
+
+Usage: wasm-tools addr2line [OPTIONS] [INPUT] [ADDRESSES]...
+
+Arguments:
+  [INPUT]
+          Input file to process.
+          
+          If not provided or if this is `-` then stdin is read entirely and
+          processed. Note that for most subcommands this input can either be a
+          binary `*.wasm` file or a textual format `*.wat` file.
+
+  [ADDRESSES]...
+          Addresses to convert to filenames and line numbers.
+          
+          Arguments can be specified as either `0x...` or `@...` in hexadecimal
+          or are otherwise parsed as a base-10 address. Addresses should be
+          relative to the beginning of the module unless
+          `--code-section-relative` is passed in which case they should be
+          relative to the beginning of the contents of the code section.
+
+Options:
+      --generate-dwarf <lines|full>
+          Optionally generate DWARF debugging information from WebAssembly text
+          files.
+          
+          When the input to this command is a WebAssembly text file, such as
+          `*.wat`, then this option will instruct the text parser to insert
+          DWARF debugging information to map binary locations back to the
+          original source locations in the input `*.wat` file. This option has
+          no effect if the `INPUT` argument is already a WebAssembly binary or
+          if the text format uses `(module binary ...)`.
+
+  -g
+          Shorthand for `--generate-dwarf full`
+
+  -o, --output <OUTPUT>
+          Where to place output.
+          
+          Required when printing WebAssembly binary output.
+          
+          If not provided, then stdout is used.
+
+  -v, --verbose...
+          Use verbose output (-v info, -vv debug, -vvv trace)
+
+      --color <COLOR>
+          Configuration over whether terminal colors are used in output.
+          
+          Supports one of `auto|never|always|always-ansi`. The default is to
+          detect what to do based on the terminal environment, for example by
+          using `isatty`.
+          
+          [default: auto]
+
+      --code-section-relative
+          Indicates that addresses are code-section-relative instead of offsets
+          from the beginning of the module
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+Examples:
+
+Suppose foo.wat is as follows:
+
+(module
+  (func $"dwarf(name)"
+(;@18;)  i32.const 0
+(;@1a;)  drop
+  )
+
+  (func $another-function
+(;@1e;)  i32.const 0
+(;@20;)  drop
+  )
+)
+
+    # Parse foo.wat to binary form and then print filename
+    # and line number information for four addresses in the binary
+    # (that is, byte offsets).
+    # Each line of output shows the requested address, then the name of
+    # the function enclosing this address, then the source filename and
+    # beginning and endling line numbers.
+    $ wasm-tools addr2line --generate-dwarf lines foo.wat 0x18 0x1a 0x1e 0x20
+0x18: dwarf(name) foo.wat:3:10
+0x1a: dwarf(name) foo.wat:4:10
+0x1e: another-function foo.wat:8:10
+0x20: another-function foo.wat:9:10
+
+Suppose foo.c was compiled to a .wasm file called foo.wasm. (foo.c not shown.)
+
+    # Print filename and line number information for two addresses.
+    $ target/debug/wasm-tools addr2line --generate-dwarf lines foo.wasm 0xff
+    0x200
+0xff: main foo.c:14:0
+0x200: main foo.c:22:9
+
+The output shows that both offsets are in the `main()` function, but at
+different
+line numbers.
+
+    # Print filename and line number information for two addresses (specified as
+    decimals),
+    # interpreting the addresses relative to the beginning of the code section.
+    $ target/debug/wasm-tools addr2line --generate-dwarf lines
+    --code-section-relative foo.wasm 255 512
+0xff: main foo.c:21:9
+0x200: main foo.c:25:9
+
+The output shows how the addresses correspond to different source locations
+if interpreted relative to the beginning of the code section.
