1. Procédures de développement

1.1. Avant-Propos

Avertissement

Vous voulez participer au développement de Scilab, et en particulier contribuer à l’amélioration, l’ajout et/ou la correction de son code. Nous souhaitons vous encourager et vous aider dans cet objectif.
Néanmoins, sachez que vous intégrez un projet important et opérationnel depuis plusieurs années. Ce projet respecte des règles, qui peuvent paraître arbitraires, mais qui lui assurent une indispensable cohérence. Certaines sont d’ailleurs explicites à la lecture plus ou moins détaillée du code. Vous trouverez ces recommandations dans les pages suivantes. Il est fortement conseillé de respecter ces règles pour conserver une certaine homogénéité d’un projet disposant d’une communauté de développeurs très hétérogènes. D’autres développeurs ou contributeurs peuvent lire voire modifier votre code.
Evidemment, tout ceci n'empêche pas de critiquer une règle et d'en proposer une autre. N'hésitez pas à le faire, mais avec justification.
Enfin, toutes exceptions confirment la règle. Celles-ci doivent donc être… exceptionnelles.

garder à l'esprit que le « provisoire » a souvent tendance à devenir définitif …

1.2. Introduction et objectifs

Les procédures décrites ci-dessous ont pour but d'assurer la qualité et la pérennité du développement de Scilab conformément aux critères suivants :

• portabilité,
• modularité,
• réutilisabilité,
• efficacité,
• lisibilité du code source, nécessaire dans une logique open source (partage et cohérence),

Les mesures prises pour assurer ces critères sont décrites ICI (section 7.3). Elles visent de plus à assurer la tracabilité des modifications réalisées au fur et à mesure des développements. Les principes utilisés sont les suivants :

• unicité des documents sources,
• renseignement des documents sources sous forme de commentaires,
• développement de bibliothèques spécifiques et génériques,
• regroupement des sections de code non portables dans des bibliothèques spécifiques,
• gestion informatisée de l'ensemble des documents sur une unique plateforme.

1.3. Dispositions de la programmation

Le programme Scilab est fondé sur la juxtaposition des modules le composant; (voir XXX)

Scilab est écrit en langage :

• Fortran,
• C,
• Java,
• Scilab
• XML.

Les paragraphes suivants décrivent les règles applicables et communes à tous fichiers et les règles de développements préconisées pour chacun de ces langages.

Remarque

À ce jour, il existe encore des fichiers qui ne respectent pas les règles émises dans ce chapitre. L’existant étant trop important, il n’est pas question de reprendre chaque fichier ne correspondant pas aux dispositions prises. Ces fichiers historiques sont mis à jour un par un uniquement lorsque ils sont corrigés ou modifiés.

1.3.1. Règles communes à tous les langages

Tout fichier source, quelque soit son langage, possède une entête précisant son copyright. Pour l’Inria, il s’écrira comme suit :

// copyright INRIA

• Le nom ou les initiales de l’auteur sont également autorisés.
  • Les commentaires, les noms des fichiers, des fonctions, des variables sont en langue anglaise
