Add WASI docs

doc/guide/src/PlatformSpecificNotes.adoc

@@ -14,6 +14,7 @@ Here are notes about using MLton on the following platforms.
 * <<RunningOnNetBSD#,NetBSD>>
 * <<RunningOnOpenBSD#,OpenBSD>>
 * <<RunningOnSolaris#,Solaris>>
+* <<RunningOnWASI#,WASI>>
 
 == Architectures
 
@@ -22,6 +23,7 @@ Here are notes about using MLton on the following platforms.
 * <<RunningOnPowerPC#,PowerPC>>
 * <<RunningOnPowerPC64#,PowerPC64>>
 * <<RunningOnSparc#,Sparc>>
+* <<RunningOnWASI#,WebAssembly>>
 * <<RunningOnX86#,X86>>
 
 == Also see

doc/guide/src/RunningOnWASI.adoc

@@ -0,0 +1,99 @@
+= 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 <<GMP#>> library is required. It must be compiled for WASI. An
+   example configuration command is below (substitute your own wasi-sdk paths):
++
+[,shell]
+----
+./configure --host=wasm32-unknown-wasi \
+            CC=$HOME/wasi-sdk-21.0/bin/clang \
+            RANLIB=$HOME/wasi-sdk-21.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-21.0/bin/clang \
+      AR=$HOME/wasi-sdk-21.0/bin/ar \
+      RANLIB=$HOME/wasi-sdk-21.0/bin/ranlib \
+      TARGET_OS=wasi \
+      TARGET_ARCH=wasm32 \
+      TARGET=wasm32-unknown-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-unknown-wasi`` flag, to build WASI binaries:
++
+[,shell]
+----
+mlton -target wasm32-unknown-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