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

## Using Eclipse

See the Jmol Wiki.