Intro

So you want to get started, but have no idea how. Well, you are not alone!

There are a few available scripts to set things up, mostly automatically, for you, or you can do things manually (like some of us still like to do, or have to do before pushing out the updates to said scripts). Both methods will be covered on this page.

The basic steps you will need to perform to get a working KOS dev setup are the following:

1. Install prerequisites
2. Pull KOS from Git (or use a release version)
3. Compile Binutils
4. Compile GCC
5. Compile Newlib
6. Compile GCC again
7. Setup an environ.sh
8. Compile KOS
9. Compile Ports (optional)

Installing Prerequisites

You will need a few packages installed on your machine before you get started with the rest of the steps in here. This all assumes you have a relatively sane POSIX-like environment. If you are on Mac OS X, Linux, *BSD, or anything of the like, then you already have the POSIX requirement taken care of. If you are on Windows, you will need to set up a POSIX-like environment. Most people tend to use Cygwin for this, although there are other options (such as installing a VM with Linux or *BSD on it).

Unfortunately, due to the vast differences between various distributions and OSes, it is pretty much impossible to tell you exactly how to set up your environment on your computer. However, here is a general list of packages you will need to get started:

• A full GCC setup and development libraries for your OS
• A working POSIX-compatible shell (such as bash — should be installed in any POSIX environment)
• A working POSIX-compatible awk (such as GNU awk — should also be installed in any POSIX environment)
• patch version 2.5.4 (or later)
• bzip2 version 1.0.2 (or later)
• GNU tar version 1.14 (or later)
• GNU make version 3.80 (or later)
• GNU Multiple Precision Library (GMP) version 4.3.2 (or later) — make sure to install the development library for this as well
• MPFR Library version 2.4.2 (or later) — once again, you need the development library too
• MPC Library version 0.8.1 (or later) — once again, you need the development library too
• gettext version 0.14.5 (or later) — only needed if you want localized error messages from the compiler
• wget (any version should work, I think) — needed to use the download script with dc-chain. Not really necessary, since you can download all the source code to GCC and friends yourself.
• libelf — make sure to install the development package for this too. Only needed for building dc-tool (serial or broadband). If you do not need to build them, then you do not have to worry about it.
• texinfo (not sure of the version) — Needed for building Newlib documentation. Newlib's Makefile complains if you don't have it, so it is a good idea to install it.
• bison, flex, and sed — Probably already installed along with the rest of the POSIX environment, but it does not hurt to list them here too.
• Git version 1.7.5 (or later)

Hopefully, I have not missed anything on that list...

Pulling KOS from Git (or use a release version)

Pulling KOS from Git is covered here.

Alternatively, if you'd rather use a release version of KOS, you're welcome to use version 2.0.0, which was posted on the SourceForge page not all that long ago. It is basically a snapshot of the Git repository as of May 23, 2013. Make sure to grab both the kos and kos-ports tarballs, if you want both. Then, extract them to a common place on your development machine (so that you have a kos-2.0.0-src and a kos-ports directory sitting next to each other). The dc-chain script referred to below will be in the kos-2.0.0-src/utils/dc-chain directory (rooted wherever you extracted the two tarballs).

Getting a working Binutils/GCC/Newlib

Even for basic use, it is required to patch GCC and Newlib for use with KOS. While you could probably get away without patching GCC if you do not plan on ever using threads, C++, or Objective C in any of your programs, its really not a good idea (especially with advancements like C11). The patches used for this are included with KOS (in utils/dc-chain/patches). Several versions of patches are provided, but it is generally recommended for new toolchains to go with the latest versions of everything that have patches (and thus are tested). As of the time of this writing, the recommended versions of everything are Binutils 2.23.2, GCC 4.7.4, and Newlib 2.0.0.

