[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
4.1 System Requirements 4.2 Unpacking the Sources 4.3 Lisp Installation 4.4 C++ Installation 4.5 Java Installation 4.6 Removing Unneeded Files 4.7 Installing PowerLoom Patches
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To install and use PowerLoom you'll approximately need the following amounts of disk space:
This means that you will need approximately 90 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 15 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 file `powerloom.jar' is only 2.2 MB (4 MB including Java sources). The dynamic C++ libraries `libstella.so' and `liblogic.so' compiled on a Linux platform are about 7 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 See section 4.6 Removing Unneeded Files.
To run the Lisp version of PowerLoom you 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 6.1, Macintosh CL 3.0-5.0, Lucid CL 4.1 (plus the necessary ANSI extensions and Mark Kantrowitz's logical pathnames implementation) and the freely available CMUCL 18e. Our main development platform is Allegro CL running under Sun Solaris and Linux RedHat, so, 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 is also not a problem.
To run the C++ version of PowerLoom you need a C++ compiler such as g++ that supports templates and exception handling. We have successfully compiled and run PowerLoom with g++ 3.2 under Linux Redhat 8.0, and with CygWin 5.0 under Windows 2000 (CygWin provides a very Unix-like environment). We have not yet tried to run the C++ version fully natively under Windows. The main portability issue is the garbage collector. It is supposed to be very portable and run natively on Windows platforms, but we have never verified that.
For the Java version you will need Java JDK 1.2 or later. To get reasonable performance, you should use JDK 1.3 or later. 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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".
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
If you want to use the version that uses Lisp structs instead of CLOS objects to implement STELLA objects do the following:
(CL:setq cl-user::*load-cl-struct-stella?* CL:t) (CL:load "load-powerloom.lisp") |
Alternatively, you can edit the initial value of the variable
*load-cl-struct-stella?*
in the file `load-stella.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.0.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 *
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To compile the C++ version of PowerLoom change to the native C++ directory
and run make
:
% cd native/cpp/logic % make |
This will compile all PowerLoom and STELLA files, the C++ garbage collector and generate static or dynamic `libstella' and `liblogic' library files in the directory `native/cpp/lib' which can later 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 like this:
% ./native/cpp/logic/logic Initializing STELLA... Initializing PowerLoom... Welcome to PowerLoom 3.0.0 Copyright (C) USC Information Sciences Institute, 1997-2003. 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. |= |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Nothing needs to be done to install the Java version. Since 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 `powerloom.jar' in the PowerLoom directory. To try out the Java version of PowerLoom run the following in the PowerLoom directory:
% java -jar powerloom.jar Initializing STELLA... Initializing PowerLoom... Welcome to PowerLoom 3.0.0 Copyright (C) USC Information Sciences Institute, 1997-2003. 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. |= |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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'.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 and you 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).
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |