A compiler for Starlog: A pure temporal logic programming language.

Copyright 2001, Mark Utting (marku@cs.waikato.ac.nz)
This program is free software.  See the file COPYING for details.

Starlog is a pure, temporal, logic-programming language that is
good for writing reactive programs.  It uses a bottom-up style 
of execution, similar to expert systems.  For more information, see:

	http://www.cs.waikato.ac.nz/Research/starlog

This compiler does type, mode and determinism analysis, then
generates C or Java code.  One of the intended uses of this compiler 
is to generate embedded programs to control LEGO(TM) MINDSTORMS
robots (see the lego subdirectory).

How to use it
=============

If you have downloaded a binary version of this compiler for Linux,
you can just do this (in the tests subdirectory):
	../stc --print hamming.st
	javac hamming*.java
	java hamming      % You should see the hamming tuples.

Note: The --print flag means generate code to PRINT each tuple as it 
is produced.
Type '../stc' to see a brief help message.

If you write your own Starlog program, say tests/prog.st, then use the
same steps as above to compile and run it (with 'prog' replacing 'hamming').

Alternatively, if you are using the source code distribution, you must:

    1.  Install Hugs (from http://www.haskell.org/hugs/)

    2.  Execute the shell command (in the tests subdirectory):   

		runhugs ../Compile --print hamming.st

	This produces the files hammingHeader.java and hamming.java.
        (The --print flag means PRINT each tuple as it is produced.)

	Type 'runhugs Compile' to see a brief help message.

    3.  Compile the .java files.

    4.  Run the hamming executable (java hamming) and it will print 
        all the tuples.


Compiler Options
================
    The Java code generator also supports an experimental 'triggering' 
    evaluation technique.  Add the '-trigger' flag to try this.
    NOTE: the -trigger option does not necessarily generate tuples in
    time order, as you will see if you enable '-print'.


LEGO MINDSTORMS(TM) Output
==========================
See the README file in the lego subdirectory for instructions on how to
write Starlog programs that control the LEGO MINDSTORMS Robot (RCX).

Java Graphics
=============
See the README file in the javagraphics subdirectory for instructions 
on how to write real-time graphics animations using Starlog.


WARNINGS/BUGS
=============
Stratification:
Currently the compiler does not 'stratification' checking, to make
sure that rules are evaluated in the right order.  This means that
some programs will run incorrectly.  However, you can control the
stratification order manually, by ordering your predicates
ALPHABETICALLY in the desired execution order.  This is horrible,
and will be improved eventually.

Recursive Predicates:
The type inference is sometimes too weak on recursive
(including mutually recursive) predicates, where an argument is
passed through the recursion unchanged.  This results in errors
in the generated code saying "cannot generate code for type...".
A work-around for this is to add "X = X + 0" for each such integer 
variable, to tell the compiler that it is an integer.