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.

This book is available in HTML form via FTP from
  ftp.cs.cmu.edu:/user/ai/lang/lisp/doc/cltl/cltl_ht.tgz  and
  ma2s2.mathematik.uni-karlsruhe.de:/pub/lisp/CLtL2/cltl_ht.tgz
and can be viewed through WWW under
  http://www.cs.cmu.edu:8001/Web/Groups/AI/html/cltl/cltl2.html or
  http://www.cs.cmu.edu:8001/afs/cs/project/ai-repository/ai/html/cltl/cltl2.html .

For experts: This standard text has emerged into an ANSI standard, which
you can exceptionally get free of charge from
  http://www.harlequin.com/books/HyperSpec/

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:

#ifdef UNIX
#ifndef UNIX_BINARY_DISTRIB
   base/lisp.a            main program, to be linked
#endif
#ifdef UNIX_BINARY_DISTRIB
   base/lisp.run          main program
#endif
   base/lispinit.mem      memory image needed for startup
   doc/clisp.1            manual page in Unix man format
   doc/clisp.man          manual page
   doc/clisp.html         manual page in HTML format
   doc/impnotes.txt       implementation notes
   doc/cltl2.txt          notes about the relation of CLISP to CLtL2
#ifdef GNU_READLINE
   doc/clreadline.3       line editing manual page in Unix man format
   doc/clreadline.man     line editing manual page
#endif
   doc/LISP-tutorial.txt  LISP tutorial for beginners
   doc/CLOS-guide.txt     brief guide to CLOS
   README                 this text
   SUMMARY                short description of CLISP
   ANNOUNCE               announcement
   NEWS                   list of modifications since the last version
   COPYRIGHT              copyright notice
   GNU-GPL                free software license
#ifdef GNU_READLINE
   doc/readline.dvi       GNU readline library documentation
#endif
   doc/editors.txt        survey of editors with Lisp support
   emacs/*.el             Emacs customization, see doc/editors.txt
#ifndef UNIX_BINARY_DISTRIB
   src/clisp.c            source of driver program
#endif
   src/config.lsp         site-dependent configuration

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

   src/*.lsp              the source of lispinit.mem
   src/*.fas              the same files, already compiled
#if !defined(UNIX_BINARY_DISTRIB) && defined(GNU_READLINE)

For building the executable, you also need:

   base/libreadline.a     GNU readline library

or

   base/libnoreadline.a   dummy replacement for the GNU readline library
#endif
#else /* !defined(UNIX) */
#ifdef AMIGAOS
      lisp.run           main program
#endif
#ifdef MSDOS
      lisp.exe           main program
#ifndef OS2
      lisp_1mb.exe       main program, use this one if you have
                         only 1 or 2 MB of RAM
#endif
#endif
#ifdef RISCOS
      lisp               main program
#endif
      lispinit.mem       memory image needed for startup
      clisp.1            manual page in Unix man format
#ifdef AMIGAOS
      clisp.doc          manual page
#else
      clisp.man          manual page
#endif
      clisp.html         manual page in HTML format
#ifdef MSDOS
      clisp.dvi          manual page in dvi format
#endif
      impnotes.txt       implementation notes
      cltl2.txt          notes about the relation of CLISP to CLtL2
#ifdef GNU_READLINE
      clreadline.3       line editing manual page in Unix man format
      clreadline.man     line editing manual page
#ifdef MSDOS
      clreadline.dvi     line editing manual page in dvi format
#endif
#endif
      LISP-tutorial.txt  LISP tutorial for beginners
      CLOS-guide.txt     brief guide to CLOS
#ifdef EMUNIX
      emx-user.doc       emx applications user's guide
      emx-faq.doc        frequently asked questions about emx applications
#ifdef EMUNIX_PORTABEL
      emx.dll            OS/2 dynamic link library containing emx
      emxlibc.dll        OS/2 dynamic link library containing the emx libc
#endif
      termcap.dat        terminal capabilities database
#endif
#if defined(MSDOS) && !defined(OS2)
      rsx.exe            DOS extender rsx for running clisp under Windows
      rsx-read.txt       general description of rsx
      rsx-inst.txt       installation instructions for rsx
      rsx-faq.txt        frequently asked questions about rsx applications
      rsx-copy.txt       copyright notice for rsx
      delay.exe          auxiliary program for running clisp under Windows
#endif
#ifdef RISCOS
      !Run               run file for CLISP
      !Sprites           icon for CLISP
