1. Installing prerequisites
  2. Getting the KRoC source
  3. Installing KRoC (for end users)
  4. Installing KRoC (for developers and packagers)
  5. Using KRoC

This page describes how to install KRoC on your machine.

Installing prerequisites

The KRoC suite currently supports the following operating systems. You should read the specific instructions for your platform before continuing with this page.

If your machine is running a 64-bit operating system (e.g. the amd64 version of Debian or Ubuntu), please read 64BitNotes before installing KRoC.

If your machine does not have an IA32 (x86) or AMD64 (x86-64) processor, you'll need to specify the Transterpreter toolchain when building; see below for more information.

If you want to port KRoC to a new platform, please get in contact with us first!

Getting the KRoC source

There are three supported ways of obtaining a KRoC source tree:

  • checking out the stable source code from Subversion
  • checking out the development source code from Subversion
  • using a stable release tarball

... from Subversion

Subversion is the source code control system that we use to manage KRoC development. You can use a Subversion client to download either a stable, supported version of KRoC, or the latest development version.

The stable version is likely to be your best bet as a user, since it contains the latest bug fixes for KRoC. To check out the stable KRoC source tree, say: 

svn co http://projects.cs.kent.ac.uk/projects/kroc/svn/kroc/branches/kroc-1.5 kroc-svn

(svn may ask you to accept a certificate; say p to permanently accept it.)

The development version will probably only be of use if you want to work on KRoC yourself or try out our very latest changes; we don't suggest you use it normally, since it sometimes contains incomplete or experimental work. To check out the development tree, say: 

svn co http://projects.cs.kent.ac.uk/projects/kroc/svn/kroc/trunk kroc-svn

This will result in a kroc-svn directory containing a complete KRoC source tree. Once you've got a KRoC distribution this way, you can use svn update (in the kroc-svn directory) at any time to update the source tree to the latest Subversion version.

... from a tarball

If you are unable to use Subversion to download KRoC, tarball releases of KRoC can be found on Fred's KRoC pre-releases page. Since KRoC changes rapidly, the tarball version is likely to be somewhat out of date relative to Subversion; if you encounter problems with it, we suggest you try the stable Subversion version first.

Simply extracting the tarball will give you a kroc-VERSION directory.

Installing KRoC (for end users)

For most users who've downloaded a KRoC source tree, the easiest way to compile and install KRoC is to use the build script that's provided. (If you want to make changes to KRoC, or you're packaging KRoC for an operating system distribution, see the next section.)

build supports several options; to list all of them, run: 

./build --help

For your first KRoC installation, the only one you will probably need to use is --prefix, which sets the directory into which KRoC will install. A typical invocation will look like: 

./build --prefix=/usr/local/kroc

I'll assume that you used the prefix in the example above for the rest of the instructions; if you installed it somewhere else, then change /usr/local/kroc to whatever you specified as --prefix in the examples below.

It's often convenient to use an installation directory somewhere inside your home directory -- e.g. $HOME/kroc -- because then you can build and install KRoC as your regular user without needing to fiddle with permissions. If you do use /usr/local/kroc, then you will need to create that directory as root and chown it to your regular user (or just run the ./build script as root, which we don't recommend).

Alternatively, you can install KRoC directly into a system prefix such as /usr/local (which is the default if you don't specify --prefix), which will generally mean you won't need to source kroc-setup.sh to set up your environment when using KRoC (assuming that you have /usr/local/lib listed in /etc/ld.so.conf, so your machine knows to look there for shared libraries). You should probably try installing KRoC into a separate directory first so you know where it's going to put things.

After the build script has completed successfully, we recommend that you run the KRoC test suite to check that the basics of KRoC work on your system: 

make check

The Transterpreter

If the machine you want to run occam-pi programs on doesn't have an IA32 (or AMD64) processor, then you'll need to use the Transterpreter, an interpretive implementation of the occam-pi virtual machine, rather than the native code toolchain based on tranx86 and CCSP.

To build the Transterpreter toolchain, give the option --with-toolchain=tvm to ./build.

Cluster support

The pony module ships with KRoC, and provides support for channels that transparently span TCP/IP network connections. It allows you to build applications that run on clusters of PCs. It requires special support from the compiler, which isn't enabled by default because it makes most occam-pi programs slightly slower and more memory-hungry.

If you want pony support in your KRoC system, then you should give the option --enable-pony to ./build.

Installing KRoC (for developers and packagers)

KRoC, like many other free software packages, is built using GNU automake. If you've downloaded a tarball release of KRoC (version 1.5.0-pre5 or later), you can install it in the same way as any other automake package: 

./configure --prefix=...
make
make install

If you've downloaded KRoC from Subversion, however, there won't be a configure script in the tree yet; you need to generate it from the configure.ac file first. To do this, run: 

autoreconf -vfi

After you have configured KRoC once, typing make will usually regenerate the automake files if necessary -- unless a new directory has been added to the KRoC source tree, in which case another autoreconf -vfi will be necessary to force a rebuild.

KRoC's installation process supports DESTDIR, so it should be straightforward to create packages of KRoC for operating system distributions. If you're doing this, please let us know!

Using KRoC

KRoC installs the scripts kroc-setup.sh and kroc-setup.csh that you can source in order to set up your $PATH and other environment variables -- for example, if you're using the bash shell, then you might say: 

. /usr/local/kroc/bin/kroc-setup.sh

... which'll then make all the KRoC commands immediately available to you. As with build, you don't have to use kroc-setup.sh, but it's usually convenient. You might want to include that command or an equivalent in your shell profile if you often use KRoC.

To check that your new KRoC installation works, put this into a file called hello.occ: 

#INCLUDE "course.module"
PROC hello (CHAN BYTE out!)
  out.string ("Hello, world!*n", 0, out!)
:

and run occbuild --program hello.occ to compile it; this should give you a binary called hello.