Setting up a Rust environment for Dreamcast development

The following guide will provide instructions for setting up a Rust development environment for Dreamcast.

If you run into any errors or other challenges while following this tutorial, or simply need clarification on any of the steps, feel free to ask for assistance on the message board or our Discord server and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.

Prerequisites

First, we will need to set up the prerequisites.

  • You must have the rustup tool installed for your operating system to manage Rust toolchain installations. It will automatically manage the latest Rust nightly installations for you. You cannot use a Rust toolchain that may be provided by your operating system vendor.
  • Install the dependency packages for your operating system. These are listed in the Dependencies section on the Getting Started with Dreamcast development page, with lists provided for most common operating systems.
  • We will install our custom Rust toolchain environment within /opt/toolchains/dc/rust. If it does not already exist, create the /opt/toolchains/dc directory and grant it proper permissions using the following commands.
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
  • Clone the Rust for Dreamcast repo containing necessary support files to /opt/toolchains/dc/rust:
git clone https://github.com/dreamcast-rs/rust-for-dreamcast.git /opt/toolchains/dc/rust

Installing our custom KallistiOS and GCC toolchain

Clone the git repository for our custom libpthread-enabled version of KallistiOS:

git clone https://github.com/dreamcast-rs/KallistiOS /opt/toolchains/dc/rust/kos

Build the sh-elf-gcc toolchain with the proper settings set up for you. By default, this uses 2 cores for building, but you can increase the number of cores by changing the 2 to the desired number of cores. This can take a while depending on the performance of your computer. If you want to adjust GCC/toolchain settings, check the rust-toolchain.cfg file in the same directory for options.

/opt/toolchains/dc/rust/misc/install-toolchain.sh -j2

Once the GCC toolchain is built, source the environ.sh KallistiOS environment settings. A custom environ.sh file has been provided for you, containing settings pre-adjusted for Rust development using this guide. You will need to run the source command to apply the KallistiOS environment settings to your currently running shell. Run the following now, and whenever you open a new shell to work on Dreamcast projects:

source /opt/toolchains/dc/rust/misc/environ.sh

Enter the KallistiOS directory:

cd /opt/toolchains/dc/rust/kos

Build KallistiOS:

make

Building rustc_codegen_gcc and Rust sysroot

Now that we have a working KallistiOS environment suitable for Rust development set up, we can build the Rust compiler compiler and sysroot components. A script is provided which will download the necessary components from the respective repositories and compile them for you. Run the installer script:

/opt/toolchains/dc/rust/misc/install-rust.sh

If all goes well, you'll see Rust for KallistiOS/Dreamcast installed! message!

Building KOS ports libraries

If desired, you may also built the KOS ports collection of libraries for use with your Rust environment. It is recommended to maintain a separate KOS ports installation for linking with Rust projects in /opt/toolchains/dc/rust/kos-ports. This is because the Rust environment is using the -m4-single ABI, but the KallistiOS default installation will be using the -m4-single-only, which cannot be mixed and matched.

Clone the kos-ports repository to your system:

git clone https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/rust/kos-ports

An individual port can be built and installed by entering its directory and running the proper command. For example, installing GLdc:

cd /opt/toolchains/dc/rust/kos-ports/libGL
make install

Or, instead, you may run the script to build all of the included ports:

/opt/toolchains/dc/rust/kos-ports/utils/build-all.sh