README-POWERLOOM

-*- Mode: Text -*-

POWERLOOM INSTALLATION GUIDE

Version: README,v 1.6 2006/05/21 07:35:39 hans Exp
This document describes PowerLoom 3.0 or later.

For more documentation on PowerLoom, please see the PowerLoom manual.
This is available from the PowerLoom web site:

  http://www.isi.edu/isd/LOOM/PowerLoom/

and included with the release, in the directory `sources/logic/doc/'.


System Requirements
===================

To install and use PowerLoom, you'll approximately need the following
amounts of disk space:

   * 16 MB for the tarred or zipped archive file

   * 70 MB for the untarred sources, tanslations, compiled Java files,
     and documentation

   * 16 MB to compile a Lisp version

   * 16 MB to compile the C++ version (without -g)

   * 5 MB to compile the Java version (already included)


   This means that you will need approximately 100 MB to work with one
Lisp, one C++ and one Java version of PowerLoom in parallel.  If you
also want to experiment with the Lisp translation variant that uses
structures instead of CLOS instances to implement STELLA objects, then
you will need an extra 16 MB to compile that.

   The full PowerLoom development tree is quite large, since for every
STELLA source file there are three to four translated versions and as
many or more compiled versions thereof.  The actual PowerLoom libraries
that you have to ship with an application, however, are quite small.
For example, the Java jar files `powerloom.jar' and `stella.jar' are
only 2.3 MB total (4 MB including Java sources).  The dynamic C++
libraries `libstella.so' and `liblogic.so' compiled on a Linux
platform, are about 8 MB total.  Additionally, if you don't need all
the different translations of PowerLoom, you can delete some of the
versions to keep your development tree smaller *Note Removing Unneeded
Files::.

   To run the Lisp version of PowerLoom, you will need an ANSI
Common-Lisp (or at least one that supports CLOS and logical pathnames).
We have successfully tested PowerLoom with Allegro-CL 4.2, 4.3, 5.0,
6.0 and 7.0, Macintosh MCL 3.0, 4.0 and 5.1, OpenMCL 1.0, SBCL 0.9.4,
CMUCL 19c, LispWorks 4.4.6, CLisp 2.37, Lucid CL 4.1 (plus the
necessary ANSI extensions and Mark Kantrowitz's logical pathnames
implementation), and various others.  Our main development platform is
Allegro CL running under Sun Solaris and Linux.  The closer your
environment is to ours, the higher are the chances that everything will
work right out of the box.  Lisp development under Windows should also
be no problem.

   To run the C++ version of PowerLoom, you will need a C++ compiler
(such as g++) that supports templates and exception handling.  We have
successfully compiled and run PowerLoom with g++ 3.2 and later under
Linux Redhat 8.0 & 9.0, SunOS and MacOS X, and with CygWin 5.0 and MinGW
5.0 under Windows 2000 and XP.  Both CygWin and MinGW provide a GNU Unix
environment, but MinGW can generate Windows executables that are fully
standalone.  We've also managed to compile PowerLoom under MS Visual
C++, however, we never got the Boehm garbage collector to work.  The GC
claims to be very portable, so this should be solvable for somebody with
good knowledge of MS Visual C++.

   For the Java version, you will need Java JDK 1.2 or later. To get
reasonable performance, you should use J2SDK 1.4 or 1.5.  We've run the
Java version of PowerLoom on a variety of platforms without any
problems.

   Any one of the Lisp, C++, or Java implementations of PowerLoom can be
used to develop your own PowerLoom-based applications.  Which one you
choose is primarily a matter of your application and programming
environment.  The Lisp and Java versions are comparable in speed, the
C++ version is usually a factor of 2-3 faster than Lisp or Java.


Unpacking the Sources
=====================

