Rename some JS files from X.js to X.c-pp.js to keep the maintainer, and downstream build customizers, aware that those files contain constructs specific to the c-pp preprocessor and will not run as-is in JS.

FossilOrigin-Name: 2eade7c7b17a186735c72974c11a34798a08364861d0f307e897ba765c0a93c7

ext/wasm/GNUmakefile

@@ -279,8 +279,8 @@ sqlite3-license-version-header.js := $(dir.api)/sqlite3-license-version-header.j
 # sqlite3-api-build-version.js = generated JS file which populates the
 # sqlite3.version object using $(bin.version-info).
 sqlite3-api-build-version.js := $(dir.tmp)/sqlite3-api-build-version.js
-# sqlite3-api.jses = the list of JS files which make up $(sqlite3-api.js), in
-# the order they need to be assembled.
+# sqlite3-api.jses = the list of JS files which make up
+# $(sqlite3-api.js.in), in the order they need to be assembled.
 sqlite3-api.jses := $(sqlite3-license-version.js)
 sqlite3-api.jses += $(dir.api)/sqlite3-api-prologue.js
 sqlite3-api.jses += $(dir.common)/whwasmutil.js
@@ -290,7 +290,7 @@ sqlite3-api.jses += $(sqlite3-api-build-version.js)
 sqlite3-api.jses += $(dir.api)/sqlite3-api-oo1.js
 sqlite3-api.jses += $(dir.api)/sqlite3-api-worker1.js
 sqlite3-api.jses += $(dir.api)/sqlite3-vfs-helper.js
-sqlite3-api.jses += $(dir.api)/sqlite3-vfs-opfs.js
+sqlite3-api.jses += $(dir.api)/sqlite3-vfs-opfs.c-pp.js
 sqlite3-api.jses += $(dir.api)/sqlite3-api-cleanup.js
 
 # "External" API files which are part of our distribution
@@ -346,12 +346,12 @@ $(sqlite3-license-version.js): $(sqlite3.h) $(sqlite3-license-version-header.js)
 # --post-js and --pre-js are emcc flags we use to append/prepend JS to
 # the generated emscripten module file. The following rules generate
 # various versions of those files for the vanilla and ESM builds.
-pre-js.js.in := $(dir.api)/pre-js.js
+pre-js.js.in := $(dir.api)/pre-js.c-pp.js
 pre-js.js.esm := $(dir.tmp)/pre-js.esm.js
 pre-js.js.vanilla := $(dir.tmp)/pre-js.vanilla.js
 $(eval $(call C-PP.FILTER,$(pre-js.js.in),$(pre-js.js.vanilla),$(c-pp.D.vanilla)))
 $(eval $(call C-PP.FILTER,$(pre-js.js.in),$(pre-js.js.esm),$(c-pp.D.esm)))
-post-js.js.in := $(dir.tmp)/post-js.js
+post-js.js.in := $(dir.tmp)/post-js.c-pp.js
 post-js.js.vanilla := $(dir.tmp)/post-js.vanilla.js
 post-js.js.esm := $(dir.tmp)/post-js.esm.js
 post-jses.js := \
@@ -371,7 +371,7 @@ $(eval $(call C-PP.FILTER,$(post-js.js.in),$(post-js.js.esm),$(c-pp.D.esm)))
 # extern-post-js* and extern-pre-js* are files for use with
 # Emscripten's --extern-pre-js and --extern-post-js flags.  These
 # rules make different copies for the vanilla and ESM builds.
-extern-post-js.js.in := $(dir.api)/extern-post-js.js
+extern-post-js.js.in := $(dir.api)/extern-post-js.c-pp.js
 extern-post-js.js.vanilla := $(dir.tmp)/extern-post-js.vanilla.js
 extern-post-js.js.esm := $(dir.tmp)/extern-post-js.esm.js
 $(eval $(call C-PP.FILTER,$(extern-post-js.js.in),$(extern-post-js.js.vanilla),$(c-pp.D.vanilla)))

