Zig Cross-Compilation for macOS

This directory contains Docker-based tools for cross-compiling Zig projects to macOS executables from any platform.

Features

• 🐳 Ubuntu-based Docker container with Zig 0.13.0
• 🎯 Cross-compilation support for both x86_64 and ARM64 macOS
• 🐍 Python script for automated building and extraction
• 📦 Volume-based workflow for easy file sharing

Quick Start

Build Guillotine EVM for macOS

From the Guillotine project root:

# Simple one-liner to build for macOS
./lib/zig/build_guillotine_macos.sh

# The executable will be in: build/guillotine-<arch>-macos

General Zig Project Cross-Compilation

# Build any Zig project for macOS
python3 lib/zig/cross_compile_macos.py /path/to/zig/project -o myapp

# Build current directory
python3 lib/zig/cross_compile_macos.py . -o myapp

# With specific build mode
python3 lib/zig/cross_compile_macos.py . -o myapp --mode ReleaseSafe

# Pass additional zig build arguments
python3 lib/zig/cross_compile_macos.py . -o myapp --args "-Denable-llvm"

How It Works

1. Docker Container: An Ubuntu 24.04 container with Zig installed
2. Volume Mount: Your source code is mounted into the container
3. Cross-Compilation: Zig compiles for macOS target inside Linux
4. Extraction: The macOS executable is copied back to your host

Architecture Support

The scripts automatically detect your Mac's architecture and build for the correct target:

• ARM64 Macs (M1/M2/M3) → aarch64-macos
• Intel Macs → x86_64-macos

Docker Commands

Manual Cross-Compilation

# Build the Docker image
docker build -t zig-cross-compiler lib/zig/

# Cross-compile manually
docker run --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  zig-cross-compiler \
  zig build -Dtarget=aarch64-macos -Doptimize=ReleaseFast

# For single file
docker run --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  zig-cross-compiler \
  zig build-exe main.zig -target aarch64-macos -O ReleaseFast

Using Docker Compose

# Start interactive session
docker-compose up -d
docker-compose exec zig bash

# Inside container
zig build -Dtarget=aarch64-macos

Build Modes

• Debug: Fast compilation, runtime safety checks, larger binary
• ReleaseSafe: Optimized with runtime safety checks
• ReleaseFast: Optimized for speed (recommended)
• ReleaseSmall: Optimized for size

Troubleshooting

Permission Issues

If the executable isn't marked as executable:

chmod +x build/guillotine-*-macos

Architecture Mismatch

The script automatically detects your architecture, but you can manually specify:

# For Apple Silicon
docker run --rm -v $(pwd):/workspace zig-cross-compiler \
  zig build -Dtarget=aarch64-macos

# For Intel
docker run --rm -v $(pwd):/workspace zig-cross-compiler \
  zig build -Dtarget=x86_64-macos

Build Failures

Check that your project builds locally first:

zig build

Files

• Dockerfile: Ubuntu container with Zig 0.13.0
• docker-compose.yml: Docker Compose configuration
• cross_compile_macos.py: Python automation script
• build_guillotine_macos.sh: Quick build script for Guillotine
• .dockerignore: Excludes unnecessary files from Docker context

Requirements

• Docker
• Python 3.6+
• macOS (for running the output executable)