Compiling KOS on Linux

Written by Christian Henz (chrhenz at gmx dot de) Comments and contributions are welcome.

v0.3 - 2007-11-15

• svn paths corrected
• Mention libpng and libjpeg requirement
• Tips for compiling KOS

v0.2 - 2007-06-25

• Mention flex and bison requirement (thanks to Cameron)
• Mention that the build script is now included in KOS
• Explain how to build dcload

v0.1 - 2006-08-15

• Initial draft

Overview

This tutorial is a step-by-step guide on how to setup a toolchain and KOS environment on your GNU/Linux system. The instructions should also be valid for other Unices, like *BSD, MacOS X and even CygWin (except for the pre-built toolchain of course).

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. The ARM compiler is a rather basic an only supports C though.

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

Preparations

You need the following software installed:

• subversion
• make
• tar/gzip/bzip2
• development packages of libjpeg and libpng

If you want to compile the toolchain yourself, you also need:

• gcc <= 3.4.x
• flex
• bison
• patch
• wget

All these should be easily available from your GNU/Linux distribution of choice, if they aren't installed already.

We'll set up a directory in our home directory to keep the environment in:

$ mkdir /home/foobert/dc 
$ cd /home/foobert/dc 

Here "foobert" is of course an example user name that you need to replace with your own ;-)

Downloading KOS

KOS is available through a Subversion repository at SourceForge.

$ svn co https://cadcdev.svn.sourceforge.net/svnroot/cadcdev/kos 
$ svn co https://cadcdev.svn.sourceforge.net/svnroot/cadcdev/kos-ports 

Next you should decide if you want to use a pre-built toolchain, or compile it yourself.

Toolchain

Pre-built toolchain

NOTE: The pre-built toolchain available here does not include libbfd, so dcload (see below) cannot be compiled using it!

A pre-built toolchain for i386 machines is available at dc-toolchain-gcc346-1-i386.tar.bz2.

In order to install it, unpack the tarball to / (as root):

$ tar jxf dc-toolchain-gcc346-1-i386.tar.bz2 -C / 

The toolchain will then be available under /usr/local/dc.

Compiling the toolchain yourself

To compile the toolchain ourselves, we will use an updated version of the build script written by Jim Ursetto. The most recent version is included in the KOS subversion repository, under kos/utils/dc-chain.

(Earlier versions, as well as other build scripts are available at http://stalin.thegypsy.com)

The README that is included in the distribution is rather outdated at the moment, so don't rely on it too much but stick to this guide.

To start building the toolchain, we first go to the dc-chain directory

$ cd kos/utils/dc-chain 

Next we need to download the actual sourcecode of the toolchain. To do this automatically, run

$ sh download.sh 

The script needs to download about 44MB, so it might take a while. After it has finished, run

$ sh unpack.sh 

to unpack the source packages. If there are problems during the compilation process later on and you need to start over, just run unpack.sh again and it will delete the source code and re-unpack the archives for a fresh start.

Next we have to edit the Makefile.

There are really only three settings that need to be configured. The first is the location of the KOS sourcecode set by the "kos_root" variable. In our example, we must change the line to: kos_root="/home/foobert/dc"

Next there are the "sh_prefix" and "arm_prefix" variables. These control where the toolchain will be installed. You don't need to change these, but you have to make sure that the directory /usr/local/dc is writeable by your user then OR later on run the make command as root.

In our example we will change the variables so the compilers are installed in our /home/foobert/dc directory:

sh_prefix := /home/foobert/dc/$(sh_target) 
arm_prefix := /home/foobert/dc/$(arm_target) 

Now we are ready to compile the toolchain. It is important to make sure that we do so using a version of GCC <= 3.4.x, as the 4.x versions will fail!

You should check that your default gcc has a version <= 3.4.x by running

$ gcc --version 

If the version is <= 3.4.x, you can then compile and install the toolchain by just running make:

$ make 

If the version is >= 4.x, you need to explicitly specify the compiler to use, for example if you also have GCC 3.4.x installed:

$ make CC=gcc-3.4 

Also remember that the user who runs "make" must have write permission on the the installation directories specified above!

It should take a while for the compilation to finish (about 45 minutes on my 1GHz machine). If the compilation process fails, check the compiler output under logs/ for details.

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:

$ cd /home/foobert/dc/kos 
$ cp doc/environ.sh.sample environ.sh 

Now we have to edit environ.sh to match our installation. First we need to change the KOS_BASE variable:

export KOS_BASE="/home/foobert/dc/kos" 

In case you installed the pre-built toolchain, or did not change the installation directories when installing the self-compiled toolchain, you need to change KOS_CC_BASE and KOS_CC_PREFIX like this:

export KOS_CC_BASE="/usr/local/dc/sh-elf" 
export KOS_CC_PREFIX="sh-elf" 

If you compiled the toolchain yourself and followed the example, you need to change KOS_CC_BASE, KOS_CC_PREFIX as well as DC_ARM_BASE:

export KOS_CC_BASE="/home/foobert/dc/sh-elf" 
export KOS_CC_PREFIX="sh-elf" 
export DC_ARM_BASE="/home/foobert/dc/arm-elf" 

Next we "start" our Dreamcast development environment:

$ source environ.sh 

This makes all the configuration variables defined in the environ.sh script available in the shell's environment.

Remember to do this every time you want to use the KOS environment in a newly opened shell. If you want to enable it permanently, put the command in your shell's config file, for example $HOME/.bashrc. And Dont't forget to run the above command again when editing environ.sh.

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

$ cd /home/foobert/dc/kos 
$ make 

After that, go to the kos-ports directory and run "make" there too.

$ cd /home/foobert/dc/kos-ports 
$ make 

If you got a linker error like "ld: Relocations in generic ELF" then just type:

make clean 

and run make again.

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!

dcload

NOTE: This section is still incomplete!

The dcload package is a pair of programs, dc-tool and dcload, that allow you to upload and run your programs on the Dreamcast. dcload is burned onto a CDROM and run on the Dreamcast. After it starts, it waits for dc-tool on the PC to communicate and upload data.

Two versions of the dcload package exist: dcload-ip, which works over an ethernet connection (BBA, Lan adapter), and dcload-serial, which works over a serial port connection (Coders cable, USB cables).

I will only cover dcload-serial here. The process for dcload-ip should be similar though.

First we download the latest version from the subversion repository:

$ svn co https://cadcdev.svn.sourceforge.net/svnroot/cadcdev/dcload/dcload-serial 

Next we have to edit Makefile.cfg. Three settings are important here:

HOSTCC sets the compiler that should be used to create the tool that will run on your PC. Again we have to use GCC <= 3.4.

HOSTCC = gcc-3.4 

TARGETPREFIX tells the compiler where to find the toolchain.

TARGETPREFIX = /home/foobert/dc/sh-elf 

Finally, TOOLINSTALLDIR tells make where to install the tools.

TOOLINSTALLDIR = /home/foobert/dc/bin 

Now we can compile and install:

$ make 
$ make install 

dc-tool should now be available in /home/foobert/dc/bin.

In target-src/1st_read, you will find the binary that is to be burned onto CDROM and booted on the Dreamcast.

For now I will not cover how to burn the CDROM. The Makefile in make-cd did not work for me the last time I tried it, so I ended up doing it manually. You also need the scramble utility for the process to work.

Check the net and the usual Dreamcast communities for info on how to burn bootable CDROMS.

I might add this info in a later revision of this tutorial.