




                                  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. 

        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. 

        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):
        
            1.  % yacc src/complr library
                
            2.  % yaclr -s src/complr.r src/complr | lrgen >> src/complr.r
                % rc src/complr.r yyplb library
                
            3.  % yaclr -s src/complr.r src/complr  > lrgram
                % lrgen < lrgram >> src/complr.r
                % rc src/complr.r yyplb library
        
        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. 

        [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. 

        [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:
        
            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)
        
        
        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. 


        Have fun!  Send us YOUR toys for the next tape... 























