# Jmol Anleitung für Entwickler

2005 Jmol Development Team (jmol-developers@lists.sourceforge.net)

## Voraussetzungen

- Java 2 JDK 1.4 ()

- Apache Ant ()

  Ant sollte auf einem Linux/Unix/OSX System möglichst mit Hilfe der Paketverwaltung installiert werden.

- CVS - The definitive CVS documentation unter )

  Für Win32 kann wincvs von eingesetzt werden.

  Bei Mac OSX befindet sich die CVS-Software auf der Entwickler-CD, welche kostenlos bei Apple heruntergeladen werden kann.

## Jmol per CVS auschecken

Für den anonymen CVS-Checkout bei SourceForge:

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

Bei der Passwortabfrage einfach `Enter` betätigen:

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

Wir arbeiten im Verzeichnis `Jmol-HEAD`.

      cd Jmol-HEAD

Später, für updates ...

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

## Jmol übersetzen

Voraussetzungen:

- Java 2 JDK 1.4 ()

- Apache Ant ()

- Jmol Quellcode

Jmol Quellcode kann entweder als Paket herundergeladen (siehe SourceForge Projekt-Dateien) oder per CVS ausgecheckt werden (siehe SourceForge CVS Zugang).

Wenn die Vorraussetzungen alle erfüllt sind, kann Jmol durch das folgende Kommando, welches im Arbeitsverzeichnis von Jmol ausgeführt werden muss, übersetzt werden:

Unter Linux/OSX/Unix:

      [~/jmol/Jmol-HEAD]$ ant

Unter Windows:

      C:\jmol\Jmol-HEAD> ant

## Jmol starten

Die Entwickler-Version von Jmol wird normalerweise einfach durch das jmol Skript im Arbeitsverzeichnis gestartet.

Unter Linux/OSX/Unix:

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

Unter Windows:

      C:\jmol\Jmol-HEAD>jmol

## Coding-Standard

- Der gewählte Editor sollte Zeilen automatisch einrücken. Falls er das nicht tut und sich dieses Feature auch nicht aktivieren lässt, sollte ein anderer Editor benutzt werden.

- Die Breite der Einrückung (Tabulatorbreite) soll zwei Leerzeichen betragen.

        class Foo {
          int someClassVariable;

          Foo(int evenOrOdd) {
            someClassVariable = 99;
          }

          ...
        }

- Statt Tabulatoren sollten Leerzeichen benutzt werden

- Zuweisungen und arithmetische Operatoren besitzen i.A. auf beiden Seiten Leerzeichen.

        a = b + c;

  Es ist erlaubt, die Leerzeichen zwischen Ausdrücken zu entfernen, um die Operator-Priorität zu verdeutlichen.

        int cSquared = a*a + b*b;

- In der Liste der Argumente folgt auf ein Komma ein Leerzeichen.

        foo(a, 3.14159, "jmol");

- Eine Zeile sollte nicht länger als 80 Zeichen sein.

- Öffnende Klammern befinden sich in der Zeile, die den Block öffnet. Schließende Klammern werden in eine eigene Zeile geschrieben.

        if (condition) {
          ...
        } else {
          ...
        }

        while (condition)
          ...
        }

- Schleifen werden bei 0, nicht bei 1 gestartet.

- Nur `<` und `>=` sind valide Vergleichsoperatoren zur Termination von Schleifen ... alles andere ist möglicherweise fehlerhaft. Falls nicht absolute Gewissheit besteht, dass das Gegenteil der Fall ist, sollte in diesen Fällen ein Kommentar im Quellcode hinterlassen.

- Variablen- und Methodenbezeichnungen müssen eindeutig und beschreibend sein. Nur keine Hemmungen bei langen Bezeichnungen.

- line-by-line Kommentare sind unerwünscht ... in speziellen Fällen kann es Ausnahmen geben. Falls sich viele soclhe Kommentare im Quellcode finden, könnte es passieren, dass sie einfach gelöscht werden.

