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]
- This will automatically open the SVN Repository Exploring perspective.
- Click on the
Add SVN Repository button. [Image]
- For the URL use the value: http://www.crosswire.org/svn/jsword/trunk.
[Image]
- Open the repository, expanding https://www.crosswire.org/svn/jsword/trunk.
- Select at a minimum the following:
- bibledesktop
- common
- common-swing
- jsword
- Right click on one of the selection and choose
Checkout... [Image]
and then click Finish . [Image]
- Later you may wish to do help maintain the website and then you will
want bibledesktop-web and jsword-web.
- You don't need this perspective for day to day development,
so you can remove it.
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]
|