Add docs to mkwasmbuilds.c explaining the purpose of each of the builds. Remove some...

FossilOrigin-Name: a2bd965e103026ff5c722357ed9e3432172bbc19d267e718ebd4a876eca41742

diff --git a/ext/wasm/mkwasmbuilds.c b/ext/wasm/mkwasmbuilds.c
index 4a5d64d6e17639e77ba52d070f5a1bbf303e66d5..fdf604e4767c2596ae91134742d63b13dc9c9c3b 100644 (file)
--- a/ext/wasm/mkwasmbuilds.c
+++ b/ext/wasm/mkwasmbuilds.c
@@ -81,26 +81,48 @@ struct BuildDef {
      Base name of output JS and WASM files.
   */
   const char *zBaseName;
-  /**
-     A glyph to use in log messages for this build, intended to help
-     the eyes distinguish the build lines more easily in parallel
-     builds.
+  /*
+  ** A glyph to use in log messages for this build, intended to help
+  ** the eyes distinguish the build lines more easily in parallel
+  **  builds.
+  **
+  ** The convention for 32- vs 64-bit pairs is to give them similar
+  ** emoji, e.g. a cookie for 32-bit and a donut or cake for 64.
+  ** Alternately, the same emoji a "64" suffix, excep that that throws
+  ** off the output alignment in parallel builds ;).
   */
   const char *zEmo;
-  /**
-     If the build needs its x.wasm renamed in its x.{js,mjs}
-     then this must hold the base name to rename it to.
-     Typically "sqlite3" or "sqlite3-64bit".
+  /*
+  ** If the build needs its x.wasm renamed in its x.{js,mjs} then this
+  ** must hold the base name to rename it to.  Typically "sqlite3" or
+  ** "sqlite3-64bit". This is the case for builds which are named
+  ** something like sqlite3-foo-bar but can use the vanilla
+  ** sqlite3.wasm file. In such cases we don't need the extra
+  ** sqlite3-foo-bar.wasm which Emscripten (necessarily) creates when
+  ** compiling the module, so we patch (at build-time) the JS file to
+  ** use this name instead sqlite3-foo-bar.
   */
   const char *zDotWasm;
   const char *zCmppD;     /* Extra -D... flags for c-pp */
   const char *zEmcc;      /* Extra flags for emcc */
-  const char *zEnv;       /* emcc -sENVIRONMENT=X flag */
-  const char *zIfCond;    /* "ifeq (...)" or similar */
+  const char *zEnv;       /* emcc -sENVIRONMENT=... value */
+  /*
+  ** Makefile code "ifeq (...)". If set, this build is enclosed in a
+  ** $zIfCond/endif block.
+  */
+  const char *zIfCond;    /* makefile "ifeq (...)" or similar */
   int flags;              /* Flags from LibModeFlags */
 };
 typedef struct BuildDef BuildDef;
 
+/*
+** WASM_CUSTOM_INSTANTIATE changes how the JS pieces load the .wasm
+** file from the .js file. When set, our JS takes over that step from
+** Emscripten. Both modes are functionally equivalent but
+** customization gives us access to wasm module state which we don't
+** otherwise have. That said, the library also does not _need_ that
+** state, so we don't _need_ to customize that step.
+*/
 #if !defined(WASM_CUSTOM_INSTANTIATE)
 #  define WASM_CUSTOM_INSTANTIATE 0
 #elif (WASM_CUSTOM_INSTANTIATE+0)==0
@@ -109,17 +131,19 @@ typedef struct BuildDef BuildDef;
 #endif
 
 #if WASM_CUSTOM_INSTANTIATE
+/* c-pp -D... flags for the custom instantiateWasm(). */
 #define C_PP_D_CUSTOM_INSTANTIATE " -Dcustom-Module.instantiateWasm "
 #else
 #define C_PP_D_CUSTOM_INSTANTIATE
 #endif
 
-/* List of distinct library builds. See next comment block. */
+/* List of distinct library builds. Each one has to be set up in
+** oBuildDefs. See the next comment block. */
 #define BuildDefs_map(E)  \
   E(vanilla) E(vanilla64) \
