examples: counter with DWARF debugging (breakpoints and sourcemap) (#2563)

* feat: Added initial dwarf debug counter example

* fix: update to readme and launch.json, task.json

* fix: fix tasks.json for debugging

* fix: added Trunk.toml to fix the port

* fix: moved example to projects

projects/README.md

@@ -20,3 +20,6 @@ Feel free to submit projects to this directory via PR!
 
 ### tauri-from-scratch
 This example walks you through in explicit detail how to use [Tauri](https://tauri.app/) to render your Leptos App on non web targets using [WebView](https://en.wikipedia.org/wiki/WebView) while communicating with your leptos server and servering an SSR supported web experience. TODO: It could be simplified since part of the readme includes copying and pasting boilerplate.
+
+### counter_dwarf_debug
+This example shows how to add breakpoints within the browser or visual studio code for debugging.

projects/counter_dwarf_debug/.gitignore

@@ -0,0 +1,2 @@
+# For this example we want to include the vscode files
+!.vscode

projects/counter_dwarf_debug/.vscode/launch.json

@@ -0,0 +1,19 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Launch Browser Chrome",
+            "request": "launch",
+            "type": "chrome",
+            "url": "http://localhost:4001",
+            "webRoot": "${workspaceFolder}/dist",
+            // Needed to keep the dwarf extension in the browser
+            "userDataDir": false,
+            "preLaunchTask": "trunk: serve",
+            "postDebugTask": "postdebugKill"
+        },
+    ]
+}

projects/counter_dwarf_debug/.vscode/tasks.json

@@ -0,0 +1,53 @@
+{
+	"version": "2.0.0",
+	"tasks": [
+
+		// Task to build the sources
+		{
+			"label": "trunk: build",
+			"type": "shell",
+			"command": "trunk",
+			"args": ["build"],
+			"problemMatcher": [
+				"$rustc"
+			],
+			"group": "build",
+		},
+
+		// Task to launch trunk serve for debugging
+		{
+			"label": "trunk: serve",
+			"type": "shell",
+			"command": "trunk",
+			"args": ["serve"],
+			"isBackground": true,
+			"problemMatcher": {
+				"pattern": {
+					"regexp": ".",
+					"file": 1,"line": 1,
+					"column": 1,"message": 1
+				},
+				"background": {
+					"activeOnStart": true,
+					"beginsPattern": ".",
+					"endsPattern": "."
+				}
+			}
+		},
+
+		// Terminate the trunk serve task
+		{
+			"label": "postdebugKill",
+			"type": "shell",
+			"command": "echo ${input:terminate}",
+		},
+	],
+	"inputs": [
+		{
+			"id": "terminate",
+			"type": "command",
+			"command": "workbench.action.tasks.terminate",
+			"args": "terminateAll"
+		}
+	]
+}

projects/counter_dwarf_debug/Cargo.toml

@@ -0,0 +1,22 @@
+[workspace]
+# The empty workspace here is to keep rust-analyzer satisfied
+
+[package]
+name = "counter_dwarf_debug"
+version = "0.1.0"
+edition = "2021"
+
+[profile.release]
+codegen-units = 1
+lto = true
+
+[dependencies]
+leptos = { path = "../../leptos", features = ["csr"] }
+console_log = "1"
+log = "0.4"
+console_error_panic_hook = "0.1.7"
+
+[dev-dependencies]
+wasm-bindgen = "0.2"
+wasm-bindgen-test = "0.3.0"
+web-sys = "0.3"

projects/counter_dwarf_debug/README.md

