#######################################################################
-# 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:
#
# - 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
# 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
#
# 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.
########################################################################
########################################################################
# 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.
# -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
# 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
# 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 $@ $<
$(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)
########################################################################
# 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
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)),)
#
# 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))
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)
$(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.
# 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
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)]..."; \
# 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)
-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
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
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
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.
projects / thirdparty / sqlite.git / commitdiff