ext/wasm/api/README.md

@@ -17,7 +17,8 @@ multiple JS files because:
    to be loaded as JS Workers.
 
 Note that the structure described here is the current state of things,
-not necessarily the "final" state.
+as of this writing, but is not set in stone forever and may change
+at any time.
 
 The overall idea is that the following files get concatenated
 together, in the listed order, the resulting file is loaded by a
@@ -45,10 +46,13 @@ browser client:
   independent spinoff project, conceived for the sqlite3 project but
   maintained separately.
 - **`sqlite3-api-glue.js`**\  
-  Invokes functionality exposed by the previous two files to
-  flesh out low-level parts of `sqlite3-api-prologue.js`. Most of
-  these pieces related to the `sqlite3.capi.wasm` object.
-- **`sqlite3-api-build-version.js`**\  
+  Invokes functionality exposed by the previous two files to flesh out
+  low-level parts of `sqlite3-api-prologue.js`. Most of these pieces
+  related to populating the `sqlite3.capi.wasm` object. This file
+  also deletes most global-scope symbols the above files create,
+  effectively moving them into the scope being used for initializing
+  the API.
+- **`<build>/sqlite3-api-build-version.js`**\  
   Gets created by the build process and populates the
   `sqlite3.version` object. This part is not critical, but records the
   version of the library against which this module was built.
@@ -76,10 +80,10 @@ browser client:
       in a Worker thread.
 - **`sqlite3-vfs-helper.js`**\  
   This internal-use-only file installs `sqlite3.VfsHelper` for use by
-  `sqlite3-*.js` files which create `sqlite3_vfs` implemenations.
+  `sqlite3-*.js` files which create `sqlite3_vfs` implementations.
   `sqlite3.VfsHelper` gets removed from the the `sqlite3` object after
   the library is finished initializing.
-- **`sqlite3-vfs-opfs.js`**\  
+- **`sqlite3-vfs-opfs.c-pp.js`**\  
   is an sqlite3 VFS implementation which supports Google Chrome's
   Origin-Private FileSystem (OPFS) as a storage layer to provide
   persistent storage for database files in a browser. It requires...
@@ -100,6 +104,13 @@ browser client:
   symbol installed. When adapting the API for non-Emscripten
   toolchains, this "should" be the only file where changes are needed.
 
