wasm-documentation.md

WebAssembly Documentation

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

• Getting Started
• Building for WebAssembly
• Testing and Debugging
• Features and Configuration
• Deployment and Hosting
• Advanced Topics
• FAQ
• 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

Building for WebAssembly

Core Runtime Building

• Building CoreCLR for WebAssembly - Build the CoreCLR runtime for WebAssembly targets
• Building Mono for Browser - Browser build guide with samples and troubleshooting

Libraries Building

• Building Libraries for WebAssembly - Build .NET libraries for WebAssembly targets
• WebAssembly Build System - WasmApp.targets and build system internals

WASI Support

• WASI Support - Experimental WASI support, building, and configuration

Testing and Debugging

Library Testing

• Testing Libraries on WebAssembly - Run library tests with different JavaScript engines and browsers
• Debugging WebAssembly Libraries - Debug library tests in Chrome DevTools and VS Code

Runtime Debugging

• WebAssembly Debugging - Consolidated debugging reference for WebAssembly applications and native runtime debugging
• VS Code Debugging - Set up VS Code for debugging WASM applications

Common Debugging Scenarios

For debugging instructions including VS Code and Chrome DevTools setup, see the WebAssembly Debugging Reference.

Running coreclr callhelpers generator

After building the runtime, use the generate-coreclr-helpers script for your platform (.cmd or .sh) in src/tasks/WasmAppBuilder to [re]generate the call helpers in src/coreclr/vm/wasm.

Features and Configuration

Runtime Features

• WebAssembly Features - Configure browser features, SIMD, threads, AOT, and more
• Threading Support - Multi-threading support and limitations

JavaScript Interop

• JSInterop in Wasm - JavaScript interoperability for WebAssembly applications

Globalization and ICU

• ICU for WebAssembly - Globalization and ICU database configuration

Testing WebAssembly Changes

For testing WebAssembly implementation changes end-to-end, see the testing documentation.

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?

See the WebAssembly Debugging Reference for detailed instructions on debugging library tests locally.

How do I build for different WebAssembly targets?

See the Building for WebAssembly section above for 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 for detailed instructions.

How do I enable multi-threading?

See the Threading Support documentation for detailed multi-threading configuration and limitations.

What JavaScript engines are supported for testing?

See the Testing Libraries on WebAssembly documentation for JavaScript engine installation and usage.

How do I collect native stack traces with symbols?

See the WebAssembly Debugging documentation for symbol configuration.

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, see Building the Repo for detailed instructions.

Then test your changes with Testing the Repo using the 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 or ask in the dotnet/runtime repository discussions.