Developer Readme for the LuceneServer
=====================================

0    Contents
-------------

- Requirements
- How To Compile
- Configuration Files


1    Requirements
-----------------

What you need:
JDK (unsure of minimum version but why go less than 1.3.1?)
	A JRE is not sufficient as classes need to be compiled.
    NOTE: If using Java 1.3.x then additional libraries are
          required.  This is because Java 1.3.x does not include
          the necesary XML libraries and definitions. 
          The additional libraries are included and are:
              xml-apis.jar   - definitions of document/element etc
              xercesImpl.jar - apache implementation of xml parser
          These steps are not needed with Java >= 1.4.x as it 
          includes a XML parser.
ANT (1.5 required. get from http://ant.apache.org/)
    NOTE: As of 21/Jan/2003 Debian stable only has Ant 1.4.x which
          is not sufficient.  Debian unstable however has Ant 1.5.x.
LUCENE - This is included in binary form in the lib folder.
         http://jakarta.apache.org/lucene

         It is distributed under the Apache Software Licence 
         http://apache.org/licenses/LICENSE

         
2    How To Compile the LuceneServer
--------------------------------
         
Ensure that both java/javac and ant can be run from the command line.

The following environment variables may need to be set:
JAVA_HOME
ANT_HOME
CLASSPATH (if needed, using ant is better)
PATH=/path/to/java:/path/to/ant/bin

In order to compile Lucene from source the JavaCC.zip file is required.
It is a hassle to find on the net so it is included in the ./lib
folder for your convienience.  

Ant build Commands for this project (only normal usage ones are shown):

compile  - compile the server
jar      - create jar of the server
run      - run the server
javadocs - create java docs
jar-src  - create a jar file of the src files
package  - not really applicable for LuceneServer
clean    - delete generated files

If starting fresh from cvs setup your environment (java, ant) then 
run the command:
ant javadocs
from the project root to generate the javadocs.  These contain documentation
on the classes of the LuceneServer.
It can be found in build/docs/api/index.html

3    Configuration Files
------------------------

There are several configuration files needed to configure the LuceneServer.

These are:
Server.config                   - luceneserver configuration
etc/application/xxx.properties  - index/application specific config
etc/log4j.xml                   - logging configuration

Server.config
This file contains global properties for the luceneserver.  It is 
documented in the .config file itself.  This file contains things
such as configuration file directories, port numbers etc.

xxx.properties
These files contain information about indexes the LuceneServer manages.

Please see the example.properties file in etc/application.

log4j.xml
This file contains the logging configuration information.  Most logging it
done through log4j.  Some exception messages still escape to system.err.
By default the log outut goes asynchronously to system.out (usually the
command line).  The can be changed by modifying this file.  It includes 
the configuration options (commented out) to have both a rolling debug
log and a daily info log.
Note: Currently different logging levels for different classes and/or
packages has not been implemented.