A Scalable, Compositional Operating-System
for Commodity Platforms

Building

Readme.1st

For the latest versions of RMoX, you should follow the instructions here: https://www.cs.kent.ac.uk/research/groups/sys/wiki/Building_RMoX.

Prologue

This page describes the necessary steps for building RMoX from sources. Particularly if you intend to constribute to the development of it! :-).

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 3.3.5. This appears to be largely working so far, 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.

The directory structure for RMoX should be laid out as follows:

    oos/                   top-level (you can call this what you like, but I use oos)
    oos/minlinux/          where the minlinux tree resides
    oos/rmox/              where the RMoX sources reside

You only need to create the top-level yourself -- the other two are expanded out from the tarballs. The important thing is that "minlinux" and "rmox" are siblings (unless you want to get symb-link happy).

Unpacking the source

The first stage is to download and unpack the various components of RMoX.

Download the latest minlinux and rmox tarballs from the download page.

Extract these files in the "oos/" directory thus:

    bash:˜/oos/:0$ tar xvzf /tmp/minlinux-0.1.3.tar.gz
    ...  output from tar
    bash:˜/oos/:0$ tar xvzf /tmp/rmox-0.1.3.tar.gz
    ...  output from tar

If you only plan to use user-mode RMoX then you only need the RMoX source tree (not minlinux), and follow the steps for building UM-RMoX.

Configuring minlinux

The next stage is to configure minlinux, a stripped-down version of Linux, that currently provides the boot environment for RMoX (as time goes on RMoX will get bigger and minlinux will get smaller).

Change into the newly populated "minlinux/" directory and configure minlinux. This should be relatively straight-forward:
```
    bash:˜/oos/minlinux/:0$ make menuconfig
```
The default options should be fine, so just exit and save the configuration. You can also use "make oldconfig" if you trust the supplied configuration. If you don't have "ncurses" installed, you can use "make xconfig" or just plain "make config" instead to configure minlinux (although the last of these is slightly terse).
Next, as per a message displayed when the configuration is finished, build the dependencies for minlinux:
```
    bash:˜/oos/minlinux/:0$ make dep
    ...  output from make
```

Setting up CCSP for RMoX

The third stage is building CCSP for RMoX. Building this for the real version (i.e. non-user-mode) requires the RMoX source tree to be in place, that you should have already unpacked.

Download and install the latest pre-release of KRoC/Linux (if you didn't already). Version 1.3.4-pre4 or later is currently required to build RMoX. Instructions for compiling and installing KRoC are given on the (official) KRoC home-page, but apply equally to pre-release versions. Where you build KRoC is up to you -- it doesn't have to be in the "oos/" tree.
Change into the CCSP source directory ("src/ccsp-1.6/" in the KRoC source tree) and clean up from any earlier build (e.g. for the ordinary KRoC you maybe just compiled).
```
    bash:˜/kroc/kroc-1.3.4-pre4/src/ccsp-1.6/:0$ make distclean
    ...  output from make
```
this will fail if the source tree was already clean, but it doesn't matter in that case.

Run the pre-configure script:

    bash:˜/kroc/kroc-1.3.4-pre4/src/ccsp-1.6/:0$ ./preconfigure
    ./preconfigure: setting up for i386/linux architecture

Configure CCSP for RMoX:

    bash:˜/kroc/kroc-1.3.4-pre4/src/ccsp-1.6/:0$ ./configure --enable-oos-build --with-minlinux=$HOME/oos/minlinux --with-oos=$HOME/oos/rmox

This should configure without any errors, if the "minlinux" and "rmox" source trees are in place.

Compile CCSP:

    bash:˜/kroc/kroc-1.3.4-pre4/src/ccsp-1.6/:0$ make

Build the archive library that RMoX requires:

    bash:˜/kroc/kroc-1.3.4-pre4/src/ccsp-1.6/:0$ make libkroc_oos.a

Once built (should be very quick), copy the generated "libkroc_oos.a" into the RMoX source tree:
```
    bash:˜/kroc/kroc-1.3.4-pre4/src/ccsp-1.6/:0$ cp libkroc_oos.a ~/oos/rmox/
```

Building RMoX

The fourth stage is to build RMoX itself. This stage is not relevant for building user-mode RMoX -- see UM-RMoX section for that.

Source the KRoC setup file for your shell. For example:

    bash:˜/kroc/kroc-1.3.4-pre4/:0$ source bin/setup.sh

Change to the RMoX source directory (e.g. "oos/rmox/"), which you should have unpacked earlier (see steps 1 and 2).
Edit the top line of the top-level `Makefile' to set the location of the minlinux source-tree, for example:
```
    MINLINUX = /home/frmb/oos/minlinux
```
Edit the RMoX configuration in "occam/include/rmox_config.inc". The supplied configuration may be adequate.
Build the other configuration files by running "mkconfig":
```
    bash:˜/oos/rmox/:0$ ./mkconfig
```
Build the occam run-time system by changing into the "occam" directory and running "make":
```
    bash:˜/oos/rmox/occam/:0$ make
    ...  output from make
```
This creates the `librmox.a' archive, containing all the occam code.
Back-up to the RMoX top-level directory and build the other parts of RMoX with:
```
    bash:˜/oos/rmox/:0$ make
    ...  output from make
```

Linking it together

The fifth (and final) stage is to combine all the various parts together into a bootable image.

Change into the "oos/minlinux/" tree and do a "make bzImage":
```
    bash:˜/oos/minlinux/:0$ make bzImage
    ...  output from make
```
This (if successful) will leave behind the file: "arch/i386/boot/bzImage".
At the point you should either write the image to a floppy disk and boot it on real hardware, or use an emulator such as QEMU or bochs.
Enjoy! :-)

