Building

[ requirements | unpacking | kroc | ccsp | rmox ]

Requirements

This page describes the steps needed to build RMoX from source. If you want to hack around with it, or intend to contribute to its development, this is the page you should be reading. If you just want to play around with it (and not have the hastle of installing a whole occam-pi system), download on of the binary images and run it in an emulator — see the user documentation.

Setting up a working build environment for RMoX is now much easier than it used to be. I'm currently developing RMoX on a Debian GNU/Linux system, running unstable/testing. The gcc version is 4.3.1 (November 2008). This appears to work fine, given past failures with earlier gcc versions (3.0, 3.1 and 3.2). Version 2.95.4 of gcc (as is installed on my Debian box) also works. Any gcc version that is known to correctly build Linux kernels should be adequate, however. You will need a Linux installation to build RMoX — RMoX will not build on Apple Macs, nor will it build under cygwin.

The first thing you'll want to do is get an up-to-date working KRoC installation. Because some of RMoX's development is tied in with the occam-pi compiler and run-time system, it's a good idea to use the latest development version of KRoC, available from subversion. See below in installing KRoC for how to do this quickly. If that fails, follow the KRoC installation guide (which has details on building KRoC for various platforms).

Installing KRoC

Building RMoX requires a working KRoC installation — for the occam-pi compiler and native-code translator mostly. If you downloaded a source tarball of KRoC (see the download page), called something like "kroc-1.5.0-pre4.tar.gz", you'll need to unpack this first:

bash:~/$ tar xzf /path/to/kroc-1.5.0-pre4.tar.gz
bash:~/$ mv kroc-1.5.0-pre4 kroc-src
bash:~/$

