BSD 4_4 development

[unix-history] / usr / src / old / lisp / ReadMe

File: ReadMe 				-[Tue Mar 29 22:03:29 1983 by jkf]-
Location: the root of the lisp distribution tree

    This directory contains a Makefile which can will direct the 
initial construction and installation of the Franz Lisp system.  After the 
lisp system is installed, the Makefiles in the subdirectories should be
used directly when modifications are made to either piece of code.

    The lisp system consists of these parts:
 1) lisp - lisp interpreter
 2) liszt - lisp compiler
 3) lxref - lisp cross reference program
 4) library of files - collection of lisp files.  Some are already loaded
	into lisp. Others are loaded on demand.  Still others are just
	contributed files.
 5) on-line manual - the lisp manual formatted for lineprinter or terminal
	perusal.  The lisp 'help' command refers to this manual
 6) lisp manual - the troff input form for the lisp manual.  If you can 
	run troff or nroff at your site then you can generate a lisp manual
	from the files in this directory.
 7) pearl  AI database program - this is a contributed program.  More details
	can be found in the file pearl/ReadMe.  This program will not
	be generated automatically by the Makefile in this directory.
	If disk space is short, the pearl subdirectory may be removed
	and it won't affect any other programs.

To build lisp, follow these steps:

1) Run './lispconf' to describe the system you will be building lisp for.
   Just type './lispconf' and it will describe the possible
   configurations.   Typically, when lisp is distributed it is configured
   to run under 4.1c on a vax.

   Look in franz/h/config.h.  You may want to alter some of the
    configuration parameters before you start.

2) Look at the path name defaults in the Makefiles in the various
    source directories ({franz,liszt}/{vax,68k},utils,lisplib).
    You can modify these defaults if you like.  It is suggested
    that you leave the lisp library in /usr/lib/lisp.
    Most code doesn't really depend on where the library is,
    just as long as when the system is built, the directory
    name is known.  However, some application programs may depend on the
    library being in /usr/lib/lisp.

3) If this is a distribution of lisp source (as opposed to a complete
    4.x distribution) then you will want to copy the
    lisp library files in lisplib into the lisp library (typically
    /usr/lib/lisp).  [If you don't want to use /usr/lib/lisp change
    the value of LibDir in the Makefile].  Now type
		make copylibrary
    and the library files in lisplib will be copied to the lisp
    library.  If an error message occurs, it may be that you don't
    have permissions to write in the lisp library.  If this is the
    case, fix the permissions and type 'make copylibrary' again.

4) If you have a working lisp system, then you may be able to bring the
    system up quickly.  Type
		make fast
    and the Makefile will attempt to build a new lisp, liszt, and lxref
    and place them in franz/mylisp, liszt/nliszt and liszt/lxref respectively.
    [See Note 1 below.]
    If it fails, then you may just have to start from scratch, see step 5.
    If it works, go to step 6.

5) To make the entire lisp system, interpreter and compiler, from scratch,
    type:
		make slow
    This may take three to four hours on an unloaded vax.
    See Note 1 below.

6) once the files are made, type
		make install
    and new versions of lisp, liszt and lxref (the compiler cross reference
    program) will be installed in ObjDir.

7) If you've changed where files live, then you should change the defaults
    in each of the makefiles: liszt/Makefile, franz/Makefile, doc/Makefile
    and /usr/lib/lisp/Makefile.


Note 1: Two files which are necessary yet which are not distributed 
are the assembler and linking loader.  The assembler is required by
liszt after it has compiled a file, the loader is required by the 'cfasl'
and 'ffasl' functions.  These programs are expected to be in 
/usr/lib/lisp/as and /usr/lib/lisp/nld.  The Makefile will copy
them from /bin/as and /bin/ld.  If you are running a Berkeley vax
distribution, this is ok.  If you are using non-berkeley as or ld
then you will have to get a copy of the berkeley as or ld and place
them in /usr/lib/lisp yourself.  We don't distribute them because
they require a Unix license and because we want to avoid distributing
object files.

Note 2: For 68000 systems, we can distribute source for the assembler,
by agreement with MIT, Megatest Corp and Sun Microsystems.  As an aid
to constructing the lisp system on machines with limited memory or swap
space, you may have received the assembly language output of the
compiler for the lisp library and compiler itself.  The 68k compiler
starts out running as 1.25 Megabytes and will grow larger as it retains
macros and other information about the functions it is compiling.
(This may be impossible on certain systems.)

The .s files are distributed in files of the form x68k.38.58.*.  The
source for the assembler is in a file called lispas.  In any case, you
should still say "cat * | sh", in order to create the appropriate
files.  To construct the assembler, assemble the .s files, and contruct
the lisp system quickly, say "make fromasm" instead of "make slow".


Changes:
  Look in franz/ChangeLog and liszt/ChangeLog for a blow by blow description
of bug fixes and new features.  Also the file lispnews in this directory
describes changes to lisp which affect the user.  This file is most
easily read with  'mail -f lispnews'.

The major changes are described next.

  opus 38: the reader has changed quite a bit.  It now uses symbolic
	syntax codes and it provides infix macros.  
	The lisp library files have been reorganized in order to make
	lisp bootstrapable.

Future bug fixes:
  When you find bugs in Lisp or Liszt, mail a letter to franz-bugs@berkeley
  or ucbvax!franz-bugs.   
  We will mail bug fixes to the franz-composers mailing list.  To get on 
  this mailing list, mail a letter to franz-friends-request@berkeley or
  ucbvax!franz-friends-request.

Documentation:
  The source (troff form, with -me macros) for the Franz Lisp Manual is
in the doc subdirectory.  There is a line printer printable version 
in lisplib/manual (which is most likely copied to /usr/lib/lisp/manual).
  There is also a system manual which may be of interest to people who
want to modify the lisp system or just understand how it works.  The file
is doc/franz.n.  


The meanings of the default directories and paths in the Makefiles
in this directory tree (and LibDir)

LibDir : [/usr/lib/lisp]
	directory containing the lisp library sources, some of which
	are required to build a lisp system.  Change this with caution,
	Some programs may depend on it being /usr/lib/lisp

DestObjDir : [/usr/ucb]
	place to put the lisp and liszt that we build.  Note that for
	the liszt -r flag to work, the lisp interpreter must be in
	/usr/ucb

ObjDir: Directory containing existing lisp and liszt (if they exist).
	if they don't exist, then you will do a 'make slow' and the value
	of ObjDir doesn't matter

LispDist: [/usr/src/cmd/lispdist]
	directory to build distribution in.

CcodeDir: [../franz]
	location of C coded kernel as seen from the liszt directory

CopyTo : used as the destination directory of some of the commands in
	the makefile.  it has a different meaning in each.