dreamcast.wiki - User contributions [en]

Programming language support

2026-01-10T21:50:25Z

Darc: /* Compiled languages */

The following languages can be used in Sega Dreamcast programming:

=Assembly languages=
* '''SH4 assembly''', as the native machine code for the Dreamcast's SuperH processor
* '''ARM assembly''', as the native machine code for the Dreamcast's AICA ARM7DI sound processor

=Compiled languages=
* '''C''', the predominant language for Sega Dreamcast development, via the GCC C compiler.
* '''C++''', commonly used and very well-supported, via the GCC C++ compiler.
* '''Objective-C''', via the GCC Objective-C compiler. Preliminary support for Foundation framework via [https://gnustep.github.io/ GNUstep] is being developed. See [https://twitter.com/dinobj_c/status/1732399498977276154 Andrew Apperley's X account]. See [[Objective-C on Dreamcast]] for more information.
** The GNU '''Objective-C++''' extension is available as well.
* '''D''', via the GCC D compiler. Early support, see [https://dreamcast.wiki/D_on_Dreamcast D on Dreamcast] for more information.
* '''Go''', via gccgo with libgodc runtime. Full runtime support including garbage collection, goroutines, and channels. See [https://github.com/drpaneas/libgodc libgodc on GitHub] for more information.
* '''Rust''', via rustc_codegen_gcc and libgccjit, or via gccrs. When using rustc_codegen_gcc, the standard library is available, with bindings to KallistiOS being developed. See [[Rust on Dreamcast]] for more information.
* '''Ada''', via GNAT. [https://github.com/dkm/ada-dreamcast-helloworld Ada 3D cube demo] by [https://poulhies.fr/ Marc Poulhiès].
* '''Fortran''', via GFortran. Requires some work to create a cross-compiler, but does work.

=Scripting/Interpreted languages=
* Lua (available in [[kos-ports]])
* MicroPython (available in [[kos-ports]])
* Tcl (available in [[kos-ports]])
* mRuby (available in [[kos-ports]])
* AngelScript
* QuickJS

GLdc

2025-12-26T14:37:20Z

Darc:

[https://github.com/Kazade/GLdc GLdc] is an OpenGL implementation for the Dreamcast that is actively developed by Kazade. <br>

==Contributors==
People who also contributed to the testing and optimisation of GLdc (in no particular order): <br>
<br>
Hayden Kowalchuk (MrNeo) <br>
Unknown Shadow <br>
T_Chan <br>
Troy Davis <br>
Falco Girgis <br>
darcagn <br>
Bkacjios <br>
David Reichelt <br>
Spencer Elliott <br>
Andress Antonio Barajas <br>
Ben Baron <br>
cepawiel <br>
lerabot <br>

==Features==

Supports most of the OpenGL 1.2 implementation.

==Projects built with GLdc==
*[[Simulant|Simulant engine]]
*[[Summoning Signals]]
*[[nuQuake]]

==Building GLdc==

GLdc can be installed through the KallistiOS [https://github.com/KallistiOS/kos-ports kos-ports] system. It is provided as the <code>libGL</code> package.

Getting Started with Dreamcast development

2025-12-10T09:04:52Z

Darc: /* Setting up and compiling the toolchain with the dc-chain script */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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 Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.

<div class="mw-collapsible mw-collapsed">
====macOS on an Intel or Apple Silicon processor====
<div class="mw-collapsible-content">
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install make wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib
</div></div>

<div class="mw-collapsible mw-collapsed">
====Debian/Ubuntu-based Linux====
<div class="mw-collapsible-content">
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake cmake
</div></div>

<div class="mw-collapsible mw-collapsed">
====Fedora-based Linux====
<div class="mw-collapsible-content">
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build cmake
</div></div>

<div class="mw-collapsible mw-collapsed">
====Arch-based Linux====
<div class="mw-collapsible-content">
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake cmake
</div></div>

<div class="mw-collapsible mw-collapsed">
====Alpine-based Linux====
<div class="mw-collapsible-content">
sudo apk --update add build-base patch bash texinfo gmp-dev mpfr-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake cmake fmt
</div></div>

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.2.x''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.2.x /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues. Proceed at your own risk using unstable master!
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> (KOS 2.2.0 stable) or <code>Makefile.dreamcast.cfg</code> (KOS master unstable) file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. Simply run:
make

This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the command above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths.

You will need to run the following command to apply the KOS environment settings to your currently running shell. Run the following command now, '''and''' ''whenever'' you open a new shell to work on Dreamcast projects:
. /opt/toolchains/dc/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

On your development machine, setup [[dcload-ip]]:
* [[Using dcload-ip with Linux]]
* [[Using dcload-ip with Windows Subsystem for Linux]]

For the Dreamcast, download and burn the [[:File:Dcload-2023-06-22.zip|latest version of dcload-ip or dcload-serial]] to a CD-R -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>
* Alpine: <code>meson libisofs-dev</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Getting Started with Dreamcast development

2025-12-01T23:51:25Z

Darc:

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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 Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install make wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake cmake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build cmake

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake cmake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev mpfr-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake cmake fmt

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.2.x''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.2.x /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues. Proceed at your own risk using unstable master!
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> (KOS 2.2.0 stable) or <code>Makefile.dreamcast.cfg</code> (KOS master unstable) file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. Simply run:
make

This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the command above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths.

You will need to run the following command to apply the KOS environment settings to your currently running shell. Run the following command now, '''and''' ''whenever'' you open a new shell to work on Dreamcast projects:
. /opt/toolchains/dc/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

On your development machine, setup [[dcload-ip]]:
* [[Using dcload-ip with Linux]]
* [[Using dcload-ip with Windows Subsystem for Linux]]

For the Dreamcast, download and burn the [[:File:Dcload-2023-06-22.zip|latest version of dcload-ip or dcload-serial]] to a CD-R -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>
* Alpine: <code>meson libisofs-dev</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

SaveFileConverter

2025-10-29T04:04:09Z

Darc:

[https://savefileconverter.com/#/dreamcast SaveFileConverter.com] is a website enabling the conversion of save files from many consoles.

[https://github.com/euan-forrester Euan Forrester] created this tool, and the source code can be found [https://github.com/euan-forrester/save-file-converter on Github]. He hosts this website so you don't need to run it yourself.

In the case of Dreamcast, the tool disaggregates ''.bin'', ''.vmu'', or ''.flash'' files, into individual ''.dci'' files or a set of ''.vmi'' and ''.vms'' files, per game save. So basically you can get a single save file off of a whole memory card file.

Conversely, it can build or aggregate a VMU bin file out of multiple individual saves. Using Save File Converter, you can put combine the save files from multiple different games into a single VMU file.

Redump2CDI

2025-09-11T02:40:07Z

Darc:

'''Redump2CDI''' is a utility created by [[darc]] to convert Redump Dreamcast CD-ROM images to [[DiscJuggler]] format. The Redump image format is a non-standard form of BIN+CUE image that cannot be burned or mounted with much existing software, so conversion is convenient for non-archival purposes.

It can also convert Redump bin/cue images for other systems as well, although this is not its primary intended use case.

Redump2CDI is intended only for Redump Dreamcast CD-ROM images. It is not intended to convert GD-ROM images or old school non-selfboot BIN+CUE Dreamcast files.

* [[:File:Redump2cdi-1.00-2025-09-10.zip|Redump2CDI 1.00 2025-09-10]] (Windows/macOS/Linux/FreeBSD binaries provided)
* [[:File:Redump2cdi-0.9.0-2024-03-30.zip|Redump2CDI TEST/BETA 0.9.0 2024-03-30]]
* [[:File:Redump2cdi-0.1.0-2023-09-23.zip|Redump2CDI TEST/BETA 0.1.0 2023-09-23]]

To use, run like so:
redump2cdi -i "My Favorite Game (Unl).cue" -o myfavgame.cdi

==Changelog==
* 1.00: As requested by several users, added ability to ignore unsupported FLAGS, CDTEXTFILE, PERFORMER, SONGWRITER, and TITLE cuesheet commands with a warning about inaccuracy, though images using these flags should work fine. These aren't used by any Redump Dreamcast images, but this allows redump2cdi to be used for Redump images for other consoles. Added `-u` flag to skip other unsupported, unrecognized commands at user's own risk.
* 0.9.0: Added support for processing MODE1/2352 tracks. These aren't used in Dreamcast images, but support for these tracks was requested as it helps this utility be useful for converting other systems' images, too.
* 0.8.0: Largely refactored code. Not publicly released.
* 0.1.0: Initial release.

==Windows GUI application==
A Windows GUI frontend for Redump2CDI has kindly been provided by teddyrogers. Make sure to download the latest version of Redump2CDI above and place the Windows executable in the same folder as the GUI application.

* [[:File:Redump2CDI-GUI v1.0.zip|Redump2CDI GUI v1.0]]

Redump2CDI

2025-09-11T02:40:01Z

Darc:

Redump2CDI

2025-09-11T02:39:33Z

Darc:

'''Redump2CDI''' is a utility created by [[darc]] to convert Redump Dreamcast CD-ROM images to [[DiscJuggler]] format. The Redump image format is a non-standard form of BIN+CUE image that cannot be burned or mounted with much existing software, so conversion is convenient for non-archival purposes.

It can also convert Redump bin/cue images for other systems as well, although this is not its primary intended use case.

Redump2CDI is intended only for Redump Dreamcast CD-ROM images. It is not intended to convert GD-ROM images or old school non-selfboot BIN+CUE Dreamcast files.

This is a beta version.

* [[:File:Redump2cdi-0.9.0-2024-03-30.zip|Redump2CDI TEST/BETA 0.9.0 2024-03-30]] (Windows/macOS/Linux/FreeBSD binaries provided)
* [[:File:Redump2cdi-0.1.0-2023-09-23.zip|Redump2CDI TEST/BETA 0.1.0 2023-09-23]]

To use, run like so:
redump2cdi -i "My Favorite Game (Unl).cue" -o myfavgame.cdi

==Changelog==
* 1.00: As requested by several users, added ability to ignore unsupported FLAGS, CDTEXTFILE, PERFORMER, SONGWRITER, and TITLE cuesheet commands with a warning about inaccuracy, though images using these flags should work fine. These aren't used by any Redump Dreamcast images, but this allows redump2cdi to be used for Redump images for other consoles. Added `-u` flag to skip other unsupported, unrecognized commands at user's own risk.
* 0.9.0: Added support for processing MODE1/2352 tracks. These aren't used in Dreamcast images, but support for these tracks was requested as it helps this utility be useful for converting other systems' images, too.
* 0.8.0: Largely refactored code. Not publicly released.
* 0.1.0: Initial release.

==Windows GUI application==
A Windows GUI frontend for Redump2CDI has kindly been provided by teddyrogers. Make sure to download the latest version of Redump2CDI above and place the Windows executable in the same folder as the GUI application.

* [[:File:Redump2CDI-GUI v1.0.zip|Redump2CDI GUI v1.0]]

File:Redump2cdi-1.00-2025-09-10.zip

2025-09-11T02:26:50Z

Darc: Uploaded own work with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{no|1=Redump2cdi-1.00-2025-09-10}}
|date=2025-09-10
|source={{own}}
|author=[[User:Darc|Darc]]
|permission=
|other versions=
}}

=={{int:license-header}}==
{{licensing|generic}}

Redump2CDI

2025-09-11T02:18:42Z

Darc:

'''Redump2CDI''' is a utility created by [[darc]] to convert Redump Dreamcast CD-ROM images to [[DiscJuggler]] format. The Redump image format is a non-standard form of BIN+CUE image that cannot be burned or mounted with much existing software, so conversion is convenient for non-archival purposes.

Redump2CDI is intended only for Redump Dreamcast CD-ROM images. It is not intended to convert GD-ROM images or old school non-selfboot BIN+CUE Dreamcast files.

This is a beta version.

* [[:File:Redump2cdi-0.9.0-2024-03-30.zip|Redump2CDI TEST/BETA 0.9.0 2024-03-30]] (Windows/macOS/Linux/FreeBSD binaries provided)
* [[:File:Redump2cdi-0.1.0-2023-09-23.zip|Redump2CDI TEST/BETA 0.1.0 2023-09-23]]

To use, run like so:
redump2cdi -i "My Favorite Game (Unl).cue" -o myfavgame.cdi

==Changelog==
* 1.00: As requested by several users, added ability to ignore unsupported FLAGS, CDTEXTFILE, PERFORMER, SONGWRITER, and TITLE cuesheet commands with a warning about inaccuracy, though images using these flags should work fine. These aren't used by any Redump Dreamcast images, but this allows redump2cdi to be used for Redump images for other consoles. Added `-u` flag to skip other unsupported, unrecognized commands at user's own risk.
* 0.9.0: Added support for processing MODE1/2352 tracks. These aren't used in Dreamcast images, but support for these tracks was requested as it helps this utility be useful for converting other systems' images, too.
* 0.8.0: Largely refactored code. Not publicly released.
* 0.1.0: Initial release.

==Windows GUI application==
A Windows GUI frontend for Redump2CDI has kindly been provided by teddyrogers. Make sure to download the latest version of Redump2CDI above and place the Windows executable in the same folder as the GUI application.

* [[:File:Redump2CDI-GUI v1.0.zip|Redump2CDI GUI v1.0]]

Getting Started with Dreamcast development

2025-08-20T17:06:56Z

Darc: /* Cloning the KallistiOS git repository */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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 Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake cmake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build cmake

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake cmake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev mpfr-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake cmake fmt

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.2.x''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.2.x /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues. Proceed at your own risk using unstable master!
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> (KOS 2.2.0 stable) or <code>Makefile.dreamcast.cfg</code> (KOS master unstable) file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. Simply run:
make

This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the command above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths.

You will need to run the following command to apply the KOS environment settings to your currently running shell. Run the following command now, '''and''' ''whenever'' you open a new shell to work on Dreamcast projects:
. /opt/toolchains/dc/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

On your development machine, setup [[dcload-ip]]:
* [[Using dcload-ip with Linux]]
* [[Using dcload-ip with Windows Subsystem for Linux]]

For the Dreamcast, download and burn the [[:File:Dcload-2023-06-22.zip|latest version of dcload-ip or dcload-serial]] to a CD-R -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>
* Alpine: <code>meson libisofs-dev</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Getting Started with Dreamcast development

2025-08-04T19:17:37Z

Darc: /* Cleaning up temporary files */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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 Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake cmake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build cmake

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake cmake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev mpfr-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake cmake fmt

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.2.0''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.2.0 /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues:
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> (KOS 2.2.0 stable) or <code>Makefile.dreamcast.cfg</code> (KOS master unstable) file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. Simply run:
make

This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the command above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths.

You will need to run the following command to apply the KOS environment settings to your currently running shell. Run the following command now, '''and''' ''whenever'' you open a new shell to work on Dreamcast projects:
. /opt/toolchains/dc/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

On your development machine, setup [[dcload-ip]]:
* [[Using dcload-ip with Linux]]
* [[Using dcload-ip with Windows Subsystem for Linux]]

For the Dreamcast, download and burn the [[:File:Dcload-2023-06-22.zip|latest version of dcload-ip or dcload-serial]] to a CD-R -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>
* Alpine: <code>meson libisofs-dev</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Getting Started with Dreamcast development

2025-08-04T19:17:18Z

Darc: /* Downloading and compiling the toolchain */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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 Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake cmake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build cmake

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake cmake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev mpfr-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake cmake fmt

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.2.0''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.2.0 /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues:
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> (KOS 2.2.0 stable) or <code>Makefile.dreamcast.cfg</code> (KOS master unstable) file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. Simply run:
make

This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the command above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths.

You will need to run the following command to apply the KOS environment settings to your currently running shell. Run the following command now, '''and''' ''whenever'' you open a new shell to work on Dreamcast projects:
. /opt/toolchains/dc/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

On your development machine, setup [[dcload-ip]]:
* [[Using dcload-ip with Linux]]
* [[Using dcload-ip with Windows Subsystem for Linux]]

For the Dreamcast, download and burn the [[:File:Dcload-2023-06-22.zip|latest version of dcload-ip or dcload-serial]] to a CD-R -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>
* Alpine: <code>meson libisofs-dev</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Getting Started with Dreamcast development

2025-08-04T19:16:19Z

Darc: /* Configuring the dc-chain script */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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 Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake cmake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build cmake

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake cmake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev mpfr-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake cmake fmt

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.2.0''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.2.0 /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues:
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> (KOS 2.2.0 stable) or <code>Makefile.dreamcast.cfg</code> (KOS master unstable) file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. At this point, we have the option of building both the main CPU SH4 compiler and the AICA sound processor ARM compiler, or we can skip the ARM compiler and just build the SH4 compiler. Thankfully, KallistiOS includes a prebuilt sound driver, so the ARM compiler is only necessary if you're wanting to make changes to the sound driver or write custom code to run on the sound processor.
To build '''only the SH4 compiler''':
make
To build '''both''' the SH4 and the ARM compilers:
make all
This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the commands above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths.

You will need to run the following command to apply the KOS environment settings to your currently running shell. Run the following command now, '''and''' ''whenever'' you open a new shell to work on Dreamcast projects:
. /opt/toolchains/dc/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

On your development machine, setup [[dcload-ip]]:
* [[Using dcload-ip with Linux]]
* [[Using dcload-ip with Windows Subsystem for Linux]]

For the Dreamcast, download and burn the [[:File:Dcload-2023-06-22.zip|latest version of dcload-ip or dcload-serial]] to a CD-R -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>
* Alpine: <code>meson libisofs-dev</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

KallistiOS GameCube

2025-08-03T20:30:32Z

Darc:

A KallistiOS port to GameCube is underway, led by [[darc]].

This page exists to serve as a general reference for KallistiOS GameCube related information until a better page can be created.

Wii support is planned as well, but GameCube is the current priority. Wii U support is not planned at this time, as it would likely require significant core KallistiOS changes.

==Purpose/Goals==
# Born as a personal side project by [[darc]] to play with a non-Dreamcast embedded target and to learn more about low-level hardware programming, kernel programming, and KallistiOS low-level internals
# Restore KallistiOS to a multi-arch project. KallistiOS 1.x was originally multi-arch (dc/ps2/gba) before all non-Dreamcast targets were removed with the KallistiOS 2.x release due to lack of progress and interest. GameCube/Wii pairs well with the Dreamcast. The additional targets help keep the kernel architecture robust and provide more testing capabilities.
# Facilitate cross-platform homebrew games and allow easier development of GameCube/Wii ports of Dreamcast homebrew. While console-specific code will still be required, a unified KallistiOS core will reduce porting burden, and higher level, platform-independent KallistiOS APIs can be created for many components. OpenGL or SDL implementations can ease porting burden as well. This can help expand both the Dreamcast and GameCube/Wii homebrew dev scenes.
# For those concerned about the legality of libogc, KallistiOS serves as an alternative, as it does not use devkitPro/libogc.

==Status==
* Toolchain builder: [https://github.com/KallistiOS/KallistiOS/pull/1097 Currently in PR] (thanks pcercuei)
* Changes needed to general KOS: few left, currently pending (thanks quzar)
* GameCube arch: Not upstreamed yet (in progress by darc)
** Working: Most of core KOS kernel (interrupts/threads/etc.), USB Gecko for debug output, basic pad reading, external framebuffer for video output
** Upstreaming of core arch code expected soon(TM)

==News==
* [https://x.com/darcag3nt/status/1916867037588050326 Announcement] 4/28/2025
* [https://x.com/darcag3nt/status/1936593167454986745 Doom port demonstration] 6/21/2025

==Running homebrew==
Most accessible methods for running homebrew (non-exhaustive):
* FlippyDrive: ODE + real disc drive combo, solderless, USD$50+ kit
* CubeODE: Replaces disc drive with ODE via SD slot, solderless, about USD$50
* [https://github.com/webhdx/PicoBoot PicoBoot]: Overrides BIOS with [https://github.com/redolution/gekkoboot gekkoboot] homebrew bootloader, easy soldering required, DIY and very cheap
* [https://github.com/makeo/PicoLoader PicoLoader]: Emulates a disc drive to boot a main homebrew app then re-enables real disc drive, solderless, DIY and very cheap
* XenoGC: Allows disc drive to boot homebrew from DVD-R, requires moderate soldering, cheap
* Action Replay: Requires rare Action Replay disc to load files from SD card reader
* Save exploits

KallistiOS GameCube

2025-08-03T19:54:47Z

Darc: Created page with "A KallistiOS port to GameCube is underway, led by darc. This page exists to serve as a general reference for KallistiOS GameCube related information until a better page can be created. ==Status== * Toolchain: Currently in PR (thanks pcercuei) * Changes needed to general KOS: few left, currently pending (thanks quzar) * GameCube arch: Not upstreamed yet (in progress by darc) ==Running homebrew== Most accessible methods for running homebrew (non-exhaustive): * Flipp..."

A KallistiOS port to GameCube is underway, led by [[darc]].

This page exists to serve as a general reference for KallistiOS GameCube related information until a better page can be created.

==Status==
* Toolchain: Currently in PR (thanks pcercuei)
* Changes needed to general KOS: few left, currently pending (thanks quzar)
* GameCube arch: Not upstreamed yet (in progress by darc)

==Running homebrew==
Most accessible methods for running homebrew (non-exhaustive):
* FlippyDrive: ODE + real disc drive combo, solderless, USD$50+ kit
* CubeODE: Replaces disc drive with ODE via SD slot, solderless, about USD$50
* [https://github.com/webhdx/PicoBoot PicoBoot]: Overrides BIOS with [https://github.com/redolution/gekkoboot gekkoboot] homebrew bootloader, easy soldering required, DIY and very cheap
* [https://github.com/makeo/PicoLoader PicoLoader]: Emulates a disc drive to boot a main homebrew app then re-enables real disc drive, solderless, DIY and very cheap
* XenoGC: Allows disc drive to boot homebrew from DVD-R, requires moderate soldering, cheap
* Action Replay: Requires rare Action Replay disc to load files from SD card reader
* Save exploits

File:SH7750 Group User's Manual - Hardware.pdf

2025-07-24T21:08:39Z

Darc: Uploaded own work with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{no|1=SH7750 Group User's Manual - Hardware}}
|date=2025-07-24
|source={{own}}
|author=[[User:Darc|Darc]]
|permission=
|other versions=
}}

=={{int:license-header}}==
{{licensing|generic}}

File:SH4 C ABI.pdf

2025-07-24T21:08:39Z

Darc: Uploaded own work with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{no|1=SH4 C ABI}}
|date=2025-07-24
|source={{own}}
|author=[[User:Darc|Darc]]
|permission=
|other versions=
}}

=={{int:license-header}}==
{{licensing|generic}}

File:SH-4 Software Manual.pdf

2025-07-24T21:08:39Z

Darc: Uploaded own work with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{no|1=SH-4 Software Manual}}
|date=2025-07-24
|source={{own}}
|author=[[User:Darc|Darc]]
|permission=
|other versions=
}}

=={{int:license-header}}==
{{licensing|generic}}

Getting Started with Dreamcast development

2025-07-11T22:57:10Z

Darc: /* Cloning the KallistiOS git repository */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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 Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake cmake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build cmake

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake cmake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev mpfr-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake cmake fmt

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.2.0''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.2.0 /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues:
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. At this point, we have the option of building both the main CPU SH4 compiler and the AICA sound processor ARM compiler, or we can skip the ARM compiler and just build the SH4 compiler. Thankfully, KallistiOS includes a prebuilt sound driver, so the ARM compiler is only necessary if you're wanting to make changes to the sound driver or write custom code to run on the sound processor.
To build '''only the SH4 compiler''':
make
To build '''both''' the SH4 and the ARM compilers:
make all
This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the commands above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths.

You will need to run the following command to apply the KOS environment settings to your currently running shell. Run the following command now, '''and''' ''whenever'' you open a new shell to work on Dreamcast projects:
. /opt/toolchains/dc/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

Download and burn the [[:File:Dcload-2023-06-22.zip|latest versions of dcload-ip or dcload-serial]] -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>
* Alpine: <code>meson libisofs-dev</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Getting Started with Dreamcast development

2025-06-23T03:48:40Z

Darc: /* Setting up the environment settings */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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 Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake cmake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build cmake

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake cmake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev mpfr-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake cmake fmt

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.1.1''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.1.x /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues:
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. At this point, we have the option of building both the main CPU SH4 compiler and the AICA sound processor ARM compiler, or we can skip the ARM compiler and just build the SH4 compiler. Thankfully, KallistiOS includes a prebuilt sound driver, so the ARM compiler is only necessary if you're wanting to make changes to the sound driver or write custom code to run on the sound processor.
To build '''only the SH4 compiler''':
make
To build '''both''' the SH4 and the ARM compilers:
make all
This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the commands above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths.

You will need to run the following command to apply the KOS environment settings to your currently running shell. Run the following command now, '''and''' ''whenever'' you open a new shell to work on Dreamcast projects:
. /opt/toolchains/dc/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

Download and burn the [[:File:Dcload-2023-06-22.zip|latest versions of dcload-ip or dcload-serial]] -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>
* Alpine: <code>meson libisofs-dev</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Getting Started with Dreamcast development

2025-06-23T03:48:16Z

Darc:

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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 Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake cmake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build cmake

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake cmake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev mpfr-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake cmake fmt

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.1.1''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.1.x /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues:
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. At this point, we have the option of building both the main CPU SH4 compiler and the AICA sound processor ARM compiler, or we can skip the ARM compiler and just build the SH4 compiler. Thankfully, KallistiOS includes a prebuilt sound driver, so the ARM compiler is only necessary if you're wanting to make changes to the sound driver or write custom code to run on the sound processor.
To build '''only the SH4 compiler''':
make
To build '''both''' the SH4 and the ARM compilers:
make all
This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the commands above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths.

You will need to run the following command to apply the KOS environment settings to your currently running shell. Run the following now, '''and''' ''whenever'' you open a new shell to work on Dreamcast projects:
. /opt/toolchains/dc/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

Download and burn the [[:File:Dcload-2023-06-22.zip|latest versions of dcload-ip or dcload-serial]] -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>
* Alpine: <code>meson libisofs-dev</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Getting Started with Dreamcast development

2025-03-04T05:00:49Z

Darc: /* Need help? */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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 Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.1.1''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.1.x /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues:
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. At this point, we have the option of building both the main CPU SH4 compiler and the AICA sound processor ARM compiler, or we can skip the ARM compiler and just build the SH4 compiler. Thankfully, KallistiOS includes a prebuilt sound driver, so the ARM compiler is only necessary if you're wanting to make changes to the sound driver or write custom code to run on the sound processor.
To build '''only the SH4 compiler''':
make
To build '''both''' the SH4 and the ARM compilers:
make all
This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the commands above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths. Run the source command on the desired environ.sh file to select that configuration prior to compiling your project.

You will need to run the source command to apply the KOS 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/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

Download and burn the [[:File:Dcload-2023-06-22.zip|latest versions of dcload-ip or dcload-serial]] -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Hardware variations

2025-02-24T02:00:12Z

Darc:

The Dreamcast had three major hardware variations, usually referred to as v0, v1, or v2 consoles. U.S. and PAL consoles can be identified easily through the sticker on the bottom of the console, which will have the version number in a circle printed on it.

v0 consoles are known for their heatpipe cooling system, which can be identified by the metal fan shroud from the outside of the console. v0 consoles use 5V levels on the G1 bus, creating a compatibility issue with G1 devices designed for 3.3V levels. v0 units are more common in Japan. These models have a separate GD-ROM daughterboard.

v1 consoles are the most common in the United States and Europe, and are the most compatible with Dreamcast mods. These consoles have plastic fan shrouds, a 3.3V level G1 bus, and a separate GD-ROM daughterboard.

v2 consoles are less common, and have the GD-ROM functionality built directly into the motherboard, so the GD-ROM cannot be replaced with an [[Optical drive replacements|optical drive emulator]] device. They have plastic fan shrouds and 3.3V level G1 bus. Some later v2 consoles came fitted with firmware v1.022, which disables [[MIL-CD]] booting, so CD-based software like homebrew and indie games cannot be used without a [[BIOS modification]].

An unofficial variation of the console is the portable Chinese [[Treamcast]].

Creating a bootable Dreamcast disc

2025-02-15T20:24:32Z

Darc: /* Full Overview of the steps involved */

== Full Overview of the steps involved ==

The full list of steps to make self-bootable disc for the [[Dreamcast]] goes like this:

* Build your source (usually using [[KallistiOS]])
* Transform your .elf executable into binary
* Scramble the binary
* Build a .iso image from a directory (representing the ''second'' session of a multisession disc and not bootable)
* Transform the .iso into a .cdi image (representing a self-booting multisession disc image)
* Transfer the .cdi image to your GDEMU (or other optical disc drive emulator device), or burn the .cdi image to a CD-R to launch it in a standard Dreamcast.

There are other details that could be taken into account:
* You can make Audio/Data and Data/Data .cdi files. Both can selfboot, but the files will be organized differently on the physical CD. {{Citation needed}}
* You'll need to provide a valid [[IP.BIN]], these can be modified to display a logo during the boot screen, apply patches or execute some code.
* It is possible to make CDDA compatible images, this process in not currently covered here.

Depending on the method/tools used, some of the above steps are simplified a lot:
* mkdcdisc: does the heavy lifting for you. Linux only for now.
* mkisofs + cdi4dc
* mkisofs + cdrecord

== mkdcdisc (Linux only for now) ==

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] is a recent (2022) tool that pretty much does all the steps for you.

The minimum you need for it, is your executable .elf.

Example to build a bootable DC disc image nehe05.cdi, starting from an executable called nehe05.elf:
<syntaxhighlight lang="bash">
mkdcdisc -e nehe05.elf -o nehe05.cdi
</syntaxhighlight>

Example to build a bootable DC disc image mygame.cdi, starting from an executable called mygame.elf, with assets/textures/... files stored in a subfolder called "data":
<syntaxhighlight lang="bash">
mkdcdisc -e mygame.elf -D data -o mygame.cdi
</syntaxhighlight>

There are a lot of commandline options, so be sure to check them all out!

== mkisofs + cdi4dc ==

This is an example for automating the .cdi image process under Linux. Consider this more like a template as you'll need to edit the paths, names, etc to your own project.

#! /bin/sh
PROJECT_DIR=$PWD/build
PROJECT_NAME="Project_Name"
TARGET="main.elf"

# Build your program
# This assumes that you can properly build your source code. The program main output will be $TARGET
make $TARGET

# Elf transform
sh-elf-objcopy -R .stack -O binary $TARGET output.bin

# Scrambling process
$KOS_BASE/utils/scramble/scramble output.bin 1ST_READ.bin

# Creating a .iso image from a directory
# Make sure you have a working [[IP.BIN]] in your current directory. Or change IP.BIN path to wherever you like.
# Useful option for mkisofs is *-m* which allow to exclude files from the iso image (useful to remove .git, or some other folder)
mkisofs -C 0,11702 -V $PROJECT_NAME -G IP.BIN -r -J -l -o $PROJECT_NAME.iso $DIR

# Transform your .iso into a .cdi
$KOS_BASE/utils/cdi4dc/cdi4dc $PROJECT_NAME.iso $PROJECT_NAME.cdi

== mkisofs + cdrecord ==
TODO

Getting Started with Dreamcast development

2025-01-12T19:39:01Z

Darc: /* Building kos-ports */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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/RuKmpu7k Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.1.1''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.1.x /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues:
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. At this point, we have the option of building both the main CPU SH4 compiler and the AICA sound processor ARM compiler, or we can skip the ARM compiler and just build the SH4 compiler. Thankfully, KallistiOS includes a prebuilt sound driver, so the ARM compiler is only necessary if you're wanting to make changes to the sound driver or write custom code to run on the sound processor.
To build '''only the SH4 compiler''':
make
To build '''both''' the SH4 and the ARM compilers:
make all
This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the commands above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths. Run the source command on the desired environ.sh file to select that configuration prior to compiling your project.

You will need to run the source command to apply the KOS 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/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

Download and burn the [[:File:Dcload-2023-06-22.zip|latest versions of dcload-ip or dcload-serial]] -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Dcload-ip

2025-01-11T18:59:11Z

Darc:

dcload-ip is a homebrew program originally developed by Andrew Kieschnick, now maintained by [[KallistiOS]] developers and by [[SiZiOUS]] at the following repositories:

* [https://github.com/KallistiOS/dcload-serial KallistiOS dcload-ip repository]
* [https://github.com/sizious/dcload-ip SiZiOUS dcload-ip repository with enhancements]

It is the sister application to [[dcload-serial]].

It allows a developer to use a [[Broadband adapter]] or [[LAN adapter]] as a link to send, execute, and debug code on a Sega Dreamcast console. It is typically loaded via CD-R, but can also be loaded directly through the BIOS (for example, using [https://github.com/darcagn/DreamDash DreamDash]).

It is able to transfer .bin and .elf files (and srec files, if specially configured for it) over the BBA. It also provides chainloaded programs with a standard syscall interface for communicating with a networked PC. The program is mostly intended for homebrew development, but can also be used with special programs designed to make use of it like [https://github.com/zeldin/dc-virtcd Marcus Comstedt's dc-virtcd].

DiscJuggler images of the latest DC side software as of June 22, 2023 are available to download: [[:File:Dcload-2023-06-22.zip|DiscJuggler images of dcload-ip 2.0.1 and dcload-serial 1.0.6]]

{{DISPLAYTITLE:dcload-ip}}

Dcload-serial

2025-01-11T18:55:15Z

Darc:

dcload-serial is a homebrew program originally developed by Andrew Kieschnick, now maintained by [[KallistiOS]] developers at the [https://github.com/KallistiOS/dcload-serial dcload-serial repository]. It is the sister application to [[dcload-ip]].

It allows a developer to use a serial cable (also referred to as a "[[coder's cable]]") as a link to send, execute, and debug code on a Sega Dreamcast console. It is typically loaded via CD-R, but can also be loaded directly through the BIOS (for example, using [https://github.com/darcagn/DreamDash DreamDash]).

It is able to transfer .bin and .elf files (and srec files, if specially configured for it) over the serial port. It also provides chainloaded programs with a standard syscall interface for communicating with a connected PC. The program is mostly intended for homebrew development, but can also be used with special programs.

DiscJuggler images of the latest DC side software as of June 22, 2023 are available to download: [[:File:Dcload-2023-06-22.zip|DiscJuggler images of dcload-ip 2.0.1 and dcload-serial 1.0.6]]

{{DISPLAYTITLE:dcload-serial}}

Dcload-serial

2025-01-11T18:54:34Z

Darc:

dcload-serial is a homebrew program originally developped by Andrew Kieschnick, now maintained by [[KallistiOS]] developers at the [https://github.com/KallistiOS/dcload-serial dcload-serial repository]. It is the sister application to [[dcload-ip]].

It allows a developer to use a serial cable (also referred to as a "[[coder's cable]]") as a link to send, execute, and debug code on a Sega Dreamcast console. It is typically loaded via CD-R, but can also be loaded directly through the BIOS (for example, using [https://github.com/darcagn/DreamDash DreamDash]).

It is able to transfer .bin and .elf files (and srec files, if specially configured for it) over the serial port. It also provides chainloaded programs with a standard syscall interface for communicating with a connected PC. The program is mostly intended for homebrew development, but can also be used with special programs.

DiscJuggler images of the latest DC side software as of June 22, 2023 are available to download: [[:File:Dcload-2023-06-22.zip|DiscJuggler images of dcload-ip 2.0.1 and dcload-serial 1.0.6]]

{{DISPLAYTITLE:dcload-serial}}

Rust on Dreamcast

2025-01-02T01:19:15Z

Darc: Replaced content with "Ferris holding his Dreamcast controller '''Please visit [https://dreamcast.rs/ dreamcast.rs]!''' The Rust for Dreamcast documentation has now [https://dreamcast.rs been migrated into an mdBook]!"

[[File:Rust-dc-logo.png|thumb|Ferris holding his Dreamcast controller]]

'''Please visit [https://dreamcast.rs/ dreamcast.rs]!'''

The Rust for Dreamcast documentation has now [https://dreamcast.rs been migrated into an mdBook]!

Getting Started with Dreamcast development

2025-01-01T21:46:50Z

Darc: /* Cloning the KallistiOS git repository */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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/RuKmpu7k Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.1.1''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.1.x /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues:
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. At this point, we have the option of building both the main CPU SH4 compiler and the AICA sound processor ARM compiler, or we can skip the ARM compiler and just build the SH4 compiler. Thankfully, KallistiOS includes a prebuilt sound driver, so the ARM compiler is only necessary if you're wanting to make changes to the sound driver or write custom code to run on the sound processor.
To build '''only the SH4 compiler''':
make
To build '''both''' the SH4 and the ARM compilers:
make all
This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the commands above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths. Run the source command on the desired environ.sh file to select that configuration prior to compiling your project.

You will need to run the source command to apply the KOS 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/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

'''NOTE''': If you see the following error:
1 error(s) occurred during the build process:
/opt/toolchains/dc/kos/../kos-ports/libjimtcl: Build failed with return code 2
The error is safe to ignore as the <code>libjimtcl</code> kos-port is broken at this time. The rest should compile without issue with the default KOS settings.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

Download and burn the [[:File:Dcload-2023-06-22.zip|latest versions of dcload-ip or dcload-serial]] -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Getting Started with Dreamcast development

2024-12-31T05:43:27Z

Darc: /* Building kos-ports */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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/RuKmpu7k Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.1.0''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.1.x /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues:
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. At this point, we have the option of building both the main CPU SH4 compiler and the AICA sound processor ARM compiler, or we can skip the ARM compiler and just build the SH4 compiler. Thankfully, KallistiOS includes a prebuilt sound driver, so the ARM compiler is only necessary if you're wanting to make changes to the sound driver or write custom code to run on the sound processor.
To build '''only the SH4 compiler''':
make
To build '''both''' the SH4 and the ARM compilers:
make all
This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the commands above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths. Run the source command on the desired environ.sh file to select that configuration prior to compiling your project.

You will need to run the source command to apply the KOS 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/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

'''NOTE''': If you see the following error:
1 error(s) occurred during the build process:
/opt/toolchains/dc/kos/../kos-ports/libjimtcl: Build failed with return code 2
The error is safe to ignore as the <code>libjimtcl</code> kos-port is broken at this time. The rest should compile without issue with the default KOS settings.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

Download and burn the [[:File:Dcload-2023-06-22.zip|latest versions of dcload-ip or dcload-serial]] -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Rust on Dreamcast

2024-12-11T23:20:55Z

Darc: /* Examples */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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=
* The full '''std''' library is supported.
* 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-sys '''kos-sys'''] raw/unsafe bindings crate is provided for easily linking KallistiOS and its unsafe C API into Rust crates. This crate is in active development, but with a large portion of KallistiOS functionality available now via C FFI.
* A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] Rust crate with safe idiomatic interfaces is available but is in very early stages.
** 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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
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/hello <code>hello</code>] demonstrates how to create a simple "Hello, world!" application using cargo.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/gldc-cube <code>gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/romdisk <code>romdisk</code>] demonstrates how to generate and mount a read-only ROMdisk with a KallistiOS project.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/addlib <code>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/atomics <code>atomics</code>] demonstrates the use of atomic functions.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/filesystem-io <code>filesystem-io</code>] demonstrates listing directory contents and opening files.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/network-time <code>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/pvr/pvrmark_strips_direct <code>pvrmark_strips_direct</code>] demonstrates the use of PVR direct rendering
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/threads <code>threads</code>] demonstrates the use of threads.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/tokio-async <code>tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.

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

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
fn main() {
println!("Hello, world from Rust!");
}
</syntaxhighlight>

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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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/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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#[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
}
</syntaxhighlight>

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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Rust on Dreamcast

2024-12-11T23:04:27Z

Darc: /* Compiling individual modules into object files with rustc */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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=
* The full '''std''' library is supported.
* 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-sys '''kos-sys'''] raw/unsafe bindings crate is provided for easily linking KallistiOS and its unsafe C API into Rust crates. This crate is in active development, but with a large portion of KallistiOS functionality available now via C FFI.
* A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] Rust crate with safe idiomatic interfaces is available but is in very early stages.
** 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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
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/hello-cargo <code>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/hello-make <code>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/gldc-cube <code>gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/addlib <code>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/atomics <code>atomics</code>] demonstrates the use of atomic functions.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/filesystem-io <code>filesystem-io</code>] demonstrates listing directory contents and opening files.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/network-time <code>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/pvr_strips_direct <code>pvr_strips_direct</code>] demonstrates the use of PVR direct rendering
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/threads <code>threads</code>] demonstrates the use of threads.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/tokio-async <code>tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.

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

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
fn main() {
println!("Hello, world from Rust!");
}
</syntaxhighlight>

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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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/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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#[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
}
</syntaxhighlight>

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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Rust on Dreamcast

