From 22170b2cacab466b6f9c8feddb37d7ff3dbdcd1e Mon Sep 17 00:00:00 2001
From: Drew Hess <src@drewhess.com>
Date: Wed, 22 Nov 2023 18:29:53 +0000
Subject: [PATCH] doc: add some developer docs on how to build for Wasm

Signed-off-by: Drew Hess <src@drewhess.com>
---
 docs/development-guide-toc.md |  1 +
 docs/wasm.md                  | 39 +++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)
 create mode 100644 docs/wasm.md

diff --git a/docs/development-guide-toc.md b/docs/development-guide-toc.md
index 890ec830a..c1dbde450 100644
--- a/docs/development-guide-toc.md
+++ b/docs/development-guide-toc.md
@@ -27,3 +27,4 @@ the various packages' Haddocks.
 * [Primitives](primitives.md)
 * [Database ops](database.md)
 * [Benchmarking](benchmarking.md)
+* [WebAssembly support](wasm.md)
diff --git a/docs/wasm.md b/docs/wasm.md
new file mode 100644
index 000000000..659f6b40b
--- /dev/null
+++ b/docs/wasm.md
@@ -0,0 +1,39 @@
+# WebAssembly (Wasm) support
+
+**Note**: WebAssembly support is currently very preliminary.
+
+For horizontal scalability reasons, we would like to run the `primer`
+and `primer-api` packages in the student's browser, rather than on a
+backend server. Therefore, we'd like to compile these packages to a
+`wasm32-wasi` target and call the (native) Primer API from TypeScript.
+
+Currently, we can compile these two packages to `wasm32-wasi`, but
+with the following caveats:
+
+1. Neither `haskell.nix` nor `nixpkgs.haskellPackages` support the
+   `wasm32-wasi` cross-target at the moment, so we can only build Wasm
+   targets directly via `wasm32-wasi-cabal` and `wasm32-wasi-ghc`. For
+   interactive development, we provide a special `nix develop` shell
+   which provides the necessary tools:
+
+   ```sh
+   nix develop .#wasm
+   ```
+
+2. Once you're in the special Wasm shell, it's advisable to use the
+   special `wasm32` `Makefile` targets. To build the libraries, run:
+
+   ```sh
+   make wasm32-configure
+   make wasm32-build
+   ```
+
+   To build the tests and run them using the `wasmtime` runtime, run:
+
+   ```sh
+   make wasm32-test
+   ```
+
+   The `wasm32-test`, in particular, needs to run several steps that
+   you'd otherwise need to run by hand in order to work around
+   `wasmtime` issues.