Updated 2026-11-04: shared Rust/std work for x86_64 ABIv1, x86_64 ABIv11 and AArch64 ABIv1 is now consolidated on main, including the libc ABI fixes and HOME-only home_dir used by Helix aros3. See current status and limitations and the build and acceptance procedure.
QEMU results exist for both CPU families; physical Raspberry Pi acceptance remains open. The separate stock-compiler/mainline integration is included as an explicitly runtime-UNTESTED profile, not a replacement for the application toolchain. Source availability is not native qualification of every profile or reproducibility of the older installed v11 sysroot.
Write AROS programs in Rust. This package contains everything needed to build a Rust program on a PC or Mac and run it on AROS x86_64: a target definition, a small runtime crate, a project template, a graphical example, and a helper that deploys straight into a running AROS machine.
Two ways to use it. The no_std path (the runtime crate, template and
example below) is the stable one: core and alloc, no_std crates from
crates.io, and the AROS API through extern "C".
There is also an experimental std: with the aros-nightly toolchain that
std-groundwork/std-patch/make-std-toolchain.sh creates, an ordinary Rust
program — std::fs, std::thread, std::net, std::process, HashMap — and
crates such as serde, serde_json and anyhow straight from crates.io
build and run on AROS. ripgrep 14.1.1 builds and searches AROS directories with it, and tokio's
runtime, tasks, channels and timers work (async networking does not: mio
has no AROS selector). See std-groundwork/realworld/. Known gaps — bare
program names in Command, version-specific randomness backends, poll on sockets
only, emulated mmap — are listed in std-groundwork/std-patch/README.md. See Limitations below before you
plan a project around either path.
Verified on AROS One 1.3 (x86_64) under QEMU:
coreandalloc— iterators,core::fmt,Vec,String,BTreeMap- crates from crates.io that support
no_std— tested withlibmandhashbrown - floating point and 128-bit arithmetic, including the division behind decimal formatting
- calling the AROS API directly:
PutStr,Delay,AllocMem/FreeMem - calling the C library from the SDK, including varargs functions
- SDL2: the included example opens a window and animates a 320x200 plasma at 226 fps inside emulation, without hardware acceleration
- An AROS x86_64 SDK and cross toolchain (
x86_64-aros-gcc). - The tested Rust nightly with the sources:
rustup toolchain install nightly-2026-09-01 --profile minimal --component rust-srcNightly is required because custom target files and-Z build-stdare not stable features.
./setup.sh # finds your toolchain, writes x86_64-aros.json
cd template
cargo +nightly-2026-09-01 build --releasesetup.sh looks for x86_64-aros-gcc on your PATH and for the SDK beside
it. If it guesses wrong, tell it:
AROS_GCC=/path/to/x86_64-aros-gcc AROS_SDK=/path/to/sdk ./setup.shFor a compiler wrapper or a non-GCC driver, also set AROS_AR to the matching
archiver. setup.sh records all three paths for the C glue build scripts. For a
GCC driver, the default archiver is the same path with only its final gcc
suffix replaced by ar.
The result, target/x86_64-aros/release/hello-aros, is an ordinary AROS
executable: copy it to your AROS machine and run it from a Shell.
If you develop against AROS running in QEMU, cargo run can build, deploy and
start the program for you:
cd examples/plasma
cargo +nightly run --releaseThis uses tools/aros-qemu-run.py, which publishes the binary on a small ISO,
swaps it into the machine's CD drive and types the command into an open Shell.
It needs QEMU started with a monitor socket, a QMP socket and a CD drive:
-monitor unix:/tmp/aros-monitor.sock,server,nowait
-qmp unix:/tmp/aros-qmp.sock,server,nowait
-drive if=ide,index=2,media=cdrom
and an AmigaShell window open and focused in the guest.
One trap worth knowing if you copy .cargo/config.toml into a project of your
own: include is resolved relative to the .cargo/ directory, while
build.target and runner are resolved relative to the directory you run
cargo from. They therefore need different numbers of ../. Socket paths, the
drive id and the volume name can be overridden with environment variables;
see the top of the script. It needs nothing but Python 3 and an ISO builder
(hdiutil, xorriso, genisoimage or mkisofs).
The result comes back as a screenshot rather than as text: AROS gives no way
to send output back to the host. Writing to a QEMU vvfat drive from inside the
guest looks like it works and silently produces a corrupt file, and SER:
never reaches QEMU's serial file, so neither is a usable channel.
| Path | What it is |
|---|---|
setup.sh |
Detects your toolchain and writes the target definition. |
x86_64-aros.json.in |
Target definition template; see TARGET-NOTES.md. |
limpet/ |
Presentation capabilities, colours, titles and output for std/no_std. |
aros/ |
The runtime crate: allocator, println!, panic handler, bindings. |
template/ |
A minimal project to copy for your own program. |
examples/plasma/ |
A graphical SDL2 example. |
tools/aros-qemu-run.py |
cargo run helper for a QEMU-hosted AROS. |
std-groundwork/ |
Work towards a real std: libc bindings and their tests. |
#![no_std]
#![no_main]
extern crate alloc;
use aros::{aros_main, println};
fn run() {
println!("hello from Rust on AROS");
}
aros_main!(run);The SDK's C startup still runs the process; aros_main! exposes your function
to it. The aros crate installs the allocator and the panic handler, so
nothing else is needed.
Memory from exec.library comes with its pairing rule enforced by the compiler:
let mut buf = aros::exec::Mem::new(1024).unwrap();
buf[0] = 42;
// FreeMem happens on drop, with the size it was allocated withstdis experimental. Existing evidence covers the examples, ripgrep and Tokio's runtime/timers, not every API or crate. Async networking remains open. Seedocs/current-state.mdfor platform scope and fresh checks.- Nightly only, and nightly moves; a future release may need the target file adjusted.
- Safety stops at the API boundary. Calls into AROS are
unsafeFFI like any other C interface, and AROS shares one address space between all tasks. Rust protects the logic you write, not the system you call. panic = abort. There is no unwinder, so a panic prints and exits.- Do not
stripthe executable. A full strip leaves an AROS binary whose relocations the loader silently skips, and it crashes beforemain. Use--strip-unneeded --remove-section .commentif you must; the saving is small because the relocations need the symbols. - Console encoding depends on the handler. Stock CON: and UTF-8-capable
Limpet differ. See
limpet/for capability-aware output. - Binaries are larger than the C equivalent, and they cannot be fully stripped, so expect a few hundred kilobytes for a small program.
std-groundwork/ contains a patched std for AROS and the libc crate it
stands on. With the aros-nightly toolchain that std-patch/make-std-toolchain.sh
creates, an ordinary Rust program — std::fs, std::thread, std::net,
std::process, HashMap, and crates such as serde and anyhow straight
from crates.io — builds and runs on AROS. See std-groundwork/std-patch/README.md
for setup and the list of known gaps. The no_std path described above
remains the simpler, more robust option for now.
Current renewal work prioritizes x86_64 ABIv11, with ABIv1 next and hosted
arm64 Macaros in scope. See docs/current-state.md for completed entropy and
Limpet presentation checks and their platform limits. Next application-facing
work includes terminal input, process/pipe behaviour for language servers and
async networking driven by pinned real consumers. Zed is the reference workload;
a complete Zed port is not delivered by these building blocks.
James Knipping ported the Zed editor and the ferail file manager to AROS aarch64, which is what showed that Rust on AROS was possible at all; those run under Macaros, AROS hosted on Apple Silicon. His Rust PAL is public at jonx/rust-aros. The original x86_64 package was developed independently; the common sysroot now imports his ARM implementation with explicit CPU, ABI and SDK profiles.
MIT — see LICENSE.
