Building KOS on macOS

Jump to navigation Jump to search


This tutorial is a step-by-step guide on how to setup a toolchain and KOS environment on your Mac OS X system.

The toolchain consists of a C/C++ compiler (GCC), assembler and linker (binutils), and C library (newlib). As the Dreamcast has two processors - the SH4 CPU and the AICA (ARM) sound processor - the toolchain includes compilers for both.

KOS consists of the operating system core (kos) and a set of nicely integrated libraries (kos-ports).

Install script

Please consider trying this install script first: File:Kos setup It will perform the steps below automatically.


Install XCode.

Downloading KOS

KOS is available through a Git repository at SourceForge. The standard install directory assumed in the configuration files is /opt/toolchains/dc/{kos, kos-ports}.

$ git clone git:// /opt/toolchains/dc/kos

Toolchain (cross-compiler and libraries)

After cloning the KOS repository, enter the directory for building the toolchain:

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

Then pick the stable or testing version of the toolchain by running one of the following commands:

(GCC 12.2) $ mv 
(GCC 9.3) $ mv 
(GCC 4.7) $ mv 

Then, run the toolchain download+unpack+compile scripts:

$ ./
$ ./

Then compile the cross-compiler and system libraries. The erase=1 will delete temporary files after a successful build.

$ make erase=1

After this command completes successfully you have a working cross-compiler for Dreamcast and can compile KOS next.

Setting up KOS

You should read the documentation in the kos/doc directory for details, but here are the basic steps required to set up the KOS environment:

Go into the kos directory and copy the template configuration:

$ cp /opt/toolchains/dc/kos/doc/ /opt/toolchains/dc/kos/ 

Now edit to match your installation. If you use the default installation directory you don't need to change anything.

Execute the following command to set the KOS environment variables:

$ source /opt/toolchains/dc/kos/

Remember to do this every time you want to use the KOS environment in a newly opened shell. Dont't forget to run the above command again when editing

Now we are finally ready to compile KOS itself. In the kos directory, run:

$ cd /opt/toolchains/dc/kos 
$ make


KOS-Ports is a repository with commonly used libraries for development on the DC, like PNG or MP3 loading.

Clone the repository:

$ git clone --recursive git:// /opt/toolchains/dc/kos-ports

Compile all KOS-ports using the build-all script

$ sh /opt/toolchains/dc/kos-ports/utils/

Now you should have a working Dreamcast development environment :-)

Check out the examples in the KallistiOS directory to find out how to use KOS in your own projects!