Uncompress and untar the file `powerloom-X.Y.Z.tar.gz' (or unzip the
file `powerloom-X.Y.Z.zip') in the parent directory of where you want
to install PowerLoom (`X.Y.Z' are place holders for the actual version
numbers).  This will create the PowerLoom tree in the directory
`powerloom-X.Y.Z/' (we will use Unix syntax for pathnames).  All
pathnames mentioned below will be relative to that directory which we
will usually refer to as the "PowerLoom directory".


Lisp Installation
=================

To install the Lisp version of PowerLoom, startup Lisp and load the file
`load-powerloom.lisp' with:

     (CL:load "load-powerloom.lisp")

   The first time around, this will compile all Lisp-translated STELLA
files before they are loaded.  During subsequent sessions, the compiled
files will be loaded right away.

   By default, PowerLoom now uses the version that uses Lisp structs
instead of CLOS objects to implement STELLA objects.  If you do want to
use the CLOS-based version instead do the following:

     (CL:setq cl-user::*load-cl-struct-stella?* CL:nil)
     (CL:load "load-powerloom.lisp")

   Alternatively, you can edit the initial value of the variable
`*load-cl-struct-stella?*' in the file `load-powerloom.lisp'.  Using
structs instead of CLOS objects greatly improves slot access speed,
however, it may cause problems with incremental re-definition of STELLA
classes (this is only an issue if you are developing your application
code in the STELLA language.  In that case, it is recommended to only
use the struct option for systems that are in or near the production
stage).

   Once all the files are loaded, you should see a message similar to
this:

     PowerLoom 3.2.0 loaded.
     Type `(powerloom)' to get started.
     Type `(in-package "STELLA")' to run PowerLoom commands directly
        from the Lisp top level.
     USER(2):

   To reduce startup time, you might want to create a Lisp image that
has all of PowerLoom preloaded.

   Now type
     (in-package "STELLA")

   to enter the `STELLA' Lisp package where all the PowerLoom code
resides.  Alternatively, you can type

     (powerloom)

   which will bring up a PowerLoom listener that will allow you to
execute PowerLoom commands.

   *IMPORTANT*: All unqualified Lisp symbols in this document are
assumed to be in the `STELLA' Lisp package.  Moreover, the `STELLA'
package does *NOT* inherit anything from the `COMMON-LISP' package (see
the file `sources/stella/cl-lib/cl-setup.lisp' for the few exceptions).
Hence, you have to explicitly qualify every Lisp symbol you want to use
with `CL:'.  For example, to get the result of the previous evaluation,
you have to type `CL:*' instead of `*'.


C++ Installation
================

To compile the C++ version of PowerLoom, change to the native C++
directory of PowerLoom and run `make' like this:

     % cd native/cpp/powerloom
     % make

   This will compile all PowerLoom and STELLA files as well as the C++
garbage collector.  It will then generate static or dynamic
`libstella', `liblogic' and other library files in the directory
`native/cpp/lib' which can be linked with your own C++-translated
PowerLoom (or other) code.  To test whether the compilation was
successful, you can run PowerLoom from the top-level PowerLoom
directory using the `powerloom' script (or `powerloom.bat' under a
Windows command prompt):

     % powerloom c++
     Running C++ version of PowerLoom...
     Initializing STELLA...
     Initializing PowerLoom...

         Welcome to PowerLoom 3.2.0

     Copyright (C) USC Information Sciences Institute, 1997-2006.
     PowerLoom comes with ABSOLUTELY NO WARRANTY!
     Type `(copyright)' for detailed copyright information.
     Type `(help)' for a list of available commands.
     Type `(demo)' for a list of example applications.
     Type `bye', `exit', `halt', `quit', or `stop', to exit.


     PL-USER |=

   This will run various PowerLoom startup code and then bring up a
PowerLoom command loop where you can execute commands.  The `c++'
argument tells the script to run the C++ version of PowerLoom (which is
also run by default as long as the C++ version was compiled).  If the
C++ version was not compiled or the `java' argument was given instead,
the Java version of PowerLoom will be run.

   Type

     (demo)

   to bring up a menu of available demos, type

     (run-powerloom-tests)

   to run the PowerLoom test suite, or type

     exit

   to exit PowerLoom.


