`cross`

Rust crates的"零配置"交叉编译和"交叉测试"

本项目由cross-rs团队开发和维护。之前由Rust Embedded工作组工具团队维护。欢迎新的贡献者！请加入我们的[Matrix聊天室]并打个招呼。

<img alt="为aarch64-unknown-linux-gnu目标`cross test`一个crate" src="assets/cross-test.png" title="为aarch64-unknown-linux-gnu目标`cross test`一个crate" > 为aarch64-unknown-linux-gnu目标`cross test`一个crate

特性

cross将提供交叉编译所需的所有组件，无需触及您的系统安装。
cross提供了一个环境、交叉工具链和交叉编译的库，以生成最具可移植性的二进制文件。
"交叉测试"，cross可以测试i686和x86_64以外架构的crates。
支持稳定版、测试版和每日构建版通道。

依赖

请查看我们的入门指南了解详细的安装说明。

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

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

Docker。注意，在Linux上非sudo用户需要加入docker组或使用无根Docker。阅读容器引擎安装指南了解所需的安装和安装后步骤。需要20.10版本（API 1.40）或更高。
Podman。需要3.4.0版本或更高。

安装

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

也可以直接下载预编译的发布二进制文件或使用cargo-binstall。

使用

cross的CLI与Cargo完全相同，但依赖于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

更多文档可以在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，参见 <https://github.com/cross-rs/cross/blob/main/docs/custom_images.md#adding-dependencies-to-existing-images>
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 可以为某个目标平台交叉编译"非平凡"的（二进制）crate（通常是 Cargo），则该目标平台被视为"受支持"。

测试支持（cross test）更为复杂。它依赖于 QEMU 模拟，因此测试可能会因 QEMU 的错误而失败，而不是你的 crate 中的错误。也就是说，如果一个目标平台可以运行 compiler-builtins 测试套件，则在下表的 test 列中会有一个 ✓。

此外，测试非常慢。cross test 按顺序运行单元测试，因为 QEMU 在你生成多个线程时会出现问题。这意味着，如果你的某个单元测试生成线程，那么它更有可能失败或者最坏的情况下永远不会终止。

