From 86d115d5e5a66e01766d0b3878d43730314b9f14 Mon Sep 17 00:00:00 2001
From: Jeff Quast <contact@jeffquast.com>
Date: Mon, 28 Sep 2026 15:44:11 +0000
Subject: [PATCH] Add an address-sanitizer build target

The release build reports an out-of-bounds access as a raw wasm offset,
which leaves the faulty access unidentified. `make asan` builds the engine
into build-asan/ with -fsanitize=address and installs it, so an overrun of
a stack or heap object is reported with the variable and the shadow bytes
around it. Its allocator returns uninitialized memory, which surfaces
members that a zero-filled heap masks.
---
 makefile                              | 10 ++++++++++
 packages/micropolis-engine/.gitignore |  1 +
 packages/micropolis-engine/makefile   | 28 +++++++++++++++++++++++++++
 3 files changed, 39 insertions(+)

diff --git a/makefile b/makefile
index 2b3fe1c0..67d45726 100644
--- a/makefile
+++ b/makefile
@@ -100,6 +100,16 @@ build_MicropolisEngine:
 	echo "Building MicropolisEngine with Emscripten..."
 	cd packages/micropolis-engine ; make all
 
+########################################################################
+# build and install MicropolisEngine with AddressSanitizer
+
+asan:
+	echo "Building and installing MicropolisEngine with AddressSanitizer..."
+	cd packages/micropolis-engine ; make install-asan
+
+clean-asan:
+	cd packages/micropolis-engine ; make clean-asan
+
 ########################################################################
 # build micropolis
 
diff --git a/packages/micropolis-engine/.gitignore b/packages/micropolis-engine/.gitignore
index 378eac25..d2ad9acf 100644
--- a/packages/micropolis-engine/.gitignore
+++ b/packages/micropolis-engine/.gitignore
@@ -1 +1,2 @@
 build
+build-asan
diff --git a/packages/micropolis-engine/makefile b/packages/micropolis-engine/makefile
index 7655a936..553e9cda 100644
--- a/packages/micropolis-engine/makefile
+++ b/packages/micropolis-engine/makefile
@@ -175,6 +175,7 @@ clean:
 	rm -rf \
 	    $(OBJECTS) \
 		$(OUTPUTFILES) \
+		$(ASAN_BUILD) \
 		build
 
 
@@ -215,3 +216,30 @@ zone.cpp: micropolis.h
 
 
 ########################################################################
+# Address-sanitizer build for hunting memory bugs
+
+
+ASAN_BUILD = build-asan
+ASAN_FLAGS = -fsanitize=address -g
+ASAN_OBJECTS = $(SOURCES:%.cpp=$(ASAN_BUILD)/%.o)
+ASAN_LIBRARY = $(ASAN_BUILD)/micropolisengine
+
+
+asan: $(ASAN_LIBRARY)
+
+$(ASAN_LIBRARY): $(ASAN_OBJECTS)
+	mkdir -p $(ASAN_BUILD)
+	$(EMCC) $(EMLDFLAGS) $(ASAN_FLAGS) -o $(ASAN_LIBRARY).html $^
+
+$(ASAN_BUILD)/%.o: %.cpp $(HEADERS)
+	mkdir -p $(dir $@)
+	$(EMCC) $(EMCXXFLAGS) $(ASAN_FLAGS) -c $< -o $@
+
+install-asan: asan
+	cp $(ASAN_BUILD)/micropolisengine.wasm ../../apps/micropolis/src/lib
+	cp $(ASAN_BUILD)/micropolisengine.data ../../apps/micropolis/src/lib
+	{ printf '%s\n' '// @ts-nocheck'; cat $(ASAN_BUILD)/micropolisengine.js; } > ../../apps/micropolis/src/lib/micropolisengine.js
+
+clean-asan:
+	rm -rf $(ASAN_BUILD)
+