Flesh out the readme a little more

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
+[docs.rs](https://docs.rs/agb/latest/agb/).
-necessarily contain the latest release, but in development versions. Further work
-is needed to improve the documentation.
 
+## 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
+    * 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).
-      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
+With all of this installed, you should be able to run a full build of agbrs using by running
-
+```sh
-* Need gbafix, rust implementation can be installed with `cargo install gbafix`.
+just ci
-* On compiled elf file, additionally need to
-```bash
-arm-none-eabi-objcopy -O binary {input-elf} {output-gba}
-gbafix {output-gba}
 ```
 
+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
+While in 0.x releases, we are following a semi-semantic versioning.
-something nice to work with.
+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/)

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/<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
+```