Java Installation
=================

Nothing needs to be done to install the Java version.  Because Java
class files are platform independent, they are already shipped with the
PowerLoom distribution and can be found in the directory `native/java'
and its subdirectories.  Additionally, they have been collected into
the file `native/java/lib/powerloom.jar' in the PowerLoom directory.
To try out the Java version of PowerLoom, you can run PowerLoom from
the top-level PowerLoom directory using the `powerloom' script (or
`powerloom.bat' under a Windows command prompt):

     % powerloom java
     Running Java version of PowerLoom...
     Initializing STELLA...
     Initializing PowerLoom...

         Welcome to PowerLoom 3.2.0

     Copyright (C) USC Information Sciences Institute, 1997-2006.
     PowerLoom comes with ABSOLUTELY NO WARRANTY!
     Type `(copyright)' for detailed copyright information.
     Type `(help)' for a list of available commands.
     Type `(demo)' for a list of example applications.
     Type `bye', `exit', `halt', `quit', or `stop', to exit.


     PL-USER |=

   Similar to the C++ executable, this will run various PowerLoom
startup code and then bring up a PowerLoom command loop where you can
execute commands.  Type

     (demo)

   to bring up a menu of available demos, type

     (run-powerloom-tests)

   to run the PowerLoom test suite, or type

     exit

   to exit PowerLoom.


Removing Unneeded Files
=======================

To save disk space, you can remove files that you don't need.  For
example, if you are not interested in the C++ version of PowerLoom, you
can delete the directory `native/cpp'.  Similarly, you can remove
`native/java' to eliminate all Java-related files.  You could do the
same thing for the Lisp directory `native/lisp', but (in our opinion)
that would make it less convenient for you to develop new PowerLoom
code that is written in STELLA.  Finally, if you don't need any of the
STELLA sources, you can delete the directory `sources/stella'.  If you
don't need local copies of the STELLA and PowerLoom documentation, you
can delete parts or all of the directories `sources/stella/doc' and
`sources/logic/doc'.


Installing PowerLoom Patches
============================

If you already have an older version of PowerLoom installed, you can
upgrade to the latest patch level by downloading incremental sets of
patches instead of downloading the complete release.  Patch files are
usually significantly smaller than the complete release and patching an
existing installation can also preserve local additions, deletions, or
modifications.  PowerLoom patch files are available from the same
location as the full PowerLoom release.

   Patches are currently only available in Unix `diff' format which
requires the Unix `patch' utility to install them (the `patch' program
should be readily available on most Unix systems, otherwise, you can
get it for free from the Free Software Foundation).

   Patch files follow the following naming convention: Suppose the
current version of PowerLoom is 3.0.0.  Then the patch file to update
to the next patch level is called `powerloom-3.0.0-3.0.1.diff.gz'.

   *Important:* Patch files are strictly incremental.  Thus, to upgrade
from version 3.0.0 to 3.0.2, you will need two patch files: one to go
to version 3.0.1 and one to go from that to version 3.0.2; you will
have to apply them in that sequence.

   To find out the current version of your PowerLoom installation, look
at the version string displayed when the `powerloom' function is called
in Lisp, or when the C++ or Java program starts up.

   *Important:* Before you apply any patches, you should always make a
backup copy of your current PowerLoom installation to preserve any
local modifications you made, in case something goes wrong.

   To apply patches, copy the appropriate patch file to the top level of
