Developing OpenSim Addins - Revision history

Acryline at 11:57, 16 February 2015

2015-02-16T11:57:36Z

Diva: /* Configuration */

2015-01-08T18:43:47Z

‎Configuration

Diva: /* Configuration */

2015-01-08T18:43:31Z

‎Configuration

Diva: /* Configuration */

2015-01-08T18:43:13Z

‎Configuration

Diva at 03:37, 5 January 2015

2015-01-05T03:37:27Z

Diva: /* Packaging the Addin */

2015-01-05T03:33:23Z

‎Packaging the Addin

Diva: /* Configuration */

2015-01-05T03:31:11Z

‎Configuration

Diva: /* Configuration */

2015-01-05T03:30:56Z

‎Configuration

Diva: /* Addin Directives */

2015-01-05T03:27:56Z

‎Addin Directives

Diva: /* Addin Directives */

2015-01-05T03:24:41Z

‎Addin Directives

← Older revision		Revision as of 11:57, 16 February 2015
Line 1:		Line 1:
		+	{{Languages\|Developing_OpenSim_Addins}}
	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 [[New Region Modules\|region modules]] that run at the simulators. It is assumed that you are already familiar with the basics of developing region modules.		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 [[New Region Modules\|region modules]] that run at the simulators. It is assumed that you are already familiar with the basics of developing region modules.

@@ Line 83: / Line 83: @@
+         }
-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.
+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 ==

@@ Line 76: / Line 76: @@
                  return;
+             }
              if (created)
+             {
@@ Line 82: / Line 81: @@
                  throw new Exception("Addin must be configured prior to running");
+             }
+         }

@@ Line 48: / Line 48: @@
 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(...), which is declared further down. Here it is:
+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:
-         private void LoadConfiguration(IConfigSource config)
+         public void Initialise(IConfigSource config)
+         {
-             IConfig cnf = config.Configs["Startup"];
+            // We only load the configuration file if the main config doesn't know about this module already
              if (cnf == null)
+             {
-                 // We need to copy the one that comes in the package
+                 LoadConfiguration(config);
-                if (!Directory.Exists(configDirectory))
+                 cnf = config.Configs["AddinExample"];
-                    Directory.CreateDirectory(configDirectory);
+                 if (cnf == null)
-−
+                 {
-                 string embeddedConfig = Path.Combine(AssemblyDirectory, "AddinExample.ini");
+                    m_log.WarnFormat("[Diva.AddinExample]: Configuration section AddinExample not found. Unable to proceed.");
-                 File.Copy(embeddedConfig, configFile);
+                    return;
-                 m_log.ErrorFormat("[Diva.AddinExample]: PLEASE EDIT {0} BEFORE RUNNING THIS ADDIN", configFile);
-                 throw new Exception("AddinExample addin must be configured prior to running");
+             }
-−
-             if (File.Exists(configFile))
+LoadConfiguration is declared further down. Here it is:
+             {
-                 // Merge
+                 m_log.WarnFormat("[Diva.AddinExample]: Configuration file not merged");
-                config.Merge(new IniConfigSource(configFile));
+                return;
+             }
-This method 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.
+            if (created)
-'''TECH TIP''': There is a utility method available in OpenSim.Framework that implements the generic version of the code above. Check for it in '''OpenSim.Framework.Util.MergeConfigurationFile'''.
+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 ==

← Older revision		Revision as of 03:37, 5 January 2015
Line 1:		Line 1:
−	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. These instructions pertain to [[New Region Modules\|region modules]] that run at the simulators. It is assumed that you are already familiar with the basics of developing region modules.	+	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 [[New Region Modules\|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 [[Installing 3rd party addins\|this other page]].		If you are looking for using and installing 3rd-party addins, please see [[Installing 3rd party addins\|this other page]].

← Older revision		Revision as of 03:33, 5 January 2015
Line 101:		Line 101:

	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.		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 ==		== Distributing Your Addins ==

@@ Line 40: / Line 40: @@
 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 AddinExample 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.
+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 ==

@@ Line 23: / Line 23: @@
 Additionally, [https://github.com/diva/diva-distribution/blob/master/addon-modules/02AddinExample/Properties/AssemblyInfo.cs the assembly] that contains the region module should contain the following directives:
   [assembly: '''Addin'''("Diva.AddinExample", OpenSim.VersionInfo.VersionNumber + ".1")]
   [assembly: '''AddinDependency'''("OpenSim.Region.Framework", OpenSim.VersionInfo.VersionNumber)]
@@ Line 28: / Line 29: @@
   [assembly: '''AddinAuthor'''("Diva Canto")]
   [assembly: '''ImportAddinAssembly'''("CsvHelper.dll")]
   [assembly: '''ImportAddinFile'''("AddinExample.ini")]