reduce-historical/psl-1983/20-dist.lpt

Utah Symbolic Computation Group                        April 1982
Operating Note No. 62












                          Release Notes

                     DEC-20 V3.1 PSL System
                     DEC-20 V3.1 PSL System
                     DEC-20 V3.1 PSL System


            M. L. Griss, E. Benson and R. R. Kessler

                 Utah Symbolic Computation Group
                   Computer Science Department
                       University of Utah
                   Salt Lake City, Utah 84112
                         (801)-581-5017

                          8 March 1983




                            ABSTRACT
                            ABSTRACT
                            ABSTRACT


This note describes how to install the DEC-20 version of PSL.















Work  supported  in part by the National Science Foundation under
Grants MCS80-07034 and MCS81-21750,  and  by  development  grants
from  Boeing,  Patil  Systems,  Lucas  Film,  Wicat  and  Hewlett
Packard.
DEC-20 PSL Release                                         Page 2


1. INTRODUCTION
1. INTRODUCTION
1. INTRODUCTION

  The  attached  DUMPER  format  tape  contains most of the files
needed to use and maintain the DEC-20 PSL system. At UTAH we have
a <PSL> main directory, with a number  of  sub-directories,  each
containing  a  separate class of file, such as common interpreter
and compiler sources, DEC-20 sources, VAX sources, 68000 sources,
help files, etc.  This multi-directory structure  enables  us  to
manage  the  sources  for  all machines in a reasonable way. Most
people running PSL on the DEC-20 will not be interested in all of
the files, and certainly will not want to have them all on line.


  We  have  therefore  created  the  tape  to  enable  either   a
multi-directory  or  single  directory  model;  a  set of logical
device definitions will be TAKEn by the user (usually inserted in
the LOGIN.CMD file). Each separate distribution  directory  is  a
separate  SAVESET  on the attached dumper format tape, and so may
be individually restored into a common (<PSL> at Utah) directory,
or into appropriate sub-directories (<PSL.*> at Utah).



2. DISCLAIMER
2. DISCLAIMER
2. DISCLAIMER

  Please be aware that this is a PRELIMINARY release, and some of
the files and documentation are not quite complete; we  may  also
have  forgotten  some  files,  or sent incorrect versions. We are
releasing this preliminary version to you at this time to enhance
our collaborative research, and we expect the files  to  continue
to change quite rapidly as the system and distribution is tested.


  For these reasons please:


   a. Make a note of ANY problems, concerns, suggestions you
      have,  and  send  this  information  to  us  to aid in
      improving the system and this distribution mechanism.

   b. Please  do  not  REDISTRIBUTE  any  of  these   files,
      listings  or  machine readable form to anyone, and try
      to restrict access to a small group of users.
DEC-20 PSL Release                                         Page 3


3. CONTENTS OF THE TAPE
3. CONTENTS OF THE TAPE
3. CONTENTS OF THE TAPE

  Attached  to this note is a copy of the DUMPER run that created
the tape, indicating the savesets,  the  file  names,  and  sizes
needed to restore each saveset.


  The tape contains the following SAVESETS (current logical names
are included in [] after each saveset definition):


PSL             The  executable  files  (PSL.EXE  and RLISP.EXE),
                this  20-DIST.DOC  file,  .CMD  files  to  define
                appropriate logical names and a sample message to
                announce  PSL availability.  Also, included are a
                number of news files announcing new features  and
                changes,  some  files  associated  with the NMODE
                editor and a version of  psl  (PSLCOMP.EXE)  that
                will  compile the argument on the execution line.
                [psl:]


COMP            Common compiler, LAP, FASL sources. [pc:]


20COMP          DEC-20 specific compiler, LAP and  FASL  sources.
                [p20c:]


DOC             Miscellaneous   documentation   files,  including
                random notes on new features. [pd:]


DOCNMODE        NMODE documentation files. [pnd:]


EMODE           The EMODE screen editor sources and documentation
                to permit Driver  Customization.  *.b  files  for
                drivers  other than TELERAY are on LAP directory,
                have to load after loading EMODE itself. [pe:]


GLISP           An object oriented LISP. [pg:]


