Building KOS on MinGW-w64/MSYS2

Revision as of 13:41, 19 September 2023 by BBHoodsta (talk | contribs) (→‎Toolchain (cross-compiler and libraries))
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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 Windows 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).

Since KOS was developed for Unix-compatible systems (like Linux, BSD, etc.), a Unix-compatible development environment must be installed. The available choices are Cygwin, MSYS and MSYS2. MSYS is unmaintained and out-dated. Cygwin and MSYS2 both work, but MSYS2 seems to be maintained more actively, work better and also offers a better package management system, so it is preferred.


Install MSYS2 from (this tutorial used

Please make sure to use partition C:\. A user reported issues of git, wget, etc. not working at all when installing to partition D:\. On the MSys2 website it's mentioned that FAT filesystems don't work, so that's an alternative explanation.

As the setup completes, it will ask whether you want to open a shell. Don't. Open C:\msys32\mingw32_shell.bat instead (mingw shell instead of msys2 shell).

Install script

At this point, please consider trying the install script first. It will perform the remaining steps below automatically.

Download the install script: File:Kos setup Then change to the directory of the script and execute it (uses Unix paths instead of Windows paths, C:\ becomes /c/)

$ cd /c/Documents\ and\ Settings (find your Download folder here..)
$ sh

The script should perform all the remaining steps. If something goes wrong, you can try to continue the steps manually or ask for help on the forums/IRC.

Install required packages

MSYS2 uses the pacman package manager. The following command should download all required programs.

$ pacman -Sy --needed mingw-w64-i686-binutils mingw-w64-i686-gcc mingw-w64-i686-pkg-config mingw-w64-i686-libpng mingw-w64-i686-libjpeg-turbo diffutils git make subversion patch python tar texinfo wget

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, navigate to dc-chain directory:

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

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