occam-pi Learning Resources

Are you new to the occam-pi programming language? This page is for you: it collects resources that are likely to be of use to people who're learning occam-pi.

General resources

• occam-pi - the occam-pi home page (which you can get to quickly by going to http://occam-pi.org/)
• concurrency.cc - currently the home page for occam-pi on the Arduino, the long-term plan is to make concurrency.cc the main collection of resources for programming in occam-pi and related languages.
• KRoC - the KRoC home page. KRoC is the suite of software that contains most of the occam-pi development tools and libraries; this site has information on how to install KRoC.
• Transterpreter - home page for the Transterpreter (a portable occam runtime for small devices that's now included with KRoC).
• WoTUG - the organisers of the CPA conference series, which features many papers about occam and other process-oriented languages, many of which are available from their web site.
• Systems Research Group Wiki - (older) wiki at Kent that contains a lot of occam material. Most of the occam content will move to concurrency.cc eventually.
• CSProjects - the Subversion/Trac service at Kent that hosts many occam-related projects.

Learning the language

• Plumbing for the Arduino - a book that'll introduce you to occam-pi using the Arduino physical computing platform.
• occam-pi reference guide - a quick reference to occam-pi aimed at beginners, with many of the occam-pi extensions included.
• occam 2.1 reference guide - the full manual for the previous version of the language. This is a good guide to the basic semantics and syntax of occam, but it doesn't include the occam-pi extensions to the language.
• occam books online - a list of online books about occam.
  • In particular, Geraint Jones' "Programming in occam 2" is an excellent beginner's guide to classical occam.
• occam-pi workshop/course - slides and example programs for a seminar that describes the new features in occam-pi. In combination with a beginner's guide to occam 2, this'll give you a reasonable overview of what the language offers.
• Occam Enhancement Proposals - proposed improvements to occam-pi. This contains a reasonably complete list of the new features in occam-pi over occam 2, along with future ideas for improvements to the language.
• (You may find the "Getting Started with KRoC" document if you're browsing around for occam-pi material; this is now very out-of-date, and we suggest you ignore it.)

Writing programs

The most important bit of advice: before writing any code, draw a process diagram of your program.

• OccamDoc - the reference manual for the modules that come with occam-pi. (This is also installed as part of KRoC.)
• OccamDoc how-to - want to produce documentation like the above for your own programs? This shows how to add OccamDoc comments to your programs.
• occam-pi style guide - Adam's (somewhat biased) guide to writing occam-pi that looks like everybody's else's.
• Transforming procedural code into occam-pi - wondering how to design an occam-pi program? This page describes some of the parallels between sequential and process-oriented code.

Compiling and running programs

Assuming you've installed KRoC on your machine already, you can use the occbuild program to compile occam programs. This works the same way for both the Transterpreter and the native-code version of KRoC.

A very brief summary: assuming you've written myprogram.occ, you can compile it by saying:

occbuild --program myprogram.occ

and then run it by saying:

occbuild --run myprogram

If you want to do something more complicated (e.g. building a program from multiple source files, or building a module), then have a look at the occbuild web page for more details.

Text editors

occam-pi is an indentation-structured language (whitespace is important, like in Python or Haskell). You will need a decent text editor to work with it; here are some suggestions:

• Vim is a heavily-extended and friendlier version of the classic Unix vi editor, freely available for pretty much all platforms, and it comes with occam-pi support built in. It's probably the most popular editor for occam-pi.
  • Vim's extremely powerful, but has a steep learning curve -- if you've not used it before, you should definitely work through the built-in tutorial.
  • Mario's Kent Vim Extensions add some extra features to Vim that are useful for occam programmers.
  • If you're used to a Windows-style text editor but want to take advantage of Vim's power, the Cream package provides Windows-style behaviour for Vim.
• Kate is a programmer's editor for KDE, but you can use it in GNOME too (and on MacOS and Windows).
  • A Kate syntax highlighting file for occam-pi is available; it also supports folding.
• jEdit is a Java-based editor that's available for many platforms.
  • There's an occPlug plugin for jEdit that makes it integrate with the Transterpreter. (This is currently in need of cleaning up.)
  • To configure it for occam:
    • Utilities -> Global Options -> Editing -> "change settings for mode" occam -> "file name glob": change this to .occ. Select "no word wrap", explicit folding, wrap margin = 0, tab width = 2, indent width = 2, select soft tabs.
    • In the same Global Options frame, select 'Text Area' (under the Jedit branch) and pick a reasonable font. You may also find it useful to change the current line highlighting.
    • Again, in Global Options, under 'Syntax Highlighting' you can change the colours of a set of features (e.q. comments). There is also the possibility of adding new keyword highlighting commands, e.g. occam-pi ones, like MOBILE, by editing /usr/share/jEdit/modes/occam.xml.
• gedit is the default text editor on many Linux distributions. The VHDL syntax highlighting mode sort of works for occam, but it's so limited that we don't recommend using it.

Tips for configuring your editor

You will find working with occam much more pleasant if you tell your editor a bit about the language first.

• Enable syntax highlighting. Many editors support occam already, but they might not know all the occam-pi keywords. The extensions used for occam source code are .occ and .inc.
• Use two-space soft tabs -- i.e. make your editor insert spaces when you press the tab key. While the occam compiler understands what to do with hard tabs, it's usually better to avoid them (as in most languages).
  • Learn how to use your editor's "indent block" and "unindent block" commands (< and > in Vim; often Tab and Shift-Tab with a block selected in other editors). You'll often want to move a block of code in or out by an indentation level when working with occam.
• Folding allows you to collapse a block of code surrounded by magic comments down to a single line; most occam programs make heavy use of folding to simplify the structure of the code. Turn on folding with the explicit markers:

  
  --{{{ code for sending a message to server
  SEQ
    ...  some code that is awesome
  --}}}
  

• Pick a font that's easy to read and distinguishes between characters that are likely to be confused in programming languages (1, l, I, !; O, 0, Q). Mark likes Courier/Nimbus Mono; Adam likes Neep.

Educational occam-pi programs

The KRoC distribution includes lots of example occam-pi programs -- have a look in the demos directory, or in the various modules/whatever/examples directories. However, the programs in KRoC have been written by many people over a period of about 25 years, so the style and conventions tend to vary quite a bit...

For examples of "modern" occam-pi code, we'd suggest that you look at these directories:

• modules/course/examples and modules/course/exercises: the example programs and student exercises from the University of Kent concurrency course.
• demos/complexity: a set of example programs written by Mark Read that introduce various occam-pi features incrementally, with documentation showing the changes to the program.
• demos/game: a multiuser adventure game written in occam-pi, used in the Kent "advanced concurrency" course.
• demos/ttygames and modules/occade/examples: various arcade games written in occam-pi.

Common problems

Need some information on how to use Subversion to check out and work with code? Have a look at the svnbook.

Downloaded an occam program from somewhere, unpacked it, and now you're staring at a configure.ac file wondering how to use it to compile the program? See Using Automake.

If you're trying to run a program that uses the pony or trap networking systems, you will probably need to start the corresponding nameserver program (ponyanstcpip or trapns) first, so your cluster nodes can find each other. You may also need to create a config file to help your program find the nameserver.

Compiled your program, and now it's complaining that it can't find libfoo.so when that file is clearly in the current directory? The quick fix is to tell the OS to look in the current directory for shared libraries: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:.. (If you're on MacOS X, use DYLD_LIBRARY_PATH instead.)