commit 1ce1e5ee11337a75e665bcbd141849ed5a4376df
parent 7bf79f816239f334e6f4d9554f66371d4c843f19
Author: Alexander Burger <abu@software-lab.de>
Date: Thu, 5 May 2011 11:45:02 +0200
Global vs. local invocation (./p -> ./pil <-> pil)
Diffstat:
| M | INSTALL | | | 80 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------- |
1 file changed, 59 insertions(+), 21 deletions(-)
diff --git a/INSTALL b/INSTALL
@@ -1,4 +1,4 @@
-14apr11abu
+05may11abu
(c) Software Lab. Alexander Burger
@@ -10,11 +10,25 @@ 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.
+PicoLisp supports two installation strategies: Local and Global.
+The default (if you just download, unpack and compile the release) is a local
+installation. It will not interfere in any way with the world outside its
+directory. There is no need to touch any system locations, and you don't have to
+be root to install it. Many different versions - or local modifications - of
+PicoLisp can co-exist on a single machine.
-Please follow these steps:
+For a global installation, allowing system-wide access to the executable and
+library/documentation files, you can either install it from a ready-made
+distribution, or set some symbolic links to one of the local installation
+directories as described below.
+
+Note that you are still free to have local installations along with a global
+installation, and invoke them explicitly as desired.
+
+
+ Local Installation
+ ------------------
1. Unpack the distribution
@@ -61,36 +75,35 @@ Please follow these steps:
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
+ Global Installation
+ -------------------
- and a copy of the startup script
+The recommended way for a global installation is to use a picolisp package from
+the OS distribution.
- # cp /<installdir>/bin/pil /usr/bin
+If that is not available, you can (as root) create four symbolic links from
+/usr/lib, /usr/share and /usr/bin to a local installation directory
- for a convenient global invocation. 'pil' can also serve as a template for
- your own stand-alone scripts.
+ # ln -s /<installdir> /usr/lib/picolisp
+ # ln -s /<installdir> /usr/share/picolisp
+ # ln -s /usr/lib/picolisp/bin/picolisp /usr/bin/picolisp
+ # ln -s /usr/lib/picolisp/bin/pil /usr/bin/pil
Invocation
----------
-The shell script 'dbg' is usually called to start up a local PicoLisp in
-interactive debugging mode
+In a global installation, the 'pil' command should be used. You can either start
+in plain or in debug mode. The difference is that for debug mode the command
+must be followed by a single plus sign ('+') argument.
- $ ./dbg
+ $ pil # Plain mode
:
-In a global installation, the equivalent call is
-
- $ pil +
+ $ pil + # Debug mode
:
-(Note the trailing '+' for the debugging mode)
-
In both cases, the colon ':' is PicoLisp's prompt. You may enter some Lisp
expression,
@@ -104,13 +117,38 @@ To exit the interpreter, enter
or just type Ctrl-D.
+For a local invocation, specify a path name, e.g.
+
+ $ ./pil # Plain mode
+ :
+
+ $ ./pil + # Debug mode
+ :
+
+or
+
+ $ /home/app/pil # Invoking a local installation from some other directory
+
+
+A shortcut for debug mode is the 'dbg' script:
+
+ $ ./dbg
+ :
+
+It is available only for local installaions, and is eqivalent to
+
+ $ ./pil +
+
+Note that 'pil' can also serve as a template for your own stand-alone scripts.
+
+
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 +').
+instead of './dbg' './pil +'.
Documentation
