BuildNewPlugin

Un article de OpenMASKWiki.

Jump to: navigation, search

Un plugin OMK est une bibliothèque C++ qui peut être greffée dynamiquement à une application OpenMASK lors de son démarrage. Un plugin permet d'étendre les fonctionnalités des objets de simulation réutilisés dans cette application. Un plugin doit respecter des règles d'interface avec OpenMASK.
L'intégration d'un plugin OpenMASK est assurée par la bibliothèque OBT Documentation.
Nous proposons dans ce document, un modèle d'organisation et des squelettes de fichiers pour vous faciliter la réalisation et la distribution d'un nouveau plugin.

Sommaire

Modèle de plugin OMK

Un plugin OMK est un plugin C++ basé sur :

  • la génération d'un projet de programmation par cmake
  • une proposition d'organisation des répertoires
  • des conventions de nommage des différents types de fichiers

Un squelette que vous pourrez personnaliser est disponible sur le site OpenMASK, soit sous forme d'un package compatible windows 7, soit dans le dépôt SVN sous le répertoire OMKPluginSquelette.
Nous proposons l'organisation suivante des répertoires :

Module
 build
 cmake
 config-tests
 documentation
 inst
 Source
   Module
     Doc
     Source

Il est important de publier les différentes informations définissant le plugin et son contenu afin que ses composants puissent être ré-utilisés soit par un expérimentateur dans un fichier de configuration, soit par un programmeur pour réaliser de nouveaux composants. Ces informations seront diffusées par la documentation en ligne et des exemples de fichiers de configuration.

Version simplifiée

Pour un plugin simple ne comprenant qu'un module vous pouvez simplifier la hierarchie en supprimant le découpage en modules :

Module
 build
 cmake
 config-tests
 Doc
 inst
  include
  documentation
  lib
 Source

Exemple Hello World

Pour être certain de vous fournir un squelette qui fonctionne bien, nous allons instancier les modèles de fichier sur l'exemple classique "Hello World".
Cet exemple décrit une classe d'objet de simulation qui imprime une sentence à chaque fois que l'objet est activé, du style :

toto vous dit : Hello world

Hello world est le paramètre de configuration de l'instance toto de notre classe. Deux instances de cette classe peuvent vous montrer le jeu d'imbrication de fréquences différentes.

Dans les fichiers modèles, les parties qui ne sont pas utilisées par notre exemple seront laissées en commentaires. A vous de les réactiver si besoin.
Dans certaines versions, au CMake, vous ajouterez la nouvelle entrée : MINIMAL_BUILD pour ne pas intégrer Ogre 3D (variable utilisée dans le fichier FindOpenMASK4.cmake).

Développement du plugin

Fichiers CMake

Il suffit de mettre à jour les différents fichiers CMakeLists.txt

Répertoire .

  • mettre à jour le fichier CMakeLists.txt :
    • nom du projet (ou plugin)
    • les dépendances du projet. Les dépendances suivantes : OMK4, OBT, Ogre3D et OIS, WM4, qui sont indispensables, sont déjà dans le modèle.

Répertoire ./Source

  • mettre à jour le fichier CMakeLists.txt
    • nom des répertoires de chaque modules sources de votre plugin

Pour chaque Répertoire ./Source/modulexx/Source

  • mettre à jour le fichier CMakeLists.txt :
    • nom du module
    • une variable d'export du type : -DOMKMODULEXX_EXPORTS
    • les dépendances libs, include, link . Celles d'OMK4, OBT, Ogre3D, OIS et WM4, sont déjà dans le modèle.

Répertoire ./Doc

  • mettre à jour le fichier Doxyfile
    • nom du projet

Fichiers plugin

Dans le répertoire Source/Module/source, trois fichiers définissent un module

OMKxx_api.h
OMKxx_plugin.h
OMKxx_plugin.cpp

Remplacer xx par le nom du module.
On vous demande de respecter notre convention de définition des noms de fichier.