Building user-mode RMoX

Building user-mode RMoX is a somewhat simpler process. It is recommeded that you use the latest KRoC/Linux pre-release (currently 1.3.4-pre4).

Ensure you have a working KRoC/Linux system. Follow the instructions in step 6 above if necessary (pre-releases here, installation instructions). Make sure you remember to source the KRoC setup file.
If you hadn't done so already, download and unpack the current RMoX tarball rmox-0.1.3.tar.gz and unpack it in a suitable place:
```
    bash:˜/oos/:0$ tar xvzf /tmp/rmox-0.1.3.tar.gz
    ...  output from tar
```
Change into the "rmox/" directory and edit the file "occam/include/rmox_config.inc" such that the first few lines read:
```
    --{{{  raw/user-mode selection
    #DEFINE USE.UM.RMOX
    --#UNDEF USE.UM.RMOX
    --}}}
```
You may also want to check the rest of the file for specific User-Mode configuration.
Build the other configuration files by running "mkconfig":
```
    bash:˜/oos/rmox/:0$ ./mkconfig
```
Now to compile user-mode RMoX. There are some minor dependency issues still, but these are relatively minor.
1. Change into the "rmox/occam/" directory and run "make":
```
    bash:˜/oos/rmox/occam/:0$ make
    ...  output from make
```
  This will fail at some point, but that's OK. The errors should be related to "xtextwindow", "vga.driver" and "keyboard.driver" (i.e. they are missing).
2. Change into the "rmox/um-rmox/" directory and run "make":
```
    bash:˜/oos/rmox/um-rmox/:0$ make
    ...  output from make
```
  This should compile successfully.
3. Change back into the "rmox/occam/" directory and run "make" again:
```
    bash:˜/oos/rmox-0.1.2/occam/:0$ make
```
  This time, it should all compile successfully, leaving "librmox.a" in that directory.
4. In the same directory ("rmox/occam/") run "make um-rmox":
```
    bash:˜/oos/rmox/occam/:0$ make um-rmox
```
  This will produce an executable called "occ_kernel", which you simply run :-)
```
    bash:˜/oos/rmox/occam/:0$ ./occ_kernel
```
Enjoy! By default, the built-in animations/demos are disabled in User-Mode RMoX. To enable them, comment out the line in `rmox_config.inc' that reads:
```
    #DEFINE DISABLE.ANIMATIONS
```
To re-build user-mode RMoX, you only need to "make um-rmox" again. The "librmox.a" file isn't used for User-Mode RMoX, but serves as a good test-point.

A Scalable, Compositional Operating-Systemfor Commodity Platforms