From c81568184dce797d6ecc426f8bea61b9178be476 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 26 Aug 2025 15:59:32 +0000 Subject: [PATCH 01/11] Initial plan From f6d52bb6d83177e7818851d5485a976837d3bba5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 26 Aug 2025 16:22:09 +0000 Subject: [PATCH 02/11] Add CoreCLR WebAssembly documentation and update main README Co-authored-by: lewing <24063+lewing@users.noreply.github.com> --- docs/workflow/building/coreclr/README.md | 6 ++ docs/workflow/building/coreclr/wasm.md | 131 +++++++++++++++++++++++ 2 files changed, 137 insertions(+) create mode 100644 docs/workflow/building/coreclr/wasm.md diff --git a/docs/workflow/building/coreclr/README.md b/docs/workflow/building/coreclr/README.md index 5987da06d7bb20..970e4c2860894d 100644 --- a/docs/workflow/building/coreclr/README.md +++ b/docs/workflow/building/coreclr/README.md @@ -91,6 +91,12 @@ Using an x64 machine, it is possible to generate builds for other architectures. Detailed instructions on how to do cross-compilation can be found in the cross-building doc [over here](/docs/workflow/building/coreclr/cross-building.md). +### Platform-Specific Guides + +For specialized platforms, detailed instructions are available in the following guides: + +- **WebAssembly:** [Building CoreCLR for WebAssembly](/docs/workflow/building/coreclr/wasm.md) - Experimental support for building, running, and debugging CoreCLR on WebAssembly. + ## Other Features ### Build Drivers diff --git a/docs/workflow/building/coreclr/wasm.md b/docs/workflow/building/coreclr/wasm.md new file mode 100644 index 00000000000000..72310519aa88e1 --- /dev/null +++ b/docs/workflow/building/coreclr/wasm.md @@ -0,0 +1,131 @@ +# Building CoreCLR for WebAssembly + +This guide provides instructions for building, running, and debugging CoreCLR on WebAssembly (WASM). This is experimental support and is currently under active development. + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Building CoreCLR for WebAssembly](#building-coreclr-for-webassembly) +- [Testing the Runtime](#testing-the-runtime) +- [Debugging](#debugging) + - [Chrome DevTools with DWARF Support](#chrome-devtools-with-dwarf-support) + - [VS Code WebAssembly Debugging](#vs-code-webassembly-debugging) +- [Current State](#current-state) +- [Next Steps](#next-steps) +- [Related Issues and Resources](#related-issues-and-resources) + +## Prerequisites + +Make sure you've prepared your environment and installed all the requirements for your platform. If not, follow this [link](/docs/workflow/README.md#introduction) for the corresponding instructions. + +## Building CoreCLR for WebAssembly + +To build the CoreCLR runtime for WebAssembly, use the following command from the repository root: + +```bash +./build.sh -bl -os browser -c Debug -subset clr.runtime+libs +``` + +This command will: +- Install the Emscripten SDK (emsdk) automatically +- Build the CoreCLR runtime for WebAssembly +- Build the required libraries + +**Note:** The first build may take longer as it downloads and sets up the Emscripten toolchain. + +## Testing the Runtime + +To test the runtime startup, follow these steps: + +1. **Clean intermediate artifacts** (temporary workaround): + ```bash + rm -rf artifacts/obj/coreclr/browser.wasm.Debug/hosts/corewasmrun + ``` + This step is necessary because libraries were not available when `corewasmrun` was initially linked. This is a temporary issue that will be resolved with proper assembly loading. + +2. **Build the simple-server** (for testing): + ```bash + ./dotnet.sh build -c Release src/mono/sample/wasm/simple-server + ``` + +3. **Build and run corewasmrun** in the browser: + For a quicker development roundtrip, run this command from the `src/coreclr` directory: + ```bash + (source "../mono/browser/emsdk/emsdk_env.sh" && cd ../../artifacts/obj/coreclr/browser.wasm.Debug/; make corewasmrun -j12) && (cp hosts/corewasmrun/index.html ../../artifacts/obj/coreclr/browser.wasm.Debug/hosts/corewasmrun/; cd ../../artifacts/obj/coreclr/browser.wasm.Debug/hosts/corewasmrun/; ~/git/runtime-main/src/mono/sample/wasm/simple-server/bin/Release/net8.0/HttpServer) + ``` + + This command will: + - Build `corewasmrun` + - Copy the `index.html` file to the output directory + - Start a local HTTP server + - Open the application in your default browser + - Forward browser console output to the terminal + +**Note:** On Windows, you might need to run `ninja` instead of `make`. If Chrome is not your default browser, you can manually copy the URL and open it in Chrome for better debugging support. + +## Debugging + +### Chrome DevTools with DWARF Support + +For debugging CoreCLR WebAssembly code, the recommended approach is using Chrome browser with the **C/C++ DevTools Support (DWARF)** extension: + +1. **Install the Chrome extension:** + - [C/C++ DevTools Support (DWARF)](https://chromewebstore.google.com/detail/cc-devtools-support-dwar/nhdogjmejiglipccpnnnanhbledajbpd) + +2. **Open Chrome DevTools** (F12) while running your WebAssembly application + +3. **Set breakpoints** in the Sources tab: + - Navigate to the WebAssembly modules + - You can step through C code, set breakpoints, and inspect WebAssembly linear memory + - The extension provides source-level debugging with DWARF debug information + +**Note:** The debugging experience is not perfect but works most of the time. You can step through C code, set breakpoints, and inspect the WebAssembly linear memory. + +### VS Code WebAssembly Debugging + +For an alternative debugging experience, you can use VS Code with the **WebAssembly Dwarf Debugging** extension: + +1. **Install the VS Code extension:** + - [WebAssembly Dwarf Debugging](https://marketplace.visualstudio.com/items?itemName=wasm-debug.webassembly-dwarf-debug) + +2. **Configure your debugging environment** according to the extension's documentation + +3. **Set up your launch configuration** in VS Code to attach to the WebAssembly runtime + +## Current State + +As of the current development state, the WebAssembly CoreCLR implementation can compile and run several managed methods before encountering limitations. On the main branch, it successfully compiles and executes 6 managed methods: + +``` +Compiled method: .System.AppContext:Setup(ptr,ptr,int) +Compiled method: .System.Diagnostics.Debug:Assert(bool,System.String) +Compiled method: .System.Diagnostics.Debug:Assert(bool,System.String,System.String) +Compiled method: .System.Collections.Generic.Dictionary`2[System.__Canon,System.__Canon]:.ctor(int) +Compiled method: .System.Collections.Generic.Dictionary`2[System.__Canon,System.__Canon]:.ctor(int,System.Collections.Generic.IEqualityComparer`1[System.__Canon]) +Compiled method: .System.Object:.ctor() +``` + +With the proof-of-concept implementation, this extends to approximately 60 methods and native functions before encountering the current limitations. + +## Next Steps + +The following areas are identified for continued development to progress with runtime initialization: + +### High Priority +1. **Helper calls opcodes** - Implementation of runtime helper calls for various operations +2. **P/Invoke and QCalls** - Support for platform invoke and internal calls to native functions +3. **Stack walking** - This is currently the main breaking point and requires investigation into WebAssembly-specific stack walking mechanisms + +### Additional Work +4. **Compare WebAssembly startup with desktop startup** - Analysis to identify if managed exceptions are being hit during startup +5. **Assembly loading improvements** - Proper assembly loading to eliminate temporary workarounds +6. **Performance optimizations** - Once basic functionality is stable + +## Related Issues and Resources + +- **Main tracking issue:** [#119002 - wasm coreclr workflow and near future work](https://github.com/dotnet/runtime/issues/119002) +- **Helper calls opcodes:** [#119000](https://github.com/dotnet/runtime/issues/119000) +- **P/Invoke / QCalls:** [#119001](https://github.com/dotnet/runtime/issues/119001) +- **Proof-of-concept branch:** [clr-interp-qcall-and-helper-call-poc](https://github.com/radekdoulik/runtime/tree/clr-interp-qcall-and-helper-call-poc) + +For questions or issues related to CoreCLR WebAssembly development, please refer to the above issues or create new ones with the `arch-wasm` and `area-VM-coreclr` labels. \ No newline at end of file From 8ff8097340fd33c236e1a9f4ab6df365843afe44 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 26 Aug 2025 16:25:24 +0000 Subject: [PATCH 03/11] Update CoreCLR WebAssembly documentation with latest workflow improvements Co-authored-by: lewing <24063+lewing@users.noreply.github.com> --- docs/workflow/building/coreclr/wasm.md | 89 +++++++++++++++++++++++--- 1 file changed, 79 insertions(+), 10 deletions(-) diff --git a/docs/workflow/building/coreclr/wasm.md b/docs/workflow/building/coreclr/wasm.md index 72310519aa88e1..565c1c220e62c6 100644 --- a/docs/workflow/building/coreclr/wasm.md +++ b/docs/workflow/building/coreclr/wasm.md @@ -22,10 +22,16 @@ Make sure you've prepared your environment and installed all the requirements fo To build the CoreCLR runtime for WebAssembly, use the following command from the repository root: +**Linux/macOS:** ```bash ./build.sh -bl -os browser -c Debug -subset clr.runtime+libs ``` +**Windows:** +```cmd +.\build.cmd -os browser -c Debug -subset clr.runtime+libs +``` + This command will: - Install the Emscripten SDK (emsdk) automatically - Build the CoreCLR runtime for WebAssembly @@ -35,7 +41,34 @@ This command will: ## Testing the Runtime -To test the runtime startup, follow these steps: +### Browser Testing (Recommended) + +The simplest way to test the runtime in a browser is to use `dotnet-serve`: + +**Linux/macOS:** +```bash +dotnet-serve --directory "artifacts/bin/coreclr/browser.wasm.Debug/corewasmrun" +``` + +**Windows:** +```cmd +dotnet-serve --directory "artifacts\bin\coreclr\browser.wasm.Debug\corewasmrun" +``` + +This will start a local HTTP server and you can open the provided URL in your browser. + +### Console Testing + +You can also run the runtime directly in Node.js: + +```bash +cd artifacts/bin/coreclr/browser.wasm.Debug/corewasmrun/ +node corewasmrun.js +``` + +### Manual Testing Steps (Alternative Method) + +If you need more control over the testing process, you can follow these manual steps: 1. **Clean intermediate artifacts** (temporary workaround): ```bash @@ -54,14 +87,17 @@ To test the runtime startup, follow these steps: (source "../mono/browser/emsdk/emsdk_env.sh" && cd ../../artifacts/obj/coreclr/browser.wasm.Debug/; make corewasmrun -j12) && (cp hosts/corewasmrun/index.html ../../artifacts/obj/coreclr/browser.wasm.Debug/hosts/corewasmrun/; cd ../../artifacts/obj/coreclr/browser.wasm.Debug/hosts/corewasmrun/; ~/git/runtime-main/src/mono/sample/wasm/simple-server/bin/Release/net8.0/HttpServer) ``` - This command will: - - Build `corewasmrun` - - Copy the `index.html` file to the output directory - - Start a local HTTP server - - Open the application in your default browser - - Forward browser console output to the terminal + **On Windows**, the equivalent steps are: + ```cmd + cd artifacts\obj\coreclr\browser.wasm.Debug\ + src\mono\browser\emsdk\emsdk_env.cmd + ninja corewasmrun + copy src\coreclr\hosts\corewasmrun\index.html artifacts\obj\coreclr\browser.wasm.Debug\hosts\corewasmrun + cd artifacts\obj\coreclr\browser.wasm.Debug\hosts\corewasmrun + src\mono\sample\wasm\simple-server\bin\Release\net8.0\HttpServer.exe + ``` -**Note:** On Windows, you might need to run `ninja` instead of `make`. If Chrome is not your default browser, you can manually copy the URL and open it in Chrome for better debugging support. +**Note:** If Chrome is not your default browser, you can manually copy the URL and open it in Chrome for better debugging support. ## Debugging @@ -70,7 +106,7 @@ To test the runtime startup, follow these steps: For debugging CoreCLR WebAssembly code, the recommended approach is using Chrome browser with the **C/C++ DevTools Support (DWARF)** extension: 1. **Install the Chrome extension:** - - [C/C++ DevTools Support (DWARF)](https://chromewebstore.google.com/detail/cc-devtools-support-dwar/nhdogjmejiglipccpnnnanhbledajbpd) + - [C/C++ DevTools Support (DWARF)](https://chromewebstore.google.com/detail/cc++-devtools-support-dwa/pdcpmagijalfljmkmjngeonclgbbannb) 2. **Open Chrome DevTools** (F12) while running your WebAssembly application @@ -83,7 +119,9 @@ For debugging CoreCLR WebAssembly code, the recommended approach is using Chrome ### VS Code WebAssembly Debugging -For an alternative debugging experience, you can use VS Code with the **WebAssembly Dwarf Debugging** extension: +VS Code provides multiple debugging options for WebAssembly CoreCLR: + +#### Option 1: WebAssembly Dwarf Debugging Extension 1. **Install the VS Code extension:** - [WebAssembly Dwarf Debugging](https://marketplace.visualstudio.com/items?itemName=wasm-debug.webassembly-dwarf-debug) @@ -92,6 +130,37 @@ For an alternative debugging experience, you can use VS Code with the **WebAssem 3. **Set up your launch configuration** in VS Code to attach to the WebAssembly runtime +#### Option 2: Node.js Debugging (Recommended) + +For a simpler debugging experience, you can use VS Code's built-in Node.js debugger: + +1. **Create a launch.json configuration:** + ```json + { + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "corewasmrun", + "skipFiles": [ + "/**" + ], + "program": "corewasmrun.js", + "cwd": "${workspaceFolder}/artifacts/bin/coreclr/browser.wasm.Debug/corewasmrun/" + } + ] + } + ``` + + **Note:** On Windows, use backslashes in the path: `"${workspaceFolder}\\artifacts\\bin\\coreclr\\browser.wasm.Debug\\corewasmrun\\"` + +2. **Set breakpoints** in `corewasmrun.js` at line 1815 (the `stdout`/`printf` implementation) + +3. **Start debugging** and step through the WebAssembly code using the call stack + +This approach allows you to debug the JavaScript host and step into WebAssembly code. + ## Current State As of the current development state, the WebAssembly CoreCLR implementation can compile and run several managed methods before encountering limitations. On the main branch, it successfully compiles and executes 6 managed methods: From ec5981fc3e4509cf976791beb32187912d6e2267 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 26 Aug 2025 17:15:55 +0000 Subject: [PATCH 04/11] Apply review feedback: update build commands, remove manual testing section, and fix extension links Co-authored-by: AaronRobinsonMSFT <30635565+AaronRobinsonMSFT@users.noreply.github.com> --- docs/workflow/building/coreclr/wasm.md | 84 ++------------------------ 1 file changed, 5 insertions(+), 79 deletions(-) diff --git a/docs/workflow/building/coreclr/wasm.md b/docs/workflow/building/coreclr/wasm.md index 565c1c220e62c6..4b400fe33e1560 100644 --- a/docs/workflow/building/coreclr/wasm.md +++ b/docs/workflow/building/coreclr/wasm.md @@ -10,9 +10,6 @@ This guide provides instructions for building, running, and debugging CoreCLR on - [Debugging](#debugging) - [Chrome DevTools with DWARF Support](#chrome-devtools-with-dwarf-support) - [VS Code WebAssembly Debugging](#vs-code-webassembly-debugging) -- [Current State](#current-state) -- [Next Steps](#next-steps) -- [Related Issues and Resources](#related-issues-and-resources) ## Prerequisites @@ -24,12 +21,12 @@ To build the CoreCLR runtime for WebAssembly, use the following command from the **Linux/macOS:** ```bash -./build.sh -bl -os browser -c Debug -subset clr.runtime+libs +./build.sh -os browser -c Debug -subset clr.runtime ``` **Windows:** ```cmd -.\build.cmd -os browser -c Debug -subset clr.runtime+libs +.\build.cmd -os browser -c Debug -subset clr.runtime ``` This command will: @@ -66,39 +63,6 @@ cd artifacts/bin/coreclr/browser.wasm.Debug/corewasmrun/ node corewasmrun.js ``` -### Manual Testing Steps (Alternative Method) - -If you need more control over the testing process, you can follow these manual steps: - -1. **Clean intermediate artifacts** (temporary workaround): - ```bash - rm -rf artifacts/obj/coreclr/browser.wasm.Debug/hosts/corewasmrun - ``` - This step is necessary because libraries were not available when `corewasmrun` was initially linked. This is a temporary issue that will be resolved with proper assembly loading. - -2. **Build the simple-server** (for testing): - ```bash - ./dotnet.sh build -c Release src/mono/sample/wasm/simple-server - ``` - -3. **Build and run corewasmrun** in the browser: - For a quicker development roundtrip, run this command from the `src/coreclr` directory: - ```bash - (source "../mono/browser/emsdk/emsdk_env.sh" && cd ../../artifacts/obj/coreclr/browser.wasm.Debug/; make corewasmrun -j12) && (cp hosts/corewasmrun/index.html ../../artifacts/obj/coreclr/browser.wasm.Debug/hosts/corewasmrun/; cd ../../artifacts/obj/coreclr/browser.wasm.Debug/hosts/corewasmrun/; ~/git/runtime-main/src/mono/sample/wasm/simple-server/bin/Release/net8.0/HttpServer) - ``` - - **On Windows**, the equivalent steps are: - ```cmd - cd artifacts\obj\coreclr\browser.wasm.Debug\ - src\mono\browser\emsdk\emsdk_env.cmd - ninja corewasmrun - copy src\coreclr\hosts\corewasmrun\index.html artifacts\obj\coreclr\browser.wasm.Debug\hosts\corewasmrun - cd artifacts\obj\coreclr\browser.wasm.Debug\hosts\corewasmrun - src\mono\sample\wasm\simple-server\bin\Release\net8.0\HttpServer.exe - ``` - -**Note:** If Chrome is not your default browser, you can manually copy the URL and open it in Chrome for better debugging support. - ## Debugging ### Chrome DevTools with DWARF Support @@ -106,7 +70,7 @@ If you need more control over the testing process, you can follow these manual s For debugging CoreCLR WebAssembly code, the recommended approach is using Chrome browser with the **C/C++ DevTools Support (DWARF)** extension: 1. **Install the Chrome extension:** - - [C/C++ DevTools Support (DWARF)](https://chromewebstore.google.com/detail/cc++-devtools-support-dwa/pdcpmagijalfljmkmjngeonclgbbannb) + - [C/C++ DevTools Support (DWARF)](https://goo.gle/wasm-debugging-extension) 2. **Open Chrome DevTools** (F12) while running your WebAssembly application @@ -124,7 +88,7 @@ VS Code provides multiple debugging options for WebAssembly CoreCLR: #### Option 1: WebAssembly Dwarf Debugging Extension 1. **Install the VS Code extension:** - - [WebAssembly Dwarf Debugging](https://marketplace.visualstudio.com/items?itemName=wasm-debug.webassembly-dwarf-debug) + - [WebAssembly Dwarf Debugging](https://marketplace.visualstudio.com/items?itemName=ms-vscode.wasm-dwarf-debugging) 2. **Configure your debugging environment** according to the extension's documentation @@ -159,42 +123,4 @@ For a simpler debugging experience, you can use VS Code's built-in Node.js debug 3. **Start debugging** and step through the WebAssembly code using the call stack -This approach allows you to debug the JavaScript host and step into WebAssembly code. - -## Current State - -As of the current development state, the WebAssembly CoreCLR implementation can compile and run several managed methods before encountering limitations. On the main branch, it successfully compiles and executes 6 managed methods: - -``` -Compiled method: .System.AppContext:Setup(ptr,ptr,int) -Compiled method: .System.Diagnostics.Debug:Assert(bool,System.String) -Compiled method: .System.Diagnostics.Debug:Assert(bool,System.String,System.String) -Compiled method: .System.Collections.Generic.Dictionary`2[System.__Canon,System.__Canon]:.ctor(int) -Compiled method: .System.Collections.Generic.Dictionary`2[System.__Canon,System.__Canon]:.ctor(int,System.Collections.Generic.IEqualityComparer`1[System.__Canon]) -Compiled method: .System.Object:.ctor() -``` - -With the proof-of-concept implementation, this extends to approximately 60 methods and native functions before encountering the current limitations. - -## Next Steps - -The following areas are identified for continued development to progress with runtime initialization: - -### High Priority -1. **Helper calls opcodes** - Implementation of runtime helper calls for various operations -2. **P/Invoke and QCalls** - Support for platform invoke and internal calls to native functions -3. **Stack walking** - This is currently the main breaking point and requires investigation into WebAssembly-specific stack walking mechanisms - -### Additional Work -4. **Compare WebAssembly startup with desktop startup** - Analysis to identify if managed exceptions are being hit during startup -5. **Assembly loading improvements** - Proper assembly loading to eliminate temporary workarounds -6. **Performance optimizations** - Once basic functionality is stable - -## Related Issues and Resources - -- **Main tracking issue:** [#119002 - wasm coreclr workflow and near future work](https://github.com/dotnet/runtime/issues/119002) -- **Helper calls opcodes:** [#119000](https://github.com/dotnet/runtime/issues/119000) -- **P/Invoke / QCalls:** [#119001](https://github.com/dotnet/runtime/issues/119001) -- **Proof-of-concept branch:** [clr-interp-qcall-and-helper-call-poc](https://github.com/radekdoulik/runtime/tree/clr-interp-qcall-and-helper-call-poc) - -For questions or issues related to CoreCLR WebAssembly development, please refer to the above issues or create new ones with the `arch-wasm` and `area-VM-coreclr` labels. \ No newline at end of file +This approach allows you to debug the JavaScript host and step into WebAssembly code. \ No newline at end of file From a41878272e3b7ed7555565869178e1f41978f4a5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 26 Aug 2025 18:33:08 +0000 Subject: [PATCH 05/11] Add dotnet-serve GitHub link as requested in review feedback Co-authored-by: AaronRobinsonMSFT <30635565+AaronRobinsonMSFT@users.noreply.github.com> --- docs/workflow/building/coreclr/wasm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/workflow/building/coreclr/wasm.md b/docs/workflow/building/coreclr/wasm.md index 4b400fe33e1560..22e319e7047e0a 100644 --- a/docs/workflow/building/coreclr/wasm.md +++ b/docs/workflow/building/coreclr/wasm.md @@ -40,7 +40,7 @@ This command will: ### Browser Testing (Recommended) -The simplest way to test the runtime in a browser is to use `dotnet-serve`: +The simplest way to test the runtime in a browser is to use [`dotnet-serve`](https://github.com/natemcmaster/dotnet-serve): **Linux/macOS:** ```bash From 2ce038235869d95153557c864b372b84009c632e Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Tue, 26 Aug 2025 11:56:23 -0700 Subject: [PATCH 06/11] Apply suggestions from code review --- docs/workflow/building/coreclr/wasm.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/workflow/building/coreclr/wasm.md b/docs/workflow/building/coreclr/wasm.md index 22e319e7047e0a..ff661a1cd76f01 100644 --- a/docs/workflow/building/coreclr/wasm.md +++ b/docs/workflow/building/coreclr/wasm.md @@ -94,7 +94,7 @@ VS Code provides multiple debugging options for WebAssembly CoreCLR: 3. **Set up your launch configuration** in VS Code to attach to the WebAssembly runtime -#### Option 2: Node.js Debugging (Recommended) +#### Option 2: Node.js Debugging For a simpler debugging experience, you can use VS Code's built-in Node.js debugger: @@ -119,7 +119,7 @@ For a simpler debugging experience, you can use VS Code's built-in Node.js debug **Note:** On Windows, use backslashes in the path: `"${workspaceFolder}\\artifacts\\bin\\coreclr\\browser.wasm.Debug\\corewasmrun\\"` -2. **Set breakpoints** in `corewasmrun.js` at line 1815 (the `stdout`/`printf` implementation) +2. **Set breakpoints** in `corewasmrun.js` in one of the `put_char` functions (the `stdout`/`stderr` implementation) 3. **Start debugging** and step through the WebAssembly code using the call stack From e67bc97a62e16aa3eaab4c6001a94f1a81e2617a Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Tue, 26 Aug 2025 15:53:34 -0700 Subject: [PATCH 07/11] Update docs/workflow/building/coreclr/wasm.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/workflow/building/coreclr/wasm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/workflow/building/coreclr/wasm.md b/docs/workflow/building/coreclr/wasm.md index ff661a1cd76f01..3bfc8aea9d70a4 100644 --- a/docs/workflow/building/coreclr/wasm.md +++ b/docs/workflow/building/coreclr/wasm.md @@ -70,7 +70,7 @@ node corewasmrun.js For debugging CoreCLR WebAssembly code, the recommended approach is using Chrome browser with the **C/C++ DevTools Support (DWARF)** extension: 1. **Install the Chrome extension:** - - [C/C++ DevTools Support (DWARF)](https://goo.gle/wasm-debugging-extension) + - [C/C++ DevTools Support (DWARF)](https://chrome.google.com/webstore/detail/cc-devtools-support-dwar/odljcjlcidgdhcjhoijagojpnjcgocgd) 2. **Open Chrome DevTools** (F12) while running your WebAssembly application From 3b8eb3c238458cb829685cc2226e20180e544d8b Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Tue, 26 Aug 2025 16:06:29 -0700 Subject: [PATCH 08/11] Update docs/workflow/building/coreclr/wasm.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/workflow/building/coreclr/wasm.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/workflow/building/coreclr/wasm.md b/docs/workflow/building/coreclr/wasm.md index 3bfc8aea9d70a4..a5e45d10bf0326 100644 --- a/docs/workflow/building/coreclr/wasm.md +++ b/docs/workflow/building/coreclr/wasm.md @@ -40,8 +40,11 @@ This command will: ### Browser Testing (Recommended) -The simplest way to test the runtime in a browser is to use [`dotnet-serve`](https://github.com/natemcmaster/dotnet-serve): +If you don't have `dotnet-serve` installed, you can install it as a global .NET tool with: + +```bash +dotnet tool install --global dotnet-serve **Linux/macOS:** ```bash dotnet-serve --directory "artifacts/bin/coreclr/browser.wasm.Debug/corewasmrun" From b28c4bb5ce7478246a383c68fbf82ee5c1469ac8 Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Tue, 26 Aug 2025 16:07:55 -0700 Subject: [PATCH 09/11] Update docs/workflow/building/coreclr/wasm.md --- docs/workflow/building/coreclr/wasm.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/workflow/building/coreclr/wasm.md b/docs/workflow/building/coreclr/wasm.md index a5e45d10bf0326..af460d4e9893f7 100644 --- a/docs/workflow/building/coreclr/wasm.md +++ b/docs/workflow/building/coreclr/wasm.md @@ -40,7 +40,6 @@ This command will: ### Browser Testing (Recommended) - If you don't have `dotnet-serve` installed, you can install it as a global .NET tool with: ```bash From 3e8a5bf9f30c04300800f3bafeca64190da495ba Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Tue, 26 Aug 2025 16:08:41 -0700 Subject: [PATCH 10/11] Update wasm.md --- docs/workflow/building/coreclr/wasm.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/workflow/building/coreclr/wasm.md b/docs/workflow/building/coreclr/wasm.md index af460d4e9893f7..56169bda64e6ee 100644 --- a/docs/workflow/building/coreclr/wasm.md +++ b/docs/workflow/building/coreclr/wasm.md @@ -44,6 +44,8 @@ If you don't have `dotnet-serve` installed, you can install it as a global .NET ```bash dotnet tool install --global dotnet-serve +``` + **Linux/macOS:** ```bash dotnet-serve --directory "artifacts/bin/coreclr/browser.wasm.Debug/corewasmrun" @@ -125,4 +127,4 @@ For a simpler debugging experience, you can use VS Code's built-in Node.js debug 3. **Start debugging** and step through the WebAssembly code using the call stack -This approach allows you to debug the JavaScript host and step into WebAssembly code. \ No newline at end of file +This approach allows you to debug the JavaScript host and step into WebAssembly code. From 918b95c301fdbf04e13793b3177fb17ebbf21cab Mon Sep 17 00:00:00 2001 From: Aaron Robinson Date: Wed, 27 Aug 2025 10:05:24 -0700 Subject: [PATCH 11/11] Refine WebAssembly debugging options in VS Code --- docs/workflow/building/coreclr/wasm.md | 24 ++++++------------------ 1 file changed, 6 insertions(+), 18 deletions(-) diff --git a/docs/workflow/building/coreclr/wasm.md b/docs/workflow/building/coreclr/wasm.md index 56169bda64e6ee..b05ce9d02dad14 100644 --- a/docs/workflow/building/coreclr/wasm.md +++ b/docs/workflow/building/coreclr/wasm.md @@ -87,22 +87,12 @@ For debugging CoreCLR WebAssembly code, the recommended approach is using Chrome ### VS Code WebAssembly Debugging -VS Code provides multiple debugging options for WebAssembly CoreCLR: +VS Code, through Node.js, provides a good debugging option for WebAssembly CoreCLR: -#### Option 1: WebAssembly Dwarf Debugging Extension - -1. **Install the VS Code extension:** +1. **Install the VS Code extension (Optional):** - [WebAssembly Dwarf Debugging](https://marketplace.visualstudio.com/items?itemName=ms-vscode.wasm-dwarf-debugging) -2. **Configure your debugging environment** according to the extension's documentation - -3. **Set up your launch configuration** in VS Code to attach to the WebAssembly runtime - -#### Option 2: Node.js Debugging - -For a simpler debugging experience, you can use VS Code's built-in Node.js debugger: - -1. **Create a launch.json configuration:** +2. **Create a launch.json configuration:** ```json { "version": "0.2.0", @@ -120,11 +110,9 @@ For a simpler debugging experience, you can use VS Code's built-in Node.js debug ] } ``` - - **Note:** On Windows, use backslashes in the path: `"${workspaceFolder}\\artifacts\\bin\\coreclr\\browser.wasm.Debug\\corewasmrun\\"` -2. **Set breakpoints** in `corewasmrun.js` in one of the `put_char` functions (the `stdout`/`stderr` implementation) +3. **Set breakpoints** in `corewasmrun.js` in one of the `put_char` functions (the `stdout`/`stderr` implementation) -3. **Start debugging** and step through the WebAssembly code using the call stack +4. **Start debugging** and step through the WebAssembly code using the call stack -This approach allows you to debug the JavaScript host and step into WebAssembly code. +This approach allows you to debug the JavaScript host and step into WebAssembly code or into the C/C++ code if the Dwarf Debugging extension was installed.