sqlite/ext/wasm
stephan a525d635a9 Minor doc cleanups in SQLTester.mjs and confirm that the tests pass with both OPFS VFSes.
FossilOrigin-Name: ac747d57c2a26b47644bca2a9b191b09f5180f6872dce9c3261c370a18c848a2
2024-10-18 23:54:23 +00:00
..
api Ensure that the OPFS VFS's xOpen() writes back the read-only flag to the output flags. Resolves the problem reported in [forum:cf37d5ff1182c31081 | forum post cf37d5ff1182c31081]. 2024-10-17 12:14:34 +00:00
common Doc updates in JS code. No functional changes. 2024-06-12 12:17:03 +00:00
fiddle Fix fiddle build broken by recent build-level reworks. Remove a stale reference to an old CSS file. 2024-09-27 23:45:40 +00:00
jaccwabyt Minor doc touchup in the JS bits. 2023-12-29 04:29:07 +00:00
sql Minor cleanups in OO API #1. Add Sudoku SQL to batch-runner.js's list. 2022-09-05 13:24:08 +00:00
SQLTester Minor doc cleanups in SQLTester.mjs and confirm that the tests pass with both OPFS VFSes. 2024-10-18 23:54:23 +00:00
tests/opfs/concurrency Add several convenience links to the OPFS VFS concurrency tester app for launching it with various combinations of options. 2024-07-13 01:40:36 +00:00
batch-runner-sahpool.html Add a basic batch-mode SQL runner for the SAH Pool VFS, for use in comparing it against WebSQL. Bring the WebSQL batch runner up to date, noting that it cannot run without addition of an "origin trial" activation key from Google because that's now the only way to enable WebSQL in Chrome (that part is not checked in because that key is private). Minor code-adjacent cleanups. 2023-11-30 20:34:24 +00:00
batch-runner-sahpool.js Add a basic batch-mode SQL runner for the SAH Pool VFS, for use in comparing it against WebSQL. Bring the WebSQL batch runner up to date, noting that it cannot run without addition of an "origin trial" activation key from Google because that's now the only way to enable WebSQL in Chrome (that part is not checked in because that key is private). Minor code-adjacent cleanups. 2023-11-30 20:34:24 +00:00
batch-runner.html Apply considerable acrobatics to get the JS/WASM deliverables building to and loadable from a directory other than the one which contains the app-level code. Requires an only-slightly-leaky abstraction of passing a URL argument when loading sqlite3.js but provides much greater flexibility in where the JS/WASM files are located. 2022-10-19 04:44:58 +00:00
batch-runner.js Add a basic batch-mode SQL runner for the SAH Pool VFS, for use in comparing it against WebSQL. Bring the WebSQL batch runner up to date, noting that it cannot run without addition of an "origin trial" activation key from Google because that's now the only way to enable WebSQL in Chrome (that part is not checked in because that key is private). Minor code-adjacent cleanups. 2023-11-30 20:34:24 +00:00
c-pp.c Further wasm build cleanups and tweaks. No functional changes. 2024-09-24 00:31:08 +00:00
demo-123-worker.html Apply considerable acrobatics to get the JS/WASM deliverables building to and loadable from a directory other than the one which contains the app-level code. Requires an only-slightly-leaky abstraction of passing a URL argument when loading sqlite3.js but provides much greater flexibility in where the JS/WASM files are located. 2022-10-19 04:44:58 +00:00
demo-123.html Apply considerable acrobatics to get the JS/WASM deliverables building to and loadable from a directory other than the one which contains the app-level code. Requires an only-slightly-leaky abstraction of passing a URL argument when loading sqlite3.js but provides much greater flexibility in where the JS/WASM files are located. 2022-10-19 04:44:58 +00:00
demo-123.js Add a basic batch-mode SQL runner for the SAH Pool VFS, for use in comparing it against WebSQL. Bring the WebSQL batch runner up to date, noting that it cannot run without addition of an "origin trial" activation key from Google because that's now the only way to enable WebSQL in Chrome (that part is not checked in because that key is private). Minor code-adjacent cleanups. 2023-11-30 20:34:24 +00:00
demo-jsstorage.html Rename several demo/test files and include more of them in the end-user dist archive. 2022-10-19 07:34:36 +00:00
demo-jsstorage.js Move the sqlite3.capi.wasm namespace to sqlite3.wasm. This causes a tiny bit of naming confusion with the sqlite3.wasm *file*, but seems to make more sense than having it as a sub-namespace of capi. 2022-10-29 07:54:10 +00:00
demo-worker1-promiser.c-pp.html Resolve duplicate loading of promiser v2 demo code (a side effect of having done precisely what it was told to do). Consolidate demo-worker1-promiser(-esm).html/(m)js variants into central copies processed with c-pp. 2024-03-07 18:53:27 +00:00
demo-worker1-promiser.c-pp.js Resolve duplicate loading of promiser v2 demo code (a side effect of having done precisely what it was told to do). Consolidate demo-worker1-promiser(-esm).html/(m)js variants into central copies processed with c-pp. 2024-03-07 18:53:27 +00:00
demo-worker1.html Rename several demo/test files and include more of them in the end-user dist archive. 2022-10-19 07:34:36 +00:00
demo-worker1.js Minor cleanups in demo JS code, per forum feedback. 2023-05-23 19:11:42 +00:00
dist.make When running the 'dist' target in ext/wasm for an SEE-capable build, ensure that the resulting zip file and directory name include '-see'. 2024-04-23 05:38:49 +00:00
example_extra_init.c Minor doc tweak for the previous commit. 2023-02-27 07:23:54 +00:00
EXPORTED_FUNCTIONS.fiddle.in Fiddle: replace db export routine with a C-side one which works for both Emscripten FS-hosted and OPFS-hosted db files. Minor code-adjacent cleanups. 2022-09-26 13:55:10 +00:00
fiddle.make wasm: move the makefile-eval-generated fiddle rules into mkwasmbuilds.c. Squelch some warnings from grep when running 'make clean' on a clean tree. 2024-09-28 12:01:10 +00:00
GNUmakefile Remove the unused dbfuzz2-asan/msan makefile targets. Fix a comment typo in a makefile. 2024-10-18 16:50:29 +00:00
index-dist.html wasm promiser.v2 is essentially working but the demo code is double-loading the module for as-yet-undetermined reasons. 2024-03-07 17:56:08 +00:00
index.html Minor wasmfs speedtest1 build tweaks. Disable one wasmfs demo which was broken by Emscripten-side changes. 2024-09-24 21:54:37 +00:00
mkwasmbuilds.c wasm: move the makefile-eval-generated fiddle rules into mkwasmbuilds.c. Squelch some warnings from grep when running 'make clean' on a clean tree. 2024-09-28 12:01:10 +00:00
module-symbols.html Add a doc link for the new sqlite3_js_posix_create_file(). 2023-08-11 17:45:23 +00:00
README-dist.txt Correct the handling of the worker1 and promiser JS files in the face of the bundler-friendly changes. Those files require separate, bundler-friendly copies. 2023-01-29 05:09:39 +00:00
README.md Correct a recently-introduced falsehood in ext/wasm/README.md regarding ssh port forwarding. 2023-07-28 11:52:58 +00:00
scratchpad-wasmfs.html More work on the wasmfs build and its test apps. 2023-07-13 17:27:05 +00:00
scratchpad-wasmfs.mjs More work on the wasmfs build and its test apps. 2023-07-13 17:27:05 +00:00
speedtest1-wasmfs.html Minor wasm build cleanups. 2023-07-14 12:21:05 +00:00
speedtest1-wasmfs.mjs wasm: replace much of the eval makefile spaghetti with equivalent code generated from a small C app. It turns out that's easier to read and write than doing the same thing from shell or tcl code, due entirely to C's lack of need for escaping dollar signs. 2024-09-23 21:22:09 +00:00
speedtest1-worker.html Add a basic batch-mode SQL runner for the SAH Pool VFS, for use in comparing it against WebSQL. Bring the WebSQL batch runner up to date, noting that it cannot run without addition of an "origin trial" activation key from Google because that's now the only way to enable WebSQL in Chrome (that part is not checked in because that key is private). Minor code-adjacent cleanups. 2023-11-30 20:34:24 +00:00
speedtest1-worker.js Make explicit which JS APIs are for internal use only by moving the JS-bound internal-use-only functions out of client-visible reach and renaming the WASM-exported ones from sqlite3_wasm... to sqlite3__wasm... (with two underscores). These have always been documented as internal-use-only, so this is not a breaking change except for clients which have ignored the docs. 2024-01-08 07:52:47 +00:00
speedtest1.html Remove some dead JS code and tweak some docs. 2022-12-08 04:19:38 +00:00
split-speedtest1-script.sh batch-runner.js: move generated SQL files into ./sql and start adding hand-written ones (like the Mandelbrot) to that set. 2022-08-30 10:04:08 +00:00
test-opfs-vfs.html Apply considerable acrobatics to get the JS/WASM deliverables building to and loadable from a directory other than the one which contains the app-level code. Requires an only-slightly-leaky abstraction of passing a URL argument when loading sqlite3.js but provides much greater flexibility in where the JS/WASM files are located. 2022-10-19 04:44:58 +00:00
test-opfs-vfs.js Fix an exception misuse in test-opfs-vfs.js. 2023-11-15 11:31:49 +00:00
tester1-worker.html sqlite3.oo1.Stmt.finalize() now throws if sqlite3_finalize() returns non-zero. This is intended to address the INSERT RETURNING case covered in [forum:36f7a2e7494897df|forum post 36f7a2e7494897df]. 2023-05-19 15:54:41 +00:00
tester1.c-pp.html Add JS bundler-friendly JS build. Minor test code cleanups. 2023-01-28 04:20:46 +00:00
tester1.c-pp.js Ensure that the OPFS VFS's xOpen() writes back the read-only flag to the output flags. Resolves the problem reported in [forum:cf37d5ff1182c31081 | forum post cf37d5ff1182c31081]. 2024-10-17 12:14:34 +00:00
wasmfs.make Minor makefile doc fixes. No functional changes. 2024-09-28 00:39:19 +00:00

