✨ Features

• 🎯 Zero Configuration - Works out of the box for most targets
• 🔧 Auto-Installation - Automatically installs missing toolchains and targets
• 🎨 Beautiful Output - Colored messages with helpful tips and hints
• ⚡ Smart Detection - Figures out what you need automatically
• 📦 Interactive Setup - TUI wizard for easy project configuration
• 🚀 Parallel Builds - Build multiple targets concurrently for 2-3x speedup
• 🐳 Container Support - Docker/Podman integration for complex cross-compilation
• 🌍 Many Targets - Linux, Windows, macOS, WebAssembly, and more
• 🤖 CI/CD Ready - Perfect for GitHub Actions, GitLab CI

🚀 Quick Start

Installation

# Install from crates.io (recommended)
cargo install xcargo

# Install with container support
cargo install xcargo --features container

# Or build from source
git clone https://github.com/ibrahimcesar/xcargo
cd xcargo
cargo build --release --features container

🔐 Verifying Downloads

All xcargo release binaries are signed with minisign for authenticity and integrity verification.

Install minisign:

# macOS
brew install minisign

# Linux (Debian/Ubuntu)
sudo apt install minisign

# Linux (other) or from source
cargo install minisign-verify
# Or download from: https://github.com/jedisct1/minisign/releases

# Windows
scoop install minisign

Verify a downloaded binary:

# Download binary, signature, and checksum from GitHub releases
wget https://github.com/ibrahimcesar/xcargo/releases/download/v0.2.0/xcargo-linux-x86_64
wget https://github.com/ibrahimcesar/xcargo/releases/download/v0.2.0/xcargo-linux-x86_64.minisig
wget https://github.com/ibrahimcesar/xcargo/releases/download/v0.2.0/xcargo-linux-x86_64.sha256

# Verify signature
minisign -Vm xcargo-linux-x86_64 -P RWRzZS/Coz8XEj1XGXl9P93QnWHHSkqBfByJoX7tTXRJBUMLxR10WbW6

# Verify checksum
sha256sum -c xcargo-linux-x86_64.sha256

xcargo minisign public key:

RWRzZS/Coz8XEj1XGXl9P93QnWHHSkqBfByJoX7tTXRJBUMLxR10WbW6

Interactive Setup

The easiest way to get started is with the interactive setup wizard:

xcargo init --interactive

This will guide you through:

• ✨ Selecting target platforms
• ⚙️ Configuring parallel builds
• 🔧 Setting up caching
• 🐳 Choosing container strategy
• 📦 Installing targets automatically

First Build

# Build for your current platform
xcargo build

# Build for a specific target
xcargo build --target x86_64-pc-windows-gnu

# Build for all configured targets
xcargo build --all

# Release build
xcargo build --target x86_64-unknown-linux-gnu --release

💡 Usage Examples

Basic Cross-Compilation

# Build for Windows from any platform
xcargo build --target x86_64-pc-windows-gnu

# Build for Linux ARM
xcargo build --target aarch64-unknown-linux-gnu

# Build for macOS (M1/M2)
xcargo build --target aarch64-apple-darwin

# Build for WebAssembly
xcargo build --target wasm32-unknown-unknown

# Use container for build (requires --features container)
xcargo build --target x86_64-unknown-linux-gnu --container

Target Management

# List common cross-compilation targets
xcargo target list

# Show installed targets
xcargo target list --installed

# Get detailed info about a target
xcargo target info x86_64-pc-windows-gnu

# Add a new target
xcargo target add x86_64-unknown-linux-musl

Configuration

# Show current configuration
xcargo config

# Show default configuration template
xcargo config --default

# Initialize with defaults
xcargo init

# Interactive setup wizard
xcargo init --interactive

⚙️ Configuration File

Create an xcargo.toml in your project root:

[targets]
# Default targets to build when no target is specified
default = [
    "x86_64-unknown-linux-gnu",
    "x86_64-pc-windows-gnu",
]

# Per-target custom configuration
[targets."x86_64-pc-windows-gnu"]
linker = "x86_64-w64-mingw32-gcc"

[targets."x86_64-pc-windows-gnu".env]
CC = "x86_64-w64-mingw32-gcc"

[build]
# Enable parallel builds for multiple targets (2-3x faster!)
parallel = true

# Enable build caching
cache = true

# Force container usage (not yet implemented)
force_container = false

# Additional cargo flags to pass to all builds
cargo_flags = []

[container]
# Container runtime: auto, docker, podman
# Note: youki (pure Rust OCI runtime) will be supported in a future release
runtime = "auto"

