cross-valgrind

Drop-in replacement images for cross with Valgrind installed.

This repository is an image-focused fork of cross-rs/cross for a subset of cross targets which Valgrind supports. For most users, the recommended setup is still the upstream cross CLI with image overrides pointing at images built from this repository.

This project is in an alpha development stage. The version number is based on the valgrind version inside the image and doesn't reflect the development progress.

Goals

• Provide drop-in replacement images for targets which are supported by Valgrind
• Make Valgrind available for cross-target execution.
• Modernize important tool versions in the image stack.

Non-Goals

• This repository is not about changing the cross user experience or extending the upstream cross binary.
• Become a general-purpose fork of cross with divergent behavior.
• Track every upstream image or binary change immediately.
• Replace the upstream documentation for normal cross usage.

What Is Different From Upstream

• Recent Debian-based images (>=Bookworm) instead of Ubuntu-based images (>=20.04)
• Valgrind included in the image stack (which results in bigger image sizes)
• newer QEMU, more recent Linux kernel
• a qemu-system execution path that can run the target binary under Valgrind

Choosing Images

There are two practical ways to use images from this repository:

• override a specific target in Cross.toml
• override a specific target with CROSS_TARGET_<TRIPLE>_IMAGE

CROSS_IMAGE is not recommended as a general user setup path in this fork. This repository uses image tags that do not reliably line up with the binary's built-in default image version.

Valgrind uses the qemu-system runner. The runner can be configured explicitly per target:

[target.aarch64-unknown-linux-gnu]
runner = "qemu-system"

export CROSS_TARGET_AARCH64_UNKNOWN_LINUX_GNU_RUNNER=qemu-system

When CROSS_VALGRIND is present inside the container, cross-valgrind selects qemu-system automatically. With the cross CLI, configure CROSS_VALGRIND through Cross.toml passthrough.

Quick Start

Install the normal cross CLI first:

cargo install cross

Then point your targets at images built from this repository.

Option 1: Cross.toml

[target.aarch64-unknown-linux-gnu]
image = "ghcr.io/gungraun/aarch64-unknown-linux-gnu:latest"

[target.aarch64-unknown-linux-gnu.env]
passthrough = [
    "CROSS_VALGRIND=valgrind --tool=memcheck",
]

and run cross:

cross test --target aarch64-unknown-linux-gnu

Option 2: Environment Variables

export CROSS_TARGET_AARCH64_UNKNOWN_LINUX_GNU_IMAGE="ghcr.io/gungraun/aarch64-unknown-linux-gnu:latest"
export CROSS_VALGRIND='valgrind --tool=memcheck'

Then configure CROSS_VALGRIND passthrough in Cross.toml

[target.aarch64-unknown-linux-gnu.env]
passthrough = ["CROSS_VALGRIND"]

and use cross as usual:

cross test --target aarch64-unknown-linux-gnu

Using Valgrind

Valgrind support uses qemu-system. The qemu-user runner is not supported for Valgrind execution. If CROSS_VALGRIND is set inside the container and no runner is configured, cross-valgrind selects qemu-system automatically.

You must set CROSS_VALGRIND to the Valgrind command and arguments that should run inside the guest system. Specify it in Cross.toml target.<triple>.env.passthrough so it is forwarded into the container.

A working Cross.toml example looks like this:

[target.aarch64-unknown-linux-gnu]
image = "ghcr.io/gungraun/aarch64-unknown-linux-gnu:latest"

[target.aarch64-unknown-linux-gnu.env]
passthrough = [
    "CROSS_VALGRIND=valgrind --tool=memcheck",
]

Set CROSS_VALGRIND to a specific value when you want to store the Valgrind command in Cross.toml instead of using the shell environment. Then run cross:

cross run --target aarch64-unknown-linux-gnu

Image Tags

This repository publishes a small set of tags.

• main: image built from the main branch
• edge: additional branch-build tag as produced by the current tagging logic
• latest: most recent stable image release
• 3.27.1-alpha.0: image release tag derived from the git tags v3.27.1-alpha.0

Examples:

ghcr.io/gungraun/aarch64-unknown-linux-gnu:main
ghcr.io/gungraun/aarch64-unknown-linux-gnu:edge
ghcr.io/gungraun/aarch64-unknown-linux-gnu:latest
ghcr.io/gungraun/aarch64-unknown-linux-gnu:3.27.1-alpha.0

Supported Targets

This repository only provides a stripped-down set of images compared to upstream cross.

Target
x86_64-unknown-linux-gnu
i686-unknown-linux-gnu
aarch64-unknown-linux-gnu
armv7-unknown-linux-gnueabihf
mipsel-unknown-linux-gnu
mips64el-unknown-linux-gnuabi64
powerpc-unknown-linux-gnu
powerpc64-unknown-linux-gnu
powerpc64le-unknown-linux-gnu
riscv64gc-unknown-linux-gnu
s390x-unknown-linux-gnu

Validation

This repository runs the original CI tests and an additional Valgrind smoke test.

Contributing

Contributions are welcome if they align with the scope of this fork.

Changes whose main purpose is to improve the general cross CLI are usually better proposed upstream.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Upstream

Upstream project: cross-rs/cross