This will leave you with a "kroc-src" directory that contains the KRoC source tree (you should make sure that this directory didn't already exist!). If you checked out KRoC from its subversion repository, you'll already have a directory called kroc-src (or similar).

Next, build KRoC:

bash:~/$ cd ~/kroc-src
bash:~/kroc-src/$ ./build
KRoC  installation configuration
---------------------------------------------------------------------------
 .. configuration options

The defaults are usually sensible — the default install dir will be "~/kroc-src/install/" if that's where the build tree is. Hit return to start the build process.

If all goes well, you'll be left with a message along the following lines:

***********************************************************
*                          READ ME!                       *
***********************************************************

The KRoC distribution should now be installed.  Remember to source
the relevant file:

  /home/frmb/kroc_linux/ukcsource/install/bin/kroc-setup.sh   for sh/ksh/bash/zsh
  /home/frmb/kroc_linux/ukcsource/install/bin/kroc-setup.csh  for csh/tcsh
 .. more output

Any packages within KRoC that failed to build will be listed here. This is usually packages that depend on other software, such as the SDL and OpenGL graphics, and any packages that depend on those. However, these are not particularly important for building RMoX, but if you plan on playing around with occam-pi generally, it may be worth installing support for the missing packages.

For fuller details on building KRoC (including if any of the above failed), see the KRoC installation guide.

Unpacking the RMoX source

Assuming KRoC is installed successfully and works (e.g. the supplied example programs work), you will then need to get the RMoX and CCSP source. The subversion copy is your best bet — follow the instructions on the download page for how to get these.

Once downloaded, you should have a directory structure along the following lines:

    oos/               top-level (you can call this what you like)
    oos/ccsp/          where the CCSP run-time system resides
    oos/rmox/          where the RMoX sources reside

RMoX sources from tarball:

If you downloaded a tarball for RMoX, you'll need to unpack it yourself. The tarballs are named by the subversion revision they came from (8888 is just a placeholder, replace with the version number you actually have). E.g.:

bash:~/$ cd ~/oos/
bash:~/oos/$ tar xzf /path/to/rmox-r8888.tar.gz
bash:~/oos/$ mv rmox-r8888 rmox
bash:~/oos/$

You only need to do this once ideally — the tarball (now unpacked in "oos/rmox/") has the subversion stubs for updating.

CCSP sources from KRoC:

If you didn't grab CCSP from subversion, you'll need to copy the version out of your KRoC installation. If you still have the KRoC tarball, do something like:

bash:~/$ cd ~/oos/
bash:~/oos/$ tar -xz --strip-components 2 -f /path/to/kroc-1.5.0-pre4.tar.gz kroc-1.5.0-pre4/runtime/ccsp
bash:~/oos/$

If you don't have a tarball, copy the tree from the KRoC sources, e.g.:

bash:~/$ cd ~/oos/
bash:~/oos/$ (cd /path/to/kroc-src/runtime/ && tar cf - ccsp) | tar xf -
bash:~/oos/$ cd ~/oos/ccsp/
bash:~/oos/ccsp/$ make clean
 .. output from make
bash:~/oos/ccsp/$

In either case you should be left with a clean copy of CCSP.

Configuring and building CCSP for RMoX

RMoX requires a particular build of the CCSP run-time kernel. At the point, you should have the directory "oos/ccsp/". If not, see the instructions above for grabbing a copy from an existing KRoC tree, or the download page for a subversion copy. Then:

1. Change into the CCSP directory and run the configure script:

   
   bash:~/$ cd ~/oos/ccsp/
   bash:~/oos/ccsp/$ ./configure --with-rmox=/path/to/oos/rmox --disable-sse2 --enable-mp
    .. output from configure
   
   

   There are two optional configuration options shown above:

   • --disable-sse2 explicitly disables the use of SSE2 instructions. This is necessary if you're going to run RMoX on hardware that doesn't have them (e.g. an AMD Geode, or Intel Pentium 1, 2 or 3). Modern CPUs, Intel Pentium 4+s, Intel Core2s, AMD Athlon 64, AMD Opteron, etc. should have them. Wikipedia (SSE2) has a list of CPUs that do support it (and thus don't need this option). Any recent versions of the QEMU emulator (if this is how you intend to run RMoX) should have SSE2 instruction support.

   • --enable-mp explicitly enables the multiprocessor support in the run-time kernel. This is necessary if you want to play around with the (currently experimental) multiprocessor support in RMoX. You'll need a version of CCSP from KRoC 1.5.0-pre5 or later, or the latest subversion copy, for this to work.

2. Next, compile CCSP:

   
   bash:~/oos/ccsp/$ make
    .. output from make
   
   

Building RMoX

Once you have a working KRoC installation and a copy of CCSP built for RMoX, you can configure and build the RMoX operating system:

1. First, make sure that you have source the KRoC setup file, and have a working "kroc":

   
   bash:~/$ source /path/to/kroc-src/install/bin/kroc-setup.sh
   bash:~/$ kroc --version
   KRoC version 1.5.0-pre4 targeting i686-pc-linux-gnu (driver V2.0)
    .. kroc author list
   bash:~/$
   
   

   If you are using the "csh" or "tcsh" shell, source the 'kroc-setup.csh' file instead. Also consider changing to a less broken shell. :-)

2. Next, change into the RMoX source directory:

   
   bash:~/$ cd ~/oos/rmox/
   bash:~/oos/rmox/$
   
   

3. If you need to, edit the RMoX configuration using vi (or your favourite editor):

   
   bash:~/oos/rmox/$ vi occam/include/rmox_config.inc
   
   

   The available configuration options are plentiful. There will be some occamdoc style comments at the top of the file, which provide some information on configuration. Most of the enabled device drivers are compiled into the RMoX kernel, but not activated by default. So including drivers for which you don't have hardware shouldn't be a problem.

   The default build is for the "baremetal" version of RMoX — designed for running on real hardware or within an emulator such as QEMU.

4. Next you'll need to configure the RMoX build system using the provided configure script:

   
   bash:~/oos/rmox/$ ./configure --with-ccsp=/path/to/oos/ccsp --with-empty-grub-image=/path/to/empty-grub-20081107.img
   
   

   The option "--with-empty-grub-image" is only needed when building a version of RMoX prior to revision 4327. You can download the image file here.

5. After changing the configuration, or when building for the first time, it's a good idea to update the dependencies:

   
   bash:~/oos/rmox/$ make update-deps
    .. output from make
   bash:~/oos/rmox/$
   
   

   You should not see any errors from this (references to missing dependencies are okay).

6. Finally, compile RMoX:

   
   bash:~/oos/rmox/$ make
    .. output from make
   LINK    baremetal/rmox
   VAL []BYTE rmox.datestamp IS "20081109022028":
   HDIMAGE baremetal/hdimage.rmox
   
   bash:~/oos/rmox/$
   
   

   If this is successful, you will be left with two files:

   • baremetal/rmox: the multiboot image that can be loaded over a network or by GRUB on real hardware.

   • baremetal/hdimage.rmox: a (24 MiB) hard-disk image that can be used with an emulator such as QEMU. It contains GRUB and the RMoX kernel image.

   See the user documentation for details on booting these images (on real hardware or QEMU).

   As the last couple of 'make' output lines show, each compiled version of RMoX has a date-stamp embedded into it. When RMoX is run, this datestamp is visible on virtual terminals running the system-console (appears alongside the RMoX kernel version, e.g. '0.1.5'). The datestamp is useful to ensure that you have booted the latest version compiled (may be affected by caching in TFTP servers when booting on a network).