From 811395d1d4bc080fd10c287d9787db2f101ce5e2 Mon Sep 17 00:00:00 2001 From: Adam Goode Date: Mon, 12 Feb 2024 11:23:47 -0500 Subject: [PATCH] Add WASI docs --- doc/guide/src/PlatformSpecificNotes.adoc | 2 + doc/guide/src/RunningOnWASI.adoc | 102 +++++++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 doc/guide/src/RunningOnWASI.adoc diff --git a/doc/guide/src/PlatformSpecificNotes.adoc b/doc/guide/src/PlatformSpecificNotes.adoc index ab1769504..f0a00f7df 100644 --- a/doc/guide/src/PlatformSpecificNotes.adoc +++ b/doc/guide/src/PlatformSpecificNotes.adoc @@ -14,6 +14,7 @@ Here are notes about using MLton on the following platforms. * <> * <> * <> +* <> == Architectures @@ -22,6 +23,7 @@ Here are notes about using MLton on the following platforms. * <> * <> * <> +* <> * <> == Also see diff --git a/doc/guide/src/RunningOnWASI.adoc b/doc/guide/src/RunningOnWASI.adoc new file mode 100644 index 000000000..d2e6bcfba --- /dev/null +++ b/doc/guide/src/RunningOnWASI.adoc @@ -0,0 +1,102 @@ += RunningOnWASI + +https://wasi.dev[WASI] is a somewhat POSIX-compatible system interface +for writing https://webassembly.org[WebAssembly] (Wasm) programs. + +MLton does not run on WASI directly (since it requires unimplemented +functionality), but it can cross-compile to this target, resuling in +binaries that can run in the browser (using a shim) and from the +command line (using something like https://wasmtime.dev[Wasmtime]). + +== Notes + +* To compile MLton for WASI: + +** You will need a WASI compiler and sysroot. These are both included + in https://github.com/WebAssembly/wasi-sdk[wasi-sdk]. Follow the + directions to download and unpack a copy. + +** The <> library is required. It must be compiled for + WASI. Download it from https://gmplib.org, build it and install it + to a local prefix. An example configuration command is below + (substitute your own wasi-sdk paths): ++ +[,shell] +---- +./configure --host=wasm32-wasi \ + --prefix=$HOME/gmp-wasi-INSTALL \ + CC=$HOME/wasi-sdk-22.0/bin/clang \ + RANLIB=$HOME/wasi-sdk-22.0/bin/ranlib \ + CFLAGS=-D_WASI_EMULATED_SIGNAL LDFLAGS=-lwasi-emulated-signal +---- + +** During compilation of MLton, some files are generated, compiled, and + ran. When compiling the MLton runtime for WASI, you will need a way + of executing these binaries. Install https://wasmtime.dev[Wasmtime] + to do this. + +** MLton must be compiled and installed, then the MLton WASI runtime + target must be compiled and installed. Build and install MLton normally, + then clean the source directory and build the WASI runtime. An example + to build and install the WASI runtime is: ++ +[,shell] +---- +gmake CC=$HOME/wasi-sdk-22.0/bin/clang \ + AR=$HOME/wasi-sdk-22.0/bin/ar \ + RANLIB=$HOME/wasi-sdk-22.0/bin/ranlib \ + TARGET_OS=wasi \ + TARGET_ARCH=wasm32 \ + TARGET=wasm32-wasi \ + WITH_GMP_DIR=$HOME/gmp-wasi-INSTALL \ + PREFIX=$HOME/mlton-INSTALL \ + dirs runtime install-runtime +---- ++ +Once this is complete, you should have a functional MLton that can +cross-compile to WASI. + +* Compiling WASI binaries with MLton: + +** Once installed, you can run MLton with the + ``-target wasm32-wasi`` flag, to build WASI binaries: ++ +[,shell] +---- +mlton -target wasm32-wasi hello-world.sml +---- + +** Using Wasmtime, you can run your WASI binaries locally: ++ +[,shell] +---- +wasmtime hello-world +---- ++ +---- +Hello, World! +---- + +== Known issues + +* Many functions are unimplemented and will cause link errors during + compilation, allowing for early detection of incompatibilities. See + https://github.com/WebAssembly/wasi-libc[wasi-libc] for what is + available. In general, anything listed in ``platform/wasi.h`` is + unavailable for use. + +* Disk-backed heap is not supported. Do not set ``may-page-heap`` to + ``true``. + +* The maximum amount of available memory is fixed. See + ``platform/wasi.c`` for the current value. + +* The WASI runtime is restrictive regarding file IO and other + operations. You will need to map directories for use by compiled + binaries. See the Wasmtime help for details on how to do this. + +* MLton currently only supports WASI, which requires a shim to run in + browsers. A few options are available: + +** https://github.com/bjorn3/browser_wasi_shim +** https://runno.dev/wasi