========================================================
(C)1993 Institute for New Generation Computer Technology
(Read COPYRIGHT for detailed information.)
========================================================

How to INSTALL KL1 to C compiler
================================
July 9, 1993
Takashi Chikayama (ICOT)

Copyright 1993 Institute for New Generation Computer Technology
(Read COPYRIGHT for detailed information)

Installation of the current version of KLIC is rather clumsy.
Thank you in advance for your patience!

[1] Compilation Scheme

Understanding how KL1 programs are compiled and executed would help
understanding how to install it.

The system consists of the following two modules.

  - KLIC compiler

  - KLIC runtime system

KL1 programs are compiled using the KLIC compiler into C programs.  It
also generates files "atom.h" and "funct.h", defining atom and functor
identifiers, and "atom.c" and "funct.c", for correspondences of atoms
to their names and/or functor to their name/arity combinations.

The object C program is then compiled by a C compiler, with headers
provided by the KLIC runtime system, "atom.h" and "funct.h", linked
with the runtime system.

[2] Installing the Compiler

The current version of the compiler is written in Prolog.  SICStus
Prolog version 2.1 has been used for its development and testing, but
the compiler is meant to run also on Edinburgh Prolog compatibles,
such as Quintus Prolog.

To make a compiler executable with SICStus Prolog, cd to the directory
"compiler" and simply run "make".  It will compile and load the
compiler, and then saves an executable file "kl1cmp" in the same
directory.  Install this "kl1cmp" to wherever convenient.  With the
default setting, this should be left as is in this directory.

The Makefile assumes that SICStus Prolog is accessible by the command
"sicstus".  If it is not, or you plan to use other Prolog systems,
edit the Makefile.

[3] Installing the Runtime System

To build the runtime system library "libklic.a", cd to the directory
"runtime", edit Makefile and run "make".  It will also make another
library "libklict.a" for execution with tracing.

The Makefile several switches at its top.  The distributed file
contains switches suited for use with gcc.  Please change these lines
according to your environment.

After the library archive "libklic.a" is built, install it to wherever
convenient in your environment.  With the default setting, this should
be left as is in this directory.

[4] Installing the KLIC Shell Script

The top-level shell script for driving the KLIC compiler and C
compiler can be found as the file "klic" in the root directory of the
destribution.  Edit the file so that the definition of KLICDIR will be
the directory you installed the system.  Then install to some
convenience place (such as /usr/local/bin).

[5] Testing the Installation

Sample programs can be found in the "samples" directory.  Described
here is to run one of them, naive reverse program.

Step 1: Copy "nrev.kl1" to some convenient directory.

Step 2: "nrev.kl1" to nrev.

	Run "klic" to compile "nrev.kl1" into "nrev.c" to "nrev.o"
	then to executable "nrev".

	% klic nrev
	/usr/local/src/klic/klic-0.0/compiler/kl1cmp nrev
	Compiling nrev...

	make -f /usr/local/src/klic/klic-0.0/KLICmakefile KLICDIR=/usr/local/src/klic/klic-0.0 nrev.o nrev
	gcc -pipe -DGCC -DCARCDR -DCSUSPS -O2 -fomit-frame-pointer    -I. -Iklic -I/usr/local/src/klic/klic-0.0/include -c nrev.c
	make -f /usr/local/src/klic/klic-0.0/KLICmakefile KLICDIR=/usr/local/src/klic/klic-0.0 atom.o funct.o
	gcc -pipe -DGCC -DCARCDR -DCSUSPS -O2 -fomit-frame-pointer    -I. -Iklic -I/usr/local/src/klic/klic-0.0/include -c atom.c
	gcc -pipe -DGCC -DCARCDR -DCSUSPS -O2 -fomit-frame-pointer    -I. -Iklic -I/usr/local/src/klic/klic-0.0/include -c funct.c
	gcc -pipe -L/usr/local/src/klic/klic-0.0/runtime -o nrev nrev.o atom.o funct.o -lklic

Step 3: Run the Executable

	Run "nrev".  The result should be as follows.

% ./nrev
[30,29,28,27,26,25,24,23,22,21,20,19,18,17,16,15,14,13,12,11,10,9,8,7,6,5,4,3,2,1]
[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30]

[6] Tracer

When you want to trace execution of program "XXX" in source file in
"XXX.kl1", you have to make a traced version of executable.  It can be
done by simply typing in:

% klic XXX-t

Try, for example, the following.

% klic nrev-t
make -f /usr/local/src/klic/klic-0.0/KLICmakefile KLICDIR=/usr/local/src/klic/klic-0.0 atom.o funct.o
`atom.o' is up to date.
`funct.o' is up to date.
gcc -pipe -L/usr/local/src/klic/klic-0.0/runtime -o nrev-t nrev.o atom.o funct.o -lklict

This time, only linking is done, as the traced and normal executables
differ only with the runtime libraries.  This mechanism of making
"XXX-t" from "XXX.kl1" may not work with old "make" programs.

Unfortunately, no manuals for the tracer is currently available.
Input "?" + carriage return to display tracer commands, as follow.

% ./nrev-t
CALL: top:top? ?
	*** Commands available at CALL ports ***
    <cr>: continue;   c: continue;      s: skip;          l: leap;
    E: enable port;   D: disable port;  L: leash port;    U: unleash port;
    S <pred>: spy;    N <pred>: nospy;  t <pred>: trace;  n <pred>: notrace;
    pd: print depth;  pl: print length; pv: toggle verbose print;
    =: debug status   lm: list modules; lp: list predicates;
    a: abort execution
CALL: top:top? 

Send bug reports and comments to:
	klic-bugs@icot.or.jp