• Règles de présentation et d’écriture du code source Scilab :
  • Indentation simple (utilisation d'un pretty printer ???)
• Règles de nommage des fichiers et des variables
  • Règle simple (pas de blanc, pas d’accent caractère alphanumérique et caractère underscore)

1.3.2. Le langage Fortran

Le langage fortran utilisé dans Scilab est le fortran 77. Les commentaires doivent être visibles et indentés. La section décrivant l’algorithme doit être commentée.

1.3.3. Le langage C

• Règles de présentation et d’écriture du code source C
  • Indenté le source un minimum (votre éditeur préféré le fait très souvent pour vous) pour donner une lecture aisé.

  • Les commentaires respectent la forme comments et non pas la forme // comments

  • Les programmes sont en Code C et pas en code C++ (attention donc à la syntaxe)
  • On écrit char* pour les pointeurs et non pas la syntaxe orienté windows xxxxxxxxx
• Règles de nommage des fichiers, des fonctions et des variables
  • Les noms des variables et des fonctions sont significatifs et rédigés en langue anglaise
  • Les variables sont systématiquement initialisées et un commentaire est joint immédiatement à la suite (sur la même ligne si possible) afin de préciser à quoi elles servent si le nom utilisé n’est pas suffisamment explicatif
  • Les noms des fonctions sont significatifs et rédigés de la manière suivante : groupe de mot explicatif avec :

    • soit la première lettre de chaque mot en majuscule, exemple : CreateVarFromPtr

    • soit le caractère « _ » pour les séparer, exemple : create_var_from_ptr
• Pas d'historique de modification de fichier,

1.3.3.1. Les fichiers

Un fichier header est associé à tout fichier de code source C. Pour tout toto.c existe donc un toto.h . Le fichier header contient la définition des fonctions et leur données (input, output) codées dans le fichier code source. Le fichier code source contient le codage proprement dit complété des commentaires nécessaire à sa bonne compréhension. Les includes trop hiérarchiques seront évités.

1.3.3.1.1. Les fichiers header

Toutes les fonctions du code source sont définies dans le header. Des descriptions explicites précisent les variables et les types pour en faciliter la compréhension et l’utilisation lors d’interfaçage avec d’autres programmes. Quand des fonctions externes sont employées, elles sont déclarées dans le header en précisant les fichiers ou elles sont définies.

1.3.3.1.2. Les fichiers de code source C

Suite à la règle ci-dessus, un ficher code source C contient un et un seul fichier include : le fichier header. Pour faciliter la lecture du code, les fonctions seront distinguées en y ajoutant une ligne de commentaire sous forme de caractère étoile au début et à la fin du code de chaque fonction.

Gestion des erreurs ???

1.3.3.1.3. Arborescence des fichiers sources C

????????????

1.3.4. Le langage Scilab

• Règles de présentation et d’écriture du code source Scilab
  • Indentation simple (voir avec futur outil vincent)
• Règles de nommage des fichiers et des variables
  • Sans objet ou règle simple (pas de blanc, pas d’accent caractère alphanumérique et caractère underscore)

1.3.4.1. Les fichiers de code source Scilab

Il existe deux types de fichiers de code source Scilab : les fichiers d’extension .sci et les fichiers d’extension .sce. Les premiers correspondent à des fichiers de fonctions Scilab et les seconds à des fichiers de script d’exécution Scilab.

1.3.4.1.1. Le fichier de fonction(s)

Un fichier de fonction(s) peut contenir une ou plusieurs fonctions Scilab. Si le fichier contient plusieurs fonctions, la fonction principale du fichier de fonctions est la première fonction codée dans le fichier. Et dans ce cas, pour des raisons propres au logiciel Scilab, le nom du fichier de fonctions portera le même nom que la fonction principale.

1.3.4.1.2. Le fichier script d’exécution

Un fichier script d’exécution …

1.3.4.2. La fonction Scilab

Une fonction Scilab possède classiquement, et dans l’ordre si elles existent, une entête sous forme de commentaires, une partie correspondant à l’initialisation des variables, une partie de code et une dernière partie relative à la gestion des erreurs. Chaque fonction possède une entête mentionnant le résumé de la méthode et/ou de l’algorithme retenu dans la fonction. Cette entête suit immédiatement la déclaration de la fonction. L’entête contient également le nom ou les initiales de l’auteur de la fonction. Dans le cas ou l’auteur s’inspire d’un autre concepteur pour l’écriture de son code, il est bienséant de le nommer.

Rappel : L’aide de la fonction n’est pas contenue dans la fonction. Elle est rédigée par ailleurs et rendu accessible via le help interactif de Scilab (voir code XML).

Suite au rappel ci-dessus, pour une fonction n’ayant pas d’aide interactive prévue dans le help de Scilab (Cas par exemple de fonctions codées pour la passerelle), l’entête de la fonction contiendra l’aide nécessaire à sa bonne compréhension. Les commentaires d’aide à la lecture de la fonction à l’intérieur du code de celle-ci sont encouragés.

Vous trouverez ci-dessous un exemple de fonction.

//
// Author :
//
// REVISION variables svn %W% %G% ?????
//
// Mettre un exemple

Quid sur variables globales ???? y a-t-il qqchose pour les reconnaître ou pas en majuscule avec des %

1.3.5. Le langage Java

1.3.5.1. Formatage du code

A voir : Utilisation d'un outil de vérification comme PMD (http://pmd.sourceforge.net/)

1.3.5.2. Tests unitaires

A voir : http://emma.sourceforge.net/ Couverture de code http://www.junit.org/index.htm Tests unitaire http://jtiger.org/ Tests unitaire

Obligatoire pour chaque classe, déclaré dans les annotations...

1.3.6. Le langage XML

Le langage XML est utilisé dans Scilab pour la description de l’aide en ligne. Les sources de l’aide en ligne respectent une DTD élaborée par l’équipe et respectant la norme XML. Les commentaires sont donc de la forme <! xxxxxxxxxxxxxxxxxxxxxxxxxxxxx !>

1.4. Réalisation des évolutions

• Un développement consiste en :
  • des modifications des fichiers sources,
  • l'ajout de fichiers sources,
  • la suppression de fichiers sources,
  • l'ajout de bibliothèques,
  • modification de la documentation,
  • l'ajout de tests de validation.

Ces évolutions portent sur une version donnée de Scilab.

1.4.1. Gestion des fichiers sources

Les différents fichiers source du logiciel sont gérés par SVN suivant les procédures décrites ci-dessous : Un répertoire SVN est crée dans chaque répertoire (bibliothèque) associé aux fichiers sources. Tous les fichiers sources sont stockées dans ce répertoire Tous les fichiers sources portent en commentaires le numéro de révision, l'auteur, la date de création, le fichier Makefile générant les fichiers binaires, les bibliothèques et les exécutables sont également stockés dans le répertoire SVN, le niveau branch est utilisé pour différencier divers développements effectuées en parallèle.

1.4.2. Modification des fichiers sources

Les modifications sont réalisées conformément aux principes définis dans ce manuel sur un ou plusieurs fichiers sources extraits du répertoire SVN . Ces modifications sont archivées à nouveau dans le répertoire SVN par la commande xxx dès lors qu’elles ont été testées convenablement. C’est à ce stade que l’on commentera de façon pertinente les modifications apportées.

1.4.3. Ajout de fichiers sources

L'ajout d'un fichier source suit les étapes suivantes :

• Création du fichier source à partir d'un fichier type (un fichier existant ou le fichier xxx du répertoire )
• Modification du fichier Makefile.am pour la génération de la bibliothèque (on vérifiera en particulier les règles de dépendance)
• Génération du nouveau fichier Makefile.in via automake
• Développement et test
• Archivage du fichier source dans le repertoire SVN avec un numéro de révision compatible avec la version en cours de développement
• Archivage nouveau fichier Makefile.am dans le repertoire SVN (cette étape est réalisée par la personne responsable du repository Scilab).

1.4.4. Suppression de fichiers sources

La suppression d'un fichier source suit les étapes suivantes :

• Suppression du fichier source dans le répertoire courant
• Suppression de la référence à ce fichier dans le fichier Makefile.am En revanche, on ne supprimera pas ce fichier dans le répertoire SVN.
• Regénération du nouveauf fichier Makefile.in via automake

1.4.5. Ajout de bibliothèques

L'ajout d'une bibliothèque suit les étapes suivantes :

• Confirmation de la compatibilité de la license
• Création d'un nouveau répertoire dans répertoire src/XXX (XXX étant le langage)
• Ajout de fichiers sources dans ce répertoire
• Création du fichier Makefile.am gérant ce répertoire (s'inspirer d'un autre Makefile.am)
• Ajout du Makefile dans la liste des fichiers à générer dans le configure.ac
• Modification du fichier modules/Makefile.am (ou libs/Makefile.am) pour ajouter dans la variable SUBDIRS le nom du répertoire du module
• Modification du fichier modules/Makefile.am pour ajouter à la variable libscilab_la_LIBADD le nom de la librairie libtool (.la)
• Création du répertoire SVN et archivage
• Modification de la procédure générale d'installation pour tenir compte de cette nouvelle bibliothèque.

1.4.6. Pour les contributions acceptées

Remarque

On ne copiera pas les répertoires SVN. Si SVN est utilisé localement on recréera localement ces répertoires et on n'utilisera que le niveau sequence du numéro de révision.

1.4.7. Nouvelle version de Scilab

La création d'une nouvelle version de référence de Scilab suit les phases décrites pour les développements, la génération de la nouvelle version étant réalisée par intégration de divers branch existantes.

1.5. Création de l'exécutable

Dans le répertoire principal xxxxxxxxx se trouve la commande d'installation yyyy qui lance les différents Makefile dans chacun des répertoires.

1.5.1. Précautions d'utilisation

Afin de créer des fichiers exécutables portant un numéro de révision, il est nécessaire d'extraire tous les fichiers sources des répertoires SVN par la commande SVN xxx après avoir archivé les modification apportées par la commande SVN yyy

1.5.2. Gestion des fichiers Makefile

Les fichiers Makefile/Makefile.in sont générés et mis à jour automatiquement par les développeurs alors qu'une modification a été détecté sur un fichier Makefile.am

1.6. Documents associés aux développements

1.7. Précautions et règles d'utilisation de l'outil SVN

1.8. Sauvegarde des développements et de la documentation

Chaque développeur est responsable de la sauvegarde de ses développement réalisés en locale sur sa ou ses propres machines. A ce titre il

Chaque nouvelle version de référence est sauvegardée ainsi que le repository SVN, via les moyens et les procédures en viguer au sein de l'institut.