1This directory houses the [Web Assembly (WASM)](https://en.wikipedia.org/wiki/WebAssembly) 2parts of the sqlite3 build. 3 4It requires [emscripten][] and that the build environment be set up for 5emscripten. A mini-HOWTO for setting that up follows... 6 7First, install the Emscripten SDK, as documented 8[here](https://emscripten.org/docs/getting_started/downloads.html) and summarized 9below for Linux environments: 10 11``` 12# Clone the emscripten repository: 13$ sudo apt install git 14$ git clone https://github.com/emscripten-core/emsdk.git 15$ cd emsdk 16 17# Download and install the latest SDK tools: 18$ ./emsdk install latest 19 20# Make the "latest" SDK "active" for the current user: 21$ ./emsdk activate latest 22``` 23 24Those parts only need to be run once, but the SDK can be updated using: 25 26``` 27$ git pull 28$ ./emsdk activate latest 29``` 30 31The following needs to be run for each shell instance which needs the 32`emcc` compiler: 33 34``` 35# Activate PATH and other environment variables in the current terminal: 36$ source ./emsdk_env.sh 37 38$ which emcc 39/path/to/emsdk/upstream/emscripten/emcc 40``` 41 42Optionally, add that to your login shell's resource file (`~/.bashrc` 43or equivalent). 44 45That `env` script needs to be sourced for building this application 46from the top of the sqlite3 build tree: 47 48``` 49$ make fiddle 50``` 51 52Or: 53 54``` 55$ cd ext/wasm 56$ make 57``` 58 59That will generate the fiddle application under 60[ext/fiddle](/dir/ext/wasm/fiddle), as `fiddle.html`. That application 61cannot, due to XMLHttpRequest security limitations, run if the HTML 62file is opened directly in the browser (i.e. if it is opened using a 63`file://` URL), so it needs to be served via an HTTP server. For 64example, using [althttpd][]: 65 66``` 67$ cd ext/wasm/fiddle 68$ althttpd -page fiddle.html 69``` 70 71That will open the system's browser and run the fiddle app's page. 72 73Note that when serving this app via [althttpd][], it must be a version 74from 2022-05-17 or newer so that it recognizes the `.wasm` file 75extension and responds with the mimetype `application/wasm`, as the 76WASM loader is pedantic about that detail. 77 78# Testing on a remote machine that is accessed via SSH 79 80*NB: The following are developer notes, last validated on 2022-08-18* 81 82 * Remote: Install git, emsdk, and althttpd 83 * Use a [version of althttpd](https://sqlite.org/althttpd/timeline?r=enable-atomics) 84 that adds HTTP reply header lines to enable SharedArrayBuffers. These header 85 lines are required: 86``` 87 Cross-Origin-Opener-Policy: same-origin 88 Cross-Origin-Embedder-Policy: require-corp 89``` 90 * Remote: Install the SQLite source tree. CD to ext/wasm 91 * Remote: "`make`" to build WASM 92 * Remote: althttpd --port 8080 --popup 93 * Local: ssh -L 8180:localhost:8080 remote 94 * Local: Point your web-browser at http://localhost:8180/testing1.html 95 96In order to enable [SharedArrayBuffers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer), 97the web-browser requires that the two extra Cross-Origin lines be present 98in HTTP reply headers and that the request must come from "localhost". 99Since the web-server is on a different machine from 100the web-broser, the localhost requirement means that the connection must be tunneled 101using SSH. 102 103 104 105# Known Quirks and Limitations 106 107Some "impedence mismatch" between C and WASM/JavaScript is to be 108expected. 109 110## No I/O 111 112sqlite3 shell commands which require file I/O or pipes are disabled in 113the WASM build. 114 115## `exit()` Triggered from C 116 117When C code calls `exit()`, as happens (for example) when running an 118"unsafe" command when safe mode is active, WASM's connection to the 119sqlite3 shell environment has no sensible choice but to shut down 120because `exit()` leaves it in a state we can no longer recover 121from. The JavaScript-side application attempts to recognize this and 122warn the user that restarting the application is necessary. Currently 123the only way to restart it is to reload the page. Restructuring the 124shell code such that it could be "rebooted" without restarting the 125JS app would require some invasive changes which are not currently 126on any TODO list but have not been entirely ruled out long-term. 127 128 129[emscripten]: https://emscripten.org 130[althttpd]: https://sqlite.org/althttpd 131