Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,6 @@
/src/mono/browser @lewing @pavelsavara
/src/mono/wasi @lewing @pavelsavara
/src/mono/wasm @lewing @pavelsavara
/src/mono/browser/debugger @thaystg @ilonatommy
/src/mono/wasm/build @maraf @akoeplinger
/src/mono/wasi/build @maraf @akoeplinger
/src/mono/browser/build @maraf @akoeplinger
Expand All @@ -83,7 +82,6 @@

/src/mono/nuget/*WebAssembly*/ @lewing @akoeplinger
/src/mono/nuget/*MonoTargets*/ @lewing @akoeplinger
/src/mono/nuget/*BrowserDebugHost*/ @lewing @akoeplinger
/src/mono/nuget/*Workload.Mono.Toolchain*/ @lewing @akoeplinger
/src/mono/nuget/*MonoAOTCompiler*/ @lewing @akoeplinger

Expand Down
141 changes: 4 additions & 137 deletions docs/workflow/debugging/mono/wasm-debugging.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,147 +2,14 @@

This document provides debugging instructions for WebAssembly.

## Debug with VS Code
To debug WebAssembly with Visual Studio Code:
## Debug native code with Chrome DevTools (DWARF)

### 1. Configuration

Add the appropriate configuration to your `.vscode/launch.json` depending on your debugging scenario:

**For WebAssembly applications, library tests, and general debugging:**
```json
{
"name": "WASM Attach",
"request": "attach",
"type": "chrome",
"address": "localhost",
"port": <PROXY_PORT>
}
```

**For WASI applications:**
```json
{
"name": "WASI Attach",
"type": "mono",
"request": "attach",
"address": "localhost",
"port": <PROXY_PORT>
}
```

Replace `<PROXY_PORT>` 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
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":

