Getting Started with Dreamcast development

BEWARE: THIS ARTICLE IS CURRENTLY A WIP

WIP NOTES

This article will cover the entire beginning process: starting from zero to having a working dev environment with debug link and self-booting CD-R.

• Steps required for Windows 10/WSL, macOS/Intel, macOS/Apple Silicon, Debian/Ubuntu Linux, and Fedora Linux
  • Steps should be pretty similar for the *nix OSs besides package managers and dependencies
• Considering and choosing a Dreamcast debug link solution (serial, BBA, LAN)
  • Include charts comparing the pros and cons of each solution
• Configuring and compiling the toolchain, KOS, and KOS ports
• Setting up KOS and compiling an example program
• Executing the sample program using a debug link
  • Include up-to-date ready made CDIs for dcload-serial and dcload-ip
• Burning a project to CD and preparing for distribution

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
• macOS on Intel or Apple Silicon systems with the Homebrew package manager installed
• Debian- and Ubuntu-based Linux distributions using the default apt package manager
• Fedora-based Linux distributions using the default dnf 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 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 C/C++/Objective-C compiler
• binutils, an assembler and linker
• newlib, a C library
• gdb, a debugger

The toolchain includes compilers for both the Dreamcast's main SH4 CPU as well as 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

Explain the differences (costs, performance, and other considerations) among the options.

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	Varies on used markets, uncommonly sold 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

Debian/Ubuntu-based Linux

First, we'll need to install dependencies before building the toolchain. On Debian/Ubuntu-based systems, install the required dependencies using the following command:

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

Many of these dependencies should be installed already on a typical Debian/Ubuntu-based system, but we've chosen to list them all here for good measure.

Other 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:

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 KOS git repository

Clone the KOS git repository to your system:

git clone git://git.code.sf.net/p/cadcdev/kallistios /opt/toolchains/dc/kos

Configuring the dc-chain script

Enter the dc-chain directory:

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

You'll need to choose one of the following pre-made toolchain configurations. The testing version uses GCC 9.3.0 and Newlib 3.3.0, whereas the stable version uses GCC 4.7.4 and Newlib 2.2.0. We suggest trying to use the testing version unless you run into an issue. Run one of the following two commands to make your choice:

mv config.mk.stable.sample config.mk
mv config.mk.testing.sample config.mk

Now, configure config.mk options to your liking. Be careful if adjusting makeopts for more than one job, as this can lead to build failure. It is recommended to keep this setting at -j1.

Finally, compiling the toolchain

Run the download and unpack scripts:

./download.sh
./unpack.sh

Compile the toolchain:

make

Toolchain is now built.

Configuring and compiling KOS and kos-ports

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

Run the following now, and whenever you are working on your Dreamcast project:

source /opt/toolchains/dc/kos/environ.sh

Build KOS:

make

KOS is now built.

Clone the kos-ports repository to your system:

git clone --recursive git://git.code.sf.net/p/cadcdev/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.

Compiling and running an example program

Give a tutorial on writing and compiling very basic helloworld-style C program, configuring serial or IP link, and running the example

Burning your project to CD and distributing

Explain how to compile a CD project using mkdcdisc or similar tools, and how to package it for distribution.

Further reading

Links to articles for using gdb, integrating the dev setup with an IDE, etc.