diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 79eca2e3..feb79aeb 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -15,7 +15,9 @@ jobs: name: Test Suite strategy: matrix: - os: [ubuntu-latest, macos-latest, windows-latest] + # ubuntu-24.04-arm is the GitHub-hosted arm64 Linux runner; + # macos-latest already runs on Apple Silicon (arm64). + os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest, windows-latest] rust: [stable] runs-on: ${{ matrix.os }} diff --git a/README.md b/README.md index 4adc7940..865fa263 100644 --- a/README.md +++ b/README.md @@ -56,11 +56,13 @@ Arch: | | | | | :----------------------------------------: | :------------------------------------: | :-------------------------: | | :book: [Installation Guide][toc-install] | :books: [Documentation][links-table-2] | :parrot: [Discord][discord] | +| | :penguin: [ARM Support](docs/arm-support.md) | | ## 🙋 Table of Contents - 📖 [Installation Guide][toc-install] - 🐋 [Docker Usage][toc-docker-usage] +- 🐧 [ARM Support](docs/arm-support.md) - 🦜 [Discord][discord] - 🤸 [Usage][usage-1] diff --git a/docs/arm-support.md b/docs/arm-support.md new file mode 100644 index 00000000..d5616fae --- /dev/null +++ b/docs/arm-support.md @@ -0,0 +1,38 @@ +# ARM support + +This page covers which ARM targets RustScan's CI builds and tests, and how to build ARM binaries yourself. + +## What CI covers + +| Target | Built by | Tested by | +| --- | --- | --- | +| `aarch64-unknown-linux-gnu` (64-bit ARM Linux) | `build-nix` job in [build.yml](../.github/workflows/build.yml) | `Test Suite (ubuntu-24.04-arm)` in [test.yml](../.github/workflows/test.yml) | +| `armv7-unknown-linux-gnueabihf` (32-bit ARM Linux) | `build-nix` job in [build.yml](../.github/workflows/build.yml) | not tested in CI | +| `aarch64-apple-darwin` (Apple Silicon macOS) | `build-macos-aarch64` job in [build.yml](../.github/workflows/build.yml) | `Test Suite (macos-latest)` in [test.yml](../.github/workflows/test.yml) | + +- **Builds** use [`houseabsolute/actions-rust-cross`](https://github.com/houseabsolute/actions-rust-cross). It cross-compiles the Linux ARM targets with [`cross`](https://github.com/cross-rs/cross) on x86_64 runners. +- **Tests** run natively on GitHub-hosted arm64 runners: `ubuntu-24.04-arm` for Linux, and `macos-latest`, which runs on Apple Silicon. They run the same `just test` recipe as every other platform. + +## Building ARM binaries locally + +The simplest option is `cross`, which runs the build in a container that already has the right toolchain and linker. It needs Docker or Podman. + +```sh +cargo install cross +cross build --locked --release --target aarch64-unknown-linux-gnu +# or, for 32-bit ARM: +cross build --locked --release --target armv7-unknown-linux-gnueabihf +``` + +The binary ends up at `target//release/rustscan`. + +On an ARM machine (for example a Raspberry Pi running a 64-bit OS, or an Apple Silicon Mac) you don't need `cross`; a normal native build works: + +```sh +cargo build --locked --release +``` + +## Troubleshooting + +- **`error[E0463]: can't find crate for std`, or linker errors:** you're cross-compiling with plain `cargo`. Either use `cross`, or install the target (`rustup target add `) along with a matching cross linker. +- **`cross` can't pull its image:** check that Docker or Podman is running and that your user can reach it.