Installing 3rd party addins - Revision history

Manni at 09:40, 16 December 2025

2025-12-16T09:40:21Z

Diva: /* Versioning */

2015-01-04T19:33:16Z

‎Versioning

Diva: Added more clarifications about versioning

2015-01-04T19:31:57Z

Added more clarifications about versioning

Diva: Simplified mautil use by eliminating the -p parameter (not needed when run from bin)

2015-01-04T19:18:05Z

Simplified mautil use by eliminating the -p parameter (not needed when run from bin)

Diva: /* Uninstalling Addins */

2015-01-02T22:44:02Z

‎Uninstalling Addins

Diva at 22:08, 2 January 2015

2015-01-02T22:08:21Z

Diva at 22:45, 31 December 2014

2014-12-31T22:45:27Z

Diva at 22:40, 31 December 2014

2014-12-31T22:40:25Z

Diva at 20:39, 31 December 2014

2014-12-31T20:39:47Z

Diva at 18:07, 31 December 2014

2014-12-31T18:07:42Z

← Older revision		Revision as of 09:40, 16 December 2025
Line 1:		Line 1:
		+	{{Quicklinks\|Installing_3rd_party_addins}}
	This page explains how to install, update and uninstall 3rd-party addins for the simulator server in a systematic way. 3rd-party addins are packages created around binary distributions of region modules, possibly with additional external libraries and resources, that extend the simulator with additional functionality. Note that 3rd-party addins here refers to '''binary packages''' of OpenSim extensions; this is different from extensions available as source code, which you may already be familiar with, and for which you may already have a process in place for building and deploying into your grid. 3rd-party addins give the providers the option to keep the source code proprietary, and give you a relatively simple process for integrating those extensions into your installation of OpenSim and to evolve them in relative independence from updates to OpenSim core.		This page explains how to install, update and uninstall 3rd-party addins for the simulator server in a systematic way. 3rd-party addins are packages created around binary distributions of region modules, possibly with additional external libraries and resources, that extend the simulator with additional functionality. Note that 3rd-party addins here refers to '''binary packages''' of OpenSim extensions; this is different from extensions available as source code, which you may already be familiar with, and for which you may already have a process in place for building and deploying into your grid. 3rd-party addins give the providers the option to keep the source code proprietary, and give you a relatively simple process for integrating those extensions into your installation of OpenSim and to evolve them in relative independence from updates to OpenSim core.

@@ Line 99: / Line 99: @@
 '''Version numbers of all kinds are mainly annotations for people. The ground truth is always in the binary signature of dlls.'''
-Here some concrete examples:
+Here are some concrete examples:
 * Addin Foo requires OpenSim 0.8.1, and is being installed in OpenSim 0.8.1 ==> Addin compatibility ok. Binary compatibility ''likely'' ok.
 * Addin Foo requires OpenSim 0.7 and is being installed in OpenSim 0.8.1 ==> Addin compatibility ok. Binary compatibility ''likely'' will fail, depending on a number of things. If Foo has been compiled against OpenSim 0.7, then it will surely fail, because the OpenSim APIs tend to change substantially between releases. But if Foo was compiled against 0.8.1, but the developers of Foo forgot to update the declared dependency, then binary compatibility will be ok, and the plugin will be successfully installed.
 * Addin Foo requires OpenSim 0.9.0 and is being installed in OpenSim 0.8.1 ==> Addin compatibility will fail. Foo won't even get to run to check binary compatibility.