- Falls Kommentare unbedingt notwendig sind, sollten sie als JavaDoc vor der Funktion eingefügt werden

- Kommentare sollten nicht in Code eingefügt werden, der gerade verändert wird. Schlechte/veraltete Kommentare sind schlimmer als gar keine Kommentare.

- Empfehlenswert ist auch ein Blick in The Elements of Java Style von Vermeulen, et al.

## Ein Release erstellen

Ein Jmol Release besteht aus der Jmol Applikation und dem Applet. Beide sollten vorher ausführlich getestet werden.

Im Verzeichnis `samples/` befinden sich eine Reihe von Beispiel-Dateien, um den Input-Filter von Jmol zu überprüfen. Alle Dateien in diesem Verzeichnis sollten vor einem Release zu Testzwecken geladen werden.

## Pakete

Um Distributions-Pakete für Plattformen zu erstellen, muss der Entwickler den Support übernehmen. Dateien, die zum Erstellen der Pakete notwendig sind, werden im CVS innerhalb des Verzeichnisses Jmol/packaging abgelegt. Zur Zeit sind folgenden Pakete erhältlich:

- Debian (Daniel Leidert & Egon Willighagen)

- RPM (Miguel Howard)

## Mit Jmol's CVS-System arbeiten

Dieser Abschnitt gibt Auskunft über das Arbeiten mit dem Jmol CVS bei SourceForge.

### CVS Tags

Es ist sehr wichtig mit Tags zu arbeiten, vor allem wenn ein neues Release erscheint. Dadurch wird es möglich, dass auch später noch der exakte Quellcode für dieses Release zur Verfügung steht. Tags werden mittls `cvs tag tag-name` im Arbeitsverzeichnis erstellt.

### CVS Entwicklungszweige

Manchmal ist es auch sehr bequem mit verschiedenen Entwicklungszweigen (auch Branch genannt) zu arbeiten - einer für den nächsten Release, einer für die aktuelle Entickler-Version. Kleinere Bug-Fixes können in den stabilen Entwicklungszweig einfließen, während größere Veränderungen am Quellcode nur in die Entwickler-Version eingehen sollten. Dieser Abschnitt erklärt, wie man mit Entwicklungszweigen arbeitet.

#### Einen Entwicklungszweig auschecken

Das Kommando `cvs checkout module` checkt den Code aus dem HEAD Entwicklungszweig aus (entspricht dem Entwicklungszweig "unstable").

Einen bestimmten Entwicklungszeig zu bearbeiten, soll hier am Beispiel des b6-Branch gezeigt werden:

      cvs checkout -r b6 -d Jmol-6 Jmol

Damit checkt man eine Kopie des b6 Entwicklungszweigs aus und platziert diese im Verzeichnis `Jmol-6`.

Um festzustellen, zu welchem Entwicklungszweig eine lokale Datei gehört, nutzt man das Kommando `cvs status file`.

#### Einen Entwicklungszweig erstellen

Ein Entwicklungszweig von HEAD kann mit dem Kommando `cvs rtag -b -r HEAD branch-namemodule` erzeugt werden.

#### Entwicklungszweige zusammenführen

Bug-Fixes, welche in einen bestimmten Entwicklungszweig geflossen sind, sollten auch in HEAD eingehen. Dafür muss zuerst eine Kopie von HEAD ausgecheckt (oder falls vorhanden, aktualisiert) werden. Im Vereichnis von HEAD wird dann der folgende Befehl ausgeführt: `cvs update -j branch-to-merge`. Danach wird der Entwicklungszweig (Branch), der mit HEAD vermischt wurde, mit einem Tag versehen, um zu gewährleisten, dass spätere Änderungen auch nach HEAD übertragen werden können. Hier ein Beipsiel, wie eine solche Sitzung aussehen könnte:

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

Veränderungen, welche sich zu einem späteren Zeitpunkt ergeben, können dann nach HEAD überführt werden:

      > 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

