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$ git clone https://github.com/emscripten-core/emsdk.git 14$ cd emsdk 15 16# Download and install the latest SDK tools: 17$ ./emsdk install latest 18 19# Make the "latest" SDK "active" for the current user: 20$ ./emsdk activate latest 21``` 22 23Those parts only need to be run once, but the SDK can be updated using: 24 25``` 26$ git pull 27$ ./emsdk activate latest 28``` 29 30The following needs to be run for each shell instance which needs the 31`emcc` compiler: 32 33``` 34# Activate PATH and other environment variables in the current terminal: 35$ source ./emsdk_env.sh 36 37$ which emcc 38/path/to/emsdk/upstream/emscripten/emcc 39``` 40 41Optionally, add that to your login shell's resource file (`~/.bashrc` 42or equivalent). 43 44That `env` script needs to be sourced for building this application 45from the top of the sqlite3 build tree: 46 47``` 48$ make fiddle 49``` 50 51Or: 52 53``` 54$ cd ext/wasm 55$ make 56``` 57 58That will generate the fiddle application under 59[ext/fiddle](/dir/ext/wasm/fiddle), as `fiddle.html`. That application 60cannot, due to XMLHttpRequest security limitations, run if the HTML 61file is opened directly in the browser (i.e. if it is opened using a 62`file://` URL), so it needs to be served via an HTTP server. For 63example, using [althttpd][]: 64 65``` 66$ cd ext/wasm/fiddle 67$ althttpd -page fiddle.html 68``` 69 70That will open the system's browser and run the fiddle app's page. 71 72Note that when serving this app via [althttpd][], it must be a version 73from 2022-05-17 or newer so that it recognizes the `.wasm` file 74extension and responds with the mimetype `application/wasm`, as the 75WASM loader is pedantic about that detail. 76 77 78# Known Quirks and Limitations 79 80Some "impedence mismatch" between C and WASM/JavaScript is to be 81expected. 82 83## No I/O 84 85sqlite3 shell commands which require file I/O or pipes are disabled in 86the WASM build. 87 88## `exit()` Triggered from C 89 90When C code calls `exit()`, as happens (for example) when running an 91"unsafe" command when safe mode is active, WASM's connection to the 92sqlite3 shell environment has no sensible choice but to shut down 93because `exit()` leaves it in a state we can no longer recover 94from. The JavaScript-side application attempts to recognize this and 95warn the user that restarting the application is necessary. Currently 96the only way to restart it is to reload the page. Restructuring the 97shell code such that it could be "rebooted" without restarting the 98JS app would require some invasive changes which are not currently 99on any TODO list but have not been entirely ruled out long-term. 100 101 102[emscripten]: https://emscripten.org 103[althttpd]: https://sqlite.org/althttpd 104