#endif
      README             this text
      SUMMARY            short description of CLISP
      ANNOUNCE           announcement
      NEWS               list of modifications since the last version
      COPYRIGHT          copyright notice
      GNU-GPL            free software license
#ifdef GNU_READLINE
      readline.dvi       GNU readline library documentation
#endif
      config.lsp         site-dependent configuration
#if !(defined(UNIX) || defined(WIN32))
      timezone.lsp       site-dependent time zone
#endif

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

      *.lsp              the source of lispinit.mem
#if !defined(MSDOS)
      *.fas              the same files, already compiled
#endif
#endif

#ifdef MSDOS

Hardware requirements:
----------------------

#ifndef OS2
This DOS version of CLISP requires an 80386 (SX or DX) or an 80486 CPU
and at least 1 MB of RAM.
#else
This OS/2 version of CLISP requires an 80386 (SX or DX) or an 80486 CPU,
running OS/2 2.0.
#endif
It also runs on a Pentium; the results CLISP produces are not affected by
the Intel Pentium's division bug.

#endif
#ifdef AMIGAOS

Hardware requirements:
----------------------

This Amiga version of CLISP requires at least 1.5MB RAM. The version called
CLISP-LOW runs on machines with no memory outside the 24 bit addressable
range: on 68000, A2620, A2630. The version called CLISP-HIGH runs in memory
that is 27 bit addressable (address range #x00000000 to #x07FFFFFF), but
only on 68020/030/040(/60?) CPU: on A3000 and A4000 without Zorro-III memory
boards. The version called CLISP-00 runs on 68000/010 CPU only but is faster
than CLISP-LOW. The version called CLISP-WIDE uses 64 bit integers and runs
in any memory on 68020 or better CPU: on A4000 using VMM. The overhead for
64 bit integers cause CLISP-WIDE to be slower than CLISP-HIGH.

#endif
#ifdef RISCOS

Hardware requirements:
----------------------

This version of CLISP requires an Acorn Archimedes or Acorn RISC PC with at
least 4MB RAM and RISC OS 3.0 or higher. See below how to produce a version
of CLISP that runs in only 2 MB.

#endif
#if defined(SINGLEMAP_MEMORY) && (defined(UNIX_LINUX) || !defined(HAVE_MMAP_ANON))

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

#ifdef UNIX_LINUX
#ifdef GENERATIONAL_GC
#ifdef IMMUTABLE
This version of CLISP requires Linux 1.2.2 or newer.
#else
This version of CLISP requires Linux 1.1.52 or newer.
#endif
#else
This version of CLISP requires Linux 0.99.7 or newer.
#endif
#endif
#if !defined(HAVE_MACH_VM) && !defined(HAVE_MMAP_ANON) /* impliziert HAVE_MMAP_DEVZERO */
/dev/zero must be readable by everyone. You may execute a "chmod a+r /dev/zero"
to ensure this.
#endif

#endif
#ifdef AMIGAOS

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

This version of CLISP requires OS 2.04 (V37) or newer.

#endif

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

#ifdef OS2
First of all, install emx.dll and emxlibc.dll in a separate directory,
say c:\emx\dll. Add c:\emx\dll (insert the correct drive letter)
to the LIBPATH statement in your config.sys file. Reboot your computer
to enable the new LIBPATH statement and the new environment variables.

#endif
#ifdef EMUNIX
For overly long input lines to be displayed in a smart manner, it is necessary
that you have a line like

    DEVICE=ANSI.SYS

in your CONFIG.SYS file. Furthermore the environment variable TERM must
be set, and the environment variable TERMCAP must contain the slashified
file name of the terminal capabilities database termcap.dat. It is a good
idea to put this stuff into the clisp.bat built below. You may want to
install termcap.dat in a separate directory, say c:\emx\etc.

#endif
#if defined(UNIX) || defined(WIN32)
#if defined(UNIX) && !defined(UNIX_BINARY_DISTRIB)
Type

         make

#if 0 /* def GNU_READLINE - man muß Makefile verändern */
If you prefer to resign GNU readline's input editing capabilities, you should
have previously replaced the "libreadline.a" in the LIBS line of the file
base/makevars by "libnoreadline.a".

#endif
#endif
Change the strings in src/config.lsp, using a text editor.
#else
Edit the contents of config.lsp appropriately for your site,
especially the definitions of short-site-name and long-site-name.
You may also want to edit the time zone definition at the end of
timezone.lsp.
#endif
Then start

#ifdef MSDOS
         lisp.exe -M lispinit.mem
#endif
#ifdef AMIGAOS
         lisp.run -M lispinit.mem
#endif
#ifdef UNIX
         base/lisp.run -M base/lispinit.mem
#endif
#ifdef RISCOS
         lisp -M mem.lispinit

or double click on the !Clisp directory.
#endif

When the LISP prompt

      > _

appears, type

#ifdef RISCOS
        (cd "<clisp$path>.")

to make sure the !Clisp directory is the currently selected directory. Then

#endif
#if defined(UNIX) || defined(WIN32)
        (compile-file "src/config.lsp")
        (load "src/config.fas")
#else
        (compile-file "config.lsp")
        (load "config.fas")

and - in case you modified timezone.lsp -

        (compile-file "timezone.lsp")
        (load "timezone.fas")
#endif

and then

#ifdef UNIX
        (cd "base/")
#endif
        (saveinitmem)

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

        (exit)

#ifdef UNIX
The rest is done by a simple

        make install

Instead, you may do this yourself, step by step:

#endif
#ifndef RISCOS
Then create a directory, and put the executable and the memory image there.
#endif
#ifdef UNIX
I would suggest /usr/local/lib/lisp :

   mkdir /usr/local/lib/lisp
   mv base/lisp.run /usr/local/lib/lisp
   mv base/lispinit.mem /usr/local/lib/lisp
#endif
#ifdef MSDOS
Assuming D:\LIB\LISP :

   mkdir d:\lib\lisp
   copy lisp.exe d:\lib\lisp
   copy lispinit.mem d:\lib\lisp
#endif

#ifdef MSDOS
And create a batch file that starts lisp:

#ifndef OS2
   copy con c:\bat\clisp.bat
#else
   copy con c:\cmd\clisp.cmd
#endif
#ifdef EMUNIX
   set TERM=ansi
   set TERMCAP=c:/emx/etc/termcap.dat
#endif
   d:\lib\lisp\lisp.exe -M d:\lib\lisp\lispinit.mem %1 %2 %3 %4 %5 %6 %7 %8 %9
   [Ctrl-Z]
#endif
#ifdef UNIX
#ifdef UNIX_BINARY_DISTRIB
And create a shell script that starts lisp:

   cat > /usr/local/bin/clisp
#ifndef UNIX_BROKEN_SH
#ifdef UNIX_USE_KSH
   #!/bin/ksh
#else
   #!/bin/sh
#endif
   exec /usr/local/lib/lisp/lisp.run -M /usr/local/lib/lisp/lispinit.mem "$@"
#else
   #!/bin/sh
   if test $# = 0; then
     exec /usr/local/lib/lisp/lisp.run -M /usr/local/lib/lisp/lispinit.mem
   else
     exec /usr/local/lib/lisp/lisp.run -M /usr/local/lib/lisp/lispinit.mem "$@"
   fi
#endif
   [Ctrl-D]EOF
   chmod a+x /usr/local/bin/clisp
#else
And create the driver program that starts lisp:

   cc -O -DLISPLIBDIR='"/usr/local/lib/lisp"' \
         -DLOCALEDIR='"/usr/local/share/locale"' \
      src/clisp.c -o /usr/local/bin/clisp
#endif

#ifdef GNU_READLINE
Now install the man pages
#else
Now install the man page
#endif

   mv doc/clisp.1 /usr/local/man/man1/clisp.1
#ifdef GNU_READLINE
   mv doc/clreadline.3 /usr/local/man/man3/clreadline.3
#endif

and try

   man clisp
#endif

#if defined(MSDOS) && !defined(OS2)

Installation under Microsoft Windows:
-------------------------------------

CLISP also runs in the DOS box of Microsoft Windows 3.1.
To achieve this, the following additional steps are necessary:

1. Get and install
     ma2s2.mathematik.uni-karlsruhe.de:/pub/lisp/clisp/binaries/dos/clisp.zip
   as described above.

2. If rsx.exe is not already contained in clisp.zip,
   get and install RSX in, for instance, c:\rsx.
     ftp.uni-bielefeld.de:/pub/systems/msdos/misc/rsx503rt.zip

3. Call the PIF editor and input the following:

   Program:                c:\rsx\bin\rsx.exe
   Program title:          COMMON LISP
   Program parameters:     -Ra c:\lib\lisp\lisp.exe -M c:\lib\lisp\lispinit.mem
                           (maybe after -Ra add also -Rs1024)
   Start directory:        e:\lisp  (or whatever)
   Screen:                 Text
   Memory requirements:    requires:  500      maximum:  640
   EMS memory:             requires:    0      maximum:    0
   XMS memory:             requires: 1024      maximum:   -1
   Display:                [as you like]
   Quit_closes_window:     [as you like]
   Execution:              [as you like]
   other_options:          [as you like]

   (You will probably choose the directory which contains your lisp programs
   as start directory, instead of e:\lisp.)

   Save it under the name WINCLISP.PIF.

4. In the program manager, in a suitable group:

   Menu "File" -> "New" -> "Program", window "program properties".
   Input there:

   Description:            COMMON LISP
   Command line:           winclisp.pif
   Start directory:        e:\lisp
   Key combination:        Ctrl+Alt+Shift+L      [as you like]

Clicking with the mouse on the such created icon or pressing the key
combination given above in the program manager will now start CLISP.

Remarks:

* Cut & Paste in DOS boxes (via menu "Edit" -> "Mark" resp.
  menu "Edit" -> "Insert") inserts an <Enter> at the end. Therefore one
  cannot re-edit a pasted line.

* But the editing facilities mentioned in CLISP.MAN and READLINE.DVI work.

#endif
#ifdef AMIGAOS

Note:
-----

You can start CLISP from Workbench(tm). The following Tooltypes are
recognized in the Tool Icon:

   WINDOW=<window or pipe specification>
   ARGS=<CLI-like arguments>

For example,

   WINDOW=CON:0/11/640/200/CLISP-Listener/CLOSE
   ARGS=-M lispinit.mem

#endif
#ifdef RISCOS

Short of memory?
----------------

If you have only 2 MB RAM, you can easily produce a stripped-down CLISP
that will require less memory, but lacks some parts of CLtL2, dpANS-LOOP,
CLOS, Conditions and generic streams: Replace defs2.fas, loop.fas, clos.fas,
conditio.fas, defs3.fas, gstream.fas by empty files and run

   lisp
   > (load "init.fas")
   > (saveinitmem)
   > (exit)

This will overwrite lispinit.mem with a smaller one.

#endif

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

#ifdef EMUNIX
If clisp doesn't start up at all, check EMX-USER.DOC. lisp.exe is an EMX
application, so everything mentioned there applies to lisp.exe.

#endif
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
     Backtrace
               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.

#ifdef UNIX
On bigger problems, e.g. core dumps, please send a description of the error
#endif
#ifdef AMIGAOS
On bigger problems, e.g. "guru"s, please send a description of the error
#endif
#ifdef MSDOS
On bigger problems, e.g. register dumps, please send a description of the error
#endif
#ifdef RISCOS
On bigger problems, e.g. stack dumps, please send a description of the error
#endif
and how to produce it reliably to the authors or the maintainer. Please
accompany it with the CLISP version, which you get by calling
(lisp-implementation-version).


Sources:
--------

The sources of CLISP are available from
     ftp://ma2s2.mathematik.uni-karlsruhe.de/pub/lisp/clisp/source/clispsrc*
#ifdef UNIX_LINUX
The latest binary distribution of CLISP for Linux has its sources in
     ftp://sunsite.unc.edu/pub/Linux/devel/lang/lisp/clisp-source.tar.gz
#endif


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:
----------------

#ifdef MSDOS
If you find CLISP fast and bug-free and you like using it, a gift of $25
(or any amount you like) will be appreciated. Most DOS software costs
something, so you will probably already be used to paying.

If not, feel free to send us suggestions for improvement. Or grab the
source of CLISP, improve it yourself and send us your patches.

#endif
We are indebted to
  * Guy L. Steele and many others for the Common Lisp specification.
#ifdef UNIX
  * Richard Stallman's GNU project for GCC, Autoconf and the readline library.
#else
#ifdef GNU_READLINE
  * Richard Stallman's GNU project for GCC and the readline library.
#else
#ifdef GNU
  * Richard Stallman's GNU project for GCC.
#endif
#endif
#endif
#ifdef EMUNIX
  * Eberhard Mattes for EMX.
#endif


Authors:
--------

        Bruno Haible
        Michael Stoll

Email: haible@ma2s2.mathematik.uni-karlsruhe.de
#ifdef AMIGAOS

Amiga Port by:
--------------

        Jörg Höhle

Email: Joerg.Hoehle@gmd.de
#endif
#ifdef RISCOS

Acorn RISC OS Port by:
----------------------

        Peter Burwood

Email: clisp@arcangel.dircon.co.uk
#endif

Maintainer:
-----------

        Marcus Daniels

Email: marcus@sysc.pdx.edu