2024-11-27T01:19:01Z

Darc: /* Creating a Rust library */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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=
* The full '''std''' library is supported.
* 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-sys '''kos-sys'''] raw/unsafe bindings crate is provided for easily linking KallistiOS and its unsafe C API into Rust crates. This crate is in active development, but with a large portion of KallistiOS functionality available now via C FFI.
* A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] Rust crate with safe idiomatic interfaces is available but is in very early stages.
** 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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
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/hello-cargo <code>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/hello-make <code>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/gldc-cube <code>gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/addlib <code>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/atomics <code>atomics</code>] demonstrates the use of atomic functions.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/filesystem-io <code>filesystem-io</code>] demonstrates listing directory contents and opening files.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/network-time <code>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/pvr_strips_direct <code>pvr_strips_direct</code>] demonstrates the use of PVR direct rendering
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/threads <code>threads</code>] demonstrates the use of threads.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/tokio-async <code>tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.

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

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
fn main() {
println!("Hello, world from Rust!");
}
</syntaxhighlight>

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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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/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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#[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
}
</syntaxhighlight>

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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Rust on Dreamcast

2024-11-26T22:46:27Z

Darc: /* Installing our custom KallistiOS and GCC toolchain */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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=
* The full '''std''' library is supported.
* 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-sys '''kos-sys'''] raw/unsafe bindings crate is provided for easily linking KallistiOS and its unsafe C API into Rust crates. This crate is in active development, but with a large portion of KallistiOS functionality available now via C FFI.
* A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] Rust crate with safe idiomatic interfaces is available but is in very early stages.
** 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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
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/hello-cargo <code>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/hello-make <code>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/gldc-cube <code>gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/addlib <code>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/atomics <code>atomics</code>] demonstrates the use of atomic functions.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/filesystem-io <code>filesystem-io</code>] demonstrates listing directory contents and opening files.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/network-time <code>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/pvr_strips_direct <code>pvr_strips_direct</code>] demonstrates the use of PVR direct rendering
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/threads <code>threads</code>] demonstrates the use of threads.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/tokio-async <code>tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.

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

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
fn main() {
println!("Hello, world from Rust!");
}
</syntaxhighlight>

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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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/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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#[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
}
</syntaxhighlight>

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> as this is a library which wouldn't have a <code>main()</code> 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 <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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Rust on Dreamcast

