README LUALA

Introduction

LUALA is an acronym for LUcene Application LAyer. It is an intermediate level API for document indexing and searching. It uses the low-level API of Lucene (see http://jakarta.apache.org/lucene).

Besides Lucene, LUALA uses a few other freely available packages. See the section LICENSE for details.

LUALA includes three sample application. A command-line indexer, a command-line searcher, and a GUI-searcher. These are suitable for direct use.

DISCLAIMER

LUALA is released under the GNU LESSER GENERAL PUBLIC LICENSE, Version 2.1, see the file COPYING.LESSER.
The licenses of included packages differ, but are less restrictive than the LGPL.

Hopefully, the acronym is complicated enough to prevent any name-clash with existing projects.
There is however a town in Malaysia named Luala and there is a vase from LSA-International called Luala. This project has nothing to do with both entities.

LICENSE

The proliferation of various open-source licenses makes it quite difficult for application-assemblers to pick a suitable license. The packages used to build LUALA and their corresponding licenses are:

Lucene:      COPYING.Apache (The Apache Software License, Version 1.1)
             http://jakarta.apache.org/lucene
PDFBox:      COPYING.PDFBox (a BSD-type license)
             http://www.pdfbox.org
Log4j:       COPYING.Apache (The Apache Software License, Version 1.1)
             http://jakarta.apache.org/log4j/
Java-Getopt: COPYING.LIB (GNU LIBRARY GENERAL PUBLIC LICENSE Version 2)
             http://www.urbanophile.com/arenn/

COMPILATION

To compile (and use) LUALA, you need two packages. The LUALA source-code in an archive named luala-src-version.tar.bz2, and the supporting libraries in an archive named luala-extlib-version.tar.bz2. Note that the version-numbers need not be equal, the extlib-archive is only updated as needed. Just fetch the lib-archive with the highest available version-number. You should unpack the extlib-archive within the luala-basedirectory:

> tar -xvjf luala-src-version.tar.bz2 -C ~/src > tar -xvjf luala-extlib-version.tar.bz2 -C ~/src/luala-version

You need ant to compile and build LUALA. Just run

> ant lib

to create the library jar. If you want to build and use the sample applications, run

> ant deploy

This will create a standalone, all-in-one jar-file with all necessary library-jars and the applications included. You will find the jar-file together with some useful command-scripts in the deploy subdirectory.

Use

> ant -projecthelp

for an overview of additional targets (or have a look at the build.xml).

RUNNING

Create an index with

> cmdindexer -s sourceDir -i indexDir [-u]

cmdindexer also accepts filenames from stdin, so you could also run

> find sourceDir -type f | cmdindexer -i indexDir

If this command looks strange to you, switch to a real OS ;-) Use the -u option to update an existing index.

To query the index, run

> cmdsearcher -i indexDir [ -p path-prefix ] [-H] query

If you prefer the GUI-version, try

> guisearcher -i indexDir -b browser [ -p path-prefix ] start-page

All commands also accept the -h command-line option. This option will print a short usage message and exit.

BUGS, CONTRIBUTIONS, NOTES

If you think you found a bug or want to contribute some code please drop me a note. Note that I check my mail only once or twice a week, so please be patient.