ext/wasm/fiddle.make

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