2024-11-25T18:00:06Z

Darc: /* Installing our custom KallistiOS and GCC toolchain */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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=
* The full '''std''' library is supported.
* 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-sys '''kos-sys'''] raw/unsafe bindings crate is provided for easily linking KallistiOS and its unsafe C API into Rust crates. This crate is in active development, but with a large portion of KallistiOS functionality available now via C FFI.
* A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] Rust crate with safe idiomatic interfaces is available but is in very early stages.
** 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.

=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 [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.''

==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 sh_gcc_git_branch=master-88b2da3c175d34d65415f69961420f35ac1a1c56
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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
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/hello-cargo <code>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/hello-make <code>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/gldc-cube <code>gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/addlib <code>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/atomics <code>atomics</code>] demonstrates the use of atomic functions.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/filesystem-io <code>filesystem-io</code>] demonstrates listing directory contents and opening files.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/network-time <code>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/pvr_strips_direct <code>pvr_strips_direct</code>] demonstrates the use of PVR direct rendering
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/threads <code>threads</code>] demonstrates the use of threads.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/tokio-async <code>tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.

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

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
fn main() {
println!("Hello, world from Rust!");
}
</syntaxhighlight>

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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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/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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#[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
}
</syntaxhighlight>

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> as this is a library which wouldn't have a <code>main()</code> 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 <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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Rust on Dreamcast

