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