# When to use containers
use_when = "target.os != host.os"

# Image pull policy
pull_policy = "if-not-present"

# Build profiles for different scenarios
[profiles.release-all]
targets = [
    "x86_64-unknown-linux-gnu",
    "x86_64-pc-windows-gnu",
    "x86_64-apple-darwin",
    "aarch64-unknown-linux-gnu",
    "aarch64-apple-darwin",
]

🎯 Supported Targets

xcargo supports all Rust targets. Common ones include:

Linux

• x86_64-unknown-linux-gnu - Linux x86_64
• x86_64-unknown-linux-musl - Linux x86_64 (static)
• aarch64-unknown-linux-gnu - Linux ARM64

Windows

• x86_64-pc-windows-gnu - Windows x86_64 (MinGW)
• x86_64-pc-windows-msvc - Windows x86_64 (MSVC)

macOS

• x86_64-apple-darwin - macOS x86_64
• aarch64-apple-darwin - macOS ARM64 (M1/M2)

WebAssembly

• wasm32-unknown-unknown - WebAssembly

Run xcargo target list to see all common targets with descriptions.

🔧 Linker Configuration

For successful cross-compilation, you often need to configure linkers. xcargo makes this easy:

Windows Cross-Compilation (from macOS/Linux)

[targets."x86_64-pc-windows-gnu"]
linker = "x86_64-w64-mingw32-gcc"

[targets."x86_64-pc-windows-gnu".env]
CC = "x86_64-w64-mingw32-gcc"
AR = "x86_64-w64-mingw32-ar"

Install on macOS: brew install mingw-w64 Install on Linux: sudo apt install mingw-w64

Linux Cross-Compilation (from macOS)

[targets."x86_64-unknown-linux-gnu"]
linker = "x86_64-linux-gnu-gcc"

[targets."x86_64-unknown-linux-gnu".env]
CC = "x86_64-linux-gnu-gcc"

Note: Linux cross-compilation from macOS often requires containers

What xcargo does automatically:

• ✅ Verifies linker exists in PATH before building
• ✅ Sets CARGO_TARGET_*_LINKER environment variable
• ✅ Applies custom environment variables (CC, AR, etc.)
• ✅ Shows helpful errors with installation instructions if linker is missing

🐳 Container Builds

For complex cross-compilation scenarios where native toolchains are difficult to set up, xcargo supports container-based builds using Docker or Podman.

Installation with Container Support

# Install xcargo with container feature
cargo install xcargo --features container

# Ensure you have Docker or Podman installed
docker --version  # or: podman --version

When to Use Containers

Container builds are ideal when:

• 🌐 Cross-compiling between different operating systems (e.g., macOS → Linux)
• 🔧 Native toolchains are difficult to install or configure
• 🎯 You need reproducible builds across different development machines
• 📦 Your project has complex system dependencies

Basic Usage

# Build using a container
xcargo build --target x86_64-unknown-linux-gnu --container

# Container builds work with all flags
xcargo build --target aarch64-unknown-linux-gnu --container --release

Automatic Container Detection

Configure xcargo to automatically use containers when needed:

# xcargo.toml
[container]
# Container runtime: auto, docker, podman
runtime = "auto"

# Automatically use containers when cross-compiling to different OS
use_when = "target.os != host.os"

# Or always use containers
# use_when = "always"

# Or never use containers
# use_when = "never"

# Image pull policy: always, if-not-present, never
pull_policy = "if-not-present"

With this configuration, xcargo will automatically use containers when building for a different OS:

# On macOS, this will automatically use a container
xcargo build --target x86_64-unknown-linux-gnu

# On Linux, this will use native toolchain
xcargo build --target x86_64-unknown-linux-gnu

Supported Container Targets

xcargo uses pre-built images from cross-rs for these targets:

Linux:

• x86_64-unknown-linux-gnu
• x86_64-unknown-linux-musl
• aarch64-unknown-linux-gnu
• aarch64-unknown-linux-musl
• armv7-unknown-linux-gnueabihf
• arm-unknown-linux-gnueabihf

Windows:

• x86_64-pc-windows-gnu

Android:

• aarch64-linux-android
• armv7-linux-androideabi
• x86_64-linux-android
• i686-linux-android

Note: macOS and WebAssembly targets don't use containers:

• macOS cross-compilation requires osxcross or building on macOS
• WebAssembly builds work natively without containers

Container Requirements

Docker:

# macOS
brew install --cask docker
# Or download from https://www.docker.com/products/docker-desktop

# Linux
sudo apt install docker.io  # Ubuntu/Debian
sudo dnf install docker      # Fedora
sudo systemctl start docker
sudo usermod -aG docker $USER  # Add yourself to docker group

