dreamcast.wiki - User contributions [en]

Getting Started with Dreamcast development

2026-07-28T01:57:01Z

SpecialK: /* Configuring the dc-chain script */ added reference to kos-chain on master

<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 which gcc
</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

For KOS master:
cd /opt/toolchains/dc/kos/utils/kos-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)

Modern A/V guide

2025-09-09T04:09:18Z

SpecialK: created

== Native DC outputs ==

The Dreamcast's multi-AV port supports several video outputs. These are, in ascending order of quality:

* Composite video (yellow RGB connector)
* S-video (mini-DIN with separate luminescence and chroma (Y/C) signals)
* RGB (separate signals for red, green, and blue colors, plus a sync signal)
* VGA (PC-style connection for use with a monitor)

The Dreamcast also supported RF connection to older TVs using a cable which converts composite video and audio signals to a single signal which connects to a TV's antenna or VCR input. Nowadays RF and composite should be ignored entirely.

You should use VGA or RGB signals whenever you can. These provide the best possible video signal with less color bleeding, cross-talk, and "fuzz".

=== Composite video ===

Composite is the most common way to connect a DC to a TV, as this cable was included in the box in most regions. This yellow RCA cable's video looks acceptable on a smaller CRT display. But on a larger model it looks bad. And on a flat-panel display like a LCD, it looks absolutely awful.

Avoid composite video wherever possible.

=== S-video ===

S-video (sometimes erroneously called S-VHS) uses two signals, rather than composite's one. This greatly increases quality, as black-and-white video is carried on one path and color is carried on another. High-end CRTs and early flat panel TVs support S-video.

This was the easiest way to improve picture fidelity in North America during the DC's lifetime.

=== RGB ===

While S-video uses two signals for video, RGB uses three. This allows for amazing video quality.

There are several standards for RGB video around the world. You need to research which one is right for your location and equipment. The most common are:

* SCART (used heavily in Europe)
* JP-21 (RGB-21, used in Japan and Korea)
* RGB-S (4 RCA or BNC connectors, with the 4th cable being used for sync)
* SoG (Sync-on-green, a rarer alternative to RGB-S)

There is no difference in video quality between these standards when used correctly.

==== SCART ====

SCART can carry high quality RGB signals as well as lower quality ones. Composite to SCART adapters were common during the DC's life (such as a SCART plug with RCA connectors). These provide composite video quality, but RGB SCART cables were also available as aftermarket accessories. These are very rare nowadays, so people with a compatible TV should look into converting other, more common cables.

==== JP-21 ====

JP-21 (or RGB-21) was most commonly used in Japan and Korea. It uses the same connector as SCART but with a different pinout. This means that it is '''''not compatible''''' with SCART, and the connectors cannot be used interchagably.

As a rule, if a new old stock product is listed in Japanese and/or Korean, it is JP-21. If it is written in English and/or other European languages, it is SCART.

==== RGB-S ====

RGB-S is a video signal which uses 4 cables to transit Red, Green, Blue, and a Synchronization signal. SCART and JP-21 both use the same signals, so "RGB-S" usually implies connecting with 4 distinct RCA or BNC cables.

Some PVMs, projectors, and other high end equipment used RGB-S connections, but it is rare. Although the RCA jack colors are the same, RGB-S and component video are not compatible. Component video will be covered later in this guide.

==== Sync-on-green ====

Rather than use a separate sync signal, some displays can get that information from the green color channel. This is also very rare, and is of little interest unless you have a display which accepts it.

=== VGA ===

In the Dreamcast context, VGA can refer to a particular video signal (640x480@60Hz) or the connector used on monitors (commonly called DE-15 or D-Sub.)

Compared to TV signals like S-video or even RGB, VGA has a higher picture quality because it is progressive scan rather than interlaced (each line is drawn at the same time, not alternating.) This results in a much sharper image, equivalent to 480p.

The Dreamcast supports VGA output natively, but a small minority of games do not. Some of these unsupported games can be "tricked" into outputting VGA using mods, cheat codes, ODE overrides, or simply switching cables once the game has started.

Sega's official "VGA box" for the Dreamcast is now quite rare and expensive, but many third party alternatives exist. These may vary in quality and features. Most will have either a 3.5mm audio jack or stereo RCA cables for audio, as VGA does not carry audio.

== Common alternatives ==

=== RF ===

RF combines composite video with audio in a single coaxial cable, and was commonly used with OTA TV antennas and VCRs. The signal is often noisy and is the worst quality possible. RF should only be used on an old TV with no better options available.

=== Component ===

Also known as YPbPr or D-terminal (in Japan), component video is similar to RGB, but uses a different color conversion so the signals are not directly compatible.

Because component video became very popular after the Dreamcast, there has been a demand to convert RGB signals to YPbPr component. Most converters or purpose-built cables will use RGB signals as a source, so the video is limited to 480i rather than the 480p offered with VGA.

[https://www.hdretrovision.com/blog/2020/1/5/restock-dreamcast-and-hdmi HD Retrovision has announced] a Component video cable for Dreamcast with support for both 480i and 480p video, but there has been little news since 2020.

=== HDMI ===

Most Dreamcast HDMI cables are adapters which convert a VGA signal from the DC to HDMI.

There is a wide variety of different cables or adapters which have varying levels of quality and features. Some may upscale the video to a higher resolution, introduce video latency, or alter the color saturation and contrast.

Generic VGA-HDMI adapters also exist, but may be less suitable for gaming and be incompatible with some Dreamcast-TV combinations. Ensure any adapter is '''VGA to HDMI''' and not HDMI to VGA - the conversion is unidirectional.

TODO: Reviews?

== HDMI mods ==

A HDMI adapter which connects to the DC's multi-AV output still uses the DC's native VGA output before converting it to HDMI. This introduces latency and reduces quality because it is converting to analog video and then back to digital.

A HDMI mod, on the other hand, directly connects to the DC's video chipset and grabs the signal straight from the source. This allows for perfect video quality, no added lag, and flexible scaling options.

However they are quite expensive and require significant delicate soldering to your system. Most installations also remove the Serial port from the Dreamcast, which may be undesirable if you want to use a [[Coder's cable|Coder's Cable]] or [[Neo Geo Pocket Color link cable|NGPC link cable]].

=== RetroGEM ===

Formerly [[DCDigital]] and DCHDMI, [https://www.pixelfx.co/hdmi-retro-gem RetroGEM] is now a multi-system modification which supports Dreamcast and other consoles.

== Recommendations ==

For the best, most authentic Dreamcast experience, use a CRT PC monitor, preferably with Trinitron (or equivalent). This has the progressive scan resolution which other CRTs do not, and does not have scaling or conversion issues like newer flat panel displays (LCD, OLED) do. It is the best of both worlds.

With a modern TV or display which only accepts HDMI, RetroGEM is by far the best option, although its price and installation is an understandable barrier for many. A standard Dreamcast HDMI cable such as Kaico or Retrobird will deliver a great experience.

For older displays without HDMI or VGA, choose RGB, S-video, composite, and RF in decreasing order of preference.

For dedicated gamers or those with unique setups, a frame scaler may be a good investment but the DC has enough output options that it is rarely necessary to use a scaler.

== External links ==

[https://gamesx.com/wiki/doku.php?id=av:dreamcastav Dreamcast AV on GameSX]