Difference between revisions of "Compiling KOS on Linux"

From DCEmulation
Jump to navigation Jump to search
m (Pre-built toolchain: Updating the link -- It's been out of date for a few weeks.)
Line 1: Line 1:
Written by [http://dcemulation.org/phpBB/memberlist.php?mode=viewprofile&u=29043 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==
 
==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).  
+
This tutorial is a step-by-step guide on how to setup a toolchain and KOS environment on your GNU/Linux system.
  
 
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.  
 
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).  
 
KOS consists of the operating system core (kos) and a set of nicely integrated libraries (kos-ports).  
 +
 +
==Install script==
 +
Please consider trying this [http://dcemulation.org/phpBB/viewtopic.php?f=29&t=103850&p=1049044#p1049029 install script] first. It will perform the steps below automatically.
 +
On Debian-compatible systems it will ask you to install missing dependencies automatically.
  
 
==Preparations==
 
==Preparations==
 
 
You need the following software installed:  
 
You need the following software installed:  
  
*subversion
+
*git
*make  
+
*make (build-essential package)
 
*tar/gzip/bzip2  
 
*tar/gzip/bzip2  
*development packages of libjpeg and libpng
+
*gcc/g++ (Debian packages gcc-4.9 + g++-4.9 or 4.7 are recommended, 4.7 and 5+ are buggy)
 
+
*development packages of libjpeg and libpng
If you want to compile the toolchain yourself, you also need:
+
*patch
 
+
*wget
*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==
 
==Downloading KOS==
  
KOS is available through a Subversion repository at SourceForge.  
+
KOS is available through a Git repository at SourceForge.
 
+
The standard install directory assumed in the configuration files is /opt/toolchains/dc/{kos, kos-ports}.
$ 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!
+
$ git clone git://git.code.sf.net/p/cadcdev/kallistios /opt/toolchains/dc/kos
  
A pre-built toolchain for i386 machines is available at
 
[http://dchelp.dcemulation.org/site/downloads/dc-toolchain-gcc346-1-i386.tar.bz2 dc-toolchain-gcc346-1-i386.tar.bz2].
 
  
In order to install it, unpack the tarball to / (as root):  
+
==Toolchain (cross-compiler and libraries)==
 +
After cloning the KOS repository, run the toolchain download+unpack+compile scripts:
  
  $ tar jxf dc-toolchain-gcc346-1-i386.tar.bz2 -C /
+
  $ cd /opt/toolchains/dc/kos/utils/dc-chain
 +
$ sh download.sh
 +
$ sh unpack.sh
  
The toolchain will then be available under /usr/local/dc.
+
For compilation of the cross-compiler and system libraries, GCC version 4.8 and 5+ are known to cause issues, so please specify version 4.9 or 4.7 after installing the package gcc-4.9 and g++-4.9 (or 4.7).
 +
The erase=1 will delete temporary files after a successful build.
  
===Compiling the toolchain yourself===
+
$ CC=gcc-4.9 CXX=g++-4.9 make erase=1
  
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.
+
After this command completes successfully you have a working cross-compiler for Dreamcast and can compile KOS next.
 
 
(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==
 
==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:
+
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:
 
 
$ 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:  
+
Go into the kos directory and copy the template configuration:  
  
  export KOS_CC_BASE="/home/foobert/dc/sh-elf"
+
  $ cp /opt/toolchains/dc/kos/doc/environ.sh.sample /opt/toolchains/dc/kos/environ.sh
export KOS_CC_PREFIX="sh-elf"
 
export DC_ARM_BASE="/home/foobert/dc/arm-elf"
 
  
Next we "start" our Dreamcast development environment:
+
Now edit environ.sh to match your installation. If you use the default installation directory you don't need to change anything.
  
$ source environ.sh
+
Execute the following command to set the KOS environment variables:
  
This makes all the configuration variables defined in the environ.sh script available in the shell's environment.
+
$ source /opt/toolchains/dc/kos/environ.sh
  
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.  
+
Remember to do this every time you want to use the KOS environment in a newly opened shell.
 +
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:  
 
Now we are finally ready to compile KOS itself. In the kos directory, run:  
 
   
 
   
  $ cd /home/foobert/dc/kos  
+
  $ cd /opt/toolchains/dc/kos  
$ make
+
  $ 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.  
+
==KOS-Ports==
 +
KOS-Ports is a repository with commonly used libraries for development on the DC, like PNG or MP3 loading.
  
Now you should have a working Dreamcast development environment :-)
+
Clone the repository:
  
Check out the examples in the KallistiOS directory to find out how to use KOS in your own projects!
+
$ git clone --recursive git://git.code.sf.net/p/cadcdev/kos-ports /opt/toolchains/dc/kos-ports
  
==dcload==
+
Compile all KOS-ports using the build-all script
  
'''NOTE: This section is still incomplete!
+
$ sh /opt/toolchains/dc/kos-ports/utils/build-all.sh
  
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.
+
Now you should have a working Dreamcast development environment :-)  
 
 
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.
+
Check out the examples in the KallistiOS directory to find out how to use KOS in your own projects!

Revision as of 08:05, 15 March 2016

Overview

This tutorial is a step-by-step guide on how to setup a toolchain and KOS environment on your GNU/Linux system.

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).

Install script

Please consider trying this install script first. It will perform the steps below automatically. On Debian-compatible systems it will ask you to install missing dependencies automatically.

Preparations

You need the following software installed:

  • git
  • make (build-essential package)
  • tar/gzip/bzip2
  • gcc/g++ (Debian packages gcc-4.9 + g++-4.9 or 4.7 are recommended, 4.7 and 5+ are buggy)
  • development packages of libjpeg and libpng
  • patch
  • wget

Downloading KOS

KOS is available through a Git repository at SourceForge. The standard install directory assumed in the configuration files is /opt/toolchains/dc/{kos, kos-ports}.

$ git clone git://git.code.sf.net/p/cadcdev/kallistios /opt/toolchains/dc/kos


Toolchain (cross-compiler and libraries)

After cloning the KOS repository, run the toolchain download+unpack+compile scripts:

$ cd /opt/toolchains/dc/kos/utils/dc-chain
$ sh download.sh
$ sh unpack.sh

For compilation of the cross-compiler and system libraries, GCC version 4.8 and 5+ are known to cause issues, so please specify version 4.9 or 4.7 after installing the package gcc-4.9 and g++-4.9 (or 4.7). The erase=1 will delete temporary files after a successful build.

$ CC=gcc-4.9 CXX=g++-4.9 make erase=1

After this command completes successfully you have a working cross-compiler for Dreamcast and can compile KOS next.

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:

$ cp /opt/toolchains/dc/kos/doc/environ.sh.sample /opt/toolchains/dc/kos/environ.sh 

Now edit environ.sh to match your installation. If you use the default installation directory you don't need to change anything.

Execute the following command to set the KOS environment variables:

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

Remember to do this every time you want to use the KOS environment in a newly opened shell. 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 /opt/toolchains/dc/kos 
$ make


KOS-Ports

KOS-Ports is a repository with commonly used libraries for development on the DC, like PNG or MP3 loading.

Clone the repository:

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

Compile all KOS-ports using the build-all script

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

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!