Rust GBA 库 0.11.5 中文文档

Crate gba 0.11.5 中文文档

原文：https://docs.rs/gba/latest/gba/

版本 0.11.5

一个 GBA 开发的 crate 包。

如何使用这个包创建你自己的 GBA 项目

一个前提是你需要使用 Nightly Rust，近期的一些 Nightly 版本就行。

将 Rust 改成 Nightly 版本

1. 切换成 Nightly 版本

以下命令可以让 Rust 切成 Nightly 版本

rustup default nightly

2. 切回默认的稳定版本

rustup default stable

获得 ARM 的二进制工具集（Binutils）

你需要在你的 PATH 全局变量处获得 一个 ARM 版本的 GNU 二进制工具集（Binutils），具体地说是 ARM 版本的 链接器（arm-none-eabild）。Linux 的诸多分支版本可以从各自的包管理器中获得，Mac 和 Windows 的版本可以从 ARM 官网 入手。

运行 rustup component add rust-src

rustup component add rust-src 这一步是下载 Rust 源码包，这会对我们编译适合 GBA 体质的标准库 build-std 有所帮助。

建立配置文件 .cargo/config.toml

建立配置文件 .cargo/config.toml。你得提供一个用于 cargo build 和 cargo run 的默认配置文件，配置文件如下。

[build]
target = "thumbv4t-none-eabi"

[unstable]
build-std = ["core"]

[target.thumbv4t-none-eabi]
runner = "mgba-qt"
rustflags = ["-Clink-arg=-Tlinker_scripts/mono_boot.ld"]

建立执行文件

你可以通过以下步骤创建一个 二进制 bin 文件 或者一个示例 example 文件。每个可执行文件需要添加 #![no_std] 和 #![no_main]，而且也需要一个 #[panic_handler] 和 #[no_mangle] extern "C" fn main() -> ! {} 函数，这样程序集运行时就会在自己系统完全初始化后，随后调用它们来启动你的 Rust 程序。C ABI 必须被使用，因为 Rust 自己的 ABI 并不稳定。

#![no_std]
#![no_main]

#[panic_handler]
fn panic_handler(_: &core::panic::PanicInfo) -> ! {
  loop {}
}

#[no_mangle]
extern "C" fn main() -> ! {
  loop {}
}

其它：使用 objcopy 和 gbafix

cargo build 将会处理 mGBA 可以直接运行的 ELF 文件。如果你想要将你的程序运行在实机上的话，你需要首先使用 objcopy ，将原始二进制数据放入文件中，接着使用 gbafix 给一个合适的文件头。objcopy 是你所装好的 ARM 二进制工具集（binutils）的一部分，它的名字叫做 arm-none-eabi-objcopy，而 gbafix 可以通过 cargo 获得：cargo install gbafix。

其它 GBA 相关的 Crate 包

我们的包提供了一种安全的与 GBA 交互的 API，尽管我们在某些模块如何更改以及怎么更改上存在微小的限制。如果你乐意借用检查器（Borrow Checker）对组件提供更强的 API 访问，那么 agb 这个 Crate 包可能更适合你。

安全性

所有的安全注意事项都会假定你在构建编译目标，或者使用提供的链接器脚本，以及在GBA上运行代码。当然你可以无视一些安全事项，但是可能会让你的代码不够稳健。

你可以使用它们来修改它们。

thumbv4t-none-eabi 和 armv4t-none-eabi。

模块

asm_runtime 这个模块会承载了程序集运行时以支持你的 Rust 程序
bios GBA 的 BIOS 提供了有限的内建工具函数
buildin_art 这个模块提供了一些基础的素材
dma 这个模块与 GBA 的 内存访问单元对接
fixed 无
gba_cell GBA 独特的 cell 类型，提供了全局安全可变数据的支持
interrupts 无
keys 与设备的按钮和输入相关
mem_fns 直接和内存操作有关
mgba 让你允许使用 mGBA 进行 debug
mmio 包括 GBA 组件中 所有 MMIO 地址的定义
prelude 只是一个将其它所有 Crate 模块重新导出的模块
random 无
sound 无
timers 与 GBA 的四个定时器单元对接的模块
video 控制 GBA 的屏幕

宏

include_aligned_bytes 类似 include_bytes!，但是值被封装成了 Align4

结构体

Align4 将值以四个字节作为内存布局进行对齐的结构

译者：fanbal