Utah Symbolic Computation Group June 1983
Operating Note No. xx
Release Notes
Extended DEC-20 V3.1 PSL System
Extended DEC-20 V3.1 PSL System
Extended DEC-20 V3.1 PSL System
M. L. Griss and R. R. Kessler
Utah Symbolic Computation Group
Computer Science Department
University of Utah
Salt Lake City, Utah 84112
(801)-581-5017
20 June 1983
ABSTRACT
ABSTRACT
ABSTRACT
This note describes how to install the extended 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.
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.
DEC-20 PSL Release Page 3
The following lists each of the savesets, their logical names,
sizes and whether or not it is included in the saveset:
SSname Pages Min <Utah File Name> Logical Name
RESTORE-PSL 10 NO ---- ----
Files necessary to restore the PSL system.
PSL 1100 YES <psl> 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.
COMP 125 NO <psl.comp> pc:
Common compiler, LAP, FASL sources.
20COMP 55 NO <psl.comp.20> p20c:
DEC-20 specific compiler, LAP and FASL sources.
DIST 25 NO <psl.dist> pdist:
Files as an aid to the installer.
DOC 110 NO <psl.doc> pdoc:
Miscellaneous documentation files, including
random notes on new features.
20DOC 25 NO <psl.doc.20> p20d:
Documentation files that are 20 specific.
DOCNMODE 590 NO <psl.doc.nmode> pndoc:
NMODE documentation files.
GLISP 330 NO <psl.glisp> pg:
An object oriented LISP.
HELP 100 YES <psl.help> ph:
A set of *.HLP files, describing major modules.
KERNEL 225 NO <psl.kernel> pk:
Machine Independent kernel sources.
P20 560 NO <psl.kernel.20> p20:
DecSystem 20 dependent kernel sources.
LAP 500 YES <psl.lap> pl:
Mostly binary FASL (*.B) files, with some LISP
DEC-20 PSL Release Page 4
files (*.LAP) for loading multiple .B files of
loadable (optional) modules.
LPT 430 NO <psl.lpt> plpt:
The PSL manual in printable form (has
overprinting and underlining), as SCRIBE .LPT
files.
NMODE 270 NO <psl.nmode> pn:
The NMODE text editor sources, which is a newer
version of EMODE developed at HP Research
Laboratories.
NMODEBIN 230 YES <psl.nmode.binary> pnb:
The binary files associated with NMODE.
NONKERNEL 5 NO <psl.nonkernel> pnk:
The sources that are not in the kernel, but are
kernel related.
PT 215 NO <psl.tests> pt:
A set of timing and test files.
P20T 500 NO <psl.tests.20> p20t:
DecSystem 20 specific test files.
UTIL 575 NO <psl.util> pu:
Sources for most utilities, useful as examples of
PSL and RLISP code, and for customization.
P20U 60 NO <psl.util.20> p20u:
DecSystem 20 specific utilities.
WINDOWS 75 NO <psl.windows> pw:
The window support functions used by NMODE.
WINBIN 30 YES <psl.windows.binary> pwb:
The binaries associated with the window support.
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.
DEC-20 PSL Release Page 5
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 <*>*.*.* *.*.*
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 2400 should be sufficient).
Any <name> will do, since the logical device name PSL: will be
used.
@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>.
DEC-20 PSL Release Page 6
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:
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 currently use 18
sub-directories for the Common Sources and DEC-20 specific
sources, and have at least an extra three 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> along with the create-directories.ctl file.
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:
DEC-20 PSL Release Page 7
@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) :
@DO CREATE-DIRECTORIES.CTL
This will create all of the necessary directories.
Finally, restore the full system by DOing the full-restore.ctl
file:
@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.
DEC-20 PSL Release Page 8
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. NMODE is currently the only major
sub-system that has its 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.
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
DEC-20 PSL Release Page 9
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
___ __ ______ ___ __
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:
DEC-20 PSL Release Page 10
@DEFINE S: <scratch>
Now connect to <psl.20-comp> and rebuild DEC20-CROSS.EXE:
@CONN P20C:
@SUBMIT 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
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
DEC-20 PSL Release Page 11
version of Make-psl.ctl to perform this task).
@SUBMIT PDIST:MAKE-PSL.CTL
Finally, run MAKE-RLISP.CTL as needed:
@SUBMIT PDIST: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.
You may also remake, RLISPCOMP, PSLCOMP and NMODE, in a similar
manner.
@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.
Define S: as <scratch> or other scratch directory:
@DEFINE S: <scratch>
Rebuild DEC20-CROSS.EXE, if needed:
@SUBMIT P20C:DEC20-CROSS.CTL
DEC-20 PSL Release Page 12
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 PDIST:MAKE-PSL.CTL
Finally, run MAKE-RLISP as needed:
@SUBMIT PDIST:MAKE-RLISP.CTL
You may also remake, RLISPCOMP, PSLCOMP and NMODE, in a similar
manner.
Note that 20.SYM may be changed slightly to reflect any new
symbols encountered, and certain generated symbols. Occasionally,
repeated building of certain modules can cause 20.SYM to grow,
and then a full rebuild may be required.
DEC-20 PSL Release Page 13
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, PDIST:MAKE-RLISP.CTL for this
purpose. Edit it to reflect any modules that local usage desires
in the basic system (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
Even though this is the first version of PSL for the
DecSystem-20 that utilizes extended addressing, it is identical
to the PSL V3.1 for the non-extended 20. As a new PSL version
3.1, it 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.
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
DEC-20 PSL Release Page 14
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 2
4. INSTALLING PSL 4
4.1. Retrieve Control Files 5
4.2. Create a single subdirectory 5
4.3. A MULTIPLE SUB-DIRECTORY SYSTEM 6
4.4. Build Sub-Directories 6
4.5. Announce the System 7
4.6. Summary of Restoration Process 8
5. REBUILDING LOADABLE MODULES 8
6. REBUILDING THE INTERPRETER 9
6.1. Complete Kernel Rebuild 9
6.2. Partial or Incremental Kernel Rebuild 11
6.3. Rebuilding RLISP.EXE from PSL.EXE 13
7. RELATIONSHIP TO PSL 3.0 13
8. FUTURE UPDATES 13