![[Contents]](../manuals/icons/contents.gif){kind=icon}
![[Prev]](../manuals/icons/prev.gif){kind=icon}
![[Next]](../manuals/icons/next.gif){kind=icon}
Installing the KOE is primarily a matter of installing and checking the software on which the KOE depends. This document describes the required software and installation considerations which must be addressed as well as the installation and configuration of the KOE software itself.
The KOE requires a moderate set of installed software on the host. The specific items required are listed below, with instructions for building the components under "Building the Required Packages."
The KOE currently requires some form of the UNIX operating system. It has been tested on Solaris 2.6 (Intel and SPARC). It is assumed that the operating systems on the host computers have been installed in a reasonable configuration.
Many of the packages described below, such as Python, ILU, and Tcl/Tk are provided in binary form. Even so, you may still want to build those systems from source, perhaps after you apply patches, or because you want to install them in a location other than the default location. If so, you will need a C compiler. Some UNIX systems provide a C compile, others do not. If you do need one, GCC, the GNU C compiler makes a good choice. Be sure to get at least version 2.8.1 of gcc (we know there are bugs with gcc 2.8.0, so don't use that one; earlier versions of gcc may work, but we haven't tried them).
You may need tools such as zcat, tar, GNU gzip/gunzip, patch, and others in order to unpack the various source releases and apply any requisite patches. It is assumed that your UNIX system either already provides the necessary tools, or that you can get them from, say any GNU ftp site.
Python 1.5.1 is the most recent release of the Python language at the time of this writing. This version is required for this release of the KOE; future versions of Python are expected to be suitable. Python 1.5 is known not to work, although it may not be too difficult to fix the Python 1.5.1'isms in the KOE software. Python can be obtained from the Python Software Activity.
Xerox PARC has created a distributed object system called ILU (Inter-Language Unification) which is used in the KOE. The KOE was tested with ILU version 2.0a12 with a number of patches to support building the runtime with the more recent version of Python and to correct some memory leaks. ILU and the patches may be obtained from the ILU home page.
In addition to the required software, some optional software can be used with the KOE, to enable certain tools or demos. Again, the specific items required are listed below, with instructions for building the components under "Building the Optional Packages."
The KOE components which present a graphical user interface use the Tk toolkit from Sun Microsystems. Tk, in turn, requires the Tcl programming language libraries for internal use. The Tcl interface is also used in the Python extension which provides access to Tk. The KOE components which require Tk are compatible with Tcl/Tk 8.0. Tcl/Tk is available from Scriptics. We do not recommend using alpha or beta versions of Tcl/Tk with the KOE. Without Tcl/Tk (and Python configured to use it), the rs and visu tools and the SimpleIOAPI and PlayerAPI plugins will not work.
The Intellectual Property Rights Management demonstration uses some JPEG image files. Standard Tk can only natively display GIF files, so you need a tool to convert from JPEG to GIF. The simplest of these tools to install is the stand-alone djpeg conversion tool, which is distributed as part of the Independent JPEG Group's free JPEG software distribution.
The "official" archive site for JPEG distribution is ftp.uu.net (192.48.96.9). The most recent version can be found in the directory graphics/jpeg and as of this writing, the latest version is version 6b. The distribution contains information on building and installing the entire JPEG software, but for the purposes of the demo, you only need to build the djpeg program.
Python's README file gives detailed instructions for configuring, building and installing Python. Python can be configured to also include various extension modules when it is built. While the KOE software doesn't require you to build any modules other than those that are built by default, the following recommendations apply. Note that if you want to change the default set of built modules, you should first copy the file Modules/Setup.in to Modules/Setup and edit Modules/Setup. General instructions for editing this file are included at the top of the file.
dbm, GNU gdbm, or BSD
db. GNU gdbm is available from any
GNU site, such as
UUnet. Enable the line in Setup
depending on which is available at your site.
Python has proven to be very easily ported to a large number of systems. For most UNIX systems, no special arrangements are needed. Python uses an autoconf-generated configure script to handle configuration under UNIX. Most installations only need to specify the values for the --prefix and --exec_prefix options to configure if not using the default location (/usr/local). For additional configuration options, see the file README in the distribution.
Run make test to build Python and check that it is working properly. If everything is working, run make install to perform the installation.
ILU is the component of the KOE software which is the most difficult to configure and install. There are instructions available on the Web and included with the source archive, but there are a number of concerns and configuration parameters which are pertinent to using ILU with the KOE. Some of these are due to specific requirements of the KOE and others are due to rough edges in the ILU distribution. ILU uses a combination of an autoconf-generated configure script and imake templates for configuration and Makefile construction; this combination can be riddled with terror. Note that the X11 imake templates are not used (i.e., xmkmf is not needed, and X11 does not need to be installed for ILU to work, but you must have a working imake binary).
Start by downloading the source to ILU 2.0alpha12. As of this writing, this is the latest release of ILU, and the KOE software will not work with any older version. The ILU 2.0a12 source tarball is about 3.6MB, so plan your download accordingly.
Be careful when unpacking the ILU tarball because it unpacks into the current directory, and not its own subdirectory. It is highly recommended that you create a subdirectory called ilu-2.0a12 and cd into there before you unpack the ILU tarball. The instructions below assume you've done this.
Once the ILU sources have been unpacked, any notes distributed with the patches should be read, and all patches for the ILU version used should be applied. The patches are distributed from the ILU Web site as an HTML file; some implementations of the patch command may have difficulty with discarding the HTML sections between individual patches.
We have had success applying the patches to a virgin download of 2.0alpha12 using the following recipe:
ftp.parc.xerox.com using the anonymous account.
$ patch -l -p0 < /path/to/patches.html
$ patch -l -p0 < /path/to/p15threads2.patch
The final patch in the patches.html file has an incorrect path. patch will not be able to locate the file to patch, and it will query you for the file's path. Enter stubbers/cpp/common.c
Aside from this, both of these patches should apply completely with no chunk failures. If you see any failures, we recommend you delete the ILU 2.0a12 distribution, re-unpack it, and re-apply the patches, making sure you've followed every step outlined above. If you are still having problems, you may have to manually apply any rejected patches. We warn that this is a time-consuming, tedious, and error-prone process.
After applying Xerox's official ILU patches, you might want to install our unofficial python-stubber patch, which is in the file ilu-unofficial-patch.txt in the KOE software distribution (you'll have to download and unpack the KOE software fist of course). This patch works around some problems we've encountered in ILU when generating heavy load, as some of the Knowbot demos can do. This patch, in conjunction with the default use of the W3NG protocol as described below, helps make the KOE software more robust. This is an unofficial patch because, it only modifies the python-stubber (and thus just the generated Python code), and the ILU team will be fixing these problems in a better and more fundamental way. The KOE software will run without this unofficial patch, but if you notice ILU communication failures, you should try to apply this patch, and rebuild ILU.
Now that you've got all the patches applied, you need to build ILU. Here are some tips on choosing appropriate options for the configure script.
Despite of the use of an autoconf-generated configure script, ILU does not distinguish between the --prefix and --exec_prefix configuration parameters; only --prefix is used. For most sites, the value of this parameter should be set to a subdirectory of what would normally be the --exec_prefix parameter. The directory $exec_prefix/ilu may be a good choice. By default ILU installs in /usr/local/ilu which also might be good enough.
ILU provides two options for a simple binding service; these are not needed by the KOE, but may be built optionally.
ILU 2.0a12 enables Python support and W3NG support by default, but this could change in the future. We recommend giving the following command line options explicitly: --enable-w3ng-protocol, --enable-python-support, and if you are including Tk, --enable-tk-support.
We highly recommend that you configure ILU with the default protocol set to W3NG, by using the configure option --with-default-protocol=w3ng. W3NG is more efficient than SunRPC, and it also appears to be the most robust protocol in terms of failure avoidance. We have observed that ILU can fail catastrophically under heavy load, which some KOE demos can impose. However when using the W3NG protocol, along with our unofficial python-stubber patch, ILU seems to be much more robust.
Once the configuration options have been selected, configure, build, and install ILU. $ILUSRC is the location of the ILU source tree; refer to the ILU documentation for more information.
$ cd $ILUSRC $ ./configure <options> ...a bunch of stuff... $ make ...a bunch of stuff... $ make Install ...a bunch of stuff...
Assume ILU is installed in $exec_prefix/ilu. The next thing you need to do is byte-compile the Python files that come with ILU. Run these commands to accomplish this:
$ cd $exec_prefix/ilu
$ python -c "import compileall; compileall.compile_dir('.')"
...a bunch of stuff...
$ python -O -c "import compileall; compileall.compile_dir('.')"
...a bunch of stuff...
There should not be any errors generated by these commands, but any errors you do get are probably insignificant.
There are a couple of ways to provide the Python runtime with access to the ILU system. The preferred approach is to add a "path configuration file" to the $exec_prefix/lib/python1.5/site-packages directory. You may need to create the site-packages directory first. The file may be named ilu.pth and should contain the path to ILU's installed lib directory, (i.e. $exec_prefix/ilu/lib). For example, using ILU's default installation path of /usr/local/ilu, ilu.pth would contain:
/usr/local/ilu/lib/
If you are unable to create files in the installed Python
distribution, then you need to take a slightly different
approach. You can put the directory you would have
written in your ilu.pth file and instead,
append that path to your PYTHONPATH environment
variable. See the Python documentation for details.
$ python
Python 1.5.1 (#1, Sep 16 1998, 18:48:21) [GCC 2.8.1] on sunos5
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>> import iluPr
>>> iluPr.__file__
'/usr/local/ilu/lib/iluPrmodule.so'
>>>
The KOE software is installed by unpacking the source distribution and running make. The KOE software tarball unpacks into its own subdirectory, and this directory is the final installation location.
Cd into the parent directory of where you want to unpack the KOE source, and then use GNU gunzip and tar to extract the software. The exact commands are:
$ cd <install-dir-parent> $ gunzip -c knowbot-1.0alpha2.tar.gz | tar xf - $ cd knowbot-1.0alpha2/src
The directory referred to as $KOSROOT throughout this documentation is <install-dir-parent>/knowbot-1.0alpha2/src, created by unpacking the distribution, and you should be in this directory for much of the following instructions.
To complete the installation, you must run the ILU Python stubber on the ISL files in the src/koe/interfaces subdirectory; this is done after building and installing ILU. There are several things to note. First, the Python executable must be on your $PATH.
Second, if you installed ILU in a non-default location, perhaps because you specified a --prefix or --exec_prefix option to ILU's configure script, you must specify this by setting the make variable ILUHOME to the directory in which ILU was installed (see the example below).
If you installed ILU into its default location, you can simply type the following when in $KOSROOT:
If you installed ILU in a different location than the default, run this:$ make ...output of the ILU stub generator...
Now you want to install the KOE software tools that you'll be using. This just sets up some symbolic links into the KOE files, but by specifying a DESTDIR that's on your path, you can run the KOE programs more easily. By default, these tools are installed in /usr/local/bin by using this command:$ make ILUHOME=<ilu-install-dir> ...output of the ILU stub generator...
however, if you want to install the KOE tools in a different location, use this command:$ make install
$ make DESTDIR=<koe-install-dir> install
When you run these programs, it is assumed that the Python interpreter can be found on the shell's program search path. The aliased files must be executable, which should be the case if they have been extracted properly from the distribution tar archive. You can uninstall these links by typing:
If you specified the DESTDIR macro on the make install line above, you'll need to specify the same value when you run the make uninstall target.$ make uninstall
If Tcl/Tk will be used with the KOE, build Tcl/Tk before building Python. Python must be configured to include Tcl/Tk support. You can download Tcl/Tk from the Scriptics site. As of this writing, Tcl/Tk 8.0.3 has been released, and this should work fine for Python and the KOE. You may be able to use one of the binary releases for your platform, although we've personally only tested the source release of Tcl/Tk.
The build and installation procedures for Tcl and Tk are already well established; see the README file in each of the distributions for instructions. These packages can be built with the most basic configuration; the only requirement is to set appropriate values for the --prefix and --exec_prefix options to the configure script provided with each.
Building the Independent JPEG Group's free JPEG software distribution is pretty straight-forward. Included in the distribution is a file called install.doc which outlines the build procedures in detail. The build procedure is configure based, so building and installing is usually as simple as:
$ ./configure <options> $ make
As usual, the configure script recognizes the --prefix and --exec_prefix arguments. Once you've built and installed the JPEG software, make sure that the program djpeg is on your shell's path, otherwise the PlayerAPI plugin will not be able to find it.
The KOE software is configured by editing files in the config directory. The files are used to configure access control for the distributed namespace, for KOS kernels, for for the urllib proxy -- and to specify which KOS plugins should be started automatically when a KOS is started. Information about specific configurations is found in the following locations:
The access control file format is discussed in A Simple Access Control Mechanism.
Namespace root replication is described in Worldroot Server, with information on the file format used to set access controls in A Simple Access Control Mechanism.
KOS plugin configuration is discussed in Configuring KOS Plugins.
KOE startup and shutdown configuration is discussed in Boot and Halt scripts.