cross

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

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

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

[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)

最低支持的 Rust 版本（MSRV）

该 crate 保证可以在 Rust 1.77.2 及以上的稳定版本上编译。它可能可以在较旧的版本上编译，但这可能会在任何新的补丁版本中发生变化。

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

许可证

根据以下两种许可之一授权：

• Apache License, Version 2.0（LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0）
• MIT License（LICENSE-MIT 或 http://opensource.org/licenses/MIT）

由您选择。

贡献

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

行为准则

对该 crate 的贡献遵循 Rust 行为准则 的条款，该 crate 的维护者 cross-rs 团队承诺干预以维护该行为准则。