## Eclipse benutzen

### Voraussetzungen für Eclipse

This documentation has been tested with Eclipse 3.0x and 3.1.

Eclipse muss zuerst korrekt installiert und konfiguriert werden, bevor mit den nächsten Schritten fortgefahren werden kann.

### Konfiguration des CVS Repositoriums

Der Zugang zum Jmol CVS wird unter Eclipse so konfiguriert:

- Eclipse starten.

- Zur `CVS Repository Exploring` Perspektive wechseln.

- Rechte Maustaste auf `CVS Repositories` Fenster und dort `New` / `Repository Location...` im Kontextmenü auswählen.

- Im Fenster `Add CVS Repository` werden die folgenden Werte eingegeben:

  - Host: `cvs.sourceforge.net`

  - Repository path: `/cvsroot/jmol`

  - Authentication: `anonymous` für anonymen Zugriff, oder den Login für den Zugang als Entwickler.

  - Password: leer oder das Passwort für den Zugang als Entwickler.

  - Connection type: `pserver` für anonymen Zugriff, `extssh` für den Zugang als Entwickler.

  - Dann sind noch die Optionen `Use Default Port` und `Validate Connection on Finish` zu aktivieren.

  - Das Passwort kann mit der Option `Save Password` wahlweise gespeicht werden.

  - Zum Schluss die Einstellungen mit `Finish` bestätigen.

### Jmol per CVS auschecken

Um Jmol aus dem CVS auszuchecken:

- Zur `CVS Repository Exploring` Perspektive wechseln.

- Die Adresse des CVS-Repositoriums (siehe vorangegangener Abschnitt) eingeben und `HEAD` eintragen.

- Rechte Maustaste auf `Jmol` und `Check Out As...` im Kontextmenü auswählen.

- Im Fenster `Check Out As`, wird die Option `Check out as a project in the workspace` aktiviert und im Feld `Project Name` wird `Jmol-HEAD` eingegeben. Diese Einstellungen müssen noch mit einem Klick auf `Finish` bestätigt werden.

- Falls gewünscht, kann auch Jmol-web ausgecheckt werden. Dazu rechte Maustaste auf `Jmol-web` und `Check out` im Kontextmenü auswählen.

### Eclipse zum Übersetzen von Jmol konfigurieren

Um Jmol mit Eclipse zu übersetzen:

- Zuerst zur `Java` Perspektive wechseln.

- Rechte Maustaste auf `Jmol-HEAD` und `Properties` im Kontextmenü auswählen.

- In the `Properties for Jmol-HEAD` window, select `Java Compiler` (3.0x) or `Java Compiler -> Errors/Warnings` (3.1).

- Check `Use project (specific) settings`.

- In the `Style` tab, select `Warning` for every combo-box, except for `Unqualified access to instance field` and `Undocumented empty block` where you can select `Ignore`. For Eclipse 3.1, you will find the necessary options in the `Code Style` tab.

- In the `Advanced` tab, select `Warning` for every combo-box, except for `Local variable declaration hides another field or variable`, `Usage of deprecated API` and `Usage of non-externalized strings` where you can select `Ignore`. For Eclipse 3.1, you will find the necessary options in the `Name shadowing and conflicts`, `Deprectated and restricted API` and the `Code Style` tab.

- In the `Unused code` tab, select `Warning` for every combo-box, except for `Parameter is never read` and `Unnecessary cast or 'instance of' operation` where you can select `Ignore`. For Eclipse 3.1, you will find the necessary options in the `Unnecessary code` tab.

### Jmol starten und debuggen

Eclipse kann benutzt werden um Jmol zu starten und zu debuggen.

Die Hauptklasse ist `org.openscience.jmol.app.Jmol`

### Jmol übersetzen

Um das Jmol Projekt unter Eclipse zu erstellen, sind nur wenige Schritte notwendig: Rechte Maustaste auf `build.xml` und `Run` / `Ant Build` im Kontextmenü auswählen.