Implement DWARF support in text-to-binary (#1632)

* Implement DWARF support in text-to-binary

This commit implements support to emit DWARF debugging information when
the WebAssembly text format is converted to binary. Currently there is
otherwise no means of translating a binary offset in a WebAssembly file
back to the text format that it came from. This support is implemented
with a few API knobs here and there as well as two new CLI flags for all
the commands that support the text format as input: `-g` and
`--generate-dwarf lines|full`.

The original motivation of this commit is that I was curious to learn more
about DWARF and it seemed like a neat little feature that wouldn't be too hard
to maintain. The inspiration was bytecodealliance/wasmtime#8658 which this does
not implement as-is (e.g.  not custom DWARF, just wasm-text-DWARF). Otherwise
though I've realized that this can be useful for development in a few
situations:

* Wasmtime's backtraces can now mention filenames/line numbers of the
  WebAssembly text format.
* Validation errors can use `addr2line` to print a filename/line number
  of a WebAssembly text file.
* Wasmtime doesn't have a native debugger nor does LLDB/GDB know about
  WebAssembly. Through Wasmtime's DWARF transformation this enables
  debugging WebAssembly text files.

This commit implements knobs for "full" or "line" support in DWARF. The
"line" support should be as complete as it can be (DWARF can only
provide information for the code section). The "full" support is
somewhat basic still but my hope is that it can be expanded in the
future as needed.

* Fix a compile warning

Author: alexcrichton

Cargo.lock

@@ -85,6 +85,7 @@ hashbrown = { version = "0.14.3", default-features = false, features = ['ahash']
 ahash = { version = "0.8.11", default-features = false }
 termcolor = "1.2.0"
 indoc = "2.0.5"
+gimli = "0.29.0"
 
 wasm-compose = { version = "0.211.1", path = "crates/wasm-compose" }
 wasm-encoder = { version = "0.211.1", path = "crates/wasm-encoder" }
@@ -108,7 +109,7 @@ log = { workspace = true }
 clap = { workspace = true }
 clap_complete = { workspace = true, optional = true }
 tempfile = "3.2.0"
-wat = { workspace = true }
+wat = { workspace = true, features = ['dwarf'] }
 termcolor = { workspace = true }
 
 # Dependencies of `validate`
@@ -156,7 +157,7 @@ wit-smith = { workspace = true, features = ["clap"], optional = true }
 
 # Dependencies of `addr2line`
 addr2line = { version = "0.22.0", optional = true }
-gimli = { version = "0.29.0", optional = true }
+gimli = { workspace = true, optional = true }
 
 [target.'cfg(not(target_family = "wasm"))'.dependencies]
 is_executable = { version = "1.0.1", optional = true }
@@ -200,7 +201,7 @@ default = [
 ]
 
 # Each subcommand is gated behind a feature and lists the dependencies it needs
-validate = ['dep:wasmparser', 'rayon']
+validate = ['dep:wasmparser', 'rayon', 'dep:addr2line', 'dep:gimli']
 print = []
 parse = []
 smith = ['wasm-smith', 'arbitrary', 'dep:serde', 'dep:serde_derive', 'dep:serde_json']

Cargo.toml

@@ -13,6 +13,9 @@ Customizable Rust parsers for the WebAssembly Text formats WAT and WAST
 """
 rust-version.workspace = true
 
+[package.metadata.docs.rs]
+all-features = true
+
 [lints]
 workspace = true
 
@@ -22,12 +25,14 @@ unicode-width = "0.1.9"
 memchr = "2.4.1"
 wasm-encoder = { workspace = true }
 bumpalo = "3.14.0"
+gimli = { workspace = true, optional = true }
 
 [dev-dependencies]
 anyhow = { workspace = true }
 libtest-mimic = { workspace = true }
 wasmparser = { path = "../wasmparser" }
 wat = { path = "../wat" }
+rand = { workspace = true }
 
 [features]
 default = ['wasm-module']
@@ -40,6 +45,11 @@ default = ['wasm-module']
 # This feature is turned on by default.
 wasm-module = []
 
+# Off-by-default feature to support emitting DWARF debugging information in
+# parsed binaries pointing back to source locations in the original `*.wat`
+# source.
+dwarf = ["dep:gimli"]
+
 [[test]]
 name = "parse-fail"
 harness = false

crates/wast/Cargo.toml

@@ -1,7 +1,7 @@
 //! Types and support for parsing the component model text format.
 
 mod alias;
-mod binary;
+pub(crate) mod binary;
 mod component;
 mod custom;
 mod expand;

crates/wast/src/component.rs

@@ -1,5 +1,6 @@
 use crate::component::*;
 use crate::core;
+use crate::core::EncodeOptions;
 use crate::token::{Id, Index, NameAnnotation, Span};
 use wasm_encoder::{
     CanonicalFunctionSection, ComponentAliasSection, ComponentDefinedTypeEncoder,
@@ -9,10 +10,10 @@ use wasm_encoder::{
     NestedComponentSection, RawSection, SectionId,
 };
 
-pub fn encode(component: &Component<'_>) -> Vec<u8> {
+pub fn encode(component: &Component<'_>, options: &EncodeOptions) -> Vec<u8> {
     match &component.kind {
         ComponentKind::Text(fields) => {
-            encode_fields(&component.id, &component.name, fields).finish()
+            encode_fields(&component.id, &component.name, fields, options).finish()
         }
         ComponentKind::Binary(bytes) => bytes.iter().flat_map(|b| b.iter().copied()).collect(),
     }
@@ -23,15 +24,16 @@ fn encode_fields(
     component_id: &Option<Id<'_>>,
     component_name: &Option<NameAnnotation<'_>>,
     fields: &[ComponentField<'_>],
+    options: &EncodeOptions,
 ) -> wasm_encoder::Component {
     let mut e = Encoder::default();
 
     for field in fields {
         match field {
-            ComponentField::CoreModule(m) => e.encode_core_module(m),
+            ComponentField::CoreModule(m) => e.encode_core_module(m, options),
             ComponentField::CoreInstance(i) => e.encode_core_instance(i),
             ComponentField::CoreType(t) => e.encode_core_type(t),
-            ComponentField::Component(c) => e.encode_component(c),
+            ComponentField::Component(c) => e.encode_component(c, options),
             ComponentField::Instance(i) => e.encode_instance(i),
             ComponentField::Alias(a) => e.encode_alias(a),
             ComponentField::Type(t) => e.encode_type(t),
@@ -191,7 +193,7 @@ impl<'a> Encoder<'a> {
         })
     }
 
-    fn encode_core_module(&mut self, module: &CoreModule<'a>) {
+    fn encode_core_module(&mut self, module: &CoreModule<'a>, options: &EncodeOptions) {
         // Flush any in-progress section before encoding the module
         self.flush(None);
 
@@ -202,7 +204,7 @@ impl<'a> Encoder<'a> {
             CoreModuleKind::Import { .. } => unreachable!("should be expanded already"),
             CoreModuleKind::Inline { fields } => {
                 // TODO: replace this with a wasm-encoder based encoding (should return `wasm_encoder::Module`)
-                let data = crate::core::binary::encode(&module.id, &module.name, fields);
+                let data = crate::core::binary::encode(&module.id, &module.name, fields, options);
                 self.component.section(&RawSection {
                     id: ComponentSectionId::CoreModule.into(),
                     data: &data,
@@ -238,7 +240,7 @@ impl<'a> Encoder<'a> {
         self.flush(Some(self.core_types.id()));
     }
 
-    fn encode_component(&mut self, component: &NestedComponent<'a>) {
+    fn encode_component(&mut self, component: &NestedComponent<'a>, options: &EncodeOptions) {
         self.component_names
             .push(get_name(&component.id, &component.name));
         // Flush any in-progress section before encoding the component
@@ -252,6 +254,7 @@ impl<'a> Encoder<'a> {
                         &component.id,
                         &component.name,
                         fields,
+                        options,
                     )));
             }
         }

crates/wast/src/component/binary.rs

@@ -86,8 +86,7 @@ impl<'a> Component<'a> {
     /// This function can return an error for name resolution errors and other
     /// expansion-related errors.
     pub fn encode(&mut self) -> std::result::Result<Vec<u8>, crate::Error> {
-        self.resolve()?;
-        Ok(crate::component::binary::encode(self))
+        crate::core::EncodeOptions::default().encode_component(self)
     }
 
     pub(crate) fn validate(&self, parser: Parser<'_>) -> Result<()> {

crates/wast/src/component/component.rs

@@ -12,6 +12,7 @@ mod table;
 mod tag;
 mod types;
 mod wast;
+pub use self::binary::{EncodeOptions, GenerateDwarf};
 pub use self::custom::*;
 pub use self::export::*;
 pub use self::expr::*;