17nov10abu
(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 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 the pre-generated "*.s" files in
     "http://software-lab.de/x86-64.linux.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

   In that case, you might also copy the script bin/pil to /usr/bin, for a
   convenient global invocation.


      Invocation
      ----------

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

   $ ./dbg
   :

The colon ':' is PicoLisp's prompt. You may enter some Lisp expression,

   : (+ 1 2 3)
   -> 6

To exit the interpreter, enter

   : (bye)

or simply type an empy line (Return).


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

   $ ersatz/picolisp
   :

instead of 'dbg'.


         Console Underlines
         ==================

In case that your console (terminal) does not support underlining, you might
want to remove or replace the first statement int "ext.l" which uses the
terminfo database to initialize the global variable '*Tsm' (transient symbol
markup). Unfortunately, the VGA text mode does not properly support underlines.


      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
