mirror of
https://github.com/italicsjenga/agb.git
synced 2025-01-10 00:51:34 +11:00
Flesh out the readme a little more
This commit is contained in:
Gwilym Kuiper
parent
578b1eefa4
commit
6bd7f2a44b
109
README.md
109
README.md
|
|
@ -1,4 +1,6 @@
|
|||
# Rust for the Game Boy Advance
|
||||
# AGBRS
|
||||
|
||||
## Rust for the Game Boy Advance
|
||||
|
||||
|
||||
|
||||
|
|
@ -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 <example-name>`
|
||||
|
||||
`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.
|
||||
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/)
|
||||
73
template/README.md
Normal file
73
template/README.md
Normal file
|
|
@ -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/<your game>` or `target/thumbv4t-none-eabi/release/<your game>` 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/<your game> <your game>.gba
|
||||
gbafix <your game>.gba
|
||||
```
|
||||
Loading…
Reference in a new issue