Table of Contents
The following package are necessary:
Java 2 JDK 1.4 or Java 5 JDK 1.5 (http://java.sun.com/).
Apache Ant (http://jakarta.apache.org/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 http://svnbook.red-bean.com/.
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:
~/workspace$
svn checkout https://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 http://sourceforge.net/docman/display_doc.php?docid=31070&group_id=1
The definitive documentation for subversion is at http://svnbook.red-bean.com/
The home page for subversion is at http://subversion.tigris.org/.
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
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.
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.
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.
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)
This section is deprecated since Jmol has moved to svn.
This section gives information on how to work with Jmol's CVS at SourceForge.
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-namein the directory where the CVS files are stored.
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.
The command
cvs checkout moduleby 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
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 -jparameterbranch-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
Table of Contents
This section must be updated for svn.
Java 2 JDK 1.4 or Java 5 JDK 1.5 (http://java.sun.com/).
Eclipse SDK 3.1 (http://www.eclipse.org/downloads)
Eclipse must be installed and correctly configured before following this procedure.
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 → → and choose . Then click on the button.
Then click in the CVS Repositories windows and select → 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 Portchecked
Validate Connection on Finishchecked
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 button, and you are done.
To check out Jmol from CVS, do the following:
Switch to the CVS Repository Exploring perspective using → → and choose . Click on the button.
on the repository location you added in the previous section and then 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 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 in the contextual menu.
To configure Eclipse 3.1 to build Jmol, you need to make sure, that:
the location of the Java executables (javac.exe
and jarsigner.exe) is identified
the location of the Java library (tools.jar)
is identified
Eclipse is using the same version of the Java compiler as the Java Runtime Environment
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 .
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".
Ant needs to know where to find
tools.jar. From → . In the Preferences Window go to → and select and click on
the button. Navigate to the directory
containing tools.jar (probably something
like c:\j2sdk1.4.2_10\lib),
select tools.jar and
click on .
You can run and debug Jmol directly within Eclipse.
Open a Java Perspective using → → and there select .
To run either the application or the applet
click on Jmol under the tab
and select (for the applet) → or (for the application) → . The main class for the application
is org.openscience.jmol.app.Jmol.
If not already done, open a Java Perspective using → → and there select .
To make a full build of Jmol under Eclipse, just do the following:
Find the build.xml in the Package Explorer
window and click on it. Then select → 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").