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-vfs-helper.js`**\
  82   Installs the `sqlite3.vfs` namespace, which contain helpers for use
  83   by downstream code which creates `sqlite3_vfs` implementations.
  84 - **`sqlite3-vtab-helper.js`**\
  85   Installs the `sqlite3.vtab` namespace, which contain helpers for use
  86   by downstream code which creates `sqlite3_module` implementations.
  87 - **`sqlite3-vfs-opfs.c-pp.js`**\
  88   is an sqlite3 VFS implementation which supports the Origin-Private
  89   FileSystem (OPFS) as a storage layer to provide persistent storage
  90   for database files in a browser. It requires...
  91     - **`sqlite3-opfs-async-proxy.js`**\
  92       is the asynchronous backend part of the OPFS proxy. It speaks
  93       directly to the (async) OPFS API and channels those results back
  94       to its synchronous counterpart. This file, because it must be
  95       started in its own Worker, is not part of the amalgamation.
  96 - **`sqlite3-vfs-opfs-sahpool.c-pp.js`**\
  97   is another sqlite3 VFS supporting the OPFS, but uses a completely
  98   different approach that the above-listed one.
  99 - **`sqlite3-api-cleanup.js`**\
 100   The previous files do not immediately extend the library. Instead
 101   they add callback functions to be called during its
 102   bootstrapping. Some also temporarily create global objects in order
 103   to communicate their state to the files which follow them. This file
 104   cleans up any dangling globals and runs the API bootstrapping
 105   process, which is what finally executes the initialization code
 106   installed by the previous files. As of this writing, this code
 107   ensures that the previous files leave no more than a single global
 108   symbol installed. When adapting the API for non-Emscripten
 109   toolchains, this "should" be the only file where changes are needed.
 110
 111
 112 **Files with the extension `.c-pp.js`** are intended [to be processed
 113 with `c-pp`](#c-pp), noting that such preprocessing may be applied
 114 after all of the relevant files are concatenated. That extension is
 115 used primarily to keep the code maintainers cognisant of the fact that
 116 those files contain constructs which may not run as-is in any given
 117 JavaScript environment.
 118
 119 The build process glues those files together, resulting in
 120 `sqlite3-api.js`, which is everything except for the
 121 `pre/post-js-*.js` files, and `sqlite3.js`, which is the
 122 Emscripten-generated amalgamated output and includes the
 123 `pre/post-js-*.js` parts, as well as the Emscripten-provided module
 124 loading pieces.
 125
 126 The non-JS outlier file is `sqlite3-wasm.c`: it is a proxy for
 127 `sqlite3.c` which `#include`'s that file and adds a couple more
 128 WASM-specific helper functions, at least one of which requires access
 129 to private/static `sqlite3.c` internals. `sqlite3.wasm` is compiled
 130 from this file rather than `sqlite3.c`.
 131
 132 The following files are part of the build process but are injected
 133 into the build-generated `sqlite3.js` along with `sqlite3-api.js`.
 134
 135 - `extern-pre-js.js`\
 136   Emscripten-specific header for Emscripten's `--extern-pre-js`
 137   flag. As of this writing, that file is only used for experimentation
 138   purposes and holds no code relevant to the production deliverables.
 139 - `pre-js.c-pp.js`\
 140   Emscripten-specific header for Emscripten's `--pre-js` flag. This
 141   file is intended as a place to override certain Emscripten behavior
 142   before it starts up, but corner-case Emscripten bugs keep that from
 143   being a reality.
 144 - `post-js-header.js`\
 145   Emscripten-specific header for the `--post-js` input. It opens up
 146   a lexical scope by starting a post-run handler for Emscripten.
 147 - `post-js-footer.js`\
 148   Emscripten-specific footer for the `--post-js` input. This closes
 149   off the lexical scope opened by `post-js-header.js`.
 150 - `extern-post-js.c-pp.js`\
 151   Emscripten-specific header for Emscripten's `--extern-post-js`
 152   flag. This file overwrites the Emscripten-installed
 153   `sqlite3InitModule()` function with one which, after the module is
 154   loaded, also initializes the asynchronous parts of the sqlite3
 155   module. For example, the OPFS VFS support.
 156
 157 <a id='c-pp'></a>
 158 Preprocessing of Source Files
 159 ------------------------------------------------------------------------
 160
 161 Certain files in the build require preprocessing to filter in/out
 162 parts which differ between vanilla JS, ES6 Modules, and node.js
 163 builds. The preprocessor application itself is in
 164 [`c-pp.c`](/file/ext/wasm/c-pp.c) and the complete technical details
 165 of such preprocessing are maintained in
 166 [`GNUMakefile`](/file/ext/wasm/GNUmakefile).