-  E(esm) E(esm64)         \
+  E(esm)     E(esm64)     \
   E(bundler) E(bundler64) \
-  E(node) E(node64) \
+  E(node)    E(node64)    \
   E(wasmfs)
 
 /*
@@ -138,9 +162,13 @@ struct BuildDefs {
 typedef struct BuildDefs BuildDefs;
 
 const BuildDefs oBuildDefs = {
+  /*
+  ** The canonical build, against which all others are compared and
+  ** contrasted.  This is the one we post downloads for.
+  */
   .vanilla = {
     /* This one's zBaseName and zEnv MUST be non-NULL so it can be
-       used as a default for all others. */
+    ** used as a default for all others. */
     .zEmo        = "🍦",
     .zBaseName   = "sqlite3",
     .zDotWasm    = 0,
@@ -151,6 +179,7 @@ const BuildDefs oBuildDefs = {
     .flags       = CP_ALL
   },
 
+  /* The canonical build in 64-bit. */
   .vanilla64 = {
     .zEmo        = "🍨",
     .zBaseName   = "sqlite3-64bit",
@@ -159,9 +188,10 @@ const BuildDefs oBuildDefs = {
     .zEmcc       = "-sMEMORY64=1",
     .zEnv        = 0,
     .zIfCond     = 0,
-    .flags       = CP_ALL | F_64BIT | F_NOT_IN_ALL
+    .flags       = CP_ALL | F_64BIT
   },
 
+  /* The canonical esm build. */
   .esm = {
     .zEmo        = "🍬",
     .zBaseName   = "sqlite3",
@@ -173,6 +203,7 @@ const BuildDefs oBuildDefs = {
     .flags       = CP_JS | F_ESM
   },
 
+  /* The canonical esm build in 64-bit. */
   .esm64 = {
     .zEmo        = "🍫",
     .zBaseName   = "sqlite3-64bit",
@@ -181,15 +212,19 @@ const BuildDefs oBuildDefs = {
     .zEmcc       = "-sMEMORY64=1",
     .zEnv        = 0,
     .zIfCond     = 0,
-    .flags       = CP_JS | F_ESM | F_64BIT | F_NOT_IN_ALL
+    .flags       = CP_JS | F_ESM | F_64BIT
   },
 
+  /*
+  ** Core bundler-friendly build. Untested and "not really" supported,
+  ** but required by the downstream npm subproject.
+  **
+  ** Testing these requires special-purpose node-based tools and
+  ** custom test apps, none of which we have/use. So we can pass them
+  ** off as-is to the npm subproject and they spot failures pretty
+  ** quickly ;).
+  */
   .bundler = {
-    /* Core bundler-friendly build. Untested and "not really"
-    ** supported, but required by the downstream npm subproject.
-    ** Testing these would require special-purpose node-based tools and
-    ** custom test apps. Or we can pass them off as-is to the npm
-    ** subproject and they spot failures pretty quickly ;). */
     .zEmo        = "👛",
     .zBaseName   = "sqlite3-bundler-friendly",
     .zDotWasm    = "sqlite3",
@@ -200,6 +235,7 @@ const BuildDefs oBuildDefs = {
     .flags       = CP_JS | F_BUNDLER_FRIENDLY | F_ESM | F_NOT_IN_ALL
   },
 
+  /* 64-bit bundler-friendly. */
   .bundler64 = {
     .zEmo        = "📦",
     .zBaseName   = "sqlite3-bundler-friendly",
@@ -211,25 +247,27 @@ const BuildDefs oBuildDefs = {
     .flags       = CP_JS | F_ESM | F_BUNDLER_FRIENDLY | F_64BIT | F_NOT_IN_ALL
   },
 
-  /* We neither build nor test node builds on a regular basis. They
-     are fully unsupported. */
+  /*
+  ** We neither build node builds on a regular basis nor test them at
+  ** all. They are fully unsupported. Also, our JS targets only
+  ** browsers.
+  */
   .node = {
     .zEmo        = "🍟",
     .zBaseName   = "sqlite3-node",
     .zDotWasm    = 0,
     .zCmppD      = "-Dtarget=node $(c-pp.D.bundler)",
     .zEmcc       = 0,
-    .zEnv        = "node",
-    /*
-      Adding ",node" to the list for the other builds causes
-      Emscripten to generate code which confuses node: it cannot
-      reliably determine whether the build is for a browser or for
-      node.  */
+    .zEnv        = "node"
+    /* Adding ",node" to the zEnv list for the other builds causes
+    ** Emscripten to generate code which confuses node: it cannot
+    ** reliably determine whether the build is for a browser or for
+    ** node. */,
     .zIfCond     = 0,
     .flags       = CP_ALL | F_UNSUPPORTED | F_NODEJS
   },
 
-  /* Entirely unsupported. */
+  /* 64-bit node. */
   .node64 = {
     .zEmo        = "🍔",
     .zBaseName   = "sqlite3-node-64bit",
@@ -286,11 +324,6 @@ static void mk_prologue(void){
     ps("endif");
   }
 
-  ps(zBanner
-  );
-
-  ps("b.echo = echo '$(logtag.$(1))' '$(2)'");
-
 #if 0
   ps(zBanner
      /** $1 = build name. */
@@ -397,12 +430,12 @@ static void mk_prologue(void){
      " $(sqlite3-api.jses)"
      " $(dir.api)/post-js-footer.js\n"
      "$(post-js.in.js): $(MKDIR.bld) $(post-jses.js) $(MAKEFILE)\n"
-     " @echo '$(logtag.@) $(emo.disk)'\n"
-     " @for i in $(post-jses.js); do \\n"
-     "         echo \"/* BEGIN FILE: $$i */\"; \\n"
-     "         cat $$i || exit $$?; \\n"
-     "         echo \"/* END FILE: $$i */\"; \\n"
-     " done > $@\n"
+     "\t@echo '$(logtag.@) $(emo.disk)'\n"
+     "\t@for i in $(post-jses.js); do \\n"
+     "\t\techo \"/* BEGIN FILE: $$i */\"; \\n"
+     "\t\tcat $$i || exit $$?; \\n"
+     "\t\techo \"/* END FILE: $$i */\"; \\n"
+     "\tdone > $@\n"
   );
 
   pf(zBanner

diff --git a/ext/wasm/util.make b/ext/wasm/util.make
index 0b195927fbcdc64259aa6575606351417dc115d0..fc9f4c64ca12e960e7e69aa518d2a0d1a9a773ba 100644 (file)
--- a/ext/wasm/util.make
+++ b/ext/wasm/util.make
@@ -40,10 +40,15 @@ emo.tool = 🔨
 logtag.@ = [$@]
 logtag.filter = [🚧 $@]
 
+#
+# $(call b.echo,LOGTAG,msg)
+#
+b.echo = echo $(logtag.$(1)) $(2)
+
 #
 # $(call b.call.mkdir@)
 #
-# $1 = optional build name
+# $1 = optional LOGTAG
 #
 b.call.mkdir@ = if [ ! -d $(dir $@) ]; then \
   echo '[$(emo.folder)+] $(if $(1),$(logtag.$(1)),[$(dir $@)])'; \

diff --git a/manifest b/manifest
index 33a5941b19c69c9903beb36b14c9631c470bdad7..b395f3ac5c0cdf4f593bd8034158604422acf974 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Cosmetic\sbuild\stweaks.
-D 2025-09-24T07:31:19.910
+C Add\sdocs\sto\smkwasmbuilds.c\sexplaining\sthe\spurpose\sof\seach\sof\sthe\sbuilds.\sRemove\ssome\sinadvertent\scopy/paste\shard\stabs\sin\ssome\sC-side\smakefile\scode.
+D 2025-09-24T13:59:53.888
 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
@@ -639,7 +639,7 @@ F ext/wasm/index-dist.html 56132399702b15d70c474c3f1952541e25cb0922942868f70daf1
 F ext/wasm/index.html bcaa00eca521b372a6a62c7e7b17a870b0fcdf3e418a5921df1fd61e5344080d
 F ext/wasm/jaccwabyt/jaccwabyt.js bbac67bc7a79dca34afe6215fd16b27768d84e22273507206f888c117e2ede7d
 F ext/wasm/jaccwabyt/jaccwabyt.md 167fc0b624c9bc2c477846e336de9403842d81b1a24fc4d3b24317cb9eba734f
-F ext/wasm/mkwasmbuilds.c a276249935c02dabe5aa8fc61d3b06a479aeeddef188bc5d89f7574ba371b269
+F ext/wasm/mkwasmbuilds.c 8737ff705bd060a088609edd4cbc908e0bc89dcfc1fa48605bd339aa51dcc709
 F ext/wasm/module-symbols.html dc476b403369b26a1a23773e13b80f41b9a49f0825e81435fe3600a7cfbbe337
 F ext/wasm/scratchpad-wasmfs.html a3d7388f3c4b263676b58b526846e9d02dfcb4014ff29d3a5040935286af5b96
 F ext/wasm/scratchpad-wasmfs.mjs 66034b9256b218de59248aad796760a1584c1dd842231505895eff00dbd57c63
@@ -664,7 +664,7 @@ F ext/wasm/tests/opfs/sahpool/digest.html 206d08a34dc8bd570b2581d3d9ab3ecad3201b
 F ext/wasm/tests/opfs/sahpool/index.html be736567fd92d3ecb9754c145755037cbbd2bca01385e2732294b53f4c842328
 F ext/wasm/tests/opfs/sahpool/sahpool-pausing.js f264925cfc82155de38cecb3d204c36e0f6991460fff0cb7c15079454679a4e2
 F ext/wasm/tests/opfs/sahpool/sahpool-worker.js bd25a43fc2ab2d1bafd8f2854ad3943ef673f7c3be03e95ecf1612ff6e8e2a61
-F ext/wasm/util.make ecee9e8ee4cd05d8877550831d7d3176efb08a62d65ac2eb05e0cafac24bf841
+F ext/wasm/util.make 02f29bd0821d8fbf6fa7a02e1ecc32d9866bf9c2ebab6f06d0de4ba1cf84fd79
 F ext/wasm/wasmfs.make 5de02751b3e9e79b81a52ab4fe0ed6aa6a23311a90db58fea98c1c4e2845e562
 F magic.txt 5ade0bc977aa135e79e3faaea894d5671b26107cc91e70783aa7dc83f22f3ba0
 F main.mk 20fe7a151708fc6b1f8cd0fdcc73622701cff5959131cfb73e1f75d33e687bf8
@@ -2176,8 +2176,8 @@ F tool/version-info.c 3b36468a90faf1bbd59c65fd0eb66522d9f941eedd364fabccd7227350
 F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7
 F tool/warnings.sh 1ad0169b022b280bcaaf94a7fa231591be96b514230ab5c98fbf15cd7df842dd
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P f5167fb3615efc180e69333f99d82d6afc1d190e7f37b6a701895de00502d8c8
-R d9fca2e8597730588fac07bc64a8e3d3
+P 431725330d6c63575dbf3404664a7af33d4d87c569560e99c18de93eb4d73935
+R e3af3db66eb0d4f51c1b04cbc2314c0b
 U stephan
-Z 93780c2d051edfca4443bf188fca31ca
+Z 77ec6416fddbe3c006d4bdaeedea1332
 # Remove this line to create a well-formed Fossil manifest.

diff --git a/manifest.uuid b/manifest.uuid
index 5627895eec5d25d78fc9006cfb7724b85cb57489..77c48da42dec9d7e2c7edf56804d55e44444fa96 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-431725330d6c63575dbf3404664a7af33d4d87c569560e99c18de93eb4d73935
+a2bd965e103026ff5c722357ed9e3432172bbc19d267e718ebd4a876eca41742