Using Eclipse with Greenstone3

Most users may find the Alternative method for setting up Eclipse for use in Greenstone 3 easier than the method below and we recommend trying this first.

For a walkthrough with screen shots of the steps involved in installing Greenstone 3 by using the Eclipse plugin Subclipse (for checking out Greenstone 3 code from SVN), see Eclipse project of Greenstone 3 code using Subclipse.

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.

See the section Eclipse Java Basics if you want to learn how to

• Create an Eclipse Java project; or a Java package or class in it (Creating an Eclipse Java project)
• Configure the Build (compile) Path or specify the Run Configuration (Build Path and Run Configurations: including jars, paths and files and specifying cmd-line or VM arguments)

This is for those who will be developing Greenstone 3 source code.

Greenstone 3 code:

• 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.

• Greenstone 3 needs to be compiled with the special Ant build file. For instructions on how to do this, see the section Compiling Greenstone 3 code from within Eclipse.

(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.)

- $GS3SRCHOME/web/WEB-INF/lib


- $GS3SRCHOME/lib/jni/


- Also add $GS3SRCHOME/web/xml-apis.jar and $GS3SRCHOME/packages/tomcat/common/lib/servlet-api.jar

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.

• Add to the Build Path of the project the two jar files in

$GS3SRCHOME/gli/lib

• GLI can be executed from the command prompt (or you can also do this from Eclipse if you need to). See the section Compiling just Greenstone 3's GLI.

• Details on installation of the Subclipse plugin are at Installation
• The general case of getting source code via SVN into Eclipse using this plugin are explained in Creating an Eclipse project of some source code from SVN and compiling it.

This section deals particularly with Greenstone (3) source code.

• Open up Eclipse in a new Workspace. Let's call the workspace GS3, for Greenstone 3.
• Now that you have Subclipse installed (Installation), go to Window > Open Perspective > (Other >) SVN Repository Exploring.
• This should have opened up a pane on the left-hand side, wherein the SVN Repository tab will be active. Rightclick in the left-hand pane and choose New > Repository Location.
• Paste the repository location for Greenstone 3 code and related items, which is:

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

• It will have added the repository link in the left-hand pane. Click on this item and right-click on it.
• Choose checkout and in the dialog that opens tick "Check out as a project in the workspace".
• For Project Name, type in greenstone3 (or you could leave it to be called "trunk" if you wish). Click Next. This will turn greenstone3 into an Eclipse project.
• In the next dialog step, it asks where in the workspace you want to put this. Let's put the greenstone3 project directly into the workspace GS3, so accept what it offers. Click Finish.
• Just wait while it checks out all contents of the repository location we gave it and putting it into the project folder greenstone3.
• We're going to the Java project view. Therefore go to Window > Open Perspective > (Other >) Java.
• 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

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

$ cd $GS3SRCHOME (which is /full/path/to/your/Eclipse/workspace/GS3/greenstone3)
$ ant prepare
$ ant install

To startup, stop and restart the Tomcat web server:

ant start
ant stop
ant restart

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:

• Go to the Run > External Tools > External Tools and choose Ant Build again.
• 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.

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

$ cd $GS3SRCHOME
$ source gs3-setup.sh

Now go to gli and compile then run it:

$ cd gli
$ ./makegli.sh
$ ./gli.sh

Finally, if you want to update the pre-compiled jar file for gli, containing your updated code, you'd type:

$ ./makejar.sh

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.)
• For "Base directory", press Browse Workspace and browse to greenstone3 > gli.
• Nothing for "Arguments".
• Click Apply, OK, OK.

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.)

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.

In order to edit build.xml correctly:

• Navigate to your $GS3SRCHOME directory and open build.xml in your usual text editor
• Find the following line (a good way is to search for -Xmx):

<property name="catalina.opts" value="-Djava.util.prefs.syncInterval=2000000 -DGSDL3HOME=$GSDL3HOME -DGSDLOS=$GSDLOS -DPATH=$PATH -Xmx400M "/>

• Now duplicate that line and comment out one of the duplicates so that it now looks like the following:

