Guide du Développeur Jmol


Table des matières

1. Prérequis
2. Récupérer Jmol par CVS
3. Construire Jmol
4. Exécuter Jmol
5. Règles de Programmation
6. Générer une livraison
7. Packaging
8. Travailler avec CVS
Etiquetter sous CVS
Branches CVS
Accéder à une branche
Créer une branche
Fusionner des branches
9. Utilisation d'Eclipse
Configuration du CVS Repository
Récupérer Jmol depuis CVS
Configuration d'Eclipse pour construire Jmol
Exécuter et Débuguer Jmol
Construire Jmol

Chapitre 1. Prérequis

Chapitre 2. 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
      

Chapitre 3. Construire Jmol

Prérequis:

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
      

Chapitre 4. 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
      

Chapitre 5. 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

Chapitre 6. 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.

Chapitre 7. 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)

Chapitre 8. 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
          

Chapitre 9. 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.