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