Installing Pathena
------------------


Required Software

The Pathena application runs on Unix/Linux platforms using commonly
available open-source packages. It has been tested on Red Hat family
Linux distributions.  It should run on BSD systems, but might require
changes to the scripts.

Pathena requires a contemporary Python suite (version 2.2.x or later)
and a fairly recent PostgreSQL distribution (version 7.4.x or
later). Recent versions of Linux include suitable implementations of
these as standard software.  Fedora Core 2 and later are known to
contain all required packages.  If all RPMs have been installed on a
Fedora 2/3/4 system, Pathena should run out of the box.


Quick Installation Procedure

If you have a recent Unix/Linux distribution with all of the binary
packages installed, you can use the quick setup method.  All that's
needed is to unpack the files and run the one-step installation script.
It will check on needed packages and report any missing items.

1. Go to your home directory and unpack the tar file:

     tar -xvzf <path>/pathena-<version>.tgz

   This will create the subdirectory '.pathena' under your home
   directory.  All source code, database files and user configuration
   data will be kept here.  No special privilege is needed to run
   Pathena; all software runs with user access permissions only.

2. Start the installation script as follows:

     ./.pathena/build/quick_install

   This script will check for suitable versions of required software.
   If all packages are available, the initial database will be
   created using default parameter values.  A database server
   process will be started and left running, then the GUI client for
   submitting queries will be started.  If all is successful, Pathena
   will be ready for immediate use.


Running Pathena

The installation script above adds the following symbolic links to your
~/bin directory for command line invocation:

  pathena : starts the GUI client and, if necessary, the database server

  ptfind  : runs a query from the command line and displays any results

For a workstation or desktop system, we suggest leaving the Pathena 
client active at all times.


Building Source Distributions

If a recent binary distribution of PostgreSQL is not available on your
Unix/Linux system, the source distribution may be downloaded from
www.postgresql.org (version 7.4 or later).  Source packages 'base' and
'opt' will be needed:

    postgresql-base-XXX.tar.gz
    postgresql-opt-XXX.tar.gz

After building and installing the source version of Postgres, Pathena
may be installed.  For older OS distributions (e.g., Red Hat 8 or
earlier), installing from source is unlikely to work due to
incompatibilities with shared libraries.  It is known to work for Red
Hat 9 and Fedora 1.


Full Installation Procedure

1. First install the Pathena distribution in its target location.  Go
   to your home directory and unpack the tar file using the command:

     tar -xvzf <path>/pathena-<version>.tgz

   This will create the subdirectory '.pathena' under your home
   directory.  All source code, database files and user configuration
   data will be kept here.  No special privilege is needed to run
   Pathena; all software runs with user access permissions only.

   If you would like to keep Pathena files in a directory other than
   ~/.pathena, first unpack and move the distribution to your desired
   location.  Then change to that directory and run the relocation
   script using the command './build/relocate'.  The default location
   of ~/.pathena should suffice for nearly all users, though.

2. Check that Python and its key library modules are available.  From
   a shell, enter the Python interpreter by typing 'python'.  The
   interpreter will report its version.  It needs to be 2.2.x or later.

   The GUI is implemented via Python's interface to Tcl/Tk, which is
   called Tkinter.  Type 'import Tkinter' to the Python interpreter.
   If the module is unavailable, it will report an exception.

   The PyGreSQL 'database adapter' is required to establish
   connections to the PostgreSQL database server.  Type 'import pgdb'
   to the interpreter.  Again, if it is unavailable, an exception will
   result.  You may now type Ctrl-D to exit the Python interpreter.

   If either pgdb or Tkinter is missing, you will need to install the
   appropriate packages.  The package names and installation
   procedures are system dependent.

3. Check that a suitable PostgreSQL environment is installed.  From
   a shell type 'pg_config --version', which reports the version if
   PostgreSQL is installed.  If it is missing or has a version earlier
   than 7.4.x, you will need to install a recent package from your OS
   distribution or build from the source distribution of PostgreSQL.

   If building from source (downloadable from www.postgresql.org), the
   normal procedure is to compile the distribution, then install it
   into '/usr/local' (the default location), which requires root
   privilege.  When making the binaries, an option to include Python
   server-side language support is required in the configure step.
   After unpacking the distribution, type the following commands:

     ./configure --with-python
     gmake
     su
     <root password>
     gmake install
     exit

   The build and installation process should take 10-15 minutes.

4. Check the settings in file '~/.pathena/bin/definitions'.  If any
   environment variables need changing (they shouldn't unless you
   built PostgreSQL from source in step 3), copy this file to the
   '~/.pathena/config' directory and edit that version.  Don't
   edit the version in 'bin'.  If the default socket port 5439 is in
   use, you will need to edit the definitions with a new port number.

5. If you are using a binary distribution of PostgreSQL, skip to step 6.
   Otherwise, if you built PostgreSQL from source in step 3, you will
   need to compile some 'contrib' modules as well.  You first need to
   locate the contrib subdirectory in the source distribution, which
   typically is in /usr/local/src/postgresql-x.y.z/src or someplace
   similar.  Then type the following command sequence, which again
   requires root privilege:

     cd <contrib subdirectory>
     cd dbsize
     make
     cd ../tsearch2
     make
     su
     <root password>
     make install
     cd ../dbsize
     make install
     exit

   This action will compile the contrib modules and install the files
   into PostgreSQL's directories (hence the need for root privilege).

   At this point you could run the quick_install script described
   above or continue with the steps below.

6. Now you are ready to create a PostgreSQL database cluster, which is
   a directory tree that will hold all of the database files.  If you
   were running as root in earlier steps, be sure to exit the root
   shell, then enter this command:

     ~/.pathena/build/init_pg_cluster

   This script will populate '~/.pathena/data' with various files and
   subdirectories, all of which are managed by the database server and
   should not be disturbed.

   This script also starts the PostgreSQL server process and leaves
   it running.  The following steps assume that a server process is
   already up and running.  In the ~/.pathena/bin directory are two
   additional scripts to start and stop the database server:
   'start_server' and 'stop_server'.

7. Next, create the initial Pathena database by typing this command:

     ~/.pathena/build/create_pathena_db

   This script will generate messages from the server as the various
   SQL commands of the database schema are processed.

8. Now the client GUI process may be invoked using this command:

     ~/.pathena/bin/launch_client_pytk

   You may perform most of the Pathena tasks from the comfort of the
   client's Tk-based GUI environment.

9. A test profile has been provided to allow you to index a small 
   portion of your file system before moving on to more ambitious
   attempts.  You may initiate and control indexing jobs from the
   client interface.  Profile 'test' (found in ~/.pathena/profiles)
   will cause the files of '~/.pathena' to be indexed and cataloged
   in the newly created Pathena database.  This profile will index
   the content of Pathena's Python source files.  After successfully
   indexing the files in profile 'test', you may proceed to try the
   query interface and gain some experience with conducting searches.

10. When you are ready to start indexing your own files in earnest,
    we suggest starting small and working up to larger and larger
    subsets.  You may either erase and recreate the database between
    indexing runs (using script create_pathena_db), or index on top
    of what you have already built.


Uninstalling Pathena

To uninstall the application, first shut down any client and server
instances currently running.  Then run the following command (or
equivalent if installed in a different location):

  ~/.pathena/build/uninstall

This script will delete all database files as well as the application
software files.


-----------

