.in 8
.rm 72
.pl 60
.ce
README FIRST


FILE 1 -- THIS INTRODUCTION

This is the long-awaited Software Tools "Toys" tape where we bring you
some of the major pieces of software that have been written since the
first "basic" tape.
Hopefully, this will give everyone something to do while we continue to
smash out standards which will allow us to generate a new basic tape
in the future.

This tape contains sources for format, yacc, lex, ar, RatFor and LISP.
Format is the Software Tools formatter with tab stops added by the Real
Time  Systems  Group  at  Lawrence  Berkeley  Laboratory.    This
version  of  format  will  be necessary to read the documentation
provided for yacc and lex.  Yacc and Lex are  Unix-like  language
development  tools  developed  by RTSG.
.sp
Ar is an improved version of the Software Tools archiver which has been
taught to handle various flavors of archives including headers with
character counts, headers and trailers, and headers and trailers with
characters counts.  It was contributed by Debbie Scherrer of Carousel
Microtools.
.sp
The RatFor on the tape is the "almost" standard version which narrowly
escaped being blessed as our first standard language.
It was contributed by Joe Sventek of the Computer Science and Mathematics
(CSAM) group at LBL.
All of the code on this tape should be compiled using this RatFor.

The LISP system on the tape is a new development, and was contributed by
Charlie Dolan and Dave Martin of Hughes Aircraft.

Also included on the tape are test programs for
yacc  and  lex.  There  is  also  an archive containing 5 support
libraries which are needed by the yacc and lex code and the  test
programs.   The   following  sections  describe  the  7  archives
pertaining to format, yacc, lex, and ar.


FILE 2 -- RATDEF ARCHIVE

The Ratdef archive contains  RTSG's  standard  RatFor  definition
file.  In  particular,  you  will  need  the  definitions for P_,
prints, printf, and fprintf in order to use the  formatted  print
routines (see the prilb archive in the Support Library archive).


FILE 3 -- FORMAT ARCHIVE

The  Format  archive  consists  of  a  documentation  archive, an
include file archive, and a source code archive.  This  formatter
is  the  same as the formatter distributed on the last version of
the basic tape except that tab stops have been added  (.ta).  The
documentation  for  Yacc  and  Lex have tab stops in them, so use
this formatter to format the documentation.


FILE 4 -- YACC ARCHIVE

The yacc program translates a yacc  compiler  specification  into
an  executable  compiler.  It actually spawns to 3 main programs;
yaclr, lrgen, and rc (RatFor-compiler).  Yaclr  extracts  the  user
supplied  RatFor code and translates the yacc grammar specification
into an  lrgen grammar specification. Lrgen translates the  lrgen
grammar  spec into LALR parse tables. The user-supplied RatFor code
and the parse  tables  are  then  compiled   and  linked  with  a
support   library  called  yyplb.  This  produces  an  executable
compiler. The yacc program is really just provided on  this  tape
as  an  example  of  how to create a program which will do all of
the  individual  tasks  required  to  compile  a  yacc   compiler
specification.  To  be  able  to  use  such a program you must be
capable of doing spawns and you will probably have to modifiy  it
to  correspond  to  your RatFor compiler conventions. Otherwise you
can use yaclr and lrgen directly. The following 3 sets  of  shell
commands  create  an  executable  compiler  (assuming  your  RatFor
compiler is called rc):

.in +8
.nf
.ti -4
1.  % yacc src/complr library

.ti -4
2.  % yaclr -s src/complr.r src/complr | lrgen >> src/complr.r
% rc src/complr.r yyplb library

.ti -4
3.  % yaclr -s src/complr.r src/complr  > lrgram
% lrgen < lrgram >> src/complr.r
% rc src/complr.r yyplb library
.in -8
.fi

The main yacc archive consists of a yacc-tool  archive,  a  yaclr
archive,  a  lrgen  archive,a lrglb archive, and a yyplb archive.
Lrglb is a set of support routines for lrgen,  i.e.  lrgen  needs
to  link  with  lrglb  in  order  to compile. Yyplb is a set of 5
routines which all translated yacc programs must link with.  Each
of  these  5  archives  consist  of  a  documentation archive, an
include file archive, and a RatFor source code archive.
.sp
[Editor's note:  I tried building yacc and found routine "lastln"
missing so I scrounged up RTSG's DEC version and stuck it in the
archive.]


FILE 5 -- LEX ARCHIVE

The main lex archive consists of a yacc lex archive,  a  skeleton
lex  program  archive,  a  RatFor lex archive, and a lexlb archive.
Lex is written in yacc. This requires  that  you  implement  yacc
before  implementing  lex.  However,  the  3rd  archive  in  this
section does include the translated lex program (i.e. the  output
from  yaclr  and  lrgen)  in  RatFor.  So if you have problems with
yacc, you can just compile the RatFor lex  program.  You  can  also
use  the RatFor lex program to test your yacc program (i.e. compare
the output from using yaclr and lrgen on the yacc lex code).

