Cargo Imgbuild

Cargo Imgbuild is a tool designed to simplify cross-compiling Rust projects using cargo zigbuild. It automates the process of downloading root images, installing required packages, and using the prepared environment as a sysroot for your build.

Quick Start

1. Install cargo-imgbuild and cargo-zigbuild:

cargo install cargo-imgbuild
cargo install cargo-zigbuild

2. Create an Imgbuild.yaml configuration for your target architectures.
3. Build your project for a target:

cargo imgbuild --target aarch64-unknown-linux-gnu

This will automatically download the root image, install dependencies, and cross-compile your project.

Features

• Automatic download of root filesystem images.
• Installation of extra packages inside the root image.
• Integration with cargo zigbuild for easy cross-compilation.
• Support for multiple target architectures via a simple configuration file.
• Local caching to speed up repeated builds.

Configuration

cargo-imgbuild uses an Imgbuild.yaml configuration file to define build targets. Example configuration:

[build.aarch64-unknown-linux-gnu]
image = "https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2025-12-04/2025-12-04-raspios-trixie-arm64-lite.img.xz"
partition = 2
qemu = "/usr/bin/qemu-aarch64-static"
triple = "aarch64-linux-gnu"
commands = [
    "apt-get update",
    "apt-get install -y build-essential clang libclang-dev llvm-dev libssl-dev"
]

[build.arm-unknown-linux-gnueabihf]
image = "https://downloads.raspberrypi.org/raspios_lite_armhf/images/raspios_lite_armhf-2025-12-04/2025-12-04-raspios-trixie-armhf-lite.img.xz"
partition = 2
qemu = "/usr/bin/qemu-arm-static"
triple = "arm-linux-gnueabihf"
commands = [
    "apt-get update",
    "apt-get install -y build-essential clang libclang-dev llvm-dev libssl-dev"
]

[global]
cache_dir = "~/.cache/cargo-imgbuild"

Configuration Fields

• image: URL of the root filesystem image to use.
• partition: Partition number containing the root filesystem.
• qemu: Path to the QEMU static binary for the target architecture.
• triple: Compiler target triple (used by cargo zigbuild).
• commands: Shell commands to install additional packages inside the image.
• cache_dir (global): Directory to cache downloaded images and build artifacts.

Usage

Once your Imgbuild.yaml is configured, you can build a binary for a specific target like this:

cargo imgbuild --target aarch64-unknown-linux-gnu

This will:

1. Download the specified image if it’s not already cached.
2. Mount the image and run the listed commands to install dependencies.
3. Use the prepared sysroot to cross-compile your project with cargo zigbuild.

You can repeat this for multiple targets by changing the --target option.

Example

To build for ARMv7:

cargo imgbuild --target arm-unknown-linux-gnueabihf

To build for ARM64:

cargo imgbuild --target aarch64-unknown-linux-gnu

License

This project is licensed under the MIT License.