               Recursive Functions Algorithmic Language               
                                REFAL-M                               
                             User's Guide                             
                             version 2.00                             

Table of Contents
1. Introduction ...................................
2. Installation ...................................
3. Refal Compiler..................................
4. Refal Linker.....................................
5. Refal Tracer.....................................
6. Refal shell
7. Refal makefile generator

     Refal  programming  environment   consists   of   the   following 
components:
1) Refal Compiler  (rcomp)
2) Refal Linker    (rmod2c)
3) Refal Run-Time Kernel 
     ri.o  - "pure" kernel without tracing
     rit.o - kernel with interface to interactive tracing

4) Refal Standard Library of Built-in Functions 
     rlib.a  - very standard Refal functions 
     rlib2.a - extended standard Refal functions

5) Refal command-line  Tracer 
     trace   - interactive tracer
     trace.a - additional library for tracing

Software requirements:

- UNIX operating system (we have tested the system on Sun Solaris 2.5.1;
    HP/9000 HP-UX 712; PC LINUX 2.x);
- gcc compiler (we have tested the system under gcc 2.7.2 but we believe that
   any C compiler will do);
- gmake (we have tested the system using gmake 3.74);
- ar 

2. Installation

The system distribution consists of a single uuencoded
gzip'ed tar file  refal.2.0.tar.gz.uu.
Copy it into parent
directory of refal intallation and type:
uudecode refal.2.0.tar.gz.uu
gzip -cd refal.2.0.tar.gz | tar xvf -.
After that cd in refal directory.
Type `make install' for compile and install refal. 

3. Refal Compiler

NAME
     rcomp   - Refal Compiler

SYNOPSIS
     rcomp [options] filename

DESCRIPTION

Compiles a file containing Refal module(s) into byte-code.
Cirillic letters support in koi-8 encoding.

OPTIONS
     -l  generate source program listing
     -nopt  do not preform any optimizations
     -x  include the cross reference table into listing
     -m  generate symbolic representation of byte-code 
     -o  generate byte-code dump (for debugging)

FILES
filename.mod   - target file (is successful)
filename.lst   - source listing (if  -l option was present)
filename.rfc   - byte-code dump (if -o option was present)
filename.mac   - symbolic representation of byte-code (if -m option was present)
 
4. Refal Linker

NAME
     rmod2c  - Refal modules linker

SYNOPSIS
     rmod2c [ -o Name of output c-file] files

Refal compiler produces target .mod files  which  contains
byte-codes for module(s) in machine independent
representation. These codes have to be linked with other Refal
modules (compiled separately) and converted into c file.

Refal linker checks import/export  links  of the modules and
prepares the c-file. 

The input to Refal linker  is a  list of  modulenames,
separated by spaces. Extension ".mod" is assumed by default.
At least one module has to be specified. The target file will
have the same name  as  the first modulename in the command
line by default. It is possible to provide a different
filename for the target files in -o option.

FILES
filename.c  -  single  object  file  for  all  Refal  modules  (if 
import/export checks succeeded)

NOTE: The output .c file produced by rmod2c needs to be compiled 
with gcc compiler and linked with ri.o, rlib.a, rlib2.a.
When interactive tracing is required, the resulting .o file needs to be linked
with rit.o, rlib,a, rlib2.a and trace.a
All required files are located in bin directory of Refal installation.
See also Refal shell & Refal makefile generator section of this file.

5. Refal Tracer

NAME
     trace - command line  Refal Tracer

SYNOPSIS
     trace  executable_filename

DESCRIPTION

     Refal tracer  animates  the  execution  of  Refal  programs.  Any 
executable program produced by Refal system can be traced with  
re-linking with debug option. The name of the executable file has to be 
provided for the trace command.
     The tracer supports the following features:
- single step tracing;
- tracing within a range of steps;
- breakpoints on function calls in two modes:
     - tracing steps when a given function  is  called  (argument  and 
          result of a single step);
     - tracing function calls (argument and complete result,  possibly 
          after many steps);
- view contents of boxes;
- view user's screen;
- break key;

     The tracer is controlled by interactive commands. The following table 
lists allowed commands and their abbreviated names:

break [b] - set a breakpoint on function in mode 1 (argument
            and result of the step);
func  [f] - set a breakpoint on function in mode 2 (argument
            and result of the application);
range [r] - set range of steps for tracing; execution is stopped
	    at the  first step of range and at the last step of
	    the range; all  breakpoints  are only effective
	    within the range;  First  and  last  step  numbers
	    are prompted; when no first step number was entered
	    it is assumed to be  1 and when no  last  step
	    number  was  entered  it  is  assumed  to  be "infinity";
undo  [u] - Clear breakpoint from function;
clear [c] - Clear all functions ;     
view  [v] - View contents of a box ;  
next  [n] - apply function ;          
step  [s] - trace function ;          
run   [z] - run programm ;            
l - set list reporting to on/off;        
m - set memory cheking to on/off;        
p - print View Field ;        
q - quit ;        
h - print help ;           
     
     The program can be traced in either a  single  step  mode  or  in 
normal mode. When in normal mode the execution stops at the first step 
of the range; when a breakpoint occurs within the range; at the last 
step of the range or when the user do the break command. 
     When the execution is stopped the dialog mode is entered and  any 
commands can be used. To enter single step 
mode step should be pressed.
     In a single step mode the execution is stopped after  each  step. 
To resume the normal mode, run should be entered.
     The tracer starts  in  normal  mode  before  the  first  step  is 
executed.

FILES
     none


6. Refal shell
NAME  refal

SYNOPSYS 
      refal [-o exe-file] project-files
DESCRIPTION

  Refal complile and links project files to executable file. 
Project-files may have one of the following forms: 
 filename.ref : It will be compiled using rcomp ;
 filename : extension .ref is assumed;
 filename.mod: will be linked together with other .mod files into a 
           c-file by rmod2c;
 filename.c: will be compliled using gcc and linked into the executable
 filename.o,files.a: will be linked using gcc into executable file 
         (by default first name witout extension)

If errors occured in some step refal shell stops and prints errors.

Environment variable REFAL_HOME should be set to provide pathname of Refal 
installation. 

7. Refal makefile generator
NAME ref-gen-make
SYNOPSYS ref-gen-make [-o exe-file] [-m Makefile name] project-files
DESCRIPTION
  Generates makefile for refal project,
  Project see in Refal shell.
NOTE 
  Use for big project

