OSXCross: macOS Cross-Compilation Toolchain for Linux and BSD

What OSXCross Solves and Who Uses It

Building macOS binaries normally requires a macOS machine with Xcode. OSXCross removes that requirement. It installs a complete cross-compilation toolchain on Linux or BSD that produces macOS binaries without requiring any macOS hardware.

The README describes how OSXCross combines a host compiler, a macOS SDK, Darwin-compatible binary utilities (ar, lipo, otool, the ld64 linker), and a compiler wrapper that sets the target triple, SDK sysroot, deployment target, and linker automatically. The toolchain then presents target-prefixed commands such as x86_64-apple-darwinXX-clang++ and arm64-apple-darwinXX-clang++ on the PATH.

The repository lists two named projects that use OSXCross: multiarch/crossbuild for Docker-based multi-architecture builds across Linux, macOS, Windows, and other architectures, and Smartmontools, a hard disk monitoring tool. The host side supports x86, x86_64, ARM, and AArch64. Target architectures are arm64, arm64e, x86_64, and i386, with i386 availability depending on the build flavor chosen.

Three Build Flavors and Their Trade-offs

OSXCross offers three flavors selected during the build step. The stable flavor uses cctools 986 and ld64 711. The README describes it as known to be stable and well-working. The latest flavor uses cctools 1030.6.3 and ld64 956.6 and takes the longest to build because newer tool versions require additional dependencies.

The llvm flavor uses LLVM tools and ld64.lld instead of cctools and ld64. The README recommends it for new projects and calls it the easiest to build. However, the llvm flavor does not support i386 or x86_64h targets; it covers arm64, arm64e, and x86_64 only. It can optionally use cctools lipo instead of llvm-lipo for better compatibility when creating universal binaries.

The flavor choice is permanent for a given toolchain installation. The stable and latest flavors are better for teams that need i386 targets or that encounter linker edge cases the LLVM ld64.lld does not handle.

Getting the Apple SDK: The Required First Step

OSXCross does not ship the macOS SDK. You must extract it yourself from a full Xcode installation or from the Xcode Command Line Tools. The README points to README.SDK.md for step-by-step instructions on both macOS and Linux. The resulting archive must be placed in the tarballs/ directory before running build.sh.

This step is a real barrier: it requires access to a Mac or to a machine with Xcode already downloaded. Teams that cannot obtain the SDK from Apple directly cannot use OSXCross. The licensing terms around SDK redistribution are the reason OSXCross cannot bundle it. The README does not document where to obtain the SDK other than from Xcode.

OSXCross also provides optional scripts for building additional toolchain components: build_clang.sh for upstream LLVM/Clang and LLD, build_apple_clang.sh for Apple Clang, build_gcc.sh for vanilla GCC with x86_64 and i386 support, build_gcc_with_arm64_support.sh for the experimental Darwin GCC fork targeting ARM64, and build_compiler_rt.sh for the compiler-rt runtime library. Each has its own prerequisites documented in separate README files in the repository root.

Building OSXCross and Configuring the Toolchain

After placing the SDK archive in tarballs/ and installing build dependencies (documented in README.BUILD-DEPENDENCIES.md), run the build script:

./build.sh
BUILD_FLAVOR=llvm ./build.sh
UNATTENDED=1 BUILD_FLAVOR=latest ./build.sh
TARGET_DIR=/usr/local/osxcross OSX_VERSION_MIN=XX.X ENABLE_ARCHS="<ARCHS>" ./build.sh

Without environment variables, ./build.sh prompts interactively for a flavor. Setting BUILD_FLAVOR selects stable, latest, or llvm. Setting UNATTENDED=1 suppresses the prompt and uses the specified flavor automatically, defaulting to stable if BUILD_FLAVOR is absent. TARGET_DIR controls the installation directory; the default is ./target in the current directory. ENABLE_ARCHS restricts which target architectures are built into the toolchain, which reduces build time when only one architecture is needed.

After the build completes, add target/bin to your PATH. The installed directory contains the target-prefixed compiler wrappers, xcrun, and osxcross-conf. Run osxcross-conf to verify the active configuration and read the TARGET variable, which shows the darwin version string that the XX.X placeholder in compiler commands represents.

Compiling Code: xcrun, Target Prefixes, and Universal Binaries

