View source for Eclipse

To implement new features in Jmol (or simply build yourself a version of Jmol), you can use many development tools.
One of them is [http://www.eclipse.org/ Eclipse].

If you don't already have a suitable development environment for Jmol, then Eclipse is probably the best choice:
* it's easy to install and is bundled with several tools required for Jmol.
* it's a powerful IDE.
* Jmol is already configured as an Eclipse project.

The following description has been tested under Windows, but it should work also for other OS (Linux, Mac OS X, ...).


= Prerequisites =

The following tools must be already installed for Jmol:
* [http://java.sun.com/ Java]: Java 2 SDK 1.4, Java 5 SDK 1.5, or a later release.
* [http://www.eclipse.org/ Eclipse]: version 3.1 or a later release.
* [http://subclipse.tigris.org/ Subclipse], a Subversion (SVN) plugin for Eclipse.


= SVN Repository Configuration =

To configure Eclipse to access Jmol's SVN repository, do the following:
* Launch Eclipse.
* Using the menu system at the top of the application, navigate to {{MenuItem|Window}} {{Submenu}} {{MenuItem|Open Perspective}} {{Submenu}} {{MenuItem|Other...}} and choose {{Field|SVN Repository Exploring}}. Then click on the {{Button|OK}} button.
* Then right click in the {{WindowTitle|SVN Repository}} window and select {{MenuItem|New}} {{Submenu}} {{MenuItem|Repository Location...}} in the contextual menu.
* In the {{WindowTitle|Add SVN Repository}} window, enter the value <tt><nowiki>https://jmol.svn.sourceforge.net/svnroot/jmol</nowiki></tt> in the {{Field|Url}} field.
* Click on the {{Button|Finish}} button and you are done.

= Checking out Jmol from SVN =

To check out Jmol from SVN, do the following:
* Switch to the SVN Repository Exploring perspective using {{MenuItem|Window}} {{Submenu}} {{MenuItem|Open Perspective}} {{Submenu}} {{MenuItem|Other...}} and choose {{Field|SVN Repository Exploring}}. Click on the {{Button|OK}} button.
* Expand the repository location you added in the previous section, you should see {{Field|branches}}, {{Field|tag}} and {{Field|trunk}} after a few seconds.
* Expand {{MenuItem|trunk}}, you should see amongst other things the Jmol projects:
** {{MenuItem|Jmol}} is the source code of the Jmol Application and Applet.
** {{MenuItem|Jmol-datafiles}} is a collection of datafiles used for testing Jmol.
** {{MenuItem|Jmol-documentation}} is a collection of Jmol documentation.
** {{MenuItem|Jmol-web}} is the source of the [http://www.jmol.org/ Jmol website].
* Right click on {{MenuItem|Jmol}} and select {{MenuItem|Checkout...}} in the contextual menu.
* In the {{WindowTitle|Checkout from SVN}} window, select {{Field|Check out as a project in the workspace}} and use {{Field|Jmol}} as Project Name. Then click on the {{Button|Finish}} button.
* If you want, you can also check-out {{MenuItem|Jmol-datafiles}}:
** Right click on {{MenuItem|Jmol-datafiles}} and select {{MenuItem|Checkout...}} in the contextual menu.
** In the {{WindowTitle|Checkout from SVN}} window, select {{Field|Check out as a project in the workspace}} and use {{Field|Jmol-datafiles}} as Project Name. Then click on the {{Button|Finish}} button.
* If you want, you can also check-out {{MenuItem|Jmol-documentation}}:
** Right click on {{MenuItem|Jmol-documentation}} and select {{MenuItem|Checkout...}} in the contextual menu.
** In the {{WindowTitle|Checkout from SVN}} window, select {{Field|Check out as a project in the workspace}} and use {{Field|Jmol-documentation}} as Project Name. Then click on the {{Button|Finish}} button.
* If you want, you can also check-out {{MenuItem|Jmol-web}}:
** Right click on {{MenuItem|Jmol-web}} and select {{MenuItem|Checkout...}} in the contextual menu.
** In the {{WindowTitle|Checkout from SVN}} window, select {{Field|Check out as a project in the workspace}} and use {{Field|Jmol-web}} as Project Name. Then click on the {{Button|Finish}} button.


'''Note''': There was a bug somewhere in the SVN chain (we don't know if the problem is in Subclipse, Eclipse or Sourceforge), so you may get an error during the check-out. Apparently, it has been fixed with more recent versions of the tools, but if it happens to you, you can fix the problem by doing the following:
* Switch to the Java perspective using {{MenuItem|Window}} {{Submenu}} {{MenuItem|Open Perspective}} {{Submenu}} {{MenuItem|Other...}} and choose {{Field|Java (default)}}. Click on the {{Button|OK}} button.
* In the {{WindowTitle|Package Explorer}} window, left click on the small triangle at the top right of the window and select {{MenuItem|Filters...}}. Uncheck the {{Field|.* resources}} item and click on the {{Button|OK}} button.
* Expand the project which had a problem.
* If the {{File|.project}} file has not been checked-out (no version information after the filename), delete it by selecting it and pressing the {{Keyboard|Suppr}} key.
* Right click on the project and select {{MenuItem|Team}} {{Submenu}} {{MenuItem|Update}} in the contextual menu.


= Configuring Eclipse to build Jmol =

To configure Eclipse to build Jmol, you need to make sure that:
# the location of the Java executables ({{File|javac.exe}} and {{File|jarsigner.exe}}) is identified.
# the location of the Java library ({{File|tools.jar}}) is identified.
# Eclipse is using the same version of the Java compiler as the Java Runtime Environment.

== Identifying the location of the Java executables ==

Ant needs to know where to find {{File|javac(.exe)}} and {{File|jarsigner(.exe)}}. This simply requires adding the Java SDK {{Directory|bin}} directory to the <tt>PATH</tt> environment variable.

To do this on Windows, you need to open the Windows {{WindowTitle|Control Panel}}, then double-click the {{WindowTitle|System}} icon (which may be under category {{WindowTitle|Performance}}). On the {{Field|Advanced}} tab, select {{Field|Environment variables}}. Scroll down to the <tt>path</tt> system variable and append to it a semicolon (<tt>;</tt>) followed by the path to the Java SDK binaries, something like "<tt>;C:\j2sdk1.4.2_10\bin</tt>".

== Identifying the location of the Java library ==

Ant needs to know where to find {{File|tools.jar}}.

From {{MenuItem|Window}} {{Submenu}} {{MenuItem|Preferences...}}: in the {{WindowTitle|Preferences}} window, go to {{MenuItem|Ant}} {{Submenu}} {{MenuItem|Runtime}} and select {{MenuItem|Global Entries}} and click on the {{Button|Add External JARs}} button. Navigate to the directory containing {{File|tools.jar}} (probably something like {{Directory|C:\j2sdk1.4.2_10\lib}}), select {{File|tools.jar}} and click on {{Button|OK}}.

== Matching the Java compiler to the Java Runtime Environment ==

From {{MenuItem|Window}} {{Submenu}} {{MenuItem|Preferences...}}, select {{MenuItem|Java}}. Compare the version listed for the compiler with that for the selected installed JREs. If they are not the same, use the {{Button|Search}} facility to find more installed JREs. Then select the JRE that matches the compiler.


= Installing and configuring gettext tools =

If you want to use Jmol in an other language than English, you will need to install the gettext tools.

Download and install [http://www.gnu.org/software/gettext/gettext.html gettext]. Linux users should try to install it using their distributions package management (like rpm, dpkg, apt, ...). Windows user download gettext from [http://gnuwin32.sourceforge.net/packages/gettext.htm GnuWin32]. Both make sure, that the gettext binaries are in your <tt>PATH</tt> environment variable.

'''Note for Windows users:''' If you installed the gettext binaries into e.g. {{File|C:\Program Files\GnuWin32}}, then you need to add {{File|C:\Program Files\GnuWin32\bin;}} to the existing <tt>PATH</tt> environment variable: {{MenuItem|Control Panel}} {{Submenu}} {{MenuItem|System}} {{Submenu}} {{MenuItem|Environment Variable}} (Tab Extended) OR run the following command in a windows command shell (this command is not permanent, you need to do it each time):
 set PATH=%PATH%;C:\Program Files\GnuWin32\bin;.
Windows XP and Windows 2000 are currently supported.


= Running and Debugging Jmol =

You can run and debug Jmol directly within Eclipse.

Open a Java Perspective using {{MenuItem|Window}} {{Submenu}} {{MenuItem|Open Perspective}} {{Submenu}} {{MenuItem|Other...}} and there select {{Field|Java (default)}}.

To run either the application or the applet, right click on {{MenuItem|Jmol}} under the Projects tab and select (for the applet) {{MenuItem|Run As}} {{Submenu}} {{MenuItem|Java Applet}} or (for the application) {{MenuItem|Run As}} {{Submenu}} {{MenuItem|Java Application}}. The main class for the application is {{JavaClass|org.openscience.jmol.app.Jmol}}.


= Building Jmol =

If not already done, open a Java Perspective using {{MenuItem|Window}} {{Submenu}} {{MenuItem|Open Perspective}} {{Submenu}} {{MenuItem|Other...}} and there select {{Field|Java (default)}}.

To make a full build of Jmol under Eclipse, just do the following:
* Find {{File|build.xml}} in the {{WindowTitle|Package Explorer}} window and right click on it.
* Then select {{MenuItem|Run As}} {{Submenu}} {{MenuItem|Ant Build}} in the contextual menu.
* If the build fails, look carefully at the message, and if you can't figure it out, send a copy of it in email message to {{mail|jmol-developers@lists.sourceforge.net}}. Problems might include Ant not being able to find the Java compiler ("JAVA_HOME not in CLASSPATH?") or a difference in Java compiler and runtime environment versions ("class file has wrong version 49.0, should be 48.0").