docs: document wasm debug process (0xMiden#1341)

* docs: document wasm debug process

* docs: debug

* lint: fix typo

* fix: extension link

* pr-comments: more details in guide

* Update crates/web-client/docs/debug.md

Co-authored-by: igamigo <ignacio.amigo@lambdaclass.com>

* trigger workflow

* trigger workflow

* Apply suggestions from code review

Co-authored-by: igamigo <ignacio.amigo@lambdaclass.com>

* remove bullet point

* run tests with release mode

* chore: update test:clean target

* feat: re-do debug symbols setup

* feat: restore package.json from next

* Update crates/web-client/docs/debug.md

Co-authored-by: Marti <marti@miden.team>

* Update crates/web-client/docs/debug.md

Co-authored-by: Marti <marti@miden.team>

* Update crates/web-client/docs/debug.md

Co-authored-by: Marti <marti@miden.team>

* Update crates/web-client/docs/debug.md

Co-authored-by: Marti <marti@miden.team>

* pr-comments

* format

* fix md formatting

* docs: pr feedback

---------

Co-authored-by: igamigo <ignacio.amigo@lambdaclass.com>
Co-authored-by: Marti <marti@miden.team>

Author: 3 people

Makefile

@@ -211,3 +211,12 @@ install-tools: ## Installs Rust + Node tools required by the Makefile
 	yarn --silent
 	yarn
 	@echo "Development tools installation complete!"
+
+## --- Debug --------------------------------------------------------------------------------------
+.PHONY: build-web-client-debug
+build-web-client-debug: # build the web-client with debug symbols for the WASM-generated rust code
+	cd crates/web-client && yarn build-dev
+
+.PHONY: link-web-client-dep
+link-web-client-dep: # links the local web-client for debugging JS applications.
+	cd crates/web-client && yarn link

crates/web-client/docs/debug_wasm.md

@@ -0,0 +1,53 @@
+# Debugging WASM
+
+When debugging WASM, it can be tricky to trace the origin of an error since stack traces are not often noisy and difficult to read.
+To better trace these errors, a build with debug symbols can be generated. This doc explains how to set it up.
+
+## Requirements
+    - yarn
+    - Compatible Rust version
+    - Chrome browser
+    - [wasm-debugging-extension](https://goo.gle/wasm-debugging-extension).
+    
+## Building with debug symbols
+
+1. Clone the miden-client repo:
+```bash
+git clone git@github.com:0xMiden/miden-client.git
+```
+2. Build miden-client with debug-symbols:
+```bash
+make build-web-client-debug
+```
+Once it finishes, the Rust build log should print this:
+```
+    Finished `release` profile [optimized + debuginfo] target(s) in 38.33s
+```
+    
+## Using the debug symbols
+
+Once you have both the debug WASM and the Chrome extension, we need to link
+the dependency to the JS app we're debugging.
+
+1. Once you have the web client built with debug symbols, we have to use it as a dependency,
+for that we'll use [yarn link](https://classic.yarnpkg.com/lang/en/docs/cli/link/), 
+run this in your local copy of miden-client:
+```
+make link-web-client-dep
+```
+2. Then, run this command in the root of the project that needs to be debugged:
+```
+yarn link "@demox-labs/miden-sdk"
+```
+Essentially,`yarn link` makes the project use the local modified version of the sdk instead of the NPM hosted one. Now, when you open the devtools with chrome, you will see an output like this:
+
+
+![dev-tools-output](./devtools-output.png).
+
+
+You should also be able to see the rust source in the devtools source tab:
+![source-example](./source-example.png)
+
+
+Also, you should see friendlier stack-traces:
+![stack-trace-example](./stack-trace-example.png)

crates/web-client/docs/devtools-output.png

@@ -6,6 +6,18 @@ import copy from "rollup-plugin-copy";
 // Flag that indicates if the build is meant for development purposes.
 // If true, wasm-opt is not applied.
 const devMode = process.env.MIDEN_WEB_DEV === "true";
+
+// Arguments to tell cargo to add debug symbols
+// to the generated .wasm file.
+const cargoArgsUseDebugSymbols = [
+  // Generate debug symbols for the release cargo profile.
+  "--config",
+  "profile.release.debug='full'",
+  // Do not remove debug symbols from the final binary,
+  "--config",
+  "profile.release.strip='none'",
+];
+
 const wasmOptArgs = [
   devMode ? "-O0" : "-O3",
   "--enable-bulk-memory",
@@ -19,7 +31,7 @@ const baseCargoArgs = [
   "--config",
   `build.rustflags=["-C", "target-feature=+atomics,+bulk-memory,+mutable-globals", "-C", "link-arg=--max-memory=4294967296", "-C", "panic=abort"]`,
   "--no-default-features",
-];
+].concat(devMode ? cargoArgsUseDebugSymbols : []);
 
 /**
  * Rollup configuration file for building a Cargo project and creating a WebAssembly (WASM) module,
@@ -59,6 +71,8 @@ export default [
         extraArgs: {
           cargo: [...baseCargoArgs],
           wasmOpt: wasmOptArgs,
+          // Keep debug symbols if in dev mode.
+          wasmBindgen: devMode ? ["--keep-debug"] : [],
         },
         experimental: {
           typescriptDeclarationDir: "dist/crates",