Installation

Requirements

• A Unix-like system (Linux, macOS, WSL2)
• 4GB disk space for the toolchain
• An x86_64 or arm64 host
• Go 1.25.3 or later — required to install the godc CLI tool
• make — required for building projects
• git — required for toolchain setup and updates

Quick Start

The godc tool automates everything:

go install github.com/drpaneas/godc@latest
godc setup

This downloads the prebuilt toolchain to ~/dreamcast and configures your environment. Run godc doctor to verify the installation.

godc Commands

Configuration

godc stores its config in ~/.config/godc/config.toml:

Path = "/home/user/dreamcast"    # Toolchain location
Emu = "flycast"                  # Default emulator
IP = "192.168.2.203"             # Dreamcast IP for dc-tool

To update settings interactively:

godc config

Manual Installation

If the automated setup doesn’t work for your environment:

Step 1: Get the Toolchain

Download the prebuilt toolchain for your platform:

# Linux x86_64
curl -LO https://github.com/drpaneas/dreamcast-toolchain-builds/releases/download/gcc15.1.0-kos2.2.1/dreamcast-toolchain-gcc15.1.0-kos2.2.1-linux-x86_64.tar.gz

# Linux arm64 (aarch64)
curl -LO https://github.com/drpaneas/dreamcast-toolchain-builds/releases/download/gcc15.1.0-kos2.2.1/dreamcast-toolchain-gcc15.1.0-kos2.2.1-linux-arm64.tar.gz

# macOS arm64 (Apple Silicon)
curl -LO https://github.com/drpaneas/dreamcast-toolchain-builds/releases/download/gcc15.1.0-kos2.2.1/dreamcast-toolchain-gcc15.1.0-kos2.2.1-darwin-arm64.tar.gz

Step 2: Extract

mkdir -p ~/dreamcast
tar -xf dreamcast-toolchain-*.tar.gz -C ~/dreamcast --strip-components=1

The toolchain contains:

~/dreamcast/
├── sh-elf/           # Cross-compiler (sh-elf-gccgo, binutils)
├── kos/              # KallistiOS (OS, drivers, headers)
├── libgodc/          # This library (Go runtime)
└── tools/            # Utilities (elf2bin, makeip, etc.)

Step 3: Environment

Add these to your shell configuration (~/.bashrc, ~/.zshrc, etc.):

export PATH="$HOME/dreamcast/sh-elf/bin:$PATH"
source ~/dreamcast/kos/environ.sh

environ.sh sets KOS_BASE, KOS_ARCH, and other build variables.

Step 4: Verify

sh-elf-gccgo --version
# Should print: sh-elf-gccgo (GCC) 14.x.x ...

ls $KOS_BASE/lib/libgodc.a
# Should exist

Building libgodc from Source

If you need to modify the runtime, or if prebuilt libraries aren’t available:

git clone https://github.com/drpaneas/libgodc ~/dreamcast/libgodc
cd ~/dreamcast/libgodc
source ~/dreamcast/kos/environ.sh
make clean
make
make install

This builds libgodc.a (the runtime) and libgodcbegin.a (startup code), then installs them to $KOS_BASE/lib/.

Debug Build

For development, enable debug output:

make DEBUG=1

This adds -DLIBGODC_DEBUG=1 -g to the compiler flags, enabling trace output and symbols.

Running Code

Emulator

lxdream-nitro or flycast can run Dreamcast binaries.

cd examples/hello
make
flycast hello.elf

Real Hardware

With a Broadband Adapter or serial cable:

# Upload via IP (BBA)
dc-tool-ip -t 192.168.1.100 -x hello.elf

# Upload via serial
dc-tool-ser -t /dev/ttyUSB0 -x hello.elf

The godc run command automates this:

godc run              # Uses configured emulator
godc run --ip         # Uses dc-tool-ip with configured address

Project Structure

A minimal project:

myproject/
├── go.mod            # Module definition
├── main.go           # Your code
├── .Makefile         # Build rules (generated by godc)
└── romdisk/          # Optional: game assets
    ├── texture.png
    └── sound.wav

Example 1: Minimal (hello)

The simplest program — no graphics, just debug output:

main.go:

