From: stephan <stephan@noemail.net>
Date: Tue, 2 Jan 2024 09:03:42 +0000 (+0000)
Subject: Update and clean up the in-makefile docs for ext/wasm.
X-Git-Tag: version-3.45.0~25
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=3d4d3fb59dbd565534f32442ef8292ad130d4163;p=thirdparty%2Fsqlite.git

Update and clean up the in-makefile docs for ext/wasm.

FossilOrigin-Name: 7a7b295e6d7e95ee4a46cc42761895d11700ab295870c5a4380072bb4a5b7099
---

diff --git a/ext/wasm/GNUmakefile b/ext/wasm/GNUmakefile
index 94eff4cc32..93993ebc47 100644
--- a/ext/wasm/GNUmakefile
+++ b/ext/wasm/GNUmakefile
@@ -42,7 +42,9 @@
 # 1) Consolidate the code generation for sqlite3*.*js into a script
 #    which generates the makefile code, rather than using $(call) and
 #    $(eval), or at least centralize the setup of the numerous vars
-#    related to each build variant $(JS_BUILD_MODES).
+#    related to each build variant $(JS_BUILD_MODES). (Update: an
+#    external script was attempted but it's even less legible than the
+#    $(eval) indirection going on in this file.
 #
 default: all
 #default: quick
@@ -51,12 +53,26 @@ MAKEFILE := $(lastword $(MAKEFILE_LIST))
 CLEAN_FILES :=
 DISTCLEAN_FILES := ./--dummy--
 release: oz
-# JS_BUILD_MODES exists solely to reduce repetition in documentation
-# below.
-JS_BUILD_MODES := vanilla esm bunder-friendly node
+
+########################################################################
 # JS_BUILD_NAMES exists solely to reduce repetition in documentation
-# below.
+# below. It enumerates the core build styles:
+#
+# - sqlite3 = main build
+# - sqlite3-wasmfs = WASMFS-capable build
 JS_BUILD_NAMES := sqlite3 sqlite3-wasmfs
+
+########################################################################
+# JS_BUILD_MODES exists solely to reduce repetition in documentation
+# below. It enumerates the various flavors of build:
+#
+# - vanilla = plain-vanilla JS
+# - ecm = ES6 module a.k.a. ESM
+# - bundler-friendly = esm slightly tweaked for "bundler" tools
+# - node = for use with node.js
+JS_BUILD_MODES := vanilla esm bunder-friendly node
+
+########################################################################
 # Emscripten SDK home dir and related binaries...
 EMSDK_HOME ?= $(word 1,$(wildcard $(HOME)/emsdk $(HOME)/src/emsdk))
 emcc.bin ?= $(word 1,$(wildcard $(EMSDK_HOME)/upstream/emscripten/emcc) $(shell which emcc))
@@ -96,11 +112,14 @@ else
   maybe-wasm-strip = $(wasm-strip)
 endif
 
+########################################################################
+# dir.top = the top dir of the canonical build tree, where
+# sqlite3.[ch] live.
 dir.top := ../..
-# Reminder: some Emscripten flags require absolute paths but we want
-# relative paths for most stuff simply to reduce noise. The
-# $(abspath...) GNU make function can transform relative paths to
-# absolute.
+# Maintenance reminder: some Emscripten flags require absolute paths
+# but we want relative paths for most stuff simply to reduce
+# noise. The $(abspath...) GNU make function can transform relative
+# paths to absolute.
 dir.wasm := $(patsubst %/,%,$(dir $(MAKEFILE)))
 dir.api := api
 dir.jacc := jaccwabyt
@@ -146,12 +165,14 @@ endif
 # Set up sqlite3.c and sqlite3.h...
 #
 # To build with SEE (https://sqlite.org/see), either put sqlite3-see.c
-# in the top of this build tree or pass
-# sqlite3.c=PATH_TO_sqlite3-see.c to the build. Note that only
-# encryption modules with no 3rd-party dependencies will currently
-# work here: AES256-OFB, AES128-OFB, and AES128-CCM. Not
-# coincidentally, those 3 modules are included in the sqlite3-see.c
-# bundle.
+# in $(dir.top) or pass sqlite3.c=PATH_TO_sqlite3-see.c to the $(MAKE)
+# invocation. Note that only encryption modules with no 3rd-party
+# dependencies will currently work here: AES256-OFB, AES128-OFB, and
+# AES128-CCM. Not coincidentally, those 3 modules are included in the
+# sqlite3-see.c bundle. Note, however, that distributing an SEE build
+# of the WASM on a public site is in violation of the SEE license
+# because it effectively provides a usable copy of the SEE build to
+# all visitors.
 #
 # A custom sqlite3.c must not have any spaces in its name.
 # $(sqlite3.canonical.c) must point to the sqlite3.c in