<!-- 
<property name="catalina.opts" value="-Djava.util.prefs.syncInterval=2000000 -DGSDL3HOME=$GSDL3HOME 
	-DGSDLOS=$GSDLOS -DPATH=$PATH -Xmx400M "/>
-->
<property name="catalina.opts" value="-Djava.util.prefs.syncInterval=2000000 -DGSDL3HOME=$GSDL3HOME -DGSDLOS=$GSDLOS -DPATH=$PATH -Xmx400M "/>

• Next, edit the uncommented line to include a reference to a property remote.opts (we are about to make this) so that it looks like the following:

<property name="catalina.opts" value="-Djava.util.prefs.syncInterval=2000000 -DGSDL3HOME=$GSDL3HOME 
	-DGSDLOS=$GSDLOS -DPATH=$PATH -Xmx400M ${remote.opts} "/>

• To finish up add the following line above both occurrences of the catalina.opts property (the line we have been editing)

<property name="remote.opts" value="-Xdebug -Xrunjdwp:transport=dt_socket,address=8383,server=y,suspend=n"/>

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:

<property name="remote.opts" value="-Xdebug -Xrunjdwp:transport=dt_socket,address=8383,server=y,suspend=n"/>
<!-- 
<property name="catalina.opts" value="-Djava.util.prefs.syncInterval=2000000 -DGSDL3HOME=$GSDL3HOME 
	-DGSDLOS=$GSDLOS -DPATH=$PATH -Xmx400M "/>
-->
<property name="catalina.opts" value="-Djava.util.prefs.syncInterval=2000000 -DGSDL3HOME=$GSDL3HOME 
	-DGSDLOS=$GSDLOS -DPATH=$PATH -Xmx400M ${remote.opts} "/>

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.

To setup a Remote Debugging Configuration:

• In Eclipse open up the Debug Configurations dialog. Run > Debug Configurations…
• Create a Remote Java Application Configuration by double clicking on the Remote Java Application button.
• Edit the Details as follows:
  • 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.

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.

Instructions and modifications to build.xml based on Debugging a servlet with tomcat and Eclipse tutorial and the Stackoverflow question What are the Steps for Debugging Java Web Application?

1. Set up Eclipse by creating a new configuration:

• 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.

4. In a browser:

• Visit your Greenstone page, usually located somewhere below http://localhost:8383/greenstone3/library
• 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.

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)

Add any jars the compiler complains about into your Build Path configuration, as described in Build Path and Run Configurations: including jars, paths and files and specifying cmd-line or VM arguments. Not all of them may be necessary. The most important one–containing the Greenstone 3 specific source code–is gsdl3.jar located in $GS3SRCHOME/web/WEB-INF/lib/

• various jar files to execute.

The location of the jar files is the same as listed for compiling above. Not all of the jars may be necessary. Add the jar files needed to execute your program to the Run configuration of your executable class(es), as described in Build Path and Run Configurations: including jars, paths and files and specifying cmd-line or VM arguments

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

You need to specify the folder in which they are located, not the actual files themselves. See Build Path and Run Configurations: including jars, paths and files and specifying cmd-line or VM arguments for instructions on how to do this.

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

-Djava.library.path=/full/path/to/GS3SRCHOME/lib/jni

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

• Open Eclipse and give a name for your new workspace.

• Create a new 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.

• 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.

• 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.

• Subclipse is a plugin for Eclipse that provides SVN support.

It lets you download code from a code repository, commit changes back into the repository and update local code to reflect changes in the repository.

Detailed installation instructions

Installation in brief for those behind a firewall:

• Open Eclipse
• Go to Help > Software Updates > Find and Install > Search for new features to install
• Press Next
• If you're using a proxy, you can't download remotely, so you'll need to
  • click either New Archived Site OR New Local Site.
  • Download the latest executable zip here, eg. site-1.2.4.zip. (The executable zip you need to download might depend on the version of your Eclipse. See that download link for further details.)
  • IF you pressed New Archived Site, then, in the dialog that appears, you give it a name and browse to the full path of your subclipse zip-file. For example:

Name: Subclipse 1.2.x (Eclipse 3.2+)
URL: /full/path/to/site-1.2.4.zip