目标	libc	GCC	C++	QEMU	`test`
`aarch64-linux-android` [1]	9.0.8	9.0.8	✓	6.1.0	✓
`aarch64-unknown-linux-gnu`	2.31	9.4.0	✓	6.1.0	✓
`aarch64-unknown-linux-gnu:centos` [7]	2.17	4.8.5		4.2.1	✓
`aarch64-unknown-linux-musl`	1.2.3	9.2.0	✓	6.1.0	✓
`arm-linux-androideabi` [1]	9.0.8	9.0.8	✓	6.1.0	✓
`arm-unknown-linux-gnueabi`	2.31	9.4.0	✓	6.1.0	✓
`arm-unknown-linux-gnueabihf`	2.31	8.5.0	✓	6.1.0	✓
`arm-unknown-linux-musleabi`	1.2.3	9.2.0	✓	6.1.0	✓
`arm-unknown-linux-musleabihf`	1.2.3	9.2.0	✓	6.1.0	✓
`armv5te-unknown-linux-gnueabi`	2.31	9.4.0	✓	6.1.0	✓
`armv5te-unknown-linux-musleabi`	1.2.3	9.2.0	✓	6.1.0	✓
`armv7-linux-androideabi` [1]	9.0.8	9.0.8	✓	6.1.0	✓
`armv7-unknown-linux-gnueabi`	2.31	9.4.0	✓	6.1.0	✓
`armv7-unknown-linux-gnueabihf`	2.31	9.4.0	✓	6.1.0	✓
`armv7-unknown-linux-musleabi`	1.2.3	9.2.0	✓	6.1.0	✓
`armv7-unknown-linux-musleabihf`	1.2.3	9.2.0	✓	6.1.0	✓
`i586-unknown-linux-gnu`	2.31	9.4.0	✓	不适用	✓
`i586-unknown-linux-musl`	1.2.3	9.2.0	✓	不适用	✓
`i686-unknown-freebsd`	1.5	6.4.0	✓	不适用
`i686-linux-android` [1]	9.0.8	9.0.8	✓	6.1.0	✓
`i686-pc-windows-gnu`	不适用	9.4	✓	不适用	✓
`i686-unknown-linux-gnu`	2.31	9.4.0	✓	6.1.0	✓
`loongarch64-unknown-linux-gnu`	2.36	14.2.0	✓	8.2.2	✓
`mips-unknown-linux-gnu`	2.30	9.4.0	✓	6.1.0	✓
`mips-unknown-linux-musl`	1.2.3	9.2.0	✓	6.1.0	✓
`mips64-unknown-linux-gnuabi64`	2.30	9.4.0	✓	6.1.0	✓
`mips64-unknown-linux-muslabi64`	1.2.3	9.2.0	✓	6.1.0	✓
`mips64el-unknown-linux-gnuabi64`	2.30	9.4.0	✓	6.1.0	✓
`mips64el-unknown-linux-muslabi64`	1.2.3	9.2.0	✓	6.1.0	✓
`mipsel-unknown-linux-gnu`	2.30	9.4.0	✓	6.1.0	✓
`mipsel-unknown-linux-musl`	1.2.3	9.2.0	✓	6.1.0	✓
`powerpc-unknown-linux-gnu`	2.31	9.4.0	✓	6.1.0	✓
`powerpc64-unknown-linux-gnu`	2.31	9.4.0	✓	6.1.0	✓
`powerpc64le-unknown-linux-gnu`	2.31	9.4.0	✓	6.1.0	✓
`riscv64gc-unknown-linux-gnu`	2.35	11.4.0	✓	8.2.2	✓
`s390x-unknown-linux-gnu`	2.31	9.4.0	✓	6.1.0	✓
`sparc64-unknown-linux-gnu`	2.31	9.4.0	✓	6.1.0	✓
`sparcv9-sun-solaris`	1.22.7	8.4.0	✓	不适用
`thumbv6m-none-eabi` [4]	3.3.0	9.2.1		不适用
`thumbv7em-none-eabi` [4]	3.3.0	9.2.1		不适用
`thumbv7em-none-eabihf` [4]	3.3.0	9.2.1		不适用
`thumbv7m-none-eabi` [4]	3.3.0	9.2.1		不适用
`thumbv7neon-linux-androideabi` [1]	9.0.8	9.0.8	✓	6.1.0	✓
`thumbv7neon-unknown-linux-gnueabihf`	2.31	9.4.0	✓	不适用	✓
`thumbv8m.base-none-eabi` [4]	3.3.0	9.2.1		不适用
`thumbv8m.main-none-eabi` [4]	3.3.0	9.2.1		不适用
`thumbv8m.main-none-eabihf` [4]	3.3.0	9.2.1		不适用
`wasm32-unknown-emscripten` [6]	3.1.14	15.0.0	✓	不适用	✓
`x86_64-linux-android` [1]	9.0.8	9.0.8	✓	6.1.0	✓
`x86_64-pc-windows-gnu`	不适用	9.3	✓	不适用	✓
`x86_64-pc-solaris`	1.22.7	8.4.0	✓	不适用
`x86_64-unknown-freebsd`	1.5	6.4.0	✓	不适用
`x86_64-unknown-dragonfly` [2] [3]	6.0.1	10.3.0	✓	不适用
`x86_64-unknown-illumos`	1.20.4	8.4.0	✓	不适用
`x86_64-unknown-linux-gnu`	2.31	9.4.0	✓	6.1.0	✓
`x86_64-unknown-linux-gnu:centos` [5]	2.17	4.8.5	✓	4.2.1	✓
`x86_64-unknown-linux-musl`	1.2.3	9.2.0	✓	不适用	✓
`x86_64-unknown-netbsd` [3]	9.2.0	9.4.0	✓	不适用

[1] libc = bionic；仅适用于原生测试，即不依赖 Android 运行时的测试。对于 i686，某些测试可能会失败，错误为 assertion failed: signal(libc::SIGPIPE, libc::SIG_IGN) != libc::SIG_ERR，详见 issue #140。

[2] 无可用的 std 组件。

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

[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 可以在 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)