|
|
| (159 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| Preliminary support exists for developing for the Dreamcast using the Rust programming language. This is a bit of a challenge, however, as the official Rust compiler is based on the LLVM toolchain infrastructure, which does not support the Dreamcast's CPU SuperH architecture. Dreamcast programming is instead done with GCC, the GNU Compiler Collection. There exists two solutions to this problem:
| | [[File:Rust-dc-logo.png|thumb|Ferris holding his Dreamcast controller]] |
|
| |
|
| * rustc_codegen_gcc: A libgccjit codegen backend for rustc (preferred method)
| | '''Please visit [https://dreamcast.rs/ dreamcast.rs]!''' |
| * gccrs: a Rust frontend for GCC
| |
|
| |
|
| =rustc_codegen_gcc=
| | The Rust for Dreamcast documentation has now [https://dreamcast.rs been migrated into an mdBook]! |
| GCC includes a component called '''libgccjit''' which provides an API for an embeddable just-in-time code generator using GCC, useful for creating programs like interpreters. However, this component can also be used to generate code ahead of time as well. '''rustc_codegen_gcc''' is a project which interfaces the official Rust compiler with the libgccjit API to generate machine code from Rust using the GCC backend. With this, we can compile Rust programs for Dreamcast using familiar compiler tools such as <code>rustc</code> and <code>cargo</code>! The familiar borrow checker still works, and one can write <code>#![no_std]</code> crates with full <code>libcore</code> support. An experimental crate binding with [[KallistiOS]] provides <code>liballoc</code> functionality such as a heap and familiar collections like Vec, String, etc. as well.
| |
| | |
| We will build rustc_codegen_gcc support for the Dreamcast in the instructions below. Before we begin, though:
| |
| * You must already have a KallistiOS development environment set up. This means you have created a cross-compiling toolchain for SH4 and you have built KallistiOS with it. See [[Getting Started with Dreamcast development]] for more information.
| |
| ** For the purposes of this guide, we will assume you are using the standard paths for Dreamcast tools; i.e. your environment is set up in <code>/opt/toolchains/dc</code>.
| |
| ** Your KallistiOS installation will need its floating point precision setting set to <code>m4-single</code>. This setting is available in the <code>environ.sh</code>, but it may require you to rebuild your main toolchain if you have not built it with <code>m4-single</code> support.
| |
| * You must already have a relatively up-to-date Rust installation, either using your operating system's package manager or [https://rustup.rs/ rustup].
| |
| | |
| ==Building a cross-compiling libgccjit.so for rustc_codegen_gcc==
| |
| First, we must compile <code>libgccjit.so</code>, the cross-compiling shared library, for your system. This entails building another copy of the SH4 toolchain once more in its own directory under <code>/opt/toolchains/dc/rust</code>, using a forked version of GCC with enhancements to '''libgccjit'''.
| |
| | |
| Using <code>git</code>, clone the <code>rust-for-dreamcast</code> repository to <code>/opt/toolchains/dc/rust</code>:
| |
| git clone https://github.com/darcagn/rust-for-dreamcast /opt/toolchains/dc/rust
| |
| Enter your KallistiOS installation's <code>dc-chain</code> directory:
| |
| cd /opt/toolchains/dc/kos/utils/dc-chain
| |
| Clear out any existing build files:
| |
| make clean-keep-archives
| |
| Copy the necessary toolchain patches to your <code>dc-chain</code> setup:
| |
| cp /opt/toolchains/dc/rust/toolchain/*.diff patches/
| |
| Copy the '''rustc_codegen_gcc''' configuration file into place:
| |
| cp /opt/toolchains/dc/rust/toolchain/config.mk.rustc_codegen_gcc.sample config.mk
| |
| Make any desired changes to the configuration (e.g., change <code>makejobs=-j2</code> to the number of CPU threads you'd like to use during compilation), and then compile the SH4 toolchain:
| |
| make build-sh4
| |
| When this command is completed successfully, a <code>libgccjit.so</code> will be installed to <code>/opt/toolchains/dc/rust/sh-elf/lib/libgccjit.so</code>.
| |
| | |
| ==Building rustc_codegen_gcc==
| |
| The <code>rust-for-dreamcast</code> repository contains scripts and wrappers to assist you in building rustc_codegen_gcc and using it in conjunction with <code>cargo</code> and <code>rustc</code>. Let's add them to our environment's PATH now:
| |
| export PATH="/opt/toolchains/dc/rust/bin:$PATH"
| |
| You may also want to add the above line to your shell's startup file or else you'll need to run it every time you open a new shell.
| |
| | |
| Clone the rustc_codegen_gcc to your rust directory:
| |
| git clone https://github.com/rust-lang/rustc_codegen_gcc.git /opt/toolchains/dc/rust/rustc_codegen_gcc
| |
| Set the <code>gcc_path</code> file:
| |
| echo /opt/toolchains/dc/rust/sh-elf/lib > /opt/toolchains/dc/rust/rustc_codegen_gcc/gcc_path
| |
| Copy the architecture configuration file, <code>sh-elf.json</code>, to its place:
| |
| cp /opt/toolchains/dc/rust/misc/sh-elf.json /opt/toolchains/dc/rust/rustc_codegen_gcc/sh-elf.json
| |
| * patch out duplicate symbols in src/context.rs
| |
| * add SH4 precision mode to src/base.rs
| |
| * patch build_system/src/config.rs to alter default linker call
| |
| * patch build_sysroot/Cargo.toml to remove std and test from being pulled in
| |
| * y.sh clean
| |
| * y.sh prepare --cross
| |
| * y.sh build
| |
| | |
| ==Creating a new project using Cargo==
| |
| * create an empty staticlib crate with target in .cargo/config
| |
| * add kos-rs crate from /opt/toolchains/dc/rust/kos-rs path
| |
| | |
| ==Compiling individual modules into object files with rustc==
| |
| | |
| =gccrs=
| |
| gccrs implements a Rust compiler frontend for GCC. This essentially means implementing a new Rust compiler 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 <code>libcore</code>, so many basic language features are unimplemented or not functional. Additionally, Rust standard tooling like <code>cargo</code> is not available. Borrow checking is not implemented, but the project plans to later use the next-generation Rust borrow checker [https://github.com/rust-lang/polonius Polonius] from the official Rust project.
| |
| | |
| It is possible to use this compiler by building the GCC 14.0.1-dev toolchain or the GCCRS latest toolchain. GCC 14.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'''. The GCC 14.0.1-dev configuration file is available within the official KallistiOS repo's <code>dc-chain</code> script, while the latest GCCRS configuration is available within the [Rust for Dreamcast https://github.com/darcagn/rust-for-dreamcast] repository. 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 <code>dc-chain</code>.
| |
| | |
| ==Building a GCCRS-enabled toolchain==
| |
| ==Setting up Makefiles to compile Rust modules==
| |
