1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
//! # 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.
//!
//! ``` bash
//! 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.
//!
//! ```bash
//! # 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`](https://github.com/zlfn/rust-gb-template)
//! repository.
//!
//! ```bash
//! 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](https://bgb.bircd.org/). However, unless there is a
//! major problem, any GameBoy emulator should be able to run the `out.gb` file.