HELP            A set of *.HLP files, describing  major  modules.
                [ph:]


KERNEL          Machine Independent kernel sources. [pk:]
DEC-20 PSL Release                                         Page 4


P20             DecSystem 20 dependent kernel sources. [p20:]


LAP             Mostly  binary  FASL  (*.B) files, with some LISP
                files (*.LAP) for loading multiple  .B  files  of
                loadable (optional) modules. [pl:]


LPT             The   PSL   manual   in   printable   form   (has
                overprinting and  underlining),  as  SCRIBE  .LPT
                files. [plpt:]


NMODE           The  NMODE  text editor sources, which is a newer
                version  of  EMODE  developed  at   HP   Research
                Laboratories. [pn:]


NONKERNEL       The  sources  that are not in the kernel, but are
                kernel related.  [pnk:]


PT              A set of timing and test files. [pt:]


PT20            DecSystem 20 specific test files. [p20t:]


UTIL            Sources for most utilities, useful as examples of
                PSL and RLISP code, and for customization. [pu:]


WINDOWS         The window support functions used by NMODE. [pw:]
DEC-20 PSL Release                                         Page 5


4. INSTALLING PSL
4. INSTALLING PSL
4. INSTALLING PSL

  When  installing  the  PSL system, you have two options for the
directory structure.  You may utilize a single directory for  all
of   the   file,  or  you  may  create  a  directory  tree  using
subdirectories.    The  Utah  group  utilizes  a  directory  tree
structure  and recommends its use when installing a "full" system
(that  includes  all  of  the  sources  and  the  capability   of
rebuilding  any  part of the system).  However, if only a minimal
system  is  desired,  it  can  be  accomplished  using  a  single
directory.


4.1. Retrieve Control Files
4.1. Retrieve Control Files
4.1. Retrieve Control Files

  Whether   building   a  single  directory  system  or  multiple
directory system, logical name definition files and file  restore
control  files  must  be first retrieved.  Therefore, first mount
the dumper tape, at 1600 BPI (verify that there is no write  ring
in  the  tape).   Then, define X: as the appropriate tape device,
MTAn:, or use MOUNT if running a labeled tape system:  


@DEFINE X: MTAn:             or    @MOUNT TAPE X:
@ASSIGN X:


  Restore from the first saveset (PSL) the .cmd and .ctl files


   @DUMPER
   *tape X:
   *density 1600
   *files
   *account system-default
   *restore <*>*.c* *.*
   *rewind
   *exit


These files will be restored to  your  connected  directory,  and
should be copied to your main PSL directory after their creation.


4.2. Create a single subdirectory
4.2. Create a single subdirectory
4.2. Create a single subdirectory

  Create  a directory, call it <name> and define a logical device
PSL:  (a size of about 2600 should be sufficient).


  Any <name> will do, since the logical device name PSL: will  be
used.
DEC-20 PSL Release                                         Page 6


   @DEF PSL: <name>


  Copy the minimal-* restored files to PSL


   @COPY minimal-*.* PSL:*.*


  Now  edit the file PSL:minimal-logical-names.cmd to reflect the
your choice of <name>.


  Also  put   @TAKE   <name>minimal-logical-names.cmd   in   your
LOGIN.CMD.


  Finally,  restore  the  minimal  system  by  DOing the minimal-
restore.ctl file:


   @DO MINIMAL-RESTORE
   @DEASSIGN X:          or             @DISMOUNT  X:
DEC-20 PSL Release                                         Page 7


4.3. A MULTIPLE SUB-DIRECTORY SYSTEM
4.3. A MULTIPLE SUB-DIRECTORY SYSTEM
4.3. A MULTIPLE SUB-DIRECTORY SYSTEM

  If  you  plan  to do much source modification, or a significant
number of rebuilds, or  maintain  a  compatible  multiple-machine
version  of  PSL,  or  attempt  retargeting  of  PSL, a multiple-
directory structure such as that at UTAH should be built.


  The file FULL-LOGICAL-NAMES.CMD, retrieved above should be used
