Skip to content

Latest commit

 

History

History
215 lines (154 loc) · 8.74 KB

README.md

File metadata and controls

215 lines (154 loc) · 8.74 KB
Raw

gbadev-containers

Container scripts for a GBA dev environment & ROM compile workflow.

ROM demo: gbadev-containers.gba

Powered by OCI containers to create immutable build environments, via podman or docker.

Created for GBA Jam 2024.

ROM also hosted at https://breadmakesyoufull.itch.io/gbadev-containers

View this README in gba manual pdf format here.

by BreadMakesYouFull

Preview

Requires

  • podman OR docker (make BUILDER=docker)
  • bash
  • make

podman can be installed on linux, windows and mac.

Provides

Container images created by this project:

  • gbadev-base: debian + devkitproARM + gba development packages
  • gbadev: Used to compile the in folder via butano and devkitproARM
  • gbadev-examples: Compiled gba examples from butano / natu

Installed packages include:

Quickstart

# Build the gbadev-base container, compile the demo ROM, and run:
make && make run

# See available commands:
make help

# Package versions configured via the ``env`` file
# Regenerate base gbadev container image via:
make base

# Run the example games from butano and natu:
make examples && make run-examples

Licenses

I am not a lawyer, this is not legal advice

DO NOT distribute container images you build with this project. Do not upload them to docker.io or similar services. To understand why, read this report by the linux foundation.

If you understand and meet these obligations, this project may be used to build your own GBA homebrew ROM, be it for fun and or profit. Consider making your homebrew open source, and giving credit if you found this useful.

Project structure

.
├── gbadev-containers.gba  - Pre-built ROM
├── containers/ - Container build instructions
├── scripts/    - Bash scripts and utilities
├── env         - Build options
├── Makefile    - Entry point for builds
├── in          - gbadev-containers.gba source code
├── out         - ROM build output location
├── LICENSE     - License for this project
├── licenses    - Third party licenses
└── README.md   - Essential info

The in folder contains source for a homebrew demo, which makes use of the "butano" game engine.

The container images created by the Containerfile scripts are gbadev-base and gbadev. Which provide tools for development and run a ROM build respectively.

The resulting .gba ROM file is compiled to the out folder.

Use cases

Use case 1: Using this project as a template for your homebrew

Simply build from the existing example, the in folder, and play with iterative changes!

You must comply with LICENSE and ALL of the licenses folder.

Use case 2: Build an existing project

Here is an example of building the homebrew game, "sips", by Jono Shields (foopod). It was also written utilizing the butano game engine (by GValiente), so can easily be built using this project's set up:

# Clone the source for the game "sips"
git clone https://github.com/foopod/sips.git

# Tweak the game's makefile to point to the container image butano location
sed -i 's|LIBBUTANO   :=.*|LIBBUTANO=/opt/butano/butano|' ./sips/Makefile

# Enter the container build repo
cd gbadev-containers

# Configure butano version to when the game source code was written
sed -i 's/BUTANO=.*/BUTANO=16.2.0/' env

# Build the base dev environment with the butano version configured in the last step
make base

# Run build for the sips source code
make IN=`pwd`/../sips

Use case 3: Cross platform development

podman can be installed on linux, windows and mac.

On linux cross distribution support is simplified further via distrobox. This allows for things like launching mgba without complex socket configuration:

# Make gbadev-base podman container
make base
# Convert container to distrobox
distrobox-create --name gbadev-distrobox --image gbadev-base
# Enter distrobox
distrobox-enter gbadev-distrobox
# Run mgba GUI
distrobox-enter gbadev-distrobox

Drawbacks

This workflow may not be for you! There are a number of drawbacks to this approach including:

  • bloat -> Remove what you don't need?
  • time -> Build the base image only once?
  • overhead -> Just install and run bare metal instead?
  • maintenance -> Clean up old image builds?
  • Licenses -> Read licenses
  • C++ -> try natu / nim instead?
  • Old versions -> Nixos/Nixpkgs/Guix? Different base image? Pacman/AUR?
  • Learning curve -> Run make -> look in out for your ROM :)

Additional information

For reference this repo was created with:

$ podman -v ; docker -v ;  uname -srm ; bash --version ; make --version
podman version 3.4.4
Docker version 27.0.3, build 7d4bcd8
Linux 6.9.3 x86_64
GNU bash, version 5.1.16
GNU Make 4.3

Depending on hardware and project you will require:

  • ~10GiB disk space
  • ~15 mins for initial build
  • ~1 min for any subsequent builds

Thanks

A special thanks to the GBA Jam 2024 hosts - exelotl, destoer, evanbowman, Nikku4211, Pyro_Pyro, Jono Shields, GValiente, Xilefian, kva64, avivace

In particular GValiente for the Butano game engine and the thorough documentation.

Made possible by the open source and GBA homebrew development communities: