## MLton 20241230+git20251029+dfsg-5

# RunningOnWASI

WASI is a somewhat POSIX-compatible system interface for writing 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 Wasmtime).

## Notes

- To compile MLton for WASI:

  - You will need a WASI compiler and sysroot. These are both included in wasi-sdk. Follow the directions to download and unpack a copy.

  - The GMP 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):

        ./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 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:

        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:

        mlton -target wasm32-wasi hello-world.sml

  - Using Wasmtime, you can run your WASI binaries locally:

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