@@ -0,0 +1,74 @@
+# Debugging Leptos Counter Example in Browser and VSCode
+
+This example builds on the simple counter by adding breakpoints and single stepping the source code for debugging.  
+Both within the browser and VSCode.  
+This uses a new feature of wasm called Dwarf which is a form of source code mapping.
+
+Note variable inspection during the breakpoints doesn't seem to work at this stage.
+
+## Quick Start
+
+  * Install the requirements below
+  * Open this directory within visual studio code
+  * Add a breakpoint to the code
+  * Launch the example using the visual studio code debug launcher
+
+## How This Works
+
+### Html Changes
+
+First we need to make a change to the index.html file
+
+From this
+```html
+<link data-trunk rel="rust" data-wasm-opt="z"/>
+```
+
+To this
+```html
+<link data-trunk rel="rust" data-keep-debug="true" data-wasm-opt="z"/>
+```
+
+This instructs the rust `trunk` utility to pass a long an option to `wasm-bindgen` called `--keep-debug`  
+This option bundles in a type of sourcemap into the built wasm file.  
+Be aware that this will make the wasm file much larger.
+
+### Browser Changes
+
+Next we need to allow the browser to read the DWARF data from the wasm file.
+For Chrome / Opera there's an extension here that needs to be installed.
+
+  * https://chromewebstore.google.com/detail/cc++-devtools-support-dwa/pdcpmagijalfljmkmjngeonclgbbannb?pli=1
+
+## Debugging within the Browser
+
+Within the browser's dev console it should now be possible to view the rust source code and add breakpoints.
+
+![Chrome Debug Image](./img/breakpoint1.png)
+
+## Debugging within VSCode
+
+Note this is still experimental, although I have managed to get breakpoints working under VSCode.  
+So far I've only tried this within a windows environment.
+
+In order to have the breakpoints land at the correct position.  
+We need to install the following VSCode extension.
+
+  * [WebAssembly DWARF Debugging](https://marketplace.visualstudio.com/items?itemName=ms-vscode.wasm-dwarf-debugging)
+
+Within the browser launch section under `launch.json` we need to set userDataDir to false in order for the DWARF browser extension to be loaded.
+```json
+  {
+    "name": "Launch Browser Chrome",
+    "request": "launch",
+    "type": "chrome",
+    "url": "http://localhost:8080",
+    "webRoot": "${workspaceFolder}/dist",
+    // Needed to keep the dwarf extension in the browser
+    "userDataDir": false,
+  },
+```
+
+Now we should be able to add breakpoints within visual studio code while debugging the rust wasm.
+
+![Chrome Debug Image](./img/breakpoint2.png)

projects/counter_dwarf_debug/Trunk.toml

@@ -0,0 +1,4 @@
+[serve]
+address = "127.0.0.1"
+port = 4001
+open = false

projects/counter_dwarf_debug/index.html

@@ -0,0 +1,8 @@
+<!DOCTYPE html>
+<html>
+	<head>
+		<link data-trunk rel="rust" data-keep-debug="true" data-wasm-opt="z"/>
+		<link data-trunk rel="icon" type="image/ico" href="/public/favicon.ico"/>
+	</head>
+	<body></body>
+</html>

projects/counter_dwarf_debug/rust-toolchain.toml

@@ -0,0 +1,2 @@
+[toolchain]
+channel = "stable" # test change

projects/counter_dwarf_debug/src/lib.rs

@@ -0,0 +1,29 @@
+use leptos::*;
+
+/// A simple counter component.
+///
+/// You can use doc comments like this to document your component.
+#[component]
+pub fn SimpleCounter(
+    /// The starting value for the counter
+    initial_value: i32,
+    /// The change that should be applied each time the button is clicked.
+    step: i32,
+) -> impl IntoView {
+    let (value, set_value) = create_signal(initial_value);
+
+    view! {
+        <div>
+            <button on:click=move |_| set_value.set(0)>"Clear"</button>
+            <button on:click=move |_| set_value.update(|value| *value -= step)>"-1"</button>
+            <span>"Value: " {value} "!"</span>
+            <button on:click=move |_| {
+                // Test Panic
+                //panic!("Test Panic");
+                // In order to breakpoint the below, the code needs to be on it's own line
+                set_value.update(|value| *value += step)
+            }
+            >"+1"</button>
+        </div>
+    }
+}

projects/counter_dwarf_debug/src/main.rs

@@ -0,0 +1,15 @@
+use counter_dwarf_debug::SimpleCounter;
+use leptos::*;
+
+pub fn main() {
+    _ = console_log::init_with_level(log::Level::Debug);
+    console_error_panic_hook::set_once();
+    mount_to_body(|| {
+        view! {
+            <SimpleCounter
+                initial_value=0
+                step=1
+            />
+        }
+    })
+}