.cargo | ||
.github | ||
.vscode | ||
examples | ||
link_scripts | ||
src | ||
.gitignore | ||
Cargo.toml | ||
CHANGELOG.md | ||
dump.bat | ||
dump.sh | ||
README.md | ||
rustfmt.toml |
gba
Docs.rs Documentation
How To Make Your Own GBA Project Using This Crate
This will require the use of Nightly Rust. Any recent-ish version of Nightly should be fine.
Get ARM Binutils
You'll need the ARM version of the GNU binutils in your path, specifically the linker (arm-none-eabi-ld
).
Linux folks can use the package manager. Mac and Windows folks can use the ARM Website.
Run rustup component add rust-src
This makes rustup keep the standard library source code on hand, which is necessary for build-std
to work.
Create .cargo/config.toml
You should set up your project's cargo config like so:
[build]
target = "thumbv4t-none-eabi"
[unstable]
build-std = ["core"]
[target.thumbv4t-none-eabi]
runner = "mgba-qt"
rustflags = ["-Clink-arg=-Tlink_scripts/mono_boot.ld"]
This sets the default build target to be thumbv4t-none-eabi
using the unstable build-std
cargo feature.
Also, this sets cargo run
to run the binary as an argument to mgba-qt
.
If you're on windows then your copy of mGBA will be called "mgba.exe" instead.
Also, this sets mono_boot.ld as the linker script. You'll need to copy this into your project. If you save it to another location, adjust the path accordingly.
Make Your Executables
At this point you can make a bin
or an example
.
Every executable will need to be no_std
and no_main
.
Place these at the top of the file:
#![no_std]
#![no_main]
Every executable will need a panic handler defined, even if your code can't actually panic. A minimal panic handler looks like this:
#[panic_handler]
fn panic_handler(_: &core::panic::PanicInfo) -> ! {
loop {}
}
Every executable will need a main
function defined.
We used the no_main
attribute on the executable so that Rust will allow us to use a non-standard function signature:
#[no_mangle]
extern "C" fn main() -> ! {
loop {}
}
Optional: Use objcopy
and gbafix
The cargo build
will produce ELF files, which mGBA can run directly.
If you want to run your program on real hardware you'll need to:
objcopy
the raw binary out of the ELF into its own file.- Use
gbafix
to give the file appropriate header data to that file.
You can get gbafix
through cargo: cargo install gbafix
.
Other GBA Crates
This crate provides a largely "unmanaged" interaction with the GBA's hardware. If you would like an API that use the borrow checker to guide you more, the agb crate might be what you want.