NOTE: I suggest that you do not bookmark that link, because it is likely to change in the future. This page will host the correct link to wherever that document may be found in future. Therefore, bookmark this page instead.

In this document, $GS3SRCHOME is the full path to the top-level folder of your Greenstone 3. Wherever you see $GS3SRCHOME on this wiki page, it means you need to replace it with the full path to your top-level Greenstone 3 folder.

Eclipse project for Greenstone 3 developers

First create the project and rightclick on the project to add a new Package. The package should mimick the Greenstone 3 package structure:

org.greenstone.gsdl3

Get a copy of the source code into Eclipse

Rightclick Project > Import > General > File system > Next.
Give it the directory: $GS3SRCHOME/src/java/org/greenstone/gsdl3
Then "select all".
In the field "Into folder" <project-name>, browse for the newly created package structure.
Tick "create selected folders only".
Click Finish. And it will make copies of all the source code.

(General information: the following are some of the jar files that the compilation is dependent on. But as some of them are only generated upon executing the Ant building scripts, they won't all be available at this stage for us to add them to the Build Path of the project.)

If you want to compile and run just the GLI code:
Greenstone 3 code comes with the GLI code in its gli folder. However, sometimes you may not want to obtain and compile every part of Greenstone 3 and would just like to work on GLI.

Create the project and rightclick on it to add a new Package mimicking the GLI's gatherer package structure:

org.greenstone.gatherer

As above:

Rightclick Project > Import > General > File system > Next.
Give it the directory $GS3SRCHOME/gli/src/org/greenstone/gatherer
Then "select all".
In the field "Into folder" <project-name>, browse for the newly created package structure.
Tick "create selected folders only".
Click Finish. And it will make copies of all the source code.

In the left hand pane there should be a tab called Packages. (If it's not there, make it visible via Window > Show View > Package Explorer.)

The Packages tab will now show you the top-level folder called greenstone3 along with its repository location "main/trunk/greenstone3". You can expand the folder setup as usual by clicking on the triangles next to the folders. Click on the triangle next to the greenstone3 folder and you will see it contains the src folder and many another. The src folder is what contains the Greenstone 3 source code. (There's also the gli folder which contains its own src folder as well. We'll get back to that.)

Greenstone 3 code needs to be compiled using the Ant build file. See the section Compiling

Compiling

Compiling Greenstone 3 code from within Eclipse

This section is actually thoroughly unnecessary as you could do all this from the command-line as follows:

For those trying to avoid the command prompt, you can also set all this up so that it works from Eclipse.

To get ant prepare to work:

Do one of either:

Rightclick on the top-level greenstone3 folder in the Package View of the left-hand pane. Choose Build Path > Configure Build Path. Click on Builders. Press New. Click on Ant Build and click OK. This will create a new configuration.

Go to menu Run > External Tools > External Tools. Click on Ant Build in the left hand side and press New, or double-click on Ant Build. This will create a new configuration.

We're creating an Ant build configuration using the ant build file that Greenstone already comes with. Name the configuration ANT_PREPARE.

For "Build File", click on Browse Workspace. It should show the greenstone3 folder on the left-hand side, and the build.xml file on the right. Select the build.xml file and click OK.

For "Base Directory", click on Browse Workspace. It should start in the greenstone3 folder. Click OK. This is the folder it will be running in.

For Arguments, type

prepare

Click Apply. Click OK and click OK again.

Now you've created a build (compile) configuration and will run Greenstone's ant prepare. A dialog will pop up asking you whether the port number for the tomcat web server to listen on is OK. Click OK if 8080 is alright.

You can run the ant prepare build configuration whenever you want to from now on.

To get ant install to work:

Go to menu Run > External Tools > External Tools.

Choose Ant Build again and either double-click it or click the New button.

Name the configuration ANT_INSTALL this time.

The Build File and Base Directory are the same as for ant prepare.

For Arguments, type

install

Click Apply. Click OK and click OK again.

Now you've created an ant install configuration. The first time you do it, it will call Greenstone 3's ant install. You can repeat it whenever you want by going to Run > External Tools > ANT_INSTALL.

Hopefully you're seeing the pattern.

Let's create similar configurations for ANT_START which starts the Tomcat webserver for viewing Greenstone collections in the browser:

Duplicate the ANT_INSTALL configuration by clicking on the duplicate button just above the Ant Build on the left-hand side.

Rename the duplicate to ANT_START

Once again the Build File is still the same old build.xml in gsld and the Base Directory remains greenstone3.

Repeat the above steps to create configurations for ANT_STOP and ANT_RESTART to stop and restart Tomcat.
Executing these via Run > External Tools > ANT_<whatever> and then pointing the browser to where Tomcat is listening for Greenstone requests should produce the desired effect.

Compiling just Greenstone 3's GLI

GLI's src folder is checked out with greenstone3 (during ant prepare) and should be visible in Eclipse if you go to greenstone3/gli/src in the Package View on the left. (That is, if you had named your greenstone folder 'greenstone3'.)

Compiling and running gli from the x-term:
First go to the greenstone3 folder and set up the environment for Greenstone

Compiling from within Eclipse requires us to go through slightly different steps to what was described in Compiling Greenstone 3 code checked out from SVN in Eclipse when creating a configuration for makegli, because there is no ant file to build it. There is however a regular script, called makegli.sh for Linux and makegli.bat for Windows.

Run > External Tools > External Tools.

Choose Program on the left and click the New button above it or double-click Program to create a new configuration.

Name it MAKEGLI

For "Location", press Browse Workspace. Then, in the left-hand side of the dialog that opens up expand the folder to greenstone3 > gli. On the right-hand side select makegli.sh for Linux or makegli.bat if you're on Windows. (If gli is not visible in the folder-view on the left, cancel out of all the dialogs and in Eclipse's Package view on the left, rightclick on the greenstone3 project folder and click Refresh. Now gli should be there under greenstone3. Then open up the MAKEGLI configuration again and Browse Workspace for Location.)

This will make gli. And the configuration will be available whenever you want to use it again in future (Run > External Tools > MAKEGLI).

You can create a MAKEJAR configuration script that runs makejar.sh/makejar.bat in a similar manner.

Before we can run GLI, the Greenstone environment has to be set up. We have to source gs3-setup.sh from the command-line, as I can't find out how to do this from Eclipse:

$ cd $GS3SRCHOME
$ source gs3-setup.sh

Now that the environment is set up for GLI, we can create a configuration in Eclipse for running GLI and run it:
Repeat the steps above, but

call the configuration GLI

For "Location", choose gli.sh for Linux and gli.bat for Windows (instead of the makegli script).

In future, when you want to run GLI from Eclipse, you just go through Run > External Tools > GLI. (You might have to source gs3-setup.sh from the command prompt before that though.)

Debugging Greenstone with Eclipse (Stepping through code)

By setting up Greenstone3 code in Eclipse and then setting up Eclipse for remote debugging we are able to use the Eclipse
debugging perspective to step through the Java code as it executes. In order to do this the build.xml file must be edited
and a Remote Java Application Debugging Configuration must be set up.

Editing build.xml

In order to edit build.xml correctly:

Navigate to your $GS3SRCHOME directory and open build.xml in your usual text editor

The number 8383 can be any valid port number but will conflict with another application already using the same number, including
the Greenstone Server. So try choose a number well clear of anything. Whatever number you choose, remember it as it will be referenced
when you create the Remote Debugging Configuration in eclipse.

You should now have a section in the text file that looks very similar to the following:

Note: Having the remote.opts property included in the cataline.opts property seems to sometimes cause errors when Greenstone3 server starts and
a debugger is not attempting to connect to it. This is why the commented version of the catalina.opts property is present. Whenever you are not
debugging using eclipse you should switch the comment over to the version of catalina.opts that references remote.opts. Even if you where to find
that the server ran fine even with the remote.opts property being used you should still do this as according to
http://wiki.apache.org/tomcat/FAQ/Developing you will still get both security and performance issues.

Creating a Remote Java Application Debugging Configuration

To setup a Remote Debugging Configuration:

In Eclipse open up the Debug Configurations dialog. Run > Debug Configurations…

Change the Name New_Configuration to be something more appropriate such as greenstone3-debug

Browse in order to select your Greenstone3 project from your workspace

Leave Connection Type as Standard (Socket Attach)

Leave the Host as localhost

Change the Port number to be the number entered in the remote.opts property of the build.xml file (the example earlier used 8383)

Apply your changes and Close the Debug Configurations window

Finally place appropriate break points for what you are trying to achieve.

Running the Remote Debugger

Once you have made the required modifications to the build.xml file, have created the Remote Debugging Configuration
and set break points you are ready to start debugging:

Run ant start as described in section 2.1

Run the Remote Debugging Configuration. Run > Debug Configurations… > Double Click on the Configuration you made

You may be told that errors exist is the project. Ignore this and just continue.

When you do something with greenstone that causes a breakpoint to trigger then Eclipse will behave as it would with any other Java Application. Enjoy!

Note: After ant start is run with the remote.opts property being used it will poll for a maximum period of time waiting for Eclipse to attach.
If you are not fast enough in running the Remote Debug Configuration than you may miss the window of opportunity. Simply run ant stop and start
this step again.

Click on the down-arrow of the bug button at the top of the Eclipse window. When its options expand, choose Debug Configuration. Then double click Remote Java Application to create a new configuration for this.

Call it GS3tomcat, for the greenstone3 project (Eclipse .project and .classpath files can be downloaded from svn).

Leave the connection type at Standard (Socket Attach), and leave the host and port at their defaults (localhost, 8000), assuming no conflicts exist.

Close the Debug Configuration dialog.

2. There's a new target that's been added to GS3: debug-start-tomcat. This will start up tomcat's catalina for debugging in Eclipse, and its debugger will communicate with Eclipse on host:port localhost:8000 by default. (Again: change build.xml if there are any conflicts with the port and/or host).

Make sure tomcat is not already running

In an x-term run:

ant debug-start-tomcat

You can stop tomcat as usual with: ant stop.

3. Back in Eclipse:

click the down-arrow of the bug button at the top of the Eclipse window and choose your new GS3tomcat debug configuration to start debugging. This will connect Eclipse to the debugger of the running tomcat.

Add breakpoints anywhere in the code in the Java Perspective, by rightclicking at the very left margin of the line of code and selecting Toggle Breakpoint.

Perform whatever page activity that will trigger the line of code where you set your breakpoint

When the browser "freezes" go back to Eclipse

5. In Eclipse:

A dialog will now ask to open up the Debug Perspective.

Alternatively, go to menu Window > Open Perspective > Debug. Otherwise, in the top right of Eclipse there are the perspective shortcut buttons, so choose the Debug button to open the Debug perspective there and toggle back and forth at will between the Java Perspectives and Debug Perspective.

Once you're in the Debug Perspective, it will have stopped at a line of code where you put the breakpoint.

You can inspect values of variables in the Variables tab located in the pane in the top right quadrant.

You can continue from the breakpoint by clicking the Play button near the Debug tab of the Debug Perspective (located top center of the Debug Perspective in Eclipse).

6. Once you're done debugging:
Go back to your x-term and type:

ant stop

to stop tomcat.

Eclipse project for programs using Greenstone 3 code

OR: What you need to do to be able to import Greenstone 3 classes and packages into your code.

If you write a program that uses methods of Greenstone 3 classes, it may require one or more of the following:

various jar files to compile.

The Greenstone 3 jar files you may need are all located in

- $GS3SRCHOME/web/WEB-INF/lib/
- $GS3SRCHOME/lib/jni

You may also need the following two jar files:

- $GS3SRCHOME/web/xml-apis.jar
- $GS3SRCHOME/packages/tomcat/common/lib/servlet-api.jar (this is if you
ever need to include java's library for Servlets)

Note that run-time errors when certain libraries are missing can be less clear than compile-time errors. But if an error message says something about "wsdl", you'll know that you need to include the similarly named jar for wsdls.

paths to *.properties files. That is, the folders containing the required *.properties file

The *.properties files you'll be needing tend to all be located in $GS3SRCHOME/web/WEB-INF/classes

If executing your class causes log4j "appender" warnings, your executable class' run configuration needs to include the path to log4j.properties. If GS3 terminates "unable to open file global.properties", you need to specify the path to global.properties.

Java virtual machine (VM) arguments to specify the location of the gdbm library file (libgdbmjava.so for linux, or gdbmjava.dll for windows). These are located in $GS3SRCHOME/lib/jni. You specify this as

Eclipse Java Basics

Creating an Eclipse Java project

File > New Project > Java > Java Project.
Click Next.
Give your project a name.
Make sure the correct JRE is set (for example, Java 5/JDK 1.5* or Java 4/JDK 1.4.*).
Click Finish.
Choose Yes to open Java perspective. (You can open this
at any time through Window > Open Perspective > Java)

In the Package view on the left create an appropriate package structure for where your classes go into:

Right click on your project in the Package view on the left
Choose New > Package.
Type a directory structure where the path is all-lowercase and
separated by full stops '.' rather than directory slashes:
e.g. org.greenstone.myapplicationpackage.mypackage1
Click OK.

For each package you want to create, you can follow the above step.

Create a class in your package:

Rightclick on the package in which you want to create a new class in the Package view on the left.
Choose New > Class.
Give it a name.
* If it has a main function, tick the check box.
* If it inherits from something other than Java's Object, browse for it.

Build Path and Run Configurations: including jars, paths and files and specifying cmd-line or VM arguments

Configuring the Build Path (compile path)

To add jars into your Build Path configuration:

Rightclick on your class/package/project in the Package view on the left of the workspace.
Choose Build Path > Configure Build Path
Click on the Libraries tab
Click on Add External Jars
Browse to the location of the library jar files you need to include
Select all the jars in that folder that you want to add and click OK.
Click OK.

Repeat for other folders containing jar files you wish to include.

Setting up the Run configuration for an executable class

This specifies the command-line arguments, jar files and paths to folders and files that need to be included in the classpath for an executable Java class. You can have more than one executable class, and configure the run-time configuration for each.

First, rightclick on an executable class in the Package view on the left of the workspace.
Choose Run As > Run...
Decide if it is going to run as a Java Applet or Java Application and double click on one of these.

Now that it's created a basic run-time configuration for you, you need to specify any command-line arguments and any jar files, other files or folders to include in the run-time classpath for your Java executable.

So, in the same Run configuration dialog,

Use the Arguments tab for specifying arguments to the command-line and to Java's Virtual Machine (VM)

The VM arguments field is for specifying library files like *.so (on Linux), *.dll (on Windows).

Use the Classpath tab to add jars, files and folders into your run-tume classpath:

Click the Classpath tab in the Run configuration dialog
Click on your project folder name under User Entries
You can now:
* Click the Add External Jars button and browse to the jars you want to add. Click OK.
* Click Advanced > Add External Folder button to browse to a folder path containing
the *.properties files you want to include. Click OK.
Click Run to execute your program now that your run configuration is set up.

Using the Subclipse plugin in Eclipse to work with SVN

Subversion (SVN) is a version control system that lets you manage changes to your source code. An external code repository stores the source code, allowing you to download the latest version onto your local harddrive. You can make improvements and, if you are authorised to do so, you can upload these changes back onto the repository. Groups working together on the same source code can choose to update only the parts of their local copy of code that is different from what's in the repository. In this way everyone has up-to-date code.

OR if you chose New Local Site instead, then extract the zip file into a folder. (In the rest of this wiki page, I will refer to the full path to this folder as $SUBCLIPSE. Therefore remember to replace all occurrences of $SUBCLIPSE that you encounter in this wiki page with the full path to your subclipse extraction folder.) Then, back in the Eclipse window, in the New Local Site dialog, type in

Name: Subclipse 1.2.x (Eclipse 3.2+)
URL: $SUBCLIPSE/site-1.2.4

Click OK.

Select it and click Next.

If it complains about an optional package requiring another code resource (Mylyn), expand Subclipse in the dialog and uncheck the optional package of Integrations containing Mylyn. (This optional item won't get installed.)

Creating an Eclipse project of some source code from SVN and compiling it

This section will hopefully help beginners in using Subclipse to import any source code from an SVN repository into Eclipse.

We'll try an example with the Greenstone GLI code repository. To be able to run GLI you actually need more than the source code (you need the script that sets the GS3SRCHOME environment variable, for instance), but we are focussing here on the <i>general case</i>: how to download Java source code from some SVN code repository and get it to compile through Eclipse.

Rightclick on the src folder in the SVN folder structure on the left and choose checkout.

Tick "Checkout as a project configured using New Project Wizard"

Choose Java Project.

Set the project name to something sensible, for instance GLIfromSVNSource.

Click Next, click Finish. It will now checkout the code in the src folder from the repository.

If you go to Window > Open Perspective > Other > Java, you will see it has created the new project with the correct package structure.

2. It will now complain that certain import statements can't be resolved by marking various packages and classes with red crosses in the left-hand pane's Package view. To resolve this, we need to checkout and include the jars in the lib folder:

Untick "Use default workspace location". Instead move it to the same level as your src folder (i.e. into the Project folder I named GLIfromSVNSource). This will keep lib at the same level as src which matches how it is in the SVN repository.

Go back to Window > Open Perspective > Other > Java

Rightclick on your Source project name ('GLIfromSVNSource'), and configure the Build path to include the jars in the lib folder just downloaded:

Build Path > configure build path > Add External Jars.

Browse to the folder …/GLIfromSVNSource/lib and add the two jar files in there.

Subclipse help

So go to Eclipse's Help and you'll see that SVN is one of the options in the left-hand pane of help.

The most useful help sections include:

Getting Started (for checking out code from SVN the first time)

Tasks (for committing code, resolving conflicts, etc.)

Alternative method for setting up Eclipse for use in Greenstone 3

Method 1

Loading the gs3 eclipse project file into Eclipse

An Eclipse project file is part of the GS3 svn checkout. It consists of a .project file, with associated .classpath file.
Once you've checked out a GS3 from SVN and compiled it up with an ant prepare command followed by an ant install command, open up Eclipse.

In Eclipse, create a new workspace, and import this project file

To achieve the same from scratch:

Creating a Greenstone project that can be reused with other fresh Greenstone checkouts from SVN. The src/java and gli/src folders, which contain java code, will be set up for automatic compilation in Eclipse.
These instructions are from coderanch
Use File > Import and select General > Existing Projects into Workspace. Click next and then browse to the GS3 top level directory as this contains the eclipse project file.

If you have any build errors, it means it's probably missing some newer library jar files. In that case, update the .classpath file.

Build Greenstone before opening Eclipse

In an x-term:

checkout GS3 from SVN:

svn co http://svn.greenstone.org/main/trunk/greenstone3 greenstone3

run ant (generates build.properties from build.props.in)

run ant prepare

If on a linux that requires it, download the gnome-lib-minimal tar.gz for your architecture, and extract this into greenstone3/ext folder

run source devel.bash in greenstone3/ext/gnome-lib-minimal folder

run ant install in the top-level greenstone3 folder

run makegli in gli folder

run makejar in gli folder

Setting up Eclipse

Open Eclipse and go to Window > Open Perspective > Java (Browsing)

Rightclick in workspace's left pane > New > Java Project

In the New Java Project dialog that opens:

Untick "use default location", and browse to your GS3 folder and double click. The project will probably be named greenstone3 or something.

Click Next and agree when it asks to remove all generated resources from the old location in gs3/bin

In the Source tab of the dialog screen that appears, control/shift select all folders marked with the package icon except for src/java and gli/src. Rightclick and choose Remove from Build Path. (If at any time any folder or subfolder structure needs to be added back in as a java source folder in the compile/build path, go back to the workspace left pane, select that folder substructure, rightclick it and choose Build Path > Use as Source Folder)

In the Libraries tab, choose to remove both occurrences of LuceneWrapper.jar (since it's the LuceneWrapper3.jar files – especially in gs2build/common-src – that are the important ones)

Press the Add Jars button, browse to open greenstone3/gli/lib folder, select the 3 jars there (apache.jar, qfslib.jar, rsyntaxtextarea.jar). If project jars are not available for any reason, press the External Jars button, browse to gli's lib folder, and add in the 3 jars there (apache.jar, qfslib.jar, rsyntaxtextarea.jar).

Go to Project > Build All to find any compilation errors (there shouldn't be any)

This will reveal the .project and .classpath files that Eclipse generated and placed in your greenstone 3 installation

the .classpath file is the important one: it contains the paths to the source folders that need to be compiled for the build, and the jar files in your build path. Note how all the file paths are relative.

You can remove extraneous jar files from here as well, and resave the .classpath file so that the next time you run Eclipse, it will load the updated build path contents specified in .classpath.

Method 2

This method is much simpler than the first method described above but is slightly more restrictive. Rather than needing to use Subclipse to check out Greenstone inside Eclipse, this method allows you to use a pre-existing Greenstone SVN installation.

Firstly you will need to create a new empty project in Eclipse by clicking File > New > Java Project.

Give it a sensible name and then click Finish.

Open up the project in the Package Explorer and right-click on the 'src' folder and choose Import.

In the next dialog choose General > File System.

Click the top Browse button, find and click on your [GREENSTONE3 DIRECTORY]/src/java folder and press OK.

Click the checkbox next to the 'java' folder so that it is checked.

Click the Filter Types button and check the *.java option and press OK.

Click the Advanced button and check the 'Create links in workspace' checkbox (and make sure the two checkboxes below it are also checked).

Click Finish.

In order fix all the errors and allow the project to build correctly you will also need to complete the following steps.

Right-click on the project folder and choose Build Path > Configure Build Path. Alternatively, you may need to right click on the Project folder and choose Properties > Java Build Path.

On the Libraries tab use the 'Add External JARs' button to add the following .jar files:

You can now edit the Java files and make use of the advanced IDE features as you would normally be able to. This approach does not work very well when you need to change the name of a file or add a new file. In these cases you will probably want to make the modifications directly on the file system and then re-import the specific files affected.

See Useful Eclipse Shortcuts which also links to the autoformatting file we hope to use as a standard for Greenstone Java code.

Open "Run" then "Run Configurations...", and select your configuration. Click on the last tab, "Common". Under "Save As", choose "Shared File" instead of "Local File".
This dialog is a little confusing. The line next to "Shared File" can only be a path, not a file name - and it defaults to the root path of the current project.
Once you hit "Apply", a file named the [Run Configuration Name] + ".launch" is created within that folder.
E.g., this results in a "/JavaTest/TransformingLibrary.launch" file. This is something that can be committed to version control.