Gccrs

From dreamcast.wiki
Revision as of 21:20, 7 May 2024 by Darc (talk | contribs)
Jump to navigation Jump to search

gccrs is the Rust compiler frontend for GCC, currently under active development. This Rust compiler is a new implementation of Rust from the ground up using the GCC toolchain infrastructure. This project is in early stages and is targeting the Rust 1.49 revision from December 2020. As of this writing (February 2024), it is not yet able to compile Rust's libcore, so many basic language features are unimplemented or not functional. Additionally, Rust standard tooling like cargo is not available. Borrow checking is not implemented, but the project plans to later use the next-generation Rust borrow checker Polonius from the official Rust project.

At this time, it is recommended to use rustc_codegen_gcc to develop for Dreamcast using Rust instead of gccrs.

Although it is in early stages and highly experimental for Dreamcast dev purposes, it is possible to use this compiler by building a GCC toolchain from a development version or the gccrs latest toolchain. GCC 15.0.1-dev will get you the latest code upstreamed by the gccrs team into the main development branch of GCC, while the gccrs git repo will get you the absolute latest bleeding edge updates to gccrs. Both profiles are available in the dc-chain scripts included with KallistiOS. Brief instructions follow for setting up the latest gccrs toolchain. See Getting Started with Dreamcast development for more detailed information on how to set up and run dc-chain.

Building a gccrs-enabled toolchain

Follow the Getting Started with Dreamcast development guide for creating a Dreamcast toolchain until you arrive at the instructions for setting up the dc-chain configuration file.

Make sure your shell is currently in the correct directory:

cd /opt/toolchains/dc/kos/utils/dc-chain

Make any desired changes to the Makefile.cfg configuration. Note that to avoid conflicting with an existing stable toolchain at the default path (i.e. /opt/toolchains/dc/sh-elf), we will be installing to /opt/toolchains/dc/gccrs/sh-elf-gccrs instead. To begin compilation and installation, run:

make toolchain_profile=gccrs-dev enable_rust=1 sh_toolchain_path=/opt/toolchains/dc/sh-elf-gccrs

After building everything, you can clean up the extraneous files in your dc-chain directory by entering:

make clean

Setting up Makefiles to compile Rust modules

As mentioned before, cargo is not available to use with gccrs, so for our example, we will place our .rs modules within a typical KallistiOS Makefile project. If we assume the module file is named example.rs, you'll need to add example.rox as an object file in your Makefile's OBJS = declaration. Additionally, you'll need to add the following lines so that make knows how to compile Rust modules into rox object files:

%.rox: %.rs
	kos-cc -frust-incomplete-and-experimental-compiler-do-not-use $(CFLAGS) -c $< -o $@

Alternatively, you can add those lines to your KallistiOS Makefile.rules file to avoid having to place it in every project's Makefile.

In your example.rs file, your main function will need to be declared like so:.

#[no_mangle]
pub extern fn main() -> i32 {
    [...]
}

Make sure before you compile your code that you set export KOS_CC_BASE="/opt/toolchains/dc/sh-elf-gccrs" in your KallistiOS environ.sh file or make will not find your gccrs compiler executable.

Example project

The rust-fortran-cube repository contains an example project using gccrs in conjunction with GFortran, KallistiOS, and GLdc. View footage of the example running. This example was created by Eric Fradella and used as a demo in the FOSDEM 2024 talk Sega Dreamcast Homebrew with GCC by Falco Girgis.