FossilOrigin-Name: bee436e62a956e49b0df4a92abff2c89f2b44e21d8f593716df0331f8fc49814
2.9 KiB
This directory houses a "fiddle"-style application which embeds a Web Assembly (WASM) build of the sqlite3 shell app into an HTML page, effectively running the shell in a client-side browser.
It requires emscripten and that the build environment be set up for emscripten. A mini-HOWTO for setting that up follows...
First, install the Emscripten SDK, as documented here and summarized below for Linux environments:
# Clone the emscripten repository:
$ git clone https://github.com/emscripten-core/emsdk.git
$ cd emsdk
# Download and install the latest SDK tools:
$ ./emsdk install latest
# Make the "latest" SDK "active" for the current user:
$ ./emsdk activate latest
Those parts only need to be run once. The following needs to be run for each
shell instance which needs the emcc
compiler:
# Activate PATH and other environment variables in the current terminal:
$ source ./emsdk_env.sh
$ which emcc
/path/to/emsdk/upstream/emscripten/emcc
That env
script needs to be sourced for building this application from the
top of the sqlite3 build tree:
$ make fiddle
Or:
$ cd ext/fiddle
$ make
That will generate the fiddle application under
ext/fiddle, as fiddle.html
. That application
cannot, due to XMLHttpRequest security limitations, run if the HTML
file is opened directly in the browser (i.e. if it is opened using a
file://
URL), so it needs to be served via an HTTP server. For
example, using althttpd:
$ cd ext/fiddle
$ althttpd -debug 1 -jail 0 -port 9090 -root .
Then browse to http://localhost:9090/fiddle.html
.
Note that when serving this app via althttpd, it must be a version
from 2022-05-17 or newer so that it recognizes the .wasm
file
extension and responds with the mimetype application/wasm
, as the
WASM loader is pedantic about that detail.
Known Quirks and Limitations
Some "impedence mismatch" between C and WASM/JavaScript is to be expected.
No I/O
sqlite3 shell commands which require file I/O or pipes are disabled in the WASM build.
exit()
Triggered from C
When C code calls exit()
, as happens (for example) when running an
"unsafe" command when safe mode is active, WASM's connection to the
sqlite3 shell environment has no sensible choice but to shut down
because exit()
leaves it in a state we can no longer recover
from. The JavaScript-side application attempts to recognize this and
warn the user that restarting the application is necessary. Currently
the only way to restart it is to reload the page. Restructuring the
shell code such that it could be "rebooted" without restarting the
JS app would require some invasive changes which are not currently
on any TODO list but have not been entirely ruled out long-term.