Jmol Developer's Guide

The Jmol Development Team

Table of Contents

1. Prerequisites
2. Checking Out Jmol from SVN
3. Building Jmol
4. Running Jmol
5. Coding Standard
6. Making a release
7. Packaging
8. DEPRECATED - Working with Jmol's CVS
9. Using Eclipse

Chapter 1. Prerequisites

The following package are necessary:

Chapter 2. Checking Out Jmol from SVN

If you are using Eclipse, see Chapter 9, Using Eclipse.

In February 2006 Jmol converted to the subversion version control system for our source code repository, frequently referred to as svn. The svn repository is still hosted by SourceForge.

The current development version of the Jmol source code can be checked out using:

			svn checkout

This creates a directory called Jmol where we work on the source code:

~/workspace$ cd Jmol

To know the status of your workspace relative to the current repository you can say:

~/workspace/Jmol$ svn status

To update your workspace to the current repository revision use the update command

~/workspace/Jmol$ svn update

After modifying local files for testing, you can throw away your local changes and revert your changes back to your checkout revision:

~/workspace/Jmol$ svn revert

After developing, compiling, and testing changes locally, you can commit your changes by saying:

~/workspace/Jmol$ svn commit provides basic instructions how to use svn at this page

The definitive documentation for subversion is at

The home page for subversion is at

Chapter 3. Building Jmol

If you are using Eclipse, see Chapter 9, Using Eclipse. Otherwise read this section carefully. In additon to the prerequisites mentioned in Chapter 1, Prerequisites you will of course need the Jmol source code. It can be checked out from the subversion repository as described above.

Once you have all the prerequisites, Jmol can be built from the top source directory with the ant command.

On Linux/Unix/OSX type:

~/workspace/Jmol$ ant

Windows users not using Eclipse type:

C:\workspace\Jmol> ant

Chapter 4. Running Jmol

The development version of the Jmol application is normally run by simply executing the jmol script in the Jmol development directory.

The development version of the Jmol applet is normally run by copying the built *.jar files into a test directory and then running a web page that accesses them.

On Linux/Unix/OSX:

~/workspace/Jmol$ ./jmol

On Windows (not using Eclipse):

C:\workspace\Jmol> jmol

If you are using the Eclipse IDE, you can run the application and/or the applet from within Eclipse. This allows for simpler debugging. See Chapter 9, Using Eclipse for more information.

Chapter 5. Coding Standard

  • Your text editor should indent for you. If it doesn't then either learn how to enable it or get another editor.

  • Indentation level should be two spaces.

    class Foo {
      int someClassVariable;
      Foo(int evenOrOdd) {
        someClassVariable = 99;

  • Space characters should be used instead of tabs.

  • Assignment and arithmetic operators generally contain spaces on both sides.

    a = b + c;

    You are allowed to eliminate the spaces within expressions in order to make operator precedence more clear.

    int cSquared = a*a + b*b;

  • Spaces follow commas in argument lists.

    foo(a, 3.14159, "jmol");

  • Lines should be no more than 80 characters wide.

  • Open brace goes on the line that starts the block. Close brace goes on a line by itself.

    if (condition) {
      } else {
      while (condition) {

  • Loop indexes start at 0, not 1.

  • The only valid comparison operators for loop termination are < and >= ... anything else is probably a bug. If you are really sure that it is not a bug then put a comment in the code.

  • Use long descriptive variable names and method names. Do not be afraid of typing.

  • Line-by-line comments within the code are discouraged ... except in very special circumstances. If you put in lots of comments like this then you may find them deleted.

  • If you feel obligated to insert comments put them as javadoc before the function body.

  • If your code is changing then do not put in comments. Bad/outdated comments are worse than no comments.

  • You may want to look at The Elements of Java Style by Vermeulen, et al.

Chapter 6. Making a release

A Jmol release consists of both the application and the applet. Presumably both will have been well tested. For release, we are generating a number of JAR files using Java 1.1. This is to provide compatibility with the Microsoft Java Runtime Environment.

In the Jmol-data CVS module directory a number of test files are located for the input filters. All files below that module should be checked prior to a release.

Chapter 7. Packaging

Distribution packages will be made for any platform for which a developer promises to provide support. File used to create packages should be commited to CVS under the Jmol/packaging directory. Currently the following packages are available:

  • Debian (by Daniel Leidert and Egon Willighagen)

  • RPM (by Miguel Howard)

Chapter 8. DEPRECATED - Working with Jmol's CVS

This section is deprecated since Jmol has moved to svn.

Chapter 9. Using Eclipse

See the Jmol Wiki.