← Older revision		Revision as of 19:31, 4 January 2015
Line 96:		Line 96:

	The most problematic situation is the one in reverse. Suppose that you have installed MISearchModules,0.7.6.2.1 (which had been compiled against OpenSim 0.7.6.2), and that you update your OpenSim installation to OpenSim 0.8.1.0. The mono addins framework will deem this addin compatible with the new version of OpenSim (because the new OpenSim version is higher than the addin's). But in reality, the new OpenSim dlls may have different .NET interfaces than those against which the MISearchModules addin was compiled. When the addin uses parts of core OpenSim that have changed between versions, a failure may happen when you run OpenSim -- it may be just an exception in the log or a complete crash of the simulator. In this case, you would need to find the newer version of the MISearchModules addin for 0.8.1.0 (see check for updates above). If it doesn't exist yet, you need to uninstall the MISearchModules addin (see uninstalling addins above) until the newer version becomes available by the provider of that addin.		The most problematic situation is the one in reverse. Suppose that you have installed MISearchModules,0.7.6.2.1 (which had been compiled against OpenSim 0.7.6.2), and that you update your OpenSim installation to OpenSim 0.8.1.0. The mono addins framework will deem this addin compatible with the new version of OpenSim (because the new OpenSim version is higher than the addin's). But in reality, the new OpenSim dlls may have different .NET interfaces than those against which the MISearchModules addin was compiled. When the addin uses parts of core OpenSim that have changed between versions, a failure may happen when you run OpenSim -- it may be just an exception in the log or a complete crash of the simulator. In this case, you would need to find the newer version of the MISearchModules addin for 0.8.1.0 (see check for updates above). If it doesn't exist yet, you need to uninstall the MISearchModules addin (see uninstalling addins above) until the newer version becomes available by the provider of that addin.
		+
		+	'''Version numbers of all kinds are mainly annotations for people. The ground truth is always in the binary signature of dlls.'''
		+
		+	Here some concrete examples:
		+	* Addin Foo requires OpenSim 0.8.1, and is being installed in OpenSim 0.8.1 ==> Addin compatibility ok. Binary compatibility ''likely'' ok.
		+	* Addin Foo requires OpenSim 0.7 and is being installed in OpenSim 0.8.1 ==> Addin compatibility ok. Binary compatibility ''likely'' will fail, depending on a number of things. If Foo has been compiled against OpenSim 0.7, then it will surely fail, because the OpenSim APIs tend to change substantially between releases. But if Foo was compiled against 0.8.1, but the developers of Foo forgot to update the declared dependency, then binary compatibility will be ok, and the plugin will be successfully installed.
		+	* Addin Foo requires OpenSim 0.9.0 and is being installed in OpenSim 0.8.1 ==> Addin compatibility will fail. Foo won't even get to run to check binary compatibility.

@@ Line 33: / Line 33: @@
 Also before installing any 3rd party addins, you need to populate the registry with OpenSim's own addins, which are required for the installation of 3rd-party's. Do that by running this command in OpenSim's '''bin''' folder: (note: if you are in Linux, precede the command with '''mono''')
-   $ mautil.exe -p . -reg ''/path/to/my/registry'' reg-update
+   $ mautil.exe -reg ''/path/to/my/registry'' reg-update
 For example:
-   $ mautil.exe -p . -reg C:/addins-registry reg-update
+   $ mautil.exe -reg C:/addins-registry reg-update
-The argument to the -p parameter, in this case '.', needs to be the directory where OpenSim.exe resides. So if you run mautil.exe from somewhere else, make sure to adjust that argument's value. For example, if you run it from the OpenSim root folder, the command above should be:
+IMPORTANT: you need to issue these commands from the bin folder. Otherwise you need to add the -p parameter and set it to the directory where OpenSim.exe resides. So if you run mautil.exe from somewhere else, make sure to adjust that argument's value. For example, if you run it from the OpenSim root folder, the command above should be:
-   $ bin/mautil.exe -p bin -reg C:/addins-registry reg-update
+   $ bin/mautil.exe '''-p bin''' -reg C:/addins-registry reg-update
 You can also use absolute paths, if that makes it easier.
 == 3rd Party Repositories ==
 The next step is to add remote repositories of addins to your OpenSim installation. There is no central repository of addins for OpenSim. Remote repositories are provided and maintained by 3rd parties, and you will have to find out about them [[List of 3rd Party Addin Repositories|by some means]]. You can add as many repositories as needed. To add a repository, run these commands in OpenSim's '''bin''' folder: (note: if you are in Linux, precede the command with '''mono''')
-   $ mautil.exe -p . -reg ''/path/to/my/registry'' rep-add ''repo_url''
+   $ mautil.exe -reg ''/path/to/my/registry'' rep-add ''repo_url''
-   $ mautil.exe -p . -reg ''/path/to/my/registry'' rep-update
+   $ mautil.exe -reg ''/path/to/my/registry'' rep-update
 For example:
-   $ mautil.exe -p . -reg C:/addins-registry rep-add http://metaverseink.com/repo
+   $ mautil.exe -reg C:/addins-registry rep-add http://metaverseink.com/repo
-   $ mautil.exe -p . -reg C:/addins-registry rep-update
+   $ mautil.exe -reg C:/addins-registry rep-update
 Or if you decided to use the default OpenSim's '''bin''' folder as the registry location:
-   $ mautil.exe -p . -reg . rep-add http://metaverseink.com/repo
+   $ mautil.exe -reg . rep-add http://metaverseink.com/repo
-   $ mautil.exe -p . -reg . rep-update
+   $ mautil.exe -reg . rep-update
-Again, the argument to the -p parameter, in this case '.', needs to be the directory where OpenSim.exe resides. So if you run mautil.exe from somewhere else, make sure to adjust that argument's value.
+Again, if you run mautil.exe from somewhere else, make sure to use -p properly.
 From here on you can check what addins are available by typing
-   $ mautil.exe -p . -reg ''/path/to/my/registry'' list-av
+   $ mautil.exe -reg ''/path/to/my/registry'' list-av
 == Installing Addins ==
 Finally, you can install an available addin with the following command:
-   $ mautil.exe -p . -reg ''/path/to/my/registry'' install ''addin''
+   $ mautil.exe -reg ''/path/to/my/registry'' install ''addin''
 For example, to install the most recent version of Diva.AddinExample:
-   $ mautil.exe -p . -reg C:/addins-registry install Diva.AddinExample
+   $ mautil.exe -reg C:/addins-registry install Diva.AddinExample
 To install a specific version:
-   $ mautil.exe -p . -reg C:/addins-registry install Diva.AddinExample,0.8.1.0.1
+   $ mautil.exe -reg C:/addins-registry install Diva.AddinExample,0.8.1.0.1
 The installed addins are placed under ''/path/to/my/registry''/addins/''addin''. Often, these addins will bring a configuration (.ini) file that you may need to change. Depending on how the addins are coded, they may or may not copy their own configuration file to the folder specified above, ConfigDirectory. Even if they do, they can only do it when OpenSim runs the addins the first time. So, the best practice is for you to go to the directory where your addin was installed and copy the ini file from there to your own ConfigDirectory.
@@ Line 76: / Line 78: @@
 To check:
-   $ mautil.exe -p . -reg ''/path/to/my/registry'' list-update
+   $ mautil.exe -reg ''/path/to/my/registry'' list-update
 To update:
-   $ mautil.exe -p . -reg ''/path/to/my/registry'' update ''addin''
+   $ mautil.exe -reg ''/path/to/my/registry'' update ''addin''
 == Uninstalling Addins ==
-   $ mautil.exe -p . -reg ''/path/to/my/registry'' uninstall ''addin''
+   $ mautil.exe -reg ''/path/to/my/registry'' uninstall ''addin''
 For example:
-   $ mautil.exe -p . -reg C:/addins-registry uninstall Diva.AddinExample
+   $ mautil.exe -reg C:/addins-registry uninstall Diva.AddinExample
 == Versioning ==

@@ Line 85: / Line 85: @@
    $ mautil.exe -p . -reg ''/path/to/my/registry'' uninstall ''addin''
 For example:
-   $ mautil.exe -p . -reg C:/addins-registry uninstall Diva.MISearchModules
+   $ mautil.exe -p . -reg C:/addins-registry uninstall Diva.AddinExample
 == Versioning ==

@@ Line 16: / Line 16: @@
 From here on, all the steps described next use the Mono Addins command line tool [https://monoaddins.codeplex.com/wikipage?title=Creating%20and%20Managing%20Add-in%20Packages mautil]. mautil allows us to package, distribute, install and uninstall mono addins for .NET applications in general.
 == Initial Registry Update ==
@@ Line 50: / Line 62: @@
 Finally, you can install an available addin with the following command:
    $ mautil.exe -p . -reg ''/path/to/my/registry'' install ''addin''
-For example, to install the most recent version of Diva.MISearchModules:
+For example, to install the most recent version of Diva.AddinExample:
-   $ mautil.exe -p . -reg C:/addins-registry install Diva.MISearchModules
+   $ mautil.exe -p . -reg C:/addins-registry install Diva.AddinExample
 To install a specific version:
-   $ mautil.exe -p . -reg C:/addins-registry install Diva.MISearchModules,0.8.1.0.1
+   $ mautil.exe -p . -reg C:/addins-registry install Diva.AddinExample,0.8.1.0.1
-The installed addins are placed under ''/path/to/my/registry''/addins/''addin''. Often, these addins will bring a configuration (.ini) file that you may need to edit. If that's the case, find that file, and edit it there in ''/path/to/my/registry''/addins/''addin''; do not copy or move these configuration files anywhere. They will be read from their locations.
+For example, for this particular AddinExample, you would be able to find its configuration file in
 == Checking for, and Installing, Updates ==

← Older revision		Revision as of 22:40, 31 December 2014
Line 77:		Line 77:
	For example, suppose that the latest MISearchModules addin was compiled against OpenSim 0.8.1.0 and you have OpenSim 0.7.6.2. When you try to install that addin, the addin installation will fail, because MISearchModules,0.8.1.0.1 has an explicit dependency on OpenSim 0.8.1.0. Since your OpenSim version is older than the addin, the incompatibility will be detected, and the installation will fail. In this case, you would need to find and install the older MISearchModules addin for OpenSim 0.7.6.2.		For example, suppose that the latest MISearchModules addin was compiled against OpenSim 0.8.1.0 and you have OpenSim 0.7.6.2. When you try to install that addin, the addin installation will fail, because MISearchModules,0.8.1.0.1 has an explicit dependency on OpenSim 0.8.1.0. Since your OpenSim version is older than the addin, the incompatibility will be detected, and the installation will fail. In this case, you would need to find and install the older MISearchModules addin for OpenSim 0.7.6.2.

−	The most problematic situation is the one in reverse. Suppose that you have installed MISearchModules,0.7.6.2.1 (which had been compiled against OpenSim 0.7.6.2), and that you update your OpenSim installation to OpenSim 0.8.1.0. The mono addins framework will deem this addin compatible with the new version of OpenSim (because the new OpenSim version is higher than the addin's). But in reality, the new OpenSim dlls may have different .NET interfaces than those against which the MISearchModules addin was compiled. When the addin uses parts of core OpenSim that have changed between versions, a failure may happen when you run OpenSim -- it may be just an exception in the log or a complete crash of the simulator. In this case, you would need to find the newer version of the MISearchModules addin for 0.8.1.0 (see check for updates above). If it doesn't exist yet, you need to ~~unistall~~ the MISearchModules addin (see uninstalling addins above) until the newer version becomes available by the provider of that addin.	+	The most problematic situation is the one in reverse. Suppose that you have installed MISearchModules,0.7.6.2.1 (which had been compiled against OpenSim 0.7.6.2), and that you update your OpenSim installation to OpenSim 0.8.1.0. The mono addins framework will deem this addin compatible with the new version of OpenSim (because the new OpenSim version is higher than the addin's). But in reality, the new OpenSim dlls may have different .NET interfaces than those against which the MISearchModules addin was compiled. When the addin uses parts of core OpenSim that have changed between versions, a failure may happen when you run OpenSim -- it may be just an exception in the log or a complete crash of the simulator. In this case, you would need to find the newer version of the MISearchModules addin for 0.8.1.0 (see check for updates above). If it doesn't exist yet, you need to uninstall the MISearchModules addin (see uninstalling addins above) until the newer version becomes available by the provider of that addin.

← Older revision		Revision as of 20:39, 31 December 2014
Line 1:		Line 1:
	This page explains how to install, update and uninstall 3rd-party addins for the simulator server in a systematic way. 3rd-party addins are packages created around binary distributions of region modules, possibly with additional external libraries and resources, that extend the simulator with additional functionality. Note that 3rd-party addins here refers to '''binary packages''' of OpenSim extensions; this is different from extensions available as source code, which you may already be familiar with, and for which you may already have a process in place for building and deploying into your grid. 3rd-party addins give the providers the option to keep the source code proprietary, and give you a relatively simple process for integrating those extensions into your installation of OpenSim and to evolve them in relative independence from updates to OpenSim core.		This page explains how to install, update and uninstall 3rd-party addins for the simulator server in a systematic way. 3rd-party addins are packages created around binary distributions of region modules, possibly with additional external libraries and resources, that extend the simulator with additional functionality. Note that 3rd-party addins here refers to '''binary packages''' of OpenSim extensions; this is different from extensions available as source code, which you may already be familiar with, and for which you may already have a process in place for building and deploying into your grid. 3rd-party addins give the providers the option to keep the source code proprietary, and give you a relatively simple process for integrating those extensions into your installation of OpenSim and to evolve them in relative independence from updates to OpenSim core.
		+
		+	If you are a developer looking for information about how to develop and distribute addins, please see [[Developing OpenSim Addins\|this other page]].

	== Registry Location ==		== Registry Location ==

@@ Line 71: / Line 71: @@
 == Versioning ==
-One important aspect of installing and managing 3rd-party binary components is the issue of versioning. .NET, in particular, is quite strict about interface compatibility between libraries, and it will complain (by raising exceptions or by crashing) if an executable tries to link an incompatible library. In the case of 3rd-party addins, incompatibilities may happen when those addins have been compiled against a version of OpenSim that is different from the one you have. Some of those incompatibilities will be caught at the time of addin installation, but some will not -- these latter ones will only show up when you run OpenSim.
+One important aspect of installing and managing 3rd-party binary components is the issue of versioning. .NET, in particular, is quite strict about interface compatibility between libraries, and it will complain (by raising exceptions or by crashing) if an executable tries to link an incompatible library. In the case of 3rd-party addins, incompatibilities may happen when those addins have been compiled against a version of OpenSim that is different from the one you have. Some of those incompatibilities will be caught at the time of addin installation, but some will not -- these latter ones may show up when you run OpenSim.
 For example, suppose that the latest MISearchModules addin was compiled against OpenSim 0.8.1.0 and you have OpenSim 0.7.6.2. When you try to install that addin, the addin installation will fail, because MISearchModules,0.8.1.0.1 has an explicit dependency on OpenSim 0.8.1.0. Since your OpenSim version is older than the addin, the incompatibility will be detected, and the installation will fail. In this case, you would need to find and install the older MISearchModules addin for OpenSim 0.7.6.2.
-The most problematic situation is the one in reverse. Suppose that you have installed MISearchModules,0.7.6.2.1 (which had been compiled against OpenSim 0.7.6.2), and that you update your OpenSim installation to OpenSim 0.8.1.0. The mono addins framework will deem this addin compatible with the new version of OpenSim (because the new OpenSim version is higher than the addin's). But in reality, the new OpenSim dlls may have different .NET interfaces than those against which the MISearchModules addin was compiled. If that is the case, a failure may happen when you run OpenSim -- it may be just an exception in the log or a complete crash of the simulator. In this case, you would need to find the newer version of the MISearchModules addin for 0.8.1.0 (see check for updates above). If it doesn't exist yet, you need to unistall the MISearchModules addin (see uninstalling addins above) until the newer version becomes available by the provider of that addin.
+The most problematic situation is the one in reverse. Suppose that you have installed MISearchModules,0.7.6.2.1 (which had been compiled against OpenSim 0.7.6.2), and that you update your OpenSim installation to OpenSim 0.8.1.0. The mono addins framework will deem this addin compatible with the new version of OpenSim (because the new OpenSim version is higher than the addin's). But in reality, the new OpenSim dlls may have different .NET interfaces than those against which the MISearchModules addin was compiled. When the addin uses parts of core OpenSim that have changed between versions, a failure may happen when you run OpenSim -- it may be just an exception in the log or a complete crash of the simulator. In this case, you would need to find the newer version of the MISearchModules addin for 0.8.1.0 (see check for updates above). If it doesn't exist yet, you need to unistall the MISearchModules addin (see uninstalling addins above) until the newer version becomes available by the provider of that addin.