your PowerLoom installation directory.  Suppose the patch file is called
`powerloom-3.0.0-3.0.1.diff.gz'.  You can apply the patches using the
following command:

     gunzip -qc powerloom-3.0.0-3.0.1.diff.gz | patch -p1

   If you deleted some native PowerLoom files to save space, you can
use the `-f' option to force `patch' to proceed even if files it needs
to patch do not exist anymore (this is somewhat dangerous in case
`patch' encounters some more serious problems).  For example:

     gunzip -qc powerloom-3.0.0-3.0.1.diff.gz | patch -p1 -f

   To keep patch files small, PowerLoom patch files do not contain
updated binary files that ship with the full release (such as Java
class files, jar files and PDF documents).  Those have to be
regenerated either manually or with help of available `Makefile's.  The
Lisp version of PowerLoom will automatically recompile the first time
the updated system is loaded.  To recompile the C++ installation follow
the installation instructions given above.  The Java version will need
to be recompiled manually (better patch recompilation support might
become available in the future).


Running PowerLoom
=================

The easiest way to run PowerLoom on a variety of platforms is to use the
`powerloom' or `powerloom.bat' scripts in the top-level PowerLoom
directory.  If you have Java installed on your system, these scripts
should run out of the box without any further installation
requirements.  If you want to use the Lisp version of PowerLoom, simply
load the file `load-powerloom.lisp' into your Common Lisp.  If you want
to use the C++ version, you have to compile it first.  See the
Installation section in this manual for more details on how to install
the Lisp, C++ or Java version of PowerLoom *Note Installation::.

   Under Unix or MacOS X, open a shell window somewhere to run
PowerLoom.  For example,

     % powerloom
     Running Java version of PowerLoom...
     Initializing STELLA...
     Initializing PowerLoom...

         Welcome to PowerLoom 3.2.0

     Copyright (C) USC Information Sciences Institute, 1997-2006.
     PowerLoom comes with ABSOLUTELY NO WARRANTY!
     Type `(copyright)' for detailed copyright information.
     Type `(help)' for a list of available commands.
     Type `(demo)' for a list of example applications.
     Type `bye', `exit', `halt', `quit', or `stop', to exit.

     PL-USER |=

   Under Windows, you can do something similar by running a Command
Prompt window and executing the `powerloom.bat' script.  You can also
simply double click on the script which will run PowerLoom and bring up
a Command Prompt window for you.

   Once the `|=' prompt has come up you can type in PowerLoom commands
and see their results.  The string preceding the prompt indicates the
"current module" relative to which commands are interpreted.  For
example, type the `demo' command to see a menu of available demos.
Step through one or more of them to get familiar with PowerLoom.

   PowerLoom is a reasoning engine that is intended to be integrated
into some host application software somewhat similar to a database
system.  This is the main reason why it currently only ships with a
command-line interface; however, we do have an experimental PowerLoom
GUI which might also be released at some point.


Command-Line Options
====================

There are a few command-line options that can be supplied to the
`powerloom' script.

     powerloom [c++|java]
               [{-e|--eval} STELLA-EXPRESSION]
               [--batch]

   The first optional argument determines what version to run if both
C++ and Java versions are installed.  If no specific version is
specified, the C++ version will be run if it is installed, otherwise,
the Java version will be run.

`--eval STELLA-EXPRESSION'
`-e STELLA-EXPRESSION'
     Specifies a STELLA expression that should be run just before the
     PowerLoom command loop gets initialized.  This expression has to
     be a known command (such as the various PowerLoom commands), since
     the STELLA evaluator cannot (yet) evaluate arbitrary STELLA code.
     For example, `powerloom -e '(demo "equations" FALSE)'' will run a
     particular demo before anything else.  You will need to
     appropriately quote special characters interpreted by the shell or
     the Command Prompt window.

`--batch'
     Runs PowerLoom in batch mode without running an interactive command
     loop.  This can be useful in conjunction with the `--eval' option
     to execute a single command or load a PowerLoom script via the
     `load' command.


Questions and Comments
======================

For questions or comments, please send mail to the PowerLoom Forum mailing list
at <powerloom-forum@isi.edu>.  Visit

   http://www.isi.edu/isd/LOOM/PowerLoom/powerloom-forum.html

if you want to sign up to the PowerLoom mailing lists.