mtolmacs/wasm2map

WebAssembly sourcemap generator and WASM binary source mapping url section patcher

Cargo WASM Sourcemap Utility

Generates a browser-supported sourcemap for WASM binaries containing DWARF debug information and associates it with the WASM binary, so when loaded in the browser you can see the rust line, character and source code (if available) in the debug panel and console.

NOTE: Can build without unsafe code (the only unsafe code is related to using the memmap2 crate).

Before

After

Usage

1. Use it with Cargo to manually preprocess your WASM binary before serving:

 cargo install cargo-wasm2map

 # Build your WASM binary the way you usually do
 cargo build --target wasm32-unknown-unknown

# Generate sourcemap for the target WASM (replace myproject with your project
# name).
 cargo wasm2map target/wasm32-unknown-unknown/debug/myproject.wasm \
    -patch -base-url http://localhost:8080

 # Serve the WASM to your browser... (i.e. http://localhost:8080 or wherever
 # your index.html is)

2. Use it as a library in your utility:

use wasm2map::WASM;

let mapper = WASM::load("/path/to/the/file.wasm");
    if let Ok(mut mapper) = mapper {
        let sourcemap = mapper.map_v3(false);
        mapper.patch("http://localhost:8080").expect("Failed to patch");
}

Current limitations

• It does not bundle the source code in the sourcemap currently, so source browsing will not work in the browser

Contribution

Your contributions are welcome, especially bug reports and testing on various platforms. Feel free to open a PR if you can contribute a fix.

If you would like to contribute an API change, extension or a new trait implementation, please open an issue first and discuss before starting work on a PR. For details please read the CONTRIBUTING.md file.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

SPDX-License-Identifier: Apache-2.0 OR MIT

wasm2map's Issues

Generate sourcemap 'names' section

Should support inlined functions.

De-mangle function names if possible

Currently it's easy to compile your debug WASM with some function names, specifically in packages.

Add new API to get source paths used by the generated sourcemap

Background

When the browser can't find the source file in the sourcesContent field (i.e. it's null), it tries to load it from the same base url it downloaded the sourcemap from.

Currently only the sourcemap JSON can be extracted from the lib via its public API. However having access to the list of sources on the implementor side can be used to dynamically serve the files when requested by the browser.

API

Add new instance method to WASM with the following signature

pub fn get_sources(&self) -> Vec<String> {}

Note: The returned Vec not necessarily contains valid paths, so the String type is chosen here. It should be the responsibility of the implementor to resolve these fragments to actual file paths.

Success

• The proposed new method can be called on a WASM instance
• There is at least one test case covering this new method

Support bundling the source files in the sourcemap

Background

The sourcemap format supports bundling the original source in the sourcemap JSON file, in the sourcesContent property. The source files' contents need to be JSON encoded strings in an array.

Furthermore:

• It should support loading the rust std source files if it is installed on the system
• Load the crate sources for dependencies from the crates index as well

Success

The source files of a patched WASM can be read in the browser Dev Tools

Doesn't take `DW_AT_stmt_list` into account

I'm not entirely sure if gimli/object actually supports reading this, but not taking this into account produces wrong paths.

I will try and take a stab at this later.

Strip Wasm File

I was wondering if it's in scope to let wasm2map optionally strip the Wasm file after generating the sourcemap file.

This is useful to reduce the file size, as the information should be unnecessary when using the sourcemap anyway.
It might still be useful to retain it for environments that don't support sourcemaps but instead support the embedded DWARF information.

Use a stack-based vec type instead of String in building the VLQ encoded bits

Background

There is a tight loop within WASM::generate where mappings are built and VQL encoded, which currently uses String. However String is heap allocated, which means a ton of small allocations. Since there is a practical limit of how long the mappings usually are, we can use a stack-based vec type (arrayvec, tinyvec, smallvec or the like) to avoid these allocations completely.

Success

Expected at least 50% mapping speedup based on previous experiments with heap vs stack allocated vec types.

Fix flaky WASM compilation in tests causing flaky tests in CI

Support loading DWARF data from a supplementary object file

Investigate using indexmap instead of BTreeMap and Vec where now the .iter().position(...) is used for linear lookup

Background

The indexmap crate is already used by the dependencies of this lib (wasmparser -> object) and would offer a better lookup speed while sparing the extra sorting on the data set, which can offer some speedup in sourcemap generation.

Success

No loss of performance. The usage of indexmap is more idiomatic in this setting, which is a win in itself.

Come up with a test case for the sourcemap generation code (WASM::map_v3)

Background

Testing the valid sourcemap generation capabilities of the library can't be easily accomplished. Since this library translates DWARF code, in order to test it we need to inspect both the sourcemap and the DWARF code, which basically means a complete reimplementation of this lib (which in turn is quite pointless).

The obvious solution would be to run another tool on the same WASM file and compare the results. For this purpose the original inspiration, Emscripten's wasm_sourcemap.py can be run via an external python interpreter in the test. The downside is that it requires the test runner to have python installed.

Success

Total code coverage on the sourcemap generation code in the lib (i.e. WASM::load(), WASM::map_v3(), WASM::generate(),WASM::encode_vlq)