Introduction
See CHANGES for a description of the project status. Also see the web site: http://grok.sf.net
This file contains the configuration and build instructions; next see GETTING_STARTED.
Configuring your environment variables
The easiest thing to do is to set the environment variables "JAVA_HOME" and "GROK_HOME" to the relevant locations on your system. Set "JAVA_HOME" to match the top level directory containing the Java installation you want to use. For example:
On Windows:
C:\> set JAVA_HOME=C:\j2sdk1.4.0_01
or on Unix:
% setenv JAVA_HOME /usr/local/java
(csh)
> JAVA_HOME=/usr/java; export JAVA_HOME
(ksh, bash)
On Windows, to get these settings to persist, it's actually easiest to set your environment variables through the System Properties from the Control Panel. For example, under WinXP, go to Control Panel, click on System Properties, choose the Advanced tab, click on Environment Variables, and add your settings in the User variables area.
Next, likewise set "GROK_HOME" to be the top level directory where you unzipped the Grok download. In Unix, type 'pwd' in the directory where this file is and use the path given to you by the shell as "GROK_HOME". You can set this in the same manner as for "JAVA_HOME" above.
Next, add the directory GROK_HOME/bin to your path. For example, you can set the path in your .bashrc file as follows:
export PATH=$PATH:$JAVA_HOME/bin:$GROK_HOME/bin
Once you have taken care of these three things, you should be able to build and use Grok.
Installing the build tools
The only thing that you have to make sure of is that the "JAVA_HOME" environment property is set to match the top level directory containing the JVM you want to use. For example, on Windows:
C:\> set JAVA_HOME=C:\j2sdk1.4.0_01
or on Unix:
% setenv JAVA_HOME /usr/local/java
(csh)
> JAVA_HOME=/usr/java; export JAVA_HOME
(ksh, bash)
Building the system
The Grok build system is based on Jakarta Ant, which is a Java building tool originally developed for the Jakarta Tomcat project but now used in many other Apache projects and extended by many developers.
Ant is a little but very handy tool that uses a build file written in XML (build.xml) as building instructions. For more information refer to "http://jakarta.apache.org/ant/".
Ok, let's build the code. First, make sure your current working directory is where the build.xml file is located. Then type
build (Windows)
./build.sh (Unix)
if everything is right and all the required packages are visible, this action will generate a file called "grok-${version}.jar" in the "./output" directory. Note, that if you do further development, compilation time is reduced since Ant is able to detect which files have changed an to recompile them at need. Also, you'll note that reusing a single JVM instance for each task, increases tremendously the performance of the whole build system, compared to other tools (i.e. make or shell scripts) where a new JVM is started for each task.
Build targets
The build system is not only responsible for compiling Grok into a jar file, but is also responsible for creating the HTML documentation in the form of javadocs.
These are the meaningful targets for this build file:
- package [default] -> creates ./output/grok-${version}.jar
- compile -> compiles the source code
- javadoc -> generates the API documentation in ./build/javadocs
- clean -> restores the distribution to its original and clean state
For example, to build the Java API documentation, type
build.sh javadoc
(Unix)
To learn the details of what each target does, read the build.xml file. It is quite understandable.
Bug Reports
Please report bugs at the bug section of the Grok sourceforge site:
https://sourceforge.net/tracker/?atid=104083&group_id=4083&func=browse
Also, you can report bugs by sending mail to Michael White at mwhite@cogsci.ed.ac.uk.
Special Note
This README and the directory structure and the build system for this project were taken directly from the JDOM project. Many thanks to Jason Hunter and Brett McLaughlin for creating a very elegant way of working with XML in Java. See www.jdom.org for more details.