Creating and Using Plugins

The general idea is that OpenSim is made up of a set of dynamic libraries (dlls on windows). User plugins are built as their own dlls. Each library "registers" a set of classes that it defines and are available for use. By writing a new library and using some conventions to register the new classes(explained below), users can add to the set of classes available to the application. Since the code is written in a generic way it can make use of these new classes without knowing about them in advance.  

For example, the forward tool in the OpenSim application has a panel to specify analyses that the user wants executed. All these analyes derive from a base class (OpenSim::Analysis). By having a plugin register a class that derives from OpenSim::Analysis, users can add their own analyses to the list and have them executed.  

Slides

PowerPoint slides are available below that were adapted from the OpenSim Developers Workshop in July 2012. They demonstrate how to code, build, install, and test OpenSim plugins, based on examples that come with the OpenSim release.

Registration of Classes

To tell OpenSim about the new classes defined by a plugin (dll), the user needs to execute the following line when the plugin is loaded  

• Object::RegisterType( My_Plugin_Class1() ); 

• Object::RegisterType( My_Plugin_Class2() ); 

A convenient place to do that on windows is in the function DllMain under the case DLL_PROCESS_ATTACH.  

The classes My_Plugin_Class1, My_Plugin_Class2 should satisfy the following:  

1. Have any valid C++ class name.  

2. Derive from the class "OpenSim::Object"  

3. Have a default/no-arg constructor.  

4. If the class will need to be serialized (written/read from an XML file) and edited in the GUI, those quantities that are serialized need to be marked as such (Check the example AnalysisPlugin_Template.h in the OpenSimInstallDir/sdk/examples/plugin/ for details on that).  

The OpenSim distribution includes an example plugin and all the files necessary to build it along with step by step instructions. These are available under OpenSimInstallDir/sdk/doc. The instructions are the same for all OpenSimversions following 1.6.  

Command Line Execution

The command line version of the tools (e.g. forward, perturb, …) take an argument on the form “-L libraryName” so if you build your dll (e.g. myPlugin.dll) and implement correct APIs as above and this dll is available in your PATH, or in the directory where the executables your running exist, it can be used by the executables for various tools.  

Issues

1. Since libraries are built using a specific version of VisualStudio, and VisualStudio versions are NOT Compatible you need to be aware of the following::

' The libraries in the distribution wer built using VisualStudio8 (2005) Professional and have been tested and worked successfully with VisualStudio8 and VisualStudio9 Express but they do not work with VisualStudio9 Professional.'  

2. Microsoft does not allow distributing debug libraries so in case you want to debug your plugin you have the following options:
 . Old fashioned print statements.:
 . Build your library/plugin configuration "RelWithDebInfo". Although debugging info may not be fully available you'll be able to see the flow of the program.: