SWISH::API - Perl interface to the Swish-e C search library

$Id: README 2049 2008-03-08 15:33:49Z moseley $

DESCRIPTION
-----------

SWISH::API is an Object Oriented Perl interface to the swish-e C library. This can be used
to embed the swish-e search code into your perl program avoiding the need to run the swish-e
binary for searching.

The real difference is that search speed is improved since you may attach to a swish-e index
once and then run many queries on that open "swish handle".  This speed comes at a cost of
memory added to your program.

Note: This module replaces the SWISHE module available with versions prior to
2.3 of Swish-e.  It's recommended to upgrade your Perl code to use the
SWISH::API module.


INSTALLATION
------------

See the FAQ below if you do not have root access or installed swish in a non-standard
directory.

1) Download, build and install swish-e

    See http://swish-e.org for instructions.

    Swish is also available as a binary package from some
    operating system distributions (e.g. Debian).

2) Build the module in the normal way

    $ perl Makefile.PL
    $ make
    $ make test

Then install, this may need to be done as the root user

    $ sudo make install


Makefile.PL requires the "swish-config" program which is created when installing
swish-e.  It must reside in the same directory as the swish-e binary.  See below
if installing swish-e in a non-standard location.


FAQ
---

1) I do not have root access.  How do I link to the swish-e library?

When building the SWISH::API module the compiler and linker look in locations for header and
library files.  If swish was installed in a non-standard location you will need to specify
that location when building the module.

For example, to install *swish* in $HOME/local:

   $ ./configure --prefix=$HOME/local
   $ make && make install

Now build SWISH::API

   $ cd perl

Makefile.PL has to find the "swish-config" program.  It does this normally by searching
your PATH environment variable:

   $ PATH=$HOME/local/bin:$PATH perl Makefile.PL

another way is to specify the path with the SWISHBINDIR parameter:

   $ perl Makefile.PL SWISHBINDIR=$HOME/local/bin

(or as an environment variable)

   $ SWISHBINDIR=$HOME/local/bin perl Makefile.PL

Since you don't have root access, you should also specify where to install the
SWISH::API perl module by using the PREFIX parameter:

   $ perl Makefile.PL SWISHBINDIR=$HOME/local/bin PREFIX=$HOME/my_perl_lib

Note, that you can also specify LIBS and INC to override the settings that the
swish-config program reports.  If you have a reason to do this then you probably
already know how to override these settings.


2) How do I build a PPM under Windows using MSVC and PERL 5.8?

   $ cd perl

   $ perl Makefile.PL \
     LIBS="../src/win32/libswish-e-mt.lib ../../zlib/lib/zlib.lib libcmt.lib" \
     OPTIMIZE="-MT -Zi -DNDEBUG -O1 -I../src"

   # Logic says to use CCFLAGS for -I../src but it explodes spectacularly...

   $ nmake
   $ nmake ppd

   $ tar cvzf SWISH-API.tar.gz blib

Edit SWISH-API.ppd to your liking and upload it and SWISH-API.tar.gz to your repository in the appropriate locations.

PROBLEMS
========

If you have problems or need help please contact the swish-e discussion list.  The list is
low traffic and is the place to get help with this module or swish-e in general.