ghcr.io/cross-rs/x86_64-unknown-linux-musl:latest

cross

“零配置”的 Rust crate 交叉编译与“交叉测试”

本项目由 https://github.com/cross-rs 团队开发和维护。此前由 Rust 嵌入式工作组工具团队维护。欢迎新贡献者！请加入我们的 [Matrix 房间] 打个招呼。

为 aarch64-unknown-linux-gnu 目标对 crate 进行 cross test

特性

• cross 会提供交叉编译所需的所有组件，无需修改您的系统安装。

• cross 提供环境、交叉工具链和交叉编译库，可生成最具可移植性的二进制文件。

• “交叉测试”：cross 可以为 i686 和 x86_64 以外的架构测试 crate。

• 支持 stable、beta 和 nightly 频道。

依赖项

有关详细安装说明，请参阅我们的 入门指南。

• rustup
• 交叉测试需要支持 binfmt_misc 的 Linux 内核。

需要以下容器引擎之一。如果两者都已安装，cross 将默认使用 docker。

• Docker。注意，在 Linux 上，非 sudo 用户需要加入 docker 用户组或使用 rootless docker。有关所需的安装和安装后步骤，请阅读容器引擎 https://github.com/cross-rs/cross/wiki/Getting-Started#installing-a-container-engine。需要 20.10 版本（API 1.40）或更高版本。
• Podman。需要 3.4.0 版本或更高版本。

安装

cargo install cross --git https://github.com/cross-rs/cross

也可以直接下载预编译的 https://github.com/cross-rs/cross/releases 或使用 https://github.com/cargo-bins/cargo-binstall%E3%80%82

使用

cross 拥有与 https://github.com/rust-lang/cargo 完全相同的 CLI，但依赖于 Docker 或 Podman。对于 Docker，您需要先启动守护进程才能使用它。

# （每次启动时，在 Linux 上）
# 如果 Docker 守护进程尚未运行，使用 systemd 启动它
# 在 WSL2 和其他使用 SysVinit 的系统上，使用 `sudo service docker start`。
$ sudo systemctl start docker

# 神奇！这能直接工作
$ cross build --target aarch64-unknown-linux-gnu

# 更神奇！这也能直接工作
$ cross test --target mips64-unknown-linux-gnuabi64

# 显然，这同样能直接工作
$ cross rustc --target powerpc-unknown-linux-gnu --release -- -C lto

更多文档可在 https://github.com/cross-rs/cross/wiki 或 docs/ 子文件夹中找到。

配置

配置 cross 行为

您有四种配置 cross 的选项。所有这些选项都使用 TOML 格式进行配置，可能的配置值记录在 此处。

选项 1：直接在 Cargo.toml 中配置 cross

您可以直接在 Cargo.toml 文件的 [workspace.metadata.cross] 表（即键前缀）下设置 配置值。示例配置片段如下：

[workspace.metadata.cross.target.aarch64-unknown-linux-gnu]
# 安装 libssl-dev:arm64，参见
pre-build = [
"dpkg --add-architecture $CROSS_DEB_ARCH",
"apt-get update && apt-get --assume-yes install libssl-dev:$CROSS_DEB_ARCH"
]
[workspace.metadata.cross.target.armv7-unknown-linux-gnueabi]
image = "my/image:latest"
[workspace.metadata.cross.build]
env.volumes = ["A_DIRECTORY=/path/to/volume"]

选项 2：通过 Cross.toml 文件配置 cross

您可以将 配置 放在项目根目录下的 Cross.toml 文件中。

选项 3：使用 CROSS_CONFIG 指定配置文件位置

通过设置 CROSS_CONFIG 环境变量，您可以告诉 cross 应该在哪里搜索配置文件。这样您就不限于项目根目录下的 Cross.toml 文件。

选项 4：通过环境变量配置 cross

除了基于 TOML 的配置文件外，配置也可以通过 环境变量 传递。

Docker 中的 Docker

从容器内部运行 cross 时，cross 需要访问主机的 Docker 守护进程。这通常通过挂载 Docker 守护进程套接字 /var/run/docker.sock 来实现。例如：

$ docker run -v /var/run/docker.sock:/var/run/docker.sock -v .:/project \
-w /project my/development-image:tag cross build --target mips64-unknown-linux-gnuabi64

运行 cross 的镜像需要安装 Rust 开发工具。

通过此设置，cross 必须找到并将正确的主机路径挂载到用于交叉编译的容器中。这包括原始项目目录以及父容器的根路径，以提供对 Rust 构建工具的访问。

