UGBA testing infrastructure

1. Introduction

libugba is a library for development of GBA games. It can be used to build actual GBA game ROMs, but it can also target a regular PC so that it is easier to debug the logic in the game. It is written in C.

This repository contains several examples of how to use each one of the subsystems of the library. All examples are also used as unit tests, and they are part of the automated regresion testing system of the library.

The PC builds of the tests are simply run on the host by passing the program a Lua script with instructions. The GBA builds are run on GiiBiiAdvance, which has basic support for Lua scripts as well. Ideally, it would test on other emulators. The PC builds have some parts of the emulator inside them to simulate the GBA hardware, and it would be a good idea to test the code against a different emulator to have a second opinion.

2. Dependencies

To generate PC executables (and to run the tests):

• GCC, Clang, MSVC or another compiler supported by CMake.
• CMake 3.15 or later
• SDL2 2.0.7 or later (AudioStream support needed)
• libpng 1.6 or later (Simplified API support needed): Needed to save PNGs like screenshots and dumps from VRAM debugger windows.
• liblua 5.2 or later (Integer support needed): Needed for the Lua interpreter used for the unit tests.

To generate GBA ROMs you need one of:

• A gcc-arm-none-eabi toolchain: You can get it from your package manager, or from Arm's GNU toolchain downloads website. In Ubuntu you can just do:

sudo apt install gcc-arm-none-eabi

• devkitPro: You need to install devkitPro following the instructions in the devkitPro Getting Started guide, then follow the instructions in this readme. It comes with its own build of gcc-arm-none-eabi.

The following projects are integrated as submodules in this repository, and they are only used when building the examples, so you don't need to worry about them:

• UMOD Player: For some audio tests.
• GiiBiiAdvance: To run the GBA ROM version of the unit tests.
• SuperFamiconv: Graphics converter.

3. Build and run examples on Linux

Follow this if you're on Linux or any Linux-like environment (like MinGW or Cygwin). First, clone this repository along with its submodules:

git clone --recurse-submodules https://codeberg.org/SkyLyrac/ugba-testing
cd ugba-testing

Now, install the dependencies. For example, in Debian or Ubuntu:

sudo apt install libsdl2-dev liblua5.4-dev libpng-dev

If you haven't installed devkitPro previously, use your package manager to install the following package as well:

sudo apt install gcc-arm-none-eabi

Now, convert the assets by running:

bash assets.sh

The following will build the library, and examples for the host and for GBA:

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j`nproc`

If you aren't using devkitPro, you need to add -DUSE_DEVKITARM=OFF to the cmake command.

To override the autodetected location of the cross compiler, you can add -DARM_GCC_PATH=/path/to/folder/ to the cmake command.

To disable the generation of GBA ROMs you can add -DBUILD_GBA=OFF.

Finally, to run the tests, simply do:

ctest

4. Known bugs

• Audio tests on the GBA are too unreliable. All the test does is compare the waveform outputted by the emulator with a reference, so any small change in almost any part of the boot or audio code will break the test. Even the difference between debug and release builds is enough to break them. For now, they are disabled, and they are only run on SDL2 builds.