package-macos: bundle Homebrew dylibs into Contents/Frameworks (#43)

The macOS package script copied the BattleShip / torch binaries verbatim
into Contents/MacOS without bundling their Homebrew runtime
dependencies, so the resulting .app embedded absolute load commands like
/opt/homebrew/opt/sdl2/lib/libSDL2-2.0.0.dylib.  On any Mac without
Homebrew at the developer's prefix and exact package versions, dyld
bails before main() with `Library not loaded: /opt/homebrew/*/libSDL2-
2.0.0.dylib` — verbatim crash from issue #43 (Apple M4, macOS Tahoe
26.3).

Linux and Windows packaging already handle this (linuxdeploy walks
NEEDED for AppImage; vcpkg drops SDL2.dll next to the .exe).  macOS was
the only platform shipping host-locked binaries.

Fix uses the standard `dylibbundler` Homebrew package: walks the binaries'
transitive Homebrew deps, stages each into Contents/Frameworks/, rewrites
each dylib's id to @executable_path/../Frameworks/lib*.dylib, retargets
the binaries' load commands via install_name_tool, and replaces the
inherited Homebrew rpaths with @executable_path/../Frameworks/.  Using
the absolute @executable_path form (rather than @rpath + LC_RPATH) avoids
dylibbundler's existing-rpath rewrite stomping the LC_RPATH with literal
`@rpath/`, which produces a recursive load command dyld can't resolve.

The post-bundle adhoc `codesign --deep --force --sign -` already in the
script picks up the new Frameworks/ tree and re-signs both the dylibs
and the now-modified executables (install_name_tool invalidates the
linker signature).  Added a sanity check after dylibbundler that scans
the binaries for any remaining /opt/homebrew or /usr/local/Cellar load
commands and fails the build loudly if one slips through, rather than
shipping a host-locked .app to users.

Verified locally on a copy of dist/BattleShip.app: every Homebrew
reference replaced with @executable_path/../Frameworks/, dylib ids
match, codesign --verify --deep --strict passes.

CI: added `dylibbundler` to the brew install line in
.github/workflows/release.yml so macos-14 runners have the tool.

Closes #43.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: JRickey

.github/workflows/release.yml

@@ -40,7 +40,7 @@ jobs:
         run: |
           brew install cmake ninja \
             sdl2 glew libzip nlohmann-json tinyxml2 spdlog \
-            zip create-dmg
+            zip create-dmg dylibbundler
       - name: Package macOS .app + .dmg
         run: bash scripts/package-macos.sh
       - uses: actions/upload-artifact@v4

scripts/package-macos.sh

@@ -135,6 +135,57 @@ EOF
 # Make the binaries executable (cp preserves mode, but be defensive).
 chmod +x "$APP/Contents/MacOS/$APP_NAME" "$APP/Contents/MacOS/torch"
 
+# ── 4a. Bundle Homebrew dylib dependencies (fixes #43) ──
+# CMake links BattleShip / torch against Homebrew dylibs (SDL2, GLEW,
+# libzip, tinyxml2, spdlog, fmt, …) using their absolute install paths
+# (`/opt/homebrew/opt/<pkg>/lib/lib*.dylib`). On a developer machine the
+# .app launches fine because every load command resolves verbatim. On
+# any user's Mac without Homebrew at the same prefix and exact package
+# versions, dyld bails before main() with `Library not loaded:
+# /opt/homebrew/*/libSDL2-2.0.0.dylib`. This is the macOS analogue of
+# bundling SDL2.dll on Windows / `.so` deps via linuxdeploy on Linux —
+# the package script must walk the binaries' transitive Homebrew deps,
+# stage them into Contents/Frameworks/, rewrite each dylib's id to
+# `@rpath/lib*.dylib`, retarget the binaries' references via
+# `install_name_tool`, and add an `LC_RPATH` of `@executable_path/../Frameworks`.
+#
+# `dylibbundler` (Homebrew package) automates all of that. `-of` =
+# overwrite-files (idempotent re-runs), `-b` = bundle transitive deps,
+# `-x` = files to fix (repeatable for torch alongside BattleShip),
+# `-d` = destination directory, `-p` = install_name prefix, `-cd` =
+# create destination, `-ns` = skip dylibbundler's own adhoc codesign
+# pass since the bundle-level `codesign --deep --force` below resigns
+# everything in one shot.
+#
+# `-p @executable_path/../Frameworks/` makes the rewritten install_names
+# fully self-resolving (dyld substitutes `@executable_path` with the
+# directory of the loading executable — Contents/MacOS — so the path
+# lands at Contents/Frameworks/lib*.dylib).  Setting `-p @rpath/` would
+# require an LC_RPATH on the binary, and dylibbundler's existing-rpath
+# rewrite stomps on that path with literal `@rpath/`, producing a
+# recursive load command that dyld can't resolve.  Using the absolute
+# `@executable_path` form sidesteps that.
+step "Bundling Homebrew dylib dependencies"
+command -v dylibbundler >/dev/null \
+    || fail "dylibbundler not in PATH — install with: brew install dylibbundler"
+dylibbundler -of -b -cd -ns \
+    -x "$APP/Contents/MacOS/$APP_NAME" \
+    -x "$APP/Contents/MacOS/torch" \
+    -d "$APP/Contents/Frameworks/" \
+    -p "@executable_path/../Frameworks/"
+
+# Sanity-check: no /opt/homebrew or /usr/local references should remain in
+# the binaries' load commands. Catches the case where dylibbundler missed a
+# transitive dep (rare, but worth failing loudly here rather than letting
+# the .app ship and hit the user with a runtime "Library not loaded:").
+for bin in "$APP/Contents/MacOS/$APP_NAME" "$APP/Contents/MacOS/torch"; do
+    if otool -L "$bin" | grep -qE '(/opt/homebrew|/usr/local/Cellar)'; then
+        echo "  remaining unbundled refs in $bin:" >&2
+        otool -L "$bin" | grep -E '(/opt/homebrew|/usr/local/Cellar)' >&2
+        fail "dylibbundler left non-portable load commands in $(basename "$bin")"
+    fi
+done
+
 # ── 4b. Adhoc-sign the bundle as a unit ──
 # Modern Gatekeeper (Sequoia / 15.x+) flags downloaded adhoc-signed
 # bundles as "damaged" if the signature isn't deep enough to cover