@@ -196,6 +217,10 @@ SQLITE_OPT = \
 # can be used to find errant uses of sqlite3_js_vfs_create_file()
 # in client code.
 
+########################################################################@
+# It's important that sqlite3.h be built to completion before any
+# other parts of the build run, thus we use .NOTPARALLEL to disable
+# parallel build of that file and its dependants.
 .NOTPARALLEL: $(sqlite3.h)
 $(sqlite3.h):
 	$(MAKE) -C $(dir.top) sqlite3.c
@@ -245,6 +270,7 @@ ifneq (,$(sqlite3_wasm_extra_init.c))
   cflags.wasm_extra_init := -DSQLITE_WASM_EXTRA_INIT
 endif
 
+#########################################################################
 # bin.version-info = binary to output various sqlite3 version info for
 # embedding in the JS files and in building the distribution zip file.
 # It must NOT be in $(dir.tmp) because we need it to survive the
@@ -254,11 +280,12 @@ bin.version-info := $(dir.top)/version-info
 $(bin.version-info): $(dir.tool)/version-info.c $(sqlite3.h) $(dir.top)/Makefile
 	$(MAKE) -C $(dir.top) version-info
 
+#########################################################################
 # bin.stripcomments is used for stripping C/C++-style comments from JS
 # files. The JS files contain large chunks of documentation which we
 # don't need for all builds. That app's -k flag is of particular
 # importance here, as it allows us to retain the opening comment
-# blocks, which contain the license header and version info.
+# block(s), which contain the license header and version info.
 bin.stripccomments := $(dir.tool)/stripccomments
 $(bin.stripccomments): $(bin.stripccomments).c $(MAKEFILE)
 	$(CC) -o $@ $<
@@ -353,6 +380,7 @@ emcc_opt_full := $(emcc_opt) -g3
 # -Oz when small deliverable size is a priority.
 ########################################################################
 
+########################################################################
 # EXPORTED_FUNCTIONS.* = files for use with Emscripten's
 # -sEXPORTED_FUNCTION flag.
 EXPORTED_FUNCTIONS.api.main := $(abspath $(dir.api)/EXPORTED_FUNCTIONS.sqlite3-api)
@@ -364,6 +392,7 @@ EXPORTED_FUNCTIONS.api := $(dir.tmp)/EXPORTED_FUNCTIONS.api
 $(EXPORTED_FUNCTIONS.api): $(EXPORTED_FUNCTIONS.api.in) $(sqlite3.c) $(MAKEFILE)
 	cat $(EXPORTED_FUNCTIONS.api.in) > $@
 
+########################################################################
 # sqlite3-license-version.js = generated JS file with the license
 # header and version info.
 sqlite3-license-version.js := $(dir.tmp)/sqlite3-license-version.js
@@ -376,20 +405,35 @@ 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), in the order they need to be assembled.
 sqlite3-api.jses := $(sqlite3-license-version.js)
+# sqlite3-api-prologue.js: initial boostrapping bits:
 sqlite3-api.jses += $(dir.api)/sqlite3-api-prologue.js
+# whwhasm.js and jaccwabyt.js: Low-level utils, mostly replacing
+# Emscripten glue:
 sqlite3-api.jses += $(dir.common)/whwasmutil.js
 sqlite3-api.jses += $(dir.jacc)/jaccwabyt.js
+# sqlite3-api-glue.js Glues the previous part together:
 sqlite3-api.jses += $(dir.api)/sqlite3-api-glue.js
+# $(sqlite3-api-build-version.js) = library version info
 sqlite3-api.jses += $(sqlite3-api-build-version.js)
+# sqlite3-api-oo1.js = the oo1 API:
 sqlite3-api.jses += $(dir.api)/sqlite3-api-oo1.js
+# sqlite3-api-worker.js = the Worker1 API:
 sqlite3-api.jses += $(dir.api)/sqlite3-api-worker1.js
+# sqlite3-v-helper = helper APIs for VFSes and VTABLEs:
 sqlite3-api.jses += $(dir.api)/sqlite3-v-helper.js
+# sqlite3-vfs-opfs.c-pp.js = the first OPFS VFS:
 sqlite3-api.jses += $(dir.api)/sqlite3-vfs-opfs.c-pp.js
+# sqlite3-vfs-opfs-sahpool.c-pp.js = the second OPFS VFS:
 sqlite3-api.jses += $(dir.api)/sqlite3-vfs-opfs-sahpool.c-pp.js
+# sqlite3-api-cleanup.js = "finalizes" the build and cleans up
+# any extraneous global symbols which are needed temporarily
+# by the previous files.
 sqlite3-api.jses += $(dir.api)/sqlite3-api-cleanup.js
 
+########################################################################
 # SOAP.js is an external API file which is part of our distribution
