08mar11abu
(c) Software Lab. Alexander Burger


         PicoLisp Installation
         =====================

There is no 'configure' procedure, but the PicoLisp file structure is simple
enough to get along without it (we hope). It should compile and run on
GNU/Linux, FreeBSD, Mac OS X (Darwin), Cygwin/Win32, and possibly other systems
without problems.

By default, PicoLisp installs completely in a local directory. No need to touch
any system locations, so you don't have to be root.


Please follow these steps:

1. Unpack the distribution

      $ tar xfz picoLisp-XXX.tgz

2. Change the directory

      $ cd picoLisp-XXX

3. Compile the PicoLisp interpreter

      $ (cd src; make picolisp)

   or, if you have an x86-64 Linux or SunOS system, build the 64-bit version

      $ (cd src64; make picolisp)

   In both cases the executable bin/picolisp will be created.


   To build the 64-bit version the first time (bootstrapping), you have the
   following three options:

   - If a Java runtime system (version 1.6 or higher) is installed, it will
     build right out of the box.

   - Otherwise, download one of the pre-generated "*.s" file packages

     - http://software-lab.de/x86-64.linux.tgz
     - http://software-lab.de/x86-64.sunOs.tgz

   - Else, build a 32-bit version first, and use the resulting bin/picolisp to
     generate the "*.s" files:

      $ (cd src; make)
      $ cd src64
      $ make x86-64.linux.base.s x86-64.linux.ext.s x86-64.linux.ht.s

   After that, the 64-bit binary can be used to rebuild itself.


   Note that on the BSD family of operating systems, 'gmake' must be used
   instead of 'make'.

4. Optional (but recommended if you have permission to switch to root) are two
   symbolic links from /usr/lib and /usr/bin to the installation directory

      # ln -s /<installdir> /usr/lib/picolisp
      # ln -s /usr/lib/picolisp/bin/picolisp /usr/bin/picolisp

   and a copy of the startup script

      # cp /<installdir>/bin/pil /usr/bin

   for a convenient global invocation. 'pil' can also serve as a template for
   your own stand-alone scripts.


      Invocation
      ----------

The shell script 'dbg' is usually called to start up a local PicoLisp in
interactive debugging mode

   $ ./dbg
   :

In a global installation, the equivalent call is

   $ pil +
   :

(Note the trailing '+' for the debugging mode)

In both cases, the colon ':' is PicoLisp's prompt. You may enter some Lisp
expression,

   : (+ 1 2 3)
   -> 6

To exit the interpreter, enter

   : (bye)

or just type Ctrl-D.


If you just want to test the ready-to-run Ersatz PicoLisp (it needs a Java
runtime system), use

   $ ersatz/picolisp +
   :

instead of 'dbg' (or 'pil +').


      Documentation
      -------------

For further information, please look at "doc/index.html". There you find the
PicoLisp Reference Manual (doc/ref.html), the PicoLisp tutorials (doc/tut.html
and doc/app.html), and the frequently asked questions (doc/faq.html).

For details about the 64-bit version, refer to "doc64/README", "doc64/asm" and
"doc64/structures".

As always, the most accurate and complete documentation is the source code ;-)
Included in the distribution are many utilities and pet projects, including
tests, demo databases and servers, games (chess, minesweeper), 3D animation
(flight simulator), and more.

Any feedback is welcome!
Hope you enjoy :-)

--------------------------------------------------------------------------------

   Alexander Burger
   Software Lab. / 7fach GmbH
   Bahnhofstr. 24a, D-86462 Langweid
   abu@software-lab.de, http://www.software-lab.de, +49 8230 5060