Fichier OMKxx_api.h

  • définir le nom du namespace associé à ce plugin
  • mettre à jour éventuellement la variable EXPORT (en MAJUSCULES) si vous travaillez sous windows

Fichier OMKxx_plugin.h

  • mettre à jour les informations décrivant votre plugin

La déclaration du plugin est un service assuré par OBT.

Fichier OMKxx-plugin.cpp

pas de mise à jour particulière pour les plugin ordinaires.

Fichiers de documentation

La documentation est fabriquée par Doxygen.
Nous suggérons d'avoir une ou plusieurs pages introductives dans le répertoire Doc et de placer des directives Doxygen dans vos fichiers de code.

Fichier Doxyfile

C'est le fichier de configuration de Doxygen. Vous devrez personnaliser le modèle proposé dans le squelette. Le minimum de personnalisation est de définir le nom du projet.

Fichier module_main.dox.h

Ce fichier d'exemple décrit la page principale de la documentation de votre module. Vous pouvez vous inspirer du modèle fourni dans le squelette de plugin pour la rédiger.
Si votre plugin contient beaucoup de composants, il est conseillé de rédiger différentes pages complémentaires pour les groupes de composants que vous pouvez identifier.

Fichier module_page.dox.h

Ce fichier d'exemple décrit une page secondaire relative à un sujet particulier de votre plugin.

Commentaires en ligne des fichiers de code

Vous trouverez également dans les fichiers exemples de composants OpenMASK, les directives Doxygen suggérées. Il est important de préciser, au minimum, pour chaque nouveau composant :

  • le nom du plugin à charger dans le fichier de configuration pour disposer de ce composant.
  • son nom de classe
  • tous ses paramètres avec leur identifiant, leur type et les différentes valeurs initiales possibles

Fichiers de composants OMK

Tous les fichiers que vous mettrez dans le répertoire Source/Module/source seront les programmes sources de vos nouveaux composants OMK.
Nous proposons la convention suivante des noms de classe :

  • PEMaClasseOSO avec
    • PE étant une abréviation de PluginExample, le nom de votre plugin
    • MaClasse étant le nom de votre nouvelle classe
    • OSO étant un suffixe désignant une classe de type "objet extensible"

Une introduction à la programmation d'un nouveau composant OpenMASK est fournie dans cette page BuildNewOMKComponent.
Le cas particulier de la programmation d'un service de présentation est décrit dans cette page BuildNewServ.

Fichiers de configuration

Dans le répertoire config-tests, nous recommandons de fournir des exemples de fichiers de configuration utilisant les composants de votre pulgin. Vous fournirez une version mono-processus (sans MPI ) et une version multi-proceessus (avec MPI).


Distribution du plugin

Cmake

Recompilation

La distribution de vos sources via le modèle que nous avons proposé, implique que la personne qui les a récupérés puisse les recompiler avec Cmake à partir de vos fichiers cmake.

Répertoire ./cmake

Pour permettre l'intégration de votre bibliothèque en dépendance d'un autre projet de développement OpenMASK, nous vous suggérons de mettre à disposition un fichier FindVotreLib.cmake selon le modèle que vous trouverez dans le répertoirecmake.

Fiche d'identification

Il est bon de fournir des informations sur votre pluhgin

  • chemin de localisation de la bibliothèque dans la forge
  • nom de la bibliothèque
  • nom du namespace associé
  • noms des identificateurs de trace disponibles

Classes disponibles

Pour chaque classe publique, il faut également donner des informations d'accès.

  • nom de chaque classe
  • Id OpenMASK de chaque classe
  • Paramètres :
    • libellé du paramètre
    • type de donnée
    • valeur par défaut

Consignes d'installation

Soit l'installation de votre plugin est standard sinon il faut préciser les points particuliers.

Exemples

Il est utile de fournir des exemples de fichiers de configuration utilisant les composants de votre plugin.

Navigation