The 2nd archive is a skeleton program which lex  fills  out  when
it  is  creating  a scanner.  Lex looks for the skeleton program,
lexskel, in  a  lib  directory  using  searchpaths.   RTSG  added
searchpaths  to  the  Software  Tools to implement a kind of UNIX
Path variable. You will need to  change  the  string  declaration
for  the  skeleton  file name from "~/.%lib/lexskel" to something
like "/usr/lib/lexskel". This declaration  is  on  line  1807  of
src/lex. This is all you should need to change.
.sp
[Editor's note:  Again, I found some routines missing from my system
which may not have been on the basic tape.  They are in the "yacc.all"
archive as file "missing".]


FILE 6 -- SUPPORT LIBRARIES ARCHIVE

The  support  libraries  archive  contains documentation, include
files, and RatFor sources for 6 support libraries. These  libraries
are  needed  for  yacc,  lex, and the test programs. They are NOT
needed for ar or format. The 6 support libraries are:

.nf
.in +4
bslb - portable bit string routines
tbllb - portable (rtsg-version) symbol table routines
evalb - portable arithmetic expression evaluation routines
quelb - portable queue manipulation routines
memlb - portable dynamic memory routines
vmemlb - VAX-dependent version of memlb (same interface)
prilb - portable formatted print routines (fprintf,printf,prints)
.in -4
.fi


FILE 7 -- TUTORIALS ARCHIVE

This archive contains a tutorial  for  lex  and  a  tutorial  for
yacc.  Yacc  and  lex  were  developed seperately. Unfortunately,
they don't fit together exactly like UNIX yacc and  lex.  One  of
the  things  on  our  "wish  list"  is  to  improve the interface
between yacc and lex. Yacc expects a scanner called  yylex,  like
UNIX.  Unfortunately,  Lex  produces  a  scanner  routine  called
lexscan. So basically you need to supply a routine  called  yylex
which calls the lex scanner, lexscan. 


FILE 8 -- TEST ARCHIVE

There  are  2  test  programs  for testing yacc and lex. The yacc
test program is  a  desk  calculator  tool,  dc.  It  requires  2
support  libraries  evalb  and  tbllb.   Evalb  is  an expression
evaluation library and tbllb is the  symbol  table  library.  The
generated  dc  compiler  may  be  too  large for your computer to
handle. You can make the dc tool smaller by deleting some of  the
productions.  The  lex  test  program  is a "ratfix" tool, i.e. a
tool which converts old-style  RatFor  programs  to  the  new  RatFor
language.  It basically translates all old definitions like LETD,
NEWLINE, etc. to the new RatFor constants, 'd', '@n', etc. It  also
changes  all  single-quoted strings to double-quoted, and changes
all program  statements  to  DRIVER.  It  deletes  initr4,  endr4
statements  and inserts DRETURN statements. Again you can make it
smaller if necessary by deleting some of the  rules.   Each  test
program  archive  consists of a documentation archive, an include
file archive, a source archive, and a RatFor  source  archive.  The
RatFor  versions  will  allow  you  to  compare  your  lex and yacc
output.


FILE 9 -- AR ARCHIVE

This   archive   comes   from   Debbie   Scherrer   of   Carousel
Microsystems.  It  is  basically  a  fixed  up version of the old
archive. It handles character counts, headers, and trailers.  The
archive  consists  of  a  documentation  archive, an include file
archive, and a RatFor source archive.


FILE 10 -- RATFOR ARCHIVE

This is Joe Sventek's latest do-it-all something-for-everyone RatFor
which incorporates all the bells and whistles the standards group
insisted we can't live without.  Several different preprocessor
configurations can be generated, especially in the area of string
processing.  A second pass is now available for reordering statements
according to ANSI-66 specifications for those whose FORTRAN compilers
require it.  Again, this is the RatFor you should use when building
the other tools on this tape.


FILE 11 -- LISP ARCHIVE

And they said it couldn't be done!  A reasonably well-endowed LISP
interpreter written (almost) entirely in RatFor.  Originally developed
for an HP-1000 minicomputer (of all things), this LISP has been residing
of late in the memory-rich VAX/VMS environment.  The basic overlaying
strategy from the HP has been retained, however, so porting it back down
to a smaller machine shouldn't be too terrible.  If you're not running
on a VAX, you'll need to write equivalents for the recursion-handling
routines in "rcrsv.mar".
Since LISP requires quite a few primitives and library routines you may
not have on your local system, we have included our entire runtime
library as archive "rlib.ar" in the LISP archive.
Note:  Please don't become too attached to this particular dialect of LISP.
When COMMON LISP becomes available, we plan to rework this one to be as
compatible as possible.
.sp 2
Have fun!  Send us YOUR toys for the next tape...