-# but not part of the sqlite3-api.js amalgamation.
+# but not part of the sqlite3-api.js amalgamation. It's a component of
+# the first OPFS VFS and necessarily an external file.
 SOAP.js := $(dir.api)/sqlite3-opfs-async-proxy.js
 SOAP.js.bld := $(dir.dout)/$(notdir $(SOAP.js))
 sqlite3-api.ext.jses += $(SOAP.js.bld)
@@ -444,7 +488,9 @@ endif
 # emcc flags for .c/.o.
 emcc.cflags :=
 emcc.cflags += -std=c99 -fPIC
-# -------------^^^^^^^^ we need c99 for $(sqlite3-wasm.c).
+# -------------^^^^^^^^ we need c99 for $(sqlite3-wasm.c), primarily
+# for variadic macros and snprintf() to implement
+# sqlite3_wasm_enum_json().
 emcc.cflags += -I. -I$(dir.top)
 ########################################################################
 # emcc flags specific to building .js/.wasm files...
@@ -465,14 +511,16 @@ emcc.jsflags += -sIMPORTED_MEMORY
 emcc.jsflags += -sSTRICT_JS=0
 # STRICT_JS disabled due to:
 #   https://github.com/emscripten-core/emscripten/issues/18610
-# TL;DR: does not work with MODULARIZE or EXPORT_ES6 as of version 3.1.31.
+# TL;DR: does not work with MODULARIZE or EXPORT_ES6 as of version
+# 3.1.31.  The fix for that in newer emcc's is to throw a built-time
+# error if STRICT_JS is used together with those options.
 
 # -sENVIRONMENT values for the various build modes:
 emcc.environment.vanilla := web,worker
 emcc.environment.bundler-friendly := $(emcc.environment.vanilla)
 emcc.environment.esm := $(emcc.environment.vanilla)
 emcc.environment.node := node
-# Note that adding "node" to the list for the other builds causes
+# Note that 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.
 
@@ -575,8 +623,9 @@ emcc.jsflags += -sLLD_REPORT_UNDEFINED
 # -g3 debugging info, _huge_.
 ########################################################################
 
+########################################################################
 # $(sqlite3-api-build-version.js) injects the build version info into
-# the bundle.
+# the bundle in JSON form.
 $(sqlite3-api-build-version.js): $(bin.version-info) $(MAKEFILE)
 	@echo "Making $@..."
 	@{ \
@@ -587,8 +636,9 @@ $(sqlite3-api-build-version.js): $(bin.version-info) $(MAKEFILE)
     echo '});'; \
   } > $@
 
