Toolchain Setup - Windows Subsystem for Linux

Setting up a toolchain for building Dreamcast applications with KallistiOS is a relatively straightforward process on any reasonably POSIX-like system, like what is provided with Windows Subsystem for Linux in Windows 10. Setup on Windows 10 using the Windows Subsystem for Linux (WSL) is fairly straightforward and follows the same basic process as on a normal Linux system, after getting WSL up and running.

Windows Subsystem for Linux

Introduced as a part of Windows 10, the Windows Subsystem for Linux allows the use of Linux programs on Windows 10, without running a VM or dual booting the system. Basically, WSL works for many purposes like Cygwin, but allows the use of Linux software unmodified, rather than requiring recompilation or other porting complications. You can read more about the Windows Subsystem for Linux at Microsoft's documentation for WSL.

In order to use WSL for the rest of the setup, you will need to enable the Windows Subsystem for Linux feature of Windows 10 (or recent Windows Server versions). Regardless of whether you are using Windows 10 or Windows Server, the process is the same. Start Windows PowerShell as an administrator account (click the Start menu, type PowerShell, right click on the program and select "Run as administrator"):

Once you have PowerShell running, run the following command inside it to enable WSL (and restart when prompted, as shown below):

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

Once Debian is installed, it is a good idea to update all the pre-installed software within the Debian instance. You can do so by running the following commands inside the debian shell:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade

Please note that it will ask you for your password when running the first sudo command (and possibly subsequent ones as well, depending on the length of time between invocations). This refers to the password you set during the Debian setup, not your Windows login password.

Installing Prerequisites

As discussed on the general setup page, there are several prerequisites that must be installed to successfully build a toolchain for KOS. For Debian, you can run the following command to install all of the prerequisites at once (this should all be typed as one command):
sudo apt-get install gawk patch bzip2 tar make libgmp-dev libmpfr-dev libmpc-dev gettext wget libelf-dev texinfo bison flex sed git build-essential diffutils curl python subversion libjpeg-dev libpng-dev nano

Now that the prerequisite programs and libraries are installed, you should create the directory where the toolchain will exist. For the purposes of this guide, we will assume that the toolchain will exist in the directory /opt/toolchains/dc inside of your WSL instance. You can use any directory you would like to do this, however some scripts and such will have to be adjusted if you wish to use a different directory. These will be mentioned at the appropriate time. To create the directory to install the toolchain in (and give your regular user permission to write to the directory), run the following command:.

sudo mkdir -p -m 777 /opt/toolchains/dc

Selecting Which KOS Version to Install

At this point, you should select which version of KOS to install. Basically, you can either select to install a release version (such as 2.1.0), or the current development version. In general, the development tree is fairly stable, however the API sometimes undergoes changes without any warning in the development tree. If you're doing a long-term development project with KOS (for instance, developing a commercial indie game), then you might consider using the latest release version (and potentially updating it when a new point release comes out). However, if you're just tinkering around and don't care about minor API changes here and there, you may want to follow the development version on SourceForge (or GitHub — they should generally contain the same code). The development version (obviously) contains the latest code advancements, but also might contain the latest and greatest features bugs too.

No matter whether you choose to stick with a point release or the development version, the process for building the toolchain is relatively the same.

Option 1 — Installing the development version from the git repository

Run the following commands to grab KOS and kos-ports from the git repository hosted by SourceForge:

cd /opt/toolchains/dc
git clone git://git.code.sf.net/p/cadcdev/kallistios kos
git clone git://git.code.sf.net/p/cadcdev/kos-ports kos-ports

Option 2 — Installing a release version

Instructions to come at a later date when a more up-to-date release version of KOS is available.

Installing the Compiler Toolchain

Now that you have KOS downloaded, we will use a few tools included with it to build a complete compiler toolchain that can be used to build Dreamcast binaries. Specifically, we will be using the dc-chain utility that is included to build the compiler relatively simply. This step will probably take a significant amount of time (and hard drive space) to complete. The process is relatively simple, assuming that everything works, anyway. Just run the following commands to build the toolchain (please note that the following commands will take some time to complete and in some cases do not show any progress until they are completed):

cd /opt/toolchains/dc/kos/utils/dc-chain
./download.sh --no-deps
./unpack.sh --no-deps
make

Note: If you are installing in a directory other than /opt/toolchains/dc, you must edit the Makefile in the dc-chain directory to point to where you're installing. Edit the lines that define the sh_prefix and arm_prefix to point to the correct places.

If no errors have polluted your screen then you should have a working compiler toolchain that can be used to build KOS and Dreamcast binaries that use it.

Building KOS and kos-ports

Once the compiler toolchain has been built, you must compile KOS itself. This too is a relatively straightforward process:

cd /opt/toolchains/dc/kos
cp doc/environ.sh.sample environ.sh
chmod u+x environ.sh
source environ.sh
make

Note: If you're installing to a different directory than /opt/toolchains/dc, you will need to edit the environ.sh file to point to the correct place. Specifically, you will have to edit the KOS_BASE, KOS_CC_BASE, DC_ARM_BASE, and PATH lines to point to the correct places.

As of KOS 2.1.0, kos-ports is not necessarily meant to be built all at once anymore, but rather as you need individual packages. It is sill possible to build all of the ported libraries at once if you wish, but it is recommended to just build each piece as you need it. To build an individual library, go to its directory in the kos-ports tree and just run make install clean. As an example, here's how you would build the libpng port:

cd /opt/toolchains/dc/kos-ports/libpng
make install clean

If you wish to build all ports at the same time, then you can run the following commands to do so:

cd /opt/toolchains/dc/kos-ports
utils/build-all.sh

Finishing up

When building KOS and anything using it, you will need to make sure that the environ.sh script that was set up in the previous step is loaded into your shell. The easiest way to do this is to simply add it to your shell's startup sequence. This is as simple as editing the .bashrc files in your WSL home directory by typing the following command:

nano ~/.bashrc

Once you have done that, hit CTRL+V to skip to the bottom of the file, hit Enter/Return to add a blank line and then type the following into the file:

source /opt/toolchains/dc/kos/environ.sh

When that is done, hit CTRL+O to save the file (hitting Enter/Return to accept the filename), then CTRL+X to exit nano.

You will probably also want to create a directory that can be accessed easily from both WSL and your normal Windows-based tools (so you can use a GUI-based program to edit source code and such). The easiest thing to do is to create a directory in the root of your C:\ drive on Windows (or another drive) that you can use for storing code and such in. For instance, if you create a directory called "Data" in the root of your C:\ drive in Windows, you can access it in Debian as /mnt/c/Data. You may also find it useful to copy the KOS example programs over to that directory to make them easier to access. To do so, run the following command (assuming that you created the Data directory in the root of your C:\ drive, as suggested):

cp -a /opt/toolchains/dc/kos/examples/dreamcast /mnt/c/Data/kos-examples

You're now done! Go out and do great things and make some cool software. We'd love to hear from you if you do, so check in on the mailing list, IRC, or on the DCEmulation forums (check the lists page for links).