ext/wasm/api/README.md

   1 # sqlite3-api.js And Friends
   2
   3 This is the README for the files `sqlite3-*.js` and
   4 `sqlite3-wasm.c`. This collection of files is used to build a
   5 single-file distribution of the sqlite3 WASM API. It is broken into
   6 multiple JS files because:
   7
   8 1. To facilitate including or excluding certain components for
   9    specific use cases. e.g. by removing `sqlite3-api-oo1.js` if the
  10    OO#1 API is not needed.
  11
  12 2. To facilitate modularizing the pieces for use in different WASM
  13    build environments. e.g. the files `post-js-*.js` are for use with
  14    Emscripten's `--post-js` feature, and nowhere else.
  15
  16 3. Certain components must be in their own standalone files in order
  17    to be loaded as JS Workers.
  18
  19 Note that the structure described here is the current state of things,
  20 as of this writing, but is not set in stone forever and may change
  21 at any time.
  22
  23 The overall idea is that the following files get concatenated
  24 together, in the listed order, the resulting file is loaded by a
  25 browser client:
  26
  27 - **`sqlite3-api-prologue.js`**\
  28   Contains the initial bootstrap setup of the sqlite3 API
  29   objects. This is exposed as a function, rather than objects, so that
  30   the next step can pass in a config object which abstracts away parts
  31   of the WASM environment, to facilitate plugging it in to arbitrary
  32   WASM toolchains.
  33 - **`../common/whwasmutil.js`**\
  34   A semi-third-party collection of JS/WASM utility code intended to
  35   replace much of the Emscripten glue. The sqlite3 APIs internally use
  36   these APIs instead of their Emscripten counterparts, in order to be
  37   more portable to arbitrary WASM toolchains. This API is
  38   configurable, in principle, for use with arbitrary WASM
  39   toolchains. It is "semi-third-party" in that it was created in order
  40   to support this tree but is standalone and maintained together
  41   with...
  42 - **`../jaccwabyt/jaccwabyt.js`**\
  43   Another semi-third-party API which creates bindings between JS
  44   and C structs, such that changes to the struct state from either JS
  45   or C are visible to the other end of the connection. This is also an
  46   independent spinoff project, conceived for the sqlite3 project but
  47   maintained separately.
  48 - **`sqlite3-api-glue.js`**\
  49   Invokes functionality exposed by the previous two files to flesh out
  50   low-level parts of `sqlite3-api-prologue.js`. Most of these pieces
  51   related to populating the `sqlite3.capi.wasm` object. This file
  52   also deletes most global-scope symbols the above files create,
  53   effectively moving them into the scope being used for initializing
  54   the API.
  55 - **`<build>/sqlite3-api-build-version.js`**\
  56   Gets created by the build process and populates the
  57   `sqlite3.version` object. This part is not critical, but records the
  58   version of the library against which this module was built.
  59 - **`sqlite3-api-oo1.js`**\
  60   Provides a high-level object-oriented wrapper to the lower-level C
  61   API, colloquially known as OO API #1. Its API is similar to other
  62   high-level sqlite3 JS wrappers and should feel relatively familiar
  63   to anyone familiar with such APIs. That said, it is not a "required
  64   component" and can be elided from builds which do not want it.
  65 - **`sqlite3-api-worker1.js`**\
  66   A Worker-thread-based API which uses OO API #1 to provide an
  67   interface to a database which can be driven from the main Window
  68   thread via the Worker message-passing interface. Like OO API #1,
  69   this is an optional component, offering one of any number of
  70   potential implementations for such an API.
  71     - **`sqlite3-worker1.js`**\
  72       Is not part of the amalgamated sources and is intended to be
  73       loaded by a client Worker thread. It loads the sqlite3 module
  74       and runs the Worker #1 API which is implemented in
  75       `sqlite3-api-worker1.js`.
  76     - **`sqlite3-worker1-promiser.js`**\
  77       Is likewise not part of the amalgamated sources and provides
  78       a Promise-based interface into the Worker #1 API. This is
  79       a far user-friendlier way to interface with databases running
  80       in a Worker thread.
  81 - **`sqlite3-v-helper.js`**\
  82   Installs `sqlite3.vfs` and `sqlite3.vtab`, namespaces which contain
  83   helpers for use by downstream code which creates `sqlite3_vfs`
  84   and `sqlite3_module` implementations.
  85 - **`sqlite3-vfs-opfs.c-pp.js`**\
  86   is an sqlite3 VFS implementation which supports Google Chrome's
  87   Origin-Private FileSystem (OPFS) as a storage layer to provide
  88   persistent storage for database files in a browser. It requires...
  89     - **`sqlite3-opfs-async-proxy.js`**\
  90       is the asynchronous backend part of the OPFS proxy. It speaks
  91       directly to the (async) OPFS API and channels those results back
  92       to its synchronous counterpart. This file, because it must be
  93       started in its own Worker, is not part of the amalgamation.
  94 - **`api/sqlite3-api-cleanup.js`**\
  95   The previous files do not immediately extend the library. Instead
  96   they add callback functions to be called during its
  97   bootstrapping. Some also temporarily create global objects in order
  98   to communicate their state to the files which follow them. This file
  99   cleans up any dangling globals and runs the API bootstrapping
 100   process, which is what finally executes the initialization code
 101   installed by the previous files. As of this writing, this code
 102   ensures that the previous files leave no more than a single global
 103   symbol installed. When adapting the API for non-Emscripten
 104   toolchains, this "should" be the only file where changes are needed.
 105
 106
 107 **Files with the extension `.c-pp.js`** are intended [to be processed
 108 with `c-pp`](#c-pp), noting that such preprocessing may be applied
 109 after all of the relevant files are concatenated. That extension is
 110 used primarily to keep the code maintainers cognisant of the fact that
 111 those files contain constructs which will not run as-is in JavaScript.
 112
 113 The build process glues those files together, resulting in
 114 `sqlite3-api.js`, which is everything except for the `post-js-*.js`
 115 files, and `sqlite3.js`, which is the Emscripten-generated amalgamated
 116 output and includes the `post-js-*.js` parts, as well as the
 117 Emscripten-provided module loading pieces.
 118
 119 The non-JS outlier file is `sqlite3-wasm.c`: it is a proxy for
 120 `sqlite3.c` which `#include`'s that file and adds a couple more
 121 WASM-specific helper functions, at least one of which requires access
 122 to private/static `sqlite3.c` internals. `sqlite3.wasm` is compiled
 123 from this file rather than `sqlite3.c`.
 124
 125 The following files are part of the build process but are injected
 126 into the build-generated `sqlite3.js` along with `sqlite3-api.js`.
 127
 128 - `extern-pre-js.js`\
 129   Emscripten-specific header for Emscripten's `--extern-pre-js`
 130   flag. As of this writing, that file is only used for experimentation
 131   purposes and holds no code relevant to the production deliverables.
 132 - `pre-js.c-pp.js`\
 133   Emscripten-specific header for Emscripten's `--pre-js` flag. This
 134   file is intended as a place to override certain Emscripten behavior
 135   before it starts up, but corner-case Emscripten bugs keep that from
 136   being a reality.
 137 - `post-js-header.js`\
 138   Emscripten-specific header for the `--post-js` input. It opens up
 139   a lexical scope by starting a post-run handler for Emscripten.
 140 - `post-js-footer.js`\
 141   Emscripten-specific footer for the `--post-js` input. This closes
 142   off the lexical scope opened by `post-js-header.js`.
 143 - `extern-post-js.c-pp.js`\
 144   Emscripten-specific header for Emscripten's `--extern-post-js`
 145   flag. This file overwrites the Emscripten-installed
 146   `sqlite3InitModule()` function with one which, after the module is
 147   loaded, also initializes the asynchronous parts of the sqlite3
 148   module. For example, the OPFS VFS support.
 149
 150 <a id='c-pp'></a>
 151 Preprocessing of Source Files
 152 ------------------------------------------------------------------------
 153
 154 Certain files in the build require preprocessing to filter in/out
 155 parts which differ between vanilla JS builds and ES6 Module
 156 (a.k.a. esm) builds. The preprocessor application itself is in
 157 [`c-pp.c`](/file/ext/wasm/c-pp.c) and the complete technical details
 158 of such preprocessing are maintained in
 159 [`GNUMakefile`](/file/ext/wasm/GNUmakefile).