2024-11-22T00:28:19Z

Darc: /* Creating a new Rust project with Cargo */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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=
* The full '''std''' library is supported.
* 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-sys '''kos-sys'''] raw/unsafe bindings crate is provided for easily linking KallistiOS and its unsafe C API into Rust crates. This crate is in active development, but with a large portion of KallistiOS functionality available now via C FFI.
* A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] Rust crate with safe idiomatic interfaces is available but is in very early stages.
** 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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
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/hello-cargo <code>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/hello-make <code>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/gldc-cube <code>gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/addlib <code>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/atomics <code>atomics</code>] demonstrates the use of atomic functions.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/filesystem-io <code>filesystem-io</code>] demonstrates listing directory contents and opening files.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/network-time <code>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/pvr_strips_direct <code>pvr_strips_direct</code>] demonstrates the use of PVR direct rendering
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/threads <code>threads</code>] demonstrates the use of threads.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/tokio-async <code>tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.

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

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
fn main() {
println!("Hello, world from Rust!");
}
</syntaxhighlight>

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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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/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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#[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
}
</syntaxhighlight>

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> as this is a library which wouldn't have a <code>main()</code> 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 <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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Rust on Dreamcast

2024-11-14T14:04:10Z

Darc: /* Examples */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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=
* The full '''std''' library is supported.
* 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-sys '''kos-sys'''] raw/unsafe bindings crate is provided for easily linking KallistiOS and its unsafe C API into Rust crates. This crate is in active development, but with a large portion of KallistiOS functionality available now via C FFI.
* A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] Rust crate with safe idiomatic interfaces is available but is in very early stages.
** 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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
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/hello-cargo <code>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/hello-make <code>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/gldc-cube <code>gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/addlib <code>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/atomics <code>atomics</code>] demonstrates the use of atomic functions.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/filesystem-io <code>filesystem-io</code>] demonstrates listing directory contents and opening files.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/network-time <code>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/pvr_strips_direct <code>pvr_strips_direct</code>] demonstrates the use of PVR direct rendering
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/threads <code>threads</code>] demonstrates the use of threads.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/tokio-async <code>tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.

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

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
#![no_main]

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