The easiest way to proceed is to just use the dc-chain scripts and Makefile to build everything for you (other than KOS). They will take care of patching GCC and Newlib and building with the correct flags. If you want to do that, open up the dc-chain Makefile and check the various settings and adjust as necessary (often the only things you will need/want to change are the installation location for the toolchain and the location of the KOS sources). Be sure to read all the comments in it to make sure you do not need to change anything else for your installation. Once you are done adjusting the settings, run the two scripts included with dc-chain (download.sh and unpack.sh) to download the sources to Binutils, GCC, and Newlib and unpack them (if you changed the versions in the Makefile, you will have to change them in those scripts too or download and unpack the sources yourself). Once you're done with downloading/unpacking, all you should have to do is run "make" (possibly with sudo or as root depending on where you are installing things) and you should have a working toolchain after a little while.

If you don't trust the Makefile for some reason, then you probably want to build everything yourself. I trust that if this describes you, you probably have some idea of how things work. So, I will just provide how my toolchains are built and trust you to figure it out from there. ;) Here are the ways that each of my tools are configured:

• Binutils (sh-elf): --target=sh-elf
• GCC pass 1 (sh-elf): --target=sh-elf --without-headers --with-newlib --enable-languages=c --disable-libssp --disable-tls --with-multilib-list=m4-single-only,m4-nofpu,m4 --with-endian=little --with-cpu=m4-single-only
• Newlib (sh-elf): --target=sh-elf --with-multilib-list=m4-single-only,m4-nofpu,m4 --with-endian=little --with-cpu=m4-single-only
• GCC pass 2 (sh-elf): --target=sh-elf --with-newlib --enable-languages=c,c++,objc,obj-c++ --disable-libssp --disable-tls --with-multilib-list=m4-single-only,m4-nofpu,m4 --with-endian=little --with-cpu=m4-single-only --enable-threads=kos
• Binutils (arm-eabi): --target=arm-eabi
• GCC (arm-eabi): --target=arm-eabi --without-headers --with-newlib --enable-languages=c --disable-tls --disable-libssp --with-arch=armv4

Note that between building Newlib and GCC pass 2, you will need to symlink a few KOS header directories into the normal Newlib header paths otherwise GCC will not build properly. You should also copy a few KOS header files over their Newlib counterparts, although this may not be strictly required anymore. Look at the "fixup-sh4-newlib" target in the dc-chain Makefile for more information on that.

Building an environ.sh

Once you have a KOS tree extracted, figure out its path. This can be done by going to a shell (Cygwin or Linux/*NIX), changing to the dir containing KOS, and using 'pwd' (it'll print something like /home/foo/kos). This path will become your KOS_BASE.

Make a copy of doc/environ.sh.sample into your KOS_BASE. Edit this file with a text editor, and set KOS_BASE to the path from above. Also set KOS_CC_BASE and KOS_CC_PREFIX to match your compiler (generally the defaults are ok). You should also set DC_ARM_BASE and DC_ARM_PREFIX to point to the ARM compilers.

You may also need edit environ_dreamcast.sh if you've used a different compiler version than 4.7.x. The whys and hows of this aren't covered here, however.

Make sure environ.sh is sourced in any shell you'll do KOS work in. This can be done, for example, by changing to your KOS_BASE dir and using the command ". environ.sh". You can also add this to your ~/.bash_profile or similar, though I'm not going to cover that here.

Building KOS

Ok, the big test! Change to your KOS_BASE dir and run make. If all goes well, you should have a successful compile after a while. You may also want to go to the kos-ports dir and compile that.

Building Ports

You should place your ports tree at the same level as your KOS_BASE, to be standard. So for example, you might have ~/dc with your Dreamcast files in it, and then ~/dc/kos for KOS_BASE, and ~/dc/kos-ports for Ports.

Once you have the kos-ports tree in place, you can build any ports you want to use. To do so, simply cd to the directory of the port you want and run "make install clean" in that directory. That will build the specified port, and any dependencies it has.

If you want to build all ports in one go (which isn't necessarily recommended), you can do so by running "utils/build-all.sh" from the kos-ports directory.

Problems?

Join the KOS development list or the Dreamcast Dev IRC channel, and ask any questions there. There are a lot of really helpful people there who are happy to help you out. Really. :)

List/IRC info can be found here.