Developing OpenSim Addins/fr

Latest revision as of 03:55, 26 February 2015

Languages:

English    Français

Cette page explique comment développer, créer des paquets et distribuer des modules de région complémentaires poour OpenSimulator. Elle est écrite pour les développeurs qui désirent apporter des fonctionnalités supplémentaires en plus de celles apportées dans la distribution de base d'OpenSim, et qui souhaitent partager ces modules sous forme binaire.Ces instructions concernent les les modules de region qui s'exécutent sur des simulateurs. On suppose que vous êtes déjà familiarisé avec les bases du développement de modules de régions.

Si vous cherchez à utiliser et installer des modules complémentaires existants, veuillez vous référer à cette autre page.

[edit] Le package final

Vous trouverez un exemple de module complémentaire ici : https://github.com/diva/diva-distribution/tree/master/addon-modules/02AddinExample. C'est un exemple très simple qui ajoute une fonctionnalité au simulateur en pésentant un formulaire web à l'utilisateur pour lui demander son prénom et son nom. Les données recueillies sont stockées un fichier CSV composées de valeurs séparées par des virgules. Le formulaire Web sera disponible ici : http://yoursim/diva/addinexample. Le package final du module complémentaire contient :

• la dll du module de région (Diva.AddinExample.dll)
• une dll externe (CsvHelper.dll)
• un fichier .ini (AddinExample.ini)
• un fichier html (AddinExample.html)

Ces fichiers sont tous nécessaires pour que les utilisateurs d'OpenSim puissent faire fonctionner ce module complémentaire depuis leur installation ?

[edit] Directive pour les modules complémentaires

