ext/fiddle/index.md

   1 This directory houses a "fiddle"-style application which embeds a
   2 [Web Assembly (WASM)](https://en.wikipedia.org/wiki/WebAssembly)
   3 build of the sqlite3 shell app into an HTML page, effectively running
   4 the shell in a client-side browser.
   5
   6 It requires [emscripten][] and that the build environment be set up for
   7 emscripten. A mini-HOWTO for setting that up follows...
   8
   9 First, install the Emscripten SDK, as documented
  10 [here](https://emscripten.org/docs/getting_started/downloads.html) and summarized
  11 below for Linux environments:
  12
  13 ```
  14 # Clone the emscripten repository:
  15 $ git clone https://github.com/emscripten-core/emsdk.git
  16 $ cd emsdk
  17
  18 # Download and install the latest SDK tools:
  19 $ ./emsdk install latest
  20
  21 # Make the "latest" SDK "active" for the current user:
  22 $ ./emsdk activate latest
  23 ```
  24
  25 Those parts only need to be run once. The following needs to be run for each
  26 shell instance which needs the `emcc` compiler:
  27
  28 ```
  29 # Activate PATH and other environment variables in the current terminal:
  30 $ source ./emsdk_env.sh
  31
  32 $ which emcc
  33 /path/to/emsdk/upstream/emscripten/emcc
  34 ```
  35
  36 That `env` script needs to be sourced for building this application from the
  37 top of the sqlite3 build tree:
  38
  39 ```
  40 $ make fiddle
  41 ```
  42
  43 Or:
  44
  45 ```
  46 $ cd ext/fiddle
  47 $ make
  48 ```
  49
  50 That will generate the fiddle application under
  51 [ext/fiddle](/dir/ext/fiddle), as `fiddle.html`. That application
  52 cannot, due to XMLHttpRequest security limitations, run if the HTML
  53 file is opened directly in the browser (i.e. if it is opened using a
  54 `file://` URL), so it needs to be served via an HTTP server.  For
  55 example, using [althttpd][]:
  56
  57 ```
  58 $ cd ext/fiddle
  59 $ althttpd -debug 1 -jail 0 -port 9090 -root .
  60 ```
  61
  62 Then browse to `http://localhost:9090/fiddle.html`.
  63
  64 Note that when serving this app via [althttpd][], it must be a version
  65 from 2022-05-17 or newer so that it recognizes the `.wasm` file
  66 extension and responds with the mimetype `application/wasm`, as the
  67 WASM loader is pedantic about that detail.
  68
  69 # Known Quirks and Limitations
  70
  71 Some "impedence mismatch" between C and WASM/JavaScript is to be
  72 expected.
  73
  74 ## No I/O
  75
  76 sqlite3 shell commands which require file I/O or pipes are disabled in
  77 the WASM build.
  78
  79 ## `exit()` Triggered from C
  80
  81 When C code calls `exit()`, as happens (for example) when running an
  82 "unsafe" command when safe mode is active, WASM's connection to the
  83 sqlite3 shell environment has no sensible choice but to shut down
  84 because `exit()` leaves it in a state we can no longer recover
  85 from. The JavaScript-side application attempts to recognize this and
  86 warn the user that restarting the application is necessary. Currently
  87 the only way to restart it is to reload the page. Restructuring the
  88 shell code such that it could be "rebooted" without restarting the
  89 JS app would require some invasive changes which are not currently
  90 on any TODO list but have not been entirely ruled out long-term.
  91
  92
  93 [emscripten]: https://emscripten.org
  94 [althttpd]: https://sqlite.org/althttpd