xcargo

Crates.io	xcargo
lib.rs	xcargo
version	0.1.0
created_at	2025-11-18 23:18:01.807722+00
updated_at	2025-11-19 00:34:45.473874+00
description	Cross-compilation, zero friction - Rust cross-compilation tool with automatic toolchain management
homepage	https://ibrahimcesar.github.io/xcargo
repository	https://github.com/ibrahimcesar/xcargo
max_upload_size
id	1939118
size	178,738

Ibrahim Cesar (ibrahimcesar)

documentation

https://docs.rs/xcargo

README

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!

Commit count: 0