xcargo 0.1.0

Cross-compilation, zero friction - Rust cross-compilation tool with automatic toolchain management
Documentation

xcargo 🎯

Cross-compilation, zero friction

xcargo is a Rust cross-compilation tool that simplifies building for multiple targets. Automatic toolchain management, intelligent container usage, and zero-configuration cross-compilation.

🎯 What is xcargo?

Cross-compilation in Rust shouldn't be painful. xcargo automates the entire process:

  • Detects what you need automatically
  • Installs toolchains and dependencies
  • Builds for any target with one command
  • Uses containers only when necessary (includes embedded runtime)

✨ Features (Planned)

  • 🎯 Zero Configuration - Works out of the box for most targets
  • 🔧 Auto-Detection - Figures out what toolchains you need
  • 🐳 Smart Containers - Uses native builds when possible, containers when needed
  • ⚡ Fast - Parallel builds, intelligent caching
  • 🌍 Many Targets - Linux, Windows, macOS, mobile, embedded
  • 🤖 CI/CD Ready - Perfect for GitHub Actions, GitLab CI
  • 📦 Embedded Runtime - No Docker Desktop required (uses youki)

🚧 Status

Work in Progress - Early development

Current version: 0.1.0-alpha

🚀 Quick Example (Planned API)

# Initialize cross-compilation for your project
xcargo init

# Add target platforms
xcargo target add windows linux macos

# Check what's needed
xcargo doctor
# ✅ windows-x86_64: Ready
# ❌ linux-arm64: Missing linker (install: apt install gcc-aarch64-linux-gnu)
# ⚠️  macos-aarch64: Requires macOS host for native compilation

# Build for all configured targets
xcargo build --all

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

# Or use as cargo wrapper
xcargo cargo build --target x86_64-pc-windows-gnu

📦 Installation

# Not yet published - coming soon!
cargo install xcargo

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

🗺️ Roadmap

Phase 1: Core (Current)

  • Target detection and validation
  • Toolchain management
  • Basic native cross-compilation
  • Configuration system

Phase 2: Containers

  • Embedded container runtime (youki)
  • Docker/Podman fallback
  • Image caching
  • Native-first strategy

Phase 3: Advanced

  • Build profiles (release-all, embedded, mobile)
  • Parallel builds
  • Dependency management (OpenSSL, SQLite, etc.)
  • Custom target definitions

Phase 4: Integration

  • GitHub Actions integration
  • GitLab CI templates
  • Pre-built binaries distribution
  • GUI/TUI interface

🎯 Supported Targets

See TARGETS.md for the complete list.

Tier 1 (Native builds):

  • x86_64-unknown-linux-gnu
  • x86_64-unknown-linux-musl
  • x86_64-pc-windows-gnu
  • x86_64-apple-darwin
  • aarch64-apple-darwin

Tier 2 (Container builds):

  • aarch64-unknown-linux-gnu
  • armv7-unknown-linux-gnueabihf
  • x86_64-pc-windows-msvc
  • wasm32-unknown-unknown

Tier 3 (Specialized):

  • Mobile (Android, iOS)
  • Embedded (ARM Cortex-M)

🛠️ How It Works

┌─────────────────────────────────┐
│ xcargo build --target windows   │
└────────────┬────────────────────┘
             │
             ▼
     ┌───────────────┐
     │ Can compile   │
     │ natively?     │
     └───┬───────┬───┘
         │       │
      YES│       │NO
         │       │
         ▼       ▼
    ┌────────┐ ┌──────────────────┐
    │ Native │ │ Need container?  │
    │ build  │ │ Check deps...    │
    └────────┘ └────┬─────────────┘
                    │
                    ▼
            ┌───────────────┐
            │ Use youki     │
            │ (embedded)    │
            └───────────────┘

📖 Usage Examples

Basic Cross-Compilation

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

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

# Build for all targets
xcargo build --all

Configuration File

# xcargo.toml
[targets]
default = ["x86_64-unknown-linux-gnu", "x86_64-pc-windows-gnu"]

[profiles.release-all]
targets = [
    "x86_64-unknown-linux-gnu",
    "x86_64-pc-windows-gnu",
    "x86_64-apple-darwin",
]

[build]
parallel = true
cache = true

[container]
runtime = "auto"  # auto, youki, docker, podman
use-when = "target.os != host.os"

CI/CD Integration

# .github/workflows/build.yml
name: Cross-Platform Build

on: [push]

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

      - name: Install xcargo
        run: cargo install xcargo

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

      - name: Upload artifacts
        run: xcargo release --upload

🎨 Design Goals

Make cross-compilation boring (in a good way):

  • ✅ Just Works™ - Sensible defaults for everything
  • ✅ Fast - Native when possible, containerized when needed
  • ✅ Smart - Detects and suggests solutions automatically
  • ✅ Transparent - Shows exactly what it's doing
  • ✅ Flexible - Override any behavior when needed

🆚 Comparison

Feature xcargo cross cargo-zigbuild Manual
Native builds ✅ First ❌ ⚠️ Via Zig ✅
Container fallback ✅ ✅ ❌ ❌
No Docker required ✅ youki ❌ ✅ ✅
Auto-setup ✅ ❌ ⚠️ ❌
Native deps ✅ Planned ⚠️ ❌ ⚠️
CI/CD templates ✅ Planned ⚠️ ❌ ❌

🤝 Contributing

Contributions welcome! This project is in early stages.

How to help:

  • 🐛 Report issues or suggest features
  • 💻 Submit PRs for bug fixes or features
  • 📝 Improve documentation
  • 🎯 Test on different platforms
  • 🔧 Add support for new targets

📝 License

MIT

🙏 Acknowledgments

Inspired by:

  • cross - Container-based cross-compilation
  • cargo-zigbuild - Zig linker approach
  • xwin - Windows SDK management
  • youki - Container runtime in Rust

xcargo - Cross-compilation, zero friction 🎯

Status: 🚧 Pre-alpha - Architecture planning

Star ⭐ this repo to follow development!