Getting Started with Dreamcast development

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 Windows Subsystem for Linux
  • Users desiring a native Windows approach, see DreamSDK instead
• macOS on Intel or Apple Silicon systems with the 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 message board or 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.

Comparison of various Dreamcast connectivity options
Device:	Broadband adapter (HIT-400 or HIT-401) Realtek RTL8139C chipset	LAN adapter (HIT-300) Fujitsu MB86967 chipset	Modem with DreamPi	USB Coder's cable	Serial Coder's cable
Useful for dev?	Yes, supports dcload-ip	Yes, supports dcload-ip, but BBA is superior and cheaper	No, only useful for online multiplayer gaming	Yes, supports dcload-serial	Yes, supports dcload-serial
Cost	$100 - $200 and up on used markets	$200 and up on used markets, due to extreme rarity	Kit prices vary, around $100	See Coder's cable for vendors darc sells for $45, RetroOnyx sells for $85	Varies on used markets, uncommonly sold
Can make DIY?	No	No	Yes	Yes	Yes
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
Games support	Some games: Phantasy Star Online, Quake III Arena, Toy Racer, POD SpeedZone, Propellor Arena, Unreal Tournament Some browsers: Broadband Passport, PlanetWeb 3.0	No games One browser: Dream Passport for LAN	All multiplayer games with network support All web browsers	NO multiplayer games support	NO multiplayer games support
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 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 Makefile.cfg file in this directory. Copy or rename the Makefile.default.cfg file to Makefile.cfg and then use a text editor to edit this file's settings to your liking. For example, you may like to alter the makejobs 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 makejobs=1, 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 README.md file in the dc-chain directory for more information if you are interested. If you are unsure about options in the Makefile.cfg, 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/dreamcast

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 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 kos/examples/dreamcast 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 dc-tool-ip or dc-tool-ser 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

mkdcdisc can be used to easily generate a burnable self-boot CDI image. Dependencies required:

• Homebrew: meson libisofs pkg-config
• Debian/Ubuntu: libisofs-dev meson ninja-build
• Fedora: meson ninja-build
• Arch: meson

Build mkdcdisc:

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 WINE), ImgBurn with the CDI plugin, or the cdiburn *nix script floating around out there. (document this better)