-# $(sqlite3-license-version.js) contains the license header and build
-# version info.
+########################################################################
+# $(sqlite3-license-version.js) contains the license header and
+# in-comment build version info.
 $(sqlite3-license-version.js): $(sqlite3.h) $(sqlite3-license-version-header.js) \
   $(MAKEFILE)
 	@echo "Making $@..."; { \
@@ -707,8 +757,8 @@ sqlite3-wasmfs.cfiles := $(sqlite3-wasm.cfiles)
 # Upstream RFE:
 # https://github.com/emscripten-core/emscripten/issues/18237
 #
-# Maintenance reminder: Mac sed works differently than GNU sed, so
-# don't use sed for this.
+# Maintenance reminder: Mac sed works differently than GNU sed, so we
+# use awk instead of sed for this.
 define SQLITE3.xJS.ESM-EXPORT-DEFAULT
 if [ x1 = x$(1) ]; then \
 		echo "Fragile workaround for emscripten/issues/18237. See SQLITE3.xJS.RECIPE."; \
@@ -724,6 +774,7 @@ if [ x1 = x$(1) ]; then \
 fi
 endef
 
+########################################################################
 # extern-post-js* and extern-pre-js* are files for use with
 # Emscripten's --extern-pre-js and --extern-post-js flags.
 extern-pre-js.js := $(dir.api)/extern-pre-js.js
@@ -735,6 +786,7 @@ pre-post-common.flags := \
 # pre-post-jses.deps.* = a list of dependencies for the
 # --[extern-][pre/post]-js files.
 pre-post-jses.deps.common := $(extern-pre-js.js) $(sqlite3-license-version.js)
+
 ########################################################################
 # SETUP_LIB_BUILD_MODE is a $(call)'able which sets up numerous pieces
 # for one of the build modes.
@@ -750,7 +802,8 @@ pre-post-jses.deps.common := $(extern-pre-js.js) $(sqlite3-license-version.js)
 # Maintenance reminder: be careful not to introduce spaces around args
 # ($1, $2), otherwise string concatenation will malfunction.
 #
-# emcc.environment.$(2) must be set to a value for the -sENVIRONMENT flag.
+# emcc.environment.$(2) must be set to a value for emcc's
+# -sENVIRONMENT flag.
 #
 # $(cflags.$(1)) and $(cflags.$(1).$(2)) may be defined to append
 # CFLAGS to a given build mode.
diff --git a/ext/wasm/api/sqlite3-wasm.c b/ext/wasm/api/sqlite3-wasm.c
index 3e22c799c4..618d0f085a 100644
--- a/ext/wasm/api/sqlite3-wasm.c
+++ b/ext/wasm/api/sqlite3-wasm.c
@@ -1103,7 +1103,7 @@ const char * sqlite3_wasm_enum_json(void){
       M(xShadowName,    "i(s)");
     } _StructBinder;
 #undef CurrentStruct
-    
+
     /**
      ** Workaround: in order to map the various inner structs from
      ** sqlite3_index_info, we have to uplift those into constructs we
diff --git a/manifest b/manifest
index 70fb81c936..50fd1af7d4 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Back\sout\s[99d11e6d0ae6]\s(enabling\sof\sSTAT4\sin\sWASM/JNI),\sper\s/chat\sdiscussion.
-D 2024-01-01T23:28:02.565
+C Update\sand\sclean\sup\sthe\sin-makefile\sdocs\sfor\sext/wasm.
+D 2024-01-02T09:03:42.100
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -575,7 +575,7 @@ 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 a8a171af359b9acee604bb01229f59052b8b38c43f6020a6d009e42c76f910af
+F ext/wasm/GNUmakefile 5b1f425d3619578d4e17312a3d920cbf0d22caff67d1fc30330046ca0ae24bc6
 F ext/wasm/README-dist.txt 6382cb9548076fca472fb3330bbdba3a55c1ea0b180ff9253f084f07ff383576
 F ext/wasm/README.md a8a2962c3aebdf8d2104a9102e336c5554e78fc6072746e5daf9c61514e7d193
 F ext/wasm/SQLTester/GNUmakefile e0794f676d55819951bbfae45cc5e8d7818dc460492dc317ce7f0d2eca15caff
@@ -602,7 +602,7 @@ F ext/wasm/api/sqlite3-opfs-async-proxy.js 8cf8a897726f14071fae6be6648125162b256
 F ext/wasm/api/sqlite3-v-helper.js 7daa0eab0a513a25b05e9abae7b5beaaa39209b3ed12f86aeae9ef8d2719ed25
 F ext/wasm/api/sqlite3-vfs-opfs-sahpool.c-pp.js 595953994aa3ae2287c889c4da39ab3d6f17b6461ecf4bec334b7a3faafddb02
 F ext/wasm/api/sqlite3-vfs-opfs.c-pp.js 46c4afa6c50d7369252c104f274ad977a97e91ccfafc38b400fe36e90bdda88e
-F ext/wasm/api/sqlite3-wasm.c f280d4ea917d213ae95668dfcd173a2c2ef21a0a4bf9aeb9fcd0edaf1b21ba4b
+F ext/wasm/api/sqlite3-wasm.c dfd1f1a225b267e8fd641dcd6c7d579fbe2b731aeaa123324135efac830a2bcf
 F ext/wasm/api/sqlite3-worker1-promiser.c-pp.js f234191fe6bf41a5a1e59c9f43ed816e74a522b3d60d3f556f66c3085c448503
 F ext/wasm/api/sqlite3-worker1.c-pp.js 5e8706c2c4af2a57fbcdc02f4e7ef79869971bc21bb8ede777687786ce1c92d5
 F ext/wasm/batch-runner-sahpool.html e9a38fdeb36a13eac7b50241dfe7ae066fe3f51f5c0b0151e7baee5fce0d07a7
@@ -2156,9 +2156,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 bcac937526d9a6ef914a74b4d6757fa91cd74edab871bcd934fde4a2f9b6debd
-Q -99d11e6d0ae687ff6bac5119027f7b04d5e7185214e79cf8c56289cfa809b0f9
-R 3bfcbade7baedb397a7149e377c6dcbb
+P cd7929ee2e2c305475fa5a4dff2edaccf90067126ef04a1c2714cf464925453f
+R de6e93274e75f378c4f5110a14f6c9e3
 U stephan
-Z 7c711e37eafa39916defd330fece0ca3
+Z 326fdaaa6c149e5a91868eade9fb0075
 # Remove this line to create a well-formed Fossil manifest.
diff --git a/manifest.uuid b/manifest.uuid
index bf4d9238f0..28b1ac3a3f 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-cd7929ee2e2c305475fa5a4dff2edaccf90067126ef04a1c2714cf464925453f
\ No newline at end of file
+7a7b295e6d7e95ee4a46cc42761895d11700ab295870c5a4380072bb4a5b7099
\ No newline at end of file