From 6bd7f2a44b23625ad300a8bdfe78f165dd8f1752 Mon Sep 17 00:00:00 2001 From: Gwilym Kuiper Date: Sun, 19 Jun 2022 13:50:34 +0100 Subject: [PATCH] Flesh out the readme a little more --- README.md | 109 +++++++++++++++++++++++++++++++++++++-------- template/README.md | 73 ++++++++++++++++++++++++++++++ 2 files changed, 163 insertions(+), 19 deletions(-) create mode 100644 template/README.md diff --git a/README.md b/README.md index 1a51466..143ccf5 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -# Rust for the Game Boy Advance +# AGBRS + +## Rust for the Game Boy Advance ![AGB logo](.github/logo.png) @@ -7,13 +9,30 @@ programming language. It attempts to be a high level abstraction over the internal workings of the Game Boy Advance whilst still being high performance and memory efficient. +AGBRS provides the following features: + +* Simple build process with minimal dependencies +* Built in importing of sprites, backgrounds, music and sound effects +* High performance audio mixer +* Simple sprite and tiled background usage +* Global allocator allowing for use of both `core` and `alloc` + The documentation for the latest release can be found on -[docs.rs](https://docs.rs/agb/latest/agb/). Note that this repository does not -necessarily contain the latest release, but in development versions. Further work -is needed to improve the documentation. +[docs.rs](https://docs.rs/agb/latest/agb/). +## Getting started -## Build Requirements +The best way to get started with agb is to use the template, either within the +`template` directory in this repository or cloning the [template repository](https://github.com/agbrs/template). + +Once you have done this, you will find further instructions within the README in the template. + +There is an (in progress) tutorial which you can find on the [project website](https://agbrs.github.io/agb/). + +## Contributing to agb itself + +In order to contribute to agb itself, you will need a few extra tools on top of what you would need +to just write games for the Game Boy Advance using this library: * Recent rustup, see [the rust website](https://www.rust-lang.org/tools/install) for instructions for your operating system. @@ -22,29 +41,81 @@ is needed to improve the documentation. * arm eabi binutils * Debian and derivatives: `sudo apt install binutils-arm-none-eabi` * Arch Linux and derivatives: `pacman -S arm-none-eabi-binutils` - * Windows can apparently use the [GNU Arm Embedded - Toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads). + * Windows can apparently use the [GNU Arm Embedded Toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads). Make sure to select "Add path to environment variable" during the install. * This process has only been tested on Ubuntu and Arch Linux. - -## Test Requirements - * libelf and cmake * Debian and derivatives: `sudo apt install libelf-dev cmake` * Arch Linux and derivatives: `pacman -S libelf cmake` * mgba-test-runner * Run `cargo install --path mgba-test-runner` inside this directory +* [The 'just' build tool](https://github.com/casey/just) + * Install with `cargo install just` +* [mdbook](https://rust-lang.github.io/mdBook/index.html) + * Install with `cargo install mdbook` +* [gbafix](https://crates.io/crates/gbafix) + * Install with `cargo install gbafix` -## Real Hardware Build - -* Need gbafix, rust implementation can be installed with `cargo install gbafix`. -* On compiled elf file, additionally need to -```bash -arm-none-eabi-objcopy -O binary {input-elf} {output-gba} -gbafix {output-gba} +With all of this installed, you should be able to run a full build of agbrs using by running +```sh +just ci ``` +Note that before you create a PR, please file an issue so we can discuss what you are looking to change. + +## Structure of the repo + +`agb-fixnum` - a simple fixed point number storage since the GBA doesn't have a floating point unit, so required +for performant decimals. + +`agb-image-converter` - a crate which converts images in normal formats to a format supported by the game boy advance + +`agb-macros` - miscellaneous proc-macros which have to be in a different crate + +`agb-sound-converter` - a crate which converts wav files into a format supported by the game boy advance + +`agb` - the main library code + +`agb/examples` - basic examples often targeting 1 feature, you can run these using `just run-example ` + +`book` - the source for the tutorial and website + +`book/games` - games made as part of the tutorial + +`examples` - bigger examples of a complete game, made during game jams + +`mgba-test-runner` - a wrapper around the [mgba](https://mgba.io) emulator which allows us to write unit tests in rust + +`template` - the source for the [template repository](https://github.com/agbrs/template) + ## Stability -0% stable, I have no problems making drastic changes in the API in order to make -something nice to work with. \ No newline at end of file +While in 0.x releases, we are following a semi-semantic versioning. +So 0.x.y will be compatible with 0.x.z provided that y > z, but any changes +to the minor version will be incompatible with one another. + +Once we hit version 1.0, we will maintain stronger semantic versioning. + +## Acknowledgments + +AGBRS would not be possible without the help from the following (non-exhaustive) list of projects: + +* The amazing work of the [rust-console](https://github.com/rust-console) for making this all possible in the first place +* The [asefile](https://crates.io/crates/asefile) crate for loading aseprite files +* [agbabi](https://github.com/felixjones/agbabi) for providing high performance alternatives to common methods +* [mgba](https://mgba.io) for all the useful debugging / developer tools built in to the emulator + +## Licence + +AGBRS and all its subcrates are released under MPL version 2.0. See full licence +text in the `LICENSE` file. + +AGBRS contains a subset of the code from [agbabi](https://github.com/felixjones/agbabi) which is released under a zlib style licence, +details for which you can find under `agb/src/agbabi`. + +The template is released under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/) to allow you to make whatever +changes you wish. + +The AGBRS logo is released under [Creative Commons Attribution-ShareAlike 4.0](http://creativecommons.org/licenses/by-sa/4.0/) + +The music used for the examples is by [Josh Woodward](https://www.joshwoodward.com) and released under [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/) \ No newline at end of file diff --git a/template/README.md b/template/README.md new file mode 100644 index 0000000..423ea1e --- /dev/null +++ b/template/README.md @@ -0,0 +1,73 @@ +# AGBRS template + +## A basic template example for agb projects + +This makes getting started with a new project for the Game Boy Advance in rust really simple, by providing +all the boiler plate files for you. + +## Building + +### Prerequisites + +You will need the following installed in order to build and run this project: + +* A recent version of `rustup`. See the [rust website](https://www.rust-lang.org/tools/install) for instructions for your operating system +* `arm-none-eabi-binutils` for assembling and linking + * Windows: [GNU Arm Embedded Toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads). + Make sure you select "Add path to environment variable" during the install + * Debian and derivatives (e.g. Ubuntu, raspberry pi OS, linux mint): `sudo apt install binutils-arm-none-eabi` + * Arch linux and derivatives: `sudo pacman -S arm-none-eabi-binutils` + +You will also want to install an emulator. The best support in agb is with [mgba](https://mgba.io), with +`println!` support via `agb::println!` but any emulator should work. You'll get the best experience if +`mgba-qt` is in your `PATH`. + +If you want to run your game on real hardware, you will also need to install `gbafix` which you can do after installing +rust with the following: `cargo install gbafix`. This is not required if you are only running your game in an emulator. + +### Running in an emulator + +Once you have the prerequisites installed, you should be able to build using + +```sh +cargo build +``` + +or in release mode (recommended for the final version to ship to players) + +```sh +cargo build --release +``` + +The resulting file will be in `target/thumbv4t-none-eabi/debug/` or `target/thumbv4t-none-eabi/release/` depending on +whether you did a release or debug build. + +If you have `mgba-qt` in your path, you will be able to run your game with + +```sh +cargo run +``` + +or in release mode + +```sh +cargo run --release +``` + +## Starting development + +You can find the documentation for agb [here](https://docs.rs/agb/latest/agb/). + +You may also want to change the package name and version in `Cargo.toml` before you start. + +## Shipping a .gba file for real hardware + +To make a game run on real hardware, you will need to convert the built file into a file suitable for +running on the real thing. + +First build the binary in release mode using the instructions above, then do the following: + +```sh +arm-none-eabi-objcopy -O binary target/thumbv4t-none-eabi/release/ .gba +gbafix .gba +``` \ No newline at end of file