Cross-Compilation Guide

This project supports building for Linux, Windows, and macOS from any host platform using flexible cross-compilation toolchains.

Dependencies

All Platforms (Ubuntu/Debian)

Install all cross-compilation dependencies at once:

# All dependencies for all 6 target platforms
sudo apt install \
    cmake build-essential \
    gcc-aarch64-linux-gnu g++-aarch64-linux-gnu \
    gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64 \
    clang-22 lld-22 \
    llvm-dev libxml2-dev uuid-dev libssl-dev \
    libbz2-dev zlib1g-dev

Note: clang-22 requires adding the LLVM apt repository first (see Windows ARM64 Setup below).

Per-Platform Dependencies

Target Platform	Required Packages
Linux x86-64	`build-essential cmake`
Linux ARM64	`gcc-aarch64-linux-gnu g++-aarch64-linux-gnu`
Windows x86-64	`gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64`
Windows ARM64	`clang-22 lld-22` + Windows SDK with ARM64 libs (see below)
macOS (both)	OSXCross + `clang llvm-dev libxml2-dev uuid-dev libssl-dev libbz2-dev zlib1g-dev`

Windows ARM64 Setup (WSL2)

Windows ARM64 cross-compilation requires clang 22+, the Windows SDK, and MSVC ARM64 libraries.

1. Install clang-22 from LLVM repository:

wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
sudo add-apt-repository "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs) main"
sudo apt update
sudo apt install clang-22 lld-22

# Set as default
sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-22 100
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-22 100
sudo update-alternatives --install /usr/bin/lld-link lld-link /usr/bin/lld-link-22 100

2. Install Visual Studio ARM64 build tools (on Windows):

Open Visual Studio Installer → Modify → Individual Components
Search "ARM64" and select "MSVC v143 - VS 2022 C++ ARM64 build tools (Latest)"

Or via command line:

vs_installer.exe modify --installPath "C:\Program Files\Microsoft Visual Studio\2022\Community" --add Microsoft.VisualStudio.Component.VC.Tools.ARM64

The toolchain automatically finds Windows SDK and MSVC at /mnt/c/Program Files/...

OSXCross Setup

For macOS cross-compilation, OSXCross must be installed at ~/osxcross (or set OSXCROSS_ROOT):

cd ~
git clone https://github.com/tpoechtrager/osxcross
cd osxcross/tarballs
wget https://github.com/joseluisq/macosx-sdks/releases/download/12.3/MacOSX12.3.sdk.tar.xz
cd ..
./build.sh

See the OSXCross section below for detailed instructions.

Quick Start

Build All Platforms

./build_all_platforms.sh

This will build for all platforms where toolchains are available.

Build Specific Platform

./build_all_platforms.sh --linux-only
./build_all_platforms.sh --windows-only
./build_all_platforms.sh --macos-only

Platform-Specific Setup

Linux Builds

Native Linux:

mkdir build_linux && cd build_linux
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_MATHEMATICA_PACLET=ON
make -j$(nproc) paclet

From Windows/WSL:

# WSL can build Linux binaries natively
mkdir build_linux && cd build_linux
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_MATHEMATICA_PACLET=ON
make -j$(nproc) paclet

From macOS (cross-compilation):

# Install Linux cross-compiler or use Docker
# Docker approach recommended:
docker run --rm -v $(pwd):/src -w /src ubuntu:22.04 bash -c "
  apt update && apt install -y cmake g++ make &&
  mkdir -p build_linux && cd build_linux &&
  cmake .. -DBUILD_MATHEMATICA_PACLET=ON &&
  make -j paclet
"

Windows Builds

From Linux/WSL using MinGW:

# Install MinGW
sudo apt install gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64

# Build
mkdir build_windows && cd build_windows
cmake .. \
  -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/windows-cross.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_MATHEMATICA_PACLET=ON
make -j$(nproc) paclet

From macOS using MinGW:

# Install MinGW via Homebrew
brew install mingw-w64

# Build
mkdir build_windows && cd build_windows
cmake .. \
  -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/windows-cross.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_MATHEMATICA_PACLET=ON
make -j$(sysctl -n hw.ncpu) paclet

Using Clang instead of MinGW:

mkdir build_windows && cd build_windows
cmake .. \
  -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/windows-cross.cmake \
  -DWINDOWS_COMPILER=clang \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_MATHEMATICA_PACLET=ON
make -j$(nproc) paclet

Native Windows (MSVC or MinGW):

mkdir build_windows
cd build_windows
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_MATHEMATICA_PACLET=ON
cmake --build . --config Release --target paclet

macOS Builds

Native macOS:

mkdir build_macos && cd build_macos
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_MATHEMATICA_PACLET=ON
make -j$(sysctl -n hw.ncpu) paclet

From Linux using OSXCross:

