This is CLISP, a Common Lisp implementation.


What is LISP?
-------------

LISP is a programming language. It was invented by J. McCarthy in 1959.
There have been many dialects of it, but nowadays LISP has been standardized
and wide-spread due to the industrial standard COMMON LISP. There are
applications in the domains of symbolic knowledge processing (AI), numerical
mathematics (MACLISP yielded numerical code as good as FORTRAN), and
widely used programs like editors (EMACS) and CAD (AUTOCAD).
There is an introduction to the language:

  Sheila Hughes: Lisp. Pitman Publishing Limited, London 1986.
  107 pages.

After a while wou will need the standard text containing the language
definition:

  Guy L. Steele Jr.: Common Lisp - The Language. Digital Press.
  1. edition 1984, 465 pages.
  2. edition 1990, 1032 pages.

LISP is run in an interactive environment. You input forms, and they will be
evaluated at once. Thus you can inspect variables, call functions with given
arguments or define your own functions.


Contents:
---------

It consists of the following files:

      lisp.a           main program, to be linked
      lispinit.mem     memory image needed for startup
      clisp.1          manual page in Unix man format
      clisp.man        manual page
      impnotes.txt     implementation notes
      README           this text
      SUMMARY          short description of CLISP
      ANNOUNCE         announcement
      COPYRIGHT        copyright notice
      GNU-GPL          free software license
      config.lsp       site-dependent configuration

and - to your convenience, if you like reading source -

      *.lsp            the source of lispinit.mem
      *.fas            the same files, already compiled

For building the executable, you also need:

      libreadline.a    GNU readline library
      readline.tar.Z   GNU readline library source and documentation

or

      libnoreadline.a  dummy replacement for the GNU readline library


Software requirements:
----------------------

This version of CLISP requires Linux 0.99.7 or newer.
/dev/zero must be readable by everyone. You may execute a "chmod a+r /dev/zero"
to ensure this.


Installation:
-------------

Type

         cc lisp.a -L. -lnoreadline -ltermcap -s -o lisp.run

or - if you prefer having GNU readline's input editing capabilities -

         cc lisp.a -L. -lreadline -ltermcap -s -o lisp.run

to build the executable against your C library.

Change the strings in config.lsp, using a text editor.
Then start

         lisp.run -M lispinit.mem

When the LISP prompt

      > _

appears, type

        (compile-file "config")
        (load "config")

and then

        (saveinitmem)

to overwrite the file lispinit.mem with your configuration. Then

        (exit)

Then create a directory, and put the executable and the memory image there.
I would suggest /usr/local/lib/lisp :

   mkdir /usr/local/lib/lisp
   mv lisp.run /usr/local/lib/lisp
   mv lispinit.mem /usr/local/lib/lisp

And create a shell script that starts lisp:

   cat > /usr/local/bin/clisp
   #!/bin/sh
   exec /usr/local/lib/lisp/lisp.run -M /usr/local/lib/lisp/lispinit.mem "$@"
   [Ctrl-D]EOF
   chmod a+x /usr/local/bin/clisp

Now install the man page

   mv clisp.1 /usr/local/man/man1/clisp.1

and try

   man clisp


When you encounter problems:
----------------------------

After errors, you are in the debugger:

     1. Break> _

You can evaluate forms, as usual. Furthermore:

     Help
               calles help
     Abort     or
     Unwind
               climbs up to next higher input loop
     (show-stack)
               shows the contents of the stack, helpful for debugging

And you can look at the values of the variables of the functions where the
error occurred.

On bigger problems, e.g. core dumps, please send a description of the error
and how to produce it reliably to the authors.


Mailing List:
-------------

There is a mailing list for users of CLISP. It is the proper forum for
questions about CLISP, installation problems, bug reports, application
packages etc.

For information about the list and how to subscribe it, send mail to
listserv@ma2s2.mathematik.uni-karlsruhe.de, with the two lines
          help
          information clisp-list
in the message body.


Acknowledgement:
----------------

We are indebted to
  * Guy L. Steele and many others for the Common Lisp specification.
  * Richard Stallman's GNU project for GCC, Autoconf and the readline library.


Authors:
--------

        Bruno Haible                    Michael Stoll
        Augartenstraße 40               Gallierweg 39
    D - W 7500 Karlsruhe 1          D - W 5300 Bonn 1
        Germany                         Germany

Email: haible@ma2s2.mathematik.uni-karlsruhe.de
