Wasm-related doc additions and tweaks.

FossilOrigin-Name: ec55a3aa44a80f661dd451b9ea567449ea4c7353901cfd44a4b50ca10f00ddbd

Makefile.in

@@ -1524,6 +1524,11 @@ sqlite3.dll: $(REAL_LIBOBJ) sqlite3.def
 #
 # fiddle/wasm section
 #
+# Maintenance reminder: we can/should move this into the wasm-specific
+# GNU Make makefile, but we currently need it here for access to
+# $(SHELL_OPT). The rest of the wasm-related bits are handled via GNU
+# Make in ext/wasm/...
+#
 wasm_dir = ext/wasm
 wasm_dir_abs = $(TOP)/ext/wasm
 # ^^^ some emcc opts require absolute paths

ext/wasm/api/README.md

@@ -0,0 +1,95 @@
+# sqlite3-api.js And Friends
+
+This is the README for the files `sqlite3-*.js`. This collection of
+files is used to build a single-file distribution of the sqlite3 WASM
+API. It is broken into multiple files because:
+
+1. To facilitate including or excluding certain components for
+   specific use cases. e.g. by removing `sqlite3-api-oo1.js` if the
+   OO#1 API is not needed.
+
+2. To facilitate modularizing the pieces for use in different WASM
+   build environments. e.g. the files `post-js-*.js` are for use with
+   Emscripten's `--post-js` feature, and nowhere else.
+
+3. Certain components must be in their own standalone files in order
+   to be loaded as JS Workers.
+
+Note that the structure described here is the current state of things,
+not necessarily the "final" state.
+
+The overall idea is that the following files get concatenated
+together, in the listed order, the resulting file is loaded by a
+browser client:
+
+- `post-js-header.js`\  
+  Emscripten-specific header for the `--post-js` input.
+- `sqlite3-api-prologue.js`\  
+  Contains the initial bootstrap setup of the sqlite3 API
+  objects. This is exposed as a function, rather than objects, so that
+  the next step can pass in a config object which abstracts away parts
+  of the WASM environment, to facilitate plugging it in to arbitrary
+  WASM toolchains.
+- `whwasmutil.js`\  
+  A semi-third-party collection of JS/WASM utility code intended to
+  replace much of the Emscripten glue. The sqlite3 APIs internally use
+  these APIs instead of their Emscripten counterparts, in order to be
+  more portable to arbitrary WASM toolchains. This API is
+  configurable, in principle, for use with arbitrary WASM
+  toolchains. It is "semi-third-party" in that it was created in order
+  to support this tree but is standalone and maintained together
+  with...
+- `jaccwabyt.js`\  
+  Another semi-third-party API which creates bindings between JS
+  and C structs, such that changes to the struct state from either JS
+  or C are visible to the other end of the connection. This is also an
+  independent spinoff project, conceived for the sqlite3 project but
+  maintained separately.
+- `sqlite3-api-glue.js`\  
+  Invokes the function exposed by `sqlite3-api-prologue.js`, passing
+  it a configuration object to configure it for the current WASM
+  toolchain (noting that it currently requires Emscripten), then
+  removes that function from the global scope. The result of this file
+  is a global-scope `sqlite3` object which acts as a namespace for the
+  API's functionality. This object gets removed from the global scope
+  after the following files have attached their own features to it.
+- `sqlite3-api-oo1.js`\  
+  Provides a high-level object-oriented wrapper to the lower-level C
+  API, colloquially known as OO API #1. Its API is similar to other
+  high-level sqlite3 JS wrappers and should feel relatively familiar
+  to anyone familiar with such APIs. That said, it is not a "required
+  component" and can be elided from builds which do not want it.
+- `sqlite3-api-worker.js`\  
+  A Worker-thread-based API which uses OO API #1 to provide an
+  interface to a database which can be driven from the main Window
+  thread via the Worker message-passing interface. Like OO API #1,
+  this is an optional component, offering one of any number of
+  potential implementations for such an API.
+    - `sqlite3-worker.js`\  
+      Is not part of the amalgamated sources and is intended to be
+      loaded by a client Worker thread. It loads the sqlite3 module
+      and runs the Worker API which is implemented in
+      `sqlite3-api-worker.js`.
+- `sqlite3-api-opfs.js`\  
+  is an in-development/experimental sqlite3 VFS wrapper, the goal of
+  which being to use Google Chrome's Origin-Private FileSystem (OPFS)
+  storage layer to provide persistent storage for database files in a
+  browser. It is far from complete.
+- `sqlite3-api-cleanup.js`\  
+  the previous files temporarily create global objects in order to
+  communicate their state to the files which follow them, and _this_
+  file connects any final components together and cleans up those
+  globals. As of this writing, this code ensures that the previous
+  files leave no global symbols installed, and it moves the sqlite3
+  namespace object into the in-scope Emscripten module. Abstracting
+  this for other WASM toolchains is TODO.
+- `post-js-footer.js`\  
+  Emscripten-specific footer for the `--post-js` input. This closes
+  off the lexical scope opened by `post-js-header.js`.
+
+The build process glues those files together, resulting in
+`sqlite3-api.js`, which is everything except for the `post-js-*.js`
+files, and `sqlite3.js`, which is the Emscripten-generated amalgamated
+output and includes the `post-js-*.js` parts, as well as the
+Emscripten-provided module loading pieces.
+