OSXCross allows cross-compiling to macOS from Linux. One-time setup required (~30-60 minutes).

Step 1: Install Dependencies

# Ubuntu/Debian
sudo apt install clang llvm-dev libxml2-dev uuid-dev libssl-dev \
  bash patch make tar xz-utils bzip2 gzip sed cpio libbz2-dev zlib1g-dev

# Arch Linux
sudo pacman -S clang llvm libxml2 libbz2 zlib

# Fedora/RHEL
sudo dnf install clang llvm-devel libxml2-devel libuuid-devel openssl-devel \
  bzip2-devel zlib-devel

Step 2: Clone OSXCross

cd ~  # or wherever you want to install
git clone https://github.com/tpoechtrager/osxcross
cd osxcross

Step 3: Obtain macOS SDK

You need an official macOS SDK from Xcode. Several options:

Option A: Pre-packaged SDKs (easiest)

cd tarballs

# Download pre-packaged SDK (macOS 12.3, works for most cases)
wget https://github.com/joseluisq/macosx-sdks/releases/download/12.3/MacOSX12.3.sdk.tar.xz

# Or macOS 11.3 (for older compatibility)
# wget https://github.com/joseluisq/macosx-sdks/releases/download/11.3/MacOSX11.3.sdk.tar.xz

Option B: Extract from Xcode (if you have access to a Mac)

# On macOS with Xcode installed:
./tools/gen_sdk_package_pbzx.sh  # Creates SDK tarball

# Copy the resulting .tar.* file to Linux machine at:
# osxcross/tarballs/MacOSXxx.x.sdk.tar.xz

Option C: Download from Apple (requires Apple Developer account)

Download Xcode from https://developer.apple.com/download/
Extract SDK using OSXCross tools

Step 4: Build OSXCross

# Verify SDK is in tarballs/
ls -lh tarballs/

# Build the cross-compiler toolchain (takes 30-60 minutes)
./build.sh

# Optional: Build additional tools
./build_compiler_rt.sh  # For sanitizers

Step 5: Set Environment

# Add to ~/.bashrc or ~/.zshrc for permanent setup
export OSXCROSS_ROOT="$HOME/osxcross"
export PATH="$OSXCROSS_ROOT/target/bin:$PATH"

# Or for current session only
export OSXCROSS_ROOT=$(pwd)
export PATH="$OSXCROSS_ROOT/target/bin:$PATH"

Step 6: Verify Installation

# Check compilers are available
x86_64-apple-darwin21-clang --version
x86_64-apple-darwin21-clang++ --version

# Should see "clang version" output

Step 7: Build Project for macOS

cd /path/to/hypergraph_project
mkdir build_macos && cd build_macos

cmake .. \
  -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/macos-cross.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_MATHEMATICA_PACLET=ON

make -j$(nproc) paclet

Troubleshooting OSXCross:

SDK version mismatch: Use SDK version matching your target macOS
Missing tools: Ensure all dependencies installed
Linker errors: Try ./build_compiler_rt.sh for additional libraries
PATH issues: Verify OSXCROSS_ROOT points to correct directory

SDK Version Selection:

macOS 10.15+: Use MacOSX11.3+ SDK
macOS 12+: Use MacOSX12.3+ SDK
Older macOS: Use matching SDK version

The toolchain will automatically find the SDK if OSXCROSS_ROOT is set correctly.

From Windows: OSXCross doesn't officially support Windows. Options:

Use WSL (see Linux instructions above)
Use Docker with OSXCross image
Build on actual macOS hardware

Compiler Selection

Override Compiler via Environment Variables

# Use specific compiler
export CC=clang
export CXX=clang++
cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/windows-cross.cmake

Windows Compiler Options

# MinGW (default)
cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/windows-cross.cmake -DWINDOWS_COMPILER=mingw

# Clang
cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/windows-cross.cmake -DWINDOWS_COMPILER=clang

# MSVC/clang-cl
cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/windows-cross.cmake -DWINDOWS_COMPILER=msvc

Architecture Support

x86_64 (default)

cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/windows-cross.cmake

ARM64 (aarch64)

# Set architecture
export TARGET_ARCH=aarch64
cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/windows-cross.cmake -DCMAKE_SYSTEM_PROCESSOR=aarch64

Note: ARM64 support requires appropriate cross-compilers:

Windows ARM64: aarch64-w64-mingw32-gcc
Linux ARM64: aarch64-linux-gnu-gcc
macOS ARM64 (Apple Silicon): Native or OSXCross with ARM SDK

Toolchain Files

The project includes three toolchain files:

cmake/toolchains/windows-cross.cmake - Cross-compile to Windows
cmake/toolchains/linux-cross.cmake - Cross-compile to Linux
cmake/toolchains/macos-cross.cmake - Cross-compile to macOS

Each toolchain:

