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.


===== General notes on using Eclipse features =====

=== Swapping between Eclipse's Java and Java Browsing perspectives ===
The instructions on this page will refer to Eclipse's Perspectives for ''Java'' and ''Java Browsing''.

You can swap between Eclipse's Perspective for Java (coding) and Java Browsing by going to:
  * **Windows > Perspective > Open Perspective > Java.** In this perspective, you can see the Package Explorer tab with tree view of the source code under src/java and gli/src. The Problems tab shows any warnings or errors in the code.
  * **Windows > Perspective > Open Perspective > Java Browsing.** In this perspective, you can see the Project tab as well as Packages, Members and Types tab.

=== To Delete a Project ===
You can delete an Eclipse Project from the Java Browsing perspective. In the Projects tab, rightclick on the project to be deleted and choose Delete. Beware to only additionally choose to delete the contents on the disk too (and not just the Eclipse project) if you really mean to do that.

=====Setting up Eclipse for use in Greenstone3=====
The methods in the sections below 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=====

====A. 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. 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. Once selected, click Finish. (These instructions are from [[http://www.coderanch.com/t/419556/vc/Open-existing-project-Eclipse|coderanch]].)

Check for build errors in Eclipse's **Java perspective**. If you have any build errors, it means it's probably missing some newer library jar files. In that case, update the .classpath file in GS3's top level directory.

The ''src/java'', ''gli/src'' and ''ext/solr/src/java'' folders, which contain java code, will be set up for automatic compilation in Eclipse.


====B. To achieve the same from scratch ====

Creating an Eclipse project for Greenstone that can be reused with other fresh Greenstone checkouts from SVN.

===1. 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

===2. 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 greenstone3/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**, **gli/src** and **ext/solr/src/java**. 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)
    * Still in the Source tab, at the bottom set the ''Default output folder'' to the $GS3SRCHOME/web/WEB-INF/classes folder.
    * In the Libraries tab, remove all jar files, so that only the "JRE System Library" remains. **Be patient, this step can take quite some time.** <del>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). Also remove any occurrence of LuceneWrapper3.jar, since we've moved to using LuceneWrapper4.jar.</del>
    * Press Add External Jars and **first** add in the following jar files from web/WEB-INF/lib (order matters, else you get a compile error that DigestUtils's sha hex function isn't found): <code>
$GS3SRCHOME/web/WEB-INF/lib/ant.jar (or [ANT DIRECTORY]/lib/ant.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-io-2.1.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/jna.jar
$GS3SRCHOME/web/WEB-INF/lib/jna-platform.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/LuceneWrapper4.jar
$GS3SRCHOME/web/WEB-INF/lib/mailapi-1.5.6.jar
$GS3SRCHOME/web/WEB-INF/lib/recaptcha4j-XXX.jar
$GS3SRCHOME/web/WEB-INF/lib/serializer.jar
$GS3SRCHOME/web/WEB-INF/lib/slf4j-api-1.6.6.jar   *
$GS3SRCHOME/web/WEB-INF/lib/slf4j-jdk14-1.6.6.jar *
$GS3SRCHOME/web/WEB-INF/lib/solr-core-4.7.2.jar   *
$GS3SRCHOME/web/WEB-INF/lib/solr-solrj-4.7.2.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>\\ *The 2 slf4j*.jar files and 2 solr*.jar files are for compiling what's in ext/solr/src/java.\\  Next, also add in:\\ <code>
$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
</code>
    * 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 $GS3SRCHOME/gli/lib folder, select the 3 jars **''apache.jar'', ''qfslib.jar'', ''rsyntaxtextarea.jar''** and add them too. So you additionally have:<code>
$GS3SRCHOME/gli/lib/apache.jar
$GS3SRCHOME/gli/lib/qfslib.jar
$GS3SRCHOME/gli/lib/rsyntaxtextarea.jar
</code>\\ 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).
    * Press Finish to close the dialog
  * 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
  * Use a text editor to open the Eclipse ''.classpath'' file created by Eclipse and remove all occurrences to the full path to the GS3, so that only paths relative to the GS3 toplevel folder remain. For example, all instances of /path/to/GS3/web/WEB-INF/lib would become web/WEB-INF/lib. Save the ''.classpath'' file.
  * Open the .project Eclipse file in a text editor and ensure the project is called ''greenstone3''.

**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**.
  - Go to Window > Perspective > Open Perspective > Java. This is the Java editing view.
  - Open up the Eclipse's project in the **Package Explorer** and **right-click on the ''src'' folder** and then choose **Import**.
  - In the next dialog choose ''General -> File System''. Press Next.
  - 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**.

  * **Warning:** Additionally adding the gli source code in the way described next will result in "Access restriction" compilation errors that I've not resolved yet. I've only successfully worked with GS3's src/java folder in Eclipse using Method 2.\\ If you want to edit and compile GLI and/or the solr extension code, add ''$GS3SRCHOME/gli/src'' and ''$GS3SRCHOME/ext/solr/src/java'' as src folders too, then right-click on the Eclipse project folder in the Package Explorer > New > Source Folder. Give it a name like ''glisrc'' or ''solrsrc''.\\ Next, rightclick on this new source folder (e.g. ''glisrc'') and then choose Import. Then repeat steps 5-10 for each new code src folder to add.\\ If you forget to create a new source folder then beware that in Eclipse's package view, all the code for gli/src and ext/solr/src/java get merged into the org.greenstone.* tree of GS3's src/java if they're in the ''org.greenstone'' package.

  * Go to Project > Clean to clean the compile products. Then set Project > Build Automatically. In order fix all the compile errors and allow the project to build correctly, and in an output folder of your choosing, you will also need to complete the following steps.
  * Right-click on the project folder and choose Build Path > Configure Build Path. Alternatively, right click on the Project folder and choose Properties > Java Build Path.
  * Go to the Source tab and at the bottom set the ''Default output folder'' to ''$GS3SRCHOME/web/WEB-INF/classes''.
  * On the Libraries tab use the 'Add External JARs' button to add the following .jar files:
<code>
$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
</code>
Similarly, also add all the jar files in:
<code>
$GS3SRCHOME/web/WEB-INF/lib/ant.jar (or [ANT DIRECTORY]/lib/ant.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-io-2.1.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/jna.jar
$GS3SRCHOME/web/WEB-INF/lib/jna-platform.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/LuceneWrapper4.jar
$GS3SRCHOME/web/WEB-INF/lib/mailapi-1.5.6.jar
$GS3SRCHOME/web/WEB-INF/lib/recaptcha4j-XXX.jar
$GS3SRCHOME/web/WEB-INF/lib/serializer.jar
$GS3SRCHOME/web/WEB-INF/lib/slf4j-api-1.6.6.jar   *
$GS3SRCHOME/web/WEB-INF/lib/slf4j-jdk14-1.6.6.jar *
$GS3SRCHOME/web/WEB-INF/lib/solr-core-4.7.2.jar   *
$GS3SRCHOME/web/WEB-INF/lib/solr-solrj-4.7.2.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>
* If ''ext/solr/src/java'' was one of the source folders.

And if you gli/src is one of the source folders, then also add:
<code>
$GS3SRCHOME/gli/lib/apache.jar
$GS3SRCHOME/gli/lib/qfslib.jar
$GS3SRCHOME/gli/lib/rsyntaxtextarea.jar
</code>
Press OK.

Note that **if compile time errors remain**, or errors appear during runtime, you can add try adding any further (or even all) the jars in:
<code>
$GS3SRCHOME/web/WEB-INF/lib
</code>

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.