0
}
</syntaxhighlight>

* <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> tells Rust that we will not have Rust use a <code>main</code> function as an entry point -- this will be handled by KallistiOS.
* <syntaxhighlight lang="rust" inline>#[no_mangle]</syntaxhighlight> tells Rust to disable name mangling so that the <code>main</code> function can be used by KallistiOS's C code.
* 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>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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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/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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#[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
}
</syntaxhighlight>

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> as this is a library which wouldn't have a <code>main()</code> 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 <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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Programming language support

2024-11-14T03:59:57Z

Darc: /* Compiled languages */

The following languages can be used in Sega Dreamcast programming:

=Assembly languages=
* '''SH4 assembly''', as the native machine code for the Dreamcast's SuperH processor
* '''ARM assembly''', as the native machine code for the Dreamcast's AICA ARM7DI sound processor

=Compiled languages=
* '''C''', the predominant language for Sega Dreamcast development, via the GCC C compiler.
* '''C++''', commonly used and very well-supported, via the GCC C++ compiler.
* '''Objective-C''', via the GCC Objective-C compiler. Preliminary support for Foundation framework via [https://gnustep.github.io/ GNUstep] is being developed. See [https://twitter.com/dinobj_c/status/1732399498977276154 Andrew Apperley's X account]. See [[Objective-C on Dreamcast]] for more information.
** The GNU '''Objective-C++''' extension is available as well.
* '''Rust''', via rustc_codegen_gcc and libgccjit, or via gccrs. When using rustc_codegen_gcc, the standard library is available, with bindings to KallistiOS being developed. See [[Rust on Dreamcast]] for more information.
* '''D''', via the GCC D compiler. Early support, see [https://dreamcast.wiki/D_on_Dreamcast D on Dreamcast] for more information.
* '''Ada''', via GNAT. [https://github.com/dkm/ada-dreamcast-helloworld Ada 3D cube demo] by [https://poulhies.fr/ Marc Poulhiès].
* '''Fortran''', via GFortran. Requires some work to create a cross-compiler, but does work.

=Scripting/Interpreted languages=
* Lua (available in [[kos-ports]])
* MicroPython (available in [[kos-ports]])
* Tcl (available in [[kos-ports]])
* mRuby (available in [[kos-ports]])
* AngelScript
* QuickJS

Rust on Dreamcast

2024-11-14T01:07:38Z

Darc: /* Current Status */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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=
* The full '''std''' library is supported.
* 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-sys '''kos-sys'''] raw/unsafe bindings crate is provided for easily linking KallistiOS and its unsafe C API into Rust crates. This crate is in active development, but with a large portion of KallistiOS functionality available now via C FFI.
* A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] Rust crate with safe idiomatic interfaces is available but is in very early stages.
** 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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
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/hello-cargo <code>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/hello-make <code>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/gldc-cube <code>gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/addlib <code>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/atomics <code>atomics</code>] demonstrates the use of atomic functions.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/filesystem-io <code>filesystem-io</code>] demonstrates listing directory contents and opening files.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/network-time <code>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/threads <code>threads</code>] demonstrates the use of threads.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/tokio-async <code>tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.

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

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
#![no_main]

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

