Homebrew prefix transition from /usr/local to /opt/homebrew breaks CI build scripts

Answer

Standardize on dynamic prefix resolution using brew --prefix (or the $HOMEBREW_PREFIX environment variable) in every build step that references Homebrew‑installed files. Pinning CI runners to a single architecture is not required and reduces cross‑architecture testing.

Why this works

brew shellenv only adjusts PATH and MANPATH; it does not rewrite absolute paths that are hard‑coded in Makefiles, shell scripts, or generated configuration files. Those hard‑coded references to /usr/local continue to fail on arm64 runners where Homebrew lives under /opt/homebrew. By substituting the prefix at build time, the same source tree resolves to the correct Cellar location on both Intel and Apple Silicon machines.

Steps to implement

1. Identify every place in the repository that contains an absolute Homebrew path (e.g., /usr/local/bin, /usr/local/include, /usr/local/lib).
2. Replace each hard‑coded prefix with a variable that expands to the output of brew --prefix. In Makefiles you can use:

HOMEBREW_PREFIX := $(shell brew --prefix)
CFLAGS   += -I$(HOMEBREW_PREFIX)/include
LDFLAGS  += -L$(HOMEBREW_PREFIX)/lib

1. For shell scripts, export the variable before use:

export HOMEBREW_PREFIX=$(brew --prefix)
"$HOMEBREW_PREFIX/bin/foo" --option

1. If you use pkg-config, ensure it queries the correct prefix by setting PKG_CONFIG_PATH:

export PKG_CONFIG_PATH="$HOMEBREW_PREFIX/lib/pkgconfig:$HOMEBREW_PREFIX/share/pkgconfig"

Verification procedure

• Run brew --prefix in both the developer environment and the CI runner; the output must match the expected architecture‑specific prefix (/usr/local for Intel, /opt/homebrew for Apple Silicon).
• During the build, log the resolved path of a known dependency, e.g.:

echo "Resolved libfoo path: $(brew --prefix)/Cellar/libfoo/*/lib/libfoo.dylib"

• Confirm that the logged path begins with the prefix returned by brew --prefix and that the binary’s architecture matches the runner (use file or lipo -info).
• Add a pre‑build check that fails the job if brew --prefix does not equal the expected value for the runner’s architecture.

When brew shellenv alone is sufficient

If a build step only invokes Homebrew‑installed binaries via PATH (no absolute paths), brew shellenv is enough. Any step that resolves a Cellar symlink, includes headers, or links libraries requires explicit prefix substitution.