mirror of
https://github.com/italicsjenga/gba.git
synced 2024-12-23 19:01:30 +11:00
92 lines
2.6 KiB
Markdown
92 lines
2.6 KiB
Markdown
# `gba`
|
|
|
|
# [Docs.rs Documentation](https://docs.rs/gba)
|
|
|
|
## 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](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain).
|
|
|
|
### 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:
|
|
|
|
```toml
|
|
[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](link_scripts/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:
|
|
|
|
```rust
|
|
#![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:
|
|
|
|
```rust
|
|
#[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:
|
|
|
|
```rust
|
|
#[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:
|
|
|
|
1) `objcopy` the raw binary out of the ELF into its own file.
|
|
2) 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](https://docs.rs/agb) crate might be what you want.
|