From: stephan Date: Thu, 13 Nov 2025 17:37:40 +0000 (+0000) Subject: Generic makefile cleanups and doc updates. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=388c1da56e7c854b26c1f609d03cb6d5e9898d82;p=thirdparty%2Fsqlite.git Generic makefile cleanups and doc updates. FossilOrigin-Name: e8b34b4178be621102dac165b716283055fad90b3edc2394f56a24f9f0149448 --- diff --git a/ext/wasm/GNUmakefile b/ext/wasm/GNUmakefile index 31737ee60a..e3bb4250e1 100644 --- a/ext/wasm/GNUmakefile +++ b/ext/wasm/GNUmakefile @@ -1,5 +1,6 @@ -####################################################################### -# This GNU makefile creates the canonical sqlite3 WASM builds. +# +# This GNU makefile creates the canonical sqlite3 WASM builds. Plus some +# others. # # This build assumes a Linux platform and is not intended for # general-purpose client-level use, except for creating builds with @@ -10,28 +11,33 @@ # # default, all = build in dev mode # -# o0, o1, o2, o3, os, oz = full clean/rebuild with the -Ox level indicated -# by the target name. Rebuild is necessary for all components to get -# the desired optimization level. +# o0, o1, o2, o3, os, oz = full clean/rebuild with the -Ox level +# indicated by the target name. A clean rebuild is necessary for +# all components to get the desired optimization level. # # dist = create end user deliverables. Add dist.build=oX to build -# with a specific optimization level, where oX is one of the -# above-listed o? or qo? target names. +# with a specific optimization level, where oX is one of the +# above-listed o? target names. # # snapshot = like dist, but uses a zip file name which clearly -# marks it as a prerelease/snapshot build. +# marks it as a prerelease/snapshot build. # # clean = clean up # # Required tools beyond those needed for the canonical builds: # # - Emscripten SDK: https://emscripten.org/docs/getting_started/downloads.html +# # - The bash shell +# # - GNU make, GNU sed, GNU awk, GNU grep (all in the $PATH and without # a "g" prefix like they have on some non-GNU systems) -# - wasm-strip for release builds: https://github.com/WebAssembly/wabt +# +# - wasm-strip for release builds: https://github.com/WebAssembly/wabt. +# It will build without this but the .wasm files will be huge. +# # - InfoZip for 'dist' zip file -######################################################################## +# default: all MAKEFILE = $(lastword $(MAKEFILE_LIST)) CLEAN_FILES = @@ -231,6 +237,33 @@ $(3): $$(MAKEFILE_LIST) $$(bin.c-pp) $(2) CLEAN_FILES += $(3) endef + +# +# The various -D... values used by *.c-pp.js include: +# +# -Dtarget:es6-module: for all ESM module builds +# +# -Dtarget:node: for node.js builds +# +# -Dtarget:es6-module -Dtarget:es6-bundler-friendly: intended for +# "bundler-friendly" ESM module build. These have some restrictions +# on how URL() objects are constructed in some contexts: URLs which +# refer to files which are part of this project must be referenced +# as string literals so that bundlers' static-analysis tools can +# find those files and include them in their bundles. +# +# -Dtarget:es6-module -Dtarget:node: is intended for use by node.js +# for node.js, as opposed to by node.js on behalf of a +# browser. Mixing -sENVIRONMENT=web and -sENVIRONMENT=node leads to +# ambiguity and confusion on node's part, as it's unable to +# reliably determine whether the target is a browser or node. +# +# To repeat: all node.js builds are 100% untested and unsupported. +# +# Most c-pp.D.X are set via $(bin.mkwasmbuilds) and X is a build name. +# Those make rules reference c-pp.D.64bit, so it should be defined in +# advance. +# c-pp.D.64bit = -Dbits64 # @@ -248,6 +281,7 @@ c-pp.D.64bit = -Dbits64 # # This is intended to be used in makefile targets which generate an # Emscripten module and where $@ is the module's .js/.mjs file. +# b.strip-js-emcc-bindings = \ echo '$(1) $(emo.bug) (disabled because it breaks emsdk 4.0.16+)' @@ -269,6 +303,7 @@ b.strip-js-emcc-bindings = \ # $(sqlite3.canonical.c) must point to the sqlite3.c in # the sqlite3 canonical source tree, as that source file # is required for certain utility and test code. +# sqlite3.canonical.c = $(dir.top)/sqlite3.c sqlite3.c ?= $(firstword $(wildcard $(dir.top)/sqlite3-see.c) $(sqlite3.canonical.c)) sqlite3.h = $(dir $(sqlite3.c))/sqlite3.h @@ -278,24 +313,26 @@ sqlite3.h = $(dir $(sqlite3.c))/sqlite3.h # 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 # cleanup process for the dist build to work properly. +# bin.version-info = ./version-info $(bin.version-info): $(dir.tool)/version-info.c $(sqlite3.h) $(dir.top)/Makefile $(CC) -o $@ -I$(dir $(sqlite3.h)) $(dir.tool)/version-info.c t-version-info: $(bin.version-info) DISTCLEAN_FILES += $(bin.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 # block(s), which contain the license header and version info. +# bin.stripccomments = $(dir.tool)/stripccomments $(bin.stripccomments): $(bin.stripccomments).c $(MAKEFILE) $(CC) -o $@ $< t-stripccomments: $(bin.stripccomments) DISTCLEAN_FILES += $(bin.stripccomments) - ifeq (1,$(MAKING_CLEAN)) SQLITE_C_IS_SEE = 0 else @@ -323,7 +360,7 @@ endif # undefine barebones # relatively new gmake feature, not ubiquitous # -# It's important that sqlite3.h be built to completion before any +# It's important that sqlite3.[ch] 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. However, that makes # the whole build non-parallelizable because everything has a dep on @@ -340,8 +377,10 @@ $(sqlite3.h): # $(MAKE) -C $(dir.top) sqlite3.c $(sqlite3.c): $(sqlite3.h) +# # Common options for building sqlite3-wasm.c and speedtest1.c. # Explicit ENABLEs... +# SQLITE_OPT.common = \ -DSQLITE_THREADSAFE=0 \ -DSQLITE_TEMP_STORE=2 \ @@ -358,11 +397,15 @@ SQLITE_OPT.common = \ # removing them from this list will serve only to break the speedtest1 # builds. +# # Currently always needed but TODO is paring tester1.c-pp.js down # to be able to run without this: +# SQLITE_OPT.common += -DSQLITE_WASM_ENABLE_C_TESTS +# # Extra flags for full-featured builds... +# SQLITE_OPT.full-featured = \ -DSQLITE_ENABLE_BYTECODE_VTAB \ -DSQLITE_ENABLE_DBPAGE_VTAB \ @@ -419,13 +462,14 @@ else # -DSQLITE_OMIT_WINDOWFUNC endif +# #SQLITE_OPT += -DSQLITE_DEBUG # Enabling SQLITE_DEBUG will break sqlite3_wasm_vfs_create_file() # (and thus sqlite3_js_vfs_create_file()). Those functions are # deprecated and alternatives are in place, but this crash behavior # can be used to find errant uses of sqlite3_js_vfs_create_file() # in client code. -######################################################################## +# # The following flags are hard-coded into sqlite3-wasm.c and cannot be # modified via the build process: # @@ -434,10 +478,9 @@ endif # SQLITE_OMIT_DEPRECATED # SQLITE_OMIT_UTF16 # SQLITE_OMIT_SHARED_CACHE -######################################################################## - +# -######################################################################## +# # Adding custom C code via sqlite3_wasm_extra_init.c: # # If the canonical build process finds the file @@ -458,7 +501,7 @@ endif # make sqlite3_wasm_extra_init.c=my_custom_stuff.c # # See example_extra_init.c for an example implementation. -######################################################################## +# sqlite3_wasm_extra_init.c ?= $(wildcard sqlite3_wasm_extra_init.c) cflags.wasm_extra_init = ifneq (,$(sqlite3_wasm_extra_init.c)) @@ -479,7 +522,7 @@ endif # WASM_CUSTOM_INSTANTIATE = 1 -######################################################################## +# # $(bin.c-pp): a minimal text file preprocessor. Like C's but much # less so. # @@ -510,6 +553,7 @@ WASM_CUSTOM_INSTANTIATE = 1 # # -D... flags which should be included in all invocations should be # appended to $(b.c-pp.target.flags). +# bin.c-pp = ./c-pp-lite $(bin.c-pp): c-pp-lite.c $(sqlite3.c) $(MAKEFILE) $(CC) -O0 -o $@ c-pp-lite.c $(sqlite3.c) '-DCMPP_DEFAULT_DELIM="//#"' -I$(dir.top) \ @@ -522,6 +566,7 @@ ifeq (1,$(SQLITE_C_IS_SEE)) b.c-pp.target.flags += -Denable-see endif +# # cflags.common = C compiler flags for all builds cflags.common = -I. -I$(dir $(sqlite3.c)) -std=c99 -fPIC # emcc.WASM_BIGINT = 1 for BigInt (C int64) support, else 0. The API @@ -529,13 +574,14 @@ cflags.common = -I. -I$(dir $(sqlite3.c)) -std=c99 -fPIC # _are not tested_ on any regular basis. emcc.WASM_BIGINT ?= 1 emcc.MEMORY64 ?= 0 -######################################################################## +# # https://emscripten.org/docs/tools_reference/settings_reference.html#memory64 # # 64-bit build requires wasm-strip 1.0.36 (maybe 1.0.35, but not # 1.0.34) or will fail to strip with "tables may not be 64-bit". -######################################################################## +# +# # emcc_opt = optimization-related flags. These are primarily used by # the various oX targets. build times for -O levels higher than 0 are # painful at dev-time. @@ -547,14 +593,17 @@ emcc.MEMORY64 ?= 0 # -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 emcc_opt ?= -Oz endif +# # When passing emcc_opt from the CLI, += and re-assignment have no # effect, so emcc_opt+=-g3 doesn't work. So... +# emcc_opt_full = $(emcc_opt) -g3 # ^^^ ALWAYS use -g3. See below for why. # @@ -581,11 +630,12 @@ 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 smaller deliverable size is a priority. -######################################################################## +# -######################################################################## +# # EXPORTED_FUNCTIONS.* = files for use with Emscripten's # -sEXPORTED_FUNCTION flag. +# EXPORTED_FUNCTIONS.api.in = $(dir.api)/EXPORTED_FUNCTIONS.c-pp EXPORTED_FUNCTIONS.api = $(dir.tmp)/EXPORTED_FUNCTIONS.api EXPORTED_FUNCTIONS.c-pp.flags = @@ -597,8 +647,9 @@ $(eval $(call b.c-pp.target,filter,\ $(EXPORTED_FUNCTIONS.api),\ $(EXPORTED_FUNCTIONS.c-pp.flags))) -######################################################################## +# # emcc flags for .c/.o/.wasm/.js. +# emcc.flags = ifeq (1,$(emcc.verbose)) emcc.flags += -v @@ -686,9 +737,9 @@ ifeq (,$(emcc.INITIAL_MEMORY.$(emcc.INITIAL_MEMORY))) $(error emcc.INITIAL_MEMORY must be one of: 4, 8, 16, 32, 64, 96, 128 (megabytes)) endif emcc.jsflags += -sINITIAL_MEMORY=$(emcc.INITIAL_MEMORY.$(emcc.INITIAL_MEMORY)) +# # /INITIAL_MEMORY -######################################################################## -#emcc.jsflags += -sMEMORY64=$(emcc.MEMORY64) +# emcc.jsflags += $(emcc.environment) emcc.jsflags += -sSTACK_SIZE=512KB @@ -697,7 +748,8 @@ emcc.jsflags += -sSTACK_SIZE=512KB # VFS, which requires twice that for its xRead() and xWrite() methods. # 2023-03: those methods have since been adapted to use a malloc()'d # buffer. -######################################################################## + +# # $(sqlite3.js.init-func) is the name Emscripten assigns our exported # module init/load function. This symbol name is hard-coded in # $(extern-post-js.js) as well as in numerous docs. @@ -737,7 +789,7 @@ emcc.jsflags += -sLLD_REPORT_UNDEFINED #emcc.jsflags += --experimental-pic --unresolved-symbols=ingore-all --import-undefined #emcc.jsflags += --unresolved-symbols=ignore-all -######################################################################## +# # -sSINGLE_FILE: # https://github.com/emscripten-core/emscripten/blob/main/src/settings.js # @@ -746,12 +798,7 @@ emcc.jsflags += -sLLD_REPORT_UNDEFINED # cannot wasm-strip the binary before it gets encoded into the JS # file. The result is that the generated JS file is, because of the # -g3 debugging info, _huge_. -######################################################################## - - -sqlite3.wasm = $(dir.dout)/sqlite3.wasm -sqlite3-wasm.c = $(dir.api)/sqlite3-wasm.c -sqlite3-wasm.c.in = $(sqlite3-wasm.c) $(sqlite3_wasm_extra_init.c) +# # # b.call.patch-export-default is used by mkwasmbuilds.c and the @@ -794,30 +841,6 @@ if [ x1 = x$(1) ]; then \ fi endef -# -# The various -D... values used by *.c-pp.js include: -# -# -Dtarget:es6-module: for all ESM module builds -# -# -Dtarget:node: for node.js builds -# -# -Dtarget:es6-module -Dtarget:es6-bundler-friendly: intended for -# "bundler-friendly" ESM module build. These have some restrictions -# on how URL() objects are constructed in some contexts: URLs which -# refer to files which are part of this project must be referenced -# as string literals so that bundlers' static-analysis tools can -# find those files and include them in their bundles. -# -# -Dtarget:es6-module -Dtarget:node: is intended for use by node.js -# for node.js, as opposed to by node.js on behalf of a -# browser. Mixing -sENVIRONMENT=web and -sENVIRONMENT=node leads to -# ambiguity and confusion on node's part, as it's unable to -# reliably determine whether the target is a browser or node. -# -# To repeat: all node.js builds are 100% untested and unsupported. -# -######################################################################## - # # Inputs/outputs for the sqlite3-api.js family. # @@ -1020,6 +1043,14 @@ cflags.wasmfs = -DSQLITE_ENABLE_WASMFS # end wasmfs (the rest is in mkwasmbuilds.c) # +# +# +# +sqlite3-wasm.c = $(dir.api)/sqlite3-wasm.c +# List of input files for compiling $(sqlite3-wasm.c). That file +# #include's sqlite3.c directly, so it's implicitly includes here. +sqlite3-wasm.c.in = $(sqlite3-wasm.c) $(sqlite3_wasm_extra_init.c) + # # $(bin.mkwb) is used for generating much of the makefile code for the # various wasm builds. It used to be generated in this makefile via a @@ -1137,6 +1168,8 @@ $(dir.dout)/sqlite3-opfs-async-proxy.js: $(dir.api)/sqlite3-opfs-async-proxy.js # we don't otherwise have a great place to attach them such that # they're always copied when we need them. # +# The var $(out.$(B).js) comes from $(bin.mkwasmbuilds). +# $(foreach B,$(b.names),$(eval $(out.$(B).js): $(sqlite3.ext.js))) # # b-all: builds all available js/wasm builds. @@ -1236,9 +1269,11 @@ $(eval $(call gen-st64,speedtest1-worker.js,speedtest1-worker-64bit.js,speedtest # # To create those, we filter tester1.c-pp.js/html with $(bin.c-pp)... +# # tester1.js variants: +# define gen-tester1.js -# $1 = build name to have dep on +# $1 = build name to have a dep on # $2 = suffix for tester1SUFFIX JS # $3 = $(bin.c-pp) flags $(call b.c-pp.target,test,tester1.c-pp.js,tester1$(2),$(3)) @@ -1247,20 +1282,18 @@ tester1-$(1): tester1$(2) tester1: tester1$(2) endef -$(eval $(call gen-tester1.js,vanilla,.js, \ - $(c-pp.D.vanilla) \ - -Dsqlite3.js=$(dir.dout)/sqlite3.js)) -$(eval $(call gen-tester1.js,vanilla64,-64bit.js, \ - $(c-pp.D.vanilla64) \ - -Dsqlite3.js=$(dir.dout)/sqlite3-64bit.js)) -$(eval $(call gen-tester1.js,esm,.mjs, \ - $(c-pp.D.esm) \ - -Dsqlite3.js=$(dir.dout)/sqlite3.mjs)) -$(eval $(call gen-tester1.js,esm64,-64bit.mjs, \ - $(c-pp.D.esm64) \ - -Dsqlite3.js=$(dir.dout)/sqlite3-64bit.mjs)) +$(eval $(call gen-tester1.js,vanilla,.js,\ + $(c-pp.D.vanilla) -Dsqlite3.js=$(dir.dout)/sqlite3.js)) +$(eval $(call gen-tester1.js,vanilla64,-64bit.js,\ + $(c-pp.D.vanilla64) -Dsqlite3.js=$(dir.dout)/sqlite3-64bit.js)) +$(eval $(call gen-tester1.js,esm,.mjs,\ + $(c-pp.D.esm) -Dsqlite3.js=$(dir.dout)/sqlite3.mjs)) +$(eval $(call gen-tester1.js,esm64,-64bit.mjs,\ + $(c-pp.D.esm64) -Dsqlite3.js=$(dir.dout)/sqlite3-64bit.mjs)) +# # tester1.html variants: +# define gen-tester1.html # $1 = build name to have a dep on # $2 = filename suffix: empty, -64bit, -esm, esm-64bit @@ -1295,9 +1328,11 @@ $(eval $(call gen-tester1.html,esm64,-esm-64bit,\ -Dtester1.js=tester1-64bit.mjs \ -Dsqlite3.js=$(dir.dout)/sqlite3-64bit.mjs)) -# tester1-worker.html variants: -# There is no ESM variant of this file. Instead, that page accepts a -# ?esm URL flag to switch to ESM mode. +# +# tester1-worker.html variants: There is no ESM variant of this +# file. Instead, that page accepts the ?esm URL flag to switch to ESM +# mode. +# $(eval $(call b.c-pp.target,test,tester1-worker.c-pp.html,\ tester1-worker.html,-Dbitness=32)) $(eval $(call b.c-pp.target,test,tester1-worker.c-pp.html,\ @@ -1307,8 +1342,9 @@ tester1-worker.html: tester1.mjs tester1-worker-64bit.html: tester1-64bit.mjs all: tester1 +# # end tester1 -######################################################################## +# # # Convenience rules to rebuild with various -Ox levels. Much @@ -1319,6 +1355,7 @@ all: tester1 # # Achtung: build times with anything higher than -O0 are somewhat # painful, which is why -O0 is the default. +# .PHONY: o0 o1 o2 o3 os oz emcc-opt-extra = #ifeq (1,$(wasm-bare-bones)) @@ -1369,7 +1406,9 @@ push-testing: ssh wasm-testing 'cd $(wasm-testing.dir) && bash .gzip' || \ echo "SSH failed: it's likely that stale content will be served via old gzip files." +# # build everything needed by push-testing with -Oz +# .PHONY: for-testing for-testing: emcc_opt=-Oz for-testing: loud=1 @@ -1454,9 +1493,9 @@ endif dist-name-prefix = sqlite-wasm$(dist-name-extra) .PHONY: dist dist: - ./mkdist.sh $(dist-name-prefix) + $(bin.bash) ./mkdist.sh $(dist-name-prefix) snapshot: - ./mkdist.sh $(dist-name-prefix) --snapshot + $(bin.bash) ./mkdist.sh $(dist-name-prefix) --snapshot endif # ^^^ making dist/snapshot CLEAN_FILES += $(wildcard sqlite-wasm-*.zip) diff --git a/manifest b/manifest index 6a4791b36e..36bdd47c4a 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Internal\sdoc\sfix\s(renamed\sfile). -D 2025-11-13T16:38:45.208 +C Generic\smakefile\scleanups\sand\sdoc\supdates. +D 2025-11-13T17:37:40.529 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea @@ -575,7 +575,7 @@ F ext/session/sessionwor.test 6fd9a2256442cebde5b2284936ae9e0d54bde692d0f5fd009e F ext/session/sqlite3session.c b3de195ce668cace9b324599bf6255a70290cbfb5451e826e946f3aee6e64c54 F ext/session/sqlite3session.h 7404723606074fcb2afdc6b72c206072cdb2b7d8ba097ca1559174a80bc26f7a F ext/session/test_session.c 8766b5973a6323934cb51248f621c3dc87ad2a98f023c3cc280d79e7d78d36fb -F ext/wasm/GNUmakefile 74c73254fb44c82d517a8907da9866d5d3ef1a533addaeb4322f470e0fb81ba3 +F ext/wasm/GNUmakefile a8ed9170c5f1ac281e8111fa04f4fcc80358b947be098d3fe120fe724b7bdfde F ext/wasm/README-dist.txt f01081a850ce38a56706af6b481e3a7878e24e42b314cfcd4b129f0f8427066a F ext/wasm/README.md 2e87804e12c98f1d194b7a06162a88441d33bb443efcfe00dc6565a780d2f259 F ext/wasm/SQLTester/GNUmakefile e0794f676d55819951bbfae45cc5e8d7818dc460492dc317ce7f0d2eca15caff @@ -2167,8 +2167,8 @@ F tool/version-info.c 33d0390ef484b3b1cb685d59362be891ea162123cea181cb8e6d2cf6dd F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7 F tool/warnings.sh d924598cf2f55a4ecbc2aeb055c10bd5f48114793e7ba25f9585435da29e7e98 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f -P c566c653e4f55afa0660e819ed5b1fd96cb9b24bc78c333adcd8825331a9dd26 -R 72e80fd8c96ca5ade35d9193d47f4d81 +P cb8fb01fe19ba3af536a662aed894b2b0eb2463c8d34c644c498234fd82122f3 +R 9c409c36a1cdc118cb78bcb027efe59a U stephan -Z 2607c63c69d5b1189f154cd6eca8379a +Z b596efc51c44a0649133e19d870d692f # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index 822b0d1e6f..527950af6f 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -cb8fb01fe19ba3af536a662aed894b2b0eb2463c8d34c644c498234fd82122f3 +e8b34b4178be621102dac165b716283055fad90b3edc2394f56a24f9f0149448