要告知 cross 它正在容器内运行，请设置 CROSS_CONTAINER_IN_CONTAINER=true。

可以这样创建开发或 CI 容器：

FROM rust:1

# 设置 CROSS_CONTAINER_IN_CONTAINER 以告知 `cross` 它在容器内执行
ENV CROSS_CONTAINER_IN_CONTAINER=true

# 安装 `cross`
RUN cargo install cross

...

限制：目前仅 overlayfs2 存储驱动程序支持查找容器根目录的挂载点。为了访问父容器的 Rust 设置，子容器会挂载父容器的 overlayfs。父容器不得在子容器之前停止，因为如果子容器仍在访问 overlayfs，Docker 将无法正确卸载它。

显式选择容器引擎

默认情况下，cross 会按顺序尝试使用 Docker 或 Podman。如果要显式选择容器引擎，可以使用 CROSS_CONTAINER_ENGINE 环境变量设置二进制名称（或路径）。

例如，如果您想使用 Podman，可以设置 CROSS_CONTAINER_ENGINE=podman。

支持的目标

如果 cross 可以为某个目标交叉编译“非 trivial”（二进制）crate（通常是 Cargo），则该目标被视为“受支持”。

测试支持（cross test）更为复杂。它依赖于 QEMU 仿真，因此测试失败可能是由于 QEMU 错误而非您的 crate 中的错误。也就是说，如果某个目标可以运行 https://github.com/rust-lang-nursery/compiler-builtins 测试套件，则在下表的 test 列中会有一个 ✓。

此外，测试速度非常慢。cross test 会顺序运行单元测试，因为当您生成多个线程时，QEMU 会出现问题。这意味着，如果您的某个单元测试生成线程，则它更有可能失败，或者最糟糕的是，永远不会终止。

[1] libc = bionic；仅适用于原生测试，即不依赖Android Runtime的测试。对于i686架构，部分测试可能会失败并显示错误assertion failed: signal(libc::SIGPIPE, libc::SIG_IGN) != libc::SIG_ERR，更多信息请参见https://github.com/cross-rs/cross/issues/140%E3%80%82

[2] 无可用的std组件。

[3] 对于部分*BSD和Solaris目标，libc列表示提取libc的操作系统发行版本。

[4] libc = newlib

[5] 若要使用CentOS7兼容目标，必须在Cross.toml的[target.x86_64-unknown-linux-gnu]部分中修改image = "ghcr.io/cross-rs/x86_64-unknown-linux-gnu:main-centos"。

[6] libc = emscripten 且 GCC = clang

[7] 若要使用CentOS7兼容目标，必须在Cross.toml的[target.aarch64-unknown-linux-gnu]部分中修改image = "ghcr.io/cross-rs/aarch64-unknown-linux-gnu:main-centos"。

其他目标的额外Dockerfile可在https://github.com/cross-rs/cross-toolchains%E4%B8%AD%E6%89%BE%E5%88%B0%E3%80%82%E5%85%B6%E4%B8%AD%E5%8C%85%E6%8B%ACMSVC%E5%92%8CApple Darwin目标，我们无法提供这些目标的预构建镜像。

调试

QEMU_STRACE（v0.1.9+）

使用cross run时，您可以设置QEMU_STRACE变量来获取“外部”（非x86_64）二进制文件的系统调用回溯。

$ cargo new --bin hello && cd $_

$ QEMU_STRACE=1 cross run --target aarch64-unknown-linux-gnu
9 brk(NULL) = 0x0000004000023000
9 uname(0x4000823128) = 0
(..)
9 write(1,0xa06320,14)Hello, world!
= 14
9 sigaltstack(0x4000823588,(nil)) = 0
9 munmap(0x0000004000b16000,16384) = 0
9 exit_group(0)

最低支持的Rust版本（MSRV）

本crate保证可在稳定版Rust 1.85.0及更高版本上编译。它可能也能在旧版本上编译，但这在任何新的补丁版本中都可能发生变化。

某些交叉编译目标需要更高版本的Rust，且使用Xargo需要nightly Rust工具链。

许可证

根据以下任一许可证授权：

• Apache License, Version 2.0（LICENSE-APACHE）或
• MIT License（LICENSE-MIT 或 [***]

您可以选择其中任一许可证。

贡献

除非您明确声明，否则您有意提交的任何供纳入本作品的贡献（如Apache-2.0许可证所定义）均应采用上述双重许可，无任何附加条款或条件。

行为准则

对本crate的贡献遵循Rust行为准则的条款，本crate的维护者（https://github.com/cross-rs团队）承诺会介入以维护该行为准则。