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

$Id: README,v 1.5 2003/06/08 21:52:05 augur Exp $

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.  There is a SWISHE interface module available on the Swish-e site if you have
existing code that depends on previous versions of the SWISHE module.

    http://swish-e.org/Download/SWISHE-0.03.tar.gz

That version is simply an interface to the SWISH::API module.  You must install the
SWISH::API module to use SWISHE-0.03.tar.gz.

It's recommended to upgrade your Perl code to use the SWISH::API module directly instead of
using the SWISHE-0.03 interface module if possible.


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


Note that running "perl Makefile.PL" will ask for the location of the swish-e binary.  Make
sure you specify the location of the swish-e binary that matches the version of swish-e you
are linking the module with (i.e. from the same package as the SWISH::API perl module).  Be
aware that many ISPs have outdated versions of swish-e installed.




FAQ
---

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 to build the SWISH::API module:

   $ cd perl

   $ perl Makefile.PL PREFIX=$HOME/local \
     CCFLAGS=-I$HOME/local/include \   
     LIBS="-L$HOME/local/lib -lswish-e"

   $ LD_RUN_PATH=$HOME/local/lib make

   $ make test && make install

That last line above is bourne shell syntax.  Other shells may use a different syntax for
setting the LD_RUN_PATH environment variable before running make.

The "PREFIX" parameter to Makefile.PL sets where the module will be installed when running
"make install".


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.   


