Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
24 changes: 21 additions & 3 deletions build.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand Down
62 changes: 54 additions & 8 deletions docs/building.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -56,12 +56,6 @@ sources, or support optional repository targets.
This section outlines the recommended dependency/environmental setup for
each supported platform.

### macOS

```bash
brew install cmake ninja protobuf abseil rust
```

### Linux

```bash
Expand Down Expand Up @@ -104,6 +98,43 @@ sudo apt install -y \
libwayland-dev libdecor-0-dev
```

<a id="macos"></a>
### 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
Expand Down Expand Up @@ -403,7 +434,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

Expand Down
Loading