0
}
</syntaxhighlight>

* <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> tells Rust that we will not have Rust use a <code>main</code> function as an entry point -- this will be handled by KallistiOS.
* <syntaxhighlight lang="rust" inline>#[no_mangle]</syntaxhighlight> tells Rust to disable name mangling so that the <code>main</code> function can be used by KallistiOS's C code.
* 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>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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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/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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#[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
}
</syntaxhighlight>

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> as this is a library which wouldn't have a <code>main()</code> 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 <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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Rust on Dreamcast

2024-11-14T01:06:44Z

Darc: /* Current Status */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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=
* The full '''std''' library is supported.
* 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-sys '''kos-sys'''] raw/unsafe bindings crate is provided for easily linking KallistiOS and its unsafe C API into Rust crates. This crate is in active development, but with a large portion of KallistiOS functionality available now via C FFI.
* A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] Rust crate is available but is also in early stages.
** 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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
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/hello-cargo <code>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/hello-make <code>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/gldc-cube <code>gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/addlib <code>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/atomics <code>atomics</code>] demonstrates the use of atomic functions.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/filesystem-io <code>filesystem-io</code>] demonstrates listing directory contents and opening files.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/network-time <code>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/threads <code>threads</code>] demonstrates the use of threads.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/tokio-async <code>tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.

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

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
#![no_main]

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

0
}
</syntaxhighlight>

* <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> tells Rust that we will not have Rust use a <code>main</code> function as an entry point -- this will be handled by KallistiOS.
* <syntaxhighlight lang="rust" inline>#[no_mangle]</syntaxhighlight> tells Rust to disable name mangling so that the <code>main</code> function can be used by KallistiOS's C code.
* 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>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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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/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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#[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
}
</syntaxhighlight>

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> as this is a library which wouldn't have a <code>main()</code> 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 <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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Getting Started with Dreamcast development

2024-11-10T19:40:53Z

Darc: /* Cloning the KallistiOS git repository */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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/RuKmpu7k Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.1.0''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.1.x /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues:
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. At this point, we have the option of building both the main CPU SH4 compiler and the AICA sound processor ARM compiler, or we can skip the ARM compiler and just build the SH4 compiler. Thankfully, KallistiOS includes a prebuilt sound driver, so the ARM compiler is only necessary if you're wanting to make changes to the sound driver or write custom code to run on the sound processor.
To build '''only the SH4 compiler''':
make
To build '''both''' the SH4 and the ARM compilers:
make all
This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the commands above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths. Run the source command on the desired environ.sh file to select that configuration prior to compiling your project.

You will need to run the source command to apply the KOS 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/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

Download and burn the [[:File:Dcload-2023-06-22.zip|latest versions of dcload-ip or dcload-serial]] -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Rust on Dreamcast

2024-11-10T03:21:19Z

Darc: /* Current Status */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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=
* The full '''std''' library is supported.
* 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-sys '''kos-sys'''] raw/unsafe bindings crate is provided for easily linking KallistiOS and its unsafe C API into Rust crates. This crate is in early stages and in active development.
* A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] Rust crate is available but is also in early stages.
** 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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
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/hello-cargo <code>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/hello-make <code>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/gldc-cube <code>gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/addlib <code>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/atomics <code>atomics</code>] demonstrates the use of atomic functions.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/filesystem-io <code>filesystem-io</code>] demonstrates listing directory contents and opening files.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/network-time <code>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/threads <code>threads</code>] demonstrates the use of threads.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/tokio-async <code>tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.

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

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
#![no_main]

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

0
}
</syntaxhighlight>

* <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> tells Rust that we will not have Rust use a <code>main</code> function as an entry point -- this will be handled by KallistiOS.
* <syntaxhighlight lang="rust" inline>#[no_mangle]</syntaxhighlight> tells Rust to disable name mangling so that the <code>main</code> function can be used by KallistiOS's C code.
* 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>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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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/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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#[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
}
</syntaxhighlight>

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> as this is a library which wouldn't have a <code>main()</code> 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 <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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Getting Started with Dreamcast development

2024-11-09T13:03:05Z

Darc: /* Building the KOS examples */