+
+**Files with the extension `.c-pp.js`** are intended [to be processed
+with `c-pp`](#c-pp), noting that such preprocessing may be applied
+after all of the relevant files are concatenated. That extension is
+used primarily to keep the code maintainers cognisant of the fact that
+those files contain constructs which will not run as-is in JavaScript.
+
 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
@@ -119,7 +130,7 @@ into the build-generated `sqlite3.js` along with `sqlite3-api.js`.
   Emscripten-specific header for Emscripten's `--extern-pre-js`
   flag. As of this writing, that file is only used for experimentation
   purposes and holds no code relevant to the production deliverables.
-- `pre-js.js`\  
+- `pre-js.c-pp.js`\  
   Emscripten-specific header for Emscripten's `--pre-js` flag. This
   file is intended as a place to override certain Emscripten behavior
   before it starts up, but corner-case Emscripten bugs keep that from
@@ -130,17 +141,20 @@ into the build-generated `sqlite3.js` along with `sqlite3-api.js`.
 - `post-js-footer.js`\  
   Emscripten-specific footer for the `--post-js` input. This closes
   off the lexical scope opened by `post-js-header.js`.
-- `extern-post-js.js`\  
+- `extern-post-js.c-pp.js`\  
   Emscripten-specific header for Emscripten's `--extern-post-js`
   flag. This file overwrites the Emscripten-installed
   `sqlite3InitModule()` function with one which, after the module is
   loaded, also initializes the asynchronous parts of the sqlite3
   module. For example, the OPFS VFS support.
 
-## Preprocessing of Source Files
+<a id='c-pp'></a>
+Preprocessing of Source Files
+------------------------------------------------------------------------
 
 Certain files in the build require preprocessing to filter in/out
 parts which differ between vanilla JS builds and ES6 Module
-(a.k.a. esm) builds. The preprocessor itself is in
-[](/file/ext/wasm/c-pp.c) and the associates flags and rules are in
-[](/file/ext/wasm/GNUmakefile).
+(a.k.a. esm) builds. The preprocessor application itself is in
+[`c-pp.c`](/file/ext/wasm/c-pp.c) and the complete technical details
+of such preprocessing are maintained in
+[`GNUMakefile`](/file/ext/wasm/GNUmakefile).

ext/wasm/api/post-js-header.js

@@ -19,7 +19,8 @@ Module.postRun.push(function(Module/*the Emscripten-style module object*/){
      - sqlite3-api-glue.js      => glues previous parts together
      - sqlite3-api-oo.js        => SQLite3 OO API #1
      - sqlite3-api-worker1.js   => Worker-based API
-     - sqlite3-api-opfs.js      => OPFS VFS
+     - sqlite3-vfs-helper.js    => Internal-use utilities for...
+     - sqlite3-vfs-opfs.js      => OPFS VFS
      - sqlite3-api-cleanup.js   => final API cleanup
      - post-js-footer.js        => closes this postRun() function
   */

manifest

@@ -1,5 +1,5 @@
-C Always\suse\snanosleep()\s(instead\sof\susleep()\sor\ssleep)\sif\sthe\s\n_POSIX_C_SOURCE\smacro\ssays\sit\sshould\sbe\savailable.
-D 2022-11-30T13:44:31.719
+C Rename\ssome\sJS\sfiles\sfrom\sX.js\sto\sX.c-pp.js\sto\skeep\sthe\smaintainer,\sand\sdownstream\sbuild\scustomizers,\saware\sthat\sthose\sfiles\scontain\sconstructs\sspecific\sto\sthe\sc-pp\spreprocessor\sand\swill\snot\srun\sas-is\sin\sJS.
+D 2022-11-30T18:21:01.774
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -491,17 +491,17 @@ 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.in 27450c8b8c70875a260aca55435ec927068b34cef801a96205adb81bdcefc65c
-F ext/wasm/GNUmakefile c6b88ce5f735e29bef2b5da2e095848a7919100521a45e645cbf2456d759d5dd
+F ext/wasm/GNUmakefile 85fb066f3ad17f9252deba2a3625736fc9e4172ab1494a73f74d65e21cf93387
 F ext/wasm/README-dist.txt 2d670b426fc7c613b90a7d2f2b05b433088fe65181abead970980f0a4a75ea20
 F ext/wasm/README.md ef39861aa21632fdbca0bdd469f78f0096f6449a720f3f39642594af503030e9
 F ext/wasm/api/EXPORTED_FUNCTIONS.sqlite3-api b4d68c97d14944b48d55e06aa44f544a6f56a7fa2bcb6f9e030936a5b2a9479a
 F ext/wasm/api/EXPORTED_RUNTIME_METHODS.sqlite3-api 1ec3c73e7d66e95529c3c64ac3de2470b0e9e7fbf7a5b41261c367cf4f1b7287
-F ext/wasm/api/README.md 44a05899d607a792370260a7c9193c9c111a7df06bc3ad1823c92a159526dbf3
-F ext/wasm/api/extern-post-js.js 8923f76c3d2213159e12d641dc750523ead5c848185dc4996fae5cc12397f88d
+F ext/wasm/api/README.md 20a256f4aaae80035d2bb1c9e3e0a125570313a8d137d427471d7be10edde87a
+F ext/wasm/api/extern-post-js.c-pp.js 8923f76c3d2213159e12d641dc750523ead5c848185dc4996fae5cc12397f88d w ext/wasm/api/extern-post-js.js
 F ext/wasm/api/extern-pre-js.js cc61c09c7a24a07dbecb4c352453c3985170cec12b4e7e7e7a4d11d43c5c8f41
 F ext/wasm/api/post-js-footer.js cd0a8ec768501d9bd45d325ab0442037fb0e33d1f3b4f08902f15c34720ee4a1
-F ext/wasm/api/post-js-header.js d6ab3dfef4a06960d28a7eaa338d4e2a1a5981e9b38718168bbde8fdb2a439b8
-F ext/wasm/api/pre-js.js b88499dc303c21fc3f55f2c364a0f814f587b60a95784303881169f9e91c1d5f
+F ext/wasm/api/post-js-header.js 47b6b281f39ad59fa6e8b658308cd98ea292c286a68407b35ff3ed9cfd281a62
+F ext/wasm/api/pre-js.c-pp.js b88499dc303c21fc3f55f2c364a0f814f587b60a95784303881169f9e91c1d5f w ext/wasm/api/pre-js.js
 F ext/wasm/api/sqlite3-api-cleanup.js 680d5ccfff54459db136a49b2199d9f879c8405d9c99af1dda0cc5e7c29056f4
 F ext/wasm/api/sqlite3-api-glue.js 03c40b65530d67bb2748b7380aea5fd1534500f812b76a6b401066dcd7fc4116
 F ext/wasm/api/sqlite3-api-oo1.js 06ad2079368e16cb9f182c18cd37bdc3932536856dff4f60582d0ca5f6c491a8
@@ -510,7 +510,7 @@ F ext/wasm/api/sqlite3-api-worker1.js e94ba98e44afccfa482874cd9acb325883ade50ed1
 F ext/wasm/api/sqlite3-license-version-header.js a661182fc93fc2cf212dfd0b987f8e138a3ac98f850b1112e29b5fbdaecc87c3
 F ext/wasm/api/sqlite3-opfs-async-proxy.js 9963c78bf6e5ccb5ba28e8597851bd9d980e86803b6d341cc985e586aef10c82
 F ext/wasm/api/sqlite3-vfs-helper.js 4ad4faf02e1524bf0296be8452c00b5708dce6faf649468d0377e26a0b299263
-F ext/wasm/api/sqlite3-vfs-opfs.js 654f37fd6312d3bb0d067b21ad42f9dcfd629fd34ace892e67e06143a65dc6d0
+F ext/wasm/api/sqlite3-vfs-opfs.c-pp.js 654f37fd6312d3bb0d067b21ad42f9dcfd629fd34ace892e67e06143a65dc6d0 w ext/wasm/api/sqlite3-vfs-opfs.js
 F ext/wasm/api/sqlite3-wasi.h 25356084cfe0d40458a902afb465df8c21fc4152c1d0a59b563a3fba59a068f9
 F ext/wasm/api/sqlite3-wasm.c 8b32787a3b6bb2990cbaba2304bd5b75a9652acbc8d29909b3279019b6cbaef5
 F ext/wasm/api/sqlite3-worker1-promiser.js 0c7a9826dbf82a5ed4e4f7bf7816e825a52aff253afbf3350431f5773faf0e4b
@@ -2065,8 +2065,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 95c78f6b46e0d8efa4313061f47677479f48610b7a7261dc8d0fb1859aca2ad9
-R d8bc00ef34572bdd01b9cc18f03ff989
-U drh
-Z 7f2c7f128d3f16bc147b96b4f9824bd1
+P 6620c57b9d3eae7226a412318b43393196df069b5b90aae0cf1743fdd2d102dd
+R f73408d2fb9e184edb2374ed7b5424d1
+U stephan
+Z a35fbe212dde08194786732b15211922
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-6620c57b9d3eae7226a412318b43393196df069b5b90aae0cf1743fdd2d102dd
+2eade7c7b17a186735c72974c11a34798a08364861d0f307e897ba765c0a93c7