Developing OpenSim Addins
From OpenSimulator
 |
Languages: |
|
This page explains how to develop, package and distribute OpenSimulator region module addins. It is written for developers who wish to provide additional functionality beyond what comes in the core distribution of OpenSim, and who wish to distribute it to others in binary form. These instructions pertain to region modules that run at the simulators. It is assumed that you are already familiar with the basics of developing region modules.
If you are looking for using and installing 3rd-party addins, please see this other page.
Contents |
The Final Package
An addin example can be found at https://github.com/diva/diva-distribution/tree/master/addon-modules/02AddinExample. This is a very simple example that extends the simulator with the capability of presenting a web form to a user asking for first and last name, and storing the form data in a Comma Separated Value (CSV) file. The Web form will be available at http://yoursim/diva/addinexample. The final addin package contains:
- the region module dll (Diva.AddinExample.dll)
- an external dll (CsvHelper.dll)
- an .ini file (AddinExample.ini)
- an html file (AddinExample.html)
These are all the files we need for OpenSim users to run the addin in their installations.
Addin Directives
As usual, the region module should be annotated as an OpenSim Region Module:
[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule", Id = "AddinsExampleModule")]
public class AddinExampleModule : ISharedRegionModule
{
...
}
Additionally, the assembly that contains the region module should contain the following directives:
// These lines are required
[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")]
// The next lines are not required, and if they exist, they are specific to your addins
[assembly: ImportAddinAssembly("CsvHelper.dll")]
[assembly: ImportAddinFile("AddinExample.ini")]
[assembly: ImportAddinFile("AddinExample.html")]
The first directive [assembly: Addin("Diva.AddinExample", OpenSim.VersionInfo.VersionNumber + ".1")] establishes the public name of your addin: this is what users will see. Pay special attention to the version number. While you can use any version number you want, it is strongly advised that you tie your addin's version number with the OpenSim version against which you are compiling your code. The reason for this is simple: .NET is very picky about binary compatibility, therefore you should inform your users about which version of OpenSim this addin is compatible with. The most direct way of passing that information along is to add it to your addin's version number. In this case, we're using the first few digits to denote OpenSim's version number and the last digit to denote this addin's own version. If we were to evolve this addin in between OpenSim releases, that last digit would increase to 2, while the first few digits would remain the same.
The second directive [assembly: AddinDependency("OpenSim.Region.Framework", OpenSim.VersionInfo.VersionNumber)] establishes the dependency with the concrete OpenSim dll that this addin extends. All region module addins extend OpenSim.Region.Framework. Again, the version number there should be the current OpenSim version number, because that is the dll that you are compiling your code against. For an explanation of how versioning works see Installing_3rd_party_addins#Versioning
The third and fourth directives give a description and authorship information for your addin.
The last three directives include additional files in the package that are necessary for the addins to work in your users' environments. For your addins, these lines will either not be there, or they will include different files/libraries. In this case, we're including the example's ini file, the html form, and the external library, CsvHelper.dll, which is needed for AddinExample to work. The directive [assembly: ImportAddinAssembly("CsvHelper.dll")] has two purposes: (1) it includes that dll in the package and (2) it informs the user's runtime that when our addin is loaded into memory, that dll should also be loaded.
Configuration
A very important part of the process has to do with configuration of your addin. Rather than forcing users to manually edit their OpenSim.ini files and add the configuration section pertaining to your addin, we encourage the use of modular configurations. In modular configurations, your components are responsible for reading their own configuration files.
Take a look at how this is done in the AddinExample module: https://github.com/diva/diva-distribution/blob/master/addon-modules/02AddinExample/AddinExampleModule.cs
In the Initialise method, before the meat of that method, we call LoadConfiguration(...), but only if the main configuration doesn't have the relevant section:
public void Initialise(IConfigSource config)
{
// We only load the configuration file if the main config doesn't know about this module already
IConfig cnf = config.Configs["AddinExample"];
if (cnf == null)
{
LoadConfiguration(config);
cnf = config.Configs["AddinExample"];
if (cnf == null)
{
m_log.WarnFormat("[Diva.AddinExample]: Configuration section AddinExample not found. Unable to proceed.");
return;
}
}
LoadConfiguration is declared further down. Here it is:
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]: Configuration file not merged");
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");
}
}
This method uses OpenSim.Framework.Util.MergeConfigurationFile, which reads the ConfigDirectory variable from the OpenSim configuration and checks if this module's configuration file is already there. If it is, then it simply merges it with the OpenSim configurations. If it isn't, it copies the configuration file it brought with it in the package to the ConfigDirectory, and warns the operator that they should edit it to their needs.
Packaging the Addin
Compile your code as usual, and make sure that all the files that are to be included are all in the same directory. In our example, that is ensured by the following directives in 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>
According to these directives, all necessary files end up in a bin folder two levels above.
To package the files, we use the mautil command line tool that comes in OpenSim bin.
$ /path/to/mautil.exe pack bin/Diva.AddinExample.dll
This creates a file called Diva.AddinExample_osversion.1.mpack. This is the addin package that will be distributed and installed at the user's sites.
Note that .mpack files are compressed (zip) archives. You can open them and verify their contents using tools for inspecting zip files.
Distributing Your Addins
In order to make your addins available to others, you need to create your own addin repository and host it in some web server.
To create the repository, create a folder somewhere and place all of your addin packages (.mpack) in it. Then:
$ /path/to/mautil.exe rep-build /path/to/repo/folder
This will create additional index files with the right entries. All you need to do next is to upload the entire contents of this folder onto a Web server. For example, http://metaverseink.com/repo/ shows the index.html of this repo that shows all available addins.
Finally, you need to let users know about the URL of your repository, so they can add it to their registries and install addins from your repository. You can add your repo here.