<div style="float:right;">__TOC__</div>
=Introduction=
This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link (serial or IP) and self-booting CD-R. This guide will cover the process for the following platforms:
* '''Microsoft Windows 10''' via [https://learn.microsoft.com/en-us/windows/wsl/about Windows Subsystem for Linux]
** Users desiring a native Windows approach, see [[DreamSDK]] instead
* '''macOS''' on Intel or Apple Silicon systems with the [https://brew.sh/ Homebrew] package manager installed
* '''Linux'''-based systems
** '''Debian'''- and '''Ubuntu'''-based distributions using the default '''apt''' package manger
** '''Fedora'''-based distributions using the default '''dnf''' package manager
** '''Arch'''-based distributions using the default '''pacman''' package manager
** '''Alpine'''-based distributions using the default '''apk''' package manager

===Need help?===
Important note: ''This guide aims to remain up to date and work on all of the above platforms, but keeping instructions for such a variety of platforms up-to-date can be difficult. 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/RuKmpu7k Discord chat] and we would be happy to aid you and update the guide for the benefit of future readers and others in the community.''

===Terms===
Before we get started, let's define several terms:

The '''toolchain''' is a set of programs which turns your code into an executable file for your Dreamcast console. The toolchain includes:
* '''GCC''', a compiler which supports C, C++, Objective-C, and more (see also [[Rust on Dreamcast]] and [[Programming language support]])
* '''binutils''', an assembler and linker
* '''newlib''', a C library
* '''gdb''', a debugger
The toolchain includes a compiler for the Dreamcast's main SH4 CPU, and optionally a compiler for the ARM-based AICA sound processor. Your operating system may already have versions of these programs installed to compile code for your computer, but we will need to build a "cross-compiler" for compiling specifically for the Dreamcast.

'''KallistiOS''' or ''KOS'' is an open source development library and pseudo-operating system for the Dreamcast console. It is the best documented and most widely used development kit in the homebrew community. KallistiOS's very flexible license allows both homebrew and commercial use with no restrictions other than a requirement to include credit for its use in your project, and indeed almost all commercially sold indie Dreamcast titles use it. There are others in existence, like [[libronin]] and [[libdream]], as well as the older development kits [[Katana]] and [[Windows CE]] created by Sega and Microsoft for use in retail games, but this guide will only cover the setup and use of KallistiOS.

'''kos-ports''' is a repository including various libraries which integrate with KallistiOS. We will download and compile these libraries as well.

The '''debug link''' is a generic term referring to a hardware accessory to facilitate quickly running and debugging your programs. IP-based links include the Dreamcast's '''[[Broadband adapter]]''' and '''[[LAN adapter]]''' accessories, and serial-based links include the [[Coder's cable]], which is a cable that can connect the Dreamcast's serial port to your computer via USB or serial. This guide includes instructions for setting up and using the the Broadband adapter and a USB-based coder's cable.

'''dc-tool''' and '''dcload''' are a pair of programs to facilitate using a debug link. ''dc-tool'' runs on your computer and links to a Dreamcast running ''dcload-ip'' or ''dcload-serial''. With this setup, you can quickly load programs, read console feedback, load assets, transfer data, redirect I/O, handle exceptions, debug problems, and so forth.

=Choosing a debug link solution=
If you are building the toolchain for the purpose of building existing programs from source with little to no modifications, then a debug link setup might not be necessary for you. You may simply build programs to burn directly to CD-R. However, if you are planning to actively develop for the Dreamcast, then a debug link is a critical component. While Dreamcast emulators are mature and accurate enough to play the vast majority of the system's games library without issue, many critical bugs may show up on a real Dreamcast system, but not on a Dreamcast emulator. Therefore, it is highly recommended to test on a real system as much as possible. It's also possible to load software off of a [[Serial SD card adapter]], but without an active link to a computer, debugging and stepping through programs as they execute is significantly more challenging.

Presented below is a table comparing the different options available for a debug link. Due to the cost, potential buyers may want to factor in the ability to play multiplayer games with their purchase. Thus, for comparison, we have included information about the [[Modem]] with [[DreamPi]] as well, but understand that the Modem with DreamPi cannot be used as a debug link.

{| class="wikitable"
!colspan="6" |Comparison of various Dreamcast connectivity options
|-
|style="background-color:#c0c0c0;" width="150" | Device:
|style="background-color:#d0d0d0;" width="400" | [[Broadband adapter]] (HIT-400 or HIT-401) <br />Realtek RTL8139C chipset
|style="background-color:#d0d0d0;" width="400" | [[LAN adapter]] (HIT-300) <br />Fujitsu MB86967 chipset
|style="background-color:#d0d0d0;" width="400" | [[Modem]] with [[DreamPi]]
|style="background-color:#d0d0d0;" width="400" | USB [[Coder's cable]]
|style="background-color:#d0d0d0;" width="400" | Serial [[Coder's cable]]
|-
|style="background-color:#d0d0d0;" | Useful for dev? || Yes, supports dcload-ip || Yes, supports dcload-ip,<br/>but BBA is superior and cheaper || No, only useful for online multiplayer gaming || Yes, supports dcload-serial || Yes, supports dcload-serial
|-
|style="background-color:#d0d0d0;" | Cost || $100 - $200 and up on used markets || $200 and up on used markets,<br/>due to extreme rarity || Kit prices vary, around $100 || See [[Coder's cable]] for vendors<br />darc sells for $45, RetroOnyx sells for $85 || Varies on used markets, uncommonly sold
|-
|style="background-color:#d0d0d0;" | Can make DIY? || No || No || Yes || Yes || Yes
|-
|style="background-color:#d0d0d0;" | Performance || Up to 100 megabits/s || Up to 10 megabits/s || Up to 56 kilobits/s || Up to 1500 kilobits/s || Up to 120 kilobits/s
|-
|style="background-color:#d0d0d0;" | Games support || Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament<br />Some browsers: Broadband Passport, PlanetWeb 3.0 || No games<br />One browser: Dream Passport for LAN || All multiplayer games with network support<br />All web browsers || NO multiplayer games support || NO multiplayer games support
|-
|style="background-color:#d0d0d0;" | Homebrew support || Homebrew utilities like dcload-ip || Homebrew utilities like dcload-ip || Homebrew utilities don't support, only multiplayer games || Homebrew utilities like dcload-serial || Homebrew utilities like dcload-serial
|}

=Setting up and compiling the toolchain with the dc-chain script=
===Dependencies===
First, we'll need to install dependencies before building the toolchain. Below we have provided commands to install these dependencies on various systems. Many of the packages will likely already be installed on your system, but we have provided an exhaustive list for good measure.
====macOS 13 Ventura on an Intel or Apple Silicon processor====
First, make sure you install Apple Xcode, including the Command Line tools. You will also need to install several other packages for which we'll include instructions assuming you have installed the [https://brew.sh/ Homebrew] package manager on your system.
brew install wget gettext texinfo gmp mpfr libmpc libelf jpeg-turbo libpng cmake meson libisofs

''Important Note for Apple Silicon users'': On Apple Silicon, Homebrew installs libraries to a path not included by default by the compiler. If you haven't added these to your '''~/.zprofile''', then add the following lines now and reload your session (or run them in your Terminal session whenever you compile KOS):
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

====Debian/Ubuntu-based Linux====
sudo apt-get update
sudo apt install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl libjpeg-dev libpng-dev python3 pkg-config cmake libisofs-dev meson ninja-build rake

====Fedora-based Linux====
sudo dnf install gawk patch bzip2 tar make gmp-devel mpfr-devel libmpc-devel gettext wget elfutils-libelf-devel texinfo bison flex sed git diffutils curl libjpeg-turbo-devel libpng-devel gcc-c++ python3 rubygem-rake meson ninja-build

====Arch-based Linux====
sudo pacman -S --needed gawk patch bzip2 tar make gmp mpfr libmpc gettext wget libelf texinfo bison flex sed git diffutils curl libjpeg-turbo libpng python3 meson ruby-rake

====Alpine-based Linux====
sudo apk --update add build-base patch bash texinfo gmp-dev libjpeg-turbo-dev libpng-dev elfutils-dev curl wget python3 git ruby-rake

====Other Linux distributions====
If you're using a different Linux- or Unix-based system besides the one above, you may need to reference your distribution's package database and package manager documentation for the equivalent package names and commands necessary for your system.

===Creating a space for your toolchain installation===
Create the path where we'll install the toolchain and KOS, and grant it the proper permissions:
sudo mkdir -p /opt/toolchains/dc
sudo chmod -R 755 /opt/toolchains/dc
sudo chown -R $(id -u):$(id -g) /opt/toolchains/dc
===Cloning the KallistiOS git repository===
Next, clone the git repository for the latest '''2.1.0''' stable version of KallistiOS:
git clone https://github.com/KallistiOS/KallistiOS.git -b v2.1.0 /opt/toolchains/dc/kos

Alternatively, you may clone the latest unstable version, which contains the latest changes, but may also contain bugs or issues:
git clone https://github.com/KallistiOS/KallistiOS.git -b master /opt/toolchains/dc/kos

===Configuring the dc-chain script===
Enter the dc-chain directory:
cd /opt/toolchains/dc/kos/utils/dc-chain

You may now configure the options to your liking by creating a <code>Makefile.cfg</code> file in this directory. Copy or rename the <code>Makefile.default.cfg</code> file to <code>Makefile.cfg</code> and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the <code>makejobs</code> option to the number of threads available on your CPU to speed up the compilation. However, if you run into errors during compilation, you may want to set <code>makejobs=1</code>, as on some operating systems the toolchain may fail to build with a higher setting.

We will leave the default '''stable''' profile for the toolchain, which currently uses GCC 13.2. For advanced users, other profiles are available to you; read the <code>README.md</code> file in the dc-chain directory for more information if you are interested. If you are unsure about options in the <code>Makefile.cfg</code>, just leave the defaults alone.

===Downloading and compiling the toolchain===
Now we will run a script to download files and compile the toolchain. At this point, we have the option of building both the main CPU SH4 compiler and the AICA sound processor ARM compiler, or we can skip the ARM compiler and just build the SH4 compiler. Thankfully, KallistiOS includes a prebuilt sound driver, so the ARM compiler is only necessary if you're wanting to make changes to the sound driver or write custom code to run on the sound processor.
To build '''only the SH4 compiler''':
make
To build '''both''' the SH4 and the ARM compilers:
make all
This will download and unpack the relevant necessary files and then begin the compilation process. The compilation can take anywhere from minutes to a few hours depending on your CPU and number of threads available. When successfully finished, the toolchains will be ready. If you used the commands above, the '''gdb''' debugger will have been built as well.

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

=Configuring and compiling KOS and kos-ports=
===Setting up the environment settings===
Enter the KOS directory:
cd /opt/toolchains/dc/kos
Copy the pre-made environment script into place:
cp doc/environ.sh.sample environ.sh
For most users, the default settings will suffice. However, advanced users may edit the environ.sh to your liking if you'd like to change compile flags or alter paths. If you'd like to have multiple KOS versions installed or multiple toolchain versions installed, you can set up different environ.sh files corresponding to these different configurations by altering the paths. Run the source command on the desired environ.sh file to select that configuration prior to compiling your project.

You will need to run the source command to apply the KOS 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/kos/environ.sh

===Building KOS===
Build KOS:
make
KOS is now built.
===Building kos-ports===
Clone the kos-ports repository to your system:
git clone --recursive https://github.com/KallistiOS/kos-ports /opt/toolchains/dc/kos-ports
Run the script to build all of the included ports:
/opt/toolchains/dc/kos-ports/utils/build-all.sh
kos-ports is now built.

===Building the KOS examples===
Enter the KOS examples directory:
cd /opt/toolchains/dc/kos/examples
Build the examples:
make
All of the example programs provided with KallistiOS are now built.

=Further=
At this point, you will have a cross-compiler built so that you can generate programs for your Dreamcast from code. KallistiOS, the Dreamcast development library and operating system, is built, as is its associated packages within kos-ports, and all of its example programs.

At this point, you will likely want to view some of the following articles:
* Setting up an IDE for Dreamcast development
** [[CLion Debugging]]
** [[Visual Studio Code]]
* [[Creating a first project with KallistiOS]] ('''TODO''': Explain how to create a new DC project folder with Makefile, adding an external library, create a basic program, and compile it)
* [[Using a debug link]]
* [[Burning an example to CD-R]]

=Running an example program through a debug link=
'''TODO''': ''Give a tutorial on compiling dcload/dc-tool, setting up a serial, USB, or IP debug link, and running 2ndmix demo on real hardware.''

Download and burn the [[:File:Dcload-2023-06-22.zip|latest versions of dcload-ip or dcload-serial]] -- the IP version includes improved DHCP support, so there is no longer a need to configure things beforehand.

Run one of the examples from the <code>kos/examples/dreamcast</code> directory with one of the following commands:
dc-tool-ip -t <dreamcast IP address> -x example.elf

dc-tool-ser -t <serial device path> -x example.elf

Run <code>dc-tool-ip</code> or <code>dc-tool-ser</code> without any parameters to get additional options.

=Burning an example program to CD-R=
'''TODO''': ''Explain how to build mkdcdisc and write 2ndmix demo to CD-R and run on a Dreamcast console''

[https://gitlab.com/simulant/mkdcdisc mkdcdisc] can be used to easily generate a burnable self-boot CDI image.
Dependencies required:
* Homebrew: <code>meson libisofs pkg-config</code>
* Debian/Ubuntu: <code>libisofs-dev meson ninja-build</code>
* Fedora: <code>meson ninja-build</code>
* Arch: <code>meson</code>

Build <code>mkdcdisc</code>:
git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup builddir
meson compile -C builddir
./builddir/mkdcdisc -h
and create a CDI image from your compiled ELF like so:
mkdcdisc -e MyProgram.elf -o MyProgram.cdi
Then you can burn the CDI file using DiscJuggler (Windows-only, but also works through [https://www.winehq.org/ WINE]), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)

Rust on Dreamcast

2024-11-09T03:36:04Z

Darc: /* Examples */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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=
* The full '''std''' library is supported.
* 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-sys '''kos-sys'''] raw/unsafe bindings crate is provided for easily linking KallistiOS and its unsafe C API into Rust crates. This crate is in early stages and in active development.
& A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] Rust crate is available but is also in early stages.
** 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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
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/hello-cargo <code>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/hello-make <code>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/gldc-cube <code>gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/addlib <code>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/atomics <code>atomics</code>] demonstrates the use of atomic functions.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/filesystem-io <code>filesystem-io</code>] demonstrates listing directory contents and opening files.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/network-time <code>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/threads <code>threads</code>] demonstrates the use of threads.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/tokio-async <code>tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.

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

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
#![no_main]

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

0
}
</syntaxhighlight>

* <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> tells Rust that we will not have Rust use a <code>main</code> function as an entry point -- this will be handled by KallistiOS.
* <syntaxhighlight lang="rust" inline>#[no_mangle]</syntaxhighlight> tells Rust to disable name mangling so that the <code>main</code> function can be used by KallistiOS's C code.
* 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>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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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/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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#[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
}
</syntaxhighlight>

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> as this is a library which wouldn't have a <code>main()</code> 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 <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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Rust on Dreamcast

2024-11-09T03:35:42Z

Darc:

[[File:Rust-dc-logo.png|thumb|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 [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''', 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=
* The full '''std''' library is supported.
* 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-sys '''kos-sys'''] raw/unsafe bindings crate is provided for easily linking KallistiOS and its unsafe C API into Rust crates. This crate is in early stages and in active development.
& A [https://github.com/dreamcast-rs/kos-rs '''kos-rs'''] Rust crate is available but is also in early stages.
** 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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
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/hello-cargo <code>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/hello-make <code>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/gldc-cube <code>gldc-cube</code>] demonstrates a Rust project using the GLdc KOS port.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/addlib <code>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/atomics <code>atomics</code>] demonstrates the use of atomic functions.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/filesystem-io <code>filesystem-io</code>] demonstrates listing directory contents and opening files.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/network-time <code>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>threads</code>] demonstrates the use of threads.
* [https://github.com/dreamcast-rs/rust-for-dreamcast/tree/master/examples/tokio-async <code>tokio-async</code>] demonstrates the use of the '''tokio''' async runtime.

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

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
#![no_main]

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

0
}
</syntaxhighlight>

