Skip to content

ISSUE-683: Add ARM support for GitHub Actions #868

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
herbenderbler wants to merge 2 commits into
base: master
Choose a base branch
from
Open

ISSUE-683: Add ARM support for GitHub Actions #868

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
baa5772
Added ARM support for existing GitHub Actions; added tests for this n…
herbenderbler Jan 31, 2026
35749ad
Added documentation for new ARM support
herbenderbler Jan 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 28 additions & 28 deletions .github/workflows/build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,16 +38,17 @@ jobs:
pkg_config_path: /usr/lib/x86_64-linux-gnu/pkgconfig
steps:
- uses: actions/checkout@v4
- name: Install Rust toolchain
uses: actions/setup-rust@v1
with:
rust-version: stable
targets: ${{ matrix.target }}
- name: Install cross
uses: taiki-e/install-action@cross
- name: Cache cargo & target directories
uses: Swatinem/rust-cache@v2
- name: Build binary
uses: houseabsolute/actions-rust-cross@v0
with:
command: build
target: ${{ matrix.target }}
args: "--locked --release"
strip: true
toolchain: stable
run: cross build --locked --release --target ${{ matrix.target }}
- name: Build tar.gz for homebrew installs
if: matrix.type == 'ubuntu-x64'
run: |
Expand All @@ -68,6 +69,10 @@ jobs:
IN_PIPELINE: true
steps:
- uses: actions/checkout@v4
- name: Install Rust toolchain
uses: actions/setup-rust@v1
with:
rust-version: stable
- name: Install cargo-deb
run: cargo install -f cargo-deb
- uses: awalsh128/cache-apt-pkgs-action@v1
Expand All @@ -91,16 +96,14 @@ jobs:
if: github.ref == 'refs/heads/master'
steps:
- uses: actions/checkout@v4
- name: Install Rust toolchain
uses: actions/setup-rust@v1
with:
rust-version: stable
- name: Cache cargo & target directories
uses: Swatinem/rust-cache@v2
- name: Build binary
uses: houseabsolute/actions-rust-cross@v0
with:
command: build
target: x86_64-apple-darwin
args: "--locked --release"
strip: true
toolchain: stable
run: cargo build --locked --release --target x86_64-apple-darwin
- name: Build tar.gz for homebrew installs
run: |
tar czf x86_64-macos-rustscan.tar.gz -C target/x86_64-apple-darwin/release rustscan
Expand All @@ -120,16 +123,14 @@ jobs:
if: github.ref == 'refs/heads/master'
steps:
- uses: actions/checkout@v4
- name: Install Rust toolchain
uses: actions/setup-rust@v1
with:
rust-version: stable
- name: Cache cargo & target directories
uses: Swatinem/rust-cache@v2
- name: Build binary
uses: houseabsolute/actions-rust-cross@v0
with:
command: build
target: aarch64-apple-darwin
args: "--locked --release"
strip: true
toolchain: stable
run: cargo build --locked --release --target aarch64-apple-darwin
- name: Build tar.gz for homebrew installs
run: |
tar czf aarch64-macos-rustscan.tar.gz -C target/aarch64-apple-darwin/release rustscan
Expand Down Expand Up @@ -163,16 +164,15 @@ jobs:
path: target\i686-pc-windows-msvc\release\rustscan.exe
steps:
- uses: actions/checkout@v4
- name: Install Rust toolchain
uses: actions/setup-rust@v1
with:
rust-version: stable
targets: ${{ matrix.target }}
- name: Cache cargo & target directories
uses: Swatinem/rust-cache@v2
- name: Build binary
uses: houseabsolute/actions-rust-cross@v0
with:
command: build
target: ${{ matrix.target }}
args: "--locked --release"
strip: true
toolchain: stable
run: cargo build --locked --release --target ${{ matrix.target }}
- uses: actions/upload-artifact@v4
with:
name: ${{ matrix.name }}
Expand Down
48 changes: 43 additions & 5 deletions .github/workflows/test.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,18 @@ jobs:
- name: Checkout sources
uses: actions/checkout@v4

- name: Install stable toolchain
uses: actions-rs/toolchain@v1
- name: Install Rust toolchain
uses: actions/setup-rust@v1
with:
profile: minimal
toolchain: ${{ matrix.rust }}
override: true
rust-version: ${{ matrix.rust }}

- name: Install Python
uses: actions/setup-python@v5
with:
python-version: "3.11"

- name: Install Python dependencies
run: python -m pip install --upgrade pip setuptools wheel

- uses: taiki-e/install-action@nextest
- uses: Swatinem/rust-cache@v2
Expand All @@ -32,3 +38,35 @@ jobs:

- name: Run just
run: just test

test-arm:
name: ARM Test Suite (aarch64)
runs-on: ubuntu-latest
strategy:
matrix:
target: [aarch64-unknown-linux-gnu]
steps:
- name: Checkout sources
uses: actions/checkout@v4

- name: Install Rust toolchain
uses: actions/setup-rust@v1
with:
rust-version: stable
targets: ${{ matrix.target }}

- name: Install Python
uses: actions/setup-python@v5
with:
python-version: "3.11"

