Update and document Emscripten link-time options (#174)

mpwarres · web-flow · commit 7465dee8b295 · 2025-03-03T19:33:07.000-05:00
Set INITIAL_HEAP=64KB and ALLOW_MEMORY_GROWTH=1 to reduce starting memory usage of plugins, but allow the heap to grow. Use default Emscripten STACK_SIZE of 64KB, see this emscripten-discuss thread for background behind that value.

Also add comments documenting the purpose of each link-time option.

Signed-off-by: Michael Warres &lt;mpw@google.com&gt;
diff --git a/Makefile b/Makefile
@@ -29,17 +29,23 @@ PKG_CONFIG_PATH = ${EMSDK}/upstream/emscripten/cache/sysroot/lib/pkgconfig
 WASM_LIBS = $(shell $(PKG_CONFIG) $(WASM_DEPS) $(PROTO_DEPS) \
 	  --with-path=$(PKG_CONFIG_PATH) --libs | sed -e 's/-pthread //g')
 
+# See proxy_wasm_cc_binary build rule definition in bazel/defs.bzl for
+# explanation of emscripten link options.
+EMSCRIPTEN_LINK_OPTS := --no-entry \
+	--js-library ${PROXY_WASM_CPP_SDK}/proxy_wasm_intrinsics.js \
+	-sSTANDALONE_WASM -sEXPORTED_FUNCTIONS=_malloc \
+	-sALLOW_MEMORY_GROWTH=1 -sINITIAL_HEAP=64KB
+
+
 debug-deps:
 	# WASM_DEPS : ${WASM_DEPS}
 	# WASM_LIBS : ${WASM_LIBS}
 	# PROTO_DEPS: ${PROTO_DEPS}
 	# PROTO_OPTS: ${PROTO_OPTS}
 
-# TODO(mpwarres): Add Emscripten stack/heap size params in PR#174.
 %.wasm %.wat: %.cc
-	em++ --no-entry -sSTANDALONE_WASM -sEXPORTED_FUNCTIONS=_malloc \
-		--std=c++17 -O3 -flto \
-		--js-library ${PROXY_WASM_CPP_SDK}/proxy_wasm_intrinsics.js \
+	em++ --std=c++17 -O3 -flto \
+		${EMSCRIPTEN_LINK_OPTS} \
 		-I${PROXY_WASM_CPP_SDK} \
 		${CPP_CONTEXT_LIB} \
 		${PROTO_OPTS} \
diff --git a/bazel/defs.bzl b/bazel/defs.bzl
@@ -90,10 +90,20 @@ def proxy_wasm_cc_binary(
             "@proxy_wasm_cpp_sdk//:proxy_wasm_intrinsics_js",
         ],
         linkopts = linkopts + [
+            # Setting to indicate module is a "reactor library" without a main() entry point:
+            # https://emscripten.org/docs/tools_reference/settings_reference.html#standalone-wasm
             "--no-entry",
+            # File listing additional functions that Emscripten should expect to be implemented by the host:
+            # https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html#implement-c-in-javascript
             "--js-library=$(location @proxy_wasm_cpp_sdk//:proxy_wasm_intrinsics_js)",
+            # Emit Wasm module that can run without JavaScript
             "-sSTANDALONE_WASM",
+            # Give host code access to Emscripten's _malloc() function
             "-sEXPORTED_FUNCTIONS=_malloc",
+            # Allow allocating memory past initial heap size
+            "-sALLOW_MEMORY_GROWTH=1",
+            # Initial amount of heap memory. 64KB matches Rust SDK starting heap size.
+            "-sINITIAL_HEAP=64KB",
         ],
         tags = tags + [
             "manual",
