Jmol Developer's Guide

Chapter 1. Prerequisites

Java 2 JDK 1.4 ( http://java.sun.com/)
Apache Ant ( http://jakarta.apache.org/ant)
On Linux/Unix/OSX try to install ant using a package installer
CVS (The definitive CVS documentation is at http://cvsbook.red-bean.com/cvsbook.html )
On Win32 you can use wincvs from www.wincvs.org
On Mac OSX the cvs software comes on the Developer's CD, which can be downloaded free from Apple.

Chapter 2. Checking Out Jmol from CVS

For anonymous checkout from SourceForge cvs:

	cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/jmol login

Press the Enter key when prompted for the password

	cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/jmol co -d Jmol-HEAD Jmol

We work from the directory called Jmol-HEAD.

	cd Jmol-HEAD

Later, to get updates ...

	cd {some-path}/Jmol-HEAD
	cvs up -dP

Chapter 3. Building Jmol

Prerequisites:

Java 2 JDK 1.4 (http://java.sun.com/)
Apache Ant (http://jakarta.apache.org/ant)
Jmol source code

The Jmol source code can be either downloaded (see SourceForge project files) or checked out from the CVS repository (see SourceForge CVS access).

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

On Linux/OSX/Unix,

        [~/jmol/Jmol-HEAD]$ ant

On Windows,

        C:\jmol\Jmol-HEAD> ant

Chapter 4. Running Jmol

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

On Linux/OSX/Unix,

        [~/jmol/Jmol-HEAD]$./jmol

On Windows,

        C:\jmol\Jmol-HEAD>jmol

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, not 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 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.

In the samples/ directory a number of test files are located for the input filters. All files below that subdirectory 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 Egon Willighagen)
RPM (by Miguel Howard)

Chapter 8. Working with Jmol's CVS

Table of Contents

Tagging CVS

CVS Branches

Accessing a branch
Creating a branch
Merging branches

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. 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 the cvs rtag -b -r HEAD branch-name module command.

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 type in that directory cvs update -j branch-to-merge. After this 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-HEAD
> cvs update -j b6
> cd ~/data/SF/Jmol/Jmol-6
> cvs tag b6-merged-20030725

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

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