
            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 [2]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 )

      PATH=/usr/local/kroc/bin:$PATH
        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]
Options:
  -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
    unix%

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

    unix% ./hello
    Hello, world
    unix%

   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
    :

KROC and SP PROTOCOL

   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.
   e.g.
   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
    ofa-bugs@ukc.ac.uk
    31st March 1997
