RIGAL/examp1/sourguid.txt

--- SOURGUID.TXT ---
By Wadim Engelson , IMCS LU Riga, Latvia     16-oct-1990
Revised  1-dec-1990 (for version 1.4)
         8-apr-1991: (for version 1.50-no changes)
         15-sep-1991: (for version 2.04, TP 5.5 changed to 
6.0)

                Rigal source guide
                ==================

     Rigal is implemented as some  tasks  (.EXE-files),  in
two versions : RIG.EXE which is without the compiler option
(more simple ) , and RIG1.EXE which calls  several  another
tasks including interpreter, compiler and so on.
     Some of parts  were  compiled  Pascal  programs,  some
(ANRIG,GENRIG, RIG_LINT, RIG_CRF, RIG_PNT  )  are  compiled
RIGAL programs.
     Pascal source files include all necessary  subprograms
( UNITS in Turbo Pascal terms ) and main programs  (  their
names are equal to task names).  Units  are  used  both  to
compile tasks and to form additional part, which  is  added
to standard Turbo PascaL library TURBO.TPL, which  is  used
as Rigal runtime library.
     Turbo Pascal 6.0 (TPC.EXE) is  used  both  to  compile
pascal code and in Rigal Compiler (as last  phase  of  it).
Pascal code compilation may run as batch  (  batch  command
file RECOMP.BAT ) where  correct  directory  name  must  be
given as command line parameter). This directory  must  yet
contain  TPC.EXE   ,   any   version   of   TURBO.TPL   and
TPUMOVER.EXE. At the beginning all old  Units  are  removed
from TURBO.TPL, then normal compilation of  some  tasks  is
executed, then new Unit codes are added to TURBO.TPL.
     Rigal-written programs may be compiled by  F8  key  of
the integrated environment (or simply by running RIGCOMP.BAT)
and their  names  are  equal  to
tasks (ANRIG, GENRIG are analysis and  generation  part  of
the compiler itself, CRF (=RIG_CRF) is Cross-referencer.

             ----- Porting considerations -----

      Before porting to another  Pascal  version  -  simple
translation in MS-DOS Turbo Pascal 6.0 is recommended  (5.0
also may be used ).
     Two main problems are (1) using built-in Turbo  Pascal
procedures and  functions  and  (2)  using  Unit-dependency
schema.
     Here are recommended sequence of works which are  need
for porting of Rigal Environment from  MS-DOS/Turbo  Pascal
version to Unix/Pascal or any another.
     At first we recommend to compile DEFINE.PAS  unit.  It
describes types A and AA (the same) which must be  4  bytes
length positive number, it is used everywhere as address of
structured  objects  (atoms,  list  and  tree  descriptors)
(S-space),and text pieces (symbolic constants) ( A-space).
     Below described fields of records must be of the  same
sub-division to bytes ( in  Turbo  Pascal  no  division  to
bits). Length of records in memory must be the same.
     DEFPAGE.PAS describes paging manager and  loading  and
saving rigal objects. In preliminary  porting  loading  and
saving  rigal  objects  in  files  is  not   implementable,
butanother  procedures  will  allocate  rigal  objects   in
ordinary heap memory, using A as POINTER type.
     In more advanced level of porting we need  take  under
control such considerations about current version of paging
manager : Low-level  operations  semantics  must  be  under
control; Virtual disk name comes as parameter from  command
line , and we are sure that if heap memory is big enough  (
8 MBytes ?) - then no paging and no special disk  name  are
needed. File names ( they are now defined  as  constants  )
may be of ANY nature , because they normally  will  not  be
opened, and all paging will execute only  in  heap  memory.
BlockRead & BlockWrite & Seek procedure  semantic  must  be
carefully tested; no special disk-error or memory-error  or
disk-overflow messages are produced now. It is not so  easy
to separate paging from SAVE/LOAD of Rigal objects and only
Andris Zarins (third author) knows the  details.  Parameter
passing by reference is essential now.
     Unit LEYER.PAS describes lexical  analyzer  of  Rigal.
STRING type is used to form every one  token.  STRING  zero
byte is not mentioned in programs. GotoXY and Write are not
essential here. Pascal lexical analyzer (if it is  need  at
all) may be changed later - as you want.
     Program RIGCHECK (version 1.4) is the simplest one:
it  takes  a command line  parameter - file  which  contains
 a .RIG program and
executes syntax checking of  Rigal  program.  Program  name
(a.rig) is given , lexical analyzer  and
(then) recursive descending analyze executes; either  error
message is showed in the screen (might be redirected by
'>' DOS symbol),   either   program   special   code
(need    for interpretation ) is saved in A.RSC file.
     W*.PAS are parts  of  our  domestic  text  editor.  No
toolboxes were used, only GotoXY, ClrScr , ClrEol and Write
procedures were used for output to the screen.  Colors  are
yet fixed as declared constants. Double direction chain  of
records in heap represents  global  buffer  and  additional
one.  We  save  names  of  8  last  used  files.  Procedure
FindFirst and similar one are used to show directory. Error
messages returned  from  checker,  and  editor  shows  this
message and goes to according line and column  where  error
occurred. You can of course to use your own text editor  if
you can form output and input parameters of  procedure  WED
or similar one, menus , and to put error message  into  the
appropriate place.( In any case it is much better to  use
 ready text editor like
MS-DOS  MULTIEDIT (with Muliedit's "Big compile" option)).

     INT.EXE is interpreter  of  RSC  files.  There  is  no
porting  problems;  circular  calling  of   procedures   is
essential. No problems in text output or PRINT.
     First version (really working) RIG.EXE  prototype  now
may be compiled. In preliminary version paging  we  do  not
use - it simplifies work  (without  real  SAVE  and  LOAD).
After  this  moment  really  working  SAVE  and  LOAD   are
absolutely necessary.
     Now,   COMPILER.   Current   Rigal->Pascal    compiler
generates some pascal files from one rigal program.  Pascal
code patterns and unit dependency is common for all  cases,
only count of files is  changeable.  You  must  design  new
dependency schema (what  and  how  to  generate  in  pascal
files). After fixing all  changes  must  be  inserted  into
programs ATN.RIG and ATI3.RIG of compiler generation  part.
Compiler analysis part will  not  be  changed.  New  pascal
codes must allow  circular calling of many procedures  each
other and all they call  the  Runtime  Library.  Of  course
dependency schema will  be  simple  if  it  is  allowed  to
compile more than 2 MBytes of pascal  source  code  as  one
unit.
     Runtime library must be formed from  the  same  pascal
sources, which were used in interpreter or checker.
     Now run both parts of  compiler  may  be  run  through
themselves (using interpreter first time, and then - bootstrapping).
 Such a  way  you
get  ready  ANRIG.EXE  and  GENRIG.EXE.  Understanding   of
command line parameters passing is essential. Task  calling
we recommend to implement through  additional  batch  file,
which  is  generated  by  checker.  It   requires   correct
references  to  files  and  directories  of  user  and   of
implementation and of PASCAL compiler.
     Now all tasks are linked to one or to  set  of  tasks.
RIG1 must be the main task.
     My experience shows that porting  from  RSX11M  Oregon
Pascal to VAX/VMS Pascal and then to  MS-DOS  Turbo  Pascal
takes one man * month each. It not includes paging manager,
studying pascal differenced and operating systems.