Podman (Docker-compatible alternative):

# macOS
brew install podman
podman machine init
podman machine start

# Linux
sudo apt install podman     # Ubuntu/Debian
sudo dnf install podman      # Fedora

Advanced Configuration

[container]
# Prefer specific runtime
runtime = "podman"

# Custom registry for images
registry = "my-registry.com/cross-images"

# Always use containers for reproducible builds
use_when = "always"

# Per-target container configuration
[targets."x86_64-unknown-linux-gnu"]
linker = "x86_64-linux-gnu-gcc"

[targets."x86_64-unknown-linux-gnu".env]
CC = "x86_64-linux-gnu-gcc"
CUSTOM_VAR = "value"

How Container Builds Work

1. Runtime Detection - Finds Docker or Podman on your system
2. Image Selection - Chooses the appropriate cross-rs image for your target
3. Volume Mounting - Mounts your project and cargo cache into the container
4. Build Execution - Runs cargo build inside the container
5. Artifact Extraction - Build artifacts appear in your local target/ directory

┌─────────────────────────────────┐
│ xcargo build --container        │
└──────────┬──────────────────────┘
           │
           ▼
   ┌───────────────────┐
   │ Detect container  │
   │ runtime (Docker/  │
   │ Podman)           │
   └───────┬───────────┘
           │
           ▼
   ┌───────────────────┐
   │ Pull cross-rs     │
   │ image for target  │
   └───────┬───────────┘
           │
           ▼
   ┌───────────────────┐
   │ Mount project &   │
   │ cargo cache       │
   └───────┬───────────┘
           │
           ▼
   ┌───────────────────┐
   │ Run cargo build   │
   │ in container      │
   └───────┬───────────┘
           │
           ▼
   ┌───────────────────┐
   │ Extract artifacts │
   │ to local target/  │
   └───────────────────┘

Troubleshooting

Container runtime not found:

# Check if Docker/Podman is installed and running
docker info
# or
podman info

Permission denied errors (Linux):

# Add your user to the docker group
sudo usermod -aG docker $USER
# Then log out and back in

Image pull failures:

# Manually pull the image
docker pull ghcr.io/cross-rs/x86_64-unknown-linux-gnu:latest

# Check your network/proxy settings
docker info | grep -i proxy

🔧 How It Works

1. Target Detection - Analyzes the target triple and determines requirements
2. Toolchain Check - Verifies the Rust toolchain and target are installed
3. Auto-Installation - Installs missing components via rustup
4. Smart Building - Uses native builds when possible, suggests containers when needed
5. Helpful Output - Shows tips, hints, and next steps

┌──────────────────────────────┐
│ xcargo build --target linux  │
└──────────┬───────────────────┘
           │
           ▼
   ┌───────────────┐
   │ Detect target │
   │ requirements  │
   └───────┬───────┘
           │
           ▼
   ┌────────────────┐
   │ Check toolchain│
   │ & install if   │
   │ missing        │
   └───────┬────────┘
           │
           ▼
   ┌────────────────┐
   │ Execute cargo  │
   │ build with     │
   │ proper flags   │
   └────────────────┘

🤖 CI/CD Integration

GitHub Actions

name: Cross-Platform Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install xcargo
        run: cargo install xcargo

      - name: Build for all targets
        run: xcargo build --all

GitLab CI

