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.