as a guide to building the sub-directories. We use  at  least  16
sub-directories  for  the  Common  Sources  and  DEC-20  specific
sources, and have at least an extra two  for  each  new  machine.
Consult  the  20-DIST.LOG  file  supplied  with the PSL tape as a
guide for the amount of space required  for  each  sub-directory.
The  current set of directories for DEC-20 PSL, the logical names
that we use,  and  rough  space  estimate  follows.    Build  the
sub-directories with a somewhat larger working space allocation.


  Now  edit  the  file  PSL:full-logical-names.cmd to reflect the
your choice of <name>.


  Also put @TAKE <name>full-logical-names.cmd in your LOGIN.CMD.


4.4. Build Sub-Directories
4.4. Build Sub-Directories
4.4. Build Sub-Directories

  Then use the system command, BUILD, to build each sub-directory
with the name Pxxx:,  as  follows.  Assistance  from  the  system
manager   may   be   required   to   permit   the   creation   of
sub-directories, and  the  appropriate  choice  of  sub-directory
parameters:


    @BUILD Pxxx:
    @@PERM nnnn           ! choose appropriate size
    @@WORK wwww           ! nnnn+extra
    @@FILES-ONLY          ! Can't login
    @@GEN 2               ! Retain 1 previous version
    @@PROTECTION 777700   ! Give group access
    @@DEFAULT    777700
    @                      ! that are permitted access


  To  make  this  process easier, we have created a control file:
CREATE-DIRECTORIES.CTL that will build all of the  subdirectories
with  sizes  such  that  restoration  of  the files will succeed.
Therefore, after editing the full-logical-names.cmd file above to
reflect the correct logical names, simply DO the CTL  file  (some
systems  use MIC instead of DO, so that may be substituted in the
following examples) :
DEC-20 PSL Release                                         Page 8


    @DO CREATE-DIRECTORIES.CTL


  This will create directories with the following sizes (note the
recommended names):


define psl: <psl>               ! Executable files and misc.
                                ! -- About 6300 for all psl
                                ! -- 1000 for it alone
define pc: <psl.comp>           ! Compiler sources
                                ! -- 125 pages
define p20c: <psl.20-comp>      ! 20 Specific Compiler sources
                                ! -- 75 pages
define pd: <psl.doc>            ! Documentation files
                                ! -- 275 pages
define pnd: <psl.doc-nmode>     ! NMODE documentation files
                                ! -- 150 pages
define pe: <psl.emode>          ! EMODE support and drivers
                                ! -- 225 pages
define pg: <psl.glisp>          ! GLISP sources
                                ! -- 425 pages
define ph: <psl.help>           ! Help files
                                ! -- 125 pages
define pk: <psl.kernel>         ! Kernel Source files
                                ! -- 225 pages
define p20k: <psl.20-kernel>    ! 20 Specific Kernel Sources
                                ! -- 500 pages
define pl: <psl.lap>            ! LAP files
                                ! -- 700 pages
define plpt: <psl.lpt>          ! Printer version of Docs
                                ! -- 450 pages
define pn: <psl.nmode>          ! NMODE editor files
                                ! -- 375 pages
define pnk: <psl.nonkernel>     ! Nonkernel Sources
                                ! -- 5 pages
define pt: <psl.tests>          ! Test files
                                ! -- 200 pages
define p20t: <psl.20-tests>     ! 20 Specific Test files
                                ! -- 600 pages
define pu: <psl.util>           ! Utility program sources
                                ! -- 600 pages
define p20u: <psl.20-util>      ! 20 Specific Utility files
                                ! -- 75 pages
define pw: <psl.windows>        ! NMODE Window files
                                ! -- 75 pages


  Finally,  restore the full system by DOing the full-restore.ctl
file:
DEC-20 PSL Release                                         Page 9


   @DO FULL-RESTORE
   @DEASSIGN X:          or             @DISMOUNT  X:


4.5. Announce the System
4.5. Announce the System
4.5. Announce the System

  Send  out  a Message to all those interested in using PSL.  The
file BBOARD.MSG is a suggested start.


  Edit  as  you  see  fit,  but  please  REMIND  people  not   to
re-distribute the PSL system and sources.


  You may also want to set the directory protection to 775200 and
limit  access  only  to those that you feel should have access at
this time.


