So you want to get started, but have no idea how. Well, you are not
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:
- Install prerequisites
- Pull KOS from Git (or use a release version)
- Compile Binutils
- Compile GCC
- Compile Newlib
- Compile GCC again
- Setup an environ.sh
- Compile KOS
- Compile Ports (optional)
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
- 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
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
- Newlib (sh-elf): --target=sh-elf
- GCC pass 2 (sh-elf): --target=sh-elf --with-newlib
--enable-languages=c,c++,objc,obj-c++ --disable-libssp --disable-tls
- Binutils (arm-eabi): --target=arm-eabi
- GCC (arm-eabi): --target=arm-eabi --without-headers --with-newlib
--enable-languages=c --disable-tls --disable-libssp
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
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
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,
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.
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.
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
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.