Skip to content

fix(cmake): ignore /usr/local prefix on Darwin so host headers cannot shadow buildroot - #1290

Merged
crazywhalecc merged 1 commit into
crazywhalecc:v3from
theluckystrike:fix/1289-ignore-usr-local-prefix
Nov 14, 2026
Merged

crazywhalecc merged 1 commit into
crazywhalecc:v3from
theluckystrike:fix/1289-ignore-usr-local-prefix

Conversation

@theluckystrike

Copy link
Copy Markdown
Contributor

What

On Intel macOS the static build compiled against Homebrew headers from /usr/local instead of the
headers spc installed in buildroot, and then failed at link time. Reported in #1289.

Why

/usr/local/include is on the compiler default search path, and /usr/local is also a prefix cmake
searches ahead of CMAKE_FIND_ROOT_PATH. So find_path, find_library and find_package returned
host paths even though the buildroot include dir was passed through
CMAKE_C_STANDARD_INCLUDE_DIRECTORIES. A target include dir coming from a host prefix is placed
ahead of the buildroot one on the compile line, which is why the host header won.

Change

One guard in the generated toolchain file, Darwin only.

if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.23)
  set(CMAKE_IGNORE_PREFIX_PATH "/usr/local")
endif()

CMAKE_IGNORE_PREFIX_PATH removes the prefix from cmake searches, so the lookups stay inside
buildroot. The version guard keeps cmake below 3.23 unchanged, and Linux and Windows behaviour is
untouched. Apple Silicon Homebrew lives in /opt/homebrew, so it keeps working. Only /usr/local
on Darwin is ignored.

Verification

A minimal cmake reproduction, no PHP build needed. A fake host prefix stands in for /usr/local, and
both prefixes ship an openssl/x.h that reports its own origin.

-- X_INC=/tmp/spc1289-xvkQeW/host/include
toolchain=without -> header used: host-prefix
-- X_INC=X_INC-NOTFOUND
toolchain=with -> header used: spc-buildroot

Without the guard cmake resolves the host header and the build compiles against it. With the guard
the host prefix is skipped and the buildroot header wins.

The existing suite, with the change applied, on macOS arm64 with PHP 8.5

$ ./vendor/bin/phpunit tests
OK (472 tests, 845 assertions)

Caveat, stated plainly. I could not run a full spc build on Intel macOS hardware, so the end to end
build fix is unconfirmed on the machine that reported #1289. What is confirmed is the cmake lookup
mechanism and that the guard flips it from host to buildroot.

Script used for the reproduction above.

W=$(mktemp -d); mkdir -p "$W/host/include/openssl" "$W/buildroot/include/openssl"
printf '#define ORIGIN "host-prefix"\n'   > "$W/host/include/openssl/x.h"
printf '#define ORIGIN "spc-buildroot"\n' > "$W/buildroot/include/openssl/x.h"
cat > "$W/main.c" <<'EOF'
#include <openssl/x.h>
#include <stdio.h>
int main(void) { printf("%s\n", ORIGIN); return 0; }
EOF
cat > "$W/CMakeLists.txt" <<EOF
cmake_minimum_required(VERSION 3.20)
project(p C)
find_path(X_INC openssl/x.h)
add_executable(p main.c)
if(X_INC)
  target_include_directories(p PRIVATE \${X_INC})
endif()
target_include_directories(p PRIVATE $W/buildroot/include)
EOF
for v in without with; do
  guard=""
  [ "$v" = with ] && guard="set(CMAKE_IGNORE_PREFIX_PATH \"$W/host\")"
  printf 'set(CMAKE_SYSTEM_PREFIX_PATH "%s")\n%s\nset(CMAKE_C_STANDARD_INCLUDE_DIRECTORIES "%s")\n' \
    "$W/host" "$guard" "$W/buildroot/include" > "$W/tc-$v.cmake"
  cmake -S "$W" -B "$W/b-$v" -DCMAKE_TOOLCHAIN_FILE="$W/tc-$v.cmake" >/dev/null 2>&1
  cmake --build "$W/b-$v" >/dev/null 2>&1 && printf '%s -> ' "$v" && "$W/b-$v/p"
done
rm -rf "$W"

Refs #1289

… shadow buildroot

Homebrew on Intel macOS installs into /usr/local, which is on the compiler
default search path. cmake then resolves headers and packages from the host
instead of buildroot, so the static build compiles against Intel Homebrew
headers and fails at link time (issue crazywhalecc#1289).

CMAKE_IGNORE_PREFIX_PATH drops /usr/local from cmake's prefix searches on
Darwin. Guarded on cmake 3.23+ so older cmake is unaffected.
@crazywhalecc
crazywhalecc merged commit b8de36c into crazywhalecc:v3 Nov 14, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants