Home

Development Environment Setup

Overview

The Game Boy Advance is a very different piece of hardware from the computers you typically use. It has a different processor architecture, and does not have an operating system. Because of this, programs compiled for other machines cannot run on it. gcc and other compilers you have used are not able to produce code that runs on the GBA by default.

Because of this, we need to use a cross-compiler which is a compiler which generates code for a machine different from the one it is running on. This is a different version of gcc which has been configured to produce GBA code.

This page provides instructions on how to:

Develop using a Linux-based virtual machine image (on any system)
Install a development environment on Linux
Burn GBA games to an Everdrive card so you can run them on the real hardware

Using a Virtual Machine

If you'd like to use a virtual machine with a GBA development environment already setup, you can follow these instructions:

Download and install VirtualBox which is virtualisation software that can create and run virtual machines.
Download the CPSC 305 VM image which is a rather large file and will take some time to download.
Open VirtualBox and click the "Import" button. In the dialog that opens, click the browse for file button, then navigate to the CPSC305.ova file you downloaded. Click "next".
You can leave the settings in the next window all as default values, then click "Finish". It will spend a little time importing the VM. When done "CPSC305" should pop up on the right.
Launch the VM by selecting the CPSC305 on the left and clicking "Start", or by double-clicking the VM. This will open the VM in a new window.
The VM contains a full Linux desktop with the GBA development environment installed.

The username and password for the VM are both just "user". The user has sudo access, so you can install new software onto it, should you wish to.

Installing the Development on Linux

The GBA cross-compiler we're using was compiled for Linux, so I only have instructions for setting the tools up on your own machine if you're using Linux. Also, the tools will not work on Windows Subsystem for Linux (WSL) because it doesn't support running 32-bit programs.

If you are running native Linux, and want to install the tools locally, you can do so:

Download the Compiler and Tools

Download the DevKit Advance (project home page). This includes the compiler and tools needed for creating Game Boy Advance games. This can be done with the command:
```
wget https://ianfinlayson.net/gba/files/devkitadv.tar.bz2
```
Extract the Compiler and Tools
Extract the tarball some place with the command:
```
tar -xjvf devkitadv.tar.bz2
```
Download the build script

The gbacc build script calls the cross-compiler within DevKit Advance and creates an executable GBA ROM. You can grab it with:
```
wget https://ianfinlayson.net/gba/files/gbacc
```
Then, open the file in Vim and change the line that beings with KITHOME= such that it refers to the location where you extracted the "devkitadv" directory to.

Then give the build script executable permission:
```
chmod +x gbacc
```

Place this script somewhere in your PATH so you can run it from any directory.

Grab the GBA Patcher (and other things)
The DevKit Advance does not produce executables that can actually run on the GBA hardware. The .gba files must be patched so that the GBA will recognize them. For that you can grab a utility I wrote to do the patching.

For our first few programs, you won't need images or sound, but I also wrote a couple programs to facilitate using these in GBA programs. While we're here, you may as well set those up to. All three are available on my Github:
For each of these, do the following:
1. Clone the repository
2. Go into the directory and run the command make
3. Place the resulting executable program somewhere in your PATH
Compile Hello World

Now compile this hello.c file.

To do so, pass the hello.c file to the gbacc build script:
```
gbacc hello.c
```
This should compile it with no output, and produce a file called "program.gba". This is an executable GBA game.

You can also give it a custom name:
```
gbacc hello.c -o hello.gba
```
NOTE: If you get an error saying something like:
```
devkitadv/bin/arm-agb-elf-gcc: cannot execute binary file: Exec format error
devkitadv/bin/arm-agb-elf-objcopy: cannot execute binary file: Exec format error
```
Then the problem is that you are running 64-bit Linux and need some 32-bit libraries to be able to run 32-bit executables (which is what the DevKit uses). To fix this run:
```
sudo dpkg --add-architecture i386
sudo apt update
sudo apt install libc6-i386
```
Install the GBA Emulator

You will also need a GBA emulator installed. To do this run the command:
```
sudo apt install visualboyadvance vbaexpress
```
Run Hello World

To run the program, execute the command:
```
vba -4 program.gba
```
When you run the program, it should look something like this:

If you see this, then you are ready to start writing GBA games!

Running GBA Programs on a Real GBA

This is not needed for developing GBA programs, but if you are interested in running the .gba files directly on a real Game Boy Advance instead of an emulator, instructions for doing that follow:

Necessary Tools

In order to run your games on the actual Game Boy Advance, you will need the following things:

A Game Boy Advance or Game Boy Advance SP.
An EverDrive GBA cartridge. This is a special cartridge which allows you to load custom ROMS onto the GBA.
A micro SD card.

Setting up the Game Boy Advance

Download the GBA OS
This is a very small operating system of sorts that allows us to choose which game on the EverDrive we want to run. You can download the latest version from the EverDrive website. Then unzip the file.
Put it on your SD card
Move the "GBASYS" directory which you downloaded onto your micro SD card. Then unmount and remove the micro SD card.

Writing the Game

You are now ready to write your GBA ROMs onto the SD card so that they can be run directly on the hardware.

Copy any .gba programs you want to be able to run onto your micro SD card. Unmount the card and remove it.

Running the Game

Load the SD card into the GBA
Place the micro SD card into the EverDrive cartridge, and then the cartridge into the GBA.
Turn it on
Power on the GBA, this should bring you to the GBA OS menu. You can move with the arrow buttons and select with the "A" button. Navigate to your ROM with the arrow buttons, and select the ROM you want to run with the "A" button.
Run it

Now your GBA game will be running directly on the hardware. From the GBA's perspective, your game is running on a cartridge by itself. All the EverDrive does is load one of multiple ROMs into the GBA with a menu. Your code is running directly on the hardware.

Here is the GBA running the Test program I loaded which just displays the UMW logo:

Enjoy running your own games on the GBA!