ghcr.io/cross-rs/x86_64-pc-windows-gnu:main

cross

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

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

为 aarch64-unknown-linux-gnu 目标交叉测试 crate

功能特性

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

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

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

• 支持 stable、beta 和 nightly 通道。

依赖项

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

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

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

• [Docker]。注意，在 Linux 上，非 sudo 用户需要加入 docker 用户组或使用 rootless docker。有关必要的安装和安装后步骤，请阅读容器引擎 [安装指南][docker_install]。需要 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 格式进行配置，可能的配置值记录在 [此处][config_file]。

方式 1：直接在 Cargo.toml 中配置 cross

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

[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

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

方式 3：使用 CROSS_CONFIG 指定配置文件位置

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

方式 4：通过环境变量配置 cross

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

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 在生成多个线程时会出现问题。这意味着，如果你的某个单元测试生成线程，则更有可能失败，甚至 worst 情况下永远不会终止。

[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 中找到。其中包括 MSVC 和 Apple 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 许可证 2.0（LICENSE-APACHE 或
• MIT 许可证（LICENSE-MIT 或 [***]

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

贡献

除非您明确声明，否则您有意提交用于包含在本作品中的任何贡献，如 Apache-2.0 许可证所定义，应按上述方式双重许可，无任何附加条款或条件。

行为准则

对本 crate 的贡献遵循 [Rust 行为准则][CoC] 的条款，本 crate 的维护者（[cross-rs] 团队）承诺会介入以维护该行为准则。

[CoC]：CODE_OF_CONDUCT.md
[cross-rs]：https://github.com/cross-rs
[Docker]：[]
[Podman]：[]
[Matrix room]：[]
[docker_install]：https://github.com/cross-rs/cross/wiki/Getting-Started#installing-a-container-engine
[binfmt_misc]：[]
[config_file]：./docs/config_file.md
[docs_env_vars]：./docs/environment_variables.md