Rust on Dreamcast: Difference between revisions

From dreamcast.wiki
Jump to navigation Jump to search
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[File:Rust-dc-logo.png|thumb|Ferris holding his Dreamcast controller]]
[[File:Rust-dc-logo.png|thumb|Ferris holding his Dreamcast controller]]


'''Rust''' is a systems programming language rising in popularity which emphasizes memory safety and performance. Due to its operating at a low level, it is an ideal candidate for running on the Dreamcast. Doing so presents a bit of a challenge, however, as the official Rust compiler is based on the [https://llvm.org/ LLVM] toolchain infrastructure, which does not support the Dreamcast CPU's SuperH architecture. Dreamcast programming is instead typically done with [https://gcc.gnu.org/ GCC], the GNU Compiler Collection. There are currently two viable solutions to this challenge:
'''Rust''' is a popular modern programming language focusing on performance, memory safety, and program correctness. As a "blazingly fast" low-level language, it is viable for running on a Dreamcast console. Doing so presents a bit of a challenge, however, as the official Rust compiler is based on the [https://llvm.org/ LLVM] toolchain infrastructure, which does not support the Dreamcast CPU's SuperH architecture. Dreamcast programming is instead typically done with [https://gcc.gnu.org/ GCC], the GNU Compiler Collection. There are currently two viable solutions to this challenge:


* '''rustc_codegen_gcc''': A libgccjit-based codegen backend for rustc (preferred method)
* '''rustc_codegen_gcc''', the current preferred method: An experimental codegen backend for the official Rust '''rustc''' compiler which interfaces with GCC's libgccjit API
* '''gccrs''': a Rust frontend for GCC
* '''gccrs''': an experimental Rust frontend for GCC


While neither solution is complete at this time, '''rustc_codegen_gcc''' is much further along and is quite usable with some patience with its current limitations and rapid change. On the other hand, '''gccrs''' can compile for Dreamcast, but is in a very early stage, with much of the language unimplemented and no '''libcore''' support. Below we will focus on using rustc_codegen_gcc. For more information on using gccrs, see the [[gccrs]] page.
Neither solution is complete at this time, but '''rustc_codegen_gcc''' is much further along and is quite usable with some patience with its current limitations. On the other hand, '''gccrs''' can compile for Dreamcast, but is in an earlier state. Below we will focus on using '''rustc_codegen_gcc'''. For more information on using gccrs, see the [[gccrs]] page.


=Building rustc_codegen_gcc to develop on Dreamcast=
=Current Status=
With [https://github.com/rust-lang/rustc_codegen_gcc rustc_codegen_gcc], we can interface the standard '''rustc''' compiler frontend with '''libgccjit''', a GCC code-generation API. With the help of the [https://github.com/dreamcast-rs/rust-for-dreamcast '''Rust-for-Dreamcast''' repo] and the [https://github.com/dreamcast-rs/kos-rs '''kos-rs''' crate] containing some early basic [[KallistiOS]] bindings, we can set up rustc_codegen_gcc to compile Rust programs with [https://doc.rust-lang.org/core/ '''core'''] and [https://doc.rust-lang.org/alloc/ '''alloc'''] support (but not the entirety of [https://doc.rust-lang.org/std/ '''std''']). Rust-for-Dreamcast includes wrapper scripts to invoke the rustc and '''cargo''' tools in a familiar way. The familiar borrow checker still works, and one can import and use <code>no_std</code> crates. Despite this support, rustc_codegen_gcc is still in active development, so if using such a setup, expect that things may change rapidly over time. We will need to use some provided patches and scripts to make this solution work. See the rustc_codegen_gcc [https://blog.antoyo.xyz/ progress reports] for more information on the upstream project's progress.
* Programs can be written using the full '''std''' library or '''no_std'''. In the case of '''no_std''' programs, a memory allocator is provided so '''alloc''' types can be used (Vec, String, Box, etc.).
* A [https://github.com/dreamcast-rs/KallistiOS custom version of KallistiOS] v2.1.0 (latest stable release) is used.
** This version includes minor changes for Rust and a beta libpthread addon layer to interface with the Rust standard library.
** Wrappers are provided to invoke '''cargo''' and '''rustc''' in a familiar manner to compile projects.
* A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] crate is provided for easily linking KallistiOS into Rust crates.
** Some very minimal bindings to KallistiOS functions are provided, with expansion of these bindings in progress.
** Documentation for the bindings is available at [https://kos-rs.dreamcast.wiki/ kos-rs.dreamcast.wiki].
** If bindings do not yet exist for desired functionality, wrapping of KallistiOS C functions is required to get proper use of KallistiOS at this time. See the [https://doc.rust-lang.org/nomicon/ffi.html Foreign Function Interface page] in the Rustonomicon for further understanding.
** A custom [https://github.com/dreamcast-rs/libc/tree/libc-0.2-kos '''libc''' crate with KallistiOS support] is provided.
* Code generation uses '''rustc_codegen_gcc''', so its limitations apply here. See the [https://blog.antoyo.xyz/ development blog] for more information on its progress.
** rustc_codegen_gcc is pinned to a particular Rust nightly version, but is synced regularly. The current version in use is the '''2024-08-10''' nightly.
** A [https://github.com/dreamcast-rs/rust/tree/kos-2024-08-10 KallistiOS-patched version of the latest nightly] is maintained and updated regularly.
** Panic unwinding, debug info, LTO, etc. are not currently available.
** Architectures dependent on rustc_codegen_gcc are not yet able to be added to the rustc frontend, so a workaround is necessary: MIPS is falsely selected for KallistiOS, causing rustc to emit objects with a MIPS header and a provided wrapper is used when linking to rewrite these MIPS headers to SuperH before passing the compiled objects to the linker.
* A separate [https://github.com/rust-lang/gcc development version of the GCC toolchain] must be used.
** This version of GCC contains the latest libgccjit patches necessary to interface with rustc_codegen_gcc, and will be built to work with the custom KallistiOS's libpthread layer.
** New updates to rustc_codegen_gcc often require new updates to GCC, so recompiling GCC regularly will be necessary to keep up with the latest updates.
** The development version of GCC does not always compile well on every platform. Using a modern Linux platform is recommended for maximum compatibility.
** The custom KallistiOS and GCC environment can still be used to compile code or projects written in C, C++, etc.
* KallistiOS and all related libraries and tools must be compiled using the <code>-m4-single</code> ABI. This is already set up for you in the guide below, but if external libraries are being linked to Rust projects, make sure that code is compiled using the proper ABI.


'''What Works'''
=Setting up a Rust environment for Dreamcast development=
* '''libcore''' -- the core components of the language for running on bare metal (basics like integers, floats, enums, bools, chars, tuples, arrays, slices, closures, iterators, etc.)
The following guide will provide instructions for setting up a Rust development environment for Dreamcast.  
* '''liballoc''' -- the core components of the language that require a heap, including collections (Vec, String, Box, etc.)
 
* linking to KallistiOS -- KallistiOS and kos-ports can be used if one manually manages interoperating with C via '''unsafe'''
''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 [https://dcemulation.org/phpBB/viewforum.php?f=29 message board] or [https://discord.gg/wDEfkUh63h 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.''
* including <code>no_std</code> crates with the <code>cargo</code> build system
'''In Progress Now'''
* '''libc''' support -- Adding KallistiOS support to Rust's libc crate
* '''libstd''' support -- built-in language support for I/O, networking, threads, time and date, HashMap/HashSet, unwinding on panic, etc.
'''Future Goals'''
* KallistiOS bindings -- properly idiomatic Rust support for KallistiOS
* Upstream libc/libstd support, inclusion as a tier 3 target officially
* Expansion of <code>cargo-dc</code> to support more dcdev-specific functionallity like generating Dreamcast disc images using metadata specified in <code>Cargo.toml</code>


==Prerequisites==
==Prerequisites==
First, we will need to set up the prerequisites.
* You must have the [https://rustup.rs/ 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#Dependencies]] page, with lists provided for most common operating systems.
* We will install our custom Rust toolchain environment within <code>/opt/toolchains/dc/rust</code>. If it does not already exist, create the <code>/opt/toolchains/dc</code> 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 [https://github.com/dreamcast-rs/rust-for-dreamcast/ Rust for Dreamcast] repo containing necessary support files to <code>/opt/toolchains/dc/rust</code>:
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 Rust-patched version of KallistiOS v2.1.0 stable:
git clone https://github.com/dreamcast-rs/KallistiOS /opt/toolchains/dc/rust/kos
Enter the dc-chain directory:
cd /opt/toolchains/dc/rust/kos/utils/dc-chain
The <code>Makefile.default.cfg</code> file in this directory has been customized for you, selecting the proper toolchain profile, paths, and build options necessary for building a Rust toolchain using this guide. It is not recommended to adjust the defaults.
To build the GCC toolchain using 2 CPU cores, simply type:
make makejobs=2
Adjust the <code>makejobs=...</code> value to use the number of CPU cores available to you on your system in order to speed up compilation. This may take a while to build, so be patient.


We will build rustc_codegen_gcc support for the Dreamcast in the instructions below. Before we begin, though:
Once the GCC toolchain is built, source the <code>environ.sh</code> KallistiOS environment settings. A custom <code>environ.sh</code> file has been provided for you, containing settings pre-adjusted for Rust development using this guide.
* You must already have a KallistiOS development environment set up. This means you have installed the typical dependencies, you have created a cross-compiling toolchain for SH4, you have set up your KallistiOS <code>environ.sh</code> file, and you have built KallistiOS with it. Ideally, you will already have at least some familiarity with KallistiOS dev already. See [[Getting Started with Dreamcast development]] for more information, as well as the [https://kos-docs.dreamcast.wiki/ KallistiOS Doxygen].
** For the purposes of this guide, we will assume you are using the standard paths for Dreamcast development tools; i.e. your environment is set up in  <code>/opt/toolchains/dc</code>. Some included scripts and examples may assume this.
** Your KallistiOS installation will need its <code>KOS_SH4_PRECISION</code> setting set to <code>-m4-single</code>. At this time, rustc_codegen_gcc support will not compile with KallistiOS's default <code>-m4-single-only</code> setting. This setting can be changed in KallistiOS's <code>environ.sh</code>, but changing the setting may require you to rebuild your toolchain if you have not built it with <code>m4-single</code> support (which is off by default, but can be enabled in the <code>config.mk</code> file). Once you modify the setting in your <code>environ.sh</code> and re-source the <code>environ.sh</code>, you'll need to rebuild KallistiOS with a <code>make clean</code> and <code>make</code> for the changes to take effect. '''kos-ports''' being used will also need rebuilding with <code>-m4-single</code>. Keep in mind, however, that because KallistiOS doesn't officially support <code>-m4-single</code> yet, some things may be broken, especially libraries in kos-ports that haven't been heavily tested with this setting.
* You must already have a relatively up-to-date Rust installation using [https://rustup.rs/ rustup]. Ideally, you will already have some familiarity with Rust's tools.
* Install the <code>jq</code> and <code>xxd</code> packages for your operating system. <code>xxd</code> might be part of <code>vim</code> depending on the organization of your operating system's package manager.  


''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 [https://dcemulation.org/phpBB/viewforum.php?f=29 message board] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''
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


==Building a cross-compiling libgccjit.so for rustc_codegen_gcc==
Enter the KallistiOS directory:
Before we can use rustc_codegen_gcc, we must compile <code>libgccjit.so</code>, the libgccjit library, for your system. This entails building a unique copy of the SH4 toolchain in its own directory under <code>/opt/toolchains/dc/rust</code>, using a forked version of GCC with enhancements made to libgccjit. The forked version is based on the latest GCC 14 development branch.
cd /opt/toolchains/dc/rust/kos
* '''NOTE''': This forked version of GCC 14 with libgccjit changes is actively developed alongside rustc_codegen_gcc itself, so if you update your rustc_codegen_gcc installation later, you may also need to rebuild libgccjit to pull down new changes rustc_codegen_gcc depends upon as well.


We will first clone the Rust-for-Dreamcast repository, which contains various supporting files needed to create Rust support for Dreamcast. Using <code>git</code>, clone the repository to <code>/opt/toolchains/dc/rust</code>:
Build KallistiOS:
git clone https://github.com/dreamcast-rs/rust-for-dreamcast /opt/toolchains/dc/rust
  make
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
Make any desired changes to thie <code>Makefile.cfg</code> configuration file (e.g., change <code>makejobs=2</code> to the number of CPU threads you'd like to use during compilation), and then compile the SH4 toolchain:
  make toolchain_profile=rustc-dev sh_toolchain_path=/opt/toolchains/dc/rust/sh-elf enable_libgccjit=1 default_precision=m4-single
When this command is completed successfully, a new SH4 cross-compiler toolchain will exist at <code>/opt/toolchains/dc/rust/sh-elf</code> and your  <code>libgccjit.so</code> will be installed to <code>/opt/toolchains/dc/rust/sh-elf/lib/libgccjit.so</code>.


==Building rustc_codegen_gcc==
==Building rustc_codegen_gcc and Rust sysroot==
Now that we have libgccjit built, we can use rustc_codegen_gcc to interface with it to generate SuperH machine code from Rust. Clone the rustc_codegen_gcc repository to your rust directory:
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:
git clone https://github.com/dreamcast-rs/rustc_codegen_gcc.git -b 2024-03-09 /opt/toolchains/dc/rust/rustc_codegen_gcc
rustc_codegen_gcc needs a <code>config.toml</code> file that specifies the location of <code>libgccjit.so</code>. Let's write the the <code>gcc-path</code> to the location of our <code>libgccjit.so</code> library file in this file:
echo 'gcc-path = "/opt/toolchains/dc/rust/sh-elf/lib"' > /opt/toolchains/dc/rust/rustc_codegen_gcc/config.toml
The Rust-for-Dreamcast 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>. You'll need to add the path to those scripts to your <code>PATH</code> environment variable:
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 re-run it every time you start a new shell.


Now we can use the included Rust-for-Dreamcast scripts to set up rustc_codegen_gcc. Patches need to be applied to rustc_codegen_gcc for it to compile properly for our target platform. Let's apply them:
/opt/toolchains/dc/rust/misc/install-rust.sh
  rcg-dc patch
 
Now we can prepare and build rustc_codegen_gcc!
If all goes well, you'll see '''Rust for KallistiOS/Dreamcast installed!''' message!
  rcg-dc prepare
 
  rcg-dc build
==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 <code>/opt/toolchains/dc/rust/kos-ports</code>. This is because the Rust environment is using the <code>-m4-single</code> ABI, but the KallistiOS default installation will be using the <code>-m4-single-only</code>, 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


=Using Rust for Dreamcast=
=Using Rust for Dreamcast=
If all went well, rustc_codegen_gcc will have built successfully.
If all went well, you will now have a working Rust for Dreamcast environment!


You can now use the scripts included in the Rust for Dreamcast repo:
* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
* the <code>rcg-dc</code> script can be used to rebuild the rustc_codegen_gcc code after updating or editing it
** <code>kos-cargo run</code> can be used to build and run code on a Dreamcast console using [[dcload-ip]] or [[dcload-serial]]. You will need to set up the <code>KOS_LOADER</code> variable with the necessary command in the <code>/opt/toolchains/dc/rust/misc/environ.sh</code> file (and then re-source the file for the change to take effect).
* the <code>rustc-dc</code> script can be used to compile Rust modules
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.
* the <code>cargo-dc</code> script can be used to build Rust crates


Examples are included with the Rust for Dreamcast repo to help you get started:
==Examples==
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/cargo-hello <code>cargo-hello</code>] demonstrates how to create a simple "Hello, world!" application with KallistiOS using <code>cargo</code>
Examples are included with the Rust for Dreamcast repo to help you get started.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/cargo-cube <code>cargo-cube</code>] demonstrates a Rust project using KallistiOS with GLdc
* '''no_std''' examples:
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/cargo-addlib <code>cargo-addlib</code>] demonstrates how to create a Rust library that can be included with a KallistiOS project
** [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/no_std/hello-cargo <code>no_std/hello-cargo</code>] demonstrates how to create a simple "Hello, world!" application using cargo.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/rustc-hello <code>rustc-hello</code>] demonstrates how to compile and include a Rust module into a standard KallistiOS <code>Makefile</code>-based project
** [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/no_std/hello-make <code>no_std/hello-make</code>] demonstrates how to create a simple "Hello, world!" application using standard Makefiles.
** [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/no_std/gldc-cube <code>no_std/gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
** [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/no_std/addlib <code>no_std/addlib</code>] demonstrates how to create a Rust library that can be included with a KallistiOS project.
* '''std''' examples:
** [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/std/atomics <code>std/atomics</code>] demonstrates the use of atomic functions.
** [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/std/filesystem-io <code>std/filesystem-io</code>] demonstrates listing directory contents and opening files.
** [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/std/network-time <code>std/network-time</code>] demonstrates displaying the system time and retrieving the current UTC time from an NTP server using the [[Broadband adapter]] or [[LAN adapter]].
** [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/std/threads <code>std/threads</code>] demonstrates the use of threads.
** [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/std/tokio-async <code>std/tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.


==Creating a new Rust project with Cargo==
==Creating a new Rust project with Cargo==
First, we'll demonstrate creating a new "Hello, world!" project with <code>cargo-dc</code>. This will follow the [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/cargo-hello <code>cargo-hello</code>] example included in the Rust-for-Dreamcast repo.  
First, we'll demonstrate creating a new no_std "Hello, world!" project with <code>kos-cargo</code>. This will follow the [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/no_std/hello-cargo <code>no_std/cargo-hello</code>] example included in the Rust-for-Dreamcast repo.  


The Cargo-based examples rely on the [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] crate being present on your computer locally. This is in a separate repo, so let's pull it down now:
In a directory of your choosing, let's invoke <code>kos-cargo</code> to create a new project and then enter the directory:
git clone https://github.com/dreamcast-rs/kos-rs /opt/toolchains/dc/rust/kos-rs
  kos-cargo new hello
 
In a directory of your choosing, let's invoke <code>cargo-dc</code> to create a new project and then enter the directory:
  cargo-dc new hello
  cd hello
  cd hello


Let's add our kos-rs crate to gain access to current KallistiOS bindings. Open <code>Cargo.toml</code> in your text editor and add:
Let's add our kos-rs crate to gain access to current KallistiOS bindings. This will be a <code>no_std</code> project, so we will disable the use of the <code>std</code> library by using <syntaxhighlight lang="toml" inline>default-features = false</syntaxhighlight>. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
<syntaxhighlight lang="toml">
[dependencies]
[dependencies]
kos = { package = "kos-rs", path = "/opt/toolchains/dc/rust/kos-rs" }
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs", default-features = false }</syntaxhighlight>
</syntaxhighlight>


Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
Line 102: Line 130:


#[no_mangle]
#[no_mangle]
fn main(_argc: isize, _argv: *const *const u8) -> isize {
extern "C" fn main(_argc: isize, _argv: *const *const u8) -> isize {
     println!("Hello, world!");
     println!("Hello, world from Rust!");
     return 0;
 
     0
}
}
</syntaxhighlight>
</syntaxhighlight>
Line 114: Line 143:
* Finally, we have a <syntaxhighlight lang="rust" inline>fn main</syntaxhighlight> with the function signature of a typical C <code>main</code> function, containing a basic "Hello, world!" exclamation.
* Finally, we have a <syntaxhighlight lang="rust" inline>fn main</syntaxhighlight> with the function signature of a typical C <code>main</code> function, containing a basic "Hello, world!" exclamation.


Now we can use <code>cargo-dc build</code> to build our project. If all goes well, there will be a <code>target/sh-elf/debug/hello.elf</code> file that can be sent to the Dreamcast with <code>dc-tool</code>.
Now we can use <code>kos-cargo build</code> to build our project. If all goes well, there will be a <code>target/sh-elf/debug/hello.elf</code> file that can be sent to the Dreamcast with <code>dc-tool</code>.
If you have <code>KOS_LOADER</code> set in your KallistiOS environment, you can invoke it directly with <code>cargo-dc run</code>.
If you have <code>KOS_LOADER</code> set in the <code>environ.sh</code> file, you can invoke it directly with <code>kos-cargo run</code>.


==Creating a Rust project using kos-ports libraries==
==Creating a Rust project using kos-ports libraries==
[[File:Rust-Cube rustc codegen-gcc demo.gif|thumb|cube example in action]]
[[File:Rust-Cube rustc codegen-gcc demo.gif|thumb|cube example in action]]
The [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/cargo-cube <code>cargo-cube</code>] example included in the Rust-for-Dreamcast repo demonstrates creating a rotating 3D cube using Rust as the primary language, while calling C functions provided by the '''GLdc''' library available in kos-ports. This project's initial setup is done the same as the above <code>cargo-hello</code> example.
The [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/no_std/gldc-cube <code>gldc-cube</code>] example demonstrates creating a rotating 3D cube using Rust as the primary language, while calling C functions provided by the '''GLdc''' library available in kos-ports. This project's initial setup is done the same as the above <code>hello</code> example.


We'll be using the GLdc graphics and libm math libraries, so we need to tell <code>cargo-dc</code> to link them in. To do this, we'll add a <code>build.rs</code> file to the root of the crate with the following code:
For this example, we'll need to convert JPEG textures to VQ-encoded textures at compile time using the <code>vqenc</code> utility includes with KallistiOS. To do this, we'll add a <code>build.rs</code> file to the root of the crate with the following code (abridged to show the conversion of only one texture):
<syntaxhighlight lang="rust">
<syntaxhighlight lang="rust">
fn main() {
fn main() {
     println!("cargo:rustc-link-lib=GL");
     let kos_base = std::env::var("KOS_BASE").expect("Missing $KOS_BASE -- KallistiOS environment not sourced!");
     println!("cargo:rustc-link-lib=m");
    let vqenc_cmd = kos_base + "/utils/vqenc/vqenc";
     Command::new(&vqenc_cmd)
        .arg("-t")
        .arg("-v")
        .arg("rsrc/tex_claw.jpg")
        .output()
        .expect("vqenc on tex_claw.jpg failed!");
}
}
</syntaxhighlight>
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> macro.


We don't need to add the paths to these libraries, because adding the common paths to KallistiOS libraries is already done for us in the kos-rs crate. However, if in your project you need to include a separate unique library path, you can do that like so:
We will need to link the GLdc library in this example, but we don't need to do anything special to add the paths to this library, because adding the common paths to KallistiOS libraries is already done for us in the kos-rs crate. However, if in your project you need to include a separate unique library path, you can add it in your <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>
</syntaxhighlight>


While not shown here, in the example our <code>build.rs</code> also demonstrates how to use a build script to convert JPG images to VQ-compressed textures with the <code>vqenc</code> tool included with KallistiOS. These texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> macro.
The workings of this example's source code are too great to detail here line-by-line, but the example demonstrates how to use GLdc via the [https://github.com/dreamcast-rs/gldc-sys gldc-sys] crate, which contains unsafe/raw bindings to GLdc. Check out this crate's source code for an example of declaring and binding external C functions, constants, and structures so they can be used in Rust code. Since the entirety of the gldc-cube example uses C FFI functions without safe wrappers, the <code>main()</code> source is wrapped in <code>unsafe {}</code>. In the future, this would be much less necessary as higher level safe Rust bindings to KallistiOS and other libraries become mature.
 
The workings of this example's source code are too great to detail here line-by-line, but the example demonstrates declaring and binding external C functions, constants, and structures and then using them in Rust code. Since the entirety of the example is C interop, the <code>main()</code> source is wrapped in <code>unsafe {}</code>. In the future, this would be much less necessary as higher level safe Rust bindings to KallistiOS and other libraries become mature.


==Creating a Rust library==
==Creating a Rust library==
Next, we'll demonstrate creating a Rust library with <code>cargo-dc</code> that can be included in other Dreamcast code. This will follow the [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/cargo-addlib <code>cargo-addlib</code>] example included in the Rust-for-Dreamcast repo. Once again, this project's initial setup is done the same as the above <code>cargo-hello</code> example, but you'll create the new project using <code>cargo-dc new --lib addlib</code> to specify that we're creating a library named <code>addlib</code>. You'll also need to add the following text to this project's <code>Cargo.toml</code> file:
Next, we'll demonstrate creating a Rust library with <code>kos-cargo</code> that can be included in other Dreamcast code. This will follow the [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/no_std/addlib <code>addlib</code>] example. Once again, this project's initial setup is done the same as the above <code>hello</code> example, but you'll create the new project using <code>kos-cargo new --lib addlib</code> to specify that we're creating a library named <code>addlib</code>. You'll also need to add the following text to this project's <code>Cargo.toml</code> file:


<syntaxhighlight lang="toml">
<syntaxhighlight lang="toml">
Line 168: Line 202:
Two simple functions are provided: one for adding two integers and returning the result, and another for adding two integers and printing the result as text. Because these functions use <syntaxhighlight lang="rust" inline>#[no_mangle]</syntaxhighlight> and are declared <syntaxhighlight lang="rust" inline>extern "C"</syntaxhighlight>, they can be called by name in C code that links this library.
Two simple functions are provided: one for adding two integers and returning the result, and another for adding two integers and printing the result as text. Because these functions use <syntaxhighlight lang="rust" inline>#[no_mangle]</syntaxhighlight> and are declared <syntaxhighlight lang="rust" inline>extern "C"</syntaxhighlight>, they can be called by name in C code that links this library.


When built using <code>cargo-dc build</code>, a <code>target/sh-elf/debug/libaddlib.a</code> file will be generated. This can be linked into other projects to gain the use of these functions.
When built using <code>kos-cargo build</code>, a <code>target/sh-elf/debug/libaddlib.a</code> file will be generated. This can be linked into other projects to gain the use of these functions.


For example, this can be added to a standard <code>Makefile</code>-based KallistiOS project by editing the <code>Makefile</code>:
For example, this can be added to a standard <code>Makefile</code>-based KallistiOS project by editing the <code>Makefile</code>:
Line 186: Line 220:


==Compiling individual modules into object files with rustc==
==Compiling individual modules into object files with rustc==
If we'd like to mix C and Rust code in the same <code>Makefile</code>-based KallistiOS project without building an entirely separate library, we can do that as well. This is demonstrated in the [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/rustc-hello <code>rustc-hello</code>] example included in the Rust-for-Dreamcast repo.
If we'd like to mix C and Rust code in the same <code>Makefile</code>-based KallistiOS project without building an entirely separate library, we can do that as well. This is demonstrated in the [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/no_std/hello-make <code>hello-make</code>] example.


Instead of using <code>cargo-dc</code>, we can invoke the <code>rustc-dc</code> script in our <code>Makefile</code> to build Rust modules. If we assume the Rust module file is named <code>example.rs</code>, you'll need to add <code>example.o</code> as an object file in your <code>Makefile</code>'s <code>OBJS =</code> declaration. For example, if the project has two source files <code>hello_c.c</code> and <code>hello_rust.rs</code>, our <code>Makefile</code> would have a line like this:
Instead of using <code>kos-cargo</code>, we can invoke the <code>kos-rustc</code> via a <code>Makefile</code> to build Rust modules. If we assume the Rust file is named <code>example.rs</code>, you'll need to add <code>example.o</code> as an object file in your <code>Makefile</code>'s <code>OBJS =</code> declaration. For example, if the project has two source files <code>hello_c.c</code> and <code>hello_rust.rs</code>, our <code>Makefile</code> would have a line like this:
<syntaxhighlight lang="make">
<syntaxhighlight lang="make">
OBJS = hello_c.o hello_rust.o
OBJS = hello_c.o hello_rust.o
</syntaxhighlight>
</syntaxhighlight>


Additionally, you'll need to add the following lines so that <code>make</code> knows how to compile Rust modules into <code>.o</code> object files:
The example code demonstrates starting a C <code>main()</code> function to call a Rust function which builds a <code>String</code> containing the "Hello, world!" text which is passed back to a C function which prints <code>String</code>s.
<syntaxhighlight lang="make">
 
%.o: %.rs
==Using the libc crate with KallistiOS==
rustc-dc $< -o $@
If any of the crates in your project's dependency tree requires the '''libc''' crate, you will need to override fetching the default crate with our custom libc crate with KallistiOS/Dreamcast definitions. This custom version was copied to <code>/opt/toolchains/dc/rust/libc</code> when building the Rust sysroot earlier. Add the following text to your <code>Cargo.toml</code>:
<syntaxhighlight lang="toml">
[patch.crates-io]
libc = { path = "/opt/toolchains/dc/rust/libc" }
</syntaxhighlight>
</syntaxhighlight>


The example code demonstrates starting a C <code>main()</code> function to call a Rust function which builds a <code>String</code> containing the "Hello, world!" text which is passed back to a C function which prints <code>String</code>s.
==Adjusting build flags==
 
Build settings can be adjusted through the <code>KOS_RCG_RUSTFLAGS</code> variable in the <code>environ.sh</code> file under the <code>### Rust Flags</code> section.
==Adjusting build settings==
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
Build settings can be adjusted through the <code>CG_GCCFLAGS</code> and <code>CG_RUSTFLAGS</code> environment variables. For example, invoking cargo like so:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
CG_GCCFLAGS="-freorder-blocks-algorithm=simple" cargo-dc build
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
will build the project while passing along the <code>-freorder-blocks-algorithm=simple</code> optimization setting to the GCC backend. <code>rustc-dc</code> will also pass through these settings. If you wish to adjust the default flags passed to GCC, they are specified in the <code>common.sh</code> file.
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>
If you wish to have <code>cargo-dc</code> pass through <code>RUSTFLAGS</code> arguments to the <code>rustc</code> compiler frontend, you can do so by using the <code>CG_RUSTFLAGS</code> environment variable.

Latest revision as of 22:29, 29 October 2024

Ferris holding his Dreamcast controller

Rust is a popular modern programming language focusing on performance, memory safety, and program correctness. As a "blazingly fast" low-level language, it is viable for running on a Dreamcast console. Doing so presents a bit of a challenge, however, as the official Rust compiler is based on the LLVM toolchain infrastructure, which does not support the Dreamcast CPU's SuperH architecture. Dreamcast programming is instead typically done with GCC, the GNU Compiler Collection. There are currently two viable solutions to this challenge:

  • rustc_codegen_gcc, the current preferred method: An experimental codegen backend for the official Rust rustc compiler which interfaces with GCC's libgccjit API
  • gccrs: an experimental Rust frontend for GCC

Neither solution is complete at this time, but rustc_codegen_gcc is much further along and is quite usable with some patience with its current limitations. On the other hand, gccrs can compile for Dreamcast, but is in an earlier state. Below we will focus on using rustc_codegen_gcc. For more information on using gccrs, see the gccrs page.

Current Status

  • Programs can be written using the full std library or no_std. In the case of no_std programs, a memory allocator is provided so alloc types can be used (Vec, String, Box, etc.).
  • A custom version of KallistiOS v2.1.0 (latest stable release) is used.
    • This version includes minor changes for Rust and a beta libpthread addon layer to interface with the Rust standard library.
    • Wrappers are provided to invoke cargo and rustc in a familiar manner to compile projects.
  • A kos-rs crate is provided for easily linking KallistiOS into Rust crates.
    • Some very minimal bindings to KallistiOS functions are provided, with expansion of these bindings in progress.
    • Documentation for the bindings is available at kos-rs.dreamcast.wiki.
    • If bindings do not yet exist for desired functionality, wrapping of KallistiOS C functions is required to get proper use of KallistiOS at this time. See the Foreign Function Interface page in the Rustonomicon for further understanding.
    • A custom libc crate with KallistiOS support is provided.
  • Code generation uses rustc_codegen_gcc, so its limitations apply here. See the development blog for more information on its progress.
    • rustc_codegen_gcc is pinned to a particular Rust nightly version, but is synced regularly. The current version in use is the 2024-08-10 nightly.
    • A KallistiOS-patched version of the latest nightly is maintained and updated regularly.
    • Panic unwinding, debug info, LTO, etc. are not currently available.
    • Architectures dependent on rustc_codegen_gcc are not yet able to be added to the rustc frontend, so a workaround is necessary: MIPS is falsely selected for KallistiOS, causing rustc to emit objects with a MIPS header and a provided wrapper is used when linking to rewrite these MIPS headers to SuperH before passing the compiled objects to the linker.
  • A separate development version of the GCC toolchain must be used.
    • This version of GCC contains the latest libgccjit patches necessary to interface with rustc_codegen_gcc, and will be built to work with the custom KallistiOS's libpthread layer.
    • New updates to rustc_codegen_gcc often require new updates to GCC, so recompiling GCC regularly will be necessary to keep up with the latest updates.
    • The development version of GCC does not always compile well on every platform. Using a modern Linux platform is recommended for maximum compatibility.
    • The custom KallistiOS and GCC environment can still be used to compile code or projects written in C, C++, etc.
  • KallistiOS and all related libraries and tools must be compiled using the -m4-single ABI. This is already set up for you in the guide below, but if external libraries are being linked to Rust projects, make sure that code is compiled using the proper ABI.

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#Dependencies 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 Rust-patched version of KallistiOS v2.1.0 stable:

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

Enter the dc-chain directory:

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

The Makefile.default.cfg file in this directory has been customized for you, selecting the proper toolchain profile, paths, and build options necessary for building a Rust toolchain using this guide. It is not recommended to adjust the defaults.

To build the GCC toolchain using 2 CPU cores, simply type:

make makejobs=2

Adjust the makejobs=... value to use the number of CPU cores available to you on your system in order to speed up compilation. This may take a while to build, so be patient.

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

Using Rust for Dreamcast

If all went well, you will now have a working Rust for Dreamcast environment!

  • cargo can be invoked to target Dreamcast using the kos-cargo command.
    • kos-cargo run can be used to build and run code on a Dreamcast console using dcload-ip or dcload-serial. You will need to set up the KOS_LOADER variable with the necessary command in the /opt/toolchains/dc/rust/misc/environ.sh file (and then re-source the file for the change to take effect).
  • rustc can be invoked to target Dreamcast using the kos-rustc command.

Examples

Examples are included with the Rust for Dreamcast repo to help you get started.

Creating a new Rust project with Cargo

First, we'll demonstrate creating a new no_std "Hello, world!" project with kos-cargo. This will follow the no_std/cargo-hello example included in the Rust-for-Dreamcast repo.

In a directory of your choosing, let's invoke kos-cargo to create a new project and then enter the directory:

kos-cargo new hello
cd hello

Let's add our kos-rs crate to gain access to current KallistiOS bindings. This will be a no_std project, so we will disable the use of the std library by using default-features = false. Open Cargo.toml in your text editor and add:

[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs", default-features = false }

Now we can open up src/main.rs and write our "Hello, world!" example code:

#![no_std]
#![no_main]
extern crate alloc;
use kos::println;

#[no_mangle]
extern "C" fn main(_argc: isize, _argv: *const *const u8) -> isize {
    println!("Hello, world from Rust!");

    0
}
  • #![no_std] and #![no_main] tell Rust that our project does not use the standard library and we will not have Rust use a main function as an entry point -- this will be handled by KallistiOS.
  • extern crate alloc; tells Rust to use the alloc crate to gain access to heap-allocated types (in our case, String).
  • use kos::println!; tells Rust to use the println! macro defined in the kos-rs crate. With this, we can print output to our dc-tool console.
  • #[no_mangle] tells Rust to disable name mangling so that the main function can be used by KallistiOS.
  • Finally, we have a fn main with the function signature of a typical C main function, containing a basic "Hello, world!" exclamation.

Now we can use kos-cargo build to build our project. If all goes well, there will be a target/sh-elf/debug/hello.elf file that can be sent to the Dreamcast with dc-tool. If you have KOS_LOADER set in the environ.sh file, you can invoke it directly with kos-cargo run.

Creating a Rust project using kos-ports libraries

cube example in action

The gldc-cube example demonstrates creating a rotating 3D cube using Rust as the primary language, while calling C functions provided by the GLdc library available in kos-ports. This project's initial setup is done the same as the above hello example.

For this example, we'll need to convert JPEG textures to VQ-encoded textures at compile time using the vqenc utility includes with KallistiOS. To do this, we'll add a build.rs file to the root of the crate with the following code (abridged to show the conversion of only one texture):

fn main() {
    let kos_base = std::env::var("KOS_BASE").expect("Missing $KOS_BASE -- KallistiOS environment not sourced!");
    let vqenc_cmd = kos_base + "/utils/vqenc/vqenc";
    Command::new(&vqenc_cmd)
        .arg("-t")
        .arg("-v")
        .arg("rsrc/tex_claw.jpg")
        .output()
        .expect("vqenc on tex_claw.jpg failed!");
}

The texture files are then included in our project using the include_bytes! macro.

We will need to link the GLdc library in this example, but we don't need to do anything special to add the paths to this library, because adding the common paths to KallistiOS libraries is already done for us in the kos-rs crate. However, if in your project you need to include a separate unique library path, you can add it in your build.rs like so:

println!("cargo:rustc-link-search=native={}", lib_path);

The workings of this example's source code are too great to detail here line-by-line, but the example demonstrates how to use GLdc via the gldc-sys crate, which contains unsafe/raw bindings to GLdc. Check out this crate's source code for an example of declaring and binding external C functions, constants, and structures so they can be used in Rust code. Since the entirety of the gldc-cube example uses C FFI functions without safe wrappers, the main() source is wrapped in unsafe {}. In the future, this would be much less necessary as higher level safe Rust bindings to KallistiOS and other libraries become mature.

Creating a Rust library

Next, we'll demonstrate creating a Rust library with kos-cargo that can be included in other Dreamcast code. This will follow the addlib example. Once again, this project's initial setup is done the same as the above hello example, but you'll create the new project using kos-cargo new --lib addlib to specify that we're creating a library named addlib. You'll also need to add the following text to this project's Cargo.toml file:

[lib]
crate-type = ["staticlib"]

This tells Rust to build a static .a library archive file from our code, which is located in src/lib.rs:

#![no_std]
extern crate alloc;
use kos::print;

#[no_mangle]
pub extern "C" fn print_added(a: isize, b: isize) {
    print!("{}", a + b);
}

#[no_mangle]
pub extern "C" fn add_integers(a: isize, b: isize) -> isize {
    a + b
}

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify #![no_main] as this is a library which wouldn't have a main() function anyway.

Two simple functions are provided: one for adding two integers and returning the result, and another for adding two integers and printing the result as text. Because these functions use #[no_mangle] and are declared extern "C", they can be called by name in C code that links this library.

When built using kos-cargo build, a target/sh-elf/debug/libaddlib.a file will be generated. This can be linked into other projects to gain the use of these functions.

For example, this can be added to a standard Makefile-based KallistiOS project by editing the Makefile:

$(TARGET): $(OBJS)
	kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib

Then, we can use the code in our C source:

/* Declare the external function from the Rust library */
int add_integers(int a, int b);

/* Use the function */
printf("Five plus six is %d\n", add_integers(5, 6));

Compiling individual modules into object files with rustc

If we'd like to mix C and Rust code in the same Makefile-based KallistiOS project without building an entirely separate library, we can do that as well. This is demonstrated in the hello-make example.

Instead of using kos-cargo, we can invoke the kos-rustc via a Makefile to build Rust modules. If we assume the Rust file is named example.rs, you'll need to add example.o as an object file in your Makefile's OBJS = declaration. For example, if the project has two source files hello_c.c and hello_rust.rs, our Makefile would have a line like this:

OBJS = hello_c.o hello_rust.o

The example code demonstrates starting a C main() function to call a Rust function which builds a String containing the "Hello, world!" text which is passed back to a C function which prints Strings.

Using the libc crate with KallistiOS

If any of the crates in your project's dependency tree requires the libc crate, you will need to override fetching the default crate with our custom libc crate with KallistiOS/Dreamcast definitions. This custom version was copied to /opt/toolchains/dc/rust/libc when building the Rust sysroot earlier. Add the following text to your Cargo.toml:

[patch.crates-io]
libc = { path = "/opt/toolchains/dc/rust/libc" }

Adjusting build flags

Build settings can be adjusted through the KOS_RCG_RUSTFLAGS variable in the environ.sh file under the ### Rust Flags section.

  • To pass arguments to the rustc frontend, e.g. to disable debug assertions:
    • export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"
  • To pass arguments to the GCC backend, e.g. to enable the -freorder-blocks-algorithm=simple optimization for Rust code:
    • export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"