Why Your Build Breaks on Linux but Works on macOS: A Technical Primer
Archi4 min read
Contents
The same source, two different compilers#
You clone the repository. On your Mac it builds clean. On the Linux CI runner it fails with a linker error or a missing symbol. Nothing in the code changed. The difference is the toolchain: the compiler, the linker, the system headers, and the libraries each one finds by default.
Open source projects feel this first because contributors arrive with whatever machine they own. A maintainer merges a pull request that worked on the author's laptop, and the next scheduled build turns red. The root cause is usually one of four things: C library differences, compiler and standard library versions, header search order, or dynamic linking at runtime.
The C library is not the same C library#
On Linux, most builds link against glibc. On macOS, the system C library is different. On Alpine Linux, it is musl. Functions that exist in glibc may be missing or behave differently in musl. For example, getrandom behavior, malloc alignment guarantees, and the handling of LC_ALL vary. A program that compiles against glibc headers can fail to link on musl because a symbol is simply not there.
This is why container images based on Alpine sometimes need gcompat or a rebuild from source. The code is fine. The contract with the C library is different.
Compiler versions drift faster than people think#
GCC 9 and GCC 13 are not the same compiler. Clang 12 and Clang 17 differ too. Newer versions add warnings, change default flags, and sometimes alter code generation in ways that expose undefined behavior. A common example: strict aliasing. Code that casts pointers between unrelated types may work under one optimization level and crash under another.
Projects that pin a compiler version in CI avoid many surprises. Projects that use latest in their build image inherit every upstream change. A warning that was informational becomes an error because someone enabled -Werror in a shared CMake file.
Header search order is invisible until it bites#
When you write #include <foo.h>, the compiler looks in a list of directories. That list is built from the compiler's defaults, the -I flags in your build system, and environment variables like CPATH. If two directories contain a foo.h, the first one wins. On your machine, the order favors the version you installed. On another machine, a system package provides an older foo.h earlier in the list.
The build fails not because the header is missing but because the wrong header was found. This is especially common with libraries that ship both a development package and a runtime package. The development package must be installed, and the include path must point at the right prefix.
Dynamic linking at runtime is a separate problem#
A binary can compile and link successfully and still fail to start. On Linux, the dynamic linker searches for shared libraries in a fixed order: the RPATH or RUNPATH embedded in the binary, then LD_LIBRARY_PATH, then the system cache. On macOS, the equivalent is DYLD_LIBRARY_PATH and the install name of each library. A library that is present on the build machine may be absent on the target machine, leading to error while loading shared libraries.
The fix is usually to set RPATH to a relative path like $ORIGIN/../lib so the binary finds its own bundled libraries. Projects that skip this step work on the developer's machine and fail on a clean server.
What to check first#
When a build works in one place and not another, compare four things before changing code:
- The output of
cc --versionandld --versionon both machines. - The C library: run
ldd --versionor check/lib/libc.so.6. - The include search path:
cc -E -v -prints it. - The linker search path and any
RPATHin the binary:readelf -dorotool -L.
Most of these failures are not mysterious. They are the result of different defaults, and defaults are documented. A build that is reproducible in a container is reproducible because the container fixes those defaults. The source code was never the variable.
A note on package managers#
Homebrew on macOS, apt on Debian, and dnf on Fedora install libraries into different prefixes. Homebrew uses /opt/homebrew on Apple Silicon. Debian uses /usr/lib/x86_64-linux-gnu. If your build system assumes one prefix, it will fail on a machine that uses another. The fix is to let the build system discover the prefix with pkg-config or a CMake find module rather than hardcoding a path.
The takeaway for contributors#
If you submit a patch to an open source project, run the build in the same kind of environment the project uses. If the project provides a Dockerfile or a devcontainer, use it. That single step eliminates most of the environment differences described here. The remaining failures are real bugs in the code or the build scripts, and those are worth reporting.
More articles