4.6. Summary of Restoration Process
4.6. Summary of Restoration Process
4.6. Summary of Restoration Process

  In summary, first retrieve the cmd and ctl files from the first
saveset on the DUMPER tape.  Then choose  a  single  or  multiple
directory  system  and  edit the appropriate logical name file to
reflect the directory name(s).  If creating a multiple  directory
system  use the create-directories.ctl control file to build each
directory.  Then run the appropriate file retrieval control file.
Finally, announce the system to any interested users.



5. REBUILDING LOADABLE MODULES
5. REBUILDING LOADABLE MODULES
5. REBUILDING LOADABLE MODULES

  Most of the utilities, and many of the more experimental  parts
of  the system are kept as binary FASL files (with extensions .b)
on the PL:  directory.  EMODE and NMODE are  currently  the  only
major  sub-systems that have there own set of sub-directories. In
some cases (usually large sub-systems, or sub-systems that  share
modules)  there  are  a  number of .B files, and a .LAP file that
loads each .B file in turn. The PSL LOAD function will look first
for a .B file, then a .LAP file first on the user directory, then
on PL: (both this "search" path and the order of  extensions  can
be changed).


  In  order  to  ease the task of rebuilding and modifying the .B
files, we have a small utility, BUILD.  To use BUILD for a module
you call xxxx, prepare a file called xxxx.BUILD, which has  RLISP
syntax  commands  for  loading the appropriate source files.  The
file can also have various  CompileTime  options,  including  the
loading  of  various  .B  files to set up the correct compilation
environment.
DEC-20 PSL Release                                        Page 10


  Then  run PSL:RLISP, LOAD BUILD; and finally enter BUILD 'xxxx;
this will do a FASLOUT to "PL:xxxx", input the  xxxx.BUILD  file,
and finally close the FASL file.


  The  target  file  "PL:xxxx"  is constructed using the variable
"BuildFileFormat!*", initialized in the file PU:Build.Red .


  For example, consider the contents of PU:Gsort.Build:


    CompileTime load Syslisp;
    in "gsort.red"$


  Note that the SYSLISP module is required,  since  some  of  the
fast sorting functions in GSORT are written in SYSLISP mode.


  GSORT is then rebuilt by the sequence:


    PSL:RLISP
    LOAD BUILD;
    BUILD 'GSORT;
    QUIT;


  This  is  such  a  common  sequence  that  a MIC file (MIC is a
parameterized DO facility) PU:BUILD.MIC is provided, and is  used
by passing the module name to MIC, after connecting to PU:  


    @mic BUILD GSORT


  is all that is required.



