Greenstone Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Eclipse and Greenstone 3 ======

Greenstone 3 can be run as a project inside the [www.eclipse.org Eclipse IDE]. 

**Note: not available for Greenstone 2.**

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.


=====Setting up Eclipse for use in Greenstone3=====

The following methods can be used if you already have an SVN client on your computer. If you don't have SVN, you can instead use the Eclipse plugin Subclipse to checkout Greenstone.

====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 [[http://www.coderanch.com/t/419556/vc/Open-existing-project-Eclipse|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: 
<code>svn co http://svn.greenstone.org/main/trunk/greenstone3 greenstone3</code>
  * run //ant// (generates build.properties from build.props.in)
  * run //ant prepare//
  * If on a linux that requires it, download the [[http://trac.greenstone.org/browser/gs2-extensions/gnome-lib/trunk/|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.

====Method 2==== 

  * 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 ''$GS3SRCHOME/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:
<code>
[ANT DIRECTORY]/lib/ant.jar
$GS3SRCHOME/lib/java/svnkit.jar
$GS3SRCHOME/lib/jni/mg.jar
$GS3SRCHOME/lib/jni/mgpp.jar
$GS3SRCHOME/lib/jni/javagdbm.jar
$GS3SRCHOME/packages/tomcat/lib/servlet-api.jar
$GS3SRCHOME/web/WEB-INF/lib/axis.jar
$GS3SRCHOME/web/WEB-INF/lib/commons-codec-XXX.jar
$GS3SRCHOME/web/WEB-INF/lib/commons-fileupload-XXX.jar
$GS3SRCHOME/web/WEB-INF/lib/commons-langXXX.jar
$GS3SRCHOME/web/WEB-INF/lib/DLservices.jar
$GS3SRCHOME/web/WEB-INF/lib/fedoraGS3.jar
$GS3SRCHOME/web/WEB-INF/lib/gson-1.7.1.jar
$GS3SRCHOME/web/WEB-INF/lib/jaxrpc.jar
$GS3SRCHOME/web/WEB-INF/lib/jdbm.jar
$GS3SRCHOME/web/WEB-INF/lib/JSON-java.jar
$GS3SRCHOME/web/WEB-INF/lib/junit.jar
$GS3SRCHOME/web/WEB-INF/lib/log4j-1.2.8.jar
$GS3SRCHOME/web/WEB-INF/lib/LuceneWrapper.jar (or LuceneWrapper3.jar, whichever is present)
$GS3SRCHOME/web/WEB-INF/lib/mail.jar
$GS3SRCHOME/web/WEB-INF/lib/recaptcha4j-XXX.jar
$GS3SRCHOME/web/WEB-INF/lib/serializer.jar
$GS3SRCHOME/web/WEB-INF/lib/xalan.jar
$GS3SRCHOME/web/WEB-INF/lib/xercesImpl.jar
$GS3SRCHOME/web/WEB-INF/lib/xml-apis.jar
$GS3SRCHOME/web/WEB-INF/lib/xsltc.jar
</code>
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 [[en:developer:Eclipse Shortcuts|Eclipse shortcuts]] which also links to the autoformatting file we hope to use as a standard for Greenstone Java code.


===== Creating Run configurations in Eclipse =====
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 [[http://stackoverflow.com/questions/8625060/store-run-configuration-with-project-in-eclipse|Store run configuration with project in Eclipse]]:

<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.</code>

===== Additional Resources =====
  * There are some [[en:developer:eclipse_shortcuts|useful Eclipse shortcuts]] available on the wiki. 
  * 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 [[http://www.cs.waikato.ac.nz/~ak19/eclipse_project_of_GS3_from_SVN.html|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.