From 2024f8059d3954c49053414149e8c91f9913d4c7 Mon Sep 17 00:00:00 2001
From: Andy Kopra <ack@acm.org>
Date: Sat, 18 Jul 2026 20:03:40 +0200
Subject: [PATCH] Default to the optimized -O3 build; DEBUG=1 for a debug build

Bare 'make -C com' now builds -O3 (optimize.env default flip); the install guides drop OPTIMIZE=1 and document DEBUG=1 for an AddressSanitizer build.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 doc/install/linux_source_install.md | 12 +++++++-----
 doc/install/macos_source_install.md |  7 +++++--
 mac/env/optimize.env                | 26 +++++++++++++++-----------
 3 files changed, 27 insertions(+), 18 deletions(-)

diff --git a/doc/install/linux_source_install.md b/doc/install/linux_source_install.md
index e0798a5..7da2ec8 100644
--- a/doc/install/linux_source_install.md
+++ b/doc/install/linux_source_install.md
@@ -88,14 +88,16 @@ If `python3-config` is missing, install your distribution's `python3-dev`
 
 Build the shared library, the SKS components, and the three commands with a
 single command: `make -C com` builds its prerequisites in `mac/` and `sks/`
-first, then the commands. `OPTIMIZE=1` selects an optimized `-O3` build (what
-you want to install and run); without it you get a slower `-O0` debug build
-with AddressSanitizer, intended for development:
+first, then the commands. The build is optimized (`-O3`) by default — the build
+you want to install and run:
 
 ```bash
-make -C com -j OPTIMIZE=1        # lib/libklammertext.so + sks/*.so + bin/{ktext,kdesc,kdiag}
+make -C com -j        # lib/libklammertext.so + sks/*.so + bin/{ktext,kdesc,kdiag}
 ```
 
+(For a slower `-O0` debug build with AddressSanitizer, intended for development,
+prefix `DEBUG=1`: `DEBUG=1 make -C com -j`.)
+
 Verify the build:
 
 ```bash
@@ -243,7 +245,7 @@ To update an existing source installation to the latest version:
 ```bash
 cd $KLAMMERTEXT_HOME
 git pull
-make -C com -j OPTIMIZE=1   # rebuild library, SKS components, and commands
+make -C com -j             # rebuild library, SKS components, and commands (optimized)
 ```
 
 The TeX Live tree only needs rebuilding if the SKS's package requirements
diff --git a/doc/install/macos_source_install.md b/doc/install/macos_source_install.md
index c0da126..a5bb9ad 100644
--- a/doc/install/macos_source_install.md
+++ b/doc/install/macos_source_install.md
@@ -81,10 +81,13 @@ then the commands:
 
 ```sh
 cd "$KLAMMERTEXT_HOME"
-make -C com -j OPTIMIZE=1     # libklammertext.so + sks/*.so + bin/{ktext,kdesc,kdiag}
+make -C com -j               # optimized (-O3) by default; libklammertext.so + sks/*.so + bin/{ktext,kdesc,kdiag}
 ktext -s '@eval 1 + 1 @' -d  # smoke test — prints 2
 ```
 
+(For a debug build with AddressSanitizer, intended for development, prefix
+`DEBUG=1`: `DEBUG=1 make -C com -j`.)
+
 For a document smoke test, create a small file and render it to HTML:
 
 ```sh
@@ -149,7 +152,7 @@ To update an existing source installation to the latest version:
 ```sh
 cd "$KLAMMERTEXT_HOME"
 git pull
-make -C com -j OPTIMIZE=1     # rebuild library, SKS components, and commands
+make -C com -j               # rebuild library, SKS components, and commands (optimized)
 ```
 
 Rebuild the TeX Live tree only if the SKS's package requirements changed (rare);
diff --git a/mac/env/optimize.env b/mac/env/optimize.env
index e5ddf1e..0ed7ddd 100644
--- a/mac/env/optimize.env
+++ b/mac/env/optimize.env
@@ -1,16 +1,20 @@
 
-ifdef OPTIMIZE
-# Performance build: make OPTIMIZE=1
-# `override` so a command-line `make OPTIMIZE=1` is remapped to -O3 too;
-# without it, a command-line assignment wins over this `:=` and the literal
-# `1` leaks into CXXFLAGS (g++ then treats `1` as an input file).
-override OPTIMIZE := -O3
-SANITIZE :=
+# Build mode. The DEFAULT is an optimized -O3 build (what installs and releases
+# use). Opt into other modes explicitly:
+#     DEBUG=1     -> debug build: -O0 -g + AddressSanitizer (development)
+#     NOPYTHON=1  -> -O0 -g -DNOPYTHON, no ASan (build without the interpreter)
+# `override` is used throughout so that a stray command-line or environment
+# `OPTIMIZE=...` cannot leak into CXXFLAGS: OPTIMIZE is an internal flag string
+# here, no longer a trigger. (A legacy `make OPTIMIZE=1` still yields -O3, since
+# it falls through to the optimized default below.)
+ifdef DEBUG
+override OPTIMIZE := -O0 -g
+SANITIZE := -fsanitize=address -fno-omit-frame-pointer
 else ifdef NOPYTHON
-OPTIMIZE := -O0 -g -DNOPYTHON
+override OPTIMIZE := -O0 -g -DNOPYTHON
 SANITIZE :=
 else
-# Debug build (default): includes AddressSanitizer
-OPTIMIZE := -O0 -g
-SANITIZE := -fsanitize=address -fno-omit-frame-pointer
+# Performance build (default).
+override OPTIMIZE := -O3
+SANITIZE :=
 endif