ext/wasm/GNUmakefile

   1 #######################################################################
   2 # This GNU makefile drives the build of the sqlite3 WASM
   3 # components. It is not part of the canonical build process.
   4 #
   5 # This build assumes a Linux platform and is not intended for
   6 # general-purpose client-level use, except for creating builds with
   7 # custom configurations. It is primarily intended for the sqlite
   8 # project's own development of the JS/WASM components.
   9 #
  10 # Primary targets:
  11 #
  12 #  default, all = build in dev mode
  13 #
  14 #  o0, o1, o2, o3, os, oz = full clean/rebuild with the -Ox level indicated
  15 #      by the target name. Rebuild is necessary for all components to get
  16 #      the desired optimization level.
  17 #
  18 #  quick, q = do just a minimal build (sqlite3.js/wasm, tester1) for
  19 #      faster development-mode turnaround.
  20 #
  21 #  qo2, qoz = a combination of quick+o2/oz.
  22 #
  23 #  dist = create end user deliverables. Add dist.build=oX to build
  24 #      with a specific optimization level, where oX is one of the
  25 #      above-listed o? or qo? target names.
  26 #
  27 #  snapshot = like dist, but uses a zip file name which clearly
  28 #      marks it as a prerelease/snapshot build.
  29 #
  30 #  clean = clean up
  31 #
  32 # Required tools beyond those needed for the canonical builds:
  33 #
  34 # - Emscripten SDK: https://emscripten.org/docs/getting_started/downloads.html
  35 # - The bash shell
  36 # - GNU make, GNU sed, GNU awk, GNU grep (all in the $PATH)
  37 # - wasm-strip for release builds: https://github.com/WebAssembly/wabt
  38 # - InfoZip for 'dist' zip file
  39 ########################################################################
  40 #
  41 # Significant TODOs for this build include, but are not necessarily
  42 # limited to:
  43 #
  44 # 1) Consolidate the code generation for sqlite3*.*js into a script
  45 #    which generates the makefile code, rather than using $(call) and
  46 #    $(eval), or at least centralize the setup of the numerous vars
  47 #    related to each build variant (vanilla, esm, bundler-friendly).
  48 #
  49 SHELL := $(shell which bash 2>/dev/null)
  50 MAKEFILE := $(lastword $(MAKEFILE_LIST))
  51 CLEAN_FILES :=
  52 DISTCLEAN_FILES := ./--dummy--
  53 default: all
  54 release: oz
  55
  56 # Emscripten SDK home dir and related binaries...
  57 EMSDK_HOME ?= $(word 1,$(wildcard $(HOME)/emsdk $(HOME)/src/emsdk))
  58 emcc.bin ?= $(word 1,$(wildcard $(EMSDK_HOME)/upstream/emscripten/emcc) $(shell which emcc))
  59 ifeq (,$(emcc.bin))
  60   $(error Cannot find emcc.)
  61 endif
  62 emcc.version := $(shell "$(emcc.bin)" --version | sed -n 1p \
  63                   | sed -e 's/^.* \([3-9][^ ]*\) .*$$/\1/;')
  64 ifeq (,$(emcc.version))
  65   $(warning Cannot determine emcc version. This might unduly impact build flags.)
  66 else
  67   $(info using emcc version [$(emcc.version)])
  68 endif
  69 emcc.version := $(shell "$(emcc.bin)" --version | sed -n 1p \
  70                   | sed -e 's/^.* \([3-9][^ ]*\) .*$$/\1/;')
  71 ifeq (,$(emcc.version))
  72   $(warning Cannot determine emcc version. This might unduly impact build flags.)
  73 else
  74   $(info using emcc version [$(emcc.version)])
  75 endif
  76
  77 wasm-strip ?= $(shell which wasm-strip 2>/dev/null)
  78 ifeq (,$(filter clean,$(MAKECMDGOALS)))
  79 ifeq (,$(wasm-strip))
  80   $(info WARNING: *******************************************************************)
  81   $(info WARNING: builds using -O2/-O3/-Os/-Oz will minify WASM-exported names,)
  82   $(info WARNING: breaking _All The Things_. The workaround for that is to build)
  83   $(info WARNING: with -g3 (which explodes the file size) and then strip the debug)
  84   $(info WARNING: info after compilation, using wasm-strip, to shrink the wasm file.)
  85   $(info WARNING: wasm-strip was not found in the PATH so we cannot strip those.)
  86   $(info WARNING: If this build uses any optimization level higher than -O1 then)
  87   $(info WARNING: the ***resulting JS code WILL NOT BE USABLE***.)
  88   $(info WARNING: wasm-strip is part of the wabt package:)
  89   $(info WARNING:    https://github.com/WebAssembly/wabt)
  90   $(info WARNING: on Ubuntu-like systems it can be installed with:)
  91   $(info WARNING:    sudo apt install wabt)
  92   $(info WARNING: *******************************************************************)
  93 endif
  94 endif # 'make clean' check
  95
  96 ifeq (,$(wasm-strip))
  97   maybe-wasm-strip = echo "not wasm-stripping"
  98 else
  99   maybe-wasm-strip = $(wasm-strip)
 100 endif
 101
 102 dir.top := ../..
 103 # Reminder: some Emscripten flags require absolute paths but we want
 104 # relative paths for most stuff simply to reduce noise. The
 105 # $(abspath...) GNU make function can transform relative paths to
 106 # absolute.
 107 dir.wasm := $(patsubst %/,%,$(dir $(MAKEFILE)))
 108 dir.api := api
 109 dir.jacc := jaccwabyt
 110 dir.common := common
 111 dir.fiddle := fiddle
 112 dir.tool := $(dir.top)/tool
 113 CLEAN_FILES += *~ $(dir.jacc)/*~ $(dir.api)/*~ $(dir.common)/*~ $(dir.fiddle)/*~
 114
 115 ########################################################################
 116 # dir.dout = output dir for deliverables.
 117 #
 118 # MAINTENANCE REMINDER: the output .js and .wasm files of certain emcc
 119 # buildables must be in _this_ dir, rather than a subdir, or else
 120 # parts of the generated code get confused and cannot load
 121 # property. Specifically, when X.js loads X.wasm, whether or not X.js
 122 # uses the correct path for X.wasm depends on how it's loaded: an HTML
 123 # script tag will resolve it intuitively, whereas a Worker's call to
 124 # importScripts() will not.  That's a fundamental incompatibility with
 125 # how URL resolution in JS happens between those two contexts. See:
 126 #
 127 # https://zzz.buzz/2017/03/14/relative-uris-in-web-development/
 128 #
 129 # We unfortunately have no way, from Worker-initiated code, to
 130 # automatically resolve the path from X.js to X.wasm.
 131 #
 132 # We have an "only slightly unsightly" solution for our main builds
 133 # but it does not work for the WASMFS builds, so those builds have to
 134 # be built to _this_ directory and can only run when the client app is
 135 # loaded from the same directory.
 136 dir.dout := $(dir.wasm)/jswasm
 137 # dir.tmp = output dir for intermediary build files, as opposed to
 138 # end-user deliverables.
 139 dir.tmp := $(dir.wasm)/bld
 140 CLEAN_FILES += $(dir.tmp)/* $(dir.dout)/*
 141 ifeq (,$(wildcard $(dir.dout)))
 142   dir._tmp := $(shell mkdir -p $(dir.dout))
 143 endif
 144 ifeq (,$(wildcard $(dir.tmp)))
 145   dir._tmp := $(shell mkdir -p $(dir.tmp))
 146 endif
 147
 148 sqlite3.c := $(dir.top)/sqlite3.c
 149 sqlite3.h := $(dir.top)/sqlite3.h
 150 # Most SQLITE_OPT flags are set in sqlite3-wasm.c but we need them
 151 # made explicit here for building speedtest1.c.
 152 SQLITE_OPT = \
 153   -DSQLITE_ENABLE_FTS5 \
 154   -DSQLITE_ENABLE_RTREE \
 155   -DSQLITE_ENABLE_EXPLAIN_COMMENTS \
 156   -DSQLITE_ENABLE_UNKNOWN_SQL_FUNCTION \
 157   -DSQLITE_ENABLE_STMTVTAB \
 158   -DSQLITE_ENABLE_DBPAGE_VTAB \
 159   -DSQLITE_ENABLE_DBSTAT_VTAB \
 160   -DSQLITE_ENABLE_BYTECODE_VTAB \
 161   -DSQLITE_ENABLE_OFFSET_SQL_FUNC \
 162   -DSQLITE_OMIT_LOAD_EXTENSION \
 163   -DSQLITE_OMIT_DEPRECATED \
 164   -DSQLITE_OMIT_UTF16 \
 165   -DSQLITE_OMIT_SHARED_CACHE \
 166   -DSQLITE_OMIT_WAL \
 167   -DSQLITE_THREADSAFE=0 \
 168   -DSQLITE_TEMP_STORE=3 \
 169   -DSQLITE_OS_KV_OPTIONAL=1 \
 170   '-DSQLITE_DEFAULT_UNIX_VFS="unix-none"' \
 171   -DSQLITE_USE_URI=1 \
 172   -DSQLITE_WASM_ENABLE_C_TESTS
 173
 174 $(sqlite3.c) $(sqlite3.h):
 175         $(MAKE) -C $(dir.top) sqlite3.c
 176
 177 .PHONY: clean distclean
 178 clean:
 179         -rm -f $(CLEAN_FILES)
 180 distclean: clean
 181         -rm -f $(DISTCLEAN_FILES)
 182
 183 ifeq (release,$(filter release,$(MAKECMDGOALS)))
 184   ifeq (,$(wasm-strip))
 185     $(error Cannot make release-quality binary because wasm-strip is not available. \
 186             See notes in the warning above)
 187   endif
 188 else
 189   $(info Development build. Use '$(MAKE) release' for a smaller release build.)
 190 endif
 191
 192 # bin.version-info = binary to output various sqlite3 version info for
 193 # embedding in the JS files and in building the distribution zip file.
 194 # It must NOT be in $(dir.tmp) because we need it to survive the
 195 # cleanup process for the dist build to work properly.
 196 bin.version-info := $(dir.wasm)/version-info
 197 $(bin.version-info): $(dir.wasm)/version-info.c $(sqlite3.h) $(MAKEFILE)
 198         $(CC) -O0 -I$(dir.top) -o $@ $<
 199 DISTCLEAN_FILES += $(bin.version-info)
 200
 201 # bin.stripcomments is used for stripping C/C++-style comments from JS
 202 # files. The JS files contain large chunks of documentation which we
 203 # don't need for all builds. That app's -k flag is of particular
 204 # importance here, as it allows us to retain the opening comment
 205 # blocks, which contain the license header and version info.
 206 bin.stripccomments := $(dir.tool)/stripccomments
 207 $(bin.stripccomments): $(bin.stripccomments).c $(MAKEFILE)
 208         $(CC) -o $@ $<
 209 DISTCLEAN_FILES += $(bin.stripccomments)
 210
 211
 212 ########################################################################
 213 # C-PP.FILTER: a $(call)able to transform $(1) to $(2) via ./c-pp -f
 214 # $(1) ...
 215 #
 216 # Historical notes:
 217 #
 218 # - We first attempted to use gcc and/or clang to preprocess JS files
 219 #   in the same way we would normally do C files, but C-specific quirks
 220 #   of each makes that untennable.
 221 #
 222 # - We implemented c-pp.c (the C-Minus Pre-processor) as a custom
 223 #   generic/file-format-agnostic preprocessor to enable us to pack
 224 #   code for different target builds into the same JS files. Most
 225 #   notably, some ES6 module (a.k.a. ESM) features cannot legally be
 226 #   referenced at all in non-ESM code, e.g.  the "import" and "export"
 227 #   keywords. This preprocessing step permits us to swap out sections
 228 #   of code where necessary for ESM and non-ESM (a.k.a. vanilla JS)
 229 #   require different implementations. The alternative to such
 230 #   preprocessing, would be to have separate source files for ES6
 231 #   builds, which would have a higher maintenance burden than c-pp.c
 232 #   seems likely to.
 233 #
 234 # c-pp.c was written specifically for the sqlite project's JavaScript
 235 # builds but is maintained as a standalone project:
 236 # https://fossil.wanderinghorse.net/r/c-pp
 237 bin.c-pp := ./c-pp
 238 $(bin.c-pp): c-pp.c $(sqlite3.c) $(MAKEFILE)
 239         $(CC) -O0 -o $@ c-pp.c $(sqlite3.c) '-DCMPP_DEFAULT_DELIM="//#"' -I$(dir.top) \
 240                 -DSQLITE_OMIT_LOAD_EXTENSION -DSQLITE_OMIT_DEPRECATED -DSQLITE_OMIT_UTF16 \
 241                 -DSQLITE_OMIT_SHARED_CACHE -DSQLITE_OMIT_WAL -DSQLITE_THREADSAFE=0 \
 242                 -DSQLITE_TEMP_STORE=3
 243 define C-PP.FILTER
 244 # Create $2 from $1 using $(bin.c-pp)
 245 # $1 = Input file: c-pp -f $(1).js
 246 # $2 = Output file: c-pp -o $(2).js
 247 # $3 = optional c-pp -D... flags
 248 $(2): $(1) $$(MAKEFILE) $$(bin.c-pp)
 249         $$(bin.c-pp) -f $(1) -o $$@ $(3)
 250 CLEAN_FILES += $(2)
 251 endef
 252 # /end C-PP.FILTER
 253 ########################################################################
 254
 255 # cflags.common = C compiler flags for all builds
 256 cflags.common :=  -I. -I.. -I$(dir.top)
 257 # emcc.WASM_BIGINT = 1 for BigInt (C int64) support, else 0.  The API
 258 # disables certain features if BigInt is not enabled and such builds
 259 # _are not tested_ on any regular basis.
 260 emcc.WASM_BIGINT ?= 1
 261
 262 # emcc_opt = optimization-related flags. These are primarily used by
 263 # the various oX targets. build times for -O levels higher than 0 are
 264 # painful at dev-time.
 265 emcc_opt ?= -O0
 266
 267 # When passing emcc_opt from the CLI, += and re-assignment have no
 268 # effect, so emcc_opt+=-g3 doesn't work. So...
 269 emcc_opt_full := $(emcc_opt) -g3
 270 # ^^^ ALWAYS use -g3. See below for why.
 271 #
 272 # ^^^ -flto improves runtime speed at -O0 considerably but doubles
 273 # build time.
 274 #
 275 # ^^^^ -O3, -Oz, -Os minify symbol names and there appears to be no
 276 # way around that except to use -g3, but -g3 causes the binary file
 277 # size to absolutely explode (approx. 5x larger). This minification
 278 # utterly breaks the resulting module, making it unsable except as
 279 # self-contained/self-referential-only code, as ALL of the exported
 280 # symbols get minified names.
 281 #
 282 # However, we have an option for using -Oz or -Os:
 283 #
 284 # Build with (-Os -g3) or (-Oz -g3) then use wasm-strip, from the wabt
 285 # tools package (https://github.com/WebAssembly/wabt), to strip the
 286 # debugging symbols. That results in a small build with unmangled
 287 # symbol names. -Oz gives ever-so-slightly better compression than
 288 # -Os: not quite 1% in some completely unscientific tests. Runtime
 289 # speed for the unit tests is all over the place either way so it's
 290 # difficult to say whether -Os gives any speed benefit over -Oz.
 291 #
 292 # Much practice has demonstrated that -O2 consistently gives the best
 293 # runtime speeds, but not by a large enough factor to rule out use of
 294 # -Oz when small deliverable size is a priority.
 295 ########################################################################
 296
 297 # EXPORTED_FUNCTIONS.* = files for use with Emscripten's
 298 # -sEXPORTED_FUNCTION flag.
 299 EXPORTED_FUNCTIONS.api.in := $(abspath $(dir.api)/EXPORTED_FUNCTIONS.sqlite3-api)
 300 EXPORTED_FUNCTIONS.api := $(dir.tmp)/EXPORTED_FUNCTIONS.api
 301 $(EXPORTED_FUNCTIONS.api): $(EXPORTED_FUNCTIONS.api.in) $(MAKEFILE)
 302         cp $(EXPORTED_FUNCTIONS.api.in) $@
 303
 304 # sqlite3-license-version.js = generated JS file with the license
 305 # header and version info.
 306 sqlite3-license-version.js := $(dir.tmp)/sqlite3-license-version.js
 307 # sqlite3-license-version-header.js = JS file containing only the
 308 # license header.
 309 sqlite3-license-version-header.js := $(dir.api)/sqlite3-license-version-header.js
 310 # sqlite3-api-build-version.js = generated JS file which populates the
 311 # sqlite3.version object using $(bin.version-info).
 312 sqlite3-api-build-version.js := $(dir.tmp)/sqlite3-api-build-version.js
 313 # sqlite3-api.jses = the list of JS files which make up
 314 # $(sqlite3-api.js.in), in the order they need to be assembled.
 315 sqlite3-api.jses := $(sqlite3-license-version.js)
 316 sqlite3-api.jses += $(dir.api)/sqlite3-api-prologue.js
 317 sqlite3-api.jses += $(dir.common)/whwasmutil.js
 318 sqlite3-api.jses += $(dir.jacc)/jaccwabyt.js
 319 sqlite3-api.jses += $(dir.api)/sqlite3-api-glue.js
 320 sqlite3-api.jses += $(sqlite3-api-build-version.js)
 321 sqlite3-api.jses += $(dir.api)/sqlite3-api-oo1.js
 322 sqlite3-api.jses += $(dir.api)/sqlite3-api-worker1.js
 323 sqlite3-api.jses += $(dir.api)/sqlite3-v-helper.js
 324 sqlite3-api.jses += $(dir.api)/sqlite3-vfs-opfs.c-pp.js
 325 sqlite3-api.jses += $(dir.api)/sqlite3-api-cleanup.js
 326
 327 # "External" API files which are part of our distribution
 328 # but not part of the sqlite3-api.js amalgamation.
 329 SOAP.js := $(dir.api)/sqlite3-opfs-async-proxy.js
 330 # COPY_XAPI = a $(call)able function to copy $1 to $(dir.dout), where
 331 # $1 must be one of the "external" JS API files.
 332 define COPY_XAPI
 333 sqlite3-api.ext.jses += $$(dir.dout)/$$(notdir $(1))
 334 $$(dir.dout)/$$(notdir $(1)): $(1) $$(MAKEFILE)
 335         cp $$< $$@
 336 endef
 337 $(foreach X,$(SOAP.js),\
 338   $(eval $(call COPY_XAPI,$(X))))
 339 all quick: $(sqlite3-api.ext.jses)
 340 q: quick
 341
 342 ########################################################################
 343 # $(sqlite3-api*.*js) contain the core library code but not the
 344 # Emscripten-related glue which deals with loading sqlite3.wasm. In
 345 # theory they can be used by arbitrary build environments and WASM
 346 # loaders, but in practice that breaks down because the WASM loader
 347 # has to be able to provide all of the necessary "imports" to
 348 # sqlite3.wasm, and that list of imports is unknown until sqlite3.wasm
 349 # is compiled, at which point Emscripten sets up the imports
 350 # appropriately. Abstractly speaking, it's impossible for other build
 351 # environments to know exactly which imports are needed and provide
 352 # them. Tools like wasm-objdump can be used to find the list of
 353 # imports but it's questionable whether a non-Emscripten tool could
 354 # realistically use that info to provide proper implementations.
 355 # Sidebar: some of the imports are used soley by the Emscripten glue,
 356 # which the sqlite3 JS code does not rely on.
 357 #
 358 # We build $(sqlite3-api*.*) "because we can" and because it might be
 359 # a useful point of experimentation for some clients, but the
 360 # above-described caveat may well make them unusable for real-life
 361 # clients.
 362 #
 363 # sqlite3-api.js.in = the generated sqlite3-api.js before it gets
 364 # preprocessed. It contains all of $(sqlite3-api.jses) but none of the
 365 # Emscripten-specific headers and footers.
 366 sqlite3-api.js.in := $(dir.tmp)/sqlite3-api.c-pp.js
 367 $(sqlite3-api.js.in): $(sqlite3-api.jses) $(MAKEFILE)
 368         @echo "Making $@..."
 369         @for i in $(sqlite3-api.jses); do \
 370                 echo "/* BEGIN FILE: $$i */"; \
 371                 cat $$i; \
 372                 echo "/* END FILE: $$i */"; \
 373         done > $@
 374
 375 ########################################################################
 376 # emcc flags for .c/.o/.wasm/.js.
 377 emcc.flags :=
 378 ifeq (1,$(emcc.verbose))
 379 emcc.flags += -v
 380 # -v is _very_ loud but also informative about what it's doing
 381 endif
 382
 383 ########################################################################
 384 # emcc flags for .c/.o.
 385 emcc.cflags :=
 386 emcc.cflags += -std=c99 -fPIC
 387 # -------------^^^^^^^^ we need c99 for $(sqlite3-wasm.c).
 388 emcc.cflags += -I. -I$(dir.top)
 389 ########################################################################
 390 # emcc flags specific to building .js/.wasm files...
 391 emcc.jsflags := -fPIC
 392 emcc.jsflags += --minify 0
 393 emcc.jsflags += --no-entry
 394 emcc.jsflags += -sWASM_BIGINT=$(emcc.WASM_BIGINT)
 395 emcc.jsflags += -sMODULARIZE
 396 emcc.jsflags += -sDYNAMIC_EXECUTION=0
 397 emcc.jsflags += -sNO_POLYFILL
 398 emcc.jsflags += -sEXPORTED_FUNCTIONS=@$(EXPORTED_FUNCTIONS.api)
 399 emcc.exportedRuntimeMethods := \
 400     -sEXPORTED_RUNTIME_METHODS=wasmMemory
 401     # wasmMemory ==> required by our code for use with -sIMPORTED_MEMORY
 402 emcc.jsflags += $(emcc.exportedRuntimeMethods)
 403 emcc.jsflags += -sUSE_CLOSURE_COMPILER=0
 404 emcc.jsflags += -sIMPORTED_MEMORY
 405 ifeq (3.1.31,$(emcc.version))
 406   emcc.jsflags += -sSTRICT_JS=0
 407   $(warning Disabling -sSTRICT_JS for emcc $(emcc.version): \
 408      https://github.com/emscripten-core/emscripten/issues/18610)
 409 else
 410   emcc.jsflags += -sSTRICT_JS=1
 411 endif
 412 emcc.environment := -sENVIRONMENT=web,worker
 413 ########################################################################
 414 # -sINITIAL_MEMORY: How much memory we need to start with is governed
 415 # at least in part by whether -sALLOW_MEMORY_GROWTH is enabled. If so,
 416 # we can start with less. If not, we need as much as we'll ever
 417 # possibly use (which, of course, we can't know for sure).  Note,
 418 # however, that speedtest1 shows that performance for even moderate
 419 # workloads MAY suffer considerably if we start small and have to grow
 420 # at runtime. e.g. OPFS-backed (speedtest1 --size 75) take MAY take X
 421 # time with 16mb+ memory and 3X time when starting with 8MB. However,
 422 # such test results are inconsistent due to browser internals which
 423 # are opaque to us.
 424 emcc.jsflags += -sALLOW_MEMORY_GROWTH
 425 emcc.INITIAL_MEMORY.128 := 13107200
 426 emcc.INITIAL_MEMORY.96  := 100663296
 427 emcc.INITIAL_MEMORY.64  := 64225280
 428 emcc.INITIAL_MEMORY.32  := 33554432
 429 emcc.INITIAL_MEMORY.16  := 16777216
 430 emcc.INITIAL_MEMORY.8   := 8388608
 431 emcc.INITIAL_MEMORY ?= 16
 432 ifeq (,$(emcc.INITIAL_MEMORY.$(emcc.INITIAL_MEMORY)))
 433 $(error emcc.INITIAL_MEMORY must be one of: 8, 16, 32, 64, 96, 128 (megabytes))
 434 endif
 435 emcc.jsflags += -sINITIAL_MEMORY=$(emcc.INITIAL_MEMORY.$(emcc.INITIAL_MEMORY))
 436 # /INITIAL_MEMORY
 437 ########################################################################
 438
 439 emcc.jsflags += $(emcc.environment)
 440 emcc.jsflags += -sSTACK_SIZE=512KB
 441 # ^^^ ACHTUNG: emsdk 3.1.27 reduced the default stack size from 5MB to
 442 # a mere 64KB, which leads to silent memory corruption via the kvvfs
 443 # VFS, which requires twice that for its xRead() and xWrite() methods.
 444 ########################################################################
 445 # $(sqlite3.js.init-func) is the name Emscripten assigns our exported
 446 # module init/load function. This symbol name is hard-coded in
 447 # $(extern-post-js.js) as well as in numerous docs.
 448 #
 449 # "sqlite3InitModule" is the symbol we document for client use, so
 450 # that's the symbol name which must be exported, whether it comes from
 451 # Emscripten or our own code in extern-post-js.js.
 452 #
 453 # That said... we can change $(sqlite3.js.init-func) as long as the
 454 # name "sqlite3InitModule" is the one which gets exposed via the
 455 # resulting JS files. That can be accomplished via
 456 # extern-post-js.js. However...  using a temporary symbol name here
 457 # and then adding sqlite3InitModule() ourselves results in 2 global
 458 # symbols: we cannot "delete" the Emscripten-defined
 459 # $(sqlite3.js.init-func) because it's declared with "var".
 460 sqlite3.js.init-func := sqlite3InitModule
 461 emcc.jsflags += -sEXPORT_NAME=$(sqlite3.js.init-func)
 462 emcc.jsflags += -sGLOBAL_BASE=4096 # HYPOTHETICALLY keep func table indexes from overlapping w/ heap addr.
 463 #emcc.jsflags += -sSTRICT # fails due to missing __syscall_...()
 464 #emcc.jsflags += -sALLOW_UNIMPLEMENTED_SYSCALLS
 465 #emcc.jsflags += -sFILESYSTEM=0 # only for experimentation. sqlite3 needs the FS API
 466 #emcc.jsflags += -sABORTING_MALLOC # only for experimentation
 467 emcc.jsflags += -sALLOW_TABLE_GROWTH
 468 # ^^^^ -sALLOW_TABLE_GROWTH is required for installing new SQL UDFs
 469 emcc.jsflags += -Wno-limited-postlink-optimizations
 470 # ^^^^ emcc likes to warn when we have "limited optimizations" via the
 471 # -g3 flag.
 472 # emcc.jsflags += -sSTANDALONE_WASM # causes OOM errors, not sure why.
 473
 474 # Re. undefined symbol handling, see: https://lld.llvm.org/WebAssembly.html
 475 emcc.jsflags += -sERROR_ON_UNDEFINED_SYMBOLS=1
 476 emcc.jsflags += -sLLD_REPORT_UNDEFINED
 477 #emcc.jsflags += --allow-undefined
 478 #emcc.jsflags += --import-undefined
 479 #emcc.jsflags += --unresolved-symbols=import-dynamic --experimental-pic
 480 #emcc.jsflags += --experimental-pic --unresolved-symbols=ingore-all --import-undefined
 481 #emcc.jsflags += --unresolved-symbols=ignore-all
 482
 483 ########################################################################
 484 # -sMEMORY64=1 fails to load, erroring with:
 485 #  invalid memory limits flags 0x5
 486 #    (enable via --experimental-wasm-memory64)
 487 #
 488 # ^^^^ MEMORY64=2 builds and loads but dies when we do things like:
 489 #
 490 #  new Uint8Array(wasm.heap8u().buffer, ptr, n)
 491 #
 492 # because ptr is now a BigInt, so is invalid for passing to arguments
 493 # which have strict must-be-a-Number requirements. That aspect will
 494 # make any eventual port to 64-bit address space extremely painful, as
 495 # such constructs are found all over the place in the source code.
 496 ########################################################################
 497
 498 ########################################################################
 499 # -sSINGLE_FILE:
 500 # https://github.com/emscripten-core/emscripten/blob/main/src/settings.js
 501 #
 502 # -sSINGLE_FILE=1 would be _really_ nice but we have to build with -g3
 503 # for -O2 and higher to work (else minification breaks the code) and
 504 # cannot wasm-strip the binary before it gets encoded into the JS
 505 # file. The result is that the generated JS file is, because of the
 506 # -g3 debugging info, _huge_.
 507 ########################################################################
 508
 509 $(sqlite3-api-build-version.js): $(bin.version-info) $(MAKEFILE)
 510         @echo "Making $@..."
 511         @{ \
 512   echo 'self.sqlite3ApiBootstrap.initializers.push(function(sqlite3){'; \
 513         echo -n '  sqlite3.version = '; \
 514   $(bin.version-info) --json; \
 515   echo ';'; \
 516         echo '});'; \
 517   } > $@
 518 $(sqlite3-license-version.js): $(sqlite3.h) $(sqlite3-license-version-header.js) \
 519   $(MAKEFILE)
 520         @echo "Making $@..."; { \
 521     cat $(sqlite3-license-version-header.js); \
 522     echo '/*'; \
 523     echo '** This code was built from sqlite3 version...'; \
 524     echo "**"; \
 525     awk -e '/define SQLITE_VERSION/{$$1=""; print "**" $$0}' \
 526         -e '/define SQLITE_SOURCE_ID/{$$1=""; print "**" $$0}' $(sqlite3.h); \
 527     echo "**"; \
 528     echo "** Using the Emscripten SDK version $(emcc.version)."; \
 529     echo '*/'; \
 530    } > $@
 531
 532 ########################################################################
 533 # --post-js and --pre-js are emcc flags we use to append/prepend JS to
 534 # the generated emscripten module file. These rules set up the core
 535 # pre/post files for use by the various builds.
 536 pre-js.js.in := $(dir.api)/pre-js.c-pp.js
 537 post-js.js.in := $(dir.tmp)/post-js.c-pp.js
 538 post-jses.js := \
 539   $(dir.api)/post-js-header.js \
 540   $(sqlite3-api.js.in) \
 541   $(dir.api)/post-js-footer.js
 542 $(post-js.js.in): $(post-jses.js) $(MAKEFILE)
 543         @echo "Making $@..."
 544         @for i in $(post-jses.js); do \
 545                 echo "/* BEGIN FILE: $$i */"; \
 546                 cat $$i; \
 547                 echo "/* END FILE: $$i */"; \
 548         done > $@
 549
 550
 551 ########################################################################
 552 # call-make-pre-post is a $(call)able which creates rules for
 553 # pre-js-$(1).js. $1 = the base name of the JS file on whose behalf
 554 # this pre-js is for (one of: sqlite3, sqlite3-wasmfs). $2 is the build
 555 # mode: one of (vanilla, esm, bundler-friendly).  This sets up
 556 # --[extern-][pre/post]-js flags in $(pre-post-$(1).flags.$(2)) and
 557 # dependencies in $(pre-post-$(1).deps.$(2)).
 558 define call-make-pre-post
 559 pre-post-$(1).flags.$(2) ?=
 560 $$(dir.tmp)/pre-js-$(1)-$(2).js: $$(pre-js.js.$(2)) $$(MAKEFILE)
 561         cp $$(pre-js.js.$(2)) $$@
 562         @if [ sqlite3-wasmfs = $(1) ]; then \
 563                 echo "delete Module[xNameOfInstantiateWasm] /*for WASMFS build*/;"; \
 564         elif [ sqlite3 != $(1) ]; then \
 565                 echo "Module[xNameOfInstantiateWasm].uri = '$(1).wasm';"; \
 566         fi >> $$@
 567 pre-post-$(1).deps.$(2) := \
 568   $$(pre-post-jses.deps.$(2)) \
 569   $$(dir.tmp)/pre-js-$(1)-$(2).js
 570 pre-post-$(1).flags.$(2) += \
 571   $$(pre-post-common.flags.$(2)) \
 572   --pre-js=$$(dir.tmp)/pre-js-$(1)-$(2).js
 573 endef
 574 # /post-js and pre-js
 575 ########################################################################
 576
 577 # Undocumented Emscripten feature: if the target file extension is
 578 # "mjs", it defaults to ES6 module builds:
 579 # https://github.com/emscripten-core/emscripten/issues/14383
 580 sqlite3.wasm := $(dir.dout)/sqlite3.wasm
 581 sqlite3-wasm.c := $(dir.api)/sqlite3-wasm.c
 582 # sqlite3-wasm.o vs sqlite3-wasm.c: building against the latter
 583 # (predictably) results in a slightly faster binary. We're close
 584 # enough to the target speed requirements that the 500ms makes a
 585 # difference, so we build all binaries against sqlite3-wasm.c instead
 586 # of building a shared copy of sqlite3-wasm.o to link against.
 587 ########################################################################
 588 # SQLITE3.xJS.EXPORT-DEFAULT is part of SQLITE3-WASMFS.xJS.RECIPE and
 589 # SETUP_LIB_BUILD_MODE, factored into a separate piece to avoid code
 590 # duplication. $1 is 1 if the build mode needs this workaround (esm,
 591 # bundler-friendly) and 0 if not (vanilla).
 592 #
 593 # Reminder for ESM builds: even if we use -sEXPORT_ES6=0, emcc _still_
 594 # adds:
 595 #
 596 #   export default $(sqlite3.js.init-func);
 597 #
 598 # when building *.mjs, which is bad because we need to export an
 599 # overwritten version of that function and cannot "export default"
 600 # twice. Because of this, we have to sed *.mjs to remove the _first_
 601 # instance (only) of /^export default/.
 602 #
 603 # Upstream RFE:
 604 # https://github.com/emscripten-core/emscripten/issues/18237
 605 define SQLITE3.xJS.ESM-EXPORT-DEFAULT
 606 if [ x1 = x$(1) ]; then \
 607                 echo "Fragile workaround for an Emscripten annoyance. See SQLITE3.xJS.RECIPE."; \
 608                 sed -i -e '0,/^export default/{/^export default/d;}' $@ || exit $$?; \
 609                 if ! grep -q '^export default' $@; then \
 610                         echo "Cannot find export default." 1>&2; \
 611                         exit 1; \
 612                 fi; \
 613 fi
 614 endef
 615
 616 # extern-post-js* and extern-pre-js* are files for use with
 617 # Emscripten's --extern-pre-js and --extern-post-js flags.
 618 extern-pre-js.js := $(dir.api)/extern-pre-js.js
 619 extern-post-js.js.in := $(dir.api)/extern-post-js.c-pp.js
 620 # Emscripten flags for --[extern-][pre|post]-js=... for the
 621 # various builds.
 622 pre-post-common.flags := \
 623   --extern-pre-js=$(sqlite3-license-version.js)
 624 # pre-post-jses.deps.* = a list of dependencies for the
 625 # --[extern-][pre/post]-js files.
 626 pre-post-jses.deps.common := $(extern-pre-js.js) $(sqlite3-license-version.js)
 627 ########################################################################
 628 # SETUP_LIB_BUILD_MODE is a $(call)'able which sets up numerous pieces
 629 # for one of the build modes (vanilla, esm, bundler-friendly).
 630 #
 631 # $1 = build mode name
 632 # $2 = 1 for ESM build mode, else 0
 633 # $3 = resulting sqlite-api JS/MJS file
 634 # $4 = resulting JS/MJS file
 635 # $5 = -D... flags for $(bin.c-pp)
 636 # $6 = emcc -sXYZ flags
 637 define SETUP_LIB_BUILD_MODE
 638 $(info Setting up build [$(1)]: $(4))
 639 c-pp.D.$(1) := $(5)
 640 pre-js.js.$(1) := $$(dir.api)/pre-js.$(1).js
 641 $$(eval $$(call C-PP.FILTER,$$(pre-js.js.in),$$(pre-js.js.$(1)),$$(c-pp.D.$(1))))
 642 post-js.js.$(1) := $$(dir.tmp)/post-js.$(1).js
 643 $$(eval $$(call C-PP.FILTER,$$(post-js.js.in),$$(post-js.js.$(1)),$$(c-pp.D.$(1))))
 644 extern-post-js.js.$(1) := $$(dir.tmp)/extern-post-js.$(1).js
 645 $$(eval $$(call C-PP.FILTER,$$(extern-post-js.js.in),$$(extern-post-js.js.$(1)),$$(c-pp.D.$(1))))
 646 pre-post-common.flags.$(1) := \
 647   $$(pre-post-common.flags) \
 648   --post-js=$$(post-js.js.$(1)) \
 649   --extern-post-js=$$(extern-post-js.js.$(1))
 650 pre-post-jses.deps.$(1) := $$(pre-post-jses.deps.common) \
 651   $$(post-js.js.$(1)) $$(extern-post-js.js.$(1))
 652 $$(eval $$(call call-make-pre-post,sqlite3,$(1)))
 653 emcc.flags.sqlite3.$(1) := $(6)
 654 $$(eval $$(call C-PP.FILTER, $$(sqlite3-api.js.in), $(3), $(5)))
 655 $(4): $(3)
 656 $(4): $(3) $$(MAKEFILE) $$(sqlite3-wasm.c) $$(EXPORTED_FUNCTIONS.api) $$(pre-post-sqlite3.deps.$(1))
 657         @echo "Building $$@ ..."
 658         $$(emcc.bin) -o $$@ $$(emcc_opt_full) $$(emcc.flags) \
 659     $$(emcc.jsflags) \
 660     $$(pre-post-sqlite3.flags.$(1)) $$(emcc.flags.sqlite3.$(1)) \
 661     $$(cflags.common) $$(SQLITE_OPT) $$(sqlite3-wasm.c)
 662         @$$(call SQLITE3.xJS.ESM-EXPORT-DEFAULT,$(2))
 663         @if [ bundler-friendly = $(1) ]; then \
 664                 echo "Patching $(3) for sqlite3.wasm..."; \
 665                 rm -f $$(dir.dout)/sqlite3-bundler-friendly.wasm; \
 666                 sed -i -e 's/sqlite3-bundler-friendly.wasm/sqlite3.wasm/g' $$@ || exit $$$$?; \
 667         fi
 668         chmod -x $$(sqlite3.wasm)
 669         $$(maybe-wasm-strip) $$(sqlite3.wasm)
 670         @ls -la $@ $$(sqlite3.wasm)
 671 all: $(4)
 672 quick: $(4)
 673 CLEAN_FILES += $(3) $(4)
 674 endef
 675 # ^^^ /SETUP_LIB_BUILD_MODE
 676 ########################################################################
 677 sqlite3-api.js := $(dir.dout)/sqlite3-api.js
 678 sqlite3.js := $(dir.dout)/sqlite3.js
 679 sqlite3-api.mjs := $(dir.dout)/sqlite3-api.mjs
 680 sqlite3.mjs := $(dir.dout)/sqlite3.mjs
 681 sqlite3-api-bundler-friendly.mjs := $(dir.dout)/sqlite3-api-bundler-friendly.mjs
 682 sqlite3-bundler-friendly.mjs := $(dir.dout)/sqlite3-bundler-friendly.mjs
 683 # Maintenance reminder: careful not to introduce spaces around args $1, $2
 684 #$(info $(call SETUP_LIB_BUILD_MODE,vanilla,0, $(sqlite3-api.js), $(sqlite3.js)))
 685 $(eval $(call SETUP_LIB_BUILD_MODE,vanilla,0, $(sqlite3-api.js), $(sqlite3.js)))
 686 $(eval $(call SETUP_LIB_BUILD_MODE,esm,1, $(sqlite3-api.mjs), $(sqlite3.mjs), \
 687        -Dtarget=es6-module, -sEXPORT_ES6 -sUSE_ES6_IMPORT_META))
 688 $(eval $(call SETUP_LIB_BUILD_MODE,bundler-friendly,1,\
 689        $(sqlite3-api-bundler-friendly.mjs),$(sqlite3-bundler-friendly.mjs),\
 690        $(c-pp.D.esm) -Dtarget=es6-bundler-friendly, $(emcc.flags.sqlite3.esm)))
 691 # The various -D... values used by *.c-pp.js include:
 692 #
 693 # -Dtarget=es6-module: for all ESM module builds
 694 #
 695 # -Dtarget=es6-module -Dtarget=es6-bundler-friendly: intended for
 696 #    "bundler-friendly" ESM module build. These have some restrictions
 697 #    on how URL() objects are constructed in some contexts: URLs which
 698 #    refer to files which are part of this project must be references
 699 #    as string literals so that bundlers' static-analysis tools can
 700 #    find those files and include them in their bundles.
 701 #
 702 ########################################################################
 703 ########################################################################
 704 # We have to ensure that we do not build both $(sqlite3*.*js) in
 705 # parallel because both result in the creation of $(sqlite3.wasm). We
 706 # have no way to build just the .mjs file without also building the
 707 # .wasm file because the generated .mjs file has to include info about
 708 # the imports needed by the wasm file, so they have to be built
 709 # together. i.e.  we're building $(sqlite3.wasm) multiple times, but
 710 # that's unavoidable (and harmless, just a waste of build time).
 711 $(sqlite3.wasm): $(sqlite3.js)
 712 $(sqlite3.mjs): $(sqlite3.js)
 713 $(sqlite3-bundler-friendly.mjs): $(sqlite3.mjs)
 714 CLEAN_FILES += $(sqlite3.wasm)
 715
 716 ########################################################################
 717 # We need separate copies of certain supplementary JS files for the
 718 # bundler-friendly build. Concretely, any supplemental JS files which
 719 # themselves use importScripts() or Workers or URL() constructors
 720 # which refer to other in-tree (m)JS files quire a bundler-friendly
 721 # copy.
 722 sqlite3-worker1.js.in := $(dir.api)/sqlite3-worker1.c-pp.js
 723 sqlite3-worker1-promiser.js.in := $(dir.api)/sqlite3-worker1-promiser.c-pp.js
 724 sqlite3-worker1.js := $(dir.dout)/sqlite3-worker1.js
 725 sqlite3-worker1-promiser.js := $(dir.dout)/sqlite3-worker1-promiser.js
 726 sqlite3-worker1-bundler-friendly.js := $(dir.dout)/sqlite3-worker1-bundler-friendly.js
 727 sqlite3-worker1-promiser-bundler-friendly.js := $(dir.dout)/sqlite3-worker1-promiser-bundler-friendly.js
 728 $(eval $(call C-PP.FILTER,$(sqlite3-worker1.js.in),$(sqlite3-worker1.js)))
 729 $(eval $(call C-PP.FILTER,$(sqlite3-worker1.js.in),$(sqlite3-worker1-bundler-friendly.js),\
 730     $(c-pp.D.bundler-friendly)))
 731 $(eval $(call C-PP.FILTER,$(sqlite3-worker1-promiser.js.in),$(sqlite3-worker1-promiser.js)))
 732 $(eval $(call C-PP.FILTER,$(sqlite3-worker1-promiser.js.in),\
 733     $(sqlite3-worker1-promiser-bundler-friendly.js),\
 734     $(c-pp.D.bundler-friendly)))
 735 $(sqlite3-bundler-friendly.mjs): $(sqlite3-worker1-bundler-friendly.js) \
 736     $(sqlite3-worker1-promiser-bundler-friendly.js)
 737 $(sqlite3.js) $(sqlite3.mjs): $(sqlite3-worker1.js) $(sqlite3-worker1-promiser.js)
 738
 739 ########################################################################
 740 # batch-runner.js is part of one of the test apps which reads in SQL
 741 # dumps generated by $(speedtest1) and executes them.
 742 dir.sql := sql
 743 speedtest1 := ../../speedtest1
 744 speedtest1.c := ../../test/speedtest1.c
 745 speedtest1.sql := $(dir.sql)/speedtest1.sql
 746 speedtest1.cliflags := --size 25 --big-transactions
 747 $(speedtest1):
 748         $(MAKE) -C ../.. speedtest1
 749 $(speedtest1.sql): $(speedtest1) $(MAKEFILE)
 750         $(speedtest1) $(speedtest1.cliflags) --script $@
 751 batch-runner.list: $(MAKEFILE) $(speedtest1.sql) $(dir.sql)/000-mandelbrot.sql
 752         bash split-speedtest1-script.sh $(dir.sql)/speedtest1.sql
 753         ls -1 $(dir.sql)/*.sql | grep -v speedtest1.sql | sort > $@
 754 clean-batch:
 755         rm -f batch-runner.list $(dir.sql)/speedtest1*.sql
 756 # ^^^ we don't do this along with 'clean' because we clean/rebuild on
 757 # a regular basis with different -Ox flags and rebuilding the batch
 758 # pieces each time is an unnecessary time sink.
 759 batch: batch-runner.list
 760 all: batch
 761 # end batch-runner.js
 762 ########################################################################
 763 # Wasmified speedtest1 is our primary benchmarking tool.
 764 #
 765 # emcc.speedtest1.common = emcc flags used by multiple builds of speedtest1
 766 # emcc.speedtest1 = emcc flags used by main build of speedtest1
 767 emcc.speedtest1.common := $(emcc_opt_full)
 768 emcc.speedtest1 :=
 769 emcc.speedtest1 += -sENVIRONMENT=web
 770 emcc.speedtest1 += -sALLOW_MEMORY_GROWTH
 771 emcc.speedtest1 += -sINITIAL_MEMORY=$(emcc.INITIAL_MEMORY.$(emcc.INITIAL_MEMORY))
 772 emcc.speedtest1.common += -sINVOKE_RUN=0
 773 emcc.speedtest1.common += --no-entry
 774 emcc.speedtest1.common += -sABORTING_MALLOC
 775 emcc.speedtest1.common += -sSTRICT_JS
 776 emcc.speedtest1.common += -sMODULARIZE
 777 emcc.speedtest1.common += -Wno-limited-postlink-optimizations
 778 EXPORTED_FUNCTIONS.speedtest1 := $(abspath $(dir.tmp)/EXPORTED_FUNCTIONS.speedtest1)
 779 emcc.speedtest1.common += -sSTACK_SIZE=512KB
 780 emcc.speedtest1.common += -sEXPORTED_FUNCTIONS=@$(EXPORTED_FUNCTIONS.speedtest1)
 781 emcc.speedtest1.common += $(emcc.exportedRuntimeMethods)
 782 emcc.speedtest1.common += -sALLOW_TABLE_GROWTH
 783 emcc.speedtest1.common += -sDYNAMIC_EXECUTION=0
 784 emcc.speedtest1.common += --minify 0
 785 emcc.speedtest1.common += -sEXPORT_NAME=$(sqlite3.js.init-func)
 786 emcc.speedtest1.common += -sWASM_BIGINT=$(emcc.WASM_BIGINT)
 787 speedtest1.exit-runtime0 := -sEXIT_RUNTIME=0
 788 speedtest1.exit-runtime1 := -sEXIT_RUNTIME=1
 789 # Re -sEXIT_RUNTIME=1 vs 0: if it's 1 and speedtest1 crashes, we get
 790 # this error from emscripten:
 791 #
 792 # > native function `free` called after runtime exit (use
 793 # NO_EXIT_RUNTIME to keep it alive after main() exits))
 794 #
 795 # If it's 0 and it crashes, we get:
 796 #
 797 # > stdio streams had content in them that was not flushed. you should
 798 # set EXIT_RUNTIME to 1 (see the FAQ), or make sure to emit a newline
 799 # when you printf etc.
 800 #
 801 # and pending output is not flushed because it didn't end with a
 802 # newline (by design). The lesser of the two evils seems to be
 803 # -sEXIT_RUNTIME=1 but we need EXIT_RUNTIME=0 for the worker-based app
 804 # which runs speedtest1 multiple times.
 805
 806 $(EXPORTED_FUNCTIONS.speedtest1): $(EXPORTED_FUNCTIONS.api)
 807         @echo "Making $@ ..."
 808         @{ echo _wasm_main; cat $(EXPORTED_FUNCTIONS.api); } > $@
 809 speedtest1.js := $(dir.dout)/speedtest1.js
 810 speedtest1.wasm := $(dir.dout)/speedtest1.wasm
 811 cflags.speedtest1 := $(cflags.common) -DSQLITE_SPEEDTEST1_WASM
 812 speedtest1.cses := $(speedtest1.c) $(sqlite3-wasm.c)
 813 $(eval $(call call-make-pre-post,speedtest1,vanilla))
 814 $(speedtest1.js): $(MAKEFILE) $(speedtest1.cses) \
 815     $(pre-post-speedtest1.deps.vanilla) \
 816     $(EXPORTED_FUNCTIONS.speedtest1)
 817         @echo "Building $@ ..."
 818         $(emcc.bin) \
 819         $(emcc.speedtest1) $(emcc.speedtest1.common) \
 820         $(cflags.speedtest1) $(pre-post-speedtest1.flags.vanilla) \
 821         $(SQLITE_OPT) \
 822         $(speedtest1.exit-runtime0) \
 823         -o $@ $(speedtest1.cses) -lm
 824         $(maybe-wasm-strip) $(speedtest1.wasm)
 825         ls -la $@ $(speedtest1.wasm)
 826
 827 speedtest1: $(speedtest1.js)
 828 all: speedtest1
 829 CLEAN_FILES += $(speedtest1.js) $(speedtest1.wasm)
 830 # end speedtest1.js
 831 ########################################################################
 832
 833 ########################################################################
 834 # tester1 is the main unit and regression test application and needs
 835 # to be able to run in 4 separate modes to cover the primary
 836 # client-side use cases:
 837 #
 838 # 1) Load sqlite3 in the main UI thread of a conventional script.
 839 # 2) Load sqlite3 in a conventional Worker thread.
 840 # 3) Load sqlite3 as an ES6 module (ESM) in the main thread.
 841 # 4) Load sqlite3 as an ESM worker. (Not all browsers support this.)
 842 #
 843 # To that end, we require two separate builds of tester1.js:
 844 #
 845 #  tester1.js: cases 1 and 2
 846 #  tester1.mjs: cases 3 and 4
 847 #
 848 # To create those, we filter tester1.c-pp.js with $(bin.c-pp)...
 849 $(eval $(call C-PP.FILTER,tester1.c-pp.js,tester1.js))
 850 $(eval $(call C-PP.FILTER,tester1.c-pp.js,tester1.mjs,$(c-pp.D.esm)))
 851 $(eval $(call C-PP.FILTER,tester1.c-pp.html,tester1.html))
 852 $(eval $(call C-PP.FILTER,tester1.c-pp.html,tester1-esm.html,$(c-pp.D.esm)))
 853 tester1: tester1.js tester1.mjs tester1.html tester1-esm.html
 854 # Note that we do not include $(sqlite3-bundler-friendly.mjs) in this
 855 # because bundlers are client-specific.
 856 all quick: tester1
 857
 858 ########################################################################
 859 # Convenience rules to rebuild with various -Ox levels. Much
 860 # experimentation shows -O2 to be the clear winner in terms of speed.
 861 # Note that build times with anything higher than -O0 are somewhat
 862 # painful.
 863
 864 .PHONY: o0 o1 o2 o3 os oz
 865 o-xtra :=
 866 #o-xtra ?= -flto
 867 # ^^^^ -flto can have a considerably performance boost at -O0 but
 868 # doubles the build time and seems to have negligible, if any, effect
 869 # on higher optimization levels.
 870 o0: clean
 871         $(MAKE) -e "emcc_opt=-O0"
 872 o1: clean
 873         $(MAKE) -e "emcc_opt=-O1 $(o-xtra)"
 874 o2: clean
 875         $(MAKE) -j2 -e "emcc_opt=-O2 $(o-xtra)"
 876 qo2: clean
 877         $(MAKE) -j2 -e "emcc_opt=-O2 $(o-xtra)" quick
 878 o3: clean
 879         $(MAKE) -e "emcc_opt=-O3 $(o-xtra)"
 880 os: clean
 881         @echo "WARNING: -Os can result in a build with mysteriously missing pieces!"
 882         $(MAKE) -e "emcc_opt=-Os $(o-xtra)"
 883 oz: clean
 884         $(MAKE) -j2 -e "emcc_opt=-Oz $(o-xtra)"
 885 qoz: clean
 886         $(MAKE) -j2 -e "emcc_opt=-Oz $(o-xtra)" quick
 887
 888 ########################################################################
 889 # Sub-makes...
 890
 891 # sqlite.org/fiddle application...
 892 include fiddle.make
 893
 894 # Only add wasmfs if wasmfs.enable=1 or we're running (dist)clean
 895 ifneq (,$(filter wasmfs,$(MAKECMDGOALS)))
 896 wasmfs.enable ?= 1
 897 else
 898 wasmfs.enable ?= $(if $(filter %clean,$(MAKECMDGOALS)),1,0)
 899 endif
 900 ifeq (1,$(wasmfs.enable))
 901 # wasmfs build disabled 2022-10-19 per /chat discussion.
 902 # OPFS-over-wasmfs was initially a stopgap measure and a convenient
 903 # point of comparison for the OPFS sqlite3_vfs's performance, but it
 904 # currently doubles our deliverables and build maintenance burden for
 905 # little benefit.
 906 #
 907 ########################################################################
 908 # Some platforms do not support the WASMFS build. Raspberry Pi OS is one
 909 # of them. As such platforms are discovered, add their (uname -m) name
 910 # to PLATFORMS_WITH_NO_WASMFS to exclude the wasmfs build parts.
 911 PLATFORMS_WITH_NO_WASMFS := aarch64 # add any others here
 912 THIS_ARCH := $(shell /usr/bin/uname -m)
 913 ifneq (,$(filter $(THIS_ARCH),$(PLATFORMS_WITH_NO_WASMFS)))
 914 $(info This platform does not support the WASMFS build.)
 915 HAVE_WASMFS := 0
 916 else
 917 HAVE_WASMFS := 1
 918 include wasmfs.make
 919 endif
 920 endif
 921 # /wasmfs
 922 ########################################################################
 923
 924 ########################################################################
 925 # Push files to public wasm-testing.sqlite.org server
 926 wasm-testing.include = *.js *.mjs *.html \
 927   ./tests \
 928   batch-runner.list \
 929   $(dir.dout) $(dir.sql) $(dir.common) $(dir.fiddle) $(dir.jacc)
 930 wasm-testing.exclude = sql/speedtest1.sql
 931 wasm-testing.dir     = /jail/sites/wasm-testing
 932 wasm-testing.dest   ?= wasm-testing:$(wasm-testing.dir)
 933 # ---------------------^^^^^^^^^^^^ ssh alias
 934 .PHONY: push-testing
 935 push-testing:
 936         rsync -z -e ssh --ignore-times --chown=stephan:www-data --group -r \
 937     $(patsubst %,--exclude=%,$(wasm-testing.exclude)) \
 938     $(wasm-testing.include) $(wasm-testing.dest)
 939         @echo "Updating gzipped copies..."; \
 940                 ssh wasm-testing 'cd $(wasm-testing.dir) && bash .gzip' || \
 941     echo "SSH failed: it's likely that stale content will be served via old gzip files."
 942
 943 ########################################################################
 944 # If we find a copy of the sqlite.org/wasm docs checked out, copy
 945 # certain files over to it, noting that some need automatable edits...
 946 wasm.docs.home ?= ../../../wasm
 947 wasm.docs.found = $(if $(wildcard $(wasm.docs.home)/api-index.md),\
 948   $(wildcard $(wasm.docs.home)),)
 949 .PHONY: update-docs
 950 ifeq (,$(wasm.docs.found))
 951 update-docs:
 952         @echo "Cannot find wasm docs checkout."; \
 953         echo "Pass wasm.docs.home=/path/to/wasm/docs/checkout or edit this makefile to suit."; \
 954         exit 127
 955 else
 956 wasm.docs.jswasm := $(wasm.docs.home)/jswasm
 957 update-docs: $(bin.stripccomments) $(sqlite3.js) $(sqlite3.wasm)
 958         @echo "Copying files to the /wasm docs. Be sure to use an -Oz build for this!"
 959         cp $(sqlite3.wasm) $(wasm.docs.jswasm)/.
 960         $(bin.stripccomments) -k -k < $(sqlite3.js) \
 961                 | sed -e '/^[ \t]*$$/d' > $(wasm.docs.jswasm)/sqlite3.js
 962         cp demo-123.js demo-123.html demo-123-worker.html $(wasm.docs.home)
 963         sed -n -e '/EXTRACT_BEGIN/,/EXTRACT_END/p' \
 964                 module-symbols.html > $(wasm.docs.home)/module-symbols.html
 965 endif
 966 # end /wasm docs
 967 ########################################################################
 968
 969 ########################################################################
 970 # Create main client downloadable zip file:
 971 ifneq (,$(filter dist snapshot,$(MAKECMDGOALS)))
 972 include dist.make
 973 endif
 974
 975 # Run local web server for the test/demo pages.
 976 httpd:
 977         althttpd -max-age 1 -enable-sab -page index.html