xref: /sqlite-3.40.0/ext/wasm/fiddle.make (revision 7e089d0c) 
1#!/do/not/make
2#^^^ help emacs select edit mode
3#
4# Intended to include'd by ./GNUmakefile.
5#######################################################################
6MAKEFILE.fiddle := $(lastword $(MAKEFILE_LIST))
7
8########################################################################
9# shell.c and its build flags...
10make-np-0 := make -C  $(dir.top) -n -p
11make-np-1 := sed -e 's/(TOP)/(dir.top)/g'
12$(eval $(shell $(make-np-0) | grep -e '^SHELL_OPT ' | $(make-np-1)))
13$(eval $(shell $(make-np-0) | grep -e '^SHELL_SRC ' | $(make-np-1)))
14# ^^^ can't do that in 1 invocation b/c newlines get stripped
15ifeq (,$(SHELL_OPT))
16$(error Could not parse SHELL_OPT from $(dir.top)/Makefile.)
17endif
18ifeq (,$(SHELL_SRC))
19$(error Could not parse SHELL_SRC from $(dir.top)/Makefile.)
20endif
21$(dir.top)/shell.c: $(SHELL_SRC) $(dir.top)/tool/mkshellc.tcl
22	$(MAKE) -C $(dir.top) shell.c
23# /shell.c
24########################################################################
25
26EXPORTED_FUNCTIONS.fiddle := $(dir.tmp)/EXPORTED_FUNCTIONS.fiddle
27fiddle.emcc-flags = \
28  $(emcc.cflags) $(emcc_opt_full) \
29  --minify 0 \
30  -sALLOW_TABLE_GROWTH \
31  -sABORTING_MALLOC \
32  -sSTRICT_JS \
33  -sENVIRONMENT=web,worker \
34  -sMODULARIZE \
35  -sDYNAMIC_EXECUTION=0 \
36  -sWASM_BIGINT=$(emcc_enable_bigint) \
37  -sEXPORT_NAME=$(sqlite3.js.init-func) \
38  -Wno-limited-postlink-optimizations \
39  $(sqlite3.js.flags.--post-js) \
40  $(emcc.exportedRuntimeMethods) \
41  -sEXPORTED_FUNCTIONS=@$(abspath $(EXPORTED_FUNCTIONS.fiddle)) \
42  $(SQLITE_OPT) $(SHELL_OPT) \
43  -DSQLITE_SHELL_FIDDLE
44# -D_POSIX_C_SOURCE is needed for strdup() with emcc
45
46fiddle.EXPORTED_FUNCTIONS.in := \
47    EXPORTED_FUNCTIONS.fiddle.in \
48    $(EXPORTED_FUNCTIONS.api)
49
50$(EXPORTED_FUNCTIONS.fiddle): $(fiddle.EXPORTED_FUNCTIONS.in) $(MAKEFILE.fiddle)
51	sort -u $(fiddle.EXPORTED_FUNCTIONS.in) > $@
52
53fiddle-module.js := $(dir.fiddle)/fiddle-module.js
54fiddle-module.wasm := $(subst .js,.wasm,$(fiddle-module.js))
55fiddle.cses := $(dir.top)/shell.c $(sqlite3-wasm.c)
56
57fiddle.SOAP.js := $(dir.fiddle)/$(notdir $(SOAP.js))
58$(fiddle.SOAP.js): $(SOAP.js)
59	cp $< $@
60
61$(eval $(call call-make-pre-js,fiddle-module))
62$(fiddle-module.js): $(MAKEFILE) $(MAKEFILE.fiddle) \
63    $(EXPORTED_FUNCTIONS.fiddle) \
64    $(fiddle.cses) $(pre-post-fiddle-module.deps) $(fiddle.SOAP.js)
65	$(emcc.bin) -o $@ $(fiddle.emcc-flags) \
66    $(pre-post-common.flags) $(pre-post-fiddle-module.flags) \
67    $(fiddle.cses)
68	$(maybe-wasm-strip) $(fiddle-module.wasm)
69	gzip < $@ > $@.gz
70	gzip < $(fiddle-module.wasm) > $(fiddle-module.wasm).gz
71
72$(dir.fiddle)/fiddle.js.gz: $(dir.fiddle)/fiddle.js
73	gzip < $< > $@
74
75clean: clean-fiddle
76clean-fiddle:
77	rm -f $(fiddle-module.js) $(fiddle-module.js).gz \
78        $(fiddle-module.wasm) $(fiddle-module.wasm).gz \
79        $(dir.fiddle)/$(SOAP.js) \
80        $(dir.fiddle)/fiddle-module.worker.js \
81        EXPORTED_FUNCTIONS.fiddle
82.PHONY: fiddle
83fiddle: $(fiddle-module.js) $(dir.fiddle)/fiddle.js.gz
84all: fiddle
85
86########################################################################
87# Explanation of the emcc build flags follows. Full docs for these can
88# be found at:
89#
90#  https://github.com/emscripten-core/emscripten/blob/main/src/settings.js
91#
92# -sENVIRONMENT=web: elides bootstrap code related to non-web JS
93#  environments like node.js. Removing this makes the output a tiny
94#  tick larger but hypothetically makes it more portable to
95#  non-browser JS environments.
96#
97# -sMODULARIZE: changes how the generated code is structured to avoid
98#  declaring a global Module object and instead installing a function
99#  which loads and initializes the module. The function is named...
100#
101# -sEXPORT_NAME=jsFunctionName (see -sMODULARIZE)
102#
103# -sEXPORTED_RUNTIME_METHODS=@/absolute/path/to/file: a file
104#  containing a list of emscripten-supplied APIs, one per line, which
105#  must be exported into the generated JS. Must be an absolute path!
106#
107# -sEXPORTED_FUNCTIONS=@/absolute/path/to/file: a file containing a
108#  list of C functions, one per line, which must be exported via wasm
109#  so they're visible to JS. C symbols names in that file must all
110#  start with an underscore for reasons known only to the emcc
111#  developers. e.g., _sqlite3_open_v2 and _sqlite3_finalize. Must be
112#  an absolute path!
113#
114# -sSTRICT_JS ensures that the emitted JS code includes the 'use
115#  strict' option. Note that -sSTRICT is more broadly-scoped and
116#  results in build errors.
117#
118# -sALLOW_TABLE_GROWTH is required for (at a minimum) the UDF-binding
119#  feature. Without it, JS functions cannot be made to proxy C-side
120#  callbacks.
121#
122# -sABORTING_MALLOC causes the JS-bound _malloc() to abort rather than
123#  return 0 on OOM. If set to 0 then all code which uses _malloc()
124#  must, just like in C, check the result before using it, else
125#  they're likely to corrupt the JS/WASM heap by writing to its
126#  address of 0. It is, as of this writing, enabled in Emscripten by
127#  default but we enable it explicitly in case that default changes.
128#
129# -sDYNAMIC_EXECUTION=0 disables eval() and the Function constructor.
130#  If the build runs without these, it's preferable to use this flag
131#  because certain execution environments disallow those constructs.
132#  This flag is not strictly necessary, however.
133#
134# -sWASM_BIGINT is UNTESTED but "should" allow the int64-using C APIs
135#  to work with JS/wasm, insofar as the JS environment supports the
136#  BigInt type. That support requires an extremely recent browser:
137#  Safari didn't get that support until late 2020.
138#
139# --no-entry: for compiling library code with no main(). If this is
140#  not supplied and the code has a main(), it is called as part of the
141#  module init process. Note that main() is #if'd out of shell.c
142#  (renamed) when building in wasm mode.
143#
144# --pre-js/--post-js=FILE relative or absolute paths to JS files to
145#  prepend/append to the emcc-generated bootstrapping JS. It's
146#  easier/faster to develop with separate JS files (reduces rebuilding
147#  requirements) but certain configurations, namely -sMODULARIZE, may
148#  require using at least a --pre-js file. They can be used
149#  individually and need not be paired.
150#
151# -O0..-O3 and -Oz: optimization levels affect not only C-style
152#  optimization but whether or not the resulting generated JS code
153#  gets minified. -O0 compiles _much_ more quickly than -O3 or -Oz,
154#  and doesn't minimize any JS code, so is recommended for
155#  development. -O3 or -Oz are recommended for deployment, but
156#  primarily because -Oz will shrink the wasm file notably. JS-side
157#  minification makes little difference in terms of overall
158#  distributable size.
159#
160# --minify 0: disables minification of the generated JS code,
161#  regardless of optimization level. Minification of the JS has
162#  minimal overall effect in the larger scheme of things and results
163#  in JS files which can neither be edited nor viewed as text files in
164#  Fossil (which flags them as binary because of their extreme line
165#  lengths). Interestingly, whether or not the comments in the
166#  generated JS file get stripped is unaffected by this setting and
167#  depends entirely on the optimization level. Higher optimization
168#  levels reduce the size of the JS considerably even without
169#  minification.
170#
171########################################################################
172