Crate gb

Source
Expand description

§A crate for GameBoy (Color) development.

Rust-GB is a both toolchain and library for compiling Rust code into Nintendo GameBoy. It compiles Rust code into valid GameBoy ROM through LLVM-CBE and GBDK-2020.

§Install the compiler

Install a Rust-GB compiler with cargo install. You must use Rust nightly version with you are playing with Rust-GB because it uses a lot of experimental and unstable features.

In addition, due to limited size issues, external dependencies required by Rust-GB could not be uploded to crates.io, so you have to clone the repository to install a compiler.

git clone https://github.com/zlfn/rust-gb.git
git checkout tags/v0.1.0-alpha.2
cd rust-gb
cargo install --path . --features compiler

compiler feature is required when installing the Rust-GB compiler. If not, binary will not be installed.

Also, note that avr-gcc, avr-libc, sdcc, rust-src are required. You need to install them to your system before running the compiler.

# Example for Ubuntu
sudo apt install gcc-avr avr-libc sdcc
rustup component add rust-src --toolchain nightly-x86_64-unknown-linux-gnu

§Note

Right now, you can’t run the Rust-GB compiler other than Linux x64. This is because the GameBoy compilation process requires some “external binaries”. We’re going to solve this problem in the future by packaging Rust-GB compiler for a platform-specific package manager (winget, homebrew, pacman etc.)

§Setup a project

Rust-GB ROM project have to provide all the right default settings so cargo build will just work. Most recommended way to do this is cloning rust-gb-template repository.

 git clone https://github.com/zlfn/rust-gb-template.git

This repository contains minimum files to be compiled GameBoy ROM properly.

§Compile your project

By executing the cargo build-rom command inside you GameBoy ROM project, you can compile the Rust code into GameBoy ROM.

The command creates two directories: out and ext.

  • out : In this directory, all intermediates generated during the compilation process (LLVM-IR, C, ASM etc.) and the final result out.gb are generated.

  • ext : GameBoy ROM builds require external binaries (SDCC, LLVM-CBE) and dependency files. By default, the Rust-GB compiler contains these files, but when compile GameBoy ROM, it needs to be copied to the file system. This directory contains those external dependency files.

§Execute your ROM

The final result, out.gb, is located in the out directory. This file can be run using the GameBoy emulator or real GameBoy (Color / Advance).

The most recommended emulator is bgb. However, unless there is a major problem, any GameBoy emulator should be able to run the out.gb file.

§Library features

  • color — GameBoy Color feature

    This feature enables GameBoy Color only features. Such as VRAM bank or color palette.

    Since the compiler does not yet support compilation in to GameBoy Color ROM, this will not actually work.

  • prototype — Prototype feature

    This feature enables the prototype APIs of Rust-GB. Because it’s a prototype, it won’t work properly.

§Binary features

  • compiler — Feature for compiler

    This feature needed to enabled when you install Rust-GB compiler with cargo install.

    DO NOT enable this feature in your GameBoy ROM package. It will cause compile error. This is because the Rust-GB compiler cannot be compiled for ATMega328 target.

Modules§

drawing
All Points Addressable (APA) mode drawing library.
gbdk_c
Direct access API to GBDK extern functions.
io
Helpers for GameBoy I/O. including buttons, texts, and else.
mmio
Memory Map IO address for the GameBoy components.

Macros§

print
Prints to the GameBoy screen. If you’ve ever used print! macro in std, you’ll familiar with this.
println
Prints to the GameBoy screen, with a newline. If you’ve ever used println! macro in std, you’ll familiar with this.