How to Cross-Compile Bitcoin Core for Windows, macOS, and Linux Architectures

Cross-compile Bitcoin Core by building target-specific dependencies in the depends/ directory using a host triplet (e.g., x86_64-w64-mingw32), then invoke CMake with the generated toolchain.cmake file to produce binaries for architectures different from your build machine.

The bitcoin/bitcoin repository uses a specialized depends build system to enable cross-compilation across diverse platforms. When you need to build Bitcoin Core binaries for Windows, macOS, or alternative Linux architectures from a single development machine, this system automates the creation of cross-compiled libraries and CMake toolchain files that redirect the core build to target-specific artifacts.

Understanding the Cross-Compilation Architecture

The cross-compilation workflow relies on the depends subsystem located in the depends/ directory. According to depends/README.md lines 111-136, this system performs two critical functions: it builds all third-party libraries (such as Boost, OpenSSL, and libevent) for the specified target architecture, and it generates a CMake toolchain file (e.g., depends/x86_64-w64-mingw32/toolchain.cmake) that configures the compiler, linker, and library paths for the target platform.

The core Bitcoin build itself remains unchanged during cross-compilation. As noted in depends/README.md lines 77-80, CMake ignores the depends output unless you explicitly pass the toolchain file using the --toolchain parameter.

Step-by-Step: How to Cross-Compile Bitcoin Core

1. Build Cross-Compiled Dependencies

First, build the dependencies for your target platform using the HOST parameter. The HOST value uses a triplet format (e.g., x86_64-w64-mingw32 for 64-bit Windows) that identifies the target architecture, vendor, and operating system.

cd /path/to/bitcoin
make HOST=x86_64-w64-mingw32 -j$(nproc)

This process generates the toolchain file at depends/x86_64-w64-mingw32/toolchain.cmake and builds all required libraries for the target.

2. Configure Bitcoin Core with the Toolchain

Invoke CMake with the --toolchain flag pointing to the generated toolchain file. This redirects the build system to use the cross-compiled dependencies and appropriate compiler.

cmake -B build \
      --toolchain depends/x86_64-w64-mingw32/toolchain.cmake \
      -DENABLE_WALLET=ON

3. Compile the Binary

Build the project using the configured build directory:

cmake --build build -j$(nproc)

The resulting binaries will be located in build/src/ and will be executable on the target platform.

Platform-Specific Cross-Compilation Examples

Windows 64-bit (MinGW)

For Windows targets using the MSVCRT runtime (traditional Windows 7+ compatibility):

make HOST=x86_64-w64-mingw32 -j$(nproc)
cmake -B build --toolchain depends/x86_64-w64-mingw32/toolchain.cmake
cmake --build build

For the modern UCRT runtime (Windows 10+):

make HOST=x86_64-w64-mingw32ucrt -j$(nproc)
cmake -B build --toolchain depends/x86_64-w64-mingw32ucrt/toolchain.cmake
cmake --build build

macOS Intel and Apple Silicon

Cross-compiling for macOS requires the Apple SDK. According to depends/README.md lines 138-146 and contrib/macdeploy/README.md lines 11-46, you must download the Xcode SDK and place it under depends/SDKs/ before building.

First, install the required toolchain on your host (Debian/Ubuntu example):

sudo apt install clang lld llvm zip

Extract the macOS SDK:

mkdir -p depends/SDKs
tar xf Xcode-*.tar -C depends/SDKs

For Intel Macs (x86_64):

make HOST=x86_64-apple-darwin -j$(nproc)
cmake -B build --toolchain depends/x86_64-apple-darwin/toolchain.cmake
cmake --build build

For Apple Silicon (ARM64):

make HOST=arm64-apple-darwin -j$(nproc)
cmake -B build --toolchain depends/arm64-apple-darwin/toolchain.cmake
cmake --build build

Linux ARM 32-bit

For 32-bit ARM Linux targets (e.g., Raspberry Pi):

make HOST=arm-linux-gnueabihf -j$(nproc)
cmake -B build --toolchain depends/arm-linux-gnueabihf/toolchain.cmake
cmake --build build

PowerPC 64-bit (Big Endian)

For PowerPC 64-bit big-endian Linux targets:

make HOST=powerpc64-linux-gnu -j$(nproc)
cmake -B build --toolchain depends/powerpc64-linux-gnu/toolchain.cmake
cmake --build build

Key Files and References

Understanding the cross-compilation process requires familiarity with several documentation files in the repository:

• depends/README.md – The primary reference for cross-compilation workflows, host triplet specifications, and SDK requirements (lines 111-136, 77-80, 121-135, 138-146).
• depends/<host-triplet>/toolchain.cmake – The generated CMake toolchain file that configures the compiler and library paths for the target platform.
• contrib/macdeploy/README.md – Essential for macOS cross-compilation, detailing how to obtain and extract the Xcode SDK (lines 11-46).
• doc/build-unix.md, doc/build-windows.md, doc/build-osx.md – Platform-specific build instructions that complement the cross-compilation workflow.

Summary

• Use the depends system to build cross-compiled dependencies and generate CMake toolchain files for your target platform.
• Specify the target using a host triplet (e.g., x86_64-w64-mingw32, arm64-apple-darwin) when running make in the depends directory.
• Configure with the toolchain by passing --toolchain depends/<host-triplet>/toolchain.cmake to CMake to redirect the build to cross-compiled libraries.
• Handle macOS SDK requirements by placing the extracted Xcode SDK in depends/SDKs/ and installing clang/llvm on the host system before building.
• The core build remains unchanged; cross-compilation only requires pointing CMake to the correct toolchain file generated by the depends system.

Frequently Asked Questions

What is a host triplet and where do I find the correct one for my target?

A host triplet is a standardized string identifying the target architecture, vendor, and operating system (e.g., x86_64-w64-mingw32 for 64-bit Windows). According to depends/README.md lines 121-135, common triplets include x86_64-w64-mingw32 for Windows, arm64-apple-darwin for Apple Silicon, and powerpc64-linux-gnu for PowerPC. The depends system uses this triplet to select the correct compiler and build dependencies for that specific platform.

Why does macOS cross-compilation require an Apple SDK?

macOS cross-compilation requires the Apple SDK because the build needs access to proprietary Apple frameworks and headers that cannot be redistributed with the Bitcoin Core source code. As documented in depends/README.md lines 138-146 and contrib/macdeploy/README.md lines 11-46, you must download the Xcode SDK separately, extract it, and place it under depends/SDKs/. Additionally, you must install clang/llvm on your host system to handle the cross-compilation to Apple's architecture.

Can I cross-compile for Windows using the UCRT runtime instead of MSVCRT?

Yes, Bitcoin Core supports cross-compiling for Windows using the modern UCRT (Universal C Runtime) instead of the legacy MSVCRT. According to the depends system documentation, use the host triplet x86_64-w64-mingw32ucrt instead of x86_64-w64-mingw32 when building dependencies. The generated toolchain file will be located at depends/x86_64-w64-mingw32ucrt/toolchain.cmake, which you then pass to CMake to produce Windows 10+ compatible binaries.

Do I need to rebuild the dependencies every time I modify Bitcoin Core source code?

No, you do not need to rebuild the depends dependencies every time you modify the Bitcoin Core source code. The depends system builds static libraries for the target platform (such as Boost, OpenSSL, and libevent) that rarely change. Once you have built the dependencies for a specific host triplet and they exist in the depends/<host-triplet>/ directory, you can reconfigure and rebuild only the Bitcoin Core components by running CMake with the existing toolchain file. Rebuild dependencies only when upgrading library versions or switching to a different target architecture.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}