[Contents] [TitleIndex] [WordIndex

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 :

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 :

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 :

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

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

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

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

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 :

1.4.4. Suppression de fichiers sources

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

1.4.5. Ajout de bibliothèques

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

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.


2022-09-08 09:27