build:
  image: rust:latest
  script:
    - cargo install xcargo
    - xcargo build --all
  artifacts:
    paths:
      - target/*/release/*

🎨 Beautiful Output

xcargo provides helpful, colored output with tips and hints:

✨ xcargo Interactive Setup
Let's configure cross-compilation for your project!

✓ Detected host platform: aarch64-apple-darwin

? Which targets do you want to build for?
  ↑↓ to navigate, Space to select, Enter to confirm
  [ ] Linux x86_64
  [✓] Windows x86_64 (GNU)
  [✓] macOS ARM64 (M1/M2)

✓ Configuration created successfully!

📋 Configuration Summary
────────────────────────
Targets: x86_64-pc-windows-gnu, aarch64-apple-darwin
Parallel builds: enabled
Build cache: enabled
Container strategy: target.os != host.os

💡 Tip: Run 'xcargo build' to build for your host platform
💡 Tip: Run 'xcargo build --all' to build for all configured targets

📊 Status

Current Version: 0.2.0

✅ Working Features:

• Target detection and validation
• Toolchain management via rustup
• Basic cross-compilation
• Configuration system (xcargo.toml)
• Interactive TUI setup wizard
• Beautiful colored output with tips
• Self-building capability (xcargo builds itself!)
• Parallel target compilation (2-3x speedup with parallel = true)
• Linker configuration (automatic CARGO_TARGET_*_LINKER setup)
• Container builds (Docker/Podman integration with --features container)
• Smart error messages with platform-specific help
• GitHub Actions CI/CD integration

🚧 Planned Features:

• Bundled cross-compilation toolchains - Zero-dependency builds without Docker (download minimal toolchains on-demand)
• Pure Rust OCI runtime (youki integration) as optional feature
• Native dependency management
• Build caching improvements
• Custom container image support

🗺️ Roadmap

Phase 1: Core Cross-Compilation (v0.1-0.2) ✅

• ✅ Target detection and validation
• ✅ Toolchain management via rustup
• ✅ Configuration system (xcargo.toml)
• ✅ Interactive TUI setup wizard
• ✅ Parallel builds for 2-3x speedup
• ✅ Linker configuration
• ✅ Container builds (Docker/Podman)
• ✅ Binary signing (minisign)

Phase 2: Zero-Dependency Builds (v0.3) 🚧

Goal: Make cross-compilation work out of the box with zero external dependencies.

Bundled toolchain system

• Download minimal cross-compilation toolchains on-demand (~20-50MB per target)
• Cache in ~/.xcargo/toolchains/
• No Docker, no manual toolchain installation required
• Fallback to containers for complex targets
  Build and host pre-compiled toolchains for tier 1 targets
  Automatic toolchain updates

Trade-offs:

• ✅ Better UX: Just works, no setup needed
• ✅ Smaller downloads: 20-50MB vs 500MB+ containers
• ✅ Offline-friendly: Works after first download
• ⚠️ More complexity: Need to build/maintain toolchains
• ⚠️ Hosting costs: Bandwidth for toolchain downloads

Phase 3: Enhanced Security & Distribution (v0.4)

Platform-Specific Code Signing 🎯

Currently, xcargo binaries are signed with minisign (free, cross-platform). For enhanced platform integration, we're considering:

macOS Code Signing:

• What: Sign with Apple Developer certificate, enable Gatekeeper
• Benefit: Better macOS user experience, no "unidentified developer" warnings
• Cost: $99/year Apple Developer Program
• Status: Planned, pending community interest

Windows Authenticode:

• What: Sign with code signing certificate, satisfy SmartScreen
• Benefit: Better Windows user experience, no security warnings
• Cost: $100-500/year for certificate
• Status: Planned, pending community interest

Want platform-specific signing?

• 👍 React to #123 if you want macOS signing
• 👍 React to #124 if you want Windows signing
• 💬 Share your use case in the issues

Note: Platform signing requires paid certificates. We'll implement these features when there's sufficient community interest to justify the ongoing costs. Minisign signatures will always be provided as a free, cross-platform verification method.

Other v0.4 features:
xcargo sign - Help users sign their own binaries
Native dependency detection and management
Advanced build caching
Build profiles and presets

Phase 4: Advanced Features (v0.5+)

youki integration (pure Rust OCI runtime)
Custom toolchain registry
Build reproducibility guarantees
SBOM (Software Bill of Materials) generation
Integration with cargo-dist
Plugin system for custom targets

Community-Driven Priorities

We prioritize features based on community feedback. Share your needs:

• 🐛 Report bugs
• 💡 Request features
• 💬 Join discussions

🆚 Comparison

Feature	xcargo	cross	cargo-zigbuild
Native-first	✅	❌	⚠️ Via Zig
Auto-install targets	✅	❌	❌
Interactive setup	✅	❌	❌
Parallel builds	✅	❌	❌
Beautiful output	✅	⚠️	⚠️
Configuration file	✅	✅	❌
Container support	✅	✅	❌
Zero config	✅	❌	⚠️

🤝 Contributing

Contributions are welcome! This is an early-stage project with lots of opportunity to help.

Ways to contribute:

• 🐛 Report bugs and suggest features via GitHub Issues
• 💻 Submit pull requests for fixes or new features
• 📝 Improve documentation
• 🎯 Test on different platforms and targets
• ⭐ Star the repo to show support!

See CONTRIBUTING.md for development setup and guidelines.

📚 Documentation

• Full Documentation
• API Documentation
• Configuration Reference
• Target Guide

📝 License

MIT © Ibrahim Cesar

🙏 Acknowledgments

Inspired by excellent tools in the Rust ecosystem:

• cross - Container-based cross-compilation
• cargo-zigbuild - Zig linker approach
• rustup - Rust toolchain management

---