6. REBUILDING THE INTERPRETER
6. REBUILDING THE INTERPRETER
6. REBUILDING THE INTERPRETER

  A running `rlisp' is required to rebuild the basic interpreter,
since  the  entire  system  is  written  in  itself.   The kernel
modules, rather than being compiled to FASL files,  are  compiled
                  _____                                     ____
to assembly code (MACRO) and linked using the system loader LINK.
                  ____ _____ _____ ___
The  command file P20C:DEC20-cross.CTL is executed to produce the
                _ _____ _____
cross compiler, S:DEC20-cross (S: should be set to an appropriate
scratch directory).  The modules in the kernel are represented by
          ___   _____                            __ ______ __  __
the files P20:*.build.    There  is  a  program  PU:kernel.sl  or
__ ______ _
PL:kernel.b which generates command files for building the kernel
DEC-20 PSL Release                                        Page 11


                                       ___ __ ______ ___ __
when  parameterized  for  Tops-20  by  P20:20-kernel-gen.sl.  The
specific modules which are in the kernel are only listed in  this
                                   ______
file,  in the call to the function kernel.  This generates a file
____ ___          ____ _____
xxxx.CTL for each xxxx.build.


6.1. Complete Kernel Rebuild
6.1. Complete Kernel Rebuild
6.1. Complete Kernel Rebuild

  A complete rebuild is accomplished by the following  steps.  At
Utah  we  use  a <scratch> directory for some intermediate files.
Define S:   to  be  this  directory  or  some  other  appropriate
location  that  can  be  deleted  when done. Below we use @SUBMIT
xxxx.CTL to run batch jobs; on some systems, @DO xxxx.CTL can  be
used instead, or on others, @MIC xxxx.CTL may be used.


  Begin by defining S: as <scratch> or other scratch directory:


      @DEFINE S: <scratch>


  Now connect to <psl.20-comp> and rebuild NEW-DEC20-CROSS.EXE:


      @CONN P20C:


      @SUBMIT NEW-DEC20-CROSS.CTL


  Copy  the  <psl.comp>BARE-PSL.SYM to 20.SYM, and regenerate the
appropriate  .CTL  files.  This   saves   the   old   20.SYM   as
PREVIOUS-20.SYM:


      @CONN P20:


      @SUBMIT P20:FRESH-KERNEL.CTL


  Rebuild  each  module  (xxxx) in turn, using its xxxx.CTL. This
creates xxxx.MAC and Dxxxx.MAC files, and assembles each to  make
xxxx.REL  and  Dxxxx.REL.    The entire set is submitted with the
file ALL-KERNEL.CTL, which submits each file in turn.  (Note that
these must be done sequentially, not simultaneously.  If you have
more than one batch stream, make sure that these are run one at a
time):


       @SUBMIT ALL-KERNEL.CTL
DEC-20 PSL Release                                        Page 12


  Build  the  main  module, which converts the accumulated 20.SYM
into heap and symbol-table initialization:


      @SUBMIT P20:MAIN.CTL


  Finally LINK  the  xxxx.REL  and  Dxxxx.REL  files  to  produce
S:BARE-PSL.EXE:


      @SUBMIT P20:PSL-LINK.CTL


  Execute  and  save  as  PSL.EXE,  reading appropriate xxxx.INIT
files (note, each site usually customizes the PSL environment  to
suit their needs, therefore we recommend that you create your own
version of Make-psl.ctl to perform this task).


      @SUBMIT P20:MAKE-PSL.CTL


  Finally, run MAKE-RLISP.CTL as needed:


      @SUBMIT P20:MAKE-RLISP.CTL


  Rlisp.exe  and  Psl.exe  will  be saved on the <PSL> directory.
You now may want to delete any xxx.log files that where created.


        @DEL P20:*.LOG
        @DEL P20C:*.LOG


6.2. Partial or Incremental Kernel Rebuild
6.2. Partial or Incremental Kernel Rebuild
6.2. Partial or Incremental Kernel Rebuild

  Often, only a single kernel file needs to  be  changed,  and  a
complete  rebuild  is not needed. The PSL kernel building process
permits  a   (semi-)independent   rebuilding   of   modules,   by
maintaining  the  20.SYM  file to record Identifier Numbers, etc.
The 20.SYM file from the recent full-rebuild, and xxxx.INIT files
are required, as are the "xxxx.REL" and "Dxxxx.REL". The  partial
rebuild  will replace the "mmmm.REL", "Dmmmm.REL" and "mmmm.INIT"
files,  modify  "20.SYM",  and  then  rebuild  the  MAIN  module.
Assuming  that  a  recent  full  rebuild has been done, a partial
rebuild of module "mmmm", is accomplished by the following steps.


  As above, S: is required for "Scratch" space.
DEC-20 PSL Release                                        Page 13


  Define S: as <scratch> or other scratch directory:


      @DEFINE S: <scratch> 


  Rebuild DEC20-CROSS.EXE, if needed:


      @SUBMIT P20C:DEC20-CROSS.CTL


  Rebuild  the  module  (mmmm),  using its mmmm.CTL. This creates
mmmm.MAC and Dmmmm.MAC files, and assembled each to make mmmm.REL
and Dmmmm.REL.  See the file ALL-KERNEL.CTL for current modules.


      @SUBMIT P20:mmmm.CTL
        Other modules can be done after this


  Rebuild the main module, which converts the accumulated  20.SYM
into  heap  and  symbol-table  initialization:  (This step can be
omitted if  20.SYM  has  not  been  changed  by  the  incremental
recompilation.)


      @SUBMIT P20:MAIN.CTL


  Finally  LINK  the  xxxx.REL  and  Dxxxx.REL  files  to produce
S:BARE-PSL.EXE:


      @SUBMIT P20:PSL-LINK.CTL


  Execute and save  as  PSL.EXE,  reading  appropriate  xxxx.INIT
files:


      @SUBMIT P20:MAKE-PSL.CTL


  Finally, run MAKE-RLISP as needed:


      @SUBMIT P20:MAKE-RLISP.CTL


  Note  that  20.SYM  may  be changed slightly to reflect any new
symbols encountered, and certain generated symbols. Occasionally,
DEC-20 PSL Release                                        Page 14


repeated  building  of  certain modules can cause 20.SYM to grow,
and then a full rebuild may be required.


6.3. Rebuilding RLISP.EXE from PSL.EXE
6.3. Rebuilding RLISP.EXE from PSL.EXE
6.3. Rebuilding RLISP.EXE from PSL.EXE

  The PSL executable file, PSL.EXE, is a fairly bare system,  and
is  usually  extended  by loading appropriate utilities, and then
saving this as a new  executable.  We  have  provided  RLISP.EXE,
which  includes  the compiler, and the RLISP parser. RLISP.EXE is
built from PSL.EXE by the following commands:


   @TAKE PSL:minimal-logical-names.cmd
   @PSL:PSL.EXE
   (LOAD COMPILER RLISP INIT-FILE)
            % Also LOAD any other modules that
            % should be in your "standard" system
   (SAVESYSTEM "PSL 3.1 Rlisp" "PSL:rlisp.exe" '((Read-init-file
       "rlisp")))
            % The string is the Welcome Message, the save file
            % name and the startup expression to read rlisp.init.
   (QUIT)


  We have provided a command file,  P20:MAKE-RLISP.CTL  for  this
purpose.  Edit it to reflect any modules that local usage desires
in  the  basic  system  (EMODE,  PRLISP,  USEFUL, etc. are common
choices).


  In a similar fashion, a customized PSL.EXE could be  maintained
instead  of  the  "bare"  version  we  provide. In order to avoid
destroying PSL entirely, we suggest that you maintain a  copy  of
the  supplied PSL.EXE as BARE-PSL.EXE, and customize your PSL.EXE
from it.



7. RELATIONSHIP TO PSL 3.0
7. RELATIONSHIP TO PSL 3.0
7. RELATIONSHIP TO PSL 3.0

  This new  version  3.1  is  a  complete  release,  and  totally
replaces   the   previous   PSL   3.0   that   underwent  limited
                         __ ___ ___ ___       __ ____ ___
distribution. The files  pd:bug-fix.log  and  pd:bugs.txt  record
many  of  the  changes  and bug fixes that occurred since version
3.0.
DEC-20 PSL Release                                        Page 15


8. FUTURE UPDATES
8. FUTURE UPDATES
8. FUTURE UPDATES

  It  is  currently  envisioned that future updates will still be
complete releases.  It is therefore suggested that you


   a. Retain this distribution tape in case you may have  to
      compare files.

   b. Do   not   make   any  changes  on  these  distributed
      directories. If you must make your own bug  fixes,  it
      is  suggested  that  you put the changed files on some
                                 ____
      other directories, such as pnew:.  They  can  then  be
      compared  with  any  new  files sent out in subsequent
      releases.
DEC-20 PSL Release                                         Page i


                        Table of Contents
                        Table of Contents
                        Table of Contents

1. INTRODUCTION                                                 2
2. DISCLAIMER                                                   2
3. CONTENTS OF THE TAPE                                         3
4. INSTALLING PSL                                               5
     4.1. Retrieve Control Files                                5
     4.2. Create a single subdirectory                          5
     4.3. A MULTIPLE SUB-DIRECTORY SYSTEM                       7
     4.4. Build Sub-Directories                                 7
     4.5. Announce the System                                   9
     4.6. Summary of Restoration Process                        9
5. REBUILDING LOADABLE MODULES                                  9
6. REBUILDING THE INTERPRETER                                  10
     6.1. Complete Kernel Rebuild                              11
     6.2. Partial or Incremental Kernel Rebuild                12
     6.3. Rebuilding RLISP.EXE from PSL.EXE                    14
7. RELATIONSHIP TO PSL 3.0                                     14
8. FUTURE UPDATES                                              15