10. Installation

10.1 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 See section 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, Clozure CL 1.5, SBCL 0.9.4, 1.0.47, CMUCL 19c, 19e, 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 or SBCL with Mac OS X. 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++ 4.0 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.6 or later. This is required to support the embedded server architecture for PowerLoom 4.x. 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.

10.2 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".

10.3 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 *.

10.4 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 4.0.0

Copyright (C) USC Information Sciences Institute, 1997-2010.
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.

10.5 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 4.0.0

Copyright (C) USC Information Sciences Institute, 1997-2010.
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.

10.6 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’.

10.7 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).

This document was generated by Hans Chalupsky on January 6, 2023 using texi2html 1.82.