# Guide du Développeur Jmol

## Prérequis

- Java 2 JDK 1.4 (http://java.sun.com/)

- Apache Ant ( http://jakarta.apache.org/ant )

  Sur Linux/Unix/OSX essayer d'installer ant en utilisant un installeur de package

- CVS (La documentation de CVS est à http://cvsbook.red-bean.com/cvsbook.html )

  Sous Win32 vous pouvez utiliser wincvs qui est à www.wincvs.org

  Sous Mac OSX le logiciel CVS est livré sur le CD de développeur qui peut être téléchargé gratuitement chez Apple.

## Récupérer Jmol par CVS

Pour une récupération anonyme depuis le cvs de SourceForge:

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

Appuyer sur la touche `Entrée` quand le mot de passe est demandé

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

Nous travaillons depuis un répertoire nommé `Jmol-HEAD`.

            cd Jmol-HEAD

Plus tard, pour obtenir des mises à jour ...

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

## Construire Jmol

Prérequis:

- Java 2 JDK 1.4 (http://java.sun.com/)

- Apache Ant (http://jakarta.apache.org/ant)

- Code soure de Jmol

Le code source de Jmol peut être soit téléchargé (cf. SourceForge project files) soit récupéré depuis le repository CVS (cf. SourceForge CVS access).

Une fois les prérequis remplis, Jmol peut être construit depuis la racine du répertoire des sources avec la commande:

Sous Linux/OSX/Unix,

            [~/jmol/Jmol-HEAD]$ ant

Sous Windows,

            C:\jmol\Jmol-HEAD> ant

## Exécuter Jmol

La version de développement de Jmol est lancée simplement en exécutant le script jmol dans le répertoire de développement Jmol.

Sous Linux/OSX/Unix,

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

Sous Windows,

            C:\jmol\Jmol-HEAD>jmol

## Règles de Programmation

- Votre éditeur de texte devrait indenter pour vous. Si il ne le fait pas, alors apprenez comment l'activer ou trouvez un autre éditeur.

- Le niveau d'indentation devrait être deux espaces

      	  class Foo {
      	    int someClassVariable;

      	    Foo(int evenOrOdd) {
      	      someClassVariable = 99;
      	    }

      	    ...
      	  }

- Les caractères espace devraient être utilisés, pas les tabulations

- Les opérateurs d'assignation et arithmétiques contiennent généralement des espaces des deux côtés.

      	  a = b + c;

  Vous êtres autorisés à éliminer les espaces dans des expressions pour rendre les priorités des opérateurs plus claires

      	  int cSquared = a*a + b*b;

- les espaces suivent les virgules dans les listes d'arguments

      	  foo(a, 3.14159, "jmol");

- Les lignes ne devraient pas avoir plus de 80 caractères

- Les accolades ouvrantes sont sur la ligne qui commence le bloc. Les accolades fermantes sont sur une ligne à elles.

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

      	  while (condition)
      	    ...
      	  }

- les indices de boucles commencent à 0, et non 1.

- les seuls opérateurs valides pour les fins de boucle sont `<` and `>=` ... tous les autres sont probablement des anomalies. Si vous êtes sûrs qu'il ne s'agit pas d'une anomalie, mettez un commentaire dans le code.

- utilisez des noms de variables et de méthodes longs et descriptifs. N'ayez pas peur de taper.

- les commentaires ligne à ligne avec le code sont découragés ... à l'exception de cas très particuliers. Si vous mettez beaucoup de commentaires de ce genre vous risquez de les voir effacés.

- si vous vous sentez obligés de mettre des commentaires, mettez les sous forme de javadoc avant le corps de la fonction

- Si votre code change, ne le mettez pas en commentaires. Les commentaires incorrects/dépassés sont pires que pas de commentaires.

- Vous pouvez regarder à l'adresse "The Elements of Java Style" by Vermeulen, et al

## Générer une livraison

Une livraison de Jmol est constituée à la fois de l'application et de l'applet. Les deux doivent fonctionner comme attendu.

Dans le répertoire `samples/` un certain nombre de fichiers de test sont présents pour les filtres d'entrée. Avant chaque livraison, il faut vérifier que tous les fichiers de ce répertoire sont lisibles.

## Packaging

Des packages de distribution seront faits pour chaque plateforme pour laquelle un développeur s'engage à fournir un support. Un fichier utilisé pour créer les packages devrait être commité sous CVS dans le répertoire Jmol/packaging. Actuellement, les packages suivants sont disponibles:

- Debian (par Daniel Leidert & Egon Willighagen)

- RPM (par Miguel Howard)

## Travailler avec CVS

Ce chapitre donne des informations sur la manière de travailler avec la base CVS de Jmol sur SourceForge.

### Etiquetter sous CVS

Il est important d'étiquetter sous CVS quand une distribution est faite. Ceci permet de récupérer ultérieurement le code source exact de cette livraison depuis CVS. Ceci peut être fait avec `cvs tag `tag-name`` dans le répertoire où les fichiers CVS sont stockés.

### Branches CVS

Il est parfois pratique d'avoir des branches séparées pour travailler. Une branche pour une livraison à venir, et une branche pour la version non stabilisée. Les corrections d'anomalies mineures peuvent être faites dans la branche stable, tandis que les modifications importantes peuvent être faites dans la branche non stabilisée. Ce chapitre explique comment accéder, utiliser et créer des branches.

#### Accéder à une branche

La commande `cvs checkout `module`` récupère par défaut le code de la branche HEAD, qui est la branche non stabilisée de Jmol.

L'accès à une branche spécifique peut se faire avec, par exemple pour la branche b6:

    cvs checkout -r b6 -d Jmol-6 Jmol

Cette commande récupèrera une copie du module Jmol de la branche b6 dans un répertoire nommé `Jmol-6`.

Pour déterminer à quelle branche appartient un fichier particulier stocké localement, vous pouvez faire `cvs status `file``.

#### Créer une branche

Une branche de HEAD peut être créée avec la commande `cvs rtag -b -r HEAD `branch-name` `module``.

#### Fusionner des branches

Les corrections d'anomalies qui ont été commitées dans une branche peuvent être fusionnées à la branche HEAD. Pour faire ceci, récupérer (ou mettre à jour) une branche HEAD, et taper dans ce répertoire la commande `cvs update -j `branch-to-merge``. Après ceci la branche depuis laquelle les modifications ont été fusionnées avec HEAD devrait être étiquettée pour permettre de fusionner aussi des modifications ultérieures avec HEAD. Par exemple, une session pourrait ressembler à

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

Les modifications faites après cette fusion à la branche b6 peuvent alors être fusionnées avec HEAD:

    > 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

## Utilisation d'Eclipse

###

Cette documentation a été testée avec Eclipse 3.01.

Eclipse doit être installé et correctement configuré avant de suivre cette procédure.

### Configuration du CVS Repository

Pour configurer l'accès d'Eclipse au repository CVS de Jmol, effectuer les actions suivantes:

- Démarrer Eclipse.
- Passer sur la perspective `CVS Repository Exploring`.
- Cliquer avec le bouton droit de la souris dans la fênetre `CVS Repositories` et sélectionner `New` / `Repository Location...` dans le menu contextuel.
- Dans la fênetre `Add CVS Repository`, saisir les valeurs suivantes:
  - Host: `cvs.sourceforge.net`
  - Repository path: `/cvsroot/jmol`
  - Authentication: `anonymous` pour un accès anonyme, ou votre login pour un accès développeur.
  - Password: vide pour l'accès anonyme, ou votre mot de passe pour l'accès développeur.
  - Connection type: `pserver` pour l'accès anonyme, `extssh` pour l'accès développeur.
  - Cocher `Use Default Port` et `Validate Connection on Finish`.
  - Vous pouvez choisir de cocher ou non `Save Password`.
  - Cliquer sur `Finish`.

### Récupérer Jmol depuis CVS

Pour récupérer Jmol depuis CVS, effectuer les actions suivantes:

- Passer sur la perspective `CVS Repository Exploring`.
- Déplier l'emplacement du repository que vous avez ajouté au chapitre précédent et déplier `HEAD`.
- Cliquer avec le bouton droit de la souris sur `Jmol` et sélectionner `Check Out As...` dans le menu contextuel.
- Dans la fenêtre `Check Out As`, cocher `Check out as a project in the workspace` et saisir `Jmol-HEAD` dans le champ `Project Name`. Cliquer sur `Finish`.
- Si vous le souhaitez, vous pouvez aussi récupérer Jmol-web: Cliquer avec le bouton droit de la souris sur `Jmol-web` et sélectionner `Check out` dans le menu contextuel.

### Configuration d'Eclipse pour construire Jmol

Pour configurer Eclipse pour construire Jmol, vous pouvez effectuer les actions suivantes:

- Passer sur la perspective `Java`.
- Cliquer avec le bouton droit de la souris sur `Jmol-HEAD` et sélectionner `Properties` dans le menu contextuel.
- Dans la fenêtre `Properties for Jmol-HEAD`, sélectionner `Java Compiler`.
- Cocher `Use project settings`.
- Dans l'onglet `Style`, sélectionner `Warning` pour chaque combo-box, à l'exception de `Unqualified access to instance field` et `Undocumented empty block` pour lesquels vous pouvez sélectionner `Ignore`.
- Dans l'onglet `Advanced`, sélectionner `Warning` pour chaque combo-box, à l'exception de `Local variable declaration hides another field or variable`, `Usage of deprecated API` et `Usage of non-externalized strings` pour lesquels vous pouvez sélectionner `Ignore`.
- Dans l'onglet `Unused code`, sélectionner `Warning` pour chaque combo-box, à l'exception de `Parameter is never read` et `Unnecessary cast or 'instance of' operation` pour lesquels vous pouvez sélectionner `Ignore`.

### Exécuter et Débuguer Jmol

Eclipse peut être utilisé pour exécuter et débuguer Jmol directement dans Eclipse.

La classe principale est `org.openscience.jmol.app.Jmol`.

### Construire Jmol

Pour construire complètement Jmol sous Eclipse, effectuer simplement les actions suivantes: Cliquer avec le bouton droit de la souris sur `build.xml` et sélectionner `Run` / `Ant Build` dans le menu contextuel.