OSXCross provides two equivalent ways to invoke the cross-compiler. The target-prefixed commands encode the architecture and darwin version in the binary name: x86_64-apple-darwinXX-clang++ for x86_64 and arm64-apple-darwinXX-clang++ for arm64. Alternatively, xcrun selects the compiler for the current target configuration using -arch flags.

Universal binaries that run on both x86_64 and arm64 can be compiled with a single xcrun invocation:

xcrun clang++ test.cpp -O3 -arch x86_64 -arch arm64 -o test

For libc++ with C++11 or later:

xcrun clang++ -stdlib=libc++ -std=c++11 test.cpp -o test

The libc++ shortcut wrappers are also available as direct commands: x86_64-apple-darwinXX-clang++-libc++ and arm64-apple-darwinXX-clang++-libc++. These are convenience aliases that avoid passing -stdlib=libc++ manually.

Link-time optimization follows the standard three-step pattern: compile with -flto twice, then link with -flto. GCC cross-compilation replaces clang++ with g++ and uses xcrun g++ for the same architecture flags. For creating universal binaries with GCC, the README shows building x86_64 and arm64 separately then combining with xcrun lipo -create.

CMake, Autotools, and Makefile Projects

For CMake projects, OSXCross installs architecture- and compiler-specific launcher scripts and a toolchain file. The README points to README.CMAKE.md for setup, compiler selection, universal binary configuration, and package discovery. The toolchain file is the recommended way to configure a CMake build to use the cross-compiler automatically, because it sets the target system, sysroot, and compiler in one step rather than requiring individual CMake variables.

For autotools projects, pass the host triple explicitly to configure:

CC=x86_64-apple-darwinXX-clang CXX=x86_64-apple-darwinXX-clang++ ./configure --host=x86_64-apple-darwinXX

For Makefile projects, xcrun -f clang prints the path to clang, allowing the compiler to be passed as CC and CXX:

make CC=$(xcrun -f clang) CXX=$(xcrun -f clang++)

A minimal MacPorts package manager is bundled with OSXCross and documented in README.MACPORTS.md for cases where macOS library dependencies need to be resolved during cross-compilation. OSXCross also ships README.PKG-CONFIG.md for configuring pkg-config to find macOS libraries in the sysroot during the build process.

Limitations: Architecture Gaps, SDK Legality, and Deployment Targets

The llvm flavor does not support i386 or x86_64h targets. Teams that need 32-bit macOS builds must use the stable or latest flavor instead. The llvm flavor is also the only one the README explicitly recommends for arm64e; the stable flavor supports i386 which the llvm flavor drops.

The macOS deployment target defaults depend on the SDK version. SDK 10.13 or earlier sets a deployment target of macOS 10.6. SDK 10.14 and later sets macOS 10.9. SDK 14.0 and later sets macOS 10.13. These defaults can be overridden three ways: by setting OSX_VERSION_MIN before running build.sh, by passing -mmacos-version-min= to the compiler, or by setting the MACOSX_DEPLOYMENT_TARGET environment variable at compile time. Setting a deployment target of 10.9 or later causes the default C++ standard library to be libc++. Setting it lower defaults to libstdc++, which can be overridden explicitly with -stdlib=libstdc++.

Obtaining the SDK is a hard dependency that OSXCross cannot automate. The README acknowledges that SDKs must be extracted from Xcode or Xcode Command Line Tools on a macOS system or through an existing macOS installation. This is a legal requirement, not a technical one, and it means OSXCross cannot be set up in a fully automated pipeline that starts from zero without macOS access at some point in the chain.

The multiarch/crossbuild Docker image wraps OSXCross for teams that want a pre-assembled container rather than building the toolchain from source. This is the practical alternative for CI pipelines. The README lists it as a known adopter.

Editorial conclusion

OSXCross is the practical path for Linux or BSD developers who need to compile macOS binaries without a macOS machine. The llvm flavor is the starting point for new projects because it builds fastest and supports arm64 and x86_64. Before starting, confirm that you can legally extract the macOS SDK from an Xcode installation: OSXCross does not bundle the SDK and you must supply it. Teams wanting to avoid a from-source build can use the multiarch/crossbuild Docker image, which the README lists as using OSXCross internally. If i386 support is required, use the stable or latest flavor instead of llvm. The last push to the repository was on 2026-07-24.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. tpoechtrager/osxcross on GitHub