{"id":13487016,"url":"https://github.com/cross-rs/cross","last_synced_at":"2025-05-13T11:08:32.674Z","repository":{"id":36992804,"uuid":"77338532","full_name":"cross-rs/cross","owner":"cross-rs","description":"“Zero setup” cross compilation and “cross testing” of Rust crates","archived":false,"fork":false,"pushed_at":"2025-04-28T13:34:32.000Z","size":3411,"stargazers_count":7323,"open_issues_count":221,"forks_count":407,"subscribers_count":51,"default_branch":"main","last_synced_at":"2025-05-13T11:08:18.987Z","etag":null,"topics":["aarch64","arm","bsd","cargo","cross-compilation","cross-testing","linux","mips","powerpc","rust","s390x","sparc","windows","x86"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cross-rs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-12-25T18:48:10.000Z","updated_at":"2025-05-13T10:07:15.000Z","dependencies_parsed_at":"2023-10-11T20:53:02.430Z","dependency_job_id":"32ffbd5c-0e0b-40df-92f8-366502da6b51","html_url":"https://github.com/cross-rs/cross","commit_stats":{"total_commits":1104,"total_committers":100,"mean_commits":11.04,"dds":0.8007246376811594,"last_synced_commit":"6982b6c8f97b9db56bc6e005427d2367bb39a93f"},"previous_names":["rust-embedded/cross"],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cross-rs%2Fcross","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cross-rs%2Fcross/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cross-rs%2Fcross/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cross-rs%2Fcross/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cross-rs","download_url":"https://codeload.github.com/cross-rs/cross/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253929367,"owners_count":21985802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aarch64","arm","bsd","cargo","cross-compilation","cross-testing","linux","mips","powerpc","rust","s390x","sparc","windows","x86"],"created_at":"2024-07-31T18:00:54.350Z","updated_at":"2025-05-13T11:08:32.649Z","avatar_url":"https://github.com/cross-rs.png","language":"Rust","funding_links":[],"categories":["Rust","Rust 程序设计","linux","arm","书籍/教程/文档"],"sub_categories":["网络服务_其他"],"readme":"[![crates.io](https://img.shields.io/crates/v/cross.svg)](https://crates.io/crates/cross)\n[![crates.io](https://img.shields.io/crates/d/cross.svg)](https://crates.io/crates/cross)\n[![CI](https://github.com/cross-rs/cross/actions/workflows/ci.yml/badge.svg?query=branch%3Amain)](https://github.com/cross-rs/cross/actions/workflows/ci.yml?query=branch)\n[![Matrix](https://img.shields.io/matrix/cross-rs:matrix.org)](https://matrix.to/#/#cross-rs:matrix.org)\n\n# `cross`\n\n\u003e “Zero setup” cross compilation and “cross testing” of Rust crates\n\nThis project is developed and maintained by the [cross-rs] team.\nIt was previously maintained by the Rust Embedded Working Group Tools team.\nNew contributors are welcome! Please join our [Matrix room] and say hi.\n\n\u003cp align=\"center\"\u003e\n\u003cimg\n  alt=\"`cross test`ing a crate for the aarch64-unknown-linux-gnu target\"\n  src=\"assets/cross-test.png\"\n  title=\"`cross test`ing a crate for the aarch64-unknown-linux-gnu target\"\n\u003e\n\u003cbr\u003e\n\u003cem\u003e`cross test`ing a crate for the aarch64-unknown-linux-gnu target\u003c/em\u003e\n\u003c/p\u003e\n\n## Features\n\n- `cross` will provide all the ingredients needed for cross compilation without\n  touching your system installation.\n\n- `cross` provides an environment, cross toolchain and cross compiled libraries,\n  that produces the most portable binaries.\n\n- “cross testing”, `cross` can test crates for architectures other than i686 and\n  x86_64.\n\n- The stable, beta and nightly channels are supported.\n\n## Dependencies\n\nSee our [Getting Started](./docs/getting-started.md) guide for detailed\ninstallation instructions.\n\n- [rustup](https://rustup.rs/)\n- A Linux kernel with [binfmt_misc] support is required for cross testing.\n\nOne of these container engines is required. If both are installed, `cross` will\ndefault to `docker`.\n\n- [Docker]. Note that on Linux non-sudo users need to be in the `docker` group or use rootless docker.\n  Read the container engine [install guide][docker_install] for the required installation and post-installation steps. Requires version 20.10 (API 1.40) or later.\n- [Podman]. Requires version 3.4.0 or later.\n\n## Installation\n\n```sh\ncargo install cross --git https://github.com/cross-rs/cross\n```\n\nIt's also possible to directly download the pre-compiled [release\nbinaries](https://github.com/cross-rs/cross/releases) or use\n[cargo-binstall](https://github.com/cargo-bins/cargo-binstall).\n\n## Usage\n\n`cross` has the exact same CLI as [Cargo](https://github.com/rust-lang/cargo)\nbut relies on Docker or Podman. For Docker, you'll have to start\nthe daemon before you can use it.\n\n```\n# (ONCE PER BOOT, on Linux)\n# Start the Docker daemon, if it's not already running using systemd\n# on WSL2 and other systems using SysVinit, use `sudo service docker start`.\n$ sudo systemctl start docker\n\n# MAGIC! This Just Works\n$ cross build --target aarch64-unknown-linux-gnu\n\n# EVEN MORE MAGICAL! This also Just Works\n$ cross test --target mips64-unknown-linux-gnuabi64\n\n# Obviously, this also Just Works\n$ cross rustc --target powerpc-unknown-linux-gnu --release -- -C lto\n```\n\nAdditional documentation can be found on the\n[wiki](https://github.com/cross-rs/cross/wiki) or the `docs/` subfolder.\n\n## Configuration\n\n### Configuring cross behavior\n\nYou have four options to configure `cross`. All of these options use the TOML\nformat for configuration and the possible configuration values are documented\n[here][config_file].\n\n#### Option 1: Configuring `cross` directly in your `Cargo.toml`\n\nYou can directly set [configuration values][config_file] in your `Cargo.toml`\nfile, under the `[workspace.metadata.cross]` table, i.e. key prefix. An example\nconfig snippet would look like this:\n\n```toml,cargo\n[workspace.metadata.cross.target.aarch64-unknown-linux-gnu]\n# Install libssl-dev:arm64, see \u003chttps://github.com/cross-rs/cross/blob/main/docs/custom_images.md#adding-dependencies-to-existing-images\u003e\npre-build = [\n    \"dpkg --add-architecture $CROSS_DEB_ARCH\",\n    \"apt-get update \u0026\u0026 apt-get --assume-yes install libssl-dev:$CROSS_DEB_ARCH\"\n]\n[workspace.metadata.cross.target.armv7-unknown-linux-gnueabi]\nimage = \"my/image:latest\"\n[workspace.metadata.cross.build]\nenv.volumes = [\"A_DIRECTORY=/path/to/volume\"]\n```\n\n#### Option 2: Configuring `cross` via a `Cross.toml` file\n\nYou can put your [configuration][config_file] inside a `Cross.toml` file\nin your project root directory.\n\n#### Option 3: Using `CROSS_CONFIG` to specify the location of your configuration\n\nBy setting the `CROSS_CONFIG` environment variable, you can tell `cross` where\nit should search for the config file. This way you are not limited to a\n`Cross.toml` file in the project root.\n\n#### Option 4: Configuring `cross` through environment variables\n\nBesides the TOML-based configuration files, config can be passed through\n[environment variables][docs_env_vars], too.\n\n\n### Docker in Docker\n\nWhen running `cross` from inside a container, `cross` needs access to\nthe hosts docker daemon itself. This is normally achieved by mounting the\ndocker daemons socket `/var/run/docker.sock`. For example:\n\n```\n$ docker run -v /var/run/docker.sock:/var/run/docker.sock -v .:/project \\\n  -w /project my/development-image:tag cross build --target mips64-unknown-linux-gnuabi64\n```\n\nThe image running `cross` requires the rust development tools to be installed.\n\nWith this setup `cross` must find and mount the correct host paths into the\ncontainer used for cross compilation. This includes the original project\ndirectory as well as the root path of the parent container to give access to\nthe rust build tools.\n\nTo inform `cross` that it is running inside a container set\n`CROSS_CONTAINER_IN_CONTAINER=true`.\n\nA development or CI container can be created like this:\n\n```\nFROM rust:1\n\n# set CROSS_CONTAINER_IN_CONTAINER to inform `cross` that it is executed from within a container\nENV CROSS_CONTAINER_IN_CONTAINER=true\n\n# install `cross`\nRUN cargo install cross\n\n...\n\n```\n\n**Limitations**: Finding the mount point for the containers root directory is\ncurrently only available for the overlayfs2 storage driver. In order to access\nthe parent containers rust setup, the child container mounts the parents\noverlayfs. The parent must not be stopped before the child container, as the\noverlayfs can not be unmounted correctly by Docker if the child container still\naccesses it.\n\n\n### Explicitly choose the container engine\n\nBy default, `cross` tries to use [Docker] or [Podman], in that order.\nIf you want to choose a container engine explicitly, you can set the\nbinary name (or path) using the `CROSS_CONTAINER_ENGINE`\nenvironment variable.\n\nFor example in case you want use [Podman], you can set `CROSS_CONTAINER_ENGINE=podman`.\n\n\n## Supported targets\n\nA target is considered as “supported” if `cross` can cross compile a\n“non-trivial” (binary) crate, usually Cargo, for that target.\n\nTesting support (`cross test`) is more complicated. It relies on [QEMU]\nemulation, so testing may fail due to QEMU bugs rather than bugs in your crate.\nThat said, a target has a ✓ in `test` column of the table below if it can run\nthe [`compiler-builtins`] test suite.\n\n[QEMU]: https://www.qemu.org/\n[`compiler-builtins`]: https://github.com/rust-lang-nursery/compiler-builtins\n\nAlso, testing is very slow. `cross test` runs units tests *sequentially* because\nQEMU gets upset when you spawn multiple threads. This means that, if one of your\nunit tests spawns threads, then it's more likely to fail or, worst, never\nterminate.\n\n| Target                                 |  libc  |  GCC   | C++ | QEMU  | `test` |\n|----------------------------------------|-------:|-------:|:---:|------:|:------:|\n| `aarch64-linux-android` [1]            | 9.0.8  | 9.0.8  | ✓   | 6.1.0 |   ✓    |\n| `aarch64-unknown-linux-gnu`            | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `aarch64-unknown-linux-gnu:centos` [7] | 2.17   | 4.8.5  |     | 4.2.1 |   ✓    |\n| `aarch64-unknown-linux-musl`           | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |\n| `arm-linux-androideabi` [1]            | 9.0.8  | 9.0.8  | ✓   | 6.1.0 |   ✓    |\n| `arm-unknown-linux-gnueabi`            | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `arm-unknown-linux-gnueabihf`          | 2.31   | 8.5.0  | ✓   | 6.1.0 |   ✓    |\n| `arm-unknown-linux-musleabi`           | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |\n| `arm-unknown-linux-musleabihf`         | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |\n| `armv5te-unknown-linux-gnueabi`        | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `armv5te-unknown-linux-musleabi`       | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |\n| `armv7-linux-androideabi` [1]          | 9.0.8  | 9.0.8  | ✓   | 6.1.0 |   ✓    |\n| `armv7-unknown-linux-gnueabi`          | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `armv7-unknown-linux-gnueabihf`        | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `armv7-unknown-linux-musleabi`         | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |\n| `armv7-unknown-linux-musleabihf`       | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |\n| `i586-unknown-linux-gnu`               | 2.31   | 9.4.0  | ✓   | N/A   |   ✓    |\n| `i586-unknown-linux-musl`              | 1.2.3  | 9.2.0  | ✓   | N/A   |   ✓    |\n| `i686-unknown-freebsd`                 | 1.6    | 13.3.0 | ✓   | N/A   |        |\n| `i686-linux-android` [1]               | 9.0.8  | 9.0.8  | ✓   | 6.1.0 |   ✓    |\n| `i686-pc-windows-gnu`                  | N/A    | 9.4    | ✓   | N/A   |   ✓    |\n| `i686-unknown-linux-gnu`               | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `loongarch64-unknown-linux-gnu`        | 2.36   | 14.2.0 | ✓   | 8.2.2 |   ✓    |\n| `loongarch64-unknown-linux-musl`       | 1.2.5  | 14.2.0 | ✓   | 8.2.2 |   ✓    |\n| `mips-unknown-linux-gnu`               | 2.30   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `mips-unknown-linux-musl`              | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |\n| `mips64-unknown-linux-gnuabi64`        | 2.30   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `mips64-unknown-linux-muslabi64`       | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |\n| `mips64el-unknown-linux-gnuabi64`      | 2.30   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `mips64el-unknown-linux-muslabi64`     | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |\n| `mipsel-unknown-linux-gnu`             | 2.30   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `mipsel-unknown-linux-musl`            | 1.2.3  | 9.2.0  | ✓   | 6.1.0 |   ✓    |\n| `powerpc-unknown-linux-gnu`            | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `powerpc64-unknown-linux-gnu`          | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `powerpc64le-unknown-linux-gnu`        | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `riscv64gc-unknown-linux-gnu`          | 2.35   | 11.4.0 | ✓   | 8.2.2 |   ✓    |\n| `riscv64gc-unknown-linux-musl`         | 1.2.5  | 14.2.0 | ✓   | 8.2.2 |   ✓    |\n| `s390x-unknown-linux-gnu`              | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `sparc64-unknown-linux-gnu`            | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `sparcv9-sun-solaris`                  | 1.22.7 | 8.4.0  | ✓   | N/A   |        |\n| `thumbv6m-none-eabi` [4]               | 3.3.0  | 9.2.1  |     | N/A   |        |\n| `thumbv7em-none-eabi` [4]              | 3.3.0  | 9.2.1  |     | N/A   |        |\n| `thumbv7em-none-eabihf` [4]            | 3.3.0  | 9.2.1  |     | N/A   |        |\n| `thumbv7m-none-eabi` [4]               | 3.3.0  | 9.2.1  |     | N/A   |        |\n| `thumbv7neon-linux-androideabi` [1]    | 9.0.8  | 9.0.8  | ✓   | 6.1.0 |   ✓    |\n| `thumbv7neon-unknown-linux-gnueabihf`  | 2.31   | 9.4.0  | ✓   | N/A   |   ✓    |\n| `thumbv8m.base-none-eabi` [4]          | 3.3.0  | 9.2.1  |     | N/A   |        |\n| `thumbv8m.main-none-eabi` [4]          | 3.3.0  | 9.2.1  |     | N/A   |        |\n| `thumbv8m.main-none-eabihf` [4]        | 3.3.0  | 9.2.1  |     | N/A   |        |\n| `wasm32-unknown-emscripten` [6]        | 3.1.14 | 15.0.0 | ✓   | N/A   |   ✓    |\n| `x86_64-linux-android` [1]             | 9.0.8  | 9.0.8  | ✓   | 6.1.0 |   ✓    |\n| `x86_64-pc-windows-gnu`                | N/A    | 9.3    | ✓   | N/A   |   ✓    |\n| `x86_64-pc-solaris`                    | 1.22.7 | 8.4.0  | ✓   | N/A   |        |\n| `x86_64-unknown-freebsd`               | 1.6    | 13.3.0 | ✓   | N/A   |        |\n| `x86_64-unknown-dragonfly` [2] [3]     | 6.0.1  | 10.3.0 | ✓   | N/A   |        |\n| `x86_64-unknown-illumos`               | 1.20.4 | 8.4.0  | ✓   | N/A   |        |\n| `x86_64-unknown-linux-gnu`             | 2.31   | 9.4.0  | ✓   | 6.1.0 |   ✓    |\n| `x86_64-unknown-linux-gnu:centos` [5]  | 2.17   | 4.8.5  | ✓   | 4.2.1 |   ✓    |\n| `x86_64-unknown-linux-musl`            | 1.2.3  | 9.2.0  | ✓   | N/A   |   ✓    |\n| `x86_64-unknown-netbsd` [3]            | 9.2.0  | 9.4.0  | ✓   | N/A   |        |\n\u003c!--| `asmjs-unknown-emscripten` [7]       | 3.1.14 | 15.0.0  | ✓   | N/A   |   ✓    |--\u003e\n\n[1] libc = bionic; Only works with native tests, that is, tests that do not\n    depends on the Android Runtime. For i686 some tests may fails with the\n    error `assertion failed: signal(libc::SIGPIPE, libc::SIG_IGN) !=\n    libc::SIG_ERR`, see [issue\n    #140](https://github.com/cross-rs/cross/issues/140) for more information.\n\n[2] No `std` component available.\n\n[3] For some \\*BSD and Solaris targets, the libc column indicates the OS\n    release version from which libc was extracted.\n\n[4] libc = newlib\n\n[5] Must change\n    `image = \"ghcr.io/cross-rs/x86_64-unknown-linux-gnu:main-centos\"` in\n    `Cross.toml` for `[target.x86_64-unknown-linux-gnu]` to use the\n    CentOS7-compatible target.\n\n[6] libc = emscripten and GCC = clang\n\n[7] Must change\n    `image = \"ghcr.io/cross-rs/aarch64-unknown-linux-gnu:main-centos\"` in\n    `Cross.toml` for `[target.aarch64-unknown-linux-gnu]` to use the\n    CentOS7-compatible target.\n\n\u003c!--[7] libc = emscripten and GCC = clang. The Docker images for these targets are currently not built automatically\ndue to a [compiler bug](https://github.com/rust-lang/rust/issues/98216), you will have to build them yourself for now.--\u003e\n\nAdditional Dockerfiles for other targets can be found in\n[cross-toolchains](https://github.com/cross-rs/cross-toolchains). These include\nMSVC and Apple Darwin targets, which we cannot ship pre-built images of.\n\n\n## Debugging\n\n### QEMU_STRACE (v0.1.9+)\n\nYou can set the QEMU_STRACE variable when you use `cross run` to get a backtrace\nof system calls from “foreign” (non x86_64) binaries.\n\n```\n$ cargo new --bin hello \u0026\u0026 cd $_\n\n$ QEMU_STRACE=1 cross run --target aarch64-unknown-linux-gnu\n9 brk(NULL) = 0x0000004000023000\n9 uname(0x4000823128) = 0\n(..)\n9 write(1,0xa06320,14)Hello, world!\n = 14\n9 sigaltstack(0x4000823588,(nil)) = 0\n9 munmap(0x0000004000b16000,16384) = 0\n9 exit_group(0)\n```\n\n## Minimum Supported Rust Version (MSRV)\n\nThis crate is guaranteed to compile on stable Rust 1.77.2 and up. It *might*\ncompile with older versions but that may change in any new patch release.\n\nSome cross-compilation targets require a later Rust version, and using Xargo\nrequires a nightly Rust toolchain.\n\n## License\n\nLicensed under either of\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or\n  http://www.apache.org/licenses/LICENSE-2.0)\n- MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall be\ndual licensed as above, without any additional terms or conditions.\n\n## Code of Conduct\n\nContribution to this crate is organized under the terms of the [Rust Code of\nConduct][CoC], the maintainer of this crate, the [cross-rs] team, promises\nto intervene to uphold that code of conduct.\n\n[CoC]: CODE_OF_CONDUCT.md\n[cross-rs]: https://github.com/cross-rs\n[Docker]: https://www.docker.com\n[Podman]: https://podman.io\n[Matrix room]: https://matrix.to/#/#cross-rs:matrix.org\n[docker_install]: https://github.com/cross-rs/cross/wiki/Getting-Started#installing-a-container-engine\n[binfmt_misc]: https://www.kernel.org/doc/html/latest/admin-guide/binfmt-misc.html\n[config_file]: ./docs/config_file.md\n[docs_env_vars]: ./docs/environment_variables.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcross-rs%2Fcross","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcross-rs%2Fcross","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcross-rs%2Fcross/lists"}