amiga-sys 0.0.3

Rust FFI bindings for the Amiga (m68k) system libraries
Documentation
  • Coverage
  • 9.11%
    1186 out of 13018 items documented0 out of 1 items with examples
  • Size
  • Source code size: 1.84 MB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 70.97 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 12s Average build duration of successful builds.
  • all releases: 52s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • retrokp/amiga-sys
    2 0 2
  • crates.io
  • Dependencies
    • —
  • Versions
  • Owners
  • retrokp

amiga-sys

Unofficial unsafe bindings for the Amiga (m68k) system libraries.

Tested on rustc 1.99.0-nightly (87e5904f5 2026-07-20) and cargo 1.99.0-nightly (3efb1f477 2026-07-17).

Note: if you want to build high performance games or demos, have a look at amiga-rust.

WARNING: this is an experimental crate built on top of experimental Rust m68k toolchain

It is likely that Rust programs developed for Amiga will crash or simply refuse to compile, because many pieces are still missing:

  • the LLVM compiler has only experimental support for m68k: it may produce invalid code or crash during compilation because of many LLVM bugs for m68k
  • there's many Rust bugs for m68k
  • this crate isn't well tested: it may have bugs and corrupt memory

If you still want to try this out, then read on..

Features

  • direct unsafe bindings to the Amiga system libraries (based on Amiga NDK 3.2R4)
  • includes almost all definitions from NDK for Kickstart 1.0 (V30) to 3.2 (V47)
  • the bindings are unsafe: it is very easy to write a program which crashes
  • no dependency to the Amiga Native Development Kit (NDK): no dependency to the NDK headers or amiga.lib (note: these bindings have been generated from some of the NDK headers)
  • supports no_std (no dependency to std or alloc)
  • only cross-compiling for Amiga (no building on Amiga)
  • extra feature: a lazy developer who doesn't respond quickly to issues or pull requests

Not supported

  • no start up code to handle launching programs from Workbench
  • no functions with variadic arguments: there's always a similar function available without variadic arguments (the replacement function's name usually ends with Args, List or A)
  • no amiga.lib functions: BeginIO(), CreatePort(), CreateTask(), NewList(), TimeDelay(), etc. These are implemented in amiga-support.
  • no alib_stdio: functions duplicating libc functionality: printf(), fgetc(), etc.
  • no debug.lib or ddebug.lib functions: KGetChar(), KPrintF(), DGetChar(), DPrintF(), etc.
  • no direct access to hardware
  • no third-party libraries or devices
  • no support for AmigaOS 4.0 or other derivatives, PowerPC or other non-m68k Amiga versions

Special cases

  • callbacks called by the Amiga libraries have their arguments stored in CPU registers and should return a value in the CPU register d0. It's up to the callback function to use assembly code to access the register values. For an example, see the tester example test_rawdofmt().
  • FileInfoBlock and InfoData should be aligned to 4 bytes, but they don't have alignment modifiers, because it would change the size of AnchorPath and AChain. Proper alignment can be achieved by wrapping FileInfoBlock and InfoData: #[repr(C, align(4))] pub struct AlignedFileInfoBlock { data: FileInfoBlock }

Generating the bindings

The crate includes pregenerated bindings. If someone wants to regenerate them, follow these steps. These steps have been tested with nightly-2026-07-20.

Building the examples

These steps have been tested on Ubuntu 24.04 LTS.

Prerequisites:

  • Rust nightly: rustup install nightly and rustup component add rust-src.
  • the m68k-linux-gnu-ld linker for m68k-unknown-none-elf (qemu-user-static isn't needed)
  • elf2hunk

Building:

cd examples/hello-cli
cargo +nightly build --target m68k-unknown-none-elf --release
elf2hunk target/m68k-unknown-none-elf/release/hello-cli target/m68k-unknown-none-elf/release/hello-cli.exe
# Amiga executable: target/m68k-unknown-none-elf/release/hello-cli.exe

The release build is usually more successful than the debug build.

The examples have a .cargo/config.toml file to select the linker.

To build the tester example, follow the steps above by replacing hello-cli with tester.

Typical build errors

  • could not compile .. (signal: 5, SIGTRAP: trace/breakpoint trap)

Amiga string handling

Often function string parameters are null-terminated. Sometimes they are not null-terminated and the length is given as an extra parameter. Structs mostly use null-terminated strings (STRPTR). Amiga uses the ECMA-94 encoding, which is the same as ISO-8859-1 and Latin1.

Related

License

Licensed under either of Apache License, Version 2.0 or 0BSD license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.