cross

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

本项目由 [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。有关所需的安装和安装后步骤，请阅读容器引擎 [安装指南][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 in 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。

[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的OS发行版本。

[4] libc = newlib

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

[6] libc = emscripten 且 GCC = clang

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

其他目标的额外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 行为准则][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