- name: Install Python dependencies
run: python -m pip install --upgrade pip setuptools wheel

- name: Install cross
uses: taiki-e/install-action@cross

- uses: Swatinem/rust-cache@v2

- name: Run cross tests
run: cross test --target ${{ matrix.target }}
6 changes: 6 additions & 0 deletions Cross.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
[target.aarch64-unknown-linux-gnu]
pre-build = [
"apt-get update",
"apt-get install -y python3 python3-pip",
"python3 -m pip install --upgrade pip setuptools wheel"
]
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,11 +56,13 @@ Arch:
| <!--Installation Guide--> | <!--Documentation--> | <!--Discord--> |
| :----------------------------------------: | :------------------------------------: | :-------------------------: |
| :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]

Expand Down
90 changes: 90 additions & 0 deletions docs/arm-support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# ARM support

This document explains how RustScan's ARM support works, how to build ARM binaries locally, and how the CI pipeline validates ARM builds and tests.

## What ARM targets are supported

The CI pipeline builds and tests Linux ARM64 using the target:

- `aarch64-unknown-linux-gnu`

The build pipeline also produces additional Linux artifacts for other targets, but ARM validation focuses on aarch64 Linux.

## CI overview (GitHub Actions)

ARM support is provided via GitHub Actions using `actions/setup-rust` plus `cross` for cross-compilation. The pipeline includes:

- A build matrix that includes `aarch64-unknown-linux-gnu` for Linux builds.
- A dedicated ARM test job that runs `cross test` for the aarch64 target.
- Explicit Python installation and dependency setup for the scripting integration tests.

Key files:

- CI workflows: [.github/workflows/build.yml](../.github/workflows/build.yml) and [.github/workflows/test.yml](../.github/workflows/test.yml)
- Cross configuration: [Cross.toml](../Cross.toml)

### Why `cross`

`cross` runs builds and tests inside a container that has the right toolchain for the target. This avoids local toolchain setup and makes the aarch64 Linux build reproducible in CI.

### Python dependencies in ARM CI

RustScan’s scripting tests execute a Python script from the fixtures directory, so Python must exist in the test environment. For ARM CI, Python is installed in the cross container using the `pre-build` hooks in [Cross.toml](../Cross.toml).

## Local builds for ARM

You can build ARM binaries locally using `cross` on any host OS that supports Docker/Podman.

### 1) Install cross

```
cargo install cross
```

### 2) Build for aarch64 Linux

```
cross build --locked --release --target aarch64-unknown-linux-gnu
```

The resulting binary is located at:

```
target/aarch64-unknown-linux-gnu/release/rustscan
```

## Local tests for ARM

Run the test suite for the ARM target with:

```
cross test --target aarch64-unknown-linux-gnu
```

This runs the Rust unit and integration tests inside the aarch64 container. The Python script-based test is included and relies on the Python setup defined in [Cross.toml](../Cross.toml).

## Customizing the ARM container

If you need additional tools in the ARM container (for example, extra Python packages), update the `pre-build` list in [Cross.toml](../Cross.toml). The current configuration installs Python and basic packaging tools.

## Troubleshooting

### Python script test failures

If the `run_python_script` test fails, verify that the container has Python installed and that the script shebang is executable. In CI, this is handled by the `pre-build` steps in [Cross.toml](../Cross.toml). For local use, ensure your Docker/Podman backend is functioning and that `cross` can download the base image.

### Missing target errors

If you see target-related errors, ensure `cross` is installed and you are using the correct target triple:

- `aarch64-unknown-linux-gnu`

## FAQ

**Does this add native ARM runners?**

No. The ARM jobs run on standard GitHub-hosted runners and use `cross` to build and test aarch64 Linux in containers.

**Can I build ARM binaries without cross?**

Yes, but you’ll need to install a compatible target toolchain and linker locally. `cross` is the recommended approach because it’s consistent with CI.
8 changes: 2 additions & 6 deletions src/benchmark/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,12 +42,8 @@ impl Benchmark {
let mut summary = String::from("\nRustScan Benchmark Summary");

for timer in &self.named_timers {
if timer.start.is_some() && timer.end.is_some() {
let runtime_secs = timer
.end
.unwrap()
.saturating_duration_since(timer.start.unwrap())
.as_secs_f32();
if let (Some(start), Some(end)) = (timer.start, timer.end) {
let runtime_secs = end.saturating_duration_since(start).as_secs_f32();
summary.push_str(&format!("\n{0: <10} | {1: <10}s", timer.name, runtime_secs));
}
}
Expand Down
14 changes: 14 additions & 0 deletions tests/cross_config.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
use std::fs;

#[test]
fn cross_config_includes_aarch64_target() {
let cross_toml = fs::read_to_string("Cross.toml").expect("Cross.toml should exist");
assert!(
cross_toml.contains("[target.aarch64-unknown-linux-gnu]"),
"Cross.toml must define target.aarch64-unknown-linux-gnu"
);
assert!(
cross_toml.contains("pre-build"),
"Cross.toml must define pre-build steps for aarch64 target"
);
}