![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**: 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
Native C/C++ code compiled to WebAssembly can be debugged directly in Chrome DevTools using DWARF debug info:

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 <APP_URL>
```

Replace `<APP_URL>` with the URL shown in your application's output.

## Common Debugging Workflow

### For 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 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 <APP_URL>
```

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.

Use either Chrome DevTools or VS Code as described above to attach the debugger

### 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
3. **Open DevTools**: Open Chrome DevTools (F12) and use the `Sources` tab to browse the source files
4. **Debug native code**: Set breakpoints, step through C/C++ code, and inspect WebAssembly linear memory

## Advanced Debugging

Expand Down
2 changes: 1 addition & 1 deletion docs/workflow/wasm-documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ Located in `src/mono/sample/wasm/`:

### How do I debug a library test failure seen on CI?

See the [WebAssembly Debugging Reference](debugging/mono/wasm-debugging.md#common-debugging-workflow) for detailed instructions on debugging library tests locally.
See the [WebAssembly Debugging Reference](debugging/mono/wasm-debugging.md) for detailed instructions on debugging locally.

### How do I build for different WebAssembly targets?

Expand Down
1 change: 0 additions & 1 deletion eng/Signing.props
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,6 @@
<PackageArtifacts
Include="$(ArtifactsPackagesDir)**\Microsoft.NET.Runtime.wasm.Sample.Mono.*.nupkg;
$(ArtifactsPackagesDir)**\Microsoft.NET.Runtime.WorkloadTesting.Internal.*.nupkg;
$(ArtifactsPackagesDir)**\Microsoft.NETCore.BrowserDebugHost.Transport.*.nupkg;
$(ArtifactsPackagesDir)**\Microsoft.NET.Runtime.WebAssembly.Sdk.*.nupkg;
$(ArtifactsPackagesDir)**\Microsoft.NET.Runtime.WebAssembly.Templates.net11.*.nupkg;
$(ArtifactsPackagesDir)**\Microsoft.NET.Sdk.WebAssembly.Pack.*.nupkg;
Expand Down
3 changes: 1 addition & 2 deletions eng/Versions.props
Original file line number Diff line number Diff line change
Expand Up @@ -175,9 +175,8 @@
<!-- WiX 5+ dependencies for MSI generation -->
<SwixPackageVersion>1.1.87-gba258badda</SwixPackageVersion>
<WixPackageVersion>1.0.0-v3.14.0.5722</WixPackageVersion>
<!-- BrowserDebugProxy libs -->
<!-- Microsoft.Diagnostics.NETCore.Client (EventPipe tests) -->
<MicrosoftExtensionsLoggingVersion>3.1.7</MicrosoftExtensionsLoggingVersion>
<MicrosoftSymbolStoreVersion>1.0.406601</MicrosoftSymbolStoreVersion>
<!-- WiX 5+ dependencies for MSI generation -->
<MicrosoftWixVersion>6.0.3-dotnet.6</MicrosoftWixVersion>
<MicrosoftWixToolsetUIWixextVersion>6.0.3-dotnet.6</MicrosoftWixToolsetUIWixextVersion>
Expand Down
5 changes: 0 additions & 5 deletions eng/pipelines/common/evaluate-default-paths.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,6 @@ parameters:
src/mono/nuget/Microsoft.NET.Runtime.WebAssembly.Wasi.Sdk/*
src/mono/nuget/Microsoft.NET.Runtime.wasm.Sample.Mono/*
src/mono/nuget/Microsoft.NET.Sdk.WebAssembly.Pack/*
src/mono/nuget/Microsoft.NETCore.BrowserDebugHost.Transport/*
src/mono/nuget/Microsoft.NET.Runtime.WorkloadTesting.Internal/**/*
src/mono/nuget/Microsoft.NET.Workload*
src/mono/sample/wasm/*
Expand Down Expand Up @@ -256,7 +255,6 @@ jobs:
- src/mono/nuget/Microsoft.NET.Sdk.WebAssembly.Pack/*
- src/mono/nuget/Microsoft.NET.Runtime.wasm.Sample.Mono/*
- src/mono/nuget/Microsoft.NET.Workload*
- src/mono/nuget/Microsoft.NETCore.BrowserDebugHost.Transport/*
- src/mono/browser/build/*
- src/mono/browser/emscripten-version.txt
- src/mono/browser/runtime/*
Expand Down Expand Up @@ -289,7 +287,6 @@ jobs:
- src/mono/tests/*
- src/mono/tools/*
- src/mono/wasi/*
- src/mono/browser/debugger/*
- src/mono/wasm/host/*
- src/mono/wasm/templates/*
- src/mono/wasm/testassets/*
Expand Down Expand Up @@ -328,7 +325,6 @@ jobs:
- eng/testing/workloads-wasi.targets
- eng/testing/workloads-wasm.targets
- src/mono/mono/component/mini-wasm-debugger.c
- src/mono/browser/debugger/*
- src/mono/wasm/host/*
- src/mono/wasm/templates/*
- src/mono/wasm/testassets/*
Expand All @@ -338,7 +334,6 @@ jobs:
- src/mono/wasi/testassets/*
- src/mono/nuget/Microsoft.NET.Runtime*
- src/mono/nuget/Microsoft.NET.Workload*
- src/mono/nuget/Microsoft.NETCore.BrowserDebugHost.Transport/*
- ${{ parameters._const_paths._always_exclude }}
- ${{ parameters._const_paths._perf_pipeline_specific_only }}

Expand Down
2 changes: 1 addition & 1 deletion eng/pipelines/common/variables.yml
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ variables:
- name: isNotExtraPlatformsBuild
value: ${{ ne(variables['Build.DefinitionName'], 'runtime-extra-platforms') }}
- name: isWasmOnlyBuild
value: ${{ in(variables['Build.DefinitionName'], 'runtime-wasm', 'runtime-wasm-libtests', 'runtime-wasm-non-libtests', 'runtime-wasm-dbgtests', 'runtime-wasm-optional') }}
value: ${{ in(variables['Build.DefinitionName'], 'runtime-wasm', 'runtime-wasm-libtests', 'runtime-wasm-non-libtests', 'runtime-wasm-optional') }}
- name: isiOSLikeOnlyBuild
value: ${{ in(variables['Build.DefinitionName'], 'runtime-ioslike') }}
- name: isiOSLikeSimulatorOnlyBuild
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ parameters:
excludeLibTests: false
excludeNonLibTests: false
excludeOptional: true
debuggerTestsOnly: false

jobs:

Expand Down Expand Up @@ -62,7 +61,7 @@ jobs:
# - run everything, if relevant paths changed
# - For runtime-wasm, force run all the jobs
#
- ${{ if and(ne(parameters.isRollingBuild, true), ne(parameters.excludeLibTests, true), ne(parameters.debuggerTestsOnly, true)) }}:
- ${{ if and(ne(parameters.isRollingBuild, true), ne(parameters.excludeLibTests, true)) }}:
# Library tests
# these run on runtime also
- template: /eng/pipelines/common/templates/wasm-library-tests.yml
Expand Down Expand Up @@ -164,7 +163,7 @@ jobs:
scenarios:
- WasmTestOnWasmtime

- ${{ if and(ne(parameters.isRollingBuild, true), ne(parameters.excludeNonLibTests, true), ne(parameters.debuggerTestsOnly, true)) }}:
- ${{ if and(ne(parameters.isRollingBuild, true), ne(parameters.excludeNonLibTests, true)) }}:
# Builds only
- template: /eng/pipelines/common/templates/wasm-build-only.yml
parameters:
Expand Down
24 changes: 0 additions & 24 deletions eng/pipelines/runtime-wasm-dbgtests.yml

This file was deleted.

1 change: 0 additions & 1 deletion src/coreclr/.nuget/coreclr-packages.proj
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@
</ItemGroup>

<ItemGroup Condition="'$(TargetsBrowser)' == 'true'">
<ProjectReference Include="$(MonoProjectRoot)\nuget\Microsoft.NETCore.BrowserDebugHost.Transport\Microsoft.NETCore.BrowserDebugHost.Transport.pkgproj" />
<ProjectReference Include="$(MonoProjectRoot)\wasm\templates\Microsoft.NET.Runtime.WebAssembly.Templates.csproj" />
<ProjectReference Include="$(MonoProjectRoot)\nuget\Microsoft.NET.Sdk.WebAssembly.Pack\Microsoft.NET.Sdk.WebAssembly.Pack.pkgproj" />

Expand Down
2 changes: 0 additions & 2 deletions src/mono/browser/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -135,8 +135,6 @@ submit-tests-helix:
$(_MSBUILD_WASM_BUILD_ARGS) \
$(MSBUILD_ARGS)

build-dbg-proxy:
$(DOTNET) build $(TOP)/src/mono/browser/debugger/BrowserDebugHost $(MSBUILD_ARGS)
build-app-host:
$(DOTNET) build $(TOP)/src/mono/wasm/host $(_MSBUILD_WASM_BUILD_ARGS) $(MSBUILD_ARGS)

Expand Down
21 changes: 0 additions & 21 deletions src/mono/browser/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,22 +149,6 @@ src/mono/wasm/symbolicator$ dotnet run /path/to/dotnet.native.js.symbols /path/t

When not relinking, or not building with AOT, you can find `dotnet.native.js.symbols` in the runtime pack.

## Debugger tests on macOS

Debugger tests need `Google Chrome` to be installed.

`make run-debugger-tests`

To run a test with `FooBar` in the name:

`make run-debugger-tests TEST_FILTER=FooBar`

(See https://learn.microsoft.com/dotnet/core/testing/selective-unit-tests?pivots=xunit for filter options)

Additional arguments for `dotnet test` can be passed via `MSBUILD_ARGS` or `TEST_ARGS`. For example `MSBUILD_ARGS="/p:WasmDebugLevel=5"`. Though only one of `TEST_ARGS`, or `TEST_FILTER` can be used at a time.

Chrome can be installed for testing by setting `InstallChromeForDebuggerTests=true` when building the tests.

## Run samples

The samples in `src/mono/sample/wasm` can be build and run like this:
Expand Down Expand Up @@ -333,7 +317,6 @@ npm update --lockfile-version=1
| libtests aot | linux+windows: smoke, only-pc |
| high resource aot | none |
| Wasm.Build.Tests | linux+windows: only-pc |
| Debugger tests | linux+windows: only-pc |
| Runtime tests | linux+windows: only-pc |

### Run manually with `/azp run ..`
Expand All @@ -348,15 +331,12 @@ npm update --lockfile-version=1
| libtests aot | linux+windows: all | linux+windows: all | none |
| high resource aot | linux+windows: all | linux+windows: all | none |
| Wasm.Build.Tests | linux+windows | none | linux+windows |
| Debugger tests | linux+windows | none | linux+windows |
| Runtime tests | linux | none | linux |
| Multi-thread | linux: all tests | linux: all tests | none |

* `runtime-extra-platforms` does not run any wasm jobs on PRs
* `high resource aot` runs a few specific library tests with AOT, that require more memory to AOT.

* `runtime-wasm-dbgtests` runs all the debugger test jobs

## Rolling build (twice a day):

* `runtime` runs all the wasm jobs, but `AOT` still only runs smoke tests.
Expand All @@ -370,7 +350,6 @@ npm update --lockfile-version=1
| high resource aot | none | linux+windows: all |
| | | |
| Wasm.Build.Tests | linux+windows | none |
| Debugger tests | linux+windows | none |
| Runtime tests | linux | none |
| Multi-thread | linux: build only | none |

Expand Down

This file was deleted.

Loading
Loading