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 a number of files required for a handful of 61test and demo applications which can be accessed via 62`index.html`. WASM content cannot, due to XMLHttpRequest security 63limitations, be loaded if the containing HTML file is opened directly 64in the browser (i.e. if it is opened using a `file://` URL), so it 65needs to be served via an HTTP server. For example, using 66[althttpd][]: 67 68``` 69$ cd ext/wasm 70$ althttpd --enable-sab --max-age 1 --page index.html 71``` 72 73That will open the system's browser and run the index page, from which 74all of the test and demo applications can be accessed. 75 76Note that when serving this app via [althttpd][], it must be a version 77from 2022-09-26 or newer so that it recognizes the `--enable-sab` 78flag, which causes althttpd to emit two HTTP response headers which 79are required to enable JavaScript's `SharedArrayBuffer` and `Atomics` 80APIs. Those APIs are required in order to enable the OPFS-related 81features in the apps which use them. 82 83# Testing on a remote machine that is accessed via SSH 84 85*NB: The following are developer notes, last validated on 2022-08-18* 86 87 * Remote: Install git, emsdk, and althttpd 88 * Use a [version of althttpd][althttpd] from 89 September 26, 2022 or newer. 90 * Remote: Install the SQLite source tree. CD to ext/wasm 91 * Remote: "`make`" to build WASM 92 * Remote: `althttpd --enable-sab --port 8080 --popup` 93 * Local: `ssh -L 8180:localhost:8080 remote` 94 * Local: Point your web-browser at http://localhost:8180/index.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[emscripten]: https://emscripten.org 105[althttpd]: https://sqlite.org/althttpd 106