From f10ddaffb4ef9558b044e8a6c72c3e643e311e53 Mon Sep 17 00:00:00 2001 From: Alan George Date: Thu, 12 Nov 2026 15:34:46 -0700 Subject: [PATCH 1/3] Resolve mac build issue outside of CI --- AGENTS.md | 8 ++++++-- build.sh | 24 +++++++++++++++++++++--- docs/building.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 74 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e4bbd024..d9daf703 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -150,8 +150,12 @@ source builds require clang/clang++ 21+ and a matching libclang runtime; `build.sh` sources `scripts/setup-linux-toolchain.sh` to discover versioned installations and validate the toolchain. Source that script before direct Linux CMake usage. The build script rejects stale build directories configured -with another compiler. macOS builds use Xcode Apple Clang selected through -`xcrun`. On macOS: +with another compiler. macOS builds use Apple Clang from standalone Xcode +Command Line Tools or full Xcode selected through `xcrun`. `build.sh` exports +`CC`, `CXX`, and `SDKROOT` for both CMake and Cargo; an explicit `SDKROOT` must +be an absolute SDK directory containing `usr/include/TargetConditionals.h`. +When unset or empty, `SDKROOT` is discovered with +`xcrun --sdk macosx --show-sdk-path`. On macOS: `brew install cmake ninja protobuf abseil`. On Linux: see `docs/building.md` and the CI workflow for apt packages. spdlog is vendored automatically via FetchContent (or vcpkg on Windows) to avoid system conflicts. diff --git a/build.sh b/build.sh index 254be046..e93798c0 100755 --- a/build.sh +++ b/build.sh @@ -33,13 +33,31 @@ configure_macos_toolchain() { exit 1 fi - CC="$(xcrun --find clang)" - CXX="$(xcrun --find clang++)" - export CC CXX + if ! CC="$(xcrun --sdk macosx --find clang)" \ + || ! CXX="$(xcrun --sdk macosx --find clang++)"; then + echo "ERROR: Cannot locate Apple Clang. Check your developer tools with xcode-select -p." >&2 + exit 1 + fi + + # Cargo's C/C++ build scripts invoke these absolute compiler paths directly. + # Standalone Command Line Tools need an explicit SDK root for system headers. + if [[ -z "${SDKROOT:-}" ]]; then + if ! SDKROOT="$(xcrun --sdk macosx --show-sdk-path)"; then + echo "ERROR: Cannot locate the macOS SDK. Install or select Xcode Command Line Tools or Xcode." >&2 + exit 1 + fi + fi + if [[ "${SDKROOT}" != /* || ! -f "${SDKROOT}/usr/include/TargetConditionals.h" ]]; then + echo "ERROR: SDKROOT must be an absolute SDK directory containing usr/include/TargetConditionals.h: ${SDKROOT}" >&2 + echo "Unset SDKROOT to use the macOS SDK selected by xcrun." >&2 + exit 1 + fi + export CC CXX SDKROOT echo "==> macOS compiler: $("${CXX}" --version | awk 'NR == 1 { print; exit }')" echo "==> CC=${CC}" echo "==> CXX=${CXX}" + echo "==> SDKROOT=${SDKROOT}" } configure_build_toolchain() { diff --git a/docs/building.md b/docs/building.md index 468a87f4..4ba68109 100644 --- a/docs/building.md +++ b/docs/building.md @@ -18,7 +18,7 @@ CMake/vcpkg flows. | Platform | Compiler | Package manager | |----------|----------|-----------------| | Linux | Clang 21+ with libclang (See [here](#clang-compiler-usage-on-linux) for rationale) | `apt` | -| macOS | Xcode 12+ Apple Clang (macOS 12.3+ for ScreenCaptureKit) | Homebrew | +| macOS | Apple Clang from current Xcode Command Line Tools or full Xcode | Apple developer tools | | Windows | Visual Studio 2019+ (MSBuild or Ninja) | vcpkg (see below) | ### Dependencies @@ -58,10 +58,40 @@ each supported platform. ### macOS +Install Apple's standalone Command Line Tools, or use an existing full Xcode +installation: + +```bash +xcode-select --install +``` + +After installation, verify the selected developer directory, compiler, and SDK: + +```bash +xcode-select -p +xcrun --sdk macosx --find clang++ +xcrun --sdk macosx --show-sdk-path +``` + +Standalone tools normally select `/Library/Developer/CommandLineTools`; full +Xcode normally selects `/Applications/Xcode.app/Contents/Developer`. If the +selection points to an old or removed installation, select the installed tools: + +```bash +sudo xcode-select --switch /Library/Developer/CommandLineTools +# Or, for full Xcode: +# sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer +``` + +Install the remaining tools with Homebrew: + ```bash brew install cmake ninja protobuf abseil rust ``` +`build.sh` selects Apple Clang through `xcrun` and exports `CC`, `CXX`, and +`SDKROOT` for CMake and Cargo. You do not need to export `SDKROOT` manually. + ### Linux ```bash @@ -403,7 +433,22 @@ requirement imposed by libwebrtc's hermetic libc++. `build.sh` accepts both versioned libraries such as `libclang-21.so.1` and an unversioned `libclang.so`. For a custom installation, set `LLVM_ROOT` or point `LIBCLANG_PATH` at its library directory. On macOS, install the Xcode Command -Line Tools; `build.sh` selects Xcode Apple Clang with `xcrun`. +Line Tools; `build.sh` selects Apple Clang and the macOS SDK with `xcrun`. + +### macOS build cannot find `TargetConditionals.h` + +This can occur when Cargo invokes Apple Clang directly without a macOS SDK +root. Use the current `build.sh`, which exports `SDKROOT` automatically. If +you set `SDKROOT` or `DEVELOPER_DIR` yourself, check that they point to an +installed macOS SDK and developer tools, respectively. See the +[macOS setup instructions](#macos) to verify or repair the selection. + +For direct Cargo or CMake invocations outside `build.sh`, initialize the SDK +environment in that shell first: + +```bash +export SDKROOT="$(xcrun --sdk macosx --show-sdk-path)" +``` ### Rust code recompiles after C++ edits From 6e6e4ac42a13ba8e4fd0d9ca18b18eebf2db8dd8 Mon Sep 17 00:00:00 2001 From: Alan George Date: Fri, 13 Nov 2026 14:36:38 -0700 Subject: [PATCH 2/3] Update building.md --- docs/building.md | 72 ++++++++++++++++++++++++------------------------ 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/building.md b/docs/building.md index 4ba68109..3dc3cdc3 100644 --- a/docs/building.md +++ b/docs/building.md @@ -56,42 +56,6 @@ sources, or support optional repository targets. This section outlines the recommended dependency/environmental setup for each supported platform. -### macOS - -Install Apple's standalone Command Line Tools, or use an existing full Xcode -installation: - -```bash -xcode-select --install -``` - -After installation, verify the selected developer directory, compiler, and SDK: - -```bash -xcode-select -p -xcrun --sdk macosx --find clang++ -xcrun --sdk macosx --show-sdk-path -``` - -Standalone tools normally select `/Library/Developer/CommandLineTools`; full -Xcode normally selects `/Applications/Xcode.app/Contents/Developer`. If the -selection points to an old or removed installation, select the installed tools: - -```bash -sudo xcode-select --switch /Library/Developer/CommandLineTools -# Or, for full Xcode: -# sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer -``` - -Install the remaining tools with Homebrew: - -```bash -brew install cmake ninja protobuf abseil rust -``` - -`build.sh` selects Apple Clang through `xcrun` and exports `CC`, `CXX`, and -`SDKROOT` for CMake and Cargo. You do not need to export `SDKROOT` manually. - ### Linux ```bash @@ -134,6 +98,42 @@ sudo apt install -y \ libwayland-dev libdecor-0-dev ``` +### macOS + +Install Apple's standalone Command Line Tools, or use an existing full Xcode +installation: + +```bash +xcode-select --install +``` + +After installation, verify the selected developer directory, compiler, and SDK: + +```bash +xcode-select -p +xcrun --sdk macosx --find clang++ +xcrun --sdk macosx --show-sdk-path +``` + +Standalone tools normally select `/Library/Developer/CommandLineTools`; full +Xcode normally selects `/Applications/Xcode.app/Contents/Developer`. If the +selection points to an old or removed installation, select the installed tools: + +```bash +sudo xcode-select --switch /Library/Developer/CommandLineTools +# Or, for full Xcode: +# sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer +``` + +Install the remaining tools with Homebrew: + +```bash +brew install cmake ninja protobuf abseil rust +``` + +`build.sh` selects Apple Clang through `xcrun` and exports `CC`, `CXX`, and +`SDKROOT` for CMake and Cargo. You do not need to export `SDKROOT` manually. + ### Windows ```powershell From 2f04d86f235ad2451a645b0e998bfb02d565d208 Mon Sep 17 00:00:00 2001 From: Alan George Date: Fri, 13 Nov 2026 14:45:29 -0700 Subject: [PATCH 3/3] Fix docs link --- docs/building.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/building.md b/docs/building.md index 3dc3cdc3..f3e93818 100644 --- a/docs/building.md +++ b/docs/building.md @@ -98,6 +98,7 @@ sudo apt install -y \ libwayland-dev libdecor-0-dev ``` + ### macOS Install Apple's standalone Command Line Tools, or use an existing full Xcode