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 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:

• Java: Java 2 SDK 1.4, Java 5 SDK 1.5, or a later release.
• Eclipse: version 3.1 or a later release.
• 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 Window → Open Perspective → Other... and choose SVN Repository Exploring. Then click on the OK button.
• Then right click in the SVN Repository window and select New → Repository Location... in the contextual menu.
• In the Add SVN Repository window, enter the value https://svn.sourceforge.net/svnroot/jmol in the Url field.
• Click on the 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 Window → Open Perspective → Other... and choose SVN Repository Exploring. Click on the OK button.
• Expand the repository location you added in the previous section, you should see branches, tag and trunk after a few seconds.
• Expand trunk, you should see amongst other things the Jmol projects:
  • Jmol is the source code of the Jmol Application and Applet.
  • Jmol-datafiles is a collection of datafiles used for testing Jmol.
  • Jmol-web is the source of the Jmol website.
• Right click on Jmol and select Checkout... in the contextual menu.
• In the Checkout from SVN window, select Check out as a project in the workspace and use Jmol as Project Name. Then click on the Finish button.
• If you want, you can also check-out Jmol-datafiles:
  • Right click on Jmol-datafiles and select Checkout... in the contextual menu.
  • In the Checkout from SVN window, select Check out as a project in the workspace and use Jmol-datafiles as Project Name. Then click on the Finish button.
• If you want, you can also check-out Jmol-web:
  • Right click on Jmol-web and select Checkout... in the contextual menu.
  • In the Checkout from SVN window, select Check out as a project in the workspace and use Jmol-web as Project Name. Then click on the Finish button.

Note: There is 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. If it happens to you, you can fix the problem by doing the following:

• Switch to the Java perspective using Window → Open Perspective → Other... and choose Java (default). Click on the OK button.
• In the Package Explorer window, left click on the small triangle at the top right of the window and select Filters.... Uncheck the .* resources item and click on the OK button.
• Expand the project which had a problem.
• If the .project file has not been checked-out (no version information after the filename), delete it by selecting it and pressing the Suppr key.
• Right click on the project and select Team → Update in the contextual menu.

Configuring Eclipse to build Jmol

To configure Eclipse to build Jmol, you need to make sure that:

1. the location of the Java executables (javac.exe and jarsigner.exe) is identified.
2. the location of the Java library (tools.jar) is identified.
3. 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 javac(.exe) and jarsigner(.exe). This simply requires adding the Java SDK bin directory to the PATH environment variable.

To do this on Windows, you need to open the Windows System Control Panel. On the Advanced tab, select Environment variables. Scroll down to the path system variable and append to it a semicolon (;) followed by the path to the Java SDK binaries, something like ";C:\j2sdk1.4.2_10\bin".

Identifying the location of the Java library

Ant needs to know where to find tools.jar.

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

Matching the Java compiler to the Java Runtime Environment

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

Running and Debugging Jmol

You can run and debug Jmol directly within Eclipse.

Open a Java Perspective using Window → Open Perspective → Other... and there select Java (default).

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

Building Jmol

If not already done, open a Java Perspective using Window → Open Perspective → Other... and there select Java (default).

To make a full build of Jmol under Eclipse, just do the following:

• Find the build.xml in the Package Explorer window and right click on it.
• Then select Run As → 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 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").

Contributors

NicolasVervelle, Pimpim, AngelHerraez, Hansonr, Gutow