From 1834876cb7e2ffc64ede9da130e5acc5092f21c7 Mon Sep 17 00:00:00 2001 From: Lokathor Date: Tue, 4 Oct 2022 23:57:13 -0600 Subject: [PATCH] move readme explanation into the crate docs. --- README.md | 88 ------------------------------------------------------ src/lib.rs | 79 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index 480a675..77407f5 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,3 @@ # `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. diff --git a/src/lib.rs b/src/lib.rs index a9770b3..abcbf97 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -3,6 +3,85 @@ #![feature(asm_const)] #![feature(isa_attribute)] #![feature(naked_functions)] +#![warn(missing_docs)] + +//! A crate for GBA development. +//! +//! ## 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. +//! +//! [arm-download]: +//! https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain +//! +//! * **Get The 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][arm-download]. +//! * **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 A `.cargo/config.toml`:** You'll want to set up a file to provide +//! all the right default settings so that a basic `cargo build` and `cargo +//! run` will "just work". Something like the following is what you probably +//! want. +//! +//! ```toml +//! [build] +//! target = "thumbv4t-none-eabi" +//! +//! [unstable] +//! build-std = ["core"] +//! +//! [target.thumbv4t-none-eabi] +//! runner = "mgba-qt" +//! rustflags = ["-Clink-arg=-Tlinker_scripts/mono_boot.ld"] +//! ``` +//! +//! * **Make Your Executables:** At this point you can make a `bin` or an +//! `example` file. Every executable will need to be `#![no_std]` and +//! `#![no_main]`. They will also need a `#[panic_handler]` defined, as well +//! as a `#[no_mangle] extern "C" main() -> !` function, which is what the +//! assembly runtime will call to start your Rust program after it fully +//! initializes the system. +//! +//! ```rust +//! #![no_std] +//! #![no_main] +//! +//! #[panic_handler] +//! fn panic_handler(_: &core::panic::PanicInfo) -> ! { +//! loop {} +//! } +//! +//! #[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 first `objcopy` the raw binary out of the ELF +//! into its own file, then Use `gbafix` to give an appropriate header to the +//! file. `objcopy` is part of the ARM binutils you already installed, it +//! should be named `arm-none-eabi-objcopy`. You can get `gbafix` through +//! cargo: `cargo install gbafix`. +//! +//! ## Other GBA-related 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. +//! +//! ## Safety +//! +//! All safety considerations for the crate assume that you're building for the +//! `thumbv4t-none-eabi` or `armv4t-none-eabi` targets, using the provided +//! linker script, and then running the code on a GBA. While it's possible to +//! break any of these assumptions, if you do that some or all of the code +//! provided by this crate may become unsound. mod macros;