From fb67cadbc7f9a3f891abb395bb6c2330ad2413ab Mon Sep 17 00:00:00 2001 From: Gwilym Kuiper Date: Wed, 24 Nov 2021 20:20:17 +0000 Subject: [PATCH] Add some setup guide stuff --- book/src/03_environment_setup.md | 6 ++++++ book/src/03_getting_started.md | 11 +++++++++++ book/src/03a_linux_setup.md | 34 ++++++++++++++++++++++++++++++++ book/src/03b_building.md | 34 ++++++++++++++++++++++++++++++++ book/src/SUMMARY.md | 8 +++++++- 5 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 book/src/03_environment_setup.md create mode 100644 book/src/03_getting_started.md create mode 100644 book/src/03a_linux_setup.md create mode 100644 book/src/03b_building.md diff --git a/book/src/03_environment_setup.md b/book/src/03_environment_setup.md new file mode 100644 index 00000000..a6fcd811 --- /dev/null +++ b/book/src/03_environment_setup.md @@ -0,0 +1,6 @@ +# Running the example + +Environment setup will depend on the platform you are using. +agb's requirements are [rust nightly](https://www.rust-lang.org/) edition and the gnu binutils for `arm-none-eabi`. + +See the subpages here for platform specific setup guides. diff --git a/book/src/03_getting_started.md b/book/src/03_getting_started.md new file mode 100644 index 00000000..d51cdc07 --- /dev/null +++ b/book/src/03_getting_started.md @@ -0,0 +1,11 @@ +# Running an example + +In this section, we will get to the point where you can build and run the game built for the GMTK game jam using agb known as 'The Hat Chooses the Wizard'. +This will prove that your development environment is ready for the future tutorials and later building. + +You can run the game using real hardware and a flash card. +However, at this stage, it is much easier to play on an emulator. +agb is guaranteed to work well using [mgba](https://mgba.io/), but other emulators will also work. + +Note that some emulators will require a special 'fixed' gba ROM file. +See the later steps in this section for how to do this. \ No newline at end of file diff --git a/book/src/03a_linux_setup.md b/book/src/03a_linux_setup.md new file mode 100644 index 00000000..605fdb7c --- /dev/null +++ b/book/src/03a_linux_setup.md @@ -0,0 +1,34 @@ +# Linux setup + +This guide has been tested on Ubuntu, Arch Linux and Raspberry Pi OS running on a raspberry pi 4. + +# 1. Install a recent version of rust + +agb unfortunately relies on a few nightly rust features, so you need to ensure you have that installed. +Firstly, ensure that you have **rustup** installed which you can do by following the instructions on the [rust website](https://www.rust-lang.org/tools/install) + +You can update rustup with `rustup update` if you have already installed it. + +# 2. arm-none-eabi + +We need this installed in order to be able to assemble the small amount of assembly in agb, and to do the final linking. + +* On Debian and derivatives (like Ubuntu): `sudo apt install binutils-arm-non-eabi` +* On Arch Linux and derivatives: `pacman -S arm-none-eabi-binutils` + +# 3. git + +The source code for the game is hosted on github, so you will need git installed. + +* On Debian and derivatives (like Ubuntu): `sudo apt install git` +* On Arch Linux and derivatives: `pacman -S git` + +# 4. gbafix + +In order to be able to play on real hardware or on some emulators, you may need to install 'gbafix'. +The rust implementation can be installed very easily using `cargo install gbafix`. + +Make sure that the Cargo bin directory is in your `PATH` as we'll need to use it later. + +That is all you need to get started. +You can now move on to 'building the game'. \ No newline at end of file diff --git a/book/src/03b_building.md b/book/src/03b_building.md new file mode 100644 index 00000000..2ce23aec --- /dev/null +++ b/book/src/03b_building.md @@ -0,0 +1,34 @@ +# Building the game + +By the end of this section, you should be able to build and run an example game made using agb! +**This section is optional.** +If you just want to get straight into building your own games, you don't need to do this. +However, we recommended doing this section to prove that your setup works. + +# 1. Get the source code + +The source code can be fetched using `git clone https://github.com/agbrs/joinedtogether.git`. + +# 2. Build the game + +Build a copy of the game using `cargo build --release`. +This could take quite a while, but eventually you'll end up with a copy of the game in `target/thumbv4t-none-eabi/release/joinedtogether` or `target/thumbv4t-none-eabi/release/joinedtogether.elf` depending on platform. + +This can be run directly by some emulators, but we need to run an extra step in order to convert the elf file into a '.gba' file. + +```sh +arm-none-eabi-objcopy -O binary target/thumbv4t-none-eabi/release/joinedtogether joinedtogether.gba +gbafix joinedtogether.gba +``` + +or + +```sh +arm-none-eabi-objcopy -O binary target/thumbv4t-none-eabi/release/joinedtogether.elf joinedtogether.gba +gbafix joinedtogether.gba +``` + +And then load the resulting file in your emulator of choice. +That's all there is to it! + +If you have `mgba-qt` in your path, then you can launch the game directly using `cargo run --release` \ No newline at end of file diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 32a3cd0b..ed41418a 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -1,4 +1,10 @@ # Summary - [Introduction](./01_introduction.md) -- [The Game Boy Advance hardware](./02_hardware.md) \ No newline at end of file +- [The Game Boy Advance hardware](./02_hardware.md) +- [Running an example](./03_getting_started.md) + - [Environment setup](./03_environment_setup.md) + - [Linux setup](./03a_linux_setup.md) + - [Windows setup]() + - [Mac OS setup]() + - [Building the game](./03b_building.md) \ No newline at end of file