From f35935e09b17fe75f4abfa4fab5863382c6202cf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 25 Sep 2025 15:30:40 +0000 Subject: [PATCH 01/21] Initial plan From 238cab9b328e6583baafb28425e12158afb72191 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 25 Sep 2025 16:01:32 +0000 Subject: [PATCH 02/21] Create comprehensive WASM documentation index and consolidated debugging reference Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- docs/README.md | 1 + .../debugging/wasm-debugging-reference.md | 197 +++++++++++++++ docs/workflow/wasm-documentation.md | 232 ++++++++++++++++++ 3 files changed, 430 insertions(+) create mode 100644 docs/workflow/debugging/wasm-debugging-reference.md create mode 100644 docs/workflow/wasm-documentation.md diff --git a/docs/README.md b/docs/README.md index 3d7f5a529ff022..08c3c377330515 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,6 +20,7 @@ Workflow (Building, testing, benchmarking, profiling, etc.) If you want to contribute a code change to this repo, start here. - [Workflow Instructions](workflow/README.md) +- [WebAssembly (WASM) Documentation](workflow/wasm-documentation.md) Design Docs ================= diff --git a/docs/workflow/debugging/wasm-debugging-reference.md b/docs/workflow/debugging/wasm-debugging-reference.md new file mode 100644 index 00000000000000..efb16e6a872aec --- /dev/null +++ b/docs/workflow/debugging/wasm-debugging-reference.md @@ -0,0 +1,197 @@ +# WebAssembly Debugging Reference + +This document provides consolidated debugging instructions for WebAssembly applications that are referenced by multiple other documentation files. + +## Debug with VS Code + +To debug WebAssembly applications with Visual Studio Code: + +### 1. Basic Configuration + +Add the following configuration to your `.vscode/launch.json`: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "WASM Attach", + "request": "attach", + "type": "chrome", + "address": "localhost", + "port": + } + ] +} +``` + +Replace `` with the proxy port shown in your application's output. + +### 2. Library Test Debugging + +For debugging library tests specifically: + +```json +{ + "name": "Libraries", + "request": "attach", + "type": "chrome", + "address": "localhost", + "port": +} +``` + +### 3. WASI Debugging + +For WASI applications, use the Mono Debug extension: + +```json +{ + "name": "Attach", + "type": "mono", + "request": "attach", + "address": "localhost", + "port": 64000 +} +``` + +### 4. Setup Steps + +1. **Set initial breakpoint**: Place a breakpoint in `WasmTestRunner.cs` or your main entry point to prevent execution before you're ready +2. **Run the configuration**: Launch the VS Code debug configuration +3. **Set additional breakpoints**: Once stopped, set breakpoints in the code you want to debug +4. **Continue execution**: Click Resume or F5 to continue + +## Debug with Chrome DevTools + +### 1. Basic Setup + +1. **Open Chrome Inspector**: Navigate to `chrome://inspect/#devices` in a new Chrome tab +2. **Configure proxy**: Click "Configure" and add the proxy address from your application output (e.g., `127.0.0.1:58346`) +3. **Select target**: Click "Inspect" next to your application in the Remote Targets list + +### 2. Using DevTools + +1. **Sources tab**: Look for the `file://` directory to browse source files +2. **Wait for files to load**: It may take time for all source files to appear +3. **Set breakpoints**: Click on line numbers to set breakpoints +4. **Initial run strategy**: Consider using the first run to set an initial breakpoint in `WasmTestRunner.cs`, then restart the application + +### 3. For Native/C Code Debugging + +1. **Install DWARF extension**: Install the "C/C++ DevTools Support (DWARF)" Chrome extension +2. **Enable symbols**: Build with `WasmNativeDebugSymbols=true` and `WasmNativeStrip=false` +3. **Debug native code**: Step through C/C++ code, set breakpoints, and inspect WebAssembly linear memory + +## Starting Chrome with Remote Debugging + +To enable remote debugging for WebAssembly applications: + +```bash +# Close all Chrome instances first +chrome --remote-debugging-port=9222 +``` + +Replace `` with the URL shown in your application's output. + +## Common Debugging Workflow + +### For Library Tests + +1. **Run test with debugging**: + ```bash + dotnet run -r browser-wasm -c Debug --project src/libraries/System.Collections/tests/System.Collections.Tests.csproj --debug --host browser -p:DebuggerSupport=true + ``` + +2. **Note the output**: Look for lines like: + ``` + Debug proxy for chrome now listening on http://127.0.0.1:58346/ + App url: http://127.0.0.1:9000/index.html?arg=--debug&arg=--run&arg=WasmTestRunner.dll + ``` + +3. **Start Chrome**: Use the app URL with remote debugging enabled +4. **Attach debugger**: Use either Chrome DevTools or VS Code as described above + +### For WASI Applications + +1. **Build with debug**: + ```bash + cd sample/console + make debug + ``` + +2. **Set up VS Code**: Use the Mono Debug extension configuration above +3. **Set breakpoints**: Place breakpoints in your Program.cs or other C# files +4. **Start debugging**: Launch the VS Code configuration + +## Troubleshooting + +### Files Not Loading in DevTools +- Wait patiently - source files can take time to load initially +- Try refreshing the DevTools window +- Ensure your build includes debug symbols + +### Breakpoints Not Hit +- Verify the proxy port matches your configuration +- Check that Chrome is started with remote debugging enabled +- Ensure your breakpoints are set in code that will actually execute + +### Connection Issues +- Verify no firewall is blocking the proxy port +- Check that the proxy is still running (visible in application output) +- Try restarting both the application and Chrome + +## Advanced Debugging + +### Enable Additional Logging + +Add environment variables for more detailed logging: + +```javascript +await dotnet + .withDiagnosticTracing(true) + .withConfig({ + environmentVariables: { + "MONO_LOG_LEVEL": "debug", + "MONO_LOG_MASK": "all" + } + }) + .run(); +``` + +### Native Stack Traces + +For native crashes with symbols: + +1. **Build configuration**: + ```xml + + true + false + + ``` + +2. **Install DWARF extension** in Chrome for C/C++ debugging support + +### Collect Stack Traces + +From runtime code: +```c +#ifdef HOST_WASM +mono_wasm_print_stack_trace(); +#endif +``` + +Or break into JavaScript debugger: +```c +#include +EM_ASM(debugger;); +``` + +## References + +- [Testing Libraries on WebAssembly](../testing/libraries/testing-wasm.md) +- [Debugging WebAssembly Libraries](../testing/libraries/debugging-wasm.md) +- [WASM Runtime Debugging](debugging/mono/wasm-debugging.md) +- [WASI Support](../../src/mono/wasi/README.md) +- [VS Code Debugging Guide](debugging/libraries/debugging-vscode.md) \ No newline at end of file diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md new file mode 100644 index 00000000000000..f4cadf2f095308 --- /dev/null +++ b/docs/workflow/wasm-documentation.md @@ -0,0 +1,232 @@ +# WebAssembly (WASM) Documentation + +This document serves as a comprehensive index to all WebAssembly-related documentation in the dotnet/runtime repository. Whether you're building, testing, debugging, or deploying .NET applications for WebAssembly, this guide will help you find the right resources. + +## Table of Contents + +- [Getting Started](#getting-started) +- [Building for WebAssembly](#building-for-webassembly) +- [Testing and Debugging](#testing-and-debugging) +- [Features and Configuration](#features-and-configuration) +- [Deployment and Hosting](#deployment-and-hosting) +- [Advanced Topics](#advanced-topics) +- [FAQ](#faq) +- [Contributing](#contributing) + +## Getting Started + +### What is .NET WebAssembly? +.NET WebAssembly allows you to run .NET applications in web browsers and other WebAssembly-compatible environments. The runtime uses the Mono runtime to execute .NET bytecode compiled to WebAssembly. + +### Supported Environments +- **Browser (browser-wasm)**: Run .NET applications in web browsers +- **WASI (wasi-wasm)**: Run .NET applications in WASI-compatible environments + +### Quick Start +1. Install the workload: `dotnet workload install wasm-tools` +2. Create a new project: `dotnet new wasmbrowser` or `dotnet new wasiconsole` +3. Build and run: `dotnet run` + +## Building for WebAssembly + +### Core Runtime Building +- **[Building CoreCLR for WebAssembly](building/coreclr/wasm.md)** - Build the CoreCLR runtime for WebAssembly targets +- **[Building Mono for Browser](../src/mono/browser/README.md)** - Comprehensive browser build guide with samples and troubleshooting + +### Libraries Building +- **[Building Libraries for WebAssembly](building/libraries/webassembly-instructions.md)** - Build .NET libraries for WebAssembly targets +- **[WebAssembly Build System](../src/mono/browser/build/README.md)** - WasmApp.targets and build system internals + +### WASI Support +- **[WASI Support](../src/mono/wasi/README.md)** - Experimental WASI support, building, and configuration + +## Testing and Debugging + +### Library Testing +- **[Testing Libraries on WebAssembly](testing/libraries/testing-wasm.md)** - Run library tests with different JavaScript engines and browsers +- **[Debugging WebAssembly Libraries](testing/libraries/debugging-wasm.md)** - Debug library tests in Chrome DevTools and VS Code + +### Runtime Debugging +- **[WASM Runtime Debugging](debugging/mono/wasm-debugging.md)** - Debug the Mono runtime, native crashes, and collect stack traces +- **[VS Code Debugging](debugging/libraries/debugging-vscode.md)** - Set up VS Code for debugging WASM applications + +### Common Debugging Scenarios + +#### Debug with VS Code +Add this configuration to your `.vscode/launch.json`: +```json +{ + "name": "Libraries", + "request": "attach", + "type": "chrome", + "address": "localhost", + "port": +} +``` + +See detailed instructions in: +- [Library debugging guide](testing/libraries/debugging-wasm.md#debug-with-vs-code) +- [WASI debugging](../src/mono/wasi/README.md#4-debug-it) +- [VS Code debugging guide](debugging/libraries/debugging-vscode.md) + +#### Debug with Chrome DevTools +1. Open `chrome://inspect/#devices` in Chrome +2. Configure the proxy address from your test output +3. Select "Inspect" on your application +4. Set breakpoints in the Sources tab under `file://` + +## Features and Configuration + +### Runtime Features +- **[WebAssembly Features](../src/mono/wasm/features.md)** - Configure browser features, SIMD, threads, AOT, and more +- **[Threading Support](../src/mono/wasm/threads.md)** - Multi-threading support and limitations + +### Build Configuration +Key MSBuild properties for WebAssembly applications: +- `WasmEnableThreads` - Enable multi-threading support +- `WasmEnableSIMD` - Enable SIMD instruction support +- `RunAOTCompilation` - Enable Ahead-of-Time compilation +- `WasmBuildNative` - Force native rebuild +- `EnableDiagnostics` - Enable diagnostic features + +### Globalization and ICU +- **[ICU for WebAssembly](../design/features/globalization-icu-wasm.md)** - Globalization and ICU database configuration + +## Deployment and Hosting + +### Application Structure +- **AppBundle folder**: Contains your deployed application +- **_framework folder**: Runtime and managed assemblies +- **dotnet.js**: Main entry point and JavaScript API +- **dotnet.native.wasm**: Compiled .NET runtime binary + +### Web Server Configuration +Ensure your web server is configured with proper MIME types: +- `.wasm` files: `application/wasm` +- `.js` files: `text/javascript` +- `.json` files: `application/json` + +## Advanced Topics + +### Performance and Optimization +- **Profiling**: Use browser dev tools profiler integration +- **AOT Compilation**: Improve runtime performance with ahead-of-time compilation +- **IL Trimming**: Reduce application size by removing unused code + +### Samples and Examples +Located in `src/mono/sample/wasm/`: +- **browser-bench**: Performance benchmarking sample +- **browser-profile**: Profiling sample +- **console**: Console application samples + +### Workloads +- `wasm-tools`: Production WebAssembly tools and optimization +- `wasm-experimental`: Experimental features and templates + +## FAQ + +### How do I debug a library test failure seen on CI? + +1. **Run the test locally with debugging enabled**: + ```bash + dotnet run -r browser-wasm -c Debug --project src/libraries/System.Collections/tests/System.Collections.Tests.csproj --debug --host browser -p:DebuggerSupport=true + ``` + +2. **Start Chrome with remote debugging**: + ```bash + chrome --remote-debugging-port=9222 + ``` + +3. **Attach debugger**: Use either Chrome DevTools (`chrome://inspect/#devices`) or VS Code with the configuration above. + +4. **Set breakpoints**: Start with `WasmTestRunner.cs` to prevent tests from running before you're ready. + +### How do I build for different WebAssembly targets? + +- **Browser**: `./build.sh -os browser -subset mono+libs` +- **WASI**: `./build.sh -os wasi -subset mono+libs` +- **Specific library**: `dotnet build /t:Test src/libraries/System.AppContext/tests /p:TargetOS=browser` + +### How do I enable multi-threading? + +1. **Add to your .csproj**: + ```xml + + true + + ``` + +2. **Configure HTTP headers** on your server: + ``` + Cross-Origin-Embedder-Policy: require-corp + Cross-Origin-Opener-Policy: same-origin + ``` + +### How do I optimize my WebAssembly application? + +1. **Enable AOT compilation**: + ```xml + + true + + ``` + +2. **Enable IL trimming**: + ```xml + + true + full + + ``` + +3. **Install wasm-tools workload**: `dotnet workload install wasm-tools` + +### What JavaScript engines are supported for testing? + +- **V8**: Default engine for most tests +- **SpiderMonkey**: Firefox's JavaScript engine +- **JavaScriptCore**: Safari's JavaScript engine +- **Chrome/Firefox**: For browser-based testing + +Install with jsvu: `npm install jsvu -g && jsvu` + +### How do I collect native stack traces with symbols? + +1. **Add to your .csproj**: + ```xml + + true + false + + ``` + +2. **Use Chrome DevTools** with the C/C++ DevTools Support (DWARF) extension + +### How do I run tests with different configurations? + +- **With AOT**: Add `/p:RunAOTCompilation=true` +- **With trimming**: Add `/p:EnableAggressiveTrimming=true` +- **Different JS engine**: Add `/p:JSEngine=SpiderMonkey` +- **Outer loop tests**: Add `/p:Outerloop=true` + +## Contributing + +### Code Style +- Runtime JavaScript code uses ESLint rules in `.eslintrc.js` +- Run `npm run lint` in `src/mono/browser/runtime` +- Install VS Code ESLint plugin for real-time checking + +### Building Changes +When making changes that affect native code or build configuration: +1. Clean build artifacts: `git clean -xfd` +2. Rebuild: `./build.sh -os browser -subset mono+libs` +3. Test your changes with relevant test suites + +### Documentation Updates +When updating WebAssembly documentation: +1. Update this index if adding new documents +2. Ensure cross-references remain valid +3. Test documentation examples locally +4. Follow existing documentation patterns and styles + +For questions or additional help, see the main [workflow documentation](README.md) or ask in the dotnet/runtime repository discussions. \ No newline at end of file From 19751c6f683bf83a631d23e981948f9a6db5c473 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 25 Sep 2025 16:08:57 +0000 Subject: [PATCH 03/21] Consolidate duplicated debugging instructions and add cross-references Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- docs/workflow/building/coreclr/wasm.md | 6 ++- .../debugging/libraries/debugging-vscode.md | 4 +- .../workflow/debugging/mono/wasm-debugging.md | 7 +++- .../testing/libraries/debugging-wasm.md | 41 +++++++++---------- docs/workflow/wasm-documentation.md | 12 +++--- src/mono/browser/README.md | 2 + src/mono/wasi/README.md | 27 ++++++------ src/mono/wasm/features.md | 2 + src/mono/wasm/threads.md | 6 ++- 9 files changed, 58 insertions(+), 49 deletions(-) diff --git a/docs/workflow/building/coreclr/wasm.md b/docs/workflow/building/coreclr/wasm.md index b2c6caa2d495d6..9fcad40068d103 100644 --- a/docs/workflow/building/coreclr/wasm.md +++ b/docs/workflow/building/coreclr/wasm.md @@ -85,6 +85,8 @@ Note that paths to assemblies are in the `src/native/corehost/browserhost/sample ## Debugging +For comprehensive debugging instructions including VS Code and Chrome DevTools setup, see the [WebAssembly Debugging Reference](../debugging/wasm-debugging-reference.md). + ### 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: @@ -103,7 +105,9 @@ For debugging CoreCLR WebAssembly code, the recommended approach is using Chrome ### VS Code WebAssembly Debugging -VS Code, through Node.js, provides a good debugging option for WebAssembly CoreCLR: +VS Code, through Node.js, provides a good debugging option for WebAssembly CoreCLR. See the [debugging reference](../debugging/wasm-debugging-reference.md#debug-with-vs-code) for detailed setup instructions. + +**Quick setup** for CoreCLR debugging: 1. **Install the VS Code extension (Optional):** - [WebAssembly Dwarf Debugging](https://marketplace.visualstudio.com/items?itemName=ms-vscode.wasm-dwarf-debugging) diff --git a/docs/workflow/debugging/libraries/debugging-vscode.md b/docs/workflow/debugging/libraries/debugging-vscode.md index c8f8f2424d3393..ee4d6cdfe7803c 100644 --- a/docs/workflow/debugging/libraries/debugging-vscode.md +++ b/docs/workflow/debugging/libraries/debugging-vscode.md @@ -24,7 +24,9 @@ ## Debugging Libraries with Visual Studio Code running on Mono To debug the libraries on a "desktop" platform (Linux/Mac/Windows, not WebAssembly, or iOS or Android) running on Mono runtime, follow the instructions below. -See also [Android debugging](../mono/android-debugging.md) and [WebAssembly debugging](../mono/wasm-debugging.md) +See also [Android debugging](../mono/android-debugging.md) and [WebAssembly debugging](../mono/wasm-debugging.md). + +For WebAssembly-specific debugging scenarios, see the [WebAssembly Debugging Reference](../wasm-debugging-reference.md). - Install the VS Code [Mono Debugger (`ms-vscode.mono-debug`)](https://marketplace.visualstudio.com/items?itemName=ms-vscode.mono-debug) extension - Create a `launch.json` file configuration with type `mono` diff --git a/docs/workflow/debugging/mono/wasm-debugging.md b/docs/workflow/debugging/mono/wasm-debugging.md index 26b5f62ec478b1..a5928b3f8d19eb 100644 --- a/docs/workflow/debugging/mono/wasm-debugging.md +++ b/docs/workflow/debugging/mono/wasm-debugging.md @@ -1,6 +1,9 @@ -WASM runtime debugging -====================== +# WASM Runtime Debugging + +This document covers debugging the Mono WebAssembly runtime itself, native crashes, and advanced debugging scenarios. For general WebAssembly application debugging, see the [WebAssembly Debugging Reference](../wasm-debugging-reference.md). + +## Native Runtime Debugging - Disable symbol stripping by setting the `WasmNativeStrip` msbuild property to `false`. See also, [collecting stack traces with symbols in Blazor](#collecting-stack-traces-with-symbols-in-blazor) diff --git a/docs/workflow/testing/libraries/debugging-wasm.md b/docs/workflow/testing/libraries/debugging-wasm.md index 8c7f4d2645ee6a..d1e16899ea8efa 100644 --- a/docs/workflow/testing/libraries/debugging-wasm.md +++ b/docs/workflow/testing/libraries/debugging-wasm.md @@ -25,33 +25,30 @@ You may need to close all Chrome instances. Then, start the browser with debuggi Now you can choose an IDE to start debugging. Remember that the tests wait only till the debugger gets attached. Once it does, they start running. You may want to set breakpoints first, before attaching the debugger, e.g. setting one in `src\libraries\Common\tests\WasmTestRunner\WasmTestRunner.cs` on the first line of `Main()` will prevent any test to be run before you get prepared. ## Debug with Chrome DevTools -Open `chrome://inspect/#devices` in a new tab in the browser you started. Select `Configure`: -![image](https://user-images.githubusercontent.com/32700855/201867874-7f707eb1-e859-441c-8205-abb70a7a0d0b.png) +For detailed Chrome DevTools debugging instructions, see the [WebAssembly Debugging Reference](../debugging/wasm-debugging-reference.md#debug-with-chrome-devtools). -and paste the address of proxy that was provided in the program output. +Quick summary: +1. Open `chrome://inspect/#devices` in Chrome +2. Configure the proxy address from the program output +3. Click "Inspect" on your application +4. Set breakpoints in the Sources tab under `file://` -![image](https://user-images.githubusercontent.com/32700855/201862487-df76a06c-b24d-41a0-bf06-6959bba59a58.png) - -New remote targets will be displayed, select the address you opened in the other tab by clicking `Inspect`. - -![image](https://user-images.githubusercontent.com/32700855/201863048-6a4fe20b-a215-435d-b594-47750fcb2872.png) - -A new window with Chrome DevTools will be opened. In the tab `sources` you should look for `file://` directory. There you can browse through libraries file tree and open the source code. It can take some time to load the files. When the IDE is ready the tests will start running. You cannot set a breakpoints in Chrome DevTools before the files get loaded, so you might want to use the first run for setting the initial breakpoint in `WasmTestRunner.cs` and then rerun the app. DevTools will stop on the previously set breakpoint and you will have time to set breakpoints in the libs you want to debug and click Resume. +Note: It can take time for source files to load. Consider setting an initial breakpoint in `WasmTestRunner.cs` on the first run. ## Debug with VS Code -Add following configuration to your `.vscode/launch.json`: -``` - { - "name": "Libraries", - "request": "attach", - "type": "chrome", - "address": "localhost", - "port": - } +For detailed VS Code debugging instructions, see the [WebAssembly Debugging Reference](../debugging/wasm-debugging-reference.md#debug-with-vs-code). + +Quick setup: +```json +{ + "name": "Libraries", + "request": "attach", + "type": "chrome", + "address": "localhost", + "port": +} ``` -Set at least one breakpoint in the libraries, you can do it initially in `WasmTestRunner.cs`. -Run the configuration and be patient, it can take some time. Wait till VS Code will get stopped in `WasmTestRunner`. Set breakpoints in the libs you want to debug and click Resume. -![image](https://user-images.githubusercontent.com/32700855/201894003-fc5394ad-9848-4d07-a132-f687ecd17c50.png) +Replace `` with the port shown in your test output. Set an initial breakpoint in `WasmTestRunner.cs` to prevent tests from running before you're ready to debug. diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index f4cadf2f095308..ffb30acf9fe7ae 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -31,14 +31,14 @@ This document serves as a comprehensive index to all WebAssembly-related documen ### Core Runtime Building - **[Building CoreCLR for WebAssembly](building/coreclr/wasm.md)** - Build the CoreCLR runtime for WebAssembly targets -- **[Building Mono for Browser](../src/mono/browser/README.md)** - Comprehensive browser build guide with samples and troubleshooting +- **[Building Mono for Browser](../../src/mono/browser/README.md)** - Comprehensive browser build guide with samples and troubleshooting ### Libraries Building - **[Building Libraries for WebAssembly](building/libraries/webassembly-instructions.md)** - Build .NET libraries for WebAssembly targets -- **[WebAssembly Build System](../src/mono/browser/build/README.md)** - WasmApp.targets and build system internals +- **[WebAssembly Build System](../../src/mono/browser/build/README.md)** - WasmApp.targets and build system internals ### WASI Support -- **[WASI Support](../src/mono/wasi/README.md)** - Experimental WASI support, building, and configuration +- **[WASI Support](../../src/mono/wasi/README.md)** - Experimental WASI support, building, and configuration ## Testing and Debugging @@ -78,8 +78,8 @@ See detailed instructions in: ## Features and Configuration ### Runtime Features -- **[WebAssembly Features](../src/mono/wasm/features.md)** - Configure browser features, SIMD, threads, AOT, and more -- **[Threading Support](../src/mono/wasm/threads.md)** - Multi-threading support and limitations +- **[WebAssembly Features](../../src/mono/wasm/features.md)** - Configure browser features, SIMD, threads, AOT, and more +- **[Threading Support](../../src/mono/wasm/threads.md)** - Multi-threading support and limitations ### Build Configuration Key MSBuild properties for WebAssembly applications: @@ -90,7 +90,7 @@ Key MSBuild properties for WebAssembly applications: - `EnableDiagnostics` - Enable diagnostic features ### Globalization and ICU -- **[ICU for WebAssembly](../design/features/globalization-icu-wasm.md)** - Globalization and ICU database configuration +- **[ICU for WebAssembly](../../design/features/globalization-icu-wasm.md)** - Globalization and ICU database configuration ## Deployment and Hosting diff --git a/src/mono/browser/README.md b/src/mono/browser/README.md index baf2fe1785e678..a3ea89829f10e8 100644 --- a/src/mono/browser/README.md +++ b/src/mono/browser/README.md @@ -1,5 +1,7 @@ # Build WebAssembly +This document covers building .NET for WebAssembly in the browser. For comprehensive WebAssembly documentation including testing, debugging, and deployment, see [WebAssembly Documentation](../../../docs/workflow/wasm-documentation.md). + If you haven't already done so, please read [this document](../../../docs/workflow/README.md#Build_Requirements) to understand the build requirements for your operating system. If you are specifically interested in building libraries for WebAssembly, read [Libraries WebAssembly](../../../docs/workflow/building/libraries/webassembly-instructions.md). Emscripten that is needed to build the project will be provisioned automatically, unless `EMSDK_PATH` variable is set or emscripten is already present in `src\mono\browser\emsdk` directory. ### Windows diff --git a/src/mono/wasi/README.md b/src/mono/wasi/README.md index 1c2f8a2dc01b71..3fd140b00a560b 100644 --- a/src/mono/wasi/README.md +++ b/src/mono/wasi/README.md @@ -2,6 +2,8 @@ This directory contains a build configuration for WASI support, plus a basic sample. This is not intended for production use, nor is it currently supported. This is a step towards possible future support. +For comprehensive WebAssembly documentation, see [WebAssembly Documentation](../../../docs/workflow/wasm-documentation.md). + ## Try it out Here is a quick overview of how to consume published artifacts. Assuming .NET SDK is already installed, you should run: @@ -112,26 +114,21 @@ Finally, you can build and run the sample: ### 4. Debug it -Also, you can build and debug the sample: +For detailed WASI debugging instructions, see the [WebAssembly Debugging Reference](../../../docs/workflow/debugging/wasm-debugging-reference.md#for-wasi-applications). -``` +Quick setup: +```bash cd sample/console make debug ``` -Using Visual Studio code, add a breakpoint on Program.cs line 17. -Download the Mono Debug extension and configure a launch.json like this: -``` +Use VS Code with the Mono Debug extension and this launch.json configuration: +```json { - "version": "0.2.0", - "configurations": [ - { - "name": "Attach", - "type": "mono", - "request": "attach", - "address": "localhost", - "port": 64000 - } - ] + "name": "Attach", + "type": "mono", + "request": "attach", + "address": "localhost", + "port": 64000 } ``` diff --git a/src/mono/wasm/features.md b/src/mono/wasm/features.md index 97f1e8213d988f..466dcd81362279 100644 --- a/src/mono/wasm/features.md +++ b/src/mono/wasm/features.md @@ -1,5 +1,7 @@ # Configuring and hosting .NET WebAssembly applications +For comprehensive WebAssembly documentation including building, testing, and debugging, see [WebAssembly Documentation](../../../docs/workflow/wasm-documentation.md). + ## Table of contents - [Configuring browser features](#Configuring-browser-features) - [Project folder structure](#Project-folder-structure) diff --git a/src/mono/wasm/threads.md b/src/mono/wasm/threads.md index 6e73bfb0b575e6..f4cd6579da9375 100644 --- a/src/mono/wasm/threads.md +++ b/src/mono/wasm/threads.md @@ -1,6 +1,8 @@ -# Threaded runtime # +# Threaded runtime -## Building the runtime ## +For comprehensive WebAssembly documentation including building, testing, and debugging, see [WebAssembly Documentation](../../../docs/workflow/wasm-documentation.md). + +## Building the runtime Build the runtime with `/p:WasmEnableThreads=true` to enable support for multi-threading. From e6c8fbe99ecfabb955edc9ddbc9513449aa6d7de Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 26 Sep 2025 09:28:47 +0000 Subject: [PATCH 04/21] Address feedback: consolidate debugging docs and remove duplicated content Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- docs/workflow/building/coreclr/wasm.md | 6 +- .../debugging/libraries/debugging-vscode.md | 2 +- ...-debugging.md => native-wasm-debugging.md} | 4 +- .../debugging/wasm-debugging-reference.md | 64 ++++++------- .../testing/libraries/debugging-wasm.md | 21 ----- docs/workflow/wasm-documentation.md | 90 ++----------------- src/mono/wasi/README.md | 17 ---- 7 files changed, 37 insertions(+), 167 deletions(-) rename docs/workflow/debugging/mono/{wasm-debugging.md => native-wasm-debugging.md} (99%) diff --git a/docs/workflow/building/coreclr/wasm.md b/docs/workflow/building/coreclr/wasm.md index 9fcad40068d103..b2c6caa2d495d6 100644 --- a/docs/workflow/building/coreclr/wasm.md +++ b/docs/workflow/building/coreclr/wasm.md @@ -85,8 +85,6 @@ Note that paths to assemblies are in the `src/native/corehost/browserhost/sample ## Debugging -For comprehensive debugging instructions including VS Code and Chrome DevTools setup, see the [WebAssembly Debugging Reference](../debugging/wasm-debugging-reference.md). - ### 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: @@ -105,9 +103,7 @@ For debugging CoreCLR WebAssembly code, the recommended approach is using Chrome ### VS Code WebAssembly Debugging -VS Code, through Node.js, provides a good debugging option for WebAssembly CoreCLR. See the [debugging reference](../debugging/wasm-debugging-reference.md#debug-with-vs-code) for detailed setup instructions. - -**Quick setup** for CoreCLR debugging: +VS Code, through Node.js, provides a good debugging option for WebAssembly CoreCLR: 1. **Install the VS Code extension (Optional):** - [WebAssembly Dwarf Debugging](https://marketplace.visualstudio.com/items?itemName=ms-vscode.wasm-dwarf-debugging) diff --git a/docs/workflow/debugging/libraries/debugging-vscode.md b/docs/workflow/debugging/libraries/debugging-vscode.md index ee4d6cdfe7803c..17fcb129f9f790 100644 --- a/docs/workflow/debugging/libraries/debugging-vscode.md +++ b/docs/workflow/debugging/libraries/debugging-vscode.md @@ -24,7 +24,7 @@ ## Debugging Libraries with Visual Studio Code running on Mono To debug the libraries on a "desktop" platform (Linux/Mac/Windows, not WebAssembly, or iOS or Android) running on Mono runtime, follow the instructions below. -See also [Android debugging](../mono/android-debugging.md) and [WebAssembly debugging](../mono/wasm-debugging.md). +See also [Android debugging](../mono/android-debugging.md) and [WebAssembly debugging](../mono/native-wasm-debugging.md). For WebAssembly-specific debugging scenarios, see the [WebAssembly Debugging Reference](../wasm-debugging-reference.md). diff --git a/docs/workflow/debugging/mono/wasm-debugging.md b/docs/workflow/debugging/mono/native-wasm-debugging.md similarity index 99% rename from docs/workflow/debugging/mono/wasm-debugging.md rename to docs/workflow/debugging/mono/native-wasm-debugging.md index a5928b3f8d19eb..bb61a3dae1874e 100644 --- a/docs/workflow/debugging/mono/wasm-debugging.md +++ b/docs/workflow/debugging/mono/native-wasm-debugging.md @@ -1,9 +1,7 @@ -# WASM Runtime Debugging - This document covers debugging the Mono WebAssembly runtime itself, native crashes, and advanced debugging scenarios. For general WebAssembly application debugging, see the [WebAssembly Debugging Reference](../wasm-debugging-reference.md). -## Native Runtime Debugging +# Native Runtime Debugging - Disable symbol stripping by setting the `WasmNativeStrip` msbuild property to `false`. See also, [collecting stack traces with symbols in Blazor](#collecting-stack-traces-with-symbols-in-blazor) diff --git a/docs/workflow/debugging/wasm-debugging-reference.md b/docs/workflow/debugging/wasm-debugging-reference.md index efb16e6a872aec..7eaf87dfd516a5 100644 --- a/docs/workflow/debugging/wasm-debugging-reference.md +++ b/docs/workflow/debugging/wasm-debugging-reference.md @@ -1,53 +1,30 @@ # WebAssembly Debugging Reference -This document provides consolidated debugging instructions for WebAssembly applications that are referenced by multiple other documentation files. +This document provides consolidated debugging instructions for WebAssembly applications. ## Debug with VS Code To debug WebAssembly applications with Visual Studio Code: -### 1. Basic Configuration +### 1. Configuration -Add the following configuration to your `.vscode/launch.json`: +Add the appropriate configuration to your `.vscode/launch.json` depending on your debugging scenario: +**For WebAssembly applications, library tests, and general debugging:** ```json { - "version": "0.2.0", - "configurations": [ - { - "name": "WASM Attach", - "request": "attach", - "type": "chrome", - "address": "localhost", - "port": - } - ] -} -``` - -Replace `` with the proxy port shown in your application's output. - -### 2. Library Test Debugging - -For debugging library tests specifically: - -```json -{ - "name": "Libraries", - "request": "attach", + "name": "WASM Attach", + "request": "attach", "type": "chrome", "address": "localhost", "port": } ``` -### 3. WASI Debugging - -For WASI applications, use the Mono Debug extension: - +**For WASI applications:** ```json { - "name": "Attach", + "name": "WASI Attach", "type": "mono", "request": "attach", "address": "localhost", @@ -55,7 +32,9 @@ For WASI applications, use the Mono Debug extension: } ``` -### 4. Setup Steps +Replace `` with the proxy port shown in your application's output. + +### 2. Setup Steps 1. **Set initial breakpoint**: Place a breakpoint in `WasmTestRunner.cs` or your main entry point to prevent execution before you're ready 2. **Run the configuration**: Launch the VS Code debug configuration @@ -67,15 +46,24 @@ For WASI applications, use the Mono Debug extension: ### 1. Basic Setup 1. **Open Chrome Inspector**: Navigate to `chrome://inspect/#devices` in a new Chrome tab -2. **Configure proxy**: Click "Configure" and add the proxy address from your application output (e.g., `127.0.0.1:58346`) -3. **Select target**: Click "Inspect" next to your application in the Remote Targets list +2. **Configure proxy**: Click "Configure": + +![image](https://user-images.githubusercontent.com/32700855/201867874-7f707eb1-e859-441c-8205-abb70a7a0d0b.png) + +and paste the address of proxy that was provided in the program output: + +![image](https://user-images.githubusercontent.com/32700855/201862487-df76a06c-b24d-41a0-bf06-6959bba59a58.png) + +3. **Select target**: New remote targets will be displayed, select the address you opened in the other tab by clicking `Inspect`: + +![image](https://user-images.githubusercontent.com/32700855/201863048-6a4fe20b-a215-435d-b594-47750fcb2872.png) ### 2. Using DevTools -1. **Sources tab**: Look for the `file://` directory to browse source files -2. **Wait for files to load**: It may take time for all source files to appear -3. **Set breakpoints**: Click on line numbers to set breakpoints -4. **Initial run strategy**: Consider using the first run to set an initial breakpoint in `WasmTestRunner.cs`, then restart the application +1. **Sources tab**: A new window with Chrome DevTools will be opened. In the tab `sources` you should look for `file://` directory to browse source files +2. **Wait for files to load**: It may take time for all source files to appear. You cannot set breakpoints in Chrome DevTools before the files get loaded +3. **Set breakpoints**: Click on line numbers to set breakpoints +4. **Initial run strategy**: Consider using the first run to set an initial breakpoint in `WasmTestRunner.cs`, then restart the application. DevTools will stop on the previously set breakpoint and you will have time to set breakpoints in the libs you want to debug and click Resume ### 3. For Native/C Code Debugging diff --git a/docs/workflow/testing/libraries/debugging-wasm.md b/docs/workflow/testing/libraries/debugging-wasm.md index d1e16899ea8efa..70f96bcf3d6cbf 100644 --- a/docs/workflow/testing/libraries/debugging-wasm.md +++ b/docs/workflow/testing/libraries/debugging-wasm.md @@ -28,27 +28,6 @@ Now you can choose an IDE to start debugging. Remember that the tests wait only For detailed Chrome DevTools debugging instructions, see the [WebAssembly Debugging Reference](../debugging/wasm-debugging-reference.md#debug-with-chrome-devtools). -Quick summary: -1. Open `chrome://inspect/#devices` in Chrome -2. Configure the proxy address from the program output -3. Click "Inspect" on your application -4. Set breakpoints in the Sources tab under `file://` - -Note: It can take time for source files to load. Consider setting an initial breakpoint in `WasmTestRunner.cs` on the first run. - ## Debug with VS Code For detailed VS Code debugging instructions, see the [WebAssembly Debugging Reference](../debugging/wasm-debugging-reference.md#debug-with-vs-code). - -Quick setup: -```json -{ - "name": "Libraries", - "request": "attach", - "type": "chrome", - "address": "localhost", - "port": -} -``` - -Replace `` with the port shown in your test output. Set an initial breakpoint in `WasmTestRunner.cs` to prevent tests from running before you're ready to debug. diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index ffb30acf9fe7ae..79923143c2be9a 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -47,33 +47,12 @@ This document serves as a comprehensive index to all WebAssembly-related documen - **[Debugging WebAssembly Libraries](testing/libraries/debugging-wasm.md)** - Debug library tests in Chrome DevTools and VS Code ### Runtime Debugging -- **[WASM Runtime Debugging](debugging/mono/wasm-debugging.md)** - Debug the Mono runtime, native crashes, and collect stack traces +- **[Native WASM Runtime Debugging](debugging/mono/native-wasm-debugging.md)** - Debug the Mono runtime, native crashes, and collect stack traces - **[VS Code Debugging](debugging/libraries/debugging-vscode.md)** - Set up VS Code for debugging WASM applications ### Common Debugging Scenarios -#### Debug with VS Code -Add this configuration to your `.vscode/launch.json`: -```json -{ - "name": "Libraries", - "request": "attach", - "type": "chrome", - "address": "localhost", - "port": -} -``` - -See detailed instructions in: -- [Library debugging guide](testing/libraries/debugging-wasm.md#debug-with-vs-code) -- [WASI debugging](../src/mono/wasi/README.md#4-debug-it) -- [VS Code debugging guide](debugging/libraries/debugging-vscode.md) - -#### Debug with Chrome DevTools -1. Open `chrome://inspect/#devices` in Chrome -2. Configure the proxy address from your test output -3. Select "Inspect" on your application -4. Set breakpoints in the Sources tab under `file://` +For consolidated debugging instructions including VS Code and Chrome DevTools setup, see the [WebAssembly Debugging Reference](debugging/wasm-debugging-reference.md). ## Features and Configuration @@ -127,80 +106,27 @@ Located in `src/mono/sample/wasm/`: ### How do I debug a library test failure seen on CI? -1. **Run the test locally with debugging enabled**: - ```bash - dotnet run -r browser-wasm -c Debug --project src/libraries/System.Collections/tests/System.Collections.Tests.csproj --debug --host browser -p:DebuggerSupport=true - ``` - -2. **Start Chrome with remote debugging**: - ```bash - chrome --remote-debugging-port=9222 - ``` - -3. **Attach debugger**: Use either Chrome DevTools (`chrome://inspect/#devices`) or VS Code with the configuration above. - -4. **Set breakpoints**: Start with `WasmTestRunner.cs` to prevent tests from running before you're ready. +See the [WebAssembly Debugging Reference](debugging/wasm-debugging-reference.md#common-debugging-workflow) for detailed instructions on debugging library tests locally. ### How do I build for different WebAssembly targets? -- **Browser**: `./build.sh -os browser -subset mono+libs` -- **WASI**: `./build.sh -os wasi -subset mono+libs` -- **Specific library**: `dotnet build /t:Test src/libraries/System.AppContext/tests /p:TargetOS=browser` +See the [Building for WebAssembly](#building-for-webassembly) section above for comprehensive build instructions for different targets. ### How do I enable multi-threading? -1. **Add to your .csproj**: - ```xml - - true - - ``` - -2. **Configure HTTP headers** on your server: - ``` - Cross-Origin-Embedder-Policy: require-corp - Cross-Origin-Opener-Policy: same-origin - ``` +See the [Threading Support](../../src/mono/wasm/threads.md) documentation for detailed multi-threading configuration and limitations. ### How do I optimize my WebAssembly application? -1. **Enable AOT compilation**: - ```xml - - true - - ``` - -2. **Enable IL trimming**: - ```xml - - true - full - - ``` - -3. **Install wasm-tools workload**: `dotnet workload install wasm-tools` +See the [WebAssembly Features](../../src/mono/wasm/features.md) documentation for AOT compilation, IL trimming, and other optimization options. ### What JavaScript engines are supported for testing? -- **V8**: Default engine for most tests -- **SpiderMonkey**: Firefox's JavaScript engine -- **JavaScriptCore**: Safari's JavaScript engine -- **Chrome/Firefox**: For browser-based testing - -Install with jsvu: `npm install jsvu -g && jsvu` +See the [Testing Libraries on WebAssembly](testing/libraries/testing-wasm.md#prerequisites) documentation for JavaScript engine installation and usage. ### How do I collect native stack traces with symbols? -1. **Add to your .csproj**: - ```xml - - true - false - - ``` - -2. **Use Chrome DevTools** with the C/C++ DevTools Support (DWARF) extension +See the [Native WASM Runtime Debugging](debugging/mono/native-wasm-debugging.md#collecting-stack-traces-with-symbols-in-blazor) documentation for symbol configuration. ### How do I run tests with different configurations? diff --git a/src/mono/wasi/README.md b/src/mono/wasi/README.md index 3fd140b00a560b..e78022a73cf819 100644 --- a/src/mono/wasi/README.md +++ b/src/mono/wasi/README.md @@ -115,20 +115,3 @@ Finally, you can build and run the sample: ### 4. Debug it For detailed WASI debugging instructions, see the [WebAssembly Debugging Reference](../../../docs/workflow/debugging/wasm-debugging-reference.md#for-wasi-applications). - -Quick setup: -```bash -cd sample/console -make debug -``` - -Use VS Code with the Mono Debug extension and this launch.json configuration: -```json -{ - "name": "Attach", - "type": "mono", - "request": "attach", - "address": "localhost", - "port": 64000 -} -``` From 0742bbf0f3412e0aec052bf65b1f46ce9b6949f4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 26 Sep 2025 10:03:24 +0000 Subject: [PATCH 05/21] Rename wasm-debugging-reference.md to wasm-debugging.md and remove duplicated stack trace content Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- .../debugging/libraries/debugging-vscode.md | 2 +- .../debugging/mono/native-wasm-debugging.md | 2 +- ...asm-debugging-reference.md => wasm-debugging.md} | 13 +------------ docs/workflow/testing/libraries/debugging-wasm.md | 4 ++-- docs/workflow/wasm-documentation.md | 4 ++-- src/mono/wasi/README.md | 2 +- 6 files changed, 8 insertions(+), 19 deletions(-) rename docs/workflow/debugging/{wasm-debugging-reference.md => wasm-debugging.md} (96%) diff --git a/docs/workflow/debugging/libraries/debugging-vscode.md b/docs/workflow/debugging/libraries/debugging-vscode.md index 17fcb129f9f790..16da43263c889e 100644 --- a/docs/workflow/debugging/libraries/debugging-vscode.md +++ b/docs/workflow/debugging/libraries/debugging-vscode.md @@ -26,7 +26,7 @@ To debug the libraries on a "desktop" platform (Linux/Mac/Windows, not WebAssembly, or iOS or Android) running on Mono runtime, follow the instructions below. See also [Android debugging](../mono/android-debugging.md) and [WebAssembly debugging](../mono/native-wasm-debugging.md). -For WebAssembly-specific debugging scenarios, see the [WebAssembly Debugging Reference](../wasm-debugging-reference.md). +For WebAssembly-specific debugging scenarios, see the [WebAssembly Debugging Reference](../wasm-debugging.md). - Install the VS Code [Mono Debugger (`ms-vscode.mono-debug`)](https://marketplace.visualstudio.com/items?itemName=ms-vscode.mono-debug) extension - Create a `launch.json` file configuration with type `mono` diff --git a/docs/workflow/debugging/mono/native-wasm-debugging.md b/docs/workflow/debugging/mono/native-wasm-debugging.md index bb61a3dae1874e..2237b33c9f16c8 100644 --- a/docs/workflow/debugging/mono/native-wasm-debugging.md +++ b/docs/workflow/debugging/mono/native-wasm-debugging.md @@ -1,5 +1,5 @@ -This document covers debugging the Mono WebAssembly runtime itself, native crashes, and advanced debugging scenarios. For general WebAssembly application debugging, see the [WebAssembly Debugging Reference](../wasm-debugging-reference.md). +This document covers debugging the Mono WebAssembly runtime itself, native crashes, and advanced debugging scenarios. For general WebAssembly application debugging, see the [WebAssembly Debugging Reference](../wasm-debugging.md). # Native Runtime Debugging diff --git a/docs/workflow/debugging/wasm-debugging-reference.md b/docs/workflow/debugging/wasm-debugging.md similarity index 96% rename from docs/workflow/debugging/wasm-debugging-reference.md rename to docs/workflow/debugging/wasm-debugging.md index 7eaf87dfd516a5..27bb5b9c09418c 100644 --- a/docs/workflow/debugging/wasm-debugging-reference.md +++ b/docs/workflow/debugging/wasm-debugging.md @@ -163,18 +163,7 @@ For native crashes with symbols: ### Collect Stack Traces -From runtime code: -```c -#ifdef HOST_WASM -mono_wasm_print_stack_trace(); -#endif -``` - -Or break into JavaScript debugger: -```c -#include -EM_ASM(debugger;); -``` +For detailed instructions on collecting stack traces and breaking into the JavaScript debugger from runtime code, see the [Native WASM Runtime Debugging](mono/native-wasm-debugging.md) documentation. ## References diff --git a/docs/workflow/testing/libraries/debugging-wasm.md b/docs/workflow/testing/libraries/debugging-wasm.md index 70f96bcf3d6cbf..da60f816152d07 100644 --- a/docs/workflow/testing/libraries/debugging-wasm.md +++ b/docs/workflow/testing/libraries/debugging-wasm.md @@ -26,8 +26,8 @@ Now you can choose an IDE to start debugging. Remember that the tests wait only ## Debug with Chrome DevTools -For detailed Chrome DevTools debugging instructions, see the [WebAssembly Debugging Reference](../debugging/wasm-debugging-reference.md#debug-with-chrome-devtools). +For detailed Chrome DevTools debugging instructions, see the [WebAssembly Debugging Reference](../debugging/wasm-debugging.md#debug-with-chrome-devtools). ## Debug with VS Code -For detailed VS Code debugging instructions, see the [WebAssembly Debugging Reference](../debugging/wasm-debugging-reference.md#debug-with-vs-code). +For detailed VS Code debugging instructions, see the [WebAssembly Debugging Reference](../debugging/wasm-debugging.md#debug-with-vs-code). diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index 79923143c2be9a..68145cc522fbdb 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -52,7 +52,7 @@ This document serves as a comprehensive index to all WebAssembly-related documen ### Common Debugging Scenarios -For consolidated debugging instructions including VS Code and Chrome DevTools setup, see the [WebAssembly Debugging Reference](debugging/wasm-debugging-reference.md). +For consolidated debugging instructions including VS Code and Chrome DevTools setup, see the [WebAssembly Debugging Reference](debugging/wasm-debugging.md). ## Features and Configuration @@ -106,7 +106,7 @@ Located in `src/mono/sample/wasm/`: ### How do I debug a library test failure seen on CI? -See the [WebAssembly Debugging Reference](debugging/wasm-debugging-reference.md#common-debugging-workflow) for detailed instructions on debugging library tests locally. +See the [WebAssembly Debugging Reference](debugging/wasm-debugging.md#common-debugging-workflow) for detailed instructions on debugging library tests locally. ### How do I build for different WebAssembly targets? diff --git a/src/mono/wasi/README.md b/src/mono/wasi/README.md index e78022a73cf819..1456056420c265 100644 --- a/src/mono/wasi/README.md +++ b/src/mono/wasi/README.md @@ -114,4 +114,4 @@ Finally, you can build and run the sample: ### 4. Debug it -For detailed WASI debugging instructions, see the [WebAssembly Debugging Reference](../../../docs/workflow/debugging/wasm-debugging-reference.md#for-wasi-applications). +For detailed WASI debugging instructions, see the [WebAssembly Debugging Reference](../../../docs/workflow/debugging/wasm-debugging.md#for-wasi-applications). From b2a10f7b4908d0e18f9e6baebb79075ed22e3a35 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 26 Sep 2025 10:40:28 +0000 Subject: [PATCH 06/21] Fix markdown linting errors by removing trailing spaces Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- docs/workflow/debugging/wasm-debugging.md | 10 +++++----- docs/workflow/wasm-documentation.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/workflow/debugging/wasm-debugging.md b/docs/workflow/debugging/wasm-debugging.md index 27bb5b9c09418c..69d8e15372b766 100644 --- a/docs/workflow/debugging/wasm-debugging.md +++ b/docs/workflow/debugging/wasm-debugging.md @@ -26,7 +26,7 @@ Add the appropriate configuration to your `.vscode/launch.json` depending on you { "name": "WASI Attach", "type": "mono", - "request": "attach", + "request": "attach", "address": "localhost", "port": 64000 } @@ -37,7 +37,7 @@ Replace `` with the proxy port shown in your application's output. ### 2. Setup Steps 1. **Set initial breakpoint**: Place a breakpoint in `WasmTestRunner.cs` or your main entry point to prevent execution before you're ready -2. **Run the configuration**: Launch the VS Code debug configuration +2. **Run the configuration**: Launch the VS Code debug configuration 3. **Set additional breakpoints**: Once stopped, set breakpoints in the code you want to debug 4. **Continue execution**: Click Resume or F5 to continue @@ -62,7 +62,7 @@ and paste the address of proxy that was provided in the program output: 1. **Sources tab**: A new window with Chrome DevTools will be opened. In the tab `sources` you should look for `file://` directory to browse source files 2. **Wait for files to load**: It may take time for all source files to appear. You cannot set breakpoints in Chrome DevTools before the files get loaded -3. **Set breakpoints**: Click on line numbers to set breakpoints +3. **Set breakpoints**: Click on line numbers to set breakpoints 4. **Initial run strategy**: Consider using the first run to set an initial breakpoint in `WasmTestRunner.cs`, then restart the application. DevTools will stop on the previously set breakpoint and you will have time to set breakpoints in the libs you want to debug and click Resume ### 3. For Native/C Code Debugging @@ -104,7 +104,7 @@ Replace `` with the URL shown in your application's output. 1. **Build with debug**: ```bash - cd sample/console + cd sample/console make debug ``` @@ -168,7 +168,7 @@ For detailed instructions on collecting stack traces and breaking into the JavaS ## References - [Testing Libraries on WebAssembly](../testing/libraries/testing-wasm.md) -- [Debugging WebAssembly Libraries](../testing/libraries/debugging-wasm.md) +- [Debugging WebAssembly Libraries](../testing/libraries/debugging-wasm.md) - [WASM Runtime Debugging](debugging/mono/wasm-debugging.md) - [WASI Support](../../src/mono/wasi/README.md) - [VS Code Debugging Guide](debugging/libraries/debugging-vscode.md) \ No newline at end of file diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index 68145cc522fbdb..b400512d1e8666 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -63,7 +63,7 @@ For consolidated debugging instructions including VS Code and Chrome DevTools se ### Build Configuration Key MSBuild properties for WebAssembly applications: - `WasmEnableThreads` - Enable multi-threading support -- `WasmEnableSIMD` - Enable SIMD instruction support +- `WasmEnableSIMD` - Enable SIMD instruction support - `RunAOTCompilation` - Enable Ahead-of-Time compilation - `WasmBuildNative` - Force native rebuild - `EnableDiagnostics` - Enable diagnostic features From f964f687c8217c17d021d5a3d5165e85ba2ddf9b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 29 Sep 2025 08:19:44 +0000 Subject: [PATCH 07/21] Remove Quick Start paragraph to focus on repo workflow documentation Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- docs/workflow/wasm-documentation.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index b400512d1e8666..c3ecf39dfe8420 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -22,11 +22,6 @@ This document serves as a comprehensive index to all WebAssembly-related documen - **Browser (browser-wasm)**: Run .NET applications in web browsers - **WASI (wasi-wasm)**: Run .NET applications in WASI-compatible environments -### Quick Start -1. Install the workload: `dotnet workload install wasm-tools` -2. Create a new project: `dotnet new wasmbrowser` or `dotnet new wasiconsole` -3. Build and run: `dotnet run` - ## Building for WebAssembly ### Core Runtime Building From 532fa5eea5040f9b73ecd862775def65f9f8db82 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 29 Sep 2025 08:47:40 +0000 Subject: [PATCH 08/21] Add JSInterop documentation link to features section Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- docs/workflow/wasm-documentation.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index c3ecf39dfe8420..c4fd5a3f320bd2 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -55,6 +55,9 @@ For consolidated debugging instructions including VS Code and Chrome DevTools se - **[WebAssembly Features](../../src/mono/wasm/features.md)** - Configure browser features, SIMD, threads, AOT, and more - **[Threading Support](../../src/mono/wasm/threads.md)** - Multi-threading support and limitations +### JavaScript Interop +- **[JSInterop in WASM](https://learn.microsoft.com/en-us/aspnet/core/client-side/dotnet-interop/wasm-browser-app)** - JavaScript interoperability for WebAssembly applications + ### Build Configuration Key MSBuild properties for WebAssembly applications: - `WasmEnableThreads` - Enable multi-threading support From 560c881b3d8e1a675a02d9d8169fa2b450ea09e8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 29 Sep 2025 15:00:51 +0000 Subject: [PATCH 09/21] Refocus documentation on contributors and add specific feature links Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- docs/workflow/wasm-documentation.md | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index c4fd5a3f320bd2..23fc0f4b322814 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -1,6 +1,6 @@ # WebAssembly (WASM) Documentation -This document serves as a comprehensive index to all WebAssembly-related documentation in the dotnet/runtime repository. Whether you're building, testing, debugging, or deploying .NET applications for WebAssembly, this guide will help you find the right resources. +This document serves as a comprehensive guide for contributors to the WebAssembly implementation in the dotnet/runtime repository. It provides links and references to technical documentation, workflows, and resources relevant to developing and maintaining WebAssembly support within this codebase. ## Table of Contents @@ -60,28 +60,17 @@ For consolidated debugging instructions including VS Code and Chrome DevTools se ### Build Configuration Key MSBuild properties for WebAssembly applications: -- `WasmEnableThreads` - Enable multi-threading support -- `WasmEnableSIMD` - Enable SIMD instruction support -- `RunAOTCompilation` - Enable Ahead-of-Time compilation +- [`WasmEnableThreads`](../../src/mono/wasm/features.md#multi-threading) - Enable multi-threading support +- [`WasmEnableSIMD`](../../src/mono/wasm/features.md#simd---single-instruction-multiple-data) - Enable SIMD instruction support +- [`RunAOTCompilation`](../../src/mono/wasm/features.md#aot) - Enable Ahead-of-Time compilation - `WasmBuildNative` - Force native rebuild - `EnableDiagnostics` - Enable diagnostic features ### Globalization and ICU - **[ICU for WebAssembly](../../design/features/globalization-icu-wasm.md)** - Globalization and ICU database configuration -## Deployment and Hosting - -### Application Structure -- **AppBundle folder**: Contains your deployed application -- **_framework folder**: Runtime and managed assemblies -- **dotnet.js**: Main entry point and JavaScript API -- **dotnet.native.wasm**: Compiled .NET runtime binary - -### Web Server Configuration -Ensure your web server is configured with proper MIME types: -- `.wasm` files: `application/wasm` -- `.js` files: `text/javascript` -- `.json` files: `application/json` +### Testing WebAssembly Changes +For testing WebAssembly implementation changes end-to-end, see the [testing documentation](../testing/mono/testing.md#testing-webassembly). ## Advanced Topics @@ -110,6 +99,10 @@ See the [WebAssembly Debugging Reference](debugging/wasm-debugging.md#common-deb See the [Building for WebAssembly](#building-for-webassembly) section above for comprehensive build instructions for different targets. +### How do I test WASM changes end to end? + +Use Wasm.Build.Tests or Wasi.Build.Tests. See the [Wasm.Build.Tests README](../../src/mono/wasm/Wasm.Build.Tests/README.md) for detailed instructions. + ### How do I enable multi-threading? See the [Threading Support](../../src/mono/wasm/threads.md) documentation for detailed multi-threading configuration and limitations. From 229deb4753fb8b7ccc0ea666f5e6e7548c27e0f5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 29 Sep 2025 15:28:12 +0000 Subject: [PATCH 10/21] Move WASM documentation link to workflow README and remove build configuration paragraph Co-authored-by: AaronRobinsonMSFT <30635565+AaronRobinsonMSFT@users.noreply.github.com> --- docs/README.md | 1 - docs/workflow/README.md | 2 ++ docs/workflow/wasm-documentation.md | 8 -------- 3 files changed, 2 insertions(+), 9 deletions(-) diff --git a/docs/README.md b/docs/README.md index 08c3c377330515..3d7f5a529ff022 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,7 +20,6 @@ Workflow (Building, testing, benchmarking, profiling, etc.) If you want to contribute a code change to this repo, start here. - [Workflow Instructions](workflow/README.md) -- [WebAssembly (WASM) Documentation](workflow/wasm-documentation.md) Design Docs ================= diff --git a/docs/workflow/README.md b/docs/workflow/README.md index 78b4fd3f19befd..6d9b31054c94f1 100644 --- a/docs/workflow/README.md +++ b/docs/workflow/README.md @@ -17,6 +17,8 @@ The runtime repo can be worked with on Windows, Linux, macOS, and FreeBSD. Each platform has its own specific requirements to work properly, and not all architectures are supported for dev work. That said, the builds can target a wider range of platforms beyond the ones mentioned earlier. You can see it as there are always two platforms at play whenever you are working with builds in the runtime repo: +For WebAssembly-specific development workflows, see [WebAssembly (WASM) Documentation](wasm-documentation.md). + - **The Build Platform:** This is the platform of the machine where you cloned the runtime repo and therefore where all your build tools are running on. The following table shows the OS and architecture combinations that we currently support, as well as links to each OS's requirements doc. If you are using WSL directly (i.e. not Docker), then follow the Linux requirements doc. | Chip | Windows | Linux | macOS | FreeBSD | diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index 23fc0f4b322814..5cff84ab5f51d2 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -58,14 +58,6 @@ For consolidated debugging instructions including VS Code and Chrome DevTools se ### JavaScript Interop - **[JSInterop in WASM](https://learn.microsoft.com/en-us/aspnet/core/client-side/dotnet-interop/wasm-browser-app)** - JavaScript interoperability for WebAssembly applications -### Build Configuration -Key MSBuild properties for WebAssembly applications: -- [`WasmEnableThreads`](../../src/mono/wasm/features.md#multi-threading) - Enable multi-threading support -- [`WasmEnableSIMD`](../../src/mono/wasm/features.md#simd---single-instruction-multiple-data) - Enable SIMD instruction support -- [`RunAOTCompilation`](../../src/mono/wasm/features.md#aot) - Enable Ahead-of-Time compilation -- `WasmBuildNative` - Force native rebuild -- `EnableDiagnostics` - Enable diagnostic features - ### Globalization and ICU - **[ICU for WebAssembly](../../design/features/globalization-icu-wasm.md)** - Globalization and ICU database configuration From 873ac670cd5c9eef9ffebdb73296352da22d212a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 29 Sep 2025 15:54:48 +0000 Subject: [PATCH 11/21] Add specific links to performance features and remove optimization FAQ Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- docs/workflow/wasm-documentation.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index 5cff84ab5f51d2..f617eb24c63a46 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -67,9 +67,9 @@ For testing WebAssembly implementation changes end-to-end, see the [testing docu ## Advanced Topics ### Performance and Optimization -- **Profiling**: Use browser dev tools profiler integration -- **AOT Compilation**: Improve runtime performance with ahead-of-time compilation -- **IL Trimming**: Reduce application size by removing unused code +- **[Profiling](../../src/mono/wasm/features.md#profiling-in-the-browser-dev-tools)**: Use browser dev tools profiler integration +- **[AOT Compilation](../../src/mono/wasm/features.md#aot)**: Improve runtime performance with ahead-of-time compilation +- **[IL Trimming](../../src/mono/wasm/features.md#trimming)**: Reduce application size by removing unused code ### Samples and Examples Located in `src/mono/sample/wasm/`: @@ -99,10 +99,6 @@ Use Wasm.Build.Tests or Wasi.Build.Tests. See the [Wasm.Build.Tests README](../. See the [Threading Support](../../src/mono/wasm/threads.md) documentation for detailed multi-threading configuration and limitations. -### How do I optimize my WebAssembly application? - -See the [WebAssembly Features](../../src/mono/wasm/features.md) documentation for AOT compilation, IL trimming, and other optimization options. - ### What JavaScript engines are supported for testing? See the [Testing Libraries on WebAssembly](testing/libraries/testing-wasm.md#prerequisites) documentation for JavaScript engine installation and usage. From eceef0ef81334086aaf14c8c04e8e057c2d6309f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 29 Sep 2025 16:22:58 +0000 Subject: [PATCH 12/21] Merge native WASM debugging documentation into main debugging guide Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- .../debugging/libraries/debugging-vscode.md | 2 +- .../debugging/mono/native-wasm-debugging.md | 344 ----------------- docs/workflow/debugging/wasm-debugging.md | 349 +++++++++++++++++- docs/workflow/wasm-documentation.md | 4 +- 4 files changed, 350 insertions(+), 349 deletions(-) delete mode 100644 docs/workflow/debugging/mono/native-wasm-debugging.md diff --git a/docs/workflow/debugging/libraries/debugging-vscode.md b/docs/workflow/debugging/libraries/debugging-vscode.md index 16da43263c889e..1ea8de9d59d9b2 100644 --- a/docs/workflow/debugging/libraries/debugging-vscode.md +++ b/docs/workflow/debugging/libraries/debugging-vscode.md @@ -24,7 +24,7 @@ ## Debugging Libraries with Visual Studio Code running on Mono To debug the libraries on a "desktop" platform (Linux/Mac/Windows, not WebAssembly, or iOS or Android) running on Mono runtime, follow the instructions below. -See also [Android debugging](../mono/android-debugging.md) and [WebAssembly debugging](../mono/native-wasm-debugging.md). +See also [Android debugging](../mono/android-debugging.md) and [WebAssembly debugging](../wasm-debugging.md). For WebAssembly-specific debugging scenarios, see the [WebAssembly Debugging Reference](../wasm-debugging.md). diff --git a/docs/workflow/debugging/mono/native-wasm-debugging.md b/docs/workflow/debugging/mono/native-wasm-debugging.md deleted file mode 100644 index 2237b33c9f16c8..00000000000000 --- a/docs/workflow/debugging/mono/native-wasm-debugging.md +++ /dev/null @@ -1,344 +0,0 @@ - -This document covers debugging the Mono WebAssembly runtime itself, native crashes, and advanced debugging scenarios. For general WebAssembly application debugging, see the [WebAssembly Debugging Reference](../wasm-debugging.md). - -# Native Runtime Debugging - -- Disable symbol stripping by setting the `WasmNativeStrip` msbuild property to `false`. See also, [collecting stack traces with symbols in Blazor](#collecting-stack-traces-with-symbols-in-blazor) - -- Emscripten generates dwarf debug info and Chrome 80 and later can use it. - -- To break in the JS debugger from runtime code, do: -``` -#include -EM_ASM(debugger;); -``` - -- To print a stack trace from runtime code, do: -``` -#ifdef HOST_WASM -#include -EM_ASM( - var err = new Error(); - console.log ("Stacktrace: \n"); - console.log (err.stack); - ); -#endif -``` -There is a mono_wasm_print_stack_trace () function that does the same: -``` -#ifdef HOST_WASM -mono_wasm_print_stack_trace (); -#endif -``` -The ifdef is needed to avoid compilation errors when compiling the cross compiler. - -- The runtime-tests.js test runner supports various options useful for debugging: - - Runtime command line options can be passed using the --runtime-arg= option. - In particular --trace can be used to enable executing tracing when using the interpreter. - - Environment variables can be set using --setenv== - In particular MONO_LOG_LEVEL/MONO_LOG_MASK can be set. - -- The --stack-trace-limit=1000 option to V8 can be used to avoid V8 truncating stack traces. - -- Emscripten supports clang's -fsanitize=address option, it can also decompile - wasm images at runtime to create readable stacktraces for C code. - -- The numbers in stack traces such as: -``` -WebAssembly.instantiate:wasm-function[8003]:0x12b564 -``` -mean wasm function index/offset inside the wasm binary. -The `wasm-objdump` tool from `https://github.com/WebAssembly/wabt` can be used to find the -corresponding wasm code: -``` -12b551 func[8003] : -``` - -- The `wasm-dis` tool from `https://github.com/WebAssembly/binaryen` can be used to -disassemble wasm executables (.wasm files). - -# Deterministic execution - -Wasm execution can be made deterministic by passing the -s DETERMINISTIC=1 option to emcc. -This will cause the app to always execute the same way, i.e. using the same memory -addresses, random numbers, etc. This can be used to make random crashes happen reliably. -Sometimes, however, turning this on will make the problem disappear. In this case, it -might be useful to add some controlled indeterminism. For example, to make the -random number generator mostly deterministic, change `$getRandomDevice` in -`upstream/emscripten/src/library.js` to: -``` - var randomBuffer2 = new Uint8Array(1); - crypto.getRandomValues(randomBuffer2); - - FS.seed2 = randomBuffer2 [0]; - console.log('SEED: ' + FS.seed2); - return function() { - FS.seed2 = FS.seed2 * 16807 % 2147483647; - return FS.seed2; - }; -``` -Then run the app until the failure occurs. Note the seed value printed at the beginning, -and change the -`FS.seed2 = randomBuffer...` line to: -`FS.seed2 = `. -This will hopefully cause the failure to happen reliably. - -There is another random number generator in `upstream/emscripten/src/deterministic.js` -which needs the same treatment. - -Running `make patch-deterministic` in `src/mono/wasm` will patch the -emscripten installation in `src/mono/browser/emsdk` with these changes. - -# Debugging signature mismatch errors - -When v8 fails with `RuntimeError: function signature mismatch`, it means a function call was -made to a function pointer with an incompatible signature, or to a NULL pointer. -This branch of v8 contains some modifications to print out the actual function pointer -value when this kind of fault happens: https://github.com/vargaz/v8/tree/sig-mismatch. -The value is an index into the function table inside the wasm executable. - -The following script can be used to print out the table: -``` -#!/usr/bin/env python3 - -# -# print-table.py: Print the function table for a webassembly .wast file -# - -import sys - -prefix=" (elem (i32.const 1) " - -if len(sys.argv) < 2: - print ("Usage: python print-table.py ") - sys.exit (1) - -f = open (sys.argv [1]) -table_line = None -for line in f: - if prefix in line: - table_line = line[len(prefix):] - break - -for (index, v) in enumerate (table_line.split (" ")): - print ("" + str(index) + ": " + v) - index += 1 -``` -The input to the script is the textual assembly created by the wasm-dis tool. - -These kinds of faults usually happen because the mono runtime has some helper functions which are -never meant to be reached, i.e. `no_gsharedvt_in_wrapper` or `no_llvmonly_interp_method_pointer`. -These functions are used as placeholders for function pointers with different signatures, so -if they do end up being called due to a bug, a signature mismatch error happens. - -# Collecting stack traces with symbols in Blazor - -When debugging a native crash in a .NET 6 Blazor app or another WebAssembly -framework that uses our default `dotnet.wasm`, the native stack frames will not -have C symbol names, but will instead look like `$func1234`. - -For example this Razor page will crash when a user clicks on the `Crash` button - -```csharp - - -@code { - private void Crash () - { - IntPtr p = (IntPtr)0x01; - Console.WriteLine ("About to crash"); - System.Runtime.InteropServices.Marshal.FreeHGlobal(p); - } -} -``` - -Clicking on the `Crash` button will produce the following output in the console (the function indices may be different): - -```console -dotnet.wasm:0x1d8355 Uncaught (in promise) RuntimeError: memory access out of bounds - at _framework/dotnet.wasm - at _framework/dotnet.wasm - at _framework/dotnet.wasm - at _framework/dotnet.wasm - at _framework/dotnet.wasm - at _framework/dotnet.wasm - at _framework/dotnet.wasm - at _framework/dotnet.wasm - at _framework/dotnet.wasm - at _framework/dotnet.wasm -$free @ dotnet.wasm:0x1d8355 -$func4027 @ dotnet.wasm:0xead6a -$func219 @ dotnet.wasm:0x1a03a -$func167 @ dotnet.wasm:0xcaf7 -$func166 @ dotnet.wasm:0xba0a -$func2810 @ dotnet.wasm:0xabacf -$func1615 @ dotnet.wasm:0x6f8eb -$func1613 @ dotnet.wasm:0x6f85d -$func966 @ dotnet.wasm:0x502dc -$func219 @ dotnet.wasm:0x1a0e2 -$func167 @ dotnet.wasm:0xcaf7 -$func166 @ dotnet.wasm:0xba0a -$func2810 @ dotnet.wasm:0xabacf -$func1615 @ dotnet.wasm:0x6f8eb -$func1619 @ dotnet.wasm:0x6ff58 -$mono_wasm_invoke_jsexport @ dotnet.wasm:0x96c9 -Module.mono_wasm_invoke_jsexport @ dotnet.6.0.1.hopd7ipo8x.js:1 -managed__Microsoft_AspNetCore_Components_WebAssembly__Microsoft_AspNetCore_Components_WebAssembly_Services_DefaultWebAssemblyJSRuntime_BeginInvokeDotNet @ managed__Microsoft_AspNetCore_Components_WebAssembly__Microsoft_AspNetCore_Components_WebAssembly_Services_DefaultWebAssemblyJSRuntime_BeginInvokeDotNet:19 -beginInvokeDotNetFromJS @ blazor.webassembly.js:1 -b @ blazor.webassembly.js:1 -invokeMethodAsync @ blazor.webassembly.js:1 -(anonymous) @ blazor.webassembly.js:1 -invokeWhenHeapUnlocked @ blazor.webassembly.js:1 -S @ blazor.webassembly.js:1 -C @ blazor.webassembly.js:1 -dispatchGlobalEventToAllElements @ blazor.webassembly.js:1 -onGlobalEvent @ blazor.webassembly.js:1 -``` - -In order to get symbols, the user should: - -1. Install the `wasm-tools` workload using `dotnet workload install wasm-tools` -2. Set these additional properties in their `.csproj` file: - - ```xml - - - true - false - - ``` - -3. Delete the `bin` and `obj` folders, re-build the project and run it again. - -Now clicking on the `Crash` button will produce a stack trace with symbols: - -```console -dotnet.wasm:0x224878 Uncaught (in promise) RuntimeError: memory access out of bounds - at dlfree (dotnet.wasm:0x224878) - at SystemNative_Free (dotnet.wasm:0x20f0e2) - at do_icall (dotnet.wasm:0x190f9) - at do_icall_wrapper (dotnet.wasm:0x18429) - at interp_exec_method (dotnet.wasm:0xa56c) - at interp_runtime_invoke (dotnet.wasm:0x943a) - at mono_jit_runtime_invoke (dotnet.wasm:0x1dec32) - at do_runtime_invoke (dotnet.wasm:0x95fca) - at mono_runtime_invoke_checked (dotnet.wasm:0x95f57) - at mono_runtime_try_invoke_array (dotnet.wasm:0x9a87e) -$dlfree @ dotnet.wasm:0x224878 -$SystemNative_Free @ dotnet.wasm:0x20f0e2 -$do_icall @ dotnet.wasm:0x190f9 -$do_icall_wrapper @ dotnet.wasm:0x18429 -$interp_exec_method @ dotnet.wasm:0xa56c -$interp_runtime_invoke @ dotnet.wasm:0x943a -$mono_jit_runtime_invoke @ dotnet.wasm:0x1dec32 -$do_runtime_invoke @ dotnet.wasm:0x95fca -$mono_runtime_invoke_checked @ dotnet.wasm:0x95f57 -$mono_runtime_try_invoke_array @ dotnet.wasm:0x9a87e -$mono_runtime_invoke_array_checked @ dotnet.wasm:0x9af17 -$ves_icall_InternalInvoke @ dotnet.wasm:0x702ed -$ves_icall_InternalInvoke_raw @ dotnet.wasm:0x7777f -$do_icall @ dotnet.wasm:0x191c5 -$do_icall_wrapper @ dotnet.wasm:0x18429 -$interp_exec_method @ dotnet.wasm:0xa56c -$interp_runtime_invoke @ dotnet.wasm:0x943a -$mono_jit_runtime_invoke @ dotnet.wasm:0x1dec32 -$do_runtime_invoke @ dotnet.wasm:0x95fca -$mono_runtime_try_invoke @ dotnet.wasm:0x966fe -$mono_runtime_invoke @ dotnet.wasm:0x98982 -$mono_wasm_invoke_jsexport @ dotnet.wasm:0x227de2 -Module.mono_wasm_invoke_jsexport @ dotnet..y6ggkhlo8e.js:9927 -managed__Microsoft_AspNetCore_Components_WebAssembly__Microsoft_AspNetCore_Components_WebAssembly_Services_DefaultWebAssemblyJSRuntime_BeginInvokeDotNet @ managed__Microsoft_AspNetCore_Components_WebAssembly__Microsoft_AspNetCore_Components_WebAssembly_Services_DefaultWebAssemblyJSRuntime_BeginInvokeDotNet:19 -beginInvokeDotNetFromJS @ blazor.webassembly.js:1 -b @ blazor.webassembly.js:1 -invokeMethodAsync @ blazor.webassembly.js:1 -(anonymous) @ blazor.webassembly.js:1 -invokeWhenHeapUnlocked @ blazor.webassembly.js:1 -S @ blazor.webassembly.js:1 -C @ blazor.webassembly.js:1 -dispatchGlobalEventToAllElements @ blazor.webassembly.js:1 -onGlobalEvent @ blazor.webassembly.js:1 -``` - -# Enabling additional logging in Blazor - -In .NET 8+, Blazor startup can be controlled by setting the `autostart="false"` attribute on the -` - -``` - -Replace it with this: - -```html - -
- ... -
- -
- ... -
- - - -``` - -## Blazor - -In a `blazor` project, the script is `_framework/blazor.web.js` and it is loaded by `Components/App.razor` in the server-side project: - -```html - - - - -``` - -Replace it with this (note that for a `blazor` project, `Blazor.start` needs an extra dictionary with a `webAssembly` key): - -```html - - - - - -``` diff --git a/docs/workflow/debugging/wasm-debugging.md b/docs/workflow/debugging/wasm-debugging.md index 69d8e15372b766..acf54f2497634d 100644 --- a/docs/workflow/debugging/wasm-debugging.md +++ b/docs/workflow/debugging/wasm-debugging.md @@ -163,12 +163,357 @@ For native crashes with symbols: ### Collect Stack Traces -For detailed instructions on collecting stack traces and breaking into the JavaScript debugger from runtime code, see the [Native WASM Runtime Debugging](mono/native-wasm-debugging.md) documentation. +For detailed instructions on collecting stack traces and breaking into the JavaScript debugger from runtime code, see the [Native Runtime Debugging](#native-runtime-debugging) section below. + +## Native Runtime Debugging + +This section covers debugging the Mono WebAssembly runtime itself, native crashes, and advanced debugging scenarios. + +### Runtime Debugging Techniques + +- Disable symbol stripping by setting the `WasmNativeStrip` msbuild property to `false`. See also, [collecting stack traces with symbols in Blazor](#collecting-stack-traces-with-symbols-in-blazor) + +- Emscripten generates dwarf debug info and Chrome 80 and later can use it. + +- To break in the JS debugger from runtime code, do: +``` +#include +EM_ASM(debugger;); +``` + +- To print a stack trace from runtime code, do: +``` +#ifdef HOST_WASM +#include +EM_ASM( + var err = new Error(); + console.log ("Stacktrace: \n"); + console.log (err.stack); + ); +#endif +``` +There is a mono_wasm_print_stack_trace () function that does the same: +``` +#ifdef HOST_WASM +mono_wasm_print_stack_trace (); +#endif +``` +The ifdef is needed to avoid compilation errors when compiling the cross compiler. + +- The runtime-tests.js test runner supports various options useful for debugging: + - Runtime command line options can be passed using the --runtime-arg= option. + In particular --trace can be used to enable executing tracing when using the interpreter. + - Environment variables can be set using --setenv== + In particular MONO_LOG_LEVEL/MONO_LOG_MASK can be set. + +- The --stack-trace-limit=1000 option to V8 can be used to avoid V8 truncating stack traces. + +- Emscripten supports clang's -fsanitize=address option, it can also decompile + wasm images at runtime to create readable stacktraces for C code. + +- The numbers in stack traces such as: +``` +WebAssembly.instantiate:wasm-function[8003]:0x12b564 +``` +mean wasm function index/offset inside the wasm binary. +The `wasm-objdump` tool from `https://github.com/WebAssembly/wabt` can be used to find the +corresponding wasm code: +``` +12b551 func[8003] : +``` + +- The `wasm-dis` tool from `https://github.com/WebAssembly/binaryen` can be used to +disassemble wasm executables (.wasm files). + +### Deterministic Execution + +Wasm execution can be made deterministic by passing the -s DETERMINISTIC=1 option to emcc. +This will cause the app to always execute the same way, i.e. using the same memory +addresses, random numbers, etc. This can be used to make random crashes happen reliably. +Sometimes, however, turning this on will make the problem disappear. In this case, it +might be useful to add some controlled indeterminism. For example, to make the +random number generator mostly deterministic, change `$getRandomDevice` in +`upstream/emscripten/src/library.js` to: +``` + var randomBuffer2 = new Uint8Array(1); + crypto.getRandomValues(randomBuffer2); + + FS.seed2 = randomBuffer2 [0]; + console.log('SEED: ' + FS.seed2); + return function() { + FS.seed2 = FS.seed2 * 16807 % 2147483647; + return FS.seed2; + }; +``` +Then run the app until the failure occurs. Note the seed value printed at the beginning, +and change the +`FS.seed2 = randomBuffer...` line to: +`FS.seed2 = `. +This will hopefully cause the failure to happen reliably. + +There is another random number generator in `upstream/emscripten/src/deterministic.js` +which needs the same treatment. + +Running `make patch-deterministic` in `src/mono/wasm` will patch the +emscripten installation in `src/mono/browser/emsdk` with these changes. + +### Debugging Signature Mismatch Errors + +When v8 fails with `RuntimeError: function signature mismatch`, it means a function call was +made to a function pointer with an incompatible signature, or to a NULL pointer. +This branch of v8 contains some modifications to print out the actual function pointer +value when this kind of fault happens: https://github.com/vargaz/v8/tree/sig-mismatch. +The value is an index into the function table inside the wasm executable. + +The following script can be used to print out the table: +``` +#!/usr/bin/env python3 + +# +# print-table.py: Print the function table for a webassembly .wast file +# + +import sys + +prefix=" (elem (i32.const 1) " + +if len(sys.argv) < 2: + print ("Usage: python print-table.py ") + sys.exit (1) + +f = open (sys.argv [1]) +table_line = None +for line in f: + if prefix in line: + table_line = line[len(prefix):] + break + +for (index, v) in enumerate (table_line.split (" ")): + print ("" + str(index) + ": " + v) + index += 1 +``` +The input to the script is the textual assembly created by the wasm-dis tool. + +These kinds of faults usually happen because the mono runtime has some helper functions which are +never meant to be reached, i.e. `no_gsharedvt_in_wrapper` or `no_llvmonly_interp_method_pointer`. +These functions are used as placeholders for function pointers with different signatures, so +if they do end up being called due to a bug, a signature mismatch error happens. + +### Collecting Stack Traces with Symbols in Blazor + +When debugging a native crash in a .NET 6 Blazor app or another WebAssembly +framework that uses our default `dotnet.wasm`, the native stack frames will not +have C symbol names, but will instead look like `$func1234`. + +For example this Razor page will crash when a user clicks on the `Crash` button + +```csharp + + +@code { + private void Crash () + { + IntPtr p = (IntPtr)0x01; + Console.WriteLine ("About to crash"); + System.Runtime.InteropServices.Marshal.FreeHGlobal(p); + } +} +``` + +Clicking on the `Crash` button will produce the following output in the console (the function indices may be different): + +```console +dotnet.wasm:0x1d8355 Uncaught (in promise) RuntimeError: memory access out of bounds + at _framework/dotnet.wasm + at _framework/dotnet.wasm + at _framework/dotnet.wasm + at _framework/dotnet.wasm + at _framework/dotnet.wasm + at _framework/dotnet.wasm + at _framework/dotnet.wasm + at _framework/dotnet.wasm + at _framework/dotnet.wasm + at _framework/dotnet.wasm +$free @ dotnet.wasm:0x1d8355 +$func4027 @ dotnet.wasm:0xead6a +$func219 @ dotnet.wasm:0x1a03a +$func167 @ dotnet.wasm:0xcaf7 +$func166 @ dotnet.wasm:0xba0a +$func2810 @ dotnet.wasm:0xabacf +$func1615 @ dotnet.wasm:0x6f8eb +$func1613 @ dotnet.wasm:0x6f85d +$func966 @ dotnet.wasm:0x502dc +$func219 @ dotnet.wasm:0x1a0e2 +$func167 @ dotnet.wasm:0xcaf7 +$func166 @ dotnet.wasm:0xba0a +$func2810 @ dotnet.wasm:0xabacf +$func1615 @ dotnet.wasm:0x6f8eb +$func1619 @ dotnet.wasm:0x6ff58 +$mono_wasm_invoke_jsexport @ dotnet.wasm:0x96c9 +Module.mono_wasm_invoke_jsexport @ dotnet.6.0.1.hopd7ipo8x.js:1 +managed__Microsoft_AspNetCore_Components_WebAssembly__Microsoft_AspNetCore_Components_WebAssembly_Services_DefaultWebAssemblyJSRuntime_BeginInvokeDotNet @ managed__Microsoft_AspNetCore_Components_WebAssembly__Microsoft_AspNetCore_Components_WebAssembly_Services_DefaultWebAssemblyJSRuntime_BeginInvokeDotNet:19 +beginInvokeDotNetFromJS @ blazor.webassembly.js:1 +b @ blazor.webassembly.js:1 +invokeMethodAsync @ blazor.webassembly.js:1 +(anonymous) @ blazor.webassembly.js:1 +invokeWhenHeapUnlocked @ blazor.webassembly.js:1 +S @ blazor.webassembly.js:1 +C @ blazor.webassembly.js:1 +dispatchGlobalEventToAllElements @ blazor.webassembly.js:1 +onGlobalEvent @ blazor.webassembly.js:1 +``` + +In order to get symbols, the user should: + +1. Install the `wasm-tools` workload using `dotnet workload install wasm-tools` +2. Set these additional properties in their `.csproj` file: + + ```xml + + + true + false + + ``` + +3. Delete the `bin` and `obj` folders, re-build the project and run it again. + +Now clicking on the `Crash` button will produce a stack trace with symbols: + +```console +dotnet.wasm:0x224878 Uncaught (in promise) RuntimeError: memory access out of bounds + at dlfree (dotnet.wasm:0x224878) + at SystemNative_Free (dotnet.wasm:0x20f0e2) + at do_icall (dotnet.wasm:0x190f9) + at do_icall_wrapper (dotnet.wasm:0x18429) + at interp_exec_method (dotnet.wasm:0xa56c) + at interp_runtime_invoke (dotnet.wasm:0x943a) + at mono_jit_runtime_invoke (dotnet.wasm:0x1dec32) + at do_runtime_invoke (dotnet.wasm:0x95fca) + at mono_runtime_invoke_checked (dotnet.wasm:0x95f57) + at mono_runtime_try_invoke_array (dotnet.wasm:0x9a87e) +$dlfree @ dotnet.wasm:0x224878 +$SystemNative_Free @ dotnet.wasm:0x20f0e2 +$do_icall @ dotnet.wasm:0x190f9 +$do_icall_wrapper @ dotnet.wasm:0x18429 +$interp_exec_method @ dotnet.wasm:0xa56c +$interp_runtime_invoke @ dotnet.wasm:0x943a +$mono_jit_runtime_invoke @ dotnet.wasm:0x1dec32 +$do_runtime_invoke @ dotnet.wasm:0x95fca +$mono_runtime_invoke_checked @ dotnet.wasm:0x95f57 +$mono_runtime_try_invoke_array @ dotnet.wasm:0x9a87e +$mono_runtime_invoke_array_checked @ dotnet.wasm:0x9af17 +$ves_icall_InternalInvoke @ dotnet.wasm:0x702ed +$ves_icall_InternalInvoke_raw @ dotnet.wasm:0x7777f +$do_icall @ dotnet.wasm:0x191c5 +$do_icall_wrapper @ dotnet.wasm:0x18429 +$interp_exec_method @ dotnet.wasm:0xa56c +$interp_runtime_invoke @ dotnet.wasm:0x943a +$mono_jit_runtime_invoke @ dotnet.wasm:0x1dec32 +$do_runtime_invoke @ dotnet.wasm:0x95fca +$mono_runtime_try_invoke @ dotnet.wasm:0x966fe +$mono_runtime_invoke @ dotnet.wasm:0x98982 +$mono_wasm_invoke_jsexport @ dotnet.wasm:0x227de2 +Module.mono_wasm_invoke_jsexport @ dotnet..y6ggkhlo8e.js:9927 +managed__Microsoft_AspNetCore_Components_WebAssembly__Microsoft_AspNetCore_Components_WebAssembly_Services_DefaultWebAssemblyJSRuntime_BeginInvokeDotNet @ managed__Microsoft_AspNetCore_Components_WebAssembly__Microsoft_AspNetCore_Components_WebAssembly_Services_DefaultWebAssemblyJSRuntime_BeginInvokeDotNet:19 +beginInvokeDotNetFromJS @ blazor.webassembly.js:1 +b @ blazor.webassembly.js:1 +invokeMethodAsync @ blazor.webassembly.js:1 +(anonymous) @ blazor.webassembly.js:1 +invokeWhenHeapUnlocked @ blazor.webassembly.js:1 +S @ blazor.webassembly.js:1 +C @ blazor.webassembly.js:1 +dispatchGlobalEventToAllElements @ blazor.webassembly.js:1 +onGlobalEvent @ blazor.webassembly.js:1 +``` + +### Enabling Additional Logging in Blazor + +In .NET 8+, Blazor startup can be controlled by setting the `autostart="false"` attribute on the +` + +``` + +Replace it with this: + +```html + +
+ ... +
+ +
+ ... +
+ + + +``` + +#### Blazor + +In a `blazor` project, the script is `_framework/blazor.web.js` and it is loaded by `Components/App.razor` in the server-side project: + +```html + + + + +``` + +Replace it with this (note that for a `blazor` project, `Blazor.start` needs an extra dictionary with a `webAssembly` key): + +```html + + + + + +``` ## References - [Testing Libraries on WebAssembly](../testing/libraries/testing-wasm.md) - [Debugging WebAssembly Libraries](../testing/libraries/debugging-wasm.md) -- [WASM Runtime Debugging](debugging/mono/wasm-debugging.md) - [WASI Support](../../src/mono/wasi/README.md) - [VS Code Debugging Guide](debugging/libraries/debugging-vscode.md) \ No newline at end of file diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index f617eb24c63a46..f50d14f339c8e3 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -42,7 +42,7 @@ This document serves as a comprehensive guide for contributors to the WebAssembl - **[Debugging WebAssembly Libraries](testing/libraries/debugging-wasm.md)** - Debug library tests in Chrome DevTools and VS Code ### Runtime Debugging -- **[Native WASM Runtime Debugging](debugging/mono/native-wasm-debugging.md)** - Debug the Mono runtime, native crashes, and collect stack traces +- **[WebAssembly Debugging](debugging/wasm-debugging.md)** - Consolidated debugging reference for WebAssembly applications and native runtime debugging - **[VS Code Debugging](debugging/libraries/debugging-vscode.md)** - Set up VS Code for debugging WASM applications ### Common Debugging Scenarios @@ -105,7 +105,7 @@ See the [Testing Libraries on WebAssembly](testing/libraries/testing-wasm.md#pre ### How do I collect native stack traces with symbols? -See the [Native WASM Runtime Debugging](debugging/mono/native-wasm-debugging.md#collecting-stack-traces-with-symbols-in-blazor) documentation for symbol configuration. +See the [WebAssembly Debugging](debugging/wasm-debugging.md#collecting-stack-traces-with-symbols-in-blazor) documentation for symbol configuration. ### How do I run tests with different configurations? From 99c0bdf9950692297cd9be7aa18808268cba6012 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 30 Sep 2025 07:01:34 +0000 Subject: [PATCH 13/21] Move wasm-debugging.md back to mono folder and merge library debugging content Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- .../debugging/libraries/debugging-vscode.md | 4 +-- .../debugging/{ => mono}/wasm-debugging.md | 26 +++++++++++++++ .../testing/libraries/debugging-wasm.md | 33 ------------------- docs/workflow/wasm-documentation.md | 8 ++--- src/mono/wasi/README.md | 2 +- 5 files changed, 33 insertions(+), 40 deletions(-) rename docs/workflow/debugging/{ => mono}/wasm-debugging.md (91%) delete mode 100644 docs/workflow/testing/libraries/debugging-wasm.md diff --git a/docs/workflow/debugging/libraries/debugging-vscode.md b/docs/workflow/debugging/libraries/debugging-vscode.md index 1ea8de9d59d9b2..6063ffc493c657 100644 --- a/docs/workflow/debugging/libraries/debugging-vscode.md +++ b/docs/workflow/debugging/libraries/debugging-vscode.md @@ -24,9 +24,9 @@ ## Debugging Libraries with Visual Studio Code running on Mono To debug the libraries on a "desktop" platform (Linux/Mac/Windows, not WebAssembly, or iOS or Android) running on Mono runtime, follow the instructions below. -See also [Android debugging](../mono/android-debugging.md) and [WebAssembly debugging](../wasm-debugging.md). +See also [Android debugging](../mono/android-debugging.md) and [WebAssembly debugging](../mono/wasm-debugging.md). -For WebAssembly-specific debugging scenarios, see the [WebAssembly Debugging Reference](../wasm-debugging.md). +For WebAssembly-specific debugging scenarios, see the [WebAssembly Debugging Reference](../mono/wasm-debugging.md). - Install the VS Code [Mono Debugger (`ms-vscode.mono-debug`)](https://marketplace.visualstudio.com/items?itemName=ms-vscode.mono-debug) extension - Create a `launch.json` file configuration with type `mono` diff --git a/docs/workflow/debugging/wasm-debugging.md b/docs/workflow/debugging/mono/wasm-debugging.md similarity index 91% rename from docs/workflow/debugging/wasm-debugging.md rename to docs/workflow/debugging/mono/wasm-debugging.md index acf54f2497634d..3e58706f590e28 100644 --- a/docs/workflow/debugging/wasm-debugging.md +++ b/docs/workflow/debugging/mono/wasm-debugging.md @@ -2,6 +2,32 @@ This document provides consolidated debugging instructions for WebAssembly applications. +## Debugging Library Tests + +For building libraries or testing them without debugging, read: +- [Building libraries](https://github.com/dotnet/runtime/blob/main/docs/workflow/building/libraries/README.md), +- [Testing libraries](https://github.com/dotnet/runtime/blob/main/docs/workflow/testing/libraries/testing.md). + +### Run the tests with debugger support + +Run the selected library tests in the browser, e.g. `System.Collections.Concurrent.Tests` this way: +``` +dotnet run -r browser-wasm -c Debug --project src/libraries/System.Collections/tests/System.Collections.Tests.csproj --debug --host browser -p:DebuggerSupport=true +``` +where we choose `browser-wasm` as the runtime and by setting `DebuggerSupport=true` we ensure that tests won't start execution before the debugger will get attached. In the output, among others you should see: + +``` +Debug proxy for chrome now listening on http://127.0.0.1:58346/. And expecting chrome at http://localhost:9222/ +App url: http://127.0.0.1:9000/index.html?arg=--debug&arg=--run&arg=WasmTestRunner.dll&arg=System.Collections.Concurrent.Tests.dll +``` +The proxy's url/port will be used in the next step. + +You may need to close all Chrome instances. Then, start the browser with debugging mode enabled: + +`chrome --remote-debugging-port=9222 ` + +Now you can choose an IDE to start debugging. Remember that the tests wait only till the debugger gets attached. Once it does, they start running. You may want to set breakpoints first, before attaching the debugger, e.g. setting one in `src\libraries\Common\tests\WasmTestRunner\WasmTestRunner.cs` on the first line of `Main()` will prevent any test to be run before you get prepared. + ## Debug with VS Code To debug WebAssembly applications with Visual Studio Code: diff --git a/docs/workflow/testing/libraries/debugging-wasm.md b/docs/workflow/testing/libraries/debugging-wasm.md deleted file mode 100644 index da60f816152d07..00000000000000 --- a/docs/workflow/testing/libraries/debugging-wasm.md +++ /dev/null @@ -1,33 +0,0 @@ -# Debugging libraries - -For building libraries or testing them without debugging, read: -- [Building libraries](https://github.com/dotnet/runtime/blob/main/docs/workflow/building/libraries/README.md), -- [Testing libraries](https://github.com/dotnet/runtime/blob/main/docs/workflow/testing/libraries/testing.md). - -## Run the tests with debugger support - -Run the selected library tests in the browser, e.g. `System.Collections.Concurrent.Tests` this way: -``` -dotnet run -r browser-wasm -c Debug --project src/libraries/System.Collections/tests/System.Collections.Tests.csproj --debug --host browser -p:DebuggerSupport=true -``` -where we choose `browser-wasm` as the runtime and by setting `DebuggerSupport=true` we ensure that tests won't start execution before the debugger will get attached. In the output, among others you should see: - -``` -Debug proxy for chrome now listening on http://127.0.0.1:58346/. And expecting chrome at http://localhost:9222/ -App url: http://127.0.0.1:9000/index.html?arg=--debug&arg=--run&arg=WasmTestRunner.dll&arg=System.Collections.Concurrent.Tests.dll -``` -The proxy's url/port will be used in the next step. - -You may need to close all Chrome instances. Then, start the browser with debugging mode enabled: - -`chrome --remote-debugging-port=9222 ` - -Now you can choose an IDE to start debugging. Remember that the tests wait only till the debugger gets attached. Once it does, they start running. You may want to set breakpoints first, before attaching the debugger, e.g. setting one in `src\libraries\Common\tests\WasmTestRunner\WasmTestRunner.cs` on the first line of `Main()` will prevent any test to be run before you get prepared. - -## Debug with Chrome DevTools - -For detailed Chrome DevTools debugging instructions, see the [WebAssembly Debugging Reference](../debugging/wasm-debugging.md#debug-with-chrome-devtools). - -## Debug with VS Code - -For detailed VS Code debugging instructions, see the [WebAssembly Debugging Reference](../debugging/wasm-debugging.md#debug-with-vs-code). diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index f50d14f339c8e3..1421315f703b63 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -42,12 +42,12 @@ This document serves as a comprehensive guide for contributors to the WebAssembl - **[Debugging WebAssembly Libraries](testing/libraries/debugging-wasm.md)** - Debug library tests in Chrome DevTools and VS Code ### Runtime Debugging -- **[WebAssembly Debugging](debugging/wasm-debugging.md)** - Consolidated debugging reference for WebAssembly applications and native runtime debugging +- **[WebAssembly Debugging](debugging/mono/wasm-debugging.md)** - Consolidated debugging reference for WebAssembly applications and native runtime debugging - **[VS Code Debugging](debugging/libraries/debugging-vscode.md)** - Set up VS Code for debugging WASM applications ### Common Debugging Scenarios -For consolidated debugging instructions including VS Code and Chrome DevTools setup, see the [WebAssembly Debugging Reference](debugging/wasm-debugging.md). +For consolidated debugging instructions including VS Code and Chrome DevTools setup, see the [WebAssembly Debugging Reference](debugging/mono/wasm-debugging.md). ## Features and Configuration @@ -85,7 +85,7 @@ Located in `src/mono/sample/wasm/`: ### How do I debug a library test failure seen on CI? -See the [WebAssembly Debugging Reference](debugging/wasm-debugging.md#common-debugging-workflow) for detailed instructions on debugging library tests locally. +See the [WebAssembly Debugging Reference](debugging/mono/wasm-debugging.md#common-debugging-workflow) for detailed instructions on debugging library tests locally. ### How do I build for different WebAssembly targets? @@ -105,7 +105,7 @@ See the [Testing Libraries on WebAssembly](testing/libraries/testing-wasm.md#pre ### How do I collect native stack traces with symbols? -See the [WebAssembly Debugging](debugging/wasm-debugging.md#collecting-stack-traces-with-symbols-in-blazor) documentation for symbol configuration. +See the [WebAssembly Debugging](debugging/mono/wasm-debugging.md#collecting-stack-traces-with-symbols-in-blazor) documentation for symbol configuration. ### How do I run tests with different configurations? diff --git a/src/mono/wasi/README.md b/src/mono/wasi/README.md index 1456056420c265..9ed6eb688e0e90 100644 --- a/src/mono/wasi/README.md +++ b/src/mono/wasi/README.md @@ -114,4 +114,4 @@ Finally, you can build and run the sample: ### 4. Debug it -For detailed WASI debugging instructions, see the [WebAssembly Debugging Reference](../../../docs/workflow/debugging/wasm-debugging.md#for-wasi-applications). +For detailed WASI debugging instructions, see the [WebAssembly Debugging Reference](../../../docs/workflow/debugging/mono/wasm-debugging.md#for-wasi-applications). From 27cbe6af4e669ecebd436904385ee2148f345604 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 30 Sep 2025 07:25:21 +0000 Subject: [PATCH 14/21] Replace specific build commands with links to general workflow documentation Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- docs/workflow/wasm-documentation.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index 1421315f703b63..6828d3a12f6ec8 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -122,10 +122,9 @@ See the [WebAssembly Debugging](debugging/mono/wasm-debugging.md#collecting-stac - Install VS Code ESLint plugin for real-time checking ### Building Changes -When making changes that affect native code or build configuration: -1. Clean build artifacts: `git clean -xfd` -2. Rebuild: `./build.sh -os browser -subset mono+libs` -3. Test your changes with relevant test suites +When making changes that affect native code or build configuration, see [Building the Repo](https://github.com/dotnet/runtime/tree/main/docs/workflow#building-the-repo) for detailed instructions. + +Then test your changes with [Testing the Repo](https://github.com/dotnet/runtime/tree/main/docs/workflow#testing-the-repo) using the relevant test suites. ### Documentation Updates When updating WebAssembly documentation: From c96008333746e6869e7e839a95c87b4768f1d347 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 30 Sep 2025 07:52:36 +0000 Subject: [PATCH 15/21] Consolidate library debugging sections and improve workflow documentation structure Co-authored-by: ilonatommy <32700855+ilonatommy@users.noreply.github.com> --- .../workflow/debugging/mono/wasm-debugging.md | 64 ++++++++----------- 1 file changed, 27 insertions(+), 37 deletions(-) diff --git a/docs/workflow/debugging/mono/wasm-debugging.md b/docs/workflow/debugging/mono/wasm-debugging.md index 3e58706f590e28..486126c9f0240b 100644 --- a/docs/workflow/debugging/mono/wasm-debugging.md +++ b/docs/workflow/debugging/mono/wasm-debugging.md @@ -2,32 +2,6 @@ This document provides consolidated debugging instructions for WebAssembly applications. -## Debugging Library Tests - -For building libraries or testing them without debugging, read: -- [Building libraries](https://github.com/dotnet/runtime/blob/main/docs/workflow/building/libraries/README.md), -- [Testing libraries](https://github.com/dotnet/runtime/blob/main/docs/workflow/testing/libraries/testing.md). - -### Run the tests with debugger support - -Run the selected library tests in the browser, e.g. `System.Collections.Concurrent.Tests` this way: -``` -dotnet run -r browser-wasm -c Debug --project src/libraries/System.Collections/tests/System.Collections.Tests.csproj --debug --host browser -p:DebuggerSupport=true -``` -where we choose `browser-wasm` as the runtime and by setting `DebuggerSupport=true` we ensure that tests won't start execution before the debugger will get attached. In the output, among others you should see: - -``` -Debug proxy for chrome now listening on http://127.0.0.1:58346/. And expecting chrome at http://localhost:9222/ -App url: http://127.0.0.1:9000/index.html?arg=--debug&arg=--run&arg=WasmTestRunner.dll&arg=System.Collections.Concurrent.Tests.dll -``` -The proxy's url/port will be used in the next step. - -You may need to close all Chrome instances. Then, start the browser with debugging mode enabled: - -`chrome --remote-debugging-port=9222 ` - -Now you can choose an IDE to start debugging. Remember that the tests wait only till the debugger gets attached. Once it does, they start running. You may want to set breakpoints first, before attaching the debugger, e.g. setting one in `src\libraries\Common\tests\WasmTestRunner\WasmTestRunner.cs` on the first line of `Main()` will prevent any test to be run before you get prepared. - ## Debug with VS Code To debug WebAssembly applications with Visual Studio Code: @@ -112,19 +86,35 @@ Replace `` with the URL shown in your application's output. ### For Library Tests -1. **Run test with debugging**: - ```bash - dotnet run -r browser-wasm -c Debug --project src/libraries/System.Collections/tests/System.Collections.Tests.csproj --debug --host browser -p:DebuggerSupport=true - ``` +For building libraries or testing them without debugging, read: +- [Building libraries](https://github.com/dotnet/runtime/blob/main/docs/workflow/building/libraries/README.md) +- [Testing libraries](https://github.com/dotnet/runtime/blob/main/docs/workflow/testing/libraries/testing.md) -2. **Note the output**: Look for lines like: - ``` - Debug proxy for chrome now listening on http://127.0.0.1:58346/ - App url: http://127.0.0.1:9000/index.html?arg=--debug&arg=--run&arg=WasmTestRunner.dll - ``` +**Run the selected library tests with debugger support:** + +Run the selected library tests in the browser, e.g. `System.Collections.Concurrent.Tests` this way: +```bash +dotnet run -r browser-wasm -c Debug --project src/libraries/System.Collections/tests/System.Collections.Tests.csproj --debug --host browser -p:DebuggerSupport=true +``` + +Where we choose `browser-wasm` as the runtime and by setting `DebuggerSupport=true` we ensure that tests won't start execution before the debugger will get attached. In the output, among others you should see: + +``` +Debug proxy for chrome now listening on http://127.0.0.1:58346/. And expecting chrome at http://localhost:9222/ +App url: http://127.0.0.1:9000/index.html?arg=--debug&arg=--run&arg=WasmTestRunner.dll&arg=System.Collections.Concurrent.Tests.dll +``` + +The proxy's url/port will be used in the next step. + +You may need to close all Chrome instances. Then, start the browser with debugging mode enabled: + +```bash +chrome --remote-debugging-port=9222 +``` + +Now you can choose an IDE to start debugging. Remember that the tests wait only till the debugger gets attached. Once it does, they start running. You may want to set breakpoints first, before attaching the debugger, e.g. setting one in `src\libraries\Common\tests\WasmTestRunner\WasmTestRunner.cs` on the first line of `Main()` will prevent any test to be run before you get prepared. -3. **Start Chrome**: Use the app URL with remote debugging enabled -4. **Attach debugger**: Use either Chrome DevTools or VS Code as described above +Use either Chrome DevTools or VS Code as described above to attach the debugger ### For WASI Applications From 3e7360c9cbd1fff2801499d259df37d0929a1c4c Mon Sep 17 00:00:00 2001 From: Ilona Tomkowicz <32700855+ilonatommy@users.noreply.github.com> Date: Wed, 1 Oct 2025 15:55:07 +0200 Subject: [PATCH 16/21] Apply suggestions from code review Co-authored-by: Jan Kotas --- docs/workflow/debugging/libraries/debugging-vscode.md | 2 -- docs/workflow/debugging/mono/wasm-debugging.md | 4 ++-- docs/workflow/wasm-documentation.md | 2 +- 3 files changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/workflow/debugging/libraries/debugging-vscode.md b/docs/workflow/debugging/libraries/debugging-vscode.md index 6063ffc493c657..d6e21d35429c62 100644 --- a/docs/workflow/debugging/libraries/debugging-vscode.md +++ b/docs/workflow/debugging/libraries/debugging-vscode.md @@ -26,8 +26,6 @@ To debug the libraries on a "desktop" platform (Linux/Mac/Windows, not WebAssembly, or iOS or Android) running on Mono runtime, follow the instructions below. See also [Android debugging](../mono/android-debugging.md) and [WebAssembly debugging](../mono/wasm-debugging.md). -For WebAssembly-specific debugging scenarios, see the [WebAssembly Debugging Reference](../mono/wasm-debugging.md). - - Install the VS Code [Mono Debugger (`ms-vscode.mono-debug`)](https://marketplace.visualstudio.com/items?itemName=ms-vscode.mono-debug) extension - Create a `launch.json` file configuration with type `mono` diff --git a/docs/workflow/debugging/mono/wasm-debugging.md b/docs/workflow/debugging/mono/wasm-debugging.md index 486126c9f0240b..680e7f20ee7346 100644 --- a/docs/workflow/debugging/mono/wasm-debugging.md +++ b/docs/workflow/debugging/mono/wasm-debugging.md @@ -1,10 +1,10 @@ # WebAssembly Debugging Reference -This document provides consolidated debugging instructions for WebAssembly applications. +This document provides debugging instructions for WebAssembly. ## Debug with VS Code -To debug WebAssembly applications with Visual Studio Code: +To debug WebAssembly with Visual Studio Code: ### 1. Configuration diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index 6828d3a12f6ec8..02d9a1cacb2377 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -47,7 +47,7 @@ This document serves as a comprehensive guide for contributors to the WebAssembl ### Common Debugging Scenarios -For consolidated debugging instructions including VS Code and Chrome DevTools setup, see the [WebAssembly Debugging Reference](debugging/mono/wasm-debugging.md). +For debugging instructions including VS Code and Chrome DevTools setup, see the [WebAssembly Debugging Reference](debugging/mono/wasm-debugging.md). ## Features and Configuration From adf8807c5352d1423f7a5208c314a022889055f6 Mon Sep 17 00:00:00 2001 From: Ilona Tomkowicz <32700855+ilonatommy@users.noreply.github.com> Date: Thu, 2 Oct 2025 07:44:19 +0000 Subject: [PATCH 17/21] WASM -> Wasm --- docs/workflow/README.md | 2 +- docs/workflow/wasm-documentation.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/workflow/README.md b/docs/workflow/README.md index 6d9b31054c94f1..881e578790c3af 100644 --- a/docs/workflow/README.md +++ b/docs/workflow/README.md @@ -17,7 +17,7 @@ The runtime repo can be worked with on Windows, Linux, macOS, and FreeBSD. Each platform has its own specific requirements to work properly, and not all architectures are supported for dev work. That said, the builds can target a wider range of platforms beyond the ones mentioned earlier. You can see it as there are always two platforms at play whenever you are working with builds in the runtime repo: -For WebAssembly-specific development workflows, see [WebAssembly (WASM) Documentation](wasm-documentation.md). +For WebAssembly-specific development workflows, see [WebAssembly Documentation](wasm-documentation.md). - **The Build Platform:** This is the platform of the machine where you cloned the runtime repo and therefore where all your build tools are running on. The following table shows the OS and architecture combinations that we currently support, as well as links to each OS's requirements doc. If you are using WSL directly (i.e. not Docker), then follow the Linux requirements doc. diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index 02d9a1cacb2377..903cf8ccc8c3ab 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -1,4 +1,4 @@ -# WebAssembly (WASM) Documentation +# WebAssembly Documentation This document serves as a comprehensive guide for contributors to the WebAssembly implementation in the dotnet/runtime repository. It provides links and references to technical documentation, workflows, and resources relevant to developing and maintaining WebAssembly support within this codebase. @@ -56,7 +56,7 @@ For debugging instructions including VS Code and Chrome DevTools setup, see the - **[Threading Support](../../src/mono/wasm/threads.md)** - Multi-threading support and limitations ### JavaScript Interop -- **[JSInterop in WASM](https://learn.microsoft.com/en-us/aspnet/core/client-side/dotnet-interop/wasm-browser-app)** - JavaScript interoperability for WebAssembly applications +- **[JSInterop in Wasm](https://learn.microsoft.com/en-us/aspnet/core/client-side/dotnet-interop/wasm-browser-app)** - JavaScript interoperability for WebAssembly applications ### Globalization and ICU - **[ICU for WebAssembly](../../design/features/globalization-icu-wasm.md)** - Globalization and ICU database configuration @@ -91,7 +91,7 @@ See the [WebAssembly Debugging Reference](debugging/mono/wasm-debugging.md#commo See the [Building for WebAssembly](#building-for-webassembly) section above for comprehensive build instructions for different targets. -### How do I test WASM changes end to end? +### How do I test Wasm changes end to end? Use Wasm.Build.Tests or Wasi.Build.Tests. See the [Wasm.Build.Tests README](../../src/mono/wasm/Wasm.Build.Tests/README.md) for detailed instructions. From ee8db2270f834256016a081c60724c483da4705a Mon Sep 17 00:00:00 2001 From: Ilona Tomkowicz <32700855+ilonatommy@users.noreply.github.com> Date: Thu, 2 Oct 2025 07:46:57 +0000 Subject: [PATCH 18/21] Remove redundant "comprehensive". --- docs/workflow/wasm-documentation.md | 6 +++--- src/mono/browser/README.md | 2 +- src/mono/wasi/README.md | 2 +- src/mono/wasm/features.md | 2 +- src/mono/wasm/threads.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/workflow/wasm-documentation.md b/docs/workflow/wasm-documentation.md index 903cf8ccc8c3ab..0414feb91d0996 100644 --- a/docs/workflow/wasm-documentation.md +++ b/docs/workflow/wasm-documentation.md @@ -1,6 +1,6 @@ # WebAssembly Documentation -This document serves as a comprehensive guide for contributors to the WebAssembly implementation in the dotnet/runtime repository. It provides links and references to technical documentation, workflows, and resources relevant to developing and maintaining WebAssembly support within this codebase. +This document serves as a guide for contributors to the WebAssembly implementation in the dotnet/runtime repository. It provides links and references to technical documentation, workflows, and resources relevant to developing and maintaining WebAssembly support within this codebase. ## Table of Contents @@ -26,7 +26,7 @@ This document serves as a comprehensive guide for contributors to the WebAssembl ### Core Runtime Building - **[Building CoreCLR for WebAssembly](building/coreclr/wasm.md)** - Build the CoreCLR runtime for WebAssembly targets -- **[Building Mono for Browser](../../src/mono/browser/README.md)** - Comprehensive browser build guide with samples and troubleshooting +- **[Building Mono for Browser](../../src/mono/browser/README.md)** - Browser build guide with samples and troubleshooting ### Libraries Building - **[Building Libraries for WebAssembly](building/libraries/webassembly-instructions.md)** - Build .NET libraries for WebAssembly targets @@ -89,7 +89,7 @@ See the [WebAssembly Debugging Reference](debugging/mono/wasm-debugging.md#commo ### How do I build for different WebAssembly targets? -See the [Building for WebAssembly](#building-for-webassembly) section above for comprehensive build instructions for different targets. +See the [Building for WebAssembly](#building-for-webassembly) section above for build instructions for different targets. ### How do I test Wasm changes end to end? diff --git a/src/mono/browser/README.md b/src/mono/browser/README.md index a3ea89829f10e8..af3ceeff317cf0 100644 --- a/src/mono/browser/README.md +++ b/src/mono/browser/README.md @@ -1,6 +1,6 @@ # Build WebAssembly -This document covers building .NET for WebAssembly in the browser. For comprehensive WebAssembly documentation including testing, debugging, and deployment, see [WebAssembly Documentation](../../../docs/workflow/wasm-documentation.md). +This document covers building .NET for WebAssembly in the browser. For WebAssembly documentation including testing, debugging, and deployment, see [WebAssembly Documentation](../../../docs/workflow/wasm-documentation.md). If you haven't already done so, please read [this document](../../../docs/workflow/README.md#Build_Requirements) to understand the build requirements for your operating system. If you are specifically interested in building libraries for WebAssembly, read [Libraries WebAssembly](../../../docs/workflow/building/libraries/webassembly-instructions.md). Emscripten that is needed to build the project will be provisioned automatically, unless `EMSDK_PATH` variable is set or emscripten is already present in `src\mono\browser\emsdk` directory. diff --git a/src/mono/wasi/README.md b/src/mono/wasi/README.md index 9ed6eb688e0e90..915bade5917560 100644 --- a/src/mono/wasi/README.md +++ b/src/mono/wasi/README.md @@ -2,7 +2,7 @@ This directory contains a build configuration for WASI support, plus a basic sample. This is not intended for production use, nor is it currently supported. This is a step towards possible future support. -For comprehensive WebAssembly documentation, see [WebAssembly Documentation](../../../docs/workflow/wasm-documentation.md). +For WebAssembly documentation, see [WebAssembly Documentation](../../../docs/workflow/wasm-documentation.md). ## Try it out diff --git a/src/mono/wasm/features.md b/src/mono/wasm/features.md index 466dcd81362279..266bc1f50809f9 100644 --- a/src/mono/wasm/features.md +++ b/src/mono/wasm/features.md @@ -1,6 +1,6 @@ # Configuring and hosting .NET WebAssembly applications -For comprehensive WebAssembly documentation including building, testing, and debugging, see [WebAssembly Documentation](../../../docs/workflow/wasm-documentation.md). +For WebAssembly documentation including building, testing, and debugging, see [WebAssembly Documentation](../../../docs/workflow/wasm-documentation.md). ## Table of contents - [Configuring browser features](#Configuring-browser-features) diff --git a/src/mono/wasm/threads.md b/src/mono/wasm/threads.md index f4cd6579da9375..cb73898c2c9307 100644 --- a/src/mono/wasm/threads.md +++ b/src/mono/wasm/threads.md @@ -1,6 +1,6 @@ # Threaded runtime -For comprehensive WebAssembly documentation including building, testing, and debugging, see [WebAssembly Documentation](../../../docs/workflow/wasm-documentation.md). +For WebAssembly documentation including building, testing, and debugging, see [WebAssembly Documentation](../../../docs/workflow/wasm-documentation.md). ## Building the runtime From aaa6e684c1d565ffa426bcc092f1e5d8d33ebc51 Mon Sep 17 00:00:00 2001 From: Ilona Tomkowicz <32700855+ilonatommy@users.noreply.github.com> Date: Thu, 2 Oct 2025 09:50:30 +0200 Subject: [PATCH 19/21] Apply suggestions from code review --- docs/workflow/debugging/mono/wasm-debugging.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/workflow/debugging/mono/wasm-debugging.md b/docs/workflow/debugging/mono/wasm-debugging.md index 680e7f20ee7346..f6d29a2c176c7f 100644 --- a/docs/workflow/debugging/mono/wasm-debugging.md +++ b/docs/workflow/debugging/mono/wasm-debugging.md @@ -1,9 +1,8 @@ -# WebAssembly Debugging Reference +# WebAssembly Debugging This document provides debugging instructions for WebAssembly. ## Debug with VS Code - To debug WebAssembly with Visual Studio Code: ### 1. Configuration @@ -28,7 +27,7 @@ Add the appropriate configuration to your `.vscode/launch.json` depending on you "type": "mono", "request": "attach", "address": "localhost", - "port": 64000 + "port": } ``` From e3d9e79b9358bb5bcc37270b5607bf445eff1f34 Mon Sep 17 00:00:00 2001 From: Ilona Tomkowicz <32700855+ilonatommy@users.noreply.github.com> Date: Fri, 3 Oct 2025 12:07:49 +0000 Subject: [PATCH 20/21] Support PRs with doc-only changes. --- eng/pipelines/report-green.yml | 41 ++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 eng/pipelines/report-green.yml diff --git a/eng/pipelines/report-green.yml b/eng/pipelines/report-green.yml new file mode 100644 index 00000000000000..459098023013ea --- /dev/null +++ b/eng/pipelines/report-green.yml @@ -0,0 +1,41 @@ +# This CI job only runs on PRs where all other jobs are skipped. +# This allows Build Analysis to report green. Without this, no jobs would run, +# causing Build Analysis to hang indefinitely (or until someone commented "ba-g {justification}" on the PR). + +# Only run this on PRs +trigger: none +# Run for all branches, only on paths that no-op other jobs +pr: + autoCancel: true + branches: + include: + - '*' + paths: + include: + - docs/* + - '**/*.md' + - '**/*.txt' + - LICENSE.TXT + - THIRD-PARTY-NOTICES.TXT + - CODE-OF-CONDUCT.md + - CONTRIBUTING.md + - README.md + - SECURITY.md + - PATENTS.TXT + +# ABG - Always Be Green +jobs: +- template: /eng/common/templates/jobs/jobs.yml + parameters: + enableTelemetry: true + helixRepo: dotnet/runtime + jobs: + - job: Report_Green + enableSBOM: false + pool: + vmImage: ubuntu-22.04 + steps: + - powershell: | + Write-Host "This is a documentation-only change. Exiting successfully." + exit 0 + displayName: Exit 0 for doc-only changes \ No newline at end of file From e01c246d1abe55d80e2205be2faeab4fa9b720ed Mon Sep 17 00:00:00 2001 From: Ilona Tomkowicz <32700855+ilonatommy@users.noreply.github.com> Date: Fri, 3 Oct 2025 14:25:32 +0000 Subject: [PATCH 21/21] Apply @jkotas suggestion. --- docs/workflow/ci/failure-analysis.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/workflow/ci/failure-analysis.md b/docs/workflow/ci/failure-analysis.md index 2a9e7547ef5acc..59244617372564 100644 --- a/docs/workflow/ci/failure-analysis.md +++ b/docs/workflow/ci/failure-analysis.md @@ -127,7 +127,6 @@ The `Build Analysis` requests are sent to a queue. In certain scenarios, this qu While most failures can be matched via known issues, a few failures modes cannot be matched currently and it is valid to suppress them manually. Suggested wording to use in these situations (this list is not exhaustive): -- `/ba-g doc changes only` - Build analysis won't turn green for PRs that contain documentation .md file changes only. - `/ba-g deadletter` - Helix infrastructure failed with "This is a helix work item crash with status: DeadLetter." error message. Validate that the coverage provided by the dead-lettered leg is not relevant to the PR first. Rerun the leg instead if the coverage is relevant. - `/ba-g missing logs` - Logs are completely missing. - `/ba-g insufficient info in logs` - No good unique pattern in the logs to open a known issue.