1 This directory houses the [Web Assembly (WASM)](https://en.wikipedia.org/wiki/WebAssembly)
2 parts of the sqlite3 build.
4 It requires [emscripten][] and that the build environment be set up for
5 emscripten. A mini-HOWTO for setting that up follows...
7 First, install the Emscripten SDK, as documented
8 [here](https://emscripten.org/docs/getting_started/downloads.html) and summarized
9 below for Linux environments:
12 # Clone the emscripten repository:
13 $ sudo apt install git
14 $ git clone https://github.com/emscripten-core/emsdk.git
17 # Download and install the latest SDK tools:
18 $ ./emsdk install latest
20 # Make the "latest" SDK "active" for the current user:
21 $ ./emsdk activate latest
24 Those parts only need to be run once, but the SDK can be updated using:
28 $ ./emsdk install latest
29 $ ./emsdk activate latest
32 The following needs to be run for each shell instance which needs the
36 # Activate PATH and other environment variables in the current terminal:
37 $ source ./emsdk_env.sh
40 /path/to/emsdk/upstream/emscripten/emcc
43 Optionally, add that to your login shell's resource file (`~/.bashrc`
46 That `env` script needs to be sourced for building this application
47 from the top of the sqlite3 build tree:
60 That will generate the a number of files required for a handful of
61 test and demo applications which can be accessed via
62 `index.html`. WASM content cannot, due to XMLHttpRequest security
63 limitations, be loaded if the containing HTML file is opened directly
64 in the browser (i.e. if it is opened using a `file://` URL), so it
65 needs to be served via an HTTP server. For example, using
70 $ althttpd --enable-sab --max-age 1 --page index.html
73 That will open the system's browser and run the index page, from which
74 all of the test and demo applications can be accessed.
76 Note that when serving this app via [althttpd][], it must be a version
77 from 2022-09-26 or newer so that it recognizes the `--enable-sab`
78 flag, which causes althttpd to emit two HTTP response headers which
79 are required to enable JavaScript's `SharedArrayBuffer` and `Atomics`
80 APIs. Those APIs are required in order to enable the OPFS-related
81 features in the apps which use them.
83 # Testing on a remote machine that is accessed via SSH
85 *NB: The following are developer notes, last validated on 2023-07-19*
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
96 In order to enable [SharedArrayBuffer][], the web-browser requires
97 that the two extra Cross-Origin lines be present in HTTP reply headers
98 and that the request must come from "localhost" (_or_ over an SSL
99 connection). Since the web-server is on a different machine from the
100 web-broser, the localhost requirement means that the connection must
101 be tunneled using SSH.
104 [emscripten]: https://emscripten.org
105 [althttpd]: https://sqlite.org/althttpd
106 [SharedArrayBuffer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer