diff --git a/src/mono/wasi/README.md b/src/mono/wasi/README.md index 106c65322dc3a..9cf3f8757afaf 100644 --- a/src/mono/wasi/README.md +++ b/src/mono/wasi/README.md @@ -2,6 +2,46 @@ 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. +## Try it out + +Here is a quick overview of how to consume published artifacts. Assuming .NET SDK is already installed, you should run: + +``` +dotnet workload install wasi-experimental +``` + +This will install workload for building .NET based WASI apps + basic template. +Now you can create a new .NET application that targets WASI + +``` +dotnet new wasiconsole +``` + +And run it with + +``` +dotnet run +``` + +The `runtimeconfig.template.json` contains `perHostConfig` section where wasm hosts can be configured + +### Wasi SDK + +The workload for the time being doesn't include Wasi SDK, which is responsible for native compilation. +If you don't need to modify runtime configuration, you can omit this step. In case you get: + +``` +error : Could not find wasi-sdk. Either set $(WASI_SDK_PATH), or use workloads to get the sdk. SDK is required for building native files. +``` + +you will need to separately download a WASI SDK from https://github.com/WebAssembly/wasi-sdk and point an environment variable `WASI_SDK_PATH` or MSBuild property `WasiSdkRoot` to a location where you extract it. + +### Optional build flags + +- `WasmSingleFileBundle` - bundle all assets into the `.wasm`. The output file name will match the project name. +- `InvariantGlobalization` - remove globalization support, decrease the publish size. +- More details can be found at https://github.com/dotnet/runtime/blob/main/src/mono/wasm/build/WasmApp.Common.targets and https://github.com/dotnet/runtime/blob/main/src/mono/wasi/build/WasiApp.targets + ## How it works The mechanism for executing .NET code in a WASI runtime environment is equivalent to how `dotnet.wasm` executes .NET code in a browser environment. That is, it runs the Mono interpreter to execute .NET bytecode that has been built in the normal way. It should also work with AOT but this is not yet attempted. @@ -65,4 +105,4 @@ Download the Mono Debug extension and configure a launch.json like this: } ] } -``` \ No newline at end of file +```