• 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.)
• Click finish and it should be installed.
• Restart Eclipse for it to take effect.

See also Eclipse project of Greenstone 3 code using Subclipse for a walkthrough with images.

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.

The particulars of getting Greenstone 3 (including GLI) source code via SVN into Eclipse and getting it all to compile and run is explained in Creating an Eclipse project of Greenstone 3 source code from SVN using Subclipse and Compiling

1. With Eclipse open in a new workspace:

• Go to Window > Open Perspective > Other > SVN Repository Exploring
• Rightclick in the left hand pane (SVN Repository) and choose New > Repository Location
• Paste http://svn.greenstone.org/gli/trunk for GLI code or http://svn.greenstone.org/greenstone3/trunk for Greenstone 3 code

In our example here, we'll go with the first. But the process will be similar if you checked out Greenstone 3 code.

• Rightclick on the newly added location and choose Checkout
• If you had chosen the GLI trunk repository (http://svn.greenstone.org/gli/trunk), then inside the folder structure that's created is src/org/greenstone/gatherer
• Now, to create an Eclipse Project using this:
  • 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:

• Go back to (Window > Open Perspective > Other >) SVN Repository Exploring Perspective
  • Rightclick on folder lib
  • Choose checkout > "Checkout as a project in the workspace"
  • Accept the project name lib
  • 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.
  • Click OK. Click OK again.

See also Eclipse project of Greenstone 3 code using Subclipse for a walkthrough with images.

Package errors once checked out a SVN trunk?

This section contributed by bjn8:

• Go to the project properties. This can be done by right-clicking the project in the Package Explorer and selecting the "Properties" menu item (the last item listed in the context menu).
• Select the "Java Build Path" item listed on the left.
• Select the "Source" tab.
• Click on "Add Folder".
• Check the folder where your source resides. For example if all your source is in a folder named "src" check the "src" folder. (Hmmm that sounded a bit obvious!).
• Click OK.
• Click OK.
• Hopefully eclipse builds your project correctly.

Help on Subclipse is available from within Eclipse itself, as stated at the Subclipse documentation page

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.)

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 Finish to close the dialog

• The GLI source code requires further jar files. Back in the workspace's left pane, rightclick on the greenstone3 project > Build Path > Configure Build Path > Libraries tab.
• 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)
• Make sure Project > Build Automatically is checked (else you'll have to keep going to Project > Build All)
• Exit Eclipse

In an x-term

• run ls -la on your toplevel greenstone3 folder

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.

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:
  • [ANT DIRECTORY]/lib/ant.jar
  • [GREENSTONE3 DIRECTORY]/lib/java/svnkit.jar
  • [GREENSTONE3 DIRECTORY]/lib/jni/mg.jar
  • [GREENSTONE3 DIRECTORY]/lib/jni/mgpp.jar
  • [GREENSTONE3 DIRECTORY]/lib/jni/javagdbm.jar
  • [GREENSTONE3 DIRECTORY]/packages/tomcat/lib/servlet-api.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/axis.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/commons-codec-XXX.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/commons-fileupload-XXX.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/commons-langXXX.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/DLservices.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/fedoraGS3.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/gson-1.7.1.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/jaxrpc.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/jdbm.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/JSON-java.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/junit.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/log4j-1.2.8.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/LuceneWrapper.jar (or LuceneWrapper3.jar, whichever is present)
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/mail.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/recaptcha4j-XXX.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/serializer.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/xalan.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/xercesImpl.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/xml-apis.jar
  • [GREENSTONE3 DIRECTORY]/web/WEB-INF/lib/xsltc.jar

Press OK.

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.

1. Open the GS3 .project Eclipse project file in Eclipse.

2. In the Java perspective view, navigate down to executable java file and right-click on it. E.g. rightclick on the TransformingLibrary.java in src/java/org/greenstone/gsdl3 http://stackoverflow.com/questions/8625060/store-run-configuration-with-project-in-eclipse

3. Choose Run As > Run Configurations.

4. Set up the env variables and arguments to the executable.

5. Store the Run configuration with the project in Eclipse, if you need to commit the launch configuration to SVN. The instructions as explained at Store run configuration with project in Eclipse:

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.