This directory houses the Web Assembly (WASM) parts of the sqlite3 build.

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:
$ sudo apt install git
$ 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, but the SDK can be updated using:

$ git pull
$ ./emsdk install latest
$ ./emsdk activate latest

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

Optionally, add that to your login shell's resource file (~/.bashrc or equivalent).

That env script needs to be sourced for building this application from the top of the sqlite3 build tree:

$ make fiddle

Or:

$ cd ext/wasm
$ make

That will generate the a number of files required for a handful of test and demo applications which can be accessed via index.html. WASM content cannot, due to XMLHttpRequest security limitations, be loaded if the containing 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/wasm
$ althttpd --enable-sab --max-age 1 --page index.html

That will open the system's browser and run the index page, from which all of the test and demo applications can be accessed.

Note that when serving this app via althttpd, it must be a version from 2022-09-26 or newer so that it recognizes the --enable-sab flag, which causes althttpd to emit two HTTP response headers which are required to enable JavaScript's SharedArrayBuffer and Atomics APIs. Those APIs are required in order to enable the OPFS-related features in the apps which use them.

Testing on a remote machine that is accessed via SSH

NB: The following are developer notes, last validated on 2023-07-19

  • Remote: Install git, emsdk, and althttpd
  • Remote: Install the SQLite source tree. CD to ext/wasm
  • Remote: "make" to build WASM
  • Remote: althttpd --enable-sab --port 8080 --popup
  • Local: ssh -L 8180:localhost:8080 remote
  • Local: Point your web-browser at http://localhost:8180/index.html

In order to enable SharedArrayBuffer, the web-browser requires that the two extra Cross-Origin lines be present in HTTP reply headers and that the request must come from "localhost" (or over an SSL connection). Since the web-server is on a different machine from the web-broser, the localhost requirement means that the connection must be tunneled using SSH.