From c0e3a8ca195c566104fbf852ba1e5a436b950ad6 Mon Sep 17 00:00:00 2001 From: stephan Date: Thu, 4 Sep 2025 18:00:53 +0000 Subject: [PATCH] Generic doc updates in ext/wasm's makefiles. No functional changes. FossilOrigin-Name: 02721457cea255a5117a46b77cc87d2e09acb64340ce94089c5b5e6edc5b5033 --- ext/wasm/GNUmakefile | 64 ++++++++++++++++++++++++++++---------------- ext/wasm/dist.make | 52 +++++++++++++++++------------------ manifest | 16 +++++------ manifest.uuid | 2 +- 4 files changed, 75 insertions(+), 59 deletions(-) diff --git a/ext/wasm/GNUmakefile b/ext/wasm/GNUmakefile index 5cd0aa66a6..d5a2dde607 100644 --- a/ext/wasm/GNUmakefile +++ b/ext/wasm/GNUmakefile @@ -1,11 +1,10 @@ ####################################################################### -# This GNU makefile drives the build of the sqlite3 WASM -# components. It is not part of the canonical build process. +# This GNU makefile creates the canonical sqlite3 WASM builds. # # This build assumes a Linux platform and is not intended for # general-purpose client-level use, except for creating builds with -# custom configurations. It is primarily intended for the sqlite -# project's own development of the JS/WASM components. +# custom configurations. It is primarily intended for the SQLite +# project's own development of its JS/WASM components. # # Primary targets: # @@ -134,7 +133,10 @@ JS_BUILD_NAMES = sqlite3 sqlite3-wasmfs # - bundler-friendly = esm slightly tweaked for "bundler" # tools. Bundlers are invariably based on node.js, so these builds # are intended to be read at build-time by node.js but with a final -# target of browsers. +# target of browsers. All bundler-friendly builds are UNTESTED. +# They are provided primarily for use by the community-supported +# subproject which hosts npm builds of sqlite3, and they are +# actively supported only to the extent needed by that subproject. # # - node = for use by node.js for node.js, as opposed to by node.js on # behalf of browser-side code (use bundler-friendly for that). Note @@ -451,6 +453,8 @@ emcc.WASM_BIGINT ?= 1 # has shown -Oz to produce the smallest deliverables with only a # roughly 10% performance hit in the resulting WASM file compared to # -O2 (which consistently creates the fastest-running deliverables). +# Build time suffers greatly compared to -O0, which is why -O0 is the +# default. ifeq (,$(filter $(OPTIMIZED_TARGETS),$(MAKECMDGOALS))) emcc_opt ?= -O0 else @@ -499,7 +503,7 @@ emcc_opt_full = $(emcc_opt) -g3 # # Much practice has demonstrated that -O2 consistently gives the best # runtime speeds, but not by a large enough factor to rule out use of -# -Oz when small deliverable size is a priority. +# -Oz when smaller deliverable size is a priority. ######################################################################## ######################################################################## @@ -583,9 +587,20 @@ $(SOAP.js.bld): $(SOAP.js) # them. Tools like wasm-objdump can be used to find the list of # imports but it's questionable whether a non-Emscripten tool could # realistically use that info to provide proper implementations. +# # Sidebar: some of the imports are used soley by the Emscripten glue, # which the sqlite3 JS code does not rely on. # +# 2025-09-04: the most significant WASM imports sqlite3.wasm relies on +# are (A) sqlite3_malloc/sqlite3_free() (the memory-management APIs +# used by the whole library) and (B) the libc proxies for POSIX I/O +# emulation (arguably one of Emscripten's most convenient features +# when building C code for WASM). If we eliminate the POSIX I/O +# emulation then we could hypothetically eliminate all, or maybe all +# but one, Emscripten import dependency. We would either need to add +# our own POSIX emulation layer (not a trivial effort) or restrict the +# library to use of only in-memory VFSes and the JS-side VFSes. +# # sqlite3-api.js.in = the amalgamated sqlite3-api.js before it gets # preprocessed. It contains all of $(sqlite3-api.jses) but none of the # Emscripten-specific headers and footers. @@ -648,26 +663,27 @@ emcc.jsflags += -sSTRICT_JS=0 # -sSTRICT=1 Causes failures about unknown symbols which the build # tools should be installing, e.g. __syscall_geteuid32 -# -sENVIRONMENT values for the various build modes: +# emcc -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 -# Emscripten to generate code which confuses node: it cannot reliably -# determine whether the build is for a browser or for 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. We neither build nor +# test node builds on a regular basis. They are fully unsupported. ######################################################################## # -sINITIAL_MEMORY: How much memory we need to start with is governed # at least in part by whether -sALLOW_MEMORY_GROWTH is enabled. If so, # we can start with less. If not, we need as much as we'll ever -# possibly use (which, of course, we can't know for sure). Note, -# however, that speedtest1 shows that performance for even moderate -# workloads MAY suffer considerably if we start small and have to grow -# at runtime. e.g. OPFS-backed (speedtest1 --size 75) take MAY take X -# time with 16mb+ memory and 3X time when starting with 8MB. However, -# such test results are inconsistent due to browser internals which -# are opaque to us. +# possibly use (which, of course, we can't know for sure). speedtest1 +# shows that performance for even moderate workloads MAY suffer +# considerably if we start small and have to grow at runtime. +# e.g. OPFS-backed (speedtest1 --size 75) take MAY take X time with +# 16mb+ memory and 3X time when starting with 8MB. However, such test +# results are inconsistent due to browser internals which are opaque +# to us. # # 2024-03-04: emsdk 3.1.55 replaces INITIAL_MEMORY with INITIAL_HEAP, # but also says (in its changelog): "Note that it is currently not @@ -892,6 +908,8 @@ EXPORTED_FUNCTIONS.fiddle = $(dir.tmp)/EXPORTED_FUNCTIONS.fiddle # part, as it's unable to reliably determine whether the target is # a browser or node. # +# We repeat: all node.js builds are 100% untested and unsupported. +# ######################################################################## ######################################################################## # We have to ensure that we do not build $(sqlite3*.*js) in parallel @@ -921,8 +939,8 @@ ifneq (1,$(MAKING_CLEAN)) # native makefile code. Somewhat surprisingly, moving that code generation # to C makes it slightly less illegible than the previous 3 options. # -# Maintenance note: the various $(c-pp.D.XYZ) vars are defined in this -# step. +# Maintenance note: the various $(c-pp.D.XYZ) vars are defined via +# $(bin.mkwb). bin.mkwb = ./mkwasmbuilds $(bin.mkwb): $(bin.mkwb).c $(MAKEFILE) $(CC) -o $@ $< @@ -1101,7 +1119,7 @@ $(eval $(call SQLITE.CALL.C-PP.FILTER,tester1.c-pp.js,tester1.mjs,$(c-pp.D.sqlit $(eval $(call SQLITE.CALL.C-PP.FILTER,tester1.c-pp.html,tester1.html)) $(eval $(call SQLITE.CALL.C-PP.FILTER,tester1.c-pp.html,tester1-esm.html,$(c-pp.D.sqlite3-esm))) tester1: tester1.js tester1.mjs tester1.html tester1-esm.html -# Note that we do not include $(dir.dout)/sqlite3-bundler-friendly.mjs in this +# We do not include $(dir.dout)/sqlite3-bundler-friendly.mjs in this # because bundlers are client-specific. all quick: tester1 quick: $(sqlite3.js) @@ -1140,7 +1158,7 @@ oz: clean ######################################################################## # Sub-makes... -# sqlite.org/fiddle application... +# https://sqlite.org/fiddle application... include $(MAKEFILE.fiddle) # Only add wasmfs if wasmfs.enable=1 or we're running (dist)clean @@ -1195,8 +1213,8 @@ push-testing: echo "SSH failed: it's likely that stale content will be served via old gzip files." ######################################################################## -# If we find a copy of the sqlite.org/wasm docs checked out, copy -# certain files over to it, noting that some need automatable edits... +# If we find a copy of https://sqlite.org/wasm checked out, copy +# certain files over to it, applying some automated edits... wasm.docs.home ?= ../../../wasm wasm.docs.found = $(if $(wildcard $(wasm.docs.home)/api-index.md),\ $(wildcard $(wasm.docs.home)),) diff --git a/ext/wasm/dist.make b/ext/wasm/dist.make index 176972fd70..bce26342e6 100644 --- a/ext/wasm/dist.make +++ b/ext/wasm/dist.make @@ -3,12 +3,11 @@ # # Intended to include'd by ./GNUmakefile. # -# 'make dist' rules for creating a distribution archive of the WASM/JS -# pieces, noting that we only build a dist of the built files, not the -# numerous pieces required to build them. +# 'make dist' rules for creating a distribution archive of the SQLite +# WASM/JS deliverables. # -# Use 'make snapshot' to create "snapshot" releases. They use a -# distinctly different zip file and top directory name to distinguish +# Use 'make snapshot' to create "snapshot" releases. They use +# distinctly different zip file and top directory names to distinguish # them from release builds. ####################################################################### MAKEFILE.dist = $(lastword $(MAKEFILE_LIST)) @@ -32,17 +31,17 @@ endif dist-name = $(dist-name-prefix)-TEMP ######################################################################## -# dist.build must be the name of a target which triggers the build of -# the files to be packed into the dist archive. The intention is that -# it be one of (o0, o1, o2, o3, os, oz), each of which uses like-named -# -Ox optimization level flags. The o2 target provides the best -# overall runtime speeds. The oz target provides slightly slower -# speeds (roughly 10%) with significantly smaller WASM file -# sizes. Note that -O2 (the o2 target) results in faster binaries than -# both -O3 and -Os (the o3 and os targets) in all tests run to -# date. Our general policy is that we want the smallest binaries for -# dist zip files, so use the oz build unless there is a compelling -# reason not to. +# $(dist.build) must be the name of a target which triggers the build +# of the files to be packed into the dist archive. The intention is +# that it be one of (o0, o1, o2, o3, os, oz), each of which uses +# like-named -Ox optimization level flags. The o2 target provides the +# best overall runtime speeds. The oz target provides slightly slower +# speeds (roughly 10%) with significantly smaller WASM file sizes. -O2 +# (the o2 target) consistently results in faster binaries than both +# -O3 and -Os (the o3 and os targets) in all tests run to date. Our +# general policy is that we want the smallest binaries for dist zip +# files, so use the oz build unless there is a compelling reason not +# to. dist.build ?= oz dist-dir.top = $(dist-name) @@ -62,10 +61,6 @@ dist.common.extras = \ $(wildcard $(dir.common)/*.css) \ $(dir.common)/SqliteTestUtil.js -#$(info sqlite3-worker1-promiser.mjs = $(sqlite3-worker1-promiser.mjs)) -#$(info sqlite3-worker1.js = $(sqlite3-worker1.js)) -#$(info sqlite3-api.ext.jses = $(sqlite3-api.ext.jses)) -#$(info dist.jswasm.extras = $(dist.jswasm.extras)) .PHONY: dist snapshot # DIST_STRIP_COMMENTS $(call)able to be used in stripping C-style # from the dist copies of certain files. @@ -94,16 +89,19 @@ STRIP_K2.js = $(sqlite3.js) $(sqlite3.mjs) \ # dist's deps must be trimmed to non-generated files or # files which are _not_ cleaned up by the clean target. # -# Note that we require $(bin.version-info) in order to figure out the -# dist file's name, so cannot (without a recursive make) have the -# target name equal to the archive name. +# We require $(bin.version-info) in order to figure out the dist +# file's name, so cannot (without a recursive make) have the target +# name equal to the archive name. # # 2025-01-15: Emsdk 4.0.0 introduces, in its generated code, a regex # which contains the pattern /*. That, of course, confuses any C-style # comment-stripper which is not specifically JS-aware and smart enough # to know that it's in a regex or string literal. Because of that, -# comment-stripping is currently disabled, which means the builds will -# be significantly larger than before. +# comment-stripping was briefly disabled, resulting in functionally +# identical but significantly larger JS files. That issue with the +# comment-stripper has been resolved, but $(apply_comment_stripper) +# can be set to false to disable it if a similar problem arises. +# #apply_comment_stripper = false apply_comment_stripper = true # ^^^ shell command true or false @@ -138,7 +136,7 @@ ifeq (,$(wasm.docs.found)) snapshot: dist @echo "To upload the snapshot build to the wasm docs server:"; \ echo "1) move $(dist-name-prefix)*.zip to the top of a wasm docs checkout."; \ - echo "2) run 'make uv-sync'" + echo "2) From that checkout run 'make uv-sync'" else snapshot: dist @echo "Moving snapshot to [$(wasm.docs.found)]..."; \ @@ -150,5 +148,5 @@ endif # copied into the new $(dist-name) dir. .PHONY: dist-clean clean: dist-clean -dist-clean: +dist-clean: # not to be confused with distclean rm -fr $(dist-name) $(wildcard sqlite-wasm-*.zip) diff --git a/manifest b/manifest index 4b57b0a61c..561e51ce3c 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Use\sPgno\sinstead\sof\sint\sfor\sthe\spgno\sfield\sin\sthe\sDbpageCursor\sobject.\nThe\ssame\smachine\scode\sis\sgenerated,\sbut\susing\san\sunsigned\svalue\sseems\nsafer\sin\sthe\slong\srun.\n[forum:/forumpost/ccec20a858|Forum\spost\sccec20a858]. -D 2025-09-04T09:26:53.665 +C Generic\sdoc\supdates\sin\sext/wasm's\smakefiles.\sNo\sfunctional\schanges. +D 2025-09-04T18:00:53.260 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea @@ -577,7 +577,7 @@ F ext/session/sqlite3session.c 9205e6e8f389ea44a8118082ce3832374da92284a60e4fb3e F ext/session/sqlite3session.h b81e8536ce4b83babafd700f4ff67017804b6c1d71df963b30d3972958e7f4a7 F ext/session/test_session.c 8766b5973a6323934cb51248f621c3dc87ad2a98f023c3cc280d79e7d78d36fb F ext/wasm/EXPORTED_FUNCTIONS.fiddle.in 27450c8b8c70875a260aca55435ec927068b34cef801a96205adb81bdcefc65c -F ext/wasm/GNUmakefile 35e730a01b32481f5483ea5bd72c3d4609e25f34cb5aab9f85eb3eba6f0c4935 +F ext/wasm/GNUmakefile 89e18d6e4783841a5236930b988df27e02317b3ac440a1a5571de4a79df3c8e7 F ext/wasm/README-dist.txt f01081a850ce38a56706af6b481e3a7878e24e42b314cfcd4b129f0f8427066a F ext/wasm/README.md 66ace67ae98a45e4116f2ca5425b716887bcee4d64febee804ff6398e1ae9ec7 F ext/wasm/SQLTester/GNUmakefile e0794f676d55819951bbfae45cc5e8d7818dc460492dc317ce7f0d2eca15caff @@ -628,7 +628,7 @@ F ext/wasm/demo-worker1-promiser.c-pp.html 635cf90685805e21772a5f7a35d1ace80f98a F ext/wasm/demo-worker1-promiser.c-pp.js af168699d3cab1c27ad2364ebe06cd49db300bdbf404e23b00d5742ed52816ba F ext/wasm/demo-worker1.html 2c178c1890a2beb5a5fecb1453e796d067a4b8d3d2a04d65ca2eb1ab2c68ef5d F ext/wasm/demo-worker1.js 08720227e98fa5b44761cf6e219269cee3e9dd0421d8d91459535da776950314 -F ext/wasm/dist.make c29018b4db479a4c170569393e5399f0625446123a7eb6ffb0677495292bb954 +F ext/wasm/dist.make 57f5da2f0de5a297b5a0bc39ffec736380050578240ab24d864c2ff1b3634a3b F ext/wasm/example_extra_init.c 2347cd69d19d839ef4e5e77b7855103a7fe3ef2af86f2e8c95839afd8b05862f F ext/wasm/fiddle.make ea505d11aa2a89551e1693ed4c71ee6a163364ca14f806dda295d0beb26ec0ea F ext/wasm/fiddle/fiddle-worker.js 50d3edf54c0c0e3657e876724ec2c10069f55f3e40af20864d72f6f6e9ad00f8 @@ -2172,8 +2172,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 a4e137de0e82fbba890c2a608578f02f3666d2c25fb76f95ddf2d6a096a30e6c -R 74a121566763b43ba4139274c7ec5d78 -U drh -Z d147c8b5254b99458119dadcc21fa7d0 +P 26ecdde06cce063143144a79c0b4979ed5ec27548da6f127176a420c1c3f17ce +R c906f44fce625506b02efa9aa8f0e11e +U stephan +Z a1c51bbc3308c27ff98d60395e238267 # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index 664d18ba1a..eedd2d7a66 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -26ecdde06cce063143144a79c0b4979ed5ec27548da6f127176a420c1c3f17ce +02721457cea255a5117a46b77cc87d2e09acb64340ce94089c5b5e6edc5b5033 -- 2.47.3