occam For All : Kent Retargetable Occam Compiler (KROC)

Version 0.9 Beta

Installation and Use Document

KROC is currently available as a binary release for Sun SPARCs, running a SunOS 4.1.3 variant or SunOS 5.5 (Solaris 2.5) or DEC Alphas running OSF1/3.0. If you haven't got either of these, our apologies. (See README and TARGETS documents for more information.

Configuring KROC

Run the 'configure' shell script from the UNIX prompt. It should run to completion like below (Assuming here you extracted the distribution under '/usr/local/kroc'):

    unix% ./configure
    checking host system type
    Configuring kroc for a sparc-sun-sunos4.1.3_U1 target.
    creating ./config.status
    creating Makefile
    creating bin/kroc
    creating setup.csh
    creating setup.sh
    Configuration done

    Now add /usr/local/kroc/bin to your search path:
      set path=(/usr/local/kroc/bin $path)
        for C-shell (csh) or related shells
        (Script for this stored in /usr/local/kroc/setup.csh )

        for Bourne Shell (sh), Bash or related shells.
        (Script for this stored in /usr/local/kroc/setup.sh )

Most people use the C shell so just type the following:

    unix% set path=(/usr/local/kroc/bin $path)

If you intend to use KROC again, either re-configure or add the relevant lines to the end of your .cshrc (C Shell) or .bashrc (Bash) etc.

Using KROC

Now if you now type kroc you should get a usage message. If something like this doesn't appear, check the setup above.

unix% kroc
KROC version 0.9beta targeting sparc-sun-sunos4.1.3_U1 (driver V1.34)
Usage: kroc [options] [occam sources/pre-compiled sources]
  -b,  --brief         Give brief occ21 error messages
  -c,  --compile       Compile source to objects, do not link
  -h,  --help          Print this message and exit
  -IDIRECTORY          Search DIRECTORY for occam libs & includes, C headers
  -k,  --keep-temp     Keep temporary files
  -v,  --version       Print version
  -lNAME               Link with native library libNAME.a
  -LDIRECTORY          Search DIRECTORY for native libraries
  -n,  --dry-run       Do not run any commands; just print them.
       --oc-opts=opts  Use these occam compiler (occ21) options
       --oc-opts opts    ""
       --cc-opts=opts  Use these C compiler (gcc) options
       --cc-opts opts    ""
  -oFILE, -o FILE      Place output in file FILE
  -p,  --pre-compile   Pre-compile occam source to .ktx files
  -t2, -t4, -t8, -t9   Set processor compilation class (default t8)
  -v,  --verbose       Show commands run during compilation
  -w,  --warn          Additional warnings from occ21
  -X1, -X2             Experimental options (ETC, UDO)
  -nw, --no-warn       Give no warnings from occ21

kroc compiles occam source files, which we recommend are suffixed '.occ', into executables which have no suffix (e.g. 'kroc prog.occ' compiles the source file prog.occ into the excutable file prog). You can also get it to link with other files and/or libraries e.g.

    kroc main.occ math.c stuff.o -lfoo -o prog

Running the examples

There are several example programs with this distribution but it is easiest to start with the classic "Hello World" hello.occ program in examples/hello/hello.occ.

Firstly go there ('cd examples/hello') and have a look at the source:

    PROC hello (CHAN OF BYTE key, screen, error)
      VAL []BYTE message IS "Hello, world*c*n":
      SEQ i = 0 FOR SIZE message
        screen! message[i]

It is quite simple so compile it via typing 'make' or 'kroc hello.occ' (the former does that):

    unix% make
    kroc hello.occ
    Warning-oc-hello.occ(1)- Parameter error is not used
    Warning-oc-hello.occ(1)- Parameter key is not used
    KROC Version 0.9beta for sparc-sun-sunos4.1.3_U1

(Ignore the warning messages)
and then run the executable:

    unix% ./hello 
    Hello, world

and that's it!

Now you can try the other examples to see what they do. From the release directory if you type make examples, all the example programs will be built.

KROC Interface

As described above, the current interface to the outside world for KROC is three CHANs OF BYTEs corresponding to the C/Unix world's stdin, stdout, and stderr:

    PROC main (CHAN OF BYTE key, screen, error)
      ...  main body


File access is provided via the standard SP PROTOCOL from the hostio.lib or hostsp.lib libraries. The differences between the two and examples of use are given in the short document: examples/inmos-libs/inmos-libs.doc.

Separate compilation

Each time you compile an occam program now, a .tco file is also generated. If you #USE that file in another occam program, the compiler will pull out the PROC definitions and you can use them. If the subsequent program is then linked with the .o file that was built in the first step, you have separate compilation. This has not been extensively tested and there will be better support for it (and libraries) in the next release.
If you have two modules a.occ and b.occ and which to call the functions in a.occ from b.occ

  1. Compile a.occ: kroc -c a.occ giving a.o and a.tco
  2. In b.occ add a #USE "a.tco" line before the place where you use the PROCs in a.occ
  3. Compile b.occ and link with a.o: kroc b.occ a.o which will create an executable file 'b'. (Add -o exe to change this)

See the short example in examples/sc for the above. Just type 'make'.

The examples are also built using separately-compiled libraries which shows this too.

kmakef - Makefile builder

This release has the first version of the kmakef program which understands the kroc system and tries to build valid makefiles that describe the dependencies between the files along with rules to construct them. There is no documentation for it at this time but it should be used like:

      unix% kmakef program

to build a file program.kmf which will compile everything needed to make the executable program

PLEASE NOTE: This program is written in perl5. If kmakef can't find the correct perl interpreter, please edit the first few lines of bin/kmakef to point to where your version of perl 5 is installed on your system.

Problems, Suggestions and Bugs

Please contact us at the address below with the details. Please give a full description of your problem, including your source files that demonstrate the problem if necessary. Please also indicate the release of the system you are using (in the file VERSION in the distribution).

Occam For All Team
31st March 1997