From a2966e42974cccbe99bb6615c7fee21a993464f3 Mon Sep 17 00:00:00 2001
From: Luar Roji <luar@roji.net>
Date: Tue, 24 Mar 2026 11:16:21 -0300
Subject: [PATCH] Add macOS build instructions for modern Clang

Document the fix for 'cassert file not found' error on macOS 26+
with Apple Clang 17, where C++ standard library headers are no longer
in the default toolchain include path.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 README.macOS.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 README.macOS.md

diff --git a/README.macOS.md b/README.macOS.md
new file mode 100644
index 0000000..0e549f4
--- /dev/null
+++ b/README.macOS.md
@@ -0,0 +1,40 @@
+# Building reSID on macOS
+
+## Problem
+
+On modern macOS (26+) with Apple's Command Line Tools, building reSID fails with:
+
+```
+fatal error: 'cassert' file not found
+```
+
+This happens because Apple's Clang no longer places the C++ standard library headers in the default toolchain include path (`/Library/Developer/CommandLineTools/usr/include/c++/v1/`). The headers exist inside the SDK, but are not picked up automatically.
+
+## Prerequisites
+
+- macOS (tested on macOS 26.3.1)
+- Xcode Command Line Tools:
+  ```sh
+  xcode-select --install
+  ```
+
+## Build Steps
+
+1. **Configure with the SDK's C++ include path:**
+
+   ```sh
+   SDK_PATH=$(xcrun --show-sdk-path)
+   ./configure CXXFLAGS="-I${SDK_PATH}/usr/include/c++/v1 -g -Wall -O3 -fno-exceptions"
+   ```
+
+2. **Build:**
+
+   ```sh
+   make
+   ```
+
+This produces `libresid.a` in the current directory.
+
+## Why This Works
+
+`xcrun --show-sdk-path` returns the active macOS SDK path (e.g. `/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk`). Adding `-I<sdk>/usr/include/c++/v1` explicitly tells Clang where to find C++ standard library headers like `<cassert>`, `<cstdlib>`, etc.