Auto-detects available compilers (GCC, Clang, MSVC)
Respects CC/CXX environment variables
Supports multiple architectures (x86_64, ARM64)
Provides clear error messages with installation instructions

Mathematica/Wolfram Integration

The build system automatically finds Mathematica/Wolfram installations:

Manual Override:

cmake .. \
  -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/windows-cross.cmake \
  -DMATHEMATICA_INSTALL_DIR="/path/to/Mathematica"

WSL Users:

# Automatically detects Windows Mathematica
cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/windows-cross.cmake \
  -DMATHEMATICA_INSTALL_DIR="/mnt/c/Program Files/Wolfram Research/Mathematica/13.3"

Output Locations

Built libraries are placed in:

paclet/LibraryResources/
├── Linux-x86-64/libHypergraphRewriting.so
├── Windows-x86-64/HypergraphRewriting.dll
└── MacOSX-x86-64/libHypergraphRewriting.dylib

ARM64 builds go in corresponding directories:

paclet/LibraryResources/
├── Linux-ARM64/
├── Windows-ARM64/
└── MacOSX-ARM64/

Troubleshooting

MinGW Not Found

# Ubuntu/Debian
sudo apt install gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64

# Arch Linux
sudo pacman -S mingw-w64-gcc

# macOS
brew install mingw-w64

OSXCross Setup Issues

See https://github.com/tpoechtrager/osxcross for detailed setup instructions.

Common issues:

Missing Xcode Command Line Tools
SDK version mismatch
PATH not set correctly

Library Not Loading

Windows DLLs missing dependencies:

Use -static-libgcc -static-libstdc++ (automatic in toolchain)
Check for missing runtime DLLs with ldd or Dependency Walker

macOS dylib loading issues:

Verify SDK version matches deployment target
Check code signing if running on recent macOS

CI/CD Integration

Example GitHub Actions workflow:

name: Build All Platforms

on: [push]

jobs:
  build-matrix:
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            platform: linux
          - os: ubuntu-latest
            platform: windows
          - os: macos-latest
            platform: macos

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v3

      - name: Install dependencies
        run: |
          if [ "${{ matrix.platform }}" = "windows" ]; then
            sudo apt install gcc-mingw-w64-x86-64
          fi

      - name: Build
        run: ./build_all_platforms.sh --${{ matrix.platform }}-only

Development Tips

Faster Iteration

Build only what you need:

# Build just the library, skip tests
make -j$(nproc) HypergraphRewriting

# Build specific target
make -j$(nproc) hypergraph

Parallel Builds

# Use all CPU cores
make -j$(nproc)

# Limit parallel jobs
make -j4

Clean Rebuild

# Clean build directory
rm -rf build_*
./build_all_platforms.sh

Platform-Agnostic Code

This project is designed to be platform-agnostic:

No platform-specific code in core libraries
All platform differences handled via CMake
Standard C++17, no OS-specific APIs
Cross-platform threading (C++11 threads)

Adding new platforms requires only:

Create toolchain file in cmake/toolchains/
Update paclet/LibraryResources/CMakeLists.txt platform detection
Test build and runtime

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cross-Compilation Guide

Dependencies

All Platforms (Ubuntu/Debian)

Per-Platform Dependencies

Windows ARM64 Setup (WSL2)

OSXCross Setup

Quick Start

Build All Platforms

Build Specific Platform

Platform-Specific Setup

Linux Builds

Windows Builds

macOS Builds

Compiler Selection

Override Compiler via Environment Variables

Windows Compiler Options

Architecture Support

x86_64 (default)

ARM64 (aarch64)

Toolchain Files

Mathematica/Wolfram Integration

Output Locations

Troubleshooting

MinGW Not Found

OSXCross Setup Issues

Library Not Loading

CI/CD Integration

Development Tips

Faster Iteration

Parallel Builds

Clean Rebuild

Platform-Agnostic Code

FilesExpand file tree

CROSS_COMPILATION.md

Latest commit

History

CROSS_COMPILATION.md

File metadata and controls

Cross-Compilation Guide

Dependencies

All Platforms (Ubuntu/Debian)

Per-Platform Dependencies

Windows ARM64 Setup (WSL2)

OSXCross Setup

Quick Start

Build All Platforms

Build Specific Platform

Platform-Specific Setup

Linux Builds

Windows Builds

macOS Builds

Compiler Selection

Override Compiler via Environment Variables

Windows Compiler Options

Architecture Support

x86_64 (default)

ARM64 (aarch64)

Toolchain Files

Mathematica/Wolfram Integration

Output Locations

Troubleshooting

MinGW Not Found

OSXCross Setup Issues

Library Not Loading

CI/CD Integration

Development Tips

Faster Iteration

Parallel Builds

Clean Rebuild

Platform-Agnostic Code