Comme d'habitude,les modules de régions doivent être annotés comme un module de région OpenSim Region:

    [Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule", Id = "AddinsExampleModule")]
    public class AddinExampleModule : ISharedRegionModule
    {
      ...
    }

Deplus, l'assembly qui contient le module de région devrait comprendre les directives suivantes :

// Ces lignes sont requises 
[assembly: Addin("Diva.AddinExample", OpenSim.VersionInfo.VersionNumber + ".1")]
[assembly: AddinDependency("OpenSim.Region.Framework", OpenSim.VersionInfo.VersionNumber)]
[assembly: AddinDescription("Example of how to create OpenSim Addins")]
[assembly: AddinAuthor("Diva Canto")]

// Les lignes suivantes ne sont pas requises, et si elles existent, elles seront spécifique à vos modules complémentaires (Addin)
[assembly: ImportAddinAssembly("CsvHelper.dll")]
[assembly: ImportAddinFile("AddinExample.ini")]
[assembly: ImportAddinFile("AddinExample.html")]

La première directive [assembly: Addin("Diva.AddinExample", OpenSim.VersionInfo.VersionNumber + ".1")] établit le nom public de votre addin: c'est ce que les utilisateurs verront. Prêtez une attention particulière au numéro de version du module. Même si vous pouvez utiliser n'importe quel numéro de version, il est fortement conseillé d'attacher le numéro de version de votre addin à celui de la version OpenSim que vous avez utilisée pour compiler votre code. La raison à cela est simple : .NET est très sensible à la compatibilité binaire, c'est pourquoi vous devez informer les utilisateurs à propos de la version d'OpenSim compatible avec votre addin. La façon la plus directe de passer cette information est de l'indiquer dans le numéro de version de votre addin. Ainsi, nous utilisons les premiers chiffres pour indiquer le numéro de version d'OpenSim et le dernier chiffre pour désigner la version de l'addin. Si l'addin devait évoluer tout en utilisant la même version d'OpenSim, ce dernier chiffre passerait à 2, tandis que lespremiers chiffres resteraient les mêmes.

La deuxième directive [assembly: AddinDependency("OpenSim.Region.Framework", OpenSim.VersionInfo.VersionNumber)] établit la dépendance avec la dll OpenSim que cet addin va compléter. Tous les modules de région complémentaires prolongent OpenSim.Region.Framework. Aussi, le numéro de version devrait être le numéro de version d'OpenSim utilisé car c'est la dll avec laquelle vous avez compiler votre code. Pour plus d'information sur le fonctionnement du versionig référez-vous à la page Installing_3rd_party_addins#Versioning

Les troisième et quatrièmes directives donnent une description et les informations de paternité de votre addin.

Les dernières directives incluent des fichiers additionnels dans le package. Ces fichiers sont nécessaires pour que le module complémentaire fonctionne dans les environnements de vos utilisateurs. Pour vos addins, soit ces lignes n'existeront pas soit elles incluront différents fichiers/bibliothèques. Dans ce cas, nous avons ajouté le fichier ini de l'exemple, le formulaire html et la bibliothèque externe, CsvHelper.dll, qui sont nécessaires pour que l'addin exemple fonctionne. La directive [assembly: ImportAddinAssembly("CsvHelper.dll")] a deux objectifs: (1) elle inclut cette dll dans le package et (2) elle informe les utilisateurs que quand votre addin est chargé en mémoire, cette dll devrait l'être aussi.

[edit] Configuration

Une part importante du processus se passe au travers de la configuration de votre addin. Plutôt que de forcer les utilisateurs à éditer manuellement leurs fichiers OpenSim.ini et d'ajouter une section de configuration pour votre addin, nous vous encourageons à utiliser des configurations modulaires. Dans des configurations modulaires, vos composants vont lire eux-mêmes leurs propres fichiers de configuration.

Jetez un oeil sur la méthode utilisée dans le module AddinExample : https://github.com/diva/diva-distribution/blob/master/addon-modules/02AddinExample/AddinExampleModule.cs

Dans la méthode d'initialisation, avant le coeur de cette méthode, nous appelons LoadConfiguration(...), mais seulement si la configuration principale ne comporte pas de section pertinente:

       public void Initialise(IConfigSource config)
       {
           //Nous chargeon le fichier de configuration uniquemeny si la config principale ne sait rien à propos de ce module
           IConfig cnf = config.Configs["AddinExample"];
           if (cnf == null)
           {
               LoadConfiguration(config);
               cnf = config.Configs["AddinExample"];
               if (cnf == null)
               {
                   m_log.WarnFormat("[Diva.AddinExample]: La section de configurationConfiguration pour AddinExample n'a pas été trouvée. Impossible de continuer");
                   return;
               }
           }

LoadConfiguration est déclaré plus bas, la voici:

       private void LoadConfiguration(IConfigSource config)
       {
           string configPath = string.Empty;
           bool created;
           if (!Util.MergeConfigurationFile(config, "AddinExample.ini", Path.Combine(AssemblyDirectory, "AddinExample.ini"), out configPath, out created))
           {
               m_log.WarnFormat("[Diva.AddinExample]: Fichier de configuration non fusionné");
               return;
           }
           if (created)
           {
               m_log.ErrorFormat("[Diva.AddinExample]: PLEASE EDIT {0} BEFORE RUNNING THIS ADDIN", configPath);
               throw new Exception("Addin must be configured prior to running");
           }
       }

Cette méthode utiliser OpenSim.Framework.Util.MergeConfigurationFile, qui va lire la varibale ConfigDirectory dans la configuration OpenSim et contrôler si la configuration du module est déjà là. Si c'est le cas, alors elle est simplement fusionnée avec les configurations d'OpenSim. Sinon, le fichier de configuration associé au package est copié vers un fichier de configuration non fusionné et averti les opérateurs qu'ils devront l'éditer selon leur besoins.

[edit] Empaqueter l'Addin

Compilez votre code comme d'habitude, et assurez-vous que tous les fichiers qui doivent être inclus sont tous dans le même répertoire. Dans notre exemple, cela est effectué par les directives qui sont dans prebuild.xml:

 <Files>
   <Match pattern="*.cs" recurse="true"/>
   <Match pattern="*.ini" buildAction="Copy" destination="../../bin/" />
   <Match pattern="*.html" buildAction="Copy" destination="../../bin/" />
   <Match pattern="*.dll" recurse="true" buildAction="Copy" destination="../../bin/" />
 </Files>

Selon ces directives, tous les fichiers nécessaires se retrouvent dans un dossier bin deux niveaux au-dessus.

Pour empaqueter les fichiers, nous utilisons mautil outil de ligne de commande qui se trouve dans le dossier bin d'OpenSim.

 $ /path/to/mautil.exe pack bin/Diva.AddinExample.dll

Cela crée un fichier appelé Diva.AddinExample_osversion.1.mpack. C'est le package de l'addin qui sera distribué et installé dans les sites utilisateur.

Notez que les fichiers .mpack files sont des archives compressées (zip). Vous pouvez les ouvrir et vérifuer leur contenu avec des outils pour inspecter les fichiers zip.

[edit] Distribuer des modules complémentaires

Pour diffuser vos addins, vous devez créer votre propre dépôt et l'héberger sur un serveur Web.

Pour créer un dépôt, créez un dossier quelque part et placez-y tous vos packages (.mpack). Ensuite :

 $ /path/to/mautil.exe rep-build /path/to/repo/folder

Cela va créer un index additionnel de fichiers avec les droits d'entrée. Tout ce dont vous avez besoin de faire après est de télécharger tout le contenu des ce dossier sur un server Web. Par exemple : http://metaverseink.com/repo/ montre le fichier index.html de ce dépôt qui va afficher tous les addins disponibles.

Finalement, vous avez besoin de donner l'URL de votre dépôt aux utilisateurs, ainsi ils pourront l'ajouter à leur registre et installer les addins depuis votre dépôt. Vous pouvez ajouter votre dépôt ici.