* <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> tells Rust that we will not have Rust use a <code>main</code> function as an entry point -- this will be handled by KallistiOS.
* <syntaxhighlight lang="rust" inline>#[no_mangle]</syntaxhighlight> tells Rust to disable name mangling so that the <code>main</code> function can be used by KallistiOS's C code.
* 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>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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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/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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#[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
}
</syntaxhighlight>

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> as this is a library which wouldn't have a <code>main()</code> 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 <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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Rust on Dreamcast

2024-10-29T22:29:56Z

Darc: /* Creating a Rust project using kos-ports libraries */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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 [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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
Examples are included with the Rust for Dreamcast repo to help you get started.
* '''no_std''' examples:
** [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/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==
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.

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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 <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">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs", default-features = false }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
#![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
}
</syntaxhighlight>

* <syntaxhighlight lang="rust" inline>#![no_std]</syntaxhighlight> and <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> tell Rust that our project does not use the standard library and we will not have Rust use a <code>main</code> function as an entry point -- this will be handled by KallistiOS.
* <syntaxhighlight lang="rust" inline>extern crate alloc;</syntaxhighlight> tells Rust to use the alloc crate to gain access to heap-allocated types (in our case, <code>String</code>).
* <syntaxhighlight lang="rust" inline>use kos::println!;</syntaxhighlight> tells Rust to use the <code>println!</code> macro defined in the kos-rs crate. With this, we can print output to our <code>dc-tool</code> console.
* <syntaxhighlight lang="rust" inline>#[no_mangle]</syntaxhighlight> tells Rust to disable name mangling so that the <code>main</code> function can be used by KallistiOS.
* 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>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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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.

==Creating a Rust library==
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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#![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
}
</syntaxhighlight>

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> as this is a library which wouldn't have a <code>main()</code> 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 <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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Rust on Dreamcast

2024-10-25T16:23:26Z

Darc:

[[File:Rust-dc-logo.png|thumb|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 [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''', 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 [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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
Examples are included with the Rust for Dreamcast repo to help you get started.
* '''no_std''' examples:
** [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/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==
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.

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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 <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">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs", default-features = false }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
#![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
}
</syntaxhighlight>

* <syntaxhighlight lang="rust" inline>#![no_std]</syntaxhighlight> and <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> tell Rust that our project does not use the standard library and we will not have Rust use a <code>main</code> function as an entry point -- this will be handled by KallistiOS.
* <syntaxhighlight lang="rust" inline>extern crate alloc;</syntaxhighlight> tells Rust to use the alloc crate to gain access to heap-allocated types (in our case, <code>String</code>).
* <syntaxhighlight lang="rust" inline>use kos::println!;</syntaxhighlight> tells Rust to use the <code>println!</code> macro defined in the kos-rs crate. With this, we can print output to our <code>dc-tool</code> console.
* <syntaxhighlight lang="rust" inline>#[no_mangle]</syntaxhighlight> tells Rust to disable name mangling so that the <code>main</code> function can be used by KallistiOS.
* 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>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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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. The declarations are preceded by <syntaxhighlight lang="rust" inline>#[link(name = "GL")]</syntaxhighlight> to tell Rust to link in '''libGL''' (GLdc). Since the entirety of the 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.

==Creating a Rust library==
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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#![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
}
</syntaxhighlight>

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> as this is a library which wouldn't have a <code>main()</code> 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 <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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>

Rust on Dreamcast

2024-10-25T15:18:43Z

Darc: /* Current Status */

[[File:Rust-dc-logo.png|thumb|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 [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''', 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 [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.

=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 [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.''

==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.

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 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 <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=
If all went well, you will now have a working Rust for Dreamcast environment!

* '''cargo''' can be invoked to target Dreamcast using the <code>kos-cargo</code> command.
** <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).
* '''rustc''' can be invoked to target Dreamcast using the <code>kos-rustc</code> command.

==Examples==
Examples are included with the Rust for Dreamcast repo to help you get started.
* '''no_std''' examples:
** [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/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==
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.

In a directory of your choosing, let's invoke <code>kos-cargo</code> 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. Open <code>Cargo.toml</code> in your text editor and add:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", git = "https://github.com/dreamcast-rs/kos-rs" }</syntaxhighlight>

Now we can open up <code>src/main.rs</code> and write our "Hello, world!" example code:
<syntaxhighlight lang="rust" line>
#![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
}
</syntaxhighlight>

* <syntaxhighlight lang="rust" inline>#![no_std]</syntaxhighlight> and <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> tell Rust that our project does not use the standard library and we will not have Rust use a <code>main</code> function as an entry point -- this will be handled by KallistiOS.
* <syntaxhighlight lang="rust" inline>extern crate alloc;</syntaxhighlight> tells Rust to use the alloc crate to gain access to heap-allocated types (in our case, <code>String</code>).
* <syntaxhighlight lang="rust" inline>use kos::println!;</syntaxhighlight> tells Rust to use the <code>println!</code> macro defined in the kos-rs crate. With this, we can print output to our <code>dc-tool</code> console.
* <syntaxhighlight lang="rust" inline>#[no_mangle]</syntaxhighlight> tells Rust to disable name mangling so that the <code>main</code> function can be used by KallistiOS.
* 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>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 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==
[[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/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.

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">
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!");
}
</syntaxhighlight>
The texture files are then included in our project using the <syntaxhighlight lang="rust" inline>include_bytes!</syntaxhighlight> 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 <code>build.rs</code> like so:
<syntaxhighlight lang="rust">
println!("cargo:rustc-link-search=native={}", lib_path);
</syntaxhighlight>

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. The declarations are preceded by <syntaxhighlight lang="rust" inline>#[link(name = "GL")]</syntaxhighlight> to tell Rust to link in '''libGL''' (GLdc). Since the entirety of the 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.

==Creating a Rust library==
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">
[lib]
crate-type = ["staticlib"]
</syntaxhighlight>

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

<syntaxhighlight lang="rust" line>
#![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
}
</syntaxhighlight>

The source code here starts similarly to the "Hello, world!" example, except we don't need to specify <syntaxhighlight lang="rust" inline>#![no_main]</syntaxhighlight> as this is a library which wouldn't have a <code>main()</code> 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 <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>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>:
<syntaxhighlight lang="make">
$(TARGET): $(OBJS)
kos-cc -o $(TARGET) $(OBJS) -L/opt/toolchains/dc/rust/examples/cargo-addlib/target/sh-elf/debug -laddlib
</syntaxhighlight>

Then, we can use the code in our C source:
<syntaxhighlight lang="c">
/* 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));
</syntaxhighlight>

==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/no_std/hello-make <code>hello-make</code>] example.

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">
OBJS = hello_c.o hello_rust.o
</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.

==Using the std library with KallistiOS==
When using the Rust '''std''' library in your project, be sure to enable the <code>std</code> feature in '''kos-rs''' in your <code>Cargo.toml</code>:
<syntaxhighlight lang="toml">
[dependencies]
kos = { package = "kos-rs", features = ["std"], git = "https://github.com/dreamcast-rs/kos-rs" }
</syntaxhighlight>
If the <code>std</code> feature is not enabled for the '''kos-rs''' crate, there will be errors with conflicting definitions.

==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 <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>

==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.
* To pass arguments to the '''rustc''' frontend, e.g. to disable debug assertions:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cdebug-assertions=no"</syntaxhighlight>
* To pass arguments to the GCC backend, e.g. to enable the <code>-freorder-blocks-algorithm=simple</code> optimization for Rust code:
** <syntaxhighlight lang="bash" inline>export KOS_RCG_RUSTFLAGS="${KOS_RCG_RUSTFLAGS} -Cllvm-args=-freorder-blocks-algorithm=simple"</syntaxhighlight>