B.2 Installing Source Code ¶

With this document, you should also have received a tape cartridge in tar format containing the complete Common Lisp source code. You should create some directory where you want to put the source code. For the following discussion, I will assume that the source code lives in the directory /usr/lisp. To install the source code on your machine, issue the following commands:

cd /usr/lisp
tar xvf <tape device>

The first command puts you into the directory where you want the source code, and the second extracts all the files and sub-directories from the tape into the current directory. <Tape device> should be the name of the tape device on your machine, usually /dev/st0.

The following sub-directories will be created by tar:

bin

contains a single executable file, lisp, which is a C program used to start up Common Lisp.

clc

contains the Lisp source code for the Common Lisp compiler and assembler.

code

contains the Lisp source code that corresponds to all the functions, variables, macros, and special forms described in Common Lisp: The Language by Guy L. Steele Jr., as well as some Mach specific files.

hemlock

contains the Lisp source code for Hemlock, an emacs-like editor written completely in Common Lisp.

icode

contains Matchmaker generated code for interfaces to Inter Process Communication (IPC) routines. This code is used to communicate with other processes using a remote procedure call mechanism. Under Mach, all the facilities provided by Mach beyond the normal Berkeley Unix 4.3 system calls are accessed from Lisp using this IPC mechanism. Currently, the code for the Mach, name server, Lisp typescript, and Lisp eval server interfaces reside in this directory.

idefs

contains the Matchmaker definition files used to generate the Lisp code in the icode directory.

lib

contains files needed to run Lisp. The file lisp.core is known as a Lisp core file and is loaded into memory by the lisp program mentioned above in the entry for the bin directory. This file has a format which allows it to be mapped into memory at the correct locations. The files spell-dictionary.text and spell-dictionary.bin are the text and binary form of a dictionary, respectively, used by Hemlock’s spelling checker and corrector. The two files hemlock.cursor and hemlock.mask are used by Hemlock when running under the X window system.

miscops

contains the Lisp assembler source code for all the miscops that support low level Lisp functions, such as storage allocation, complex operations that can not performed in-line, garbage collection, and other operations. These routines are written in assembler, so that they are as efficient as possible. These routines use a very short calling sequence, so calling them is very cheap compared to a normal Lisp function call.

mm

contains the Lisp source code for the Matchmaker program. This program is used to generate the Lisp source code files in icode from the corresponding matchmaker definitions in idefs.

pcl

contains the Lisp source code for a version of the Common Lisp Object System (originally Portable Common Loops), an object oriented programming language built on top of Common Lisp.

X

contains the C object files for X version 10 release 4 C library routines. These are linked with the lisp startup code, so that X is available from Lisp.

scribe

contains Scribe source and postscript output for the manuals describing various aspects of the CMU Common Lisp implementation.

demos

contains the Lisp source code for various demonstration programs. This directory contains the Gabriel benchmark set (bmarks.lisp) and a sub-directory containing the Soar program which is also used for benchmarking purposes. There may be other programs and/or sub-directories here that you may look at.

These directories contain source files as well as Lisp object files. This means it is not necessary to go through all the steps to build a new a Common Lisp, only those steps that are affected by a modification to the sources. For example, modifying the compiler will require recompiling everything. Modifying a miscop file should require only reassembling that particular file and rebuilding the cold core file and full core file.

As well as the directories mentioned above, there are also several files contained in the top-level directory. These are:

init.lisp

is a Lisp init file I use. This sets up some standard search lists, as well as defines a Hemlock mode for editing miscop source files.

lisp.c

contains the C code used to start up the lisp core image under Mach.

lispstart.s

contains some assembler language code that is invoked by lisp.c to finish the process of starting up the lisp process.

makefile

contains make definitions for compiling lisp.c and lispstart.s into the lisp program.

rg

contains some adb commands that can be read into adb while debugging a lisp process. It prints out all the registers, the name of the currently executing Lisp function, and sets an adb variable to the current stack frame which is used by the following file.

st

contains some adb commands that can be read into adb while debugging a lisp process. It prints out a Lisp stack frame and the name of the function associated with the stack frame. It also updates the adb variable mentioned above to point to the next stack frame. Repeatedly reading this file into adb will produce a backtrace of all the active call frames on the Lisp stack.

ac

contains some adb commands that print out the current values of the active catch pointer. This points to the head of a list of catch frames that exist on the control stack.

cs

contains some adb commands that print out the contents of a catch frame. Reading cs into adb several times in a row (after reading ac once) will print out the catch frames in order.