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.

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 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. There are others in existence, like libronin and libdream, as well as the commercially used Katana and Windows CE, but this guide will only cover the setup and use of KallistiOS.

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.

Choosing a debug link solution

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

Setting up and compiling the toolchain with the dc-chain script

First, install dependencies (e.g. 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) using your system's package manager.

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

Clone the KOS git repository to your system:

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

Enter the dc-chain directory:

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

Choose one of the following pre-made toolchain configurations:

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

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.

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

Copy the pre-made environment script into place:

cp /opt/toolchains/dc/kos/doc/environ.sh.sample /opt/toolchains/dc/kos/environ.sh 

Edit the environ.sh to your liking. Run the following in your terminal whenever working on your Dreamcast project:

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

Build KOS:

cd /opt/toolchains/dc/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.