ext/wasm/api/sqlite3-api-worker.js

@@ -84,10 +84,9 @@ self.sqlite3.initWorkerAPI = function(){
   if('function' !== typeof importScripts){
     toss("Cannot initalize the sqlite3 worker API in the main thread.");
   }
-    /* This is a web worker, so init the worker-based API. */
   const self = this.self;
-  const sqlite3 = this.sqlite3 || toss("Missing self.sqlite3 object.");
-  const SQLite3 = sqlite3.oo1 || toss("Missing self.sqlite3.oo1 OO API.");
+  const sqlite3 = this.sqlite3 || toss("Missing this.sqlite3 object.");
+  const SQLite3 = sqlite3.oo1 || toss("Missing this.sqlite3.oo1 OO API.");
   const DB = SQLite3.DB;
 
   /**

manifest

@@ -1,9 +1,9 @@
-C Merge\sin\swasm-cleanups\sbranch,\sreorganizing\sand\supdating\sthe\swasm-related\scomponents.
-D 2022-08-11T09:18:09.465
+C Wasm-related\sdoc\sadditions\sand\stweaks.
+D 2022-08-11T15:45:32.290
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
-F Makefile.in 31f4141e5adc6f002296fc2c500803f460ca3e8b2cae53effeb021e74d7b29d7
+F Makefile.in eceb228bf7b48f961b59a508f42ffa1211bf0c4c5bc818807768cc7b187ab0c8
 F Makefile.linux-gcc f609543700659711fbd230eced1f01353117621dccae7b9fb70daa64236c5241
 F Makefile.msc d547a2fdba38a1c6cd1954977d0b0cc017f5f8fbfbc65287bf8d335808938016
 F README.md 8b8df9ca852aeac4864eb1e400002633ee6db84065bd01b78c33817f97d31f5e
@@ -472,39 +472,40 @@ F ext/session/test_session.c f433f68a8a8c64b0f5bc74dc725078f12483301ad4ae8375205
 F ext/userauth/sqlite3userauth.h 7f3ea8c4686db8e40b0a0e7a8e0b00fac13aa7a3
 F ext/userauth/user-auth.txt e6641021a9210364665fe625d067617d03f27b04
 F ext/userauth/userauth.c 7f00cded7dcaa5d47f54539b290a43d2e59f4b1eb5f447545fa865f002fc80cb
-F ext/wasm/EXPORTED_FUNCTIONS.fiddle 7fb73f7150ab79d83bb45a67d257553c905c78cd3d693101699243f36c5ae6c3 w ext/fiddle/EXPORTED_FUNCTIONS.fiddle
-F ext/wasm/EXPORTED_RUNTIME_METHODS.fiddle a004bd5eeeda6d3b28d16779b7f1a80305bfe009dfc7f0721b042967f0d39d02 w ext/fiddle/EXPORTED_RUNTIME_METHODS
-F ext/wasm/GNUmakefile 5359a37fc13b68fad2259228590450339a0c59687744edd0db7bb93d3b1ae2b1 w ext/fiddle/Makefile
-F ext/wasm/README.md 4b00ae7c7d93c4591251245f0996a319e2651361013c98d2efb0b026771b7331 w ext/fiddle/index.md
-F ext/wasm/api/EXPORTED_FUNCTIONS.sqlite3-api c5eaceabb9e759aaae7d3101a4a3e542f96ab2c99d89a80ce20ec18c23115f33 w ext/fiddle/EXPORTED_FUNCTIONS.sqlite3-api
+F ext/wasm/EXPORTED_FUNCTIONS.fiddle 7fb73f7150ab79d83bb45a67d257553c905c78cd3d693101699243f36c5ae6c3
+F ext/wasm/EXPORTED_RUNTIME_METHODS.fiddle a004bd5eeeda6d3b28d16779b7f1a80305bfe009dfc7f0721b042967f0d39d02
+F ext/wasm/GNUmakefile 5359a37fc13b68fad2259228590450339a0c59687744edd0db7bb93d3b1ae2b1
+F ext/wasm/README.md 4b00ae7c7d93c4591251245f0996a319e2651361013c98d2efb0b026771b7331
+F ext/wasm/api/EXPORTED_FUNCTIONS.sqlite3-api c5eaceabb9e759aaae7d3101a4a3e542f96ab2c99d89a80ce20ec18c23115f33
 F ext/wasm/api/EXPORTED_RUNTIME_METHODS.sqlite3-api 1ec3c73e7d66e95529c3c64ac3de2470b0e9e7fbf7a5b41261c367cf4f1b7287
+F ext/wasm/api/README.md 418939809469bf671fd715eabfe7e1a03fe83111f9dea93521436077da358274
 F ext/wasm/api/post-js-footer.js b64319261d920211b8700004d08b956a6c285f3b0bba81456260a713ed04900c
 F ext/wasm/api/post-js-header.js 0e853b78db83cb1c06b01663549e0e8b4f377f12f5a2d9a4a06cb776c003880b
 F ext/wasm/api/sqlite3-api-cleanup.js 149fd63a0400cd1d69548887ffde2ed89c13283384a63c2e9fcfc695e38a9e11
 F ext/wasm/api/sqlite3-api-glue.js 82c09f49c69984009ba5af2b628e67cc26c5dd203d383cd3091d40dab4e6514b
 F ext/wasm/api/sqlite3-api-oo1.js e9612cb704c0563c5d71ed2a8dccd95bf6394fa4de3115d1b978dc269c49ab02
 F ext/wasm/api/sqlite3-api-opfs.js a899a10b83f15cace5a449dd12d957b429d1d4eb31cdb10e6ee4c22c569ece77
-F ext/wasm/api/sqlite3-api-prologue.js 0fb0703d2d8ac89fa2d4dd8f9726b0ea226b8708ac34e5b482df046e147de0eb w ext/fiddle/sqlite3-api.js
-F ext/wasm/api/sqlite3-api-worker.js cae932a89e48730cd850ab280963a65a96cb8b4c58bacd54ba961991a3c32f51 w ext/fiddle/sqlite3-worker.js
+F ext/wasm/api/sqlite3-api-prologue.js 0fb0703d2d8ac89fa2d4dd8f9726b0ea226b8708ac34e5b482df046e147de0eb
+F ext/wasm/api/sqlite3-api-worker.js 8c5dd7b3aa8076690f49400777634161ffcb3674ebd4d3466180eea0a4499656
 F ext/wasm/api/sqlite3-wasi.h 25356084cfe0d40458a902afb465df8c21fc4152c1d0a59b563a3fba59a068f9
 F ext/wasm/api/sqlite3-wasm.c 827357635c356ca178ebfa1be5915afacb682043d27c4a230c194c1ace787be4
 F ext/wasm/api/sqlite3-worker.js 1325ca8d40129a82531902a3a077b795db2eeaee81746e5a0c811a04b415fa7f
-F ext/wasm/common/SqliteTestUtil.js e41a1406f18da9224523fad0c48885caf995b56956a5b9852909c0989e687e90 w ext/fiddle/SqliteTestUtil.js
+F ext/wasm/common/SqliteTestUtil.js e41a1406f18da9224523fad0c48885caf995b56956a5b9852909c0989e687e90
 F ext/wasm/common/emscripten.css 3d253a6fdb8983a2ac983855bfbdd4b6fa1ff267c28d69513dd6ef1f289ada3f
-F ext/wasm/common/testing.css 572cf1ffae0b6eb7ca63684d3392bf350217a07b90e7a896e4fa850700c989b0 w ext/fiddle/testing.css
+F ext/wasm/common/testing.css 572cf1ffae0b6eb7ca63684d3392bf350217a07b90e7a896e4fa850700c989b0
 F ext/wasm/common/whwasmutil.js 3d9deda1be718e2b10e2b6b474ba6ba857d905be314201ae5b3df5eef79f66aa
-F ext/wasm/fiddle/emscripten.css 3d253a6fdb8983a2ac983855bfbdd4b6fa1ff267c28d69513dd6ef1f289ada3f w ext/fiddle/emscripten.css
-F ext/wasm/fiddle/fiddle-worker.js 88bc2193a6cb6a3f04d8911bed50a4401fe6f277de7a71ba833865ab64a1b4ae w ext/fiddle/fiddle-worker.js
-F ext/wasm/fiddle/fiddle.html 550c5aafce40bd218de9bf26192749f69f9b10bc379423ecd2e162bcef885c08 w ext/fiddle/fiddle.html
-F ext/wasm/fiddle/fiddle.js 812f9954cc7c4b191884ad171f36fcf2d0112d0a7ecfdf6087896833a0c079a8 w ext/fiddle/fiddle.js
+F ext/wasm/fiddle/emscripten.css 3d253a6fdb8983a2ac983855bfbdd4b6fa1ff267c28d69513dd6ef1f289ada3f
+F ext/wasm/fiddle/fiddle-worker.js 88bc2193a6cb6a3f04d8911bed50a4401fe6f277de7a71ba833865ab64a1b4ae
+F ext/wasm/fiddle/fiddle.html 550c5aafce40bd218de9bf26192749f69f9b10bc379423ecd2e162bcef885c08
+F ext/wasm/fiddle/fiddle.js 812f9954cc7c4b191884ad171f36fcf2d0112d0a7ecfdf6087896833a0c079a8
 F ext/wasm/jaccwabyt/jaccwabyt.js 99b424b4d467d4544e82615b58e2fe07532a898540bf9de2a985f3c21e7082b2
 F ext/wasm/jaccwabyt/jaccwabyt.md 447cc02b598f7792edaa8ae6853a7847b8178a18ed356afacbdbf312b2588106
 F ext/wasm/jaccwabyt/jaccwabyt_test.c 39e4b865a33548f943e2eb9dd0dc8d619a80de05d5300668e9960fff30d0d36f
 F ext/wasm/jaccwabyt/jaccwabyt_test.exports 5ff001ef975c426ffe88d7d8a6e96ec725e568d2c2307c416902059339c06f19
-F ext/wasm/testing1.html 0bf3ff224628c1f1e3ed22a2dc1837c6c73722ad8c0ad9c8e6fb9e6047667231 w ext/fiddle/testing1.html
-F ext/wasm/testing1.js aef553114aada187eef125f5361fd1e58bf5e8e97acfa65c10cb41dd60295daa w ext/fiddle/testing1.js
-F ext/wasm/testing2.html 73e5048e666fd6fb28b6e635677a9810e1e139c599ddcf28d687c982134b92b8 w ext/fiddle/testing2.html
-F ext/wasm/testing2.js d37433c601f88ed275712c1cfc92d3fb36c7c22e1ed8c7396fb2359e42238ebc w ext/fiddle/testing2.js
+F ext/wasm/testing1.html 0bf3ff224628c1f1e3ed22a2dc1837c6c73722ad8c0ad9c8e6fb9e6047667231
+F ext/wasm/testing1.js aef553114aada187eef125f5361fd1e58bf5e8e97acfa65c10cb41dd60295daa
+F ext/wasm/testing2.html 73e5048e666fd6fb28b6e635677a9810e1e139c599ddcf28d687c982134b92b8
+F ext/wasm/testing2.js d37433c601f88ed275712c1cfc92d3fb36c7c22e1ed8c7396fb2359e42238ebc
 F install-sh 9d4de14ab9fb0facae2f48780b874848cbf2f895 x
 F ltmain.sh 3ff0879076df340d2e23ae905484d8c15d5fdea8
 F magic.txt 8273bf49ba3b0c8559cb2774495390c31fd61c60
@@ -1998,9 +1999,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P bb084adb53386d8e52ca1e818a8322d2ec641b73fd8568cee01cc74c0ee9f265 683a3b937e608a5ecaf7f63f054e8a63179d67c8b2348bf843e5e68f27a369f5
-R 4ba76f10a568f2d09e4030f5a10b07d7
-T +closed 683a3b937e608a5ecaf7f63f054e8a63179d67c8b2348bf843e5e68f27a369f5 Closed\sby\sintegrate-merge.
+P c072594d3de3d6893c5d4a9d68439b84d043325f105b0d065575765a6e66c196
+R 10881e70503a9a9d9b0dab671ab8c767
 U stephan
-Z 747d196ca566e8555d460e3b390787ac
+Z a38a9d9f317cfa8025ab6574aa1c9e88
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-c072594d3de3d6893c5d4a9d68439b84d043325f105b0d065575765a6e66c196
+ec55a3aa44a80f661dd451b9ea567449ea4c7353901cfd44a4b50ca10f00ddbd