2022-09-28 02:40:05 +10:00
# `gba`
2021-03-02 02:36:39 +11:00
2022-09-28 02:45:05 +10:00
# [Docs.rs Documentation](https://docs.rs/gba)
2018-11-19 07:09:23 +11:00
2022-09-28 02:40:05 +10:00
## How To Make Your Own GBA Project Using This Crate
2018-11-14 06:47:52 +11:00
2022-09-28 02:40:05 +10:00
This will require the use of Nightly Rust. Any recent-ish version of Nightly should be fine.
2018-11-14 06:47:52 +11:00
2022-09-28 02:40:05 +10:00
### Get ARM Binutils
2019-01-03 14:50:05 +11:00
2022-09-28 02:40:05 +10:00
You'll need the ARM version of the GNU binutils in your path, specifically the linker (`arm-none-eabi-ld`).
2021-04-09 15:57:30 +10:00
2022-09-28 02:40:05 +10:00
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 ).
2019-01-03 14:50:05 +11:00
2022-09-28 02:40:05 +10:00
### Run `rustup component add rust-src`
2021-02-21 05:49:40 +11:00
2022-09-28 02:40:05 +10:00
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"
2021-02-21 05:49:40 +11:00
2022-09-28 02:40:05 +10:00
[unstable]
build-std = ["core"]
[target.thumbv4t-none-eabi]
runner = "mgba-qt"
rustflags = ["-Clink-arg=-Tlink_scripts/mono_boot.ld"]
2021-04-06 10:11:42 +10:00
```
2021-02-21 05:49:40 +11:00
2022-09-28 02:40:05 +10:00
This sets the default build target to be `thumbv4t-none-eabi` using the unstable `build-std` cargo feature.
2018-11-14 06:47:52 +11:00
2022-09-28 02:40:05 +10:00
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.
2018-11-14 06:47:52 +11:00
2022-09-28 02:40:05 +10:00
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.
2018-11-19 02:25:32 +11:00
2022-09-28 02:40:05 +10:00
### Make Your Executables
2021-04-09 15:57:30 +10:00
2022-09-28 02:40:05 +10:00
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]
2021-04-09 15:57:30 +10:00
```
2022-09-28 02:40:05 +10:00
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 {}
}
2021-04-09 15:57:30 +10:00
```
2022-09-28 02:40:05 +10:00
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 {}
}
2018-11-19 02:25:32 +11:00
```
2022-09-28 02:40:05 +10:00
### 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
2018-11-14 06:47:52 +11:00
2022-09-28 02:40:05 +10:00
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.