Debian Codegraph @

ext/wasm/GNUmakefile

raw
1 #
2 # This GNU makefile creates the canonical sqlite3 WASM builds. Plus some
3 # others.
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 its 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
15 # indicated by the target name. A clean rebuild is necessary for
16 # all components to get the desired optimization level.
17 #
18 # dist = create end user deliverables. Add dist.build=oX to build
19 # with a specific optimization level, where oX is one of the
20 # above-listed o? target names.
21 #
22 # snapshot = like dist, but uses a zip file name which clearly
23 # marks it as a prerelease/snapshot build.
24 #
25 # clean = clean up
26 #
27 # Required tools beyond those needed for the canonical builds:
28 #
29 # - Emscripten SDK: https://emscripten.org/docs/getting_started/downloads.html
30 #
31 # - The bash shell
32 #
33 # - GNU make, GNU sed, GNU awk, GNU grep (all in the $PATH and without
34 # a "g" prefix like they have on some non-GNU systems)
35 #
36 # - wasm-strip for release builds: https://github.com/WebAssembly/wabt.
37 # It will build without this but the .wasm files will be huge.
38 #
39 # - InfoZip for 'dist' zip file
40 #
41 default: all
42 MAKEFILE = $(lastword $(MAKEFILE_LIST))
43 CLEAN_FILES =
44 DISTCLEAN_FILES = config.make
45 MAKING_CLEAN = $(if $(filter %clean,$(MAKECMDGOALS)),1,0)
46
47 #
48 # dir.X = various directory names.
49 #
50 # dir.top = the top dir of the canonical build tree, where
51 # sqlite3.[ch] live.
52 #
53 dir.top = ../..
54 dir.wasm = $(patsubst %/,%,$(dir $(MAKEFILE)))
55 dir.api = api
56 dir.jacc = jaccwabyt
57 dir.common = common
58 dir.fiddle = fiddle
59 dir.fiddle.debug = fiddle-debug
60 dir.tool = $(dir.top)/tool
61 # dir.dout = output dir for deliverables
62 dir.dout = $(dir.wasm)/jswasm
63 # dir.tmp = output dir for intermediary build files, as opposed to
64 # end-user deliverables.
65 dir.tmp = $(dir.wasm)/bld
66 dir.wasmfs = $(dir.dout)
67
68 #
69 # Emoji for log messages.
70 #
71 emo.bug = ๐Ÿž
72 emo.compile = โณ
73 emo.roadblock = ๐Ÿšง
74 emo.disk = ๐Ÿ’พ
75 emo.done = โœ…
76 emo.fire = ๐Ÿ”ฅ
77 emo.folder = ๐Ÿ“
78 emo.garbage = ๐Ÿ—‘
79 emo.lock = ๐Ÿ”’
80 emo.magic = ๐Ÿง™
81 emo.megaphone = ๐Ÿ“ฃ
82 emo.mute = ๐Ÿ”‡
83 emo.edit = โœ๏ธ
84 emo.stop = ๐Ÿ›‘
85 emo.strip = ๐Ÿ’ˆ
86 emo.test = ๐Ÿงช
87 emo.tool = ๐Ÿ”จ
88 emo.wasm-opt = ๐Ÿงผ
89 emo.cleanup = ๐Ÿงผ
90 # ๐Ÿ‘ท๐Ÿช„๐Ÿงฎ๐Ÿงซ๐Ÿงฝ๐Ÿฟโ›ฝ๐Ÿšง๐ŸŽฑ๐Ÿชš๐Ÿ†๐Ÿงผ
91
92 #
93 # Special-case builds for which we require certain pre-conditions
94 # which, if not met, may cause warnings or fatal errors in the build.
95 # This also affects the default optimization level flags. The fiddle
96 # targets are in this list because they are used for generating
97 # sqlite.org/fiddle.
98 #
99 OPTIMIZED_TARGETS = dist snapshot fiddle fiddle.debug
100
101 ifeq (1,$(MAKING_CLEAN))
102 bin.wasm-strip = echo "not stripping"
103 bin.wasm-opt = irrelevant
104 bin.emcc = irrelevant
105 bin.bash = irrelevant
106 emcc.version = unknown
107 else
108 # Include config.make and perform some bootstrapping...
109 ifeq (,$(wildcard ./config.make))
110 $(error Missing config.make. It gets generated by the configure script if the EMSDK is found)
111 endif
112 include ./config.make
113 ifeq (,$(bin.bash))
114 $(error Configure script did not find the bash shell)
115 endif
116 ifeq (,$(bin.emcc))
117 $(error Configure script did not find emcc)
118 endif
119 emcc.version = $(shell $(bin.emcc) --version | sed -n 1p | sed -e 's/^.* \([3-9][^ ]*\) .*$$/\1/;')
120 $(info using emcc version [$(emcc.version)])
121 ifeq (,$(bin.wasm-strip))
122 #
123 # We need wasm-strip for release builds (see below for why) but
124 # not strictly for non-release builds.
125 #
126 achtung = $(emo.fire)WARNING
127 $(info $(achtung): *******************************************************************)
128 $(info $(achtung): Builds using -Oz will minify WASM-exported names, breaking)
129 $(info $(achtung): _All The Things_. The workaround for that is to build)
130 $(info $(achtung): with -g3 (which explodes the file size) and then strip the debug)
131 $(info $(achtung): info after compilation, using wasm-strip, to shrink the wasm file.)
132 $(info $(achtung): wasm-strip was not found in the PATH so we cannot strip those.)
133 $(info $(achtung): If this build uses any optimization level higher than -O1 then)
134 $(info $(achtung): the ***resulting JS code WILL NOT BE USABLE***.)
135 $(info $(achtung): wasm-strip is part of the wabt package:)
136 $(info $(achtung): https://github.com/WebAssembly/wabt)
137 $(info $(achtung): on Ubuntu-like systems it can be installed with:)
138 $(info $(achtung): sudo apt install wabt)
139 $(info $(achtung): *******************************************************************)
140 ifneq (,$(filter $(OPTIMIZED_TARGETS),$(MAKECMDGOALS)))
141 $(error Cannot make release-quality binary because wasm-strip is not available.)
142 endif
143 bin.wasm-strip = echo "not wasm-stripping"
144 endif
145 ifeq (,$(filter $(OPTIMIZED_TARGETS),$(MAKECMDGOALS)))
146 $(info ==============================================================)
147 $(info == Development build. Make one of (dist, snapshot) for a)
148 $(info == smaller and faster release build.)
149 $(info ==============================================================)
150 endif
151 endif
152 # ^^^ end of are-we-MAKING_CLEAN
153
154 #
155 # Common vars and $(call)/$(eval)able utilities.
156 #
157 # The "b." prefix on some APIs is for "build". It was initially used
158 # only for features specific to each distinct js/wasm build. That's no
159 # longer the case, but the naming convention has stuck.
160 #
161
162 loud ?= 0
163 ifeq (1,$(loud))
164 $(info $(emo.megaphone) Emitting loud build info. Pass loud=0 to disable it.)
165 b.cmd@ =
166 loud.if = 1
167 else
168 $(info $(emo.mute) Eliding loud build info. Pass loud=1 to enable it.)
169 b.cmd@ = @
170 loud.if =
171 endif
172
173 #
174 # logtag.X value for log context labeling. logtag.OTHERX can be
175 # assigned to customize it for a given X. This tag is used by
176 # b.call.X, b.eval.X, etc. for logging. There motivation for this is
177 # adding a build-specific prefix to messages so that the output of
178 # parallel builds is easier to sort through. We use emoji for the
179 # prefixes because it's far easier for my eyes to sort through than
180 # using only each build's name as the prefix.
181 #
182 # Each distinct build sets up its own logtag.BUILDNAME.
183 #
184 logtag.@ = [$@]
185 logtag.filter = [$(emo.disk) $@]
186 logtag.test = [$(emo.test) $@]
187 logtag.cp = [$(emo.disk) $@]
188
189 #
190 # $(call b.echo,LOGTAG,msg)
191 #
192 b.echo = echo $(logtag.$(1)) $(2)
193
194 #
195 # $(call b.mkdir@)
196 #
197 # $1 = optional LOGTAG
198 #
199 b.mkdir@ = if [ ! -d $(dir $@) ]; then \
200 echo '[$(emo.folder)+] $(if $(1),$(logtag.$(1)),[$(dir $@)])'; \
201 mkdir -p $(dir $@) || exit; fi
202
203 #
204 # $(call b.cp,@,src,dest)
205 #
206 # $1 = logtag, $2 = src file(s). $3 = dest dir
207 b.cp = $(call b.mkdir@); \
208 echo '$(logtag.$(1)) $(emo.disk) $(2) ==> $3'; \
209 cp -f -p $(2) $(3) || exit
210
211 #
212 # $(call b.c-pp.shcmd,LOGTAG,src,dest,-Dx=y...)
213 #
214 # Resolves to shell code to create $(3) from $(2) and $(4) using
215 # $(bin.c-pp).
216 #
217 # $1 = build name/logtag
218 # $2 = Input file(s)
219 # $3 = Output file
220 # $4 = optional $(bin.c-pp) flags
221 define b.c-pp.shcmd
222 $(call b.mkdir@); \
223 $(call b.echo,$(1),$(emo.disk)$(emo.lock)[$(3)] $(4)); \
224 rm -f $(3); $(bin.c-pp) -o $(3) $(4) $(2) || exit; \
225 chmod -w $(3)
226 endef
227
228 #
229 # $(eval $(call b.c-pp.target,LOGTAG,src,dest,-Dx=y...))
230 #
231 # Creates target $(3) using $(bin.c-pp) $(2) $(4).
232 #
233 # Args: as for $(b.c-pp.shcmd).
234 define b.c-pp.target
235 $(3): $$(MAKEFILE_LIST) $$(bin.c-pp) $(2)
236 @$$(call b.mkdir@)
237 @$$(call b.c-pp.shcmd,$(1),$(2),$(3),$(4) $$(b.c-pp.target.flags))
238 CLEAN_FILES += $(3)
239 endef
240
241
242 #
243 # The various -D... values used by *.c-pp.js include:
244 #
245 # -Dtarget:es6-module: for all ESM module builds
246 #
247 # -Dtarget:node: for node.js builds
248 #
249 # -Dtarget:es6-module -Dtarget:es6-bundler-friendly: intended for
250 # "bundler-friendly" ESM module build. These have some restrictions
251 # on how URL() objects are constructed in some contexts: URLs which
252 # refer to files which are part of this project must be referenced
253 # as string literals so that bundlers' static-analysis tools can
254 # find those files and include them in their bundles.
255 #
256 # -Dtarget:es6-module -Dtarget:node: is intended for use by node.js
257 # for node.js, as opposed to by node.js on behalf of a
258 # browser. Mixing -sENVIRONMENT=web and -sENVIRONMENT=node leads to
259 # ambiguity and confusion on node's part, as it's unable to
260 # reliably determine whether the target is a browser or node.
261 #
262 # To repeat: all node.js builds are 100% untested and unsupported.
263 #
264 # Most c-pp.D.X are set via $(bin.mkwb) and X is a build name.
265 # Those make rules reference c-pp.D.64bit, so it should be defined in
266 # advance.
267 #
268 c-pp.D.64bit = -Dbits64
269
270 #
271 # $(call b.strip-js-emcc-bindings)
272 #
273 # $1 = an optional log message prefix
274 #
275 # Our JS code installs bindings of each sqlite3_...() WASM export. The
276 # generated Emscripten JS file does the same using its own framework,
277 # but we don't use those results and can speed up lib init, and reduce
278 # memory cost a bit, by stripping them out. Emscripten code-generation
279 # changes can "break" this, causing this to be a no-op, but (probably)
280 # the worst that can happen in that case is that it doesn't actually
281 # strip anything, leading to slightly larger JS files.
282 #
283 # This is intended to be used in makefile targets which generate an
284 # Emscripten module and where $@ is the module's .js/.mjs file.
285 #
286 # This is inherently fragile and has been broken by Emscripten updates
287 # before.
288 #
289 ifeq (1,1)
290 define b.strip-js-emcc-bindings
291 echo "$(1) $(emo.garbage) Stripping export wrappers."; \
292 sed -i -e '/var _sqlite3.*makeInvalidEarly.*;/d' \
293 -e '/assert.*sqlite3.*missing.*;/d' \
294 -e '/_sqlite.*createExportWrapper.*;/d' $@
295 endef
296 else
297 b.strip-js-emcc-bindings = \
298 echo '$(1) $(emo.bug) (disabled because it breaks emsdk 4.0.16+)'
299 endif
300
301 #
302 # Set up sqlite3.c and sqlite3.h...
303 #
304 # To build with SEE (https://sqlite.org/see), either put sqlite3-see.c
305 # in $(dir.top) or pass sqlite3.c=PATH_TO_sqlite3-see.c to the $(MAKE)
306 # invocation. Note that only encryption modules with no 3rd-party
307 # dependencies will currently work here: AES256-OFB, AES128-OFB, and
308 # AES128-CCM. Not coincidentally, those 3 modules are included in the
309 # sqlite3-see.c bundle. Note, however, that distributing an SEE build
310 # of the WASM on a public site is in violation of the SEE license
311 # because it effectively provides a usable copy of the SEE build to
312 # all visitors.
313 #
314 # A custom sqlite3.c must not have any spaces in its name.
315 # $(sqlite3.canonical.c) must point to the sqlite3.c in
316 # the sqlite3 canonical source tree, as that source file
317 # is required for certain utility and test code.
318 #
319 sqlite3.canonical.c = $(dir.top)/sqlite3.c
320 sqlite3.c ?= $(firstword $(wildcard $(dir.top)/sqlite3-see.c) $(sqlite3.canonical.c))
321 sqlite3.h = $(dir $(sqlite3.c))sqlite3.h
322
323 #
324 # bin.version-info = binary to output various sqlite3 version info for
325 # embedding in the JS files and in building the distribution zip file.
326 # It must NOT be in $(dir.tmp) because we need it to survive the
327 # cleanup process for the dist build to work properly.
328 #
329 bin.version-info = ./version-info
330 $(bin.version-info): $(dir.tool)/version-info.c $(sqlite3.h) $(dir.top)/Makefile
331 $(CC) -o $@ -I$(dir $(sqlite3.h)) $(dir.tool)/version-info.c
332 t-version-info: $(bin.version-info)
333 DISTCLEAN_FILES += $(bin.version-info)
334
335 #
336 # bin.stripcomments is used for stripping C/C++-style comments from JS
337 # files. The JS files contain large chunks of documentation which we
338 # don't need for all builds. That app's -k flag is of particular
339 # importance here, as it allows us to retain the opening comment
340 # block(s), which contain the license header and version info.
341 #
342 bin.stripccomments = $(dir.tool)/stripccomments
343 $(bin.stripccomments): $(bin.stripccomments).c $(MAKEFILE)
344 $(CC) -o $@ $<
345 t-stripccomments: $(bin.stripccomments)
346 DISTCLEAN_FILES += $(bin.stripccomments)
347
348 ifeq (1,$(MAKING_CLEAN))
349 SQLITE_C_IS_SEE = 0
350 else
351 ifeq (,$(shell grep sqlite3_activate_see $(sqlite3.c)))
352 SQLITE_C_IS_SEE = 0
353 else
354 SQLITE_C_IS_SEE = 1
355 $(info This is an SEE build)
356 endif
357 endif
358
359 #
360 # barebones=1 disables all "extraneous" stuff from sqlite3-wasm.c, the
361 # goal being to create a WASM file with only the core APIs.
362 #
363 ifeq (1,$(barebones))
364 wasm-bare-bones = 1
365 $(info ==============================================================)
366 $(info == This is a bare-bones build. It trades away features for)
367 $(info == a smaller .wasm file.)
368 $(info ==============================================================)
369 else
370 wasm-bare-bones = 0
371 endif
372 # undefine barebones # relatively new gmake feature, not ubiquitous
373
374 #
375 # It's important that sqlite3.[ch] be built to completion before any
376 # other parts of the build run, thus we use .NOTPARALLEL to disable
377 # parallel build of that file and its dependants. However, that makes
378 # the whole build non-parallelizable because everything has a dep on
379 # sqlite3.h/c. The alternative is to force the user to run (make
380 # sqlite3.c) from the top of the tree before running this build.
381 #
382 #.NOTPARALLEL: $(sqlite3.h)
383 #
384 $(sqlite3.h):
385 @echo "$(sqlite3.h) is out of date. "; \
386 echo "To avoid problems with parallel builds, we're exiting now. Please do:"; \
387 echo " $(MAKE) -C $(dir.top) sqlite3.c"; \
388 echo "and try again."; exit 1
389 # $(MAKE) -C $(dir.top) sqlite3.c
390 $(sqlite3.c): $(sqlite3.h)
391
392 #
393 # Common options for building sqlite3-wasm.c and speedtest1.c.
394 # Explicit ENABLEs...
395 #
396 SQLITE_OPT.common = \
397 -DSQLITE_THREADSAFE=0 \
398 -DSQLITE_TEMP_STORE=2 \
399 -DSQLITE_ENABLE_MATH_FUNCTIONS \
400 -DSQLITE_OS_KV_OPTIONAL=1 \
401 '-DSQLITE_DEFAULT_UNIX_VFS="unix-none"' \
402 -DSQLITE_USE_URI=1 \
403 -DSQLITE_C=$(sqlite3.c) \
404 -DSQLITE_OMIT_DEPRECATED \
405 -DSQLITE_OMIT_UTF16 \
406 -DSQLITE_OMIT_LOAD_EXTENSION \
407 -DSQLITE_OMIT_SHARED_CACHE
408 # ^^^ These particular OMITs are hard-coded in sqlite3-wasm.c and
409 # removing them from this list will serve only to break the speedtest1
410 # builds.
411
412 #
413 # Currently always needed but TODO is paring tester1.c-pp.js down
414 # to be able to run without this:
415 #
416 SQLITE_OPT.common += -DSQLITE_WASM_ENABLE_C_TESTS
417
418 #
419 # Extra flags for full-featured builds...
420 #
421 SQLITE_OPT.full-featured = \
422 -DSQLITE_ENABLE_BYTECODE_VTAB \
423 -DSQLITE_ENABLE_DBPAGE_VTAB \
424 -DSQLITE_ENABLE_DBSTAT_VTAB \
425 -DSQLITE_ENABLE_FTS5 \
426 -DSQLITE_ENABLE_MATH_FUNCTIONS \
427 -DSQLITE_ENABLE_OFFSET_SQL_FUNC \
428 -DSQLITE_ENABLE_PREUPDATE_HOOK \
429 -DSQLITE_ENABLE_RTREE \
430 -DSQLITE_ENABLE_SESSION \
431 -DSQLITE_ENABLE_STMTVTAB \
432 -DSQLITE_ENABLE_UNKNOWN_SQL_FUNCTION \
433 -DSQLITE_ENABLE_COLUMN_METADATA \
434 -DSQLITE_ENABLE_PERCENTILE=1
435
436
437 ifeq (0,$(wasm-bare-bones))
438 # The so-called canonical build is full-featured:
439 SQLITE_OPT = \
440 $(SQLITE_OPT.common) \
441 $(SQLITE_OPT.full-featured)
442 else
443 # The so-called bare-bones build is exactly that:
444 SQLITE_OPT = \
445 $(SQLITE_OPT.common) \
446 -DSQLITE_WASM_BARE_BONES
447 # SQLITE_WASM_BARE_BONES tells sqlite3-wasm.c to explicitly omit
448 # a bunch of stuff, in the interest of keeping the wasm file size
449 # down. As of this writing it equates to:
450 #
451 # -USQLITE_ENABLE_DBPAGE_VTAB
452 # -USQLITE_ENABLE_DBSTAT_VTAB
453 # -USQLITE_ENABLE_EXPLAIN_COMMENTS
454 # -USQLITE_ENABLE_FTS5
455 # -USQLITE_ENABLE_OFFSET_SQL_FUNC
456 # -USQLITE_ENABLE_PREUPDATE_HOOK
457 # -USQLITE_ENABLE_RTREE
458 # -USQLITE_ENABLE_SESSION
459 # -USQLITE_ENABLE_STMTVTAB
460 # -DSQLITE_OMIT_AUTHORIZATION
461 # -DSQLITE_OMIT_GET_TABLE
462 # -DSQLITE_OMIT_INCRBLOB
463 # -DSQLITE_OMIT_INTROSPECTION_PRAGMAS
464 # -DSQLITE_OMIT_JSON
465 # -DSQLITE_OMIT_PROGRESS_CALLBACK
466 # -DSQLITE_OMIT_WAL
467 #
468 # There are others we want here but which require explicit OMIT when
469 # creating their amalgamation, and that step is TODO:
470 #
471 # -DSQLITE_OMIT_EXPLAIN
472 # -DSQLITE_OMIT_TRIGGER
473 # -DSQLITE_OMIT_VIRTUALTABLE
474 # -DSQLITE_OMIT_WINDOWFUNC
475 endif
476
477 #
478 #SQLITE_OPT += -DSQLITE_DEBUG
479 # Enabling SQLITE_DEBUG will break sqlite3_wasm_vfs_create_file()
480 # (and thus sqlite3_js_vfs_create_file()). Those functions are
481 # deprecated and alternatives are in place, but this crash behavior
482 # can be used to find errant uses of sqlite3_js_vfs_create_file()
483 # in client code.
484 #
485 # The following flags are hard-coded into sqlite3-wasm.c and cannot be
486 # modified via the build process:
487 #
488 # SQLITE_ENABLE_API_ARMOR
489 # SQLITE_OMIT_LOAD_EXTENSION
490 # SQLITE_OMIT_DEPRECATED
491 # SQLITE_OMIT_UTF16
492 # SQLITE_OMIT_SHARED_CACHE
493 #
494
495 #
496 # Adding custom C code via sqlite3_wasm_extra_init.c:
497 #
498 # If the canonical build process finds the file
499 # sqlite3_wasm_extra_init.c in the main wasm build directory, it
500 # arranges to include that file in the build of sqlite3.wasm and
501 # defines SQLITE_EXTRA_INIT_MUTEXED=sqlite3_wasm_extra_init.
502 #
503 # sqlite3_wasm_extra_init() must be a function with this signature:
504 #
505 # int sqlite3_wasm_extra_init(const char *)
506 #
507 # and the sqlite3 library will call it with an argument of NULL one
508 # time during sqlite3_initialize(). If it returns non-0,
509 # initialization of the library will fail.
510 #
511 # The filename can be overridden with:
512 #
513 # make sqlite3_wasm_extra_init.c=my_custom_stuff.c
514 #
515 # See example_extra_init.c for an example implementation.
516 #
517 sqlite3_wasm_extra_init.c ?= $(wildcard sqlite3_wasm_extra_init.c)
518 cflags.wasm_extra_init =
519 ifneq (,$(sqlite3_wasm_extra_init.c))
520 $(info Enabling SQLITE_EXTRA_INIT via $(sqlite3_wasm_extra_init.c).)
521 cflags.wasm_extra_init = -DSQLITE_WASM_EXTRA_INIT
522 endif
523
524 #
525 # Actitivates (or not) a custom Module.instantiateWasm() override for
526 # Emscripten. That override gives us more control over exactly which
527 # WASM file is in use.
528 #
529 # If $(WASM_CUSTOM_INSTANTIATE) is 1 then mkwasmbuilds will add
530 # -Dcustom-Module.instantiateWasm to some of the builds. This is
531 # experimental but works on all browsers tested by its developer.
532 #
533 # Changing this may require a clean rebuild. It also might not work.
534 #
535 WASM_CUSTOM_INSTANTIATE = 1
536
537 #
538 # $(bin.c-pp): a minimal text file preprocessor. Like C's but much
539 # less so.
540 #
541 # Historical notes about preprocessing files in this project:
542 #
543 # - We first attempted to use gcc and/or clang to preprocess JS files
544 # in the same way we would normally do C files, but C-specific quirks
545 # of each makes that untennable.
546 #
547 # - We implemented c-pp-lite.c (the C-Minus Pre-processor) as a custom
548 # generic/file-format-agnostic preprocessor to enable us to pack
549 # code for different target builds into the same JS files. Most
550 # notably, some ES6 module (a.k.a. ESM) features cannot legally be
551 # referenced at all in non-ESM code, e.g. the "import" and "export"
552 # keywords. This preprocessing step permits us to swap out sections
553 # of code where necessary for ESM and non-ESM (a.k.a. vanilla JS)
554 # require different implementations. The alternative to such
555 # preprocessing, would be to have separate source files for ES6
556 # builds, which would have a higher maintenance burden than
557 # c-pp-lite.c seems likely to.
558 #
559 # c-pp-lite.c was written specifically for the sqlite project's
560 # JavaScript builds but is maintained as a standalone project:
561 # https://fossil.wanderinghorse.net/r/c-pp
562 #
563 # The SQLITE_... build flags used here have NO EFFECT on the JS/WASM
564 # build. They are solely for use with $(bin.c-pp) itself.
565 #
566 # -D... flags which should be included in all invocations should be
567 # appended to $(b.c-pp.target.flags).
568 #
569 bin.c-pp = ./c-pp
570 $(bin.c-pp): libcmpp.c $(sqlite3.c) $(MAKEFILE)
571 $(CC) -O0 -o $@ libcmpp.c $(dir.top)/sqlite3.c -I$(dir.top) \
572 -DSQLITE_OMIT_LOAD_EXTENSION -DSQLITE_OMIT_DEPRECATED -DSQLITE_OMIT_UTF16 \
573 -DSQLITE_OMIT_SHARED_CACHE -DSQLITE_OMIT_WAL -DSQLITE_THREADSAFE=0 \
574 -DSQLITE_TEMP_STORE=3 \
575 '-DCMPP_DEFAULT_DELIM="//#"' -DCMPP_MAIN -DCMPP_OMIT_D_MODULE \
576 -DCMPP_OMIT_D_PIPE
577 DISTCLEAN_FILES += $(bin.c-pp)
578 b.c-pp.target.flags ?=
579 ifeq (1,$(SQLITE_C_IS_SEE))
580 b.c-pp.target.flags += -Denable-see
581 endif
582 api.oo1 ?= 1
583 ifeq (0,$(api.oo1))
584 b.c-pp.target.flags += -Domit-oo1
585 endif
586
587 #
588 # cflags.common = C compiler flags for all builds
589 cflags.common = -I. -I$(dir $(sqlite3.c)) -std=c99 -fPIC
590 # emcc.WASM_BIGINT = 1 for BigInt (C int64) support, else 0. The API
591 # disables certain features if BigInt is not enabled and such builds
592 # _are not tested_ on any regular basis.
593 emcc.WASM_BIGINT ?= 1
594 emcc.MEMORY64 ?= 0
595 #
596 # https://emscripten.org/docs/tools_reference/settings_reference.html#memory64
597 #
598 # 64-bit build requires wasm-strip 1.0.36 (maybe 1.0.35, but not
599 # 1.0.34) or will fail to strip with "tables may not be 64-bit".
600 #
601
602 #
603 # emcc_opt = optimization-related flags. These are primarily used by
604 # the various oX targets. build times for -O levels higher than 0 are
605 # painful at dev-time.
606 #
607 # When running any of the $(OPTIMIZED_TARGETS) explicitly, e.g. for a
608 # release distribution, use a higher optimization level. Experience
609 # has shown -Oz to produce the smallest deliverables with only a
610 # roughly 10% performance hit in the resulting WASM file compared to
611 # -O2 (which consistently creates the fastest-running deliverables).
612 # Build time suffers greatly compared to -O0, which is why -O0 is the
613 # default.
614 #
615 ifeq (,$(filter $(OPTIMIZED_TARGETS),$(MAKECMDGOALS)))
616 emcc_opt ?= -O0
617 else
618 emcc_opt ?= -Oz
619 endif
620
621 #
622 # When passing emcc_opt from the CLI, += and re-assignment have no
623 # effect, so emcc_opt+=-g3 doesn't work. So...
624 #
625 emcc_opt_full = $(emcc_opt) -g3
626 # ^^^ ALWAYS use -g3. See below for why.
627 #
628 # ^^^ -flto improves runtime speed at -O0 considerably but doubles
629 # build time.
630 #
631 # ^^^^ (-O3, -Oz, -Os) all minify symbol names and there appears to be
632 # no way around that except to use -g3, but -g3 causes the binary file
633 # size to absolutely explode (approx. 5x larger). This minification
634 # utterly breaks the resulting module, making it unsable except as
635 # self-contained/self-referential-only code, as ALL of the exported
636 # symbols get minified names.
637 #
638 # However, we have an option for using -Oz or -Os:
639 #
640 # Build with (-Os -g3) or (-Oz -g3) then use wasm-strip, from the wabt
641 # tools package (https://github.com/WebAssembly/wabt), to strip the
642 # debugging symbols. That results in a small build with unmangled
643 # symbol names. -Oz gives ever-so-slightly better compression than
644 # -Os: not quite 1% in some completely unscientific tests. Runtime
645 # speed for the unit tests is all over the place either way so it's
646 # difficult to say whether -Os gives any speed benefit over -Oz.
647 #
648 # Much practice has demonstrated that -O2 consistently gives the best
649 # runtime speeds, but not by a large enough factor to rule out use of
650 # -Oz when smaller deliverable size is a priority.
651 #
652
653 #
654 # EXPORTED_FUNCTIONS.* = files for use with Emscripten's
655 # -sEXPORTED_FUNCTION flag.
656 #
657 EXPORTED_FUNCTIONS.api.in = $(dir.api)/EXPORTED_FUNCTIONS.c-pp
658 EXPORTED_FUNCTIONS.api = $(dir.tmp)/EXPORTED_FUNCTIONS.api
659 EXPORTED_FUNCTIONS.c-pp.flags =
660 ifeq (1,$(wasm-bare-bones))
661 EXPORTED_FUNCTIONS.c-pp.flags += -Dbare-bones
662 endif
663 $(eval $(call b.c-pp.target,filter,\
664 $(EXPORTED_FUNCTIONS.api.in),\
665 $(EXPORTED_FUNCTIONS.api),\
666 $(EXPORTED_FUNCTIONS.c-pp.flags)))
667
668 #
669 # emcc flags for .c/.o/.wasm/.js.
670 #
671 emcc.flags =
672 ifeq (1,$(emcc.verbose))
673 emcc.flags += -v
674 # -v is _very_ loud but also informative about what it's doing
675 endif
676
677 #
678 # emcc flags for .c/.o.
679 #
680 emcc.cflags =
681 emcc.cflags += -std=c99 -fPIC
682 # -------------^^^^^^^^ we need c99 for $(sqlite3-wasm.c), primarily
683 # for variadic macros and snprintf() to implement
684 # sqlite3__wasm_enum_json().
685 emcc.cflags += -I. -I$(dir.top)
686
687 #
688 # emcc flags specific to building .js/.wasm files...
689 #
690 emcc.jsflags = -fPIC
691 #emcc.jsflags += -Wno-gcc-install-dir-libstdcxx
692 #emcc is not passing ^^^ this on to clang
693 emcc.jsflags += --no-entry
694 emcc.jsflags += -sWASM_BIGINT=$(emcc.WASM_BIGINT)
695 emcc.jsflags += -sMODULARIZE
696 emcc.jsflags += -sDYNAMIC_EXECUTION=0
697 emcc.jsflags += -sNO_POLYFILL
698 emcc.jsflags += -sEXPORTED_FUNCTIONS=@$(EXPORTED_FUNCTIONS.api)
699 emcc.exportedRuntimeMethods = \
700 -sEXPORTED_RUNTIME_METHODS=wasmMemory
701 # wasmMemory ==> required by our code for use with -sIMPORTED_MEMORY
702 # Emscripten 4.0.7 (2025-04-15) stops exporting HEAP* by default.
703 emcc.jsflags += $(emcc.exportedRuntimeMethods)
704 emcc.jsflags += -sUSE_CLOSURE_COMPILER=0
705 emcc.jsflags += -sIMPORTED_MEMORY
706 ifeq (,$(filter -O0,$(emcc_opt)))
707 emcc.assert ?= 0
708 else
709 emcc.assert ?= 2
710 endif
711 emcc.jsflags += -sASSERTIONS=$(emcc.assert)
712 emcc.jsflags += -sSTRICT_JS=0
713 # STRICT_JS disabled due to:
714 # https://github.com/emscripten-core/emscripten/issues/18610
715 # TL;DR: does not work with MODULARIZE or EXPORT_ES6 as of version
716 # 3.1.31. The fix for that in newer emcc's is to throw a built-time
717 # error if STRICT_JS is used together with those options.
718
719 # emcc.jsflags += -sSTRICT=1
720 # -sSTRICT=1 Causes failures about unknown symbols which the build
721 # tools should be installing, e.g. __syscall_geteuid32
722
723 #
724 # -sINITIAL_MEMORY: How much memory we need to start with is governed
725 # at least in part by whether -sALLOW_MEMORY_GROWTH is enabled. If so,
726 # we can start with less. If not, we need as much as we'll ever
727 # possibly use (which, of course, we can't know for sure). speedtest1
728 # shows that performance for even moderate workloads MAY suffer
729 # considerably if we start small and have to grow at runtime.
730 # e.g. OPFS-backed (speedtest1 --size 75) take MAY take X time with
731 # 16mb+ memory and 3X time when starting with 8MB. However, such test
732 # results are inconsistent due to browser internals which are opaque
733 # to us.
734 #
735 # 2024-03-04: emsdk 3.1.55 replaces INITIAL_MEMORY with INITIAL_HEAP,
736 # but also says (in its changelog): "Note that it is currently not
737 # supported in all configurations (#21071)."
738 # https://github.com/emscripten-core/emscripten/blob/main/ChangeLog.md
739 #
740 # 2025-09-25: it turns out that _this_ WASM's heap size is not
741 # affected by Emscripten's in-memory virtual filesystem, so we don't
742 # strictly need a lot of heap. Resizing the heap is slow, though, so
743 # we want to start off with some room to grow.
744 #
745 emcc.jsflags += -sALLOW_MEMORY_GROWTH
746 emcc.INITIAL_MEMORY.128 = 134217728
747 emcc.INITIAL_MEMORY.96 = 100663296
748 emcc.INITIAL_MEMORY.64 = 67108864
749 emcc.INITIAL_MEMORY.32 = 33554432
750 emcc.INITIAL_MEMORY.16 = 16777216
751 emcc.INITIAL_MEMORY.8 = 8388608
752 emcc.INITIAL_MEMORY.4 = 4194304
753 emcc.INITIAL_MEMORY ?= 8
754 ifeq (,$(emcc.INITIAL_MEMORY.$(emcc.INITIAL_MEMORY)))
755 $(error emcc.INITIAL_MEMORY must be one of: 4, 8, 16, 32, 64, 96, 128 (megabytes))
756 endif
757 emcc.jsflags += -sINITIAL_MEMORY=$(emcc.INITIAL_MEMORY.$(emcc.INITIAL_MEMORY))
758 #
759 # /INITIAL_MEMORY
760 #
761
762 emcc.jsflags += $(emcc.environment)
763 emcc.jsflags += -sSTACK_SIZE=512KB
764 # ^^^ ACHTUNG: emsdk 3.1.27 reduced the default stack size from 5MB to
765 # a mere 64KB, which leads to silent memory corruption via the kvvfs
766 # VFS, which requires twice that for its xRead() and xWrite() methods.
767 # 2023-03: those methods have since been adapted to use a malloc()'d
768 # buffer.
769
770 #
771 # $(sqlite3.js.init-func) is the name Emscripten assigns our exported
772 # module init/load function. This symbol name is hard-coded in
773 # $(extern-post-js.js) as well as in numerous docs.
774 #
775 # "sqlite3InitModule" is the symbol we document for client use, so
776 # that's the symbol name which must be exported, whether it comes from
777 # Emscripten or our own code in extern-post-js.js.
778 #
779 # That said... we can change $(sqlite3.js.init-func) as long as the
780 # name "sqlite3InitModule" is the one which gets exposed via the
781 # resulting JS files. That can be accomplished via
782 # extern-post-js.js. However... using a temporary symbol name here
783 # and then adding sqlite3InitModule() ourselves results in 2 global
784 # symbols: we cannot "delete" the Emscripten-defined
785 # $(sqlite3.js.init-func) from vanilla builds (as opposed to ESM
786 # builds) because it's declared with "var".
787 sqlite3.js.init-func = sqlite3InitModule
788 emcc.jsflags += -sEXPORT_NAME=$(sqlite3.js.init-func)
789 emcc.jsflags += -sGLOBAL_BASE=4096 # HYPOTHETICALLY keep func table indexes from overlapping w/ heap addr.
790 #emcc.jsflags += -sSTRICT # fails due to missing __syscall_...()
791 #emcc.jsflags += -sALLOW_UNIMPLEMENTED_SYSCALLS
792 #emcc.jsflags += -sFILESYSTEM=0 # only for experimentation. fiddle needs the FS API
793 #emcc.jsflags += -sABORTING_MALLOC # only for experimentation
794 emcc.jsflags += -sALLOW_TABLE_GROWTH
795 # ^^^^ -sALLOW_TABLE_GROWTH is required for installing new SQL UDFs
796 emcc.jsflags += -Wno-limited-postlink-optimizations
797 # ^^^^ emcc likes to warn when we have "limited optimizations" via the
798 # -g3 flag.
799 # emcc.jsflags += -sSTANDALONE_WASM # causes OOM errors, not sure why.
800
801 # Re. undefined symbol handling, see: https://lld.llvm.org/WebAssembly.html
802 emcc.jsflags += -sERROR_ON_UNDEFINED_SYMBOLS=1
803 emcc.jsflags += -sLLD_REPORT_UNDEFINED
804 #emcc.jsflags += --allow-undefined
805 #emcc.jsflags += --import-undefined
806 #emcc.jsflags += --unresolved-symbols=import-dynamic --experimental-pic
807 #emcc.jsflags += --experimental-pic --unresolved-symbols=ingore-all --import-undefined
808 #emcc.jsflags += --unresolved-symbols=ignore-all
809
810 #
811 # -sSINGLE_FILE:
812 # https://github.com/emscripten-core/emscripten/blob/main/src/settings.js
813 #
814 # -sSINGLE_FILE=1 would be _really_ nice but we have to build with -g3
815 # for -O2 and higher to work (else minification breaks the code) and
816 # cannot wasm-strip the binary before it gets encoded into the JS
817 # file. The result is that the generated JS file is, because of the
818 # -g3 debugging info, _huge_.
819 #
820
821 #
822 # b.call.patch-export-default is used by mkwasmbuilds.c and the
823 # wasmfs build. $1 is 1 if the build mode needs this workaround
824 # (modes: esm, bundler-friendly, node) and 0 if not (vanilla). $2 must
825 # be 0 for all builds except sqlite3-wasmfs.mjs, in which case it must
826 # be 1. $(3) is an optional log prefix, defaulting to $(logtag.@)
827 #
828 # Reminder for ESM builds: even if we use -sEXPORT_ES6=0, emcc _still_
829 # adds:
830 #
831 # export default $(sqlite3.js.init-func);
832 #
833 # when building *.mjs, which is bad because we need to export an
834 # overwritten version of that function and cannot "export default"
835 # twice. Because of this, we have to sed *.mjs to remove the _first_
836 # instance (only) of /^export default/.
837 #
838 # Upstream RFE:
839 # https://github.com/emscripten-core/emscripten/issues/18237
840 #
841 # Maintenance reminder: Mac sed works differently than GNU sed, so we
842 # use awk instead of sed for this.
843 #
844 define b.call.patch-export-default
845 if [ x1 = x$(1) ]; then \
846 echo "$(if $(3),$(3),$(logtag.@)) $(emo.bug) Fragile" \
847 "workaround for emscripten/issues/18237." \
848 "See b.call.patch-export-default."; \
849 {\
850 awk '/^export default/ && !f{f=1; next} 1' $@ \
851 > [email protected] && mv [email protected] $@; \
852 } || exit; \
853 if [ x1 = x$(2) ]; then \
854 if ! grep -q '^export default' $@; then \
855 echo "Cannot find export default." 1>&2; \
856 exit 1; \
857 fi; \
858 fi; \
859 fi
860 endef
861
862 #
863 # $(sqlite3-license-version.js) contains the license header and
864 # in-comment build version info.
865 #
866 # Maintenance reminder: there are awk binaries out there which do not
867 # support -e SCRIPT.
868 #
869 sqlite3-license-version.js = $(dir.tmp)/sqlite3-license-version.js
870 $(sqlite3-license-version.js): $(bin.version-info) \
871 $(dir.api)/sqlite3-license-version-header.js $(MAKEFILE)
872 @$(call b.mkdir@); echo '$(logtag.@) $(emo.disk)'; { \
873 cat $(dir.api)/sqlite3-license-version-header.js || exit $$?; \
874 echo '/* @preserve'; \
875 echo '** This code was built from sqlite3 version...'; \
876 echo '**'; \
877 awk '/define SQLITE_VERSION/{$$1=""; print "**" $$0}' $(sqlite3.h); \
878 awk '/define SQLITE_SOURCE_ID/{$$1=""; print "**" $$0}' $(sqlite3.h); \
879 echo '**'; echo '** Emscripten SDK: $(emcc.version)'; \
880 echo '*/'; \
881 } > $@
882
883 #
884 # $(sqlite3-api-build-version.js) injects the build version info into
885 # the bundle in JSON form.
886 #
887 sqlite3-api-build-version.js = $(dir.tmp)/sqlite3-api-build-version.js
888 $(sqlite3-api-build-version.js): $(bin.version-info) $(MAKEFILE)
889 @echo '$(logtag.@) $(emo.disk)'; { \
890 $(call b.mkdir@); \
891 echo 'globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){'; \
892 echo -n ' sqlite3.version = '; \
893 $(bin.version-info) --json; \
894 echo ';'; \
895 echo '});'; \
896 } > $@
897
898 #
899 # Inputs/outputs for the sqlite3-api.js family.
900 #
901 # sqlite3-api.jses = the list of JS files which make up
902 # sqlite3-api.js, in the order they need to be assembled.
903 sqlite3-api.jses = $(sqlite3-license-version.js)
904 sqlite3-api.jses += $(dir.api)/sqlite3-api-prologue.js
905 sqlite3-api.jses += $(sqlite3-api-build-version.js)
906 sqlite3-api.jses += $(dir.common)/whwasmutil.js
907 sqlite3-api.jses += $(dir.jacc)/jaccwabyt.js
908 sqlite3-api.jses += $(dir.api)/sqlite3-api-glue.c-pp.js
909 sqlite3-api.jses += $(dir.api)/sqlite3-api-oo1.c-pp.js
910 sqlite3-api.jses += $(dir.api)/sqlite3-api-worker1.c-pp.js
911 sqlite3-api.jses += $(dir.api)/sqlite3-vfs-helper.c-pp.js
912 ifeq (0,$(wasm-bare-bones))
913 sqlite3-api.jses += $(dir.api)/sqlite3-vtab-helper.c-pp.js
914 endif
915 sqlite3-api.jses += $(dir.api)/sqlite3-vfs-kvvfs.c-pp.js
916 sqlite3-api.jses += $(dir.api)/opfs-common-shared.c-pp.js
917 sqlite3-api.jses += $(dir.api)/sqlite3-vfs-opfs.c-pp.js
918 sqlite3-api.jses += $(dir.api)/sqlite3-vfs-opfs-sahpool.c-pp.js
919 sqlite3-api.jses += $(dir.api)/sqlite3-vfs-opfs-wl.c-pp.js
920
921 # Parallel builds can fail if $(sqlite3-license-version.js) is not
922 # created early enough, so make all files in $(sqlite-api.jses) except
923 # for $(sqlite3-license-version.js) depend on
924 # $(sqlite3-license-version.js).
925 deps.jses = $(filter-out $(sqlite3-license-version.js),$(sqlite3-api.jses))
926 $(deps.jses): $(sqlite3-license-version.js)
927
928 #
929 # extern-post-js* and extern-pre-js* are files for use with
930 # Emscripten's --extern-pre-js and --extern-post-js flags.
931 #
932 extern-pre-js.js = $(dir.api)/extern-pre-js.js
933 extern-post-js.in.js = $(dir.api)/extern-post-js.c-pp.js
934
935 #
936 # Emscripten flags for --[extern-][pre|post]-js=... for the
937 # various builds.
938 # pre-post-jses.*.deps = lists of dependencies for the
939 # --[extern-][pre/post]-js files.
940 #
941 pre-post-jses.common.deps = $(extern-pre-js.js) $(sqlite3-license-version.js)
942
943 # --post-js and --pre-js are emcc flags we use to append/prepend JS to
944 # the generated emscripten module file. These rules set up the core
945 # pre/post files for use by the various builds. --pre-js is used to
946 # inject code which needs to run as part of the pre-WASM-load phase.
947 # --post-js injects code which runs after the WASM module is loaded
948 # and includes the entirety of the library plus some
949 # Emscripten-specific post-bootstrapping code.
950 pre-js.in.js = $(dir.api)/pre-js.c-pp.js
951 post-js.in.js = $(dir.tmp)/post-js.c-pp.js
952 post-jses.js = \
953 $(dir.api)/post-js-header.js \
954 $(sqlite3-api.jses) \
955 $(dir.api)/post-js-footer.js
956 $(post-js.in.js): $(MKDIR.bld) $(post-jses.js) $(MAKEFILE)
957 @$(call b.echo,@,$(emo.disk)); \
958 for i in $(post-jses.js); do \
959 echo "/* BEGIN FILE: $$i */"; \
960 cat $$i || exit $$?; \
961 echo "/* END FILE: $$i */"; \
962 done > $@
963
964 #
965 # speedtest1 decls needed before the $(bin.mkwb)-generated makefile
966 # is included.
967 #
968 bin.speedtest1 = ../../speedtest1
969 speedtest1.c = ../../test/speedtest1.c
970 speedtest1.c.in = $(speedtest1.c) $(sqlite3-wasm.c)
971 EXPORTED_FUNCTIONS.speedtest1 = $(abspath $(dir.tmp)/EXPORTED_FUNCTIONS.speedtest1)
972
973 #
974 # fiddle build flags
975 #
976 # Flags specifically for debug builds of fiddle. Performance suffers
977 # greatly in debug builds.
978 ########################################################################
979 # shell.c and its build flags...
980 #
981 # We should ideally collect these from ../../configure and past
982 # them in ./config.make. The problem with that is that SHELL_OPT is
983 # generated at make-time, not configure-time.
984 ifneq (1,$(MAKING_CLEAN))
985 make-np-0 = make -C $(dir.top) -n -p
986 make-np-1 = sed -e 's/(TOP)/(dir.top)/g'
987 # Extract SHELL_OPT and SHELL_DEP from the top-most makefile and import
988 # them as vars here...
989 $(eval $(shell $(make-np-0) | grep -e '^SHELL_OPT ' | $(make-np-1)))
990 $(eval $(shell $(make-np-0) | grep -e '^SHELL_DEP ' | $(make-np-1)))
991 # ^^^ can't do that in 1 invocation b/c newlines get stripped
992 ifeq (,$(SHELL_OPT))
993 $(error Could not parse SHELL_OPT from $(dir.top)/Makefile.)
994 endif
995 ifeq (,$(SHELL_DEP))
996 $(error Could not parse SHELL_DEP from $(dir.top)/Makefile.)
997 endif
998 $(dir.top)/shell.c: $(SHELL_DEP) $(dir.tool)/mkshellc.tcl $(sqlite3.c)
999 $(MAKE) -C $(dir.top) shell.c
1000 endif
1001 # /shell.c
1002 ########################################################################
1003
1004 #
1005 # Fiddle-related decls we need before .wasmbuilds is included
1006 #
1007
1008 fiddle.c.in = $(dir.top)/shell.c $(sqlite3-wasm.c)
1009
1010 EXPORTED_FUNCTIONS.fiddle = $(dir.tmp)/EXPORTED_FUNCTIONS.fiddle
1011 $(EXPORTED_FUNCTIONS.fiddle): $(EXPORTED_FUNCTIONS.api.in) \
1012 $(MAKEFILE_LIST) $(bin.c-pp)
1013 @$(call b.mkdir@)
1014 @$(call b.c-pp.shcmd,fiddle,$(EXPORTED_FUNCTIONS.api.in),\
1015 $@,$(EXPORTED_FUNCTIONS.c-pp.flags) -Dfiddle)
1016 @echo $(logtag.@) $(emo.disk)
1017
1018
1019 emcc.flags.fiddle = \
1020 $(emcc.cflags) $(emcc_opt_full) \
1021 --minify 0 \
1022 -sALLOW_TABLE_GROWTH \
1023 -sMEMORY64=$(emcc.MEMORY64) \
1024 -sINITIAL_MEMORY=$(emcc.INITIAL_MEMORY.8) \
1025 -sABORTING_MALLOC \
1026 -sSTRICT_JS=0 \
1027 -sENVIRONMENT=web,worker \
1028 -sMODULARIZE \
1029 -sDYNAMIC_EXECUTION=0 \
1030 -sWASM_BIGINT=$(emcc.WASM_BIGINT) \
1031 -sEXPORT_NAME=$(sqlite3.js.init-func) \
1032 -Wno-limited-postlink-optimizations \
1033 $(emcc.exportedRuntimeMethods),FS \
1034 -sEXPORTED_FUNCTIONS=@$(abspath $(EXPORTED_FUNCTIONS.fiddle)) \
1035 $(SQLITE_OPT.full-featured) \
1036 $(SQLITE_OPT.common) \
1037 $(SHELL_OPT) \
1038 -UHAVE_READLINE -UHAVE_EDITLINE -UHAVE_LINENOISE \
1039 -USQLITE_HAVE_ZLIB \
1040 -USQLITE_WASM_BARE_BONES \
1041 -DSQLITE_SHELL_FIDDLE
1042
1043 emcc.flags.fiddle.debug = $(emcc.flags.fiddle) \
1044 -DSQLITE_DEBUG \
1045 -DSQLITE_ENABLE_SELECTTRACE \
1046 -DSQLITE_ENABLE_WHERETRACE
1047
1048 clean: clean-fiddle
1049 clean-fiddle:
1050 rm -f $(dir.fiddle)/fiddle-module.js \
1051 $(dir.fiddle)/*.wasm \
1052 $(dir.fiddle)/sqlite3-opfs-*.js \
1053 $(dir.fiddle)/*.gz \
1054 $(dir.fiddle)/index.html \
1055 $(EXPORTED_FUNCTIONS.fiddle)
1056 rm -fr $(dir.fiddle-debug)
1057 distclean: distclean-fiddle
1058 distclean-fiddle:
1059 rm -fr $(dir.fiddle)/jqterm
1060
1061 #
1062 # WASMFS build - unsupported and untested. We used WASMFS
1063 # to jumpstart development early on, but it has always been
1064 # a moving target, in that Emscripten updates have broken
1065 # our build often enough that we no longer actively support it.
1066 # It's interesting to keep around, though.
1067 #
1068 # Only add wasmfs if wasmfs.enable=1 or we're running (dist)clean
1069 #
1070 ifneq (,$(filter wasmfs b-wasmfs for-testing,$(MAKECMDGOALS)))
1071 wasmfs.enable ?= 1
1072 else
1073 # Unconditionally enable wasmfs for [dist]clean so that the wasmfs
1074 # sub-make can clean up.
1075 wasmfs.enable ?= $(MAKING_CLEAN)
1076 endif
1077 cflags.wasmfs = -DSQLITE_ENABLE_WASMFS
1078 # end wasmfs (the rest is in mkwasmbuilds.c)
1079 #
1080
1081 #
1082 #
1083 #
1084 sqlite3-wasm.c = $(dir.api)/sqlite3-wasm.c
1085 # List of input files for compiling $(sqlite3-wasm.c). That file
1086 # #include's sqlite3.c directly, so it's implicitly includes here.
1087 sqlite3-wasm.c.in = $(sqlite3-wasm.c) $(sqlite3_wasm_extra_init.c)
1088
1089 #
1090 # $(bin.mkwb) is used for generating much of the makefile code for the
1091 # various wasm builds. It used to be generated in this makefile via a
1092 # difficult-to-read/maintain block of $(eval)'d code. Attempts were
1093 # made to generate it from tcl and bash (shell) but having to escape
1094 # the $ references in those languages made it just as illegible as the
1095 # native makefile code. Somewhat surprisingly, moving that code
1096 # generation to C makes it slightly less illegible than the previous 3
1097 # options.
1098 #
1099 # Maintenance notes:
1100 #
1101 # - Ordering of this block within this file is fragile. The generated
1102 # makefile sets up many vars which are useful for the other targets.
1103 #
1104 # - Vars which are used by $(bin.mkwb) in dependency lists and such
1105 # need to be defined before this is included. Those used in recipies
1106 # may be defined after this step.
1107 #
1108 bin.mkwb = ./mkwasmbuilds
1109 ifneq (1,$(MAKING_CLEAN))
1110 $(bin.mkwb): $(bin.mkwb).c $(MAKEFILE)
1111 $(CC) -O0 -g -std=c99 -o $@ $< -DWASM_CUSTOM_INSTANTIATE=$(WASM_CUSTOM_INSTANTIATE)
1112
1113 .wasmbuilds.make: $(bin.mkwb)
1114 @rm -f $@
1115 $(bin.mkwb) > $@
1116 @chmod -w $@
1117 -include .wasmbuilds.make
1118 endif
1119 CLEAN_FILES += .wasmbuilds.make $(bin.mkwb)
1120
1121 #
1122 # $(sqlite3.ext.js) = API-related files which are standalone
1123 # files, not part of the amalgamation. This list holds
1124 # the name of each such _output_ file.
1125 #
1126 sqlite3.ext.js =
1127
1128 ########################################################################
1129 # We need separate copies of certain supplementary JS files for the
1130 # bundler-friendly build. Concretely, any supplemental JS files which
1131 # themselves use importScripts() or Workers or URL() constructors
1132 # which refer to other in-tree (m)JS files require a bundler-friendly
1133 # copy. Bundler-friendly builds replace certain references to string
1134 # vars/expressions with string literals, as bundler tools are static
1135 # code analyzers and cannot cope with the former.
1136
1137 #
1138 # sqlite3-worker1*.*
1139 # TODO: 64-bit
1140 #
1141 define gen-worker1
1142 # $1 = X.ext part of sqlite3-worker1X.ext
1143 # $2 = $(c-pp.D.NAME)
1144 $(call b.c-pp.target,filter,$$(dir.api)/sqlite3-worker1.c-pp.js,\
1145 $$(dir.dout)/sqlite3-worker1$(1),$(2))
1146 sqlite3.ext.js += $$(dir.dout)/sqlite3-worker1$(1)
1147 all: $$(dir.dout)/sqlite3-worker1$(1)
1148 endef
1149
1150 $(eval $(call gen-worker1,.js,$(c-pp.D.vanilla)))
1151 $(eval $(call gen-worker1,.mjs,$(c-pp.D.esm)))
1152 $(eval $(call gen-worker1,-bundler-friendly.mjs,$(c-pp.D.bundler)))
1153
1154 #
1155 # sqlite3-worker1-promiser*.*
1156 # TODO: 64-bit
1157 #
1158 define gen-promiser
1159 # $1 = X.ext part of sqlite3-worker1-promiserX.ext
1160 # $2 = $(c-pp.D.NAME)
1161 $(call b.c-pp.target,filter,$$(dir.api)/sqlite3-worker1-promiser.c-pp.js,\
1162 $$(dir.dout)/sqlite3-worker1-promiser$(1),$(2))
1163 sqlite3.ext.js += $$(dir.dout)/sqlite3-worker1-promiser$(1)
1164 all: $$(dir.dout)/sqlite3-worker1-promiser$(1)
1165 endef
1166
1167 $(eval $(call gen-promiser,.js,$(c-pp.D.vanilla)))
1168 $(eval $(call gen-promiser,.mjs,$(c-pp.D.esm)))
1169 $(eval $(call gen-promiser,-bundler-friendly.mjs,$(c-pp.D.bundler)))
1170
1171 #
1172 # demo1-worker-*.*:
1173 # $1 = .js or .mjs
1174 # $2 = .html or -esm.html
1175 # $3 = -D... flags for $(bin.c-pp)
1176 #
1177 define gen-dwp
1178 $(call b.c-pp.target,test,demo-worker1-promiser.c-pp.js,demo-worker1-promiser$(1),$(3))
1179 $(call b.c-pp.target,test,demo-worker1-promiser.c-pp.html,demo-worker1-promiser$(2),$(3))
1180 demos: demo-worker1-promiser$(1) demo-worker1-promiser$(2)
1181 endef
1182 $(eval $(call gen-dwp,.js,.html,$(c-pp.D.vanilla)))
1183 $(eval $(call gen-dwp,.mjs,-esm.html,$(c-pp.D.esm)))
1184 all: demos
1185 # End worker/promiser generation
1186 #######################################################################
1187
1188 #
1189 # "SOAP" is not part of the amalgamation but gets copied into the
1190 # build output folder and into each of the fiddle builds.
1191 #
1192 sqlite3.ext.js += $(dir.dout)/sqlite3-opfs-async-proxy.js
1193 $(eval $(call b.c-pp.target,soap,\
1194 $(dir.api)/sqlite3-opfs-async-proxy.c-pp.js,\
1195 $(dir.dout)/sqlite3-opfs-async-proxy.js))
1196
1197 #
1198 # Add a dep of $(sqlite3.ext.js) on every individual build's JS file.
1199 # The primary purpose of this is to force them to be copied early in
1200 # the build process, which is sometimes a time-saver during
1201 # development, allowing the developer to reload a test page while
1202 # other parts of the build are still running. Another reason is that
1203 # we don't otherwise have a great place to attach them such that
1204 # they're always copied when we need them.
1205 #
1206 # The var $(out.$(B).js) comes from $(bin.mkwb) and $(B) is the name
1207 # of a build set up by that tool, e.g. b-vanilla or b-esm64.
1208 #
1209 $(foreach B,$(b.names),$(eval $(out.$(B).js): $(sqlite3.ext.js)))
1210
1211 #
1212 # b-all: builds all available js/wasm builds.
1213 #
1214 $(foreach B,$(b.names),$(eval b-all: $(out.$(B).js)))
1215
1216 #$(foreach B,$(b.names),$(eval pre: $(pre-js.$(B).js)))
1217 $(foreach B,$(b.names),$(eval post: $(post-js.$(B).js)))
1218
1219 #
1220 # speedtest1 is our primary benchmarking tool.
1221 #
1222 # emcc.speedtest1.common = emcc flags used by multiple builds of speedtest1
1223 # emcc.speedtest1 = emcc flags used by the main build of speedtest1
1224 #
1225 # These flags get applied via $(bin.mkwb).
1226 emcc.speedtest1.common = $(emcc_opt_full)
1227 emcc.speedtest1 = -I. -I$(dir $(sqlite3.canonical.c))
1228 emcc.speedtest1 += -sENVIRONMENT=web,worker
1229 emcc.speedtest1 += -sALLOW_MEMORY_GROWTH
1230 emcc.speedtest1 += -sINITIAL_MEMORY=$(emcc.INITIAL_MEMORY.32)
1231 emcc.speedtest1.common += -sINVOKE_RUN=0
1232 emcc.speedtest1.common += --no-entry
1233 emcc.speedtest1.common += -sABORTING_MALLOC
1234 emcc.speedtest1.common += -sSTRICT_JS=0
1235 emcc.speedtest1.common += -sMODULARIZE
1236 emcc.speedtest1.common += -Wno-limited-postlink-optimizations
1237 emcc.speedtest1.common += -Wno-unused-main
1238 # ^^^^ -Wno-unused-main is for emcc 3.1.52+. speedtest1 has a wasm_main() which is
1239 # exported and called by the JS code.
1240 emcc.speedtest1.common += -sSTACK_SIZE=512KB
1241 emcc.speedtest1.common += -sEXPORTED_FUNCTIONS=@$(EXPORTED_FUNCTIONS.speedtest1)
1242 emcc.speedtest1.common += $(emcc.exportedRuntimeMethods)
1243 emcc.speedtest1.common += -sALLOW_TABLE_GROWTH
1244 emcc.speedtest1.common += -sDYNAMIC_EXECUTION=0
1245 emcc.speedtest1.common += --minify 0
1246 emcc.speedtest1.common += -sEXPORT_NAME=$(sqlite3.js.init-func)
1247 emcc.speedtest1.common += -sWASM_BIGINT=$(emcc.WASM_BIGINT)
1248 speedtest1.exit-runtime0 = -sEXIT_RUNTIME=0
1249 speedtest1.exit-runtime1 = -sEXIT_RUNTIME=1
1250 # Re -sEXIT_RUNTIME=1 vs 0: if it's 1 and speedtest1 crashes, we get
1251 # this error from Emscripten:
1252 #
1253 # > native function `free` called after runtime exit (use
1254 # NO_EXIT_RUNTIME to keep it alive after main() exits))
1255 #
1256 # If it's 0 and it crashes, we get:
1257 #
1258 # > stdio streams had content in them that was not flushed. you should
1259 # set EXIT_RUNTIME to 1 (see the FAQ), or make sure to emit a newline
1260 # when you printf etc.
1261 #
1262 # and pending output is not flushed because it didn't end with a
1263 # newline (by design). The lesser of the two evils seems to be
1264 # -sEXIT_RUNTIME=1 but we need EXIT_RUNTIME=0 for the worker-based app
1265 # which runs speedtest1 multiple times.
1266
1267 $(EXPORTED_FUNCTIONS.speedtest1): $(EXPORTED_FUNCTIONS.api)
1268 @$(call b.mkdir@); $(call b.echo,@,$(emo.disk)); \
1269 { echo _wasm_main; cat $(EXPORTED_FUNCTIONS.api); } > $@ || exit
1270 speedtest1: b-speedtest1
1271 st: speedtest1
1272
1273 #
1274 # Generate 64-bit variants of speedtest1*.{js,html}
1275 #
1276 # $1 = input file
1277 # $2 = output file
1278 #
1279 # TODO: preprocess these like we do the rest.
1280 #
1281 define gen-st64
1282 $(2): $(1)
1283 @$$(call b.echo,speedtest164,$$(emo.disk)$(emo.lock) Creating from $$<)
1284 rm -f $$@; \
1285 sed -e 's/speedtest1\.js/speedtest1-64bit\.js/' \
1286 -e 's/speedtest1-worker\.js/speedtest1-worker-64bit\.js/' \
1287 < $$< > $$@; \
1288 chmod -w $$@
1289 $(2): b-speedtest164
1290 speedtest1: $(1) $(2)
1291 CLEAN_FILES += $(2)
1292 endef
1293 speedtest1: b-speedtest164
1294
1295 $(eval $(call gen-st64,speedtest1.html,speedtest1-64bit.html))
1296 $(eval $(call gen-st64,speedtest1-worker.html,speedtest1-worker-64bit.html))
1297 $(eval $(call gen-st64,speedtest1-worker.js,speedtest1-worker-64bit.js))
1298 # end speedtest1.js
1299 ########################################################################
1300
1301 #
1302 # tester1 is the main unit and regression test application and needs
1303 # to be able to run in 4 separate modes to cover the primary
1304 # client-side use cases:
1305 #
1306 # 1) Load sqlite3 in the main UI thread of a conventional script.
1307 # 2) Load sqlite3 in a conventional Worker thread.
1308 # 3) Load sqlite3 as an ES6 module (ESM) in the main thread.
1309 # 4) Load sqlite3 as an ESM worker. (Not all browsers support this.)
1310 #
1311 # To that end, we require two separate builds of tester1.js:
1312 #
1313 # tester1.js: cases 1 and 2
1314 # tester1.mjs: cases 3 and 4
1315 #
1316 # Then we need those again in 64-bit builds, which require a 64-bit
1317 # pair of js/wasm files.
1318 #
1319 # To create those, we filter tester1.c-pp.js/html with $(bin.c-pp)...
1320
1321 #
1322 # tester1.js variants:
1323 #
1324 define gen-tester1.js
1325 # $1 = build name to have a dep on
1326 # $2 = suffix for tester1SUFFIX JS
1327 # $3 = $(bin.c-pp) flags
1328 $(call b.c-pp.target,test,tester1.c-pp.js,tester1$(2),$(3))
1329 tester1$(2): $(sqlite3.ext.js) $(out.$(1).wasm)
1330 tester1-$(1): tester1$(2)
1331 tester1: tester1$(2)
1332 endef
1333
1334 $(eval $(call gen-tester1.js,vanilla,.js,\
1335 $(c-pp.D.vanilla) -Dsqlite3.js=$(dir.dout)/sqlite3.js))
1336 $(eval $(call gen-tester1.js,vanilla64,-64bit.js,\
1337 $(c-pp.D.vanilla64) -Dsqlite3.js=$(dir.dout)/sqlite3-64bit.js))
1338 $(eval $(call gen-tester1.js,esm,.mjs,\
1339 $(c-pp.D.esm) -Dsqlite3.js=$(dir.dout)/sqlite3.mjs))
1340 $(eval $(call gen-tester1.js,esm64,-64bit.mjs,\
1341 $(c-pp.D.esm64) -Dsqlite3.js=$(dir.dout)/sqlite3-64bit.mjs))
1342
1343 #
1344 # tester1.html variants:
1345 #
1346 define gen-tester1.html
1347 # $1 = build name to have a dep on
1348 # $2 = filename suffix: empty, -64bit, -esm, esm-64bit
1349 # $3 = $(bin.c-pp) flags
1350 $(call b.c-pp.target,test,tester1.c-pp.html,tester1$(2).html,$(3))
1351 tester1$(2).html: tester1-$(1)
1352 tester1: tester1$(2).html
1353 endef
1354
1355 $(eval $(call gen-tester1.html,vanilla,,\
1356 $(c-pp.D.vanilla) \
1357 -Dbitness=32 \
1358 -Dtitle="UI thread" \
1359 -Dtester1.js=tester1.js \
1360 -Dsqlite3.js=$(dir.dout)/sqlite3.js))
1361 $(eval $(call gen-tester1.html,vanilla64,-64bit,\
1362 $(c-pp.D.vanilla64) \
1363 -Dbitness=64 \
1364 -Dtitle="UI thread" \
1365 -Dtester1.js=tester1-64bit.js \
1366 -Dsqlite3.js=$(dir.dout)/sqlite3-64bit.js))
1367 $(eval $(call gen-tester1.html,esm,-esm,\
1368 $(c-pp.D.esm) \
1369 -Dbitness=32 \
1370 -Dtitle="ES6 Module in UI thread" \
1371 -Dtester1.js=tester1.mjs \
1372 -Dsqlite3.js=$(dir.dout)/sqlite3.mjs))
1373 $(eval $(call gen-tester1.html,esm64,-esm-64bit,\
1374 $(c-pp.D.esm64) \
1375 -Dbitness=64 \
1376 -Dtitle="ES6 Module in UI thread" \
1377 -Dtester1.js=tester1-64bit.mjs \
1378 -Dsqlite3.js=$(dir.dout)/sqlite3-64bit.mjs))
1379
1380 #
1381 # tester1-worker.html variants: There is no ESM variant of this
1382 # file. Instead, that page accepts the ?esm URL flag to switch to ESM
1383 # mode.
1384 #
1385 $(eval $(call b.c-pp.target,test,tester1-worker.c-pp.html,\
1386 tester1-worker.html,-Dbitness=32))
1387 $(eval $(call b.c-pp.target,test,tester1-worker.c-pp.html,\
1388 tester1-worker-64bit.html,$(c-pp.D.64bit) -Dbitness=64))
1389 tester1: tester1-worker.html tester1-worker-64bit.html
1390 tester1-worker.html: tester1.mjs
1391 tester1-worker-64bit.html: tester1-64bit.mjs
1392
1393 all: tester1
1394 #
1395 # end tester1
1396 #
1397
1398 #
1399 # jquery.terminal support for fiddle:
1400 #
1401 # If a clone of https://github.com/jcubic/jquery.terminal
1402 # is found in $(JQTERM), defaulting to $(HOME)/src/jquery.terminal
1403 # then add jquery.terminal support to fiddle.
1404 #
1405 # To build that package, from its checkout dir:
1406 #
1407 # npm install
1408 # make
1409 #
1410 c-pp.D.fiddle ?=
1411 JQTERM ?= $(HOME)/src/jquery.terminal
1412 dir.jqtermExt = $(firstword $(wildcard $(JQTERM)))
1413 #$(info dir.jqtermExt=$(dir.jqtermExt))
1414 ifeq (0,$(MAKING_CLEAN))
1415 ifeq (,$(wildcard $(dir.jqtermExt)/js/jquery.terminal.min.js))
1416 $(info $(emo.magic) To add jquery.terminal support to fiddle, set JQTERM=/path/to/its/built/checkout)
1417 else
1418 $(info $(emo.magic) jquery.terminal found in $(dir.jqtermExt) - adding it to fiddle. Make sure it is built!)
1419
1420 dir.jqterm = $(dir.fiddle)/jqterm
1421 $(dir.fiddle)/jqterm/jquery.terminal.bundle.min.js:
1422 @$(call b.mkdir@)
1423 cat $(dir.jqtermExt)/js/jquery-1*.min.js \
1424 $(dir.jqtermExt)/js/jquery.terminal.min.js > $@
1425
1426 $(dir.fiddle)/jqterm/jquery.terminal.min.css: $(dir.jqtermExt)/css/jquery.terminal.min.css
1427 @$(call b.mkdir@)
1428 @$(call b.cp,fiddle,$<,$(dir $@))
1429
1430 $(dir.fiddle)/index.html: $(dir.fiddle)/jqterm/jquery.terminal.bundle.min.js \
1431 $(dir.fiddle)/jqterm/jquery.terminal.min.css
1432 c-pp.D.fiddle += -Djqterm
1433 endif
1434 endif
1435 # ^^^ JQTERM/MAKING_CLEAN
1436
1437 #
1438 # Generate fiddle/index.html. Must come after JQTERM is handled.
1439 #
1440 $(dir.fiddle)/index.html: $(dir.fiddle)/index.c-pp.html
1441 $(eval $(call b.c-pp.target,fiddle,\
1442 $(dir.fiddle)/index.c-pp.html,$(dir.fiddle)/index.html,$(c-pp.D.fiddle)))
1443 $(out.fiddle.wasm): $(dir.fiddle)/index.html
1444
1445
1446 #
1447 # Convenience rules to rebuild with various -Ox levels. Much
1448 # experimentation shows -O2 to be the clear winner in terms of speed.
1449 # -Oz results are significantly smaller and only slightly slower than
1450 # -O2 (very roughly 10% in highly unscientific tests), so -Oz is the
1451 # shipping configuration.
1452 #
1453 # Achtung: build times with anything higher than -O0 are somewhat
1454 # painful, which is why -O0 is the default.
1455 #
1456 .PHONY: o0 o1 o2 o3 os oz
1457 emcc-opt-extra =
1458 #ifeq (1,$(wasm-bare-bones))
1459 #emcc-opt-extra += -flto
1460 # ^^^^ -flto can have a considerably performance boost at -O0 but
1461 # doubles the build time and seems to have negligible, if any, effect
1462 # on higher optimization levels.
1463 #
1464 # -flto does not shrink the size of bare-bones builds by any measurable
1465 # amount.
1466 #endif
1467 o0: clean
1468 $(MAKE) -e "emcc_opt=-O0"
1469 o1: clean
1470 $(MAKE) -e "emcc_opt=-O1 $(emcc-opt-extra)"
1471 o2: clean
1472 $(MAKE) -e "emcc_opt=-O2 $(emcc-opt-extra)"
1473 o3: clean
1474 $(MAKE) -e "emcc_opt=-O3 $(emcc-opt-extra)"
1475 os: clean
1476 @echo "$(emo.fire)WARNING$(emo.fire): -Os can result in a build with mysteriously missing pieces!"
1477 $(MAKE) -e "emcc_opt=-Os $(emcc-opt-extra)"
1478 oz: clean
1479 $(MAKE) -e "emcc_opt=-Oz $(emcc-opt-extra)"
1480
1481 #
1482 # Push files to the public wasm-testing.sqlite.org server.
1483 #
1484 # Ideally only -Oz builds should be pushed, so the practice has become:
1485 #
1486 # make clean
1487 # make -j4 for-testing
1488 # make push-testing
1489 #
1490 wasm-testing.include = *.js *.mjs *.html \
1491 ./tests \
1492 $(dir.dout) $(dir.common) $(dir.fiddle) $(dir.fiddle.debug) $(dir.jacc)
1493 wasm-testing.exclude = sql/speedtest1.sql jswasm/*/*
1494 wasm-testing.dir = /jail/sites/wasm-testing
1495 wasm-testing.dest ?= wasm-testing:$(wasm-testing.dir)
1496 # ---------------------^^^^^^^^^^^^ ssh alias
1497 .PHONY: push-testing
1498 push-testing:
1499 rsync -z -e ssh --ignore-times --chown=stephan:www-data --group -r \
1500 $(patsubst %,--exclude=%,$(wasm-testing.exclude)) \
1501 $(wasm-testing.include) $(wasm-testing.dest)
1502 @echo "Updating gzipped copies..."; \
1503 ssh wasm-testing 'cd $(wasm-testing.dir) && bash .gzip' || \
1504 echo "SSH failed: it's likely that stale content will be served via old gzip files."
1505
1506 #
1507 # build everything needed by push-testing with -Oz
1508 #
1509 .PHONY: for-testing
1510 for-testing: emcc_opt=-Oz
1511 for-testing: loud=1
1512 for-testing.deps = \
1513 tester1 demos \
1514 b-vanilla b-vanilla64 \
1515 b-esm b-esm64 \
1516 b-fiddle b-fiddle.debug \
1517 b-speedtest1 b-speedtest164 \
1518 b-wasmfs
1519 for-testing: $(for-testing.deps)
1520
1521 ########################################################################
1522 # If we find a copy of https://sqlite.org/wasm checked out, copy
1523 # certain files over to it, applying some automated edits...
1524 wasm.docs.home ?= ../../../wasm
1525 wasm.docs.found = $(if $(wildcard $(wasm.docs.home)/api-index.md),\
1526 $(wildcard $(wasm.docs.home)),)
1527 .PHONY: update-docs
1528 ifeq (,$(wasm.docs.found))
1529 update-docs:
1530 @echo "Cannot find wasm docs checkout."; \
1531 echo "Pass wasm.docs.home=/path/to/wasm/docs/checkout or edit this makefile to suit."; \
1532 exit 127
1533 else
1534 wasm.docs.jswasm = $(wasm.docs.home)/jswasm
1535 update-docs: $(bin.stripccomments) $(out.vanilla.js) $(out.vanilla.wasm)
1536 @echo "Copying files to the /wasm docs. Be sure to use an -Oz build for this!";
1537 cp -p $(out.vanilla.wasm) $(wasm.docs.jswasm)/.
1538 $(bin.stripccomments) -k -k < $(out.vanilla.js) \
1539 | sed -e '/^[ \t]*$$/d' > $(wasm.docs.jswasm)/sqlite3.js
1540 cp -p demo-123.js demo-123.html demo-123-worker.html $(wasm.docs.home)/.
1541 sed -n -e '/EXTRACT_BEGIN/,/EXTRACT_END/p' \
1542 module-symbols.html > $(wasm.docs.home)/module-symbols.html
1543 endif
1544 # end /wasm docs
1545 ########################################################################
1546
1547 # Run local web server for the test/demo pages.
1548 httpd:
1549 althttpd -max-age 1 -enable-sab 1 -page index.html
1550
1551 ########################################################################
1552 # fiddle_remote is the remote destination for the fiddle app. It must
1553 # be a [user@]HOST:/path for rsync. The target "should probably"
1554 # contain a symlink of index.html -> fiddle.html.
1555 fiddle_remote ?=
1556 ifeq (,$(fiddle_remote))
1557 ifneq (,$(wildcard /home/stephan))
1558 fiddle_remote = wh:www/wasm-testing/fiddle/.
1559 else ifneq (,$(wildcard /home/drh))
1560 #fiddle_remote = if appropriate, add that user@host:/path here
1561 endif
1562 endif
1563 push-fiddle: fiddle
1564 @if [ x = "x$(fiddle_remote)" ]; then \
1565 echo "fiddle_remote must be a [user@]HOST:/path for rsync"; \
1566 exit 1; \
1567 fi
1568 rsync -va fiddle/ $(fiddle_remote)
1569 # end fiddle remote push
1570 ########################################################################
1571
1572 .PHONY: clean distclean
1573 clean:
1574 -rm -f $(CLEAN_FILES)
1575 -rm -fr $(dir.dout) $(dir.tmp)
1576
1577 distclean: clean
1578 -rm -f $(DISTCLEAN_FILES)
1579
1580 CLEAN_FILES += *~ $(dir.jacc)/*~ $(dir.api)/*~ $(dir.common)/*~ $(dir.fiddle)/*~ \
1581
1582 ########################################################################
1583 # Create main client downloadable zip file:
1584 ifneq (,$(filter dist snapshot,$(MAKECMDGOALS)))
1585 ifeq (1,$(SQLITE_C_IS_SEE))
1586 dist-name-extra = -see
1587 else
1588 dist-name-extra =
1589 endif
1590 dist-name-prefix = sqlite-wasm$(dist-name-extra)
1591 .PHONY: dist
1592 dist:
1593 $(bin.bash) ./mkdist.sh $(dist-name-prefix)
1594 snapshot:
1595 $(bin.bash) ./mkdist.sh $(dist-name-prefix) --snapshot
1596 endif
1597 # ^^^ making dist/snapshot
1598 CLEAN_FILES += $(wildcard sqlite-wasm-*.zip)
1599
1600 ########################################################################
1601 # The npm target is specifically for preparing files for the downstream
1602 # https://github.com/sqlite/sqlite-wasm (npm) distribution.
1603 #
1604 # Per agreement with that project's maintainers, these filenames need
1605 # to remain stable. To avoid breakage in their deployment process, any
1606 # changes (like renaming files) which potentially break their deployment
1607 # needs to be communicated to that project via opening a new ticket or
1608 # direct coordination with its maintainers.
1609 #
1610 # This target does a full clean/rebuild so that we can ensure that the
1611 # optimization level is set consistently across all files.
1612 #
1613 npm.bundle.zip = npm-bundle.zip
1614 CLEAN_FILES += $(npm.bundle.zip)
1615 # Distributables which need to be built for npm:
1616 npm_files = $(addprefix $(dir.dout)/, \
1617 sqlite3-bundler-friendly.mjs \
1618 sqlite3-opfs-async-proxy.js \
1619 sqlite3-worker1-bundler-friendly.mjs \
1620 sqlite3-worker1-promiser.mjs \
1621 sqlite3-worker1.mjs \
1622 sqlite3.mjs \
1623 sqlite3.wasm \
1624 sqlite3-node.mjs \
1625 )
1626 npm: $(sqlite3.canonical.c)
1627 @echo "$(emo.cleanup) Forcing a clean rebuild to ensure consistent optimization flags."
1628 $(MAKE) clean
1629 $(MAKE) -e "emcc_opt=-Oz $(emcc-opt-extra)" $(npm_files)
1630 rm -f $(npm.bundle.zip); zip -r $(npm.bundle.zip) $(npm_files)
1631 unzip -l $(npm.bundle.zip)
1632
1633 ########################################################################
1634 # Explanation of, and some commentary on, various emcc build flags
1635 # follows. Full docs for these can be found at:
1636 #
1637 # https://github.com/emscripten-core/emscripten/blob/main/src/settings.js
1638 #
1639 # -sENVIRONMENT=web: elides bootstrap code related to non-web JS
1640 # environments like node.js. Removing this makes the output a tiny
1641 # tick larger but hypothetically makes it more portable to
1642 # non-browser JS environments.
1643 #
1644 # -sMODULARIZE: changes how the generated code is structured to avoid
1645 # declaring a global Module object and instead installing a function
1646 # which loads and initializes the module. The function is named...
1647 #
1648 # -sEXPORT_NAME=jsFunctionName (see -sMODULARIZE)
1649 #
1650 # -sEXPORTED_RUNTIME_METHODS=@/absolute/path/to/file: a file
1651 # containing a list of emscripten-supplied APIs, one per line, which
1652 # must be exported into the generated JS. Must be an absolute path!
1653 #
1654 # -sEXPORTED_FUNCTIONS=@/absolute/path/to/file: a file containing a
1655 # list of C functions, one per line, which must be exported via wasm
1656 # so they're visible to JS. C symbols names in that file must all
1657 # start with an underscore for reasons known only to the emcc
1658 # developers. e.g., _sqlite3_open_v2 and _sqlite3_finalize. Must be
1659 # an absolute path!
1660 #
1661 # -sSTRICT_JS ensures that the emitted JS code includes the 'use
1662 # strict' option. Note that -sSTRICT is more broadly-scoped and
1663 # results in build errors.
1664 #
1665 # -sALLOW_TABLE_GROWTH is required for (at a minimum) the UDF-binding
1666 # feature. Without it, JS functions cannot be made to proxy C-side
1667 # callbacks.
1668 #
1669 # -sABORTING_MALLOC causes the JS-bound _malloc() to abort rather than
1670 # return 0 on OOM. If set to 0 then all code which uses _malloc()
1671 # must, just like in C, check the result before using it, else
1672 # they're likely to corrupt the JS/WASM heap by writing to its
1673 # address of 0. It is, as of this writing, enabled in Emscripten by
1674 # default but we enable it explicitly in case that default changes.
1675 #
1676 # -sDYNAMIC_EXECUTION=0 disables eval() and the Function constructor.
1677 # If the build runs without these, it's preferable to use this flag
1678 # because certain execution environments disallow those constructs.
1679 # This flag is not strictly necessary, however.
1680 #
1681 # --no-entry: for compiling library code with no main(). If this is
1682 # not supplied and the code has a main(), it is called as part of the
1683 # module init process. Note that main() is #if'd out of shell.c
1684 # (renamed) when building in wasm mode.
1685 #
1686 # --pre-js/--post-js=FILE relative or absolute paths to JS files to
1687 # prepend/append to the emcc-generated bootstrapping JS. It's
1688 # easier/faster to develop with separate JS files (reduces rebuilding
1689 # requirements) but certain configurations, namely -sMODULARIZE, may
1690 # require using at least a --pre-js file. They can be used
1691 # individually and need not be paired.
1692 #
1693 # -O0..-O3 and -Oz: optimization levels affect not only C-style
1694 # optimization but whether or not the resulting generated JS code
1695 # gets minified. -O0 compiles _much_ more quickly than -O3 or -Oz,
1696 # and doesn't minimize any JS code, so is recommended for
1697 # development. -O3 or -Oz are recommended for deployment, but
1698 # primarily because -Oz will shrink the wasm file notably. JS-side
1699 # minification makes little difference in terms of overall
1700 # distributable size.
1701 #
1702 # --minify 0: supposedly disables minification of the generated JS
1703 # code, regardless of optimization level, but that's not quite true:
1704 # search the main makefile for wasm-strip for details. Minification
1705 # of the JS has minimal overall effect in the larger scheme of things
1706 # and results in JS files which can neither be edited nor viewed as
1707 # text files in Fossil (which flags them as binary because of their
1708 # extreme line lengths). Interestingly, whether or not the comments
1709 # in the generated JS file get stripped is unaffected by this setting
1710 # and depends entirely on the optimization level. Higher optimization
1711 # levels reduce the size of the JS considerably even without
1712 # minification.
1713 #
1714 ########################################################################