Dreamcast GameDev with KOS and Bash on Windows
Tags: gamedev, dreamcast, retro, wsl
Published: 2019-02-24 20:59:26

---
title: Dreamcast GameDev with KOS and Bash on Windows
published: true
canonical_url: https://brianpeek.com/dreamcast-gamedev-with-kos-and-bash-on-windows/
tags: gamedev, dreamcast, retro, wsl
---

_Cross-posted from [brianpeek.com](https://brianpeek.com/dreamcast-gamedev-with-kos-and-bash-on-windows/)._

Many years ago, an open-source Sega Dreamcast SDK known as [KallistiOS](http://gamedev.allusion.net/softprj/kos/) (KOS) was created and is still being developed today.  I used this SDK long ago to create a few emulators that were [published](http://www.ganksoft.com/), and a variety of unfinished games that were not...

KOS is easy to get up and running on a variety of platforms, but on Windows this always required setting up Cygwin.  But, with the addition of the Linux Subsystem for Windows (LXSS) in Windows 10 Anniversary Update, one can now run Ubuntu and the Bash shell natively in Windows 10, and that means one can easily setup KOS, the SH4 toolchain and (almost) everything else required to develop and deploy apps to a Sega Dreamcast.  Here's how…

# Requirements

*   A Sega Dreamcast capable of booting MIL-CDs...this is any machine manufactured prior to October 2000.
*   A Dreamcast Broadband Adapter (HIT-0300 or HIT-0400 both work)
*   The Dreamcast plugged into your network via Ethernet
*   The Linux Subsystem for Windows [installed](https://docs.microsoft.com/windows/wsl/install-win10?WT.mc_id=devto-blog-brpeek) and configured

# Updating LXSS

Make sure you upgrade the subsystem by issuing these two commands:

```bash
sudo apt-get update
sudo apt-get upgrade
```

# Downloading and Building the Toolchain and KOS

Once completed, you will need to install a few packages required to retrieve and build the SDK and tools:

```bash
sudo apt-get -y install git make gcc texinfo libjpeg-dev libpng-dev subversion genromfs libelf-dev python
```

Now that the appropriate packages are installed, make sure you're in your home directory and then download the KOS repos:

```bash
git clone git://git.code.sf.net/p/cadcdev/kallistios kos
git clone git://git.code.sf.net/p/cadcdev/kos-ports
```

Next, you need to download and unpack the toolchain bits used to build the Dreamcast toolchain:

```bash
cd ~/kos/utils/dc-chain/
./download.sh
./unpack.sh
```

That unpacking process will not display any output and may take a long time, so don't cancel!

With the packages unpacked, you can now build the toolchain.  This process builds a compatible compiler (gcc) and other tools for the Dreamcast's SH4 CPU.  While in the same directory as above, run:

```bash
sudo make
```
This will take a while, so be patient...

With that complete, you now need to setup your Bash environment so the SDK and tools can be found and used.  First, copy the following file and change its permissions:

```bash
cp ~/kos/doc/environ.sh.sample ~/kos/environ.sh
chmod 777 ~/kos/environ.sh
```

Next, edit the environ.sh file we just copied to point it at the tool location.  To do this, I use use nano, but any other text editor is fine:

```bash
nano ~/kos/environ.sh
```
Look for the entry exporting **KOS_BASE** and set it to the following:

```bash
/home/YOUR_USERNAME/kos
```

Obviously, replace **YOUR_USERNAME** with your username.  Mine looks like this:

```bash
export KOS_BASE="/home/brian/kos"
```

Next, look for the entry exporting **KOS_LOADER** and add the following prior to the -x argument:

```bash
-t IP_ADDRESS
```

...where **IP_ADDRESS** is a valid, unused IP address on your network.  Mine looks like this:

```bash
export KOS_LOADER="dc-tool -t 192.168.2.250 -x"
```

> A note on the IP address:  You cannot choose any IP in the world...it must be valid in your own subnet (probably 192.168.X.X or 10.X.X.X or similar), and it must not be used by any other device on your network.  Check your router for valid choices and more information.

Finally, edit the .bashrc file in your home directory:

```bash
nano ~/.bashrc
```

...and at the very bottom, add this line so the **environ.sh** file you just edited gets run at login:

```bash
. ~/kos/environ.sh
```

> Don't forget the period as the first character!

Now, exit and restart Bash on Windows.  To make sure the environment is setup, use the **printenv** command and you should see a variety of environment variables listed starting with **KOS_** listed.

Next, KOS itself needs to be built.  To do this, change into the **kos** directory and run the make command:

```bash
cd ~/kos
make
```
Once completed, build the **kos-ports** project:

```bash
cd ~/kos-ports/utils/
./build-all.sh
```

And finally, build the KOS example projects:

```bash
cd ~/kos/examples
make
```

A few of these examples may not build but don't worry about that for now.

# Downloading and Building dcload-ip

Next up, you will need to download and build the dcload-ip tool.  This is what will allow you to deploy a game to a retail Dreamcast over the Broadband Adapter (BBA).  Change back to your home directory, run the following:

```bash
cd ~
git clone git://git.code.sf.net/p/cadcdev/dcload-ip
cd dcload-ip
sudo make install
```

> You may see an error about /usr/local/bin existing on the final step, which is safe to ignore.

Now, you will need to burn the host dcload program to a CD so we can run it on the physical Dreamcast machine and upload our binary.  But, here we have to cheat.  Because the Linux Subsystem for Windows doesn't yet have hardware support, it can't talk to a CD-R drive.  But, I have put together a quick package that contains the required tools and the cygwin libraries to run them.  You can download that package here:

[dcload-disc.zip (1.42 mb)](https://brianpeek.com/downloads/projects/dcload-disc.zip)

Unzip this somewhere on your machine, then open an admin Windows command prompt (not Bash) and navigate to the files.  Then, run the following:

```Batchfile
wodim -scanbus
```

This will return some information about every drive it finds.  In the output, look for your recordable drive in the list and make a note of the 3 comma-delimited digits that identify the bus and location of the drive.  Mine looks like this:

```textfile
scsibus0:  
        0,0,0     0) 'HL-DT-ST' 'BD-RE  WH16NS40 ' '1.02' Removable CD-ROM
        0,1,0     1) *  
        0,2,0     2) *  
        0,3,0     3) *  
        0,4,0     4) *  
        0,5,0     5) *  
        0,6,0     6) *  
        0,7,0     7) HOST ADAPTOR
```

So, the 3 digits for me are "0,0,0".  For these next steps, replace the **X,X,X** with your values.

Insert a blank CD-R into your drive and burn the first part of the disc, the audio track, as follows:

```Batchfile
wodim dev=X,X,X -multi -audio -tao audio.raw
```

Now, burn the data track:

```Batchfile
wodim dev=X,X,X -xa -tao -multi data.raw
```

With those two items burned, you now be able to eject the CD, pop it in your Dreamcast, and it will run.

# Running a Sample

With dcload-ip running on your Dreamcast, you should see a MAC address displayed.

[![WP_20160731_01_40_04_Pro](https://brianpeek.com/content/images/WP_20160731_01_40_04_Pro_thumb_2.jpg "WP_20160731_01_40_04_Pro")](https://brianpeek.com/content/images/WP_20160731_01_40_04_Pro_2.jpg)

We need to tell our Windows machine how to find that device by an IP address.  If you recall, earlier you selected an IP for your Dreamcast.  You will need that here.

Open an admin command prompt (not Bash, but standard command prompt) and run the **arp** command as follows:

```Batchfile
arp -s IP_ADDRESS MAC_ADDRESS
```

Replace **IP\_ADDRESS** with the one selected above, and **MAC\_ADDRESS** with the one seen on screen, but use hyphens instead of colons.  Here's an example:

```Batchfile
arp -s 192.168.2.250 00-d0-f1-02-3f-07
```

> This command must be run after every reboot...it will not be saved by Windows.

You may need to exit and restart the Bash on Windows after running this command so it will know about the change.

Now, you can run the 2ndmix (or any other) sample:

```bash
cd ~/kos/examples/dreamcast/2ndmix
make run
```

If all goes to plan, this should build, deploy, and execute the 2ndmix demo on your Dreamcast!

[![WP_20160731_01_40_30_Pro](https://brianpeek.com/content/images/WP_20160731_01_40_30_Pro_thumb.jpg "WP_20160731_01_40_30_Pro")](https://brianpeek.com/content/images/WP_20160731_01_40_30_Pro.jpg)

# Next Steps

Now that you have a configured and working toolchain and SDK, you can start building your own Dreamcast games.  Take a look at all of the examples in the kos directory to learn more about the API.  Additionally, here are a few links with more information:

*   [KallistiOS](http://gamedev.allusion.net/softprj/kos/)
*   [Documentation](http://gamedev.allusion.net/docs/kos-2.0.0/)