// Minimal Dreamcast program
package main

func main() {
    println("Hello, Dreamcast!")
}

go.mod (generated by godc init):

module hello

go 1.25.3

replace kos => ~/dreamcast/libgodc/kos

Example 2: Screen Output (hello_screen)

Display text on screen using the BIOS font:

main.go:

// Hello World on Dreamcast screen using BIOS font
package main

import "kos"

func main() {
    // center "Hello World" on 640x480 screen
    x := 640/2 - (11*kos.BFONT_THIN_WIDTH)/2
    y := 480/2 - kos.BFONT_HEIGHT/2
    offset := y*640 + x

    kos.BfontDrawStr(kos.VramSOffset(offset), 640, true, "Hello World")

    for {
        kos.TimerSpinSleep(100)
    }
}

go.mod (generated by godc init):

module hello_screen

go 1.25.3

replace kos => ~/dreamcast/libgodc/kos

require kos v0.0.0-00010101000000-000000000000

Build and Run

godc init             # Generate go.mod and .Makefile
godc build            # Compile to .elf
godc run              # Launch in emulator

Or manually:

sh-elf-gccgo -O2 -ml -m4-single -fno-split-stack -mfsrra -mfsca \
    -I$KOS_BASE/lib -L$KOS_BASE/lib \
    -c main.go -o main.o

kos-cc -o myproject.elf main.o \
    -L$KOS_BASE/lib -Wl,--whole-archive -lgodcbegin \
    -Wl,--no-whole-archive -lkos -lgodc

Romdisks — Packaging Assets

A romdisk is a read-only filesystem compiled into your executable. Put assets in the romdisk/ directory:

myproject/
├── main.go
└── romdisk/
    ├── player.png
    └── music.wav

The build system automatically:

1. Creates romdisk.img using genromfs
2. Converts it to romdisk.o using bin2o
3. Links it into your executable

Access files in Go via /rd/:

texture := kos.PlxTxrLoad("/rd/player.png", true, 0)
sound := kos.SndSfxLoad("/rd/music.wav")

Compiler Flags

Default flags used by godc:

For maximum performance:

GODC_FAST=1 godc build

This enables -O3 -ffast-math -funroll-loops. Warning: -ffast-math breaks IEEE floating-point compliance.

Project Overrides

Create godc.mk for project-specific customizations:

# Reduce GC heap to free RAM for assets
CFLAGS += -DGC_SEMISPACE_SIZE_KB=1024

# Add extra libraries
LIBS += -lmy_custom_lib

# Custom romdisk location
ROMDISK_DIR = assets

Troubleshooting

“sh-elf-gccgo: command not found”

The compiler isn’t in your PATH. Check:

echo $PATH | tr ':' '\n' | grep dreamcast
which sh-elf-gccgo

“cannot find -lgodc”

The runtime library isn’t installed. Build and install it:

cd ~/dreamcast/libgodc
make install
ls $KOS_BASE/lib/libgodc.a

“undefined reference to `__go_runtime_init’”

You’re linking with the wrong library order. The correct order is:

-Wl,--whole-archive -lgodcbegin -Wl,--no-whole-archive -lkos -lgodc

-lgodcbegin must be wrapped in --whole-archive to ensure all its symbols are included.

Runtime crashes immediately

Check if your program uses double-precision floats. The SH-4 FPU is single-precision only. Compile with -m4-single and avoid float64 in hot paths.

Out of memory

The Dreamcast has 16MB. Check your allocations using the C API:

#include "gc_semispace.h"

size_t used, total;
uint32_t collections;
gc_stats(&used, &total, &collections);
printf("Heap: %zu / %zu bytes, %u collections\n", used, total, collections);

From Go, you can count goroutines:

println("Goroutines:", runtime.NumGoroutine())

Consider using KOS malloc directly for large buffers:

ptr := kos.PvrMemMalloc(size)  // PVR VRAM
ptr := kos.Malloc(size)        // KOS heap

Next Steps

• Read the Design Document to understand the runtime architecture
• Read KOS Wrappers to learn how to use KOS functions
• Look at the examples/ directory for working programs
• Read Effective Dreamcast Go for best practices and limitations