Setting Up Eclipse for JSword and BibleDesktop

JSword and Bible Desktop are being actively developed in Eclipse. While this is not an endorsement of Eclipse, you will find project files for Eclipse that will speed your ability to develop JSword. You may use any other means of developing JSword, but we may not be able to provide guidance.

This document should help you set up Eclipse so you can help develop JSword and BibleDesktop. If you find it incomplete, please let us know or once you have Eclipse set up, make the changes and send us a patch.

Obtain and install Sun's Java 1.5 (aka Java 5)

NOTE:BibleDesktop looks best in Java 5 or later and for right-to-left languages it is a necessity. If you are not changing java code, but only working on translations, you only need to install Java 1.5.0 SDK or later.

We recommend using the most recent point release which at the time of this writing was JDK 5.0 Update 12. You can get Sun's Java 5 here. Again, you can find instructions on installing Sun's Java for Linux under Installing Java for Linux.

If possible set an environment variable, JAVA_HOME to point to the directory you just created. This might be something like C:\Java\j2sdk1.5.0_b22.

Obtain and install Eclipse 3.3

Any version of Eclipse 3.3 or higher will work well. The screenshots that are provided are from 3.3, Linux, GTK version, running under the Gnome desktop.

You can get Eclipse for Windows, Linux and Mac from here: http://www.eclipse.org/downloads. Some Linux distributions provide Eclipse, but they are generally a release or two behind and often lack some functionality. For this reason only, they are not recommended. The download will be about 80-140M, so it is best to have a broadband connection. The page will provide you with several choices, but the Eclipse IDE for Java Developers is sufficient. The screenshots below are from the Linux GTK version.

Installing Eclipse

If you are installing Eclipse for your own use, you can install it to any directory for which you have permissions. Otherwise you will need Linux root or Windows' administrator permissions. Do not install it to a directory containing an existing eclipse directory. It will create the Eclipse installation in that directory. For Windows, just unzip it to the c:\java directory. For Linux, in the directory of your choosing, run gtar zxvf eclipse-java-europa-linux-gtk.tar.gz.

On Windows, you will probably will want to create a shortcut for Eclipse. Assuming that you have installed Eclipse at c:\Eclipse, use the following as the target:
c:\eclipse\eclipse.exe -vm %JAVA_HOME%\bin\javaw -vmargs -Xmx1024M

Install Subclipse, a Subversion client

Follow the instructions on the Subclipse website.

Setting up the JSword projects in Eclipse

Setup an Eclipse Workspace

When you start up Eclipse, you can choose which workspace to work in or you can create a new one. Eclipse will provide a default workspace in your home directory of workspace. [Image] Since I develop more than one project, I want to keep each in different workspaces. For JSword, I use ~/eclipse/jsword. [Image] Another project would be ~/eclipse/flashcards.

Welcome to Eclipse

When you first enter Eclipse you will be presented with an opportunity to learn about Eclipse. You can get back to this view at anytime by choosing Welcome from the Help menu.

Click on the Workbench button to use Eclipse. [Image]

Connect to JSword's SVN repository

Click on the Open Perspective button. [Image] And then pick the Other menu choice. [Image] This will provide you with a dialog box of various perspectives. Choose the SVN Repository Exploring perspective. [Image]

Setting up preferences in Eclipse

In order to speed development we request that you conform to the style of coding that is currently used. Everyone has their own favorite way of doing things, so we had to establish one style standard. And we try to maintain these. You can read more about these standards here. These are loaded with each project.

Letting Eclipse Know Where Java is Installed

Under Windows -> Preferences (on the Mac it is Eclipse -> Preferences), expand Java and then select Installed JRE. [Image] Here click on the Add button and add an entry labelled jdk-1.5.0 [Image]. Under Linux, installed according to the instructions above, Java 1.5.0 would have a path something like /usr/lib/jvm/java-1.5.0-sun-1.5.0.12. You can use the search button to find them and re-label them afterwards. Make sure that you have assertions turned on for development by adding -ea for the Default VM Args. When you are all done it should look like this. [Image]

Working under the Java Perspective

Eclipse provides several perspectives under which you can develop code. My personal rut is the Java Perspective. This can be added in the same manner that the SVN Repository Exploring Perspective was added.

Finding code is relatively easy. All source is under src. Under there you will find main, with all of the main code and test with all of the test code. Under main we currently only have java code, but we have structured this to allow for other kind of code. [Image]

Initial testing

Initial testing is nothing more than running the application and seeing it work as expected. This has been made easy, if you have named the Installed JREs as instructed above. In the Java Perspective, click on the triangle on the right of the Run button. The first time you do this, it will not be a very useful list. From that list, pick Open Run Dialog [Image]. In the Run dialog, expand Java Applications and then click on Run [Image]. You can add other launchers in a similar fashion.

Once you have added run BibleDesktop in this fashion it is added to the list. [Image] During the run, output will go to the Console, and from there you can terminate the application if it becomes unresponsive.

Working under the Team Synchronization Perspective

This can be added in the same manner that the SVN Repository Exploring Perspective was added. To initially connect this perspective to the SVN Repository, click on the Synchronize... button [Image] and select SVN [Image] if it is not highlighted. Click on the Next button and then click Select All followed by the Finish button. [Image]

When you make changes to any of the projects, this perspective will track the changes. Also, you can click the same button, now labelled Sychronize SVN (Workspace) to get the latest changes from the repository.

Checking for Updates

In the Team Synchronization Perspective click on the Synchronize SVN (Workspace) button. Click the Incoming button and then select everything that is shown. Right clicking will give you all the options that are available to you. Choose Update. [Image] If you see Override and Update [Image], stay away from it. It means that one or more of the files being updated have been changed by you and choosing it will throw away your work. Probably not what you want.

Submitting Patches

To submit changes you will create a patch file, one for each project. Zip them all up and email it to jsword-devel@crosswire.org. Make sure you explain in detail what you have done and how you have tested it.

Generally, we will review the patch and apply it locally. Then we will make changes to make it conform to the coding standards, test it and then check it in. If we are in the middle of a big change that we cannot check in at the moment, your change may have to wait until we can commit our changes. Typically, turn around is a week or less.

Checking in Changes

Everyone has permission to check in for the incubator project. A select few people have permissions elsewhere. To check in, go to the Team Synchronization Perspective and click on the Outgoing button. Select what you want to check in. Right clicking on something selected will provide you with the opportunity to choose Commit [Image], which will bring up a dialog box. In that dialog box, type a short explanation describing the change. Below this is a list of everything that has changed and a terse label for the change. Review the items in the list and check or uncheck them depending on whether the changes should be checked in. Finally, click on OK. [Image] If the repository is password protected, you will need to supply your password. Saving your password is a good idea, if your machine is secure. [Image]