# Jmol Developer's Guide

The Jmol Development Team

    				jmol-developers@lists.sourceforge.net

2005
2006
The Jmol Development Team

## Prerequisites

The following package are necessary:

- `Java 2 JDK 1.4` or `Java 5 JDK 1.5` ().

- `Apache Ant` () - not necessary if you are using Eclipse with a Windows PC (see below).

  On Linux/Unix/OSX try to install `Apache Ant` using a package installer.

- `Subversion` - The definitive svn documentation is at .

## Checking Out Jmol from SVN

If you are using Eclipse, see .

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:

    			~/workspace$
    			svn checkout https://jmol.svn.sourceforge.net/svnroot/jmol/trunk/Jmol

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

Sourceforge.net provides basic instructions how to use `svn` at this page

The definitive documentation for `subversion` is at

The home page for subversion is at .

## Building Jmol

If you are using Eclipse, see . Otherwise read this section carefully. In additon to the prerequisites mentioned in 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

## 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 for more information.

## 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.

## 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.

## 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)

## DEPRECATED - Working with Jmol's CVS

This section is deprecated since Jmol has moved to `svn`.

This section gives information on how to work with Jmol's CVS at SourceForge.

### Tagging CVS

It is important to tag CVS when a distribution was made. This makes it possible to later retrieve the exact source code from CVS in that release. This can be done with

    cvs tag tag-name

in the directory where the CVS files are stored.

### CVS Branches

Sometimes it is convenient to have separate branches to work on. One for an upcoming release, and one branch for the unstable version. Minor bug fixes can then go into the stable branch, while major changes can go into the unstable branch. This section explains how to access, use, and create branches.

#### Accessing a branch

The command

    cvs checkout module

by default gets the source code from the HEAD branch, which is the unstable branch of Jmol. Accessing a specific branch can be done with (e.g. for the b6 branch):

    cvs checkout -r b6 -d Jmol-6 Jmol

This will check out a copy of the Jmol module from the b6 branch into a directory called `Jmol-6`.

To determine to which branch a specific locally stored file belongs, you can do:

    cvs status file

#### Creating a branch

A branch of HEAD can be created with

    cvs rtag -b -r HEAD branch-name module

#### Merging branches

Bug fixes which have been commited to a branch can be merged to the HEAD branch. To do this, check out (or update) a HEAD branch, and then type in that directory

    cvs update -j parameter branch-to-merge

Then the branch from which the changes were merged with HEAD should be tagged, to make it possible to merge later changes with HEAD too. For example, a session might look like:

    > cd ~/data/SF/Jmol/Jmol
    > cvs update -j b6
    > cd ~/data/SF/Jmol/Jmol-6
    > cvs tag b6-merged-20030725

Changes made after this merge to branch b6, can then be merged with HEAD with:

    > cd ~/data/SF/Jmol/Jmol
    > cvs update -j b6-merged-20030725 -j b6
    > cd ~/data/SF/Jmol/Jmol-6
    > cvs tag b6-merged-20031011

## Using Eclipse

### Eclipse prerequisites

This section must be updated for `svn`.

- `Java 2 JDK 1.4` or `Java 5 JDK 1.5` ().

- `Eclipse SDK` 3.1 ()

Eclipse must be installed and correctly configured before following this procedure.

### CVS Repository configuration

To configure Eclipse to access Jmol's CVS repository, do the following:

- Launch Eclipse.

- Using the menu system at the top of the application, navigate to Window Open Perspective Other... and choose CVS Repository Exploring. Then click on the [OK] button.

- Then right click in the CVS Repositories windows and select New Repository Location... in the contextual menu.

- In the Add CVS Repository window, enter the following values:

  `Host:`

    `cvs.sourceforge.net`

  `Repository path:`

    `/cvsroot/jmol`

  `Authentication:`

    `anonymous` for anonymous access, or `your login id` for developer access

  `Password:`

    `empty` for anonymous access or `your password` for developer access

  `Connection type:`

    `pserver` for anonymous or `extssh` for developer access

  `Use Default Port`

    `checked`

  `Validate Connection on Finish`

    `checked`

  `Save Password`

    `checked` if password should be stored or `unchecked` if you want to type the password every time you need it

  Click on the [Finish] button, and you are done.

### Checking Out Jmol from CVS

To check out Jmol from CVS, do the following:

- Switch to the CVS Repository Exploring perspective using Window Open Perspective Other... and choose CVS Repository Exploring. Click on the [OK] button.

- Click on the repository location you added in the previous section and then click on HEAD. You should see a message on the status line indicating that Eclipse is connecting to the server.

- Right click on `Jmol` and select Check Out in the contextual menu. The files should start transferring. If you do not want to wait, you can indicate that you want the transfer to occur in the background.

- If you want, you can also check out Jmol-web: Right click on `Jmol-web` and select Check out in the contextual menu.

### Configuring Eclipse to build Jmol

To configure Eclipse 3.1 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... and there 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.

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.

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 an 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").