experimental/web/sample_dynamic/README.md

# Dynamic Web Sample

This experimental sample demonstrates one way to target the web platform with
IREE. The output artifact is a web page that loads a separately provided IREE
`.vmfb` (compiled ML model) and tests calling functions on it.

## Quickstart

1. Install IREE's host tools (e.g. by building the `install` target with CMake)
2. Install the Emscripten SDK by
   [following these directions](https://emscripten.org/docs/getting_started/downloads.html)
3. Initialize your Emscripten environment (e.g. run `emsdk_env.bat`)
4. From this directory, run `bash ./build_sample.sh`
    * You may need to set the path to your host tools install
5. Open the localhost address linked in the script output

To rebuild most parts of the sample (C runtime, sample HTML, CMake config,
etc.), just `control + C` to stop the local webserver and rerun the script.

## How it works

[Emscripten](https://emscripten.org/) is used (via the `emcmake` CMake wrapper)
to compile the runtime into WebAssembly and JavaScript files.

Any supported IREE program, such as
[simple_abs.mlir](../../../iree/samples/models/simple_abs.mlir), is compiled using
the "system library" linking mode (i.e. `--iree-llvm-link-embedded=false`).
This creates a shared object (typically .so/.dll, .wasm in this case). When the
runtime attempts to load this file using `dlopen()` and `dlsym()`, Emscripten
makes use of its
[runtime dynamic linking support](https://emscripten.org/docs/compiling/Dynamic-Linking.html#runtime-dynamic-linking-with-dlopen)
to instantiate a new `WebAssembly.Instance` which shares memory with the main
runtime then resolve each export provided by the new Wasm module.

### Asynchronous API

* [`iree_api.js`](./iree_api.js) exposes a Promise-based API to the hosting
  application in [`index.html`](./index.html)
* [`iree_api.js`](./iree_api.js) creates a worker running iree_worker.js, which
  includes Emscripten's JS code and instantiates the WebAssembly module
* messages are passed back and forth between [`iree_api.js`](./iree_api.js) and
  [`iree_worker.js`](./iree_worker.js) internally

### Multithreading

Multithreading is _not supported yet_. Emscripten only has experimental support
for dynamic linking + pthreads:
https://emscripten.org/docs/compiling/Dynamic-Linking.html#pthreads-support.
Compiled programs produced by IREE link with `wasm-ld`, while Emscripten expects
programs to be linked using `emcc` with the `-s SIDE_MODULE` option, which
includes several Emscripten-pthreads-specific module exported functions such as
`emscripten_tls_init`.