Plugin writing HOWTO

Introduction

The purpose of this guide is to explain how to add a new plugin to an already existing project. It is illustrated throughout with a worked example.

How plugins are loaded and required naming convention

StGermain determines which plugins to load and register through looking in the Dictionary for a list with the name "extensions" (note, this really should be "plugins" and may change in future). If this list is found, then every entry in the list is considered as the name of a plugin dynamic library to load and register. StGermain automatically translates this textual plugin name in the dictionary to a dynamic library file which can be found in your load library path. The plugin name is appended with "module.$SO_EXT", where $SO_EXT is the extension used for dynamic libraries on your operationg system (eg "so" on Linux, "dylib" on Mac OsX?).

From the plugin developer's perspective, what you really need to remember is how the plugin directory name translates to the name of the plugin that can then be referenced from the xml input file. .

Lets take an example.

If my plugin directory name is faultModel

StGermain will compile the plugin into a shared library called "SPModelFaultModelmodule.so", and place it in my build libraries directory.

Then if the user's xml input file contains a reference to this module:

<list name="plugins">
   <param>SPModelFaultModel</param>
</list>

given that the user added the StGermain libraries build directory to their LD_LIBRARY_PATH, StGermain will try to load and register "SPModelFaultModelmodule.so"

Writing a plugin

Creating a plugin directory and registering with build system

The easiest way to create a plugin is to copy an existing plugin directory e.g. fluvialErosion and to modify it. In this illustration we will create a variant of the fluvialErosion plugin and call it fluvialErosionVariant.

The transport equation:

Where Q is the water flux and S is the gradient. In the fluvialErosion plugin both m and n are hard coded as 1. In our new plugin we are going to add two new parameters to our xml file namely fluxPower(m) and gradientPower(n), which we will read in from the plugin to modify the transport equation.

Step 1

Copy the fluvialErosion directory as fluvialErosionVariant. Rename the source files inside fluvialErosionVariant FluvialErosionVariant.c and FluvialErosionVariant.h for clarity.

The header file is modified as follows:

FluvialErosionVariant.h

The expression FluvialErosion_ has been replaced with FluvialErosionVariant_ by a text “search and replace”. We have also defined an extension SPModelFluvialErosionVariantContextExtension which will be appended to the context when the plugin gets loaded at runtime. Please note that the extension contains the two new parameters required by this plugin.

The C source file is modied as follows:

FluvialErosionVariant.c

The expression FluvialErosion_ has been replaced with FluvialErosionVariant_ by a text “search and replace”. In the construct phase we need to register the extension that we have created and save the handle to that extension to a global variable SPModel_FluvialErosionVariant_ContextExtHandle. Then we make use of the two new parameters in the transportEquation. The rest of the code is very similar to the code that we copied from the fluvialErosion directory earlier.

Step 2

We now need to add our new plugin to the build system so it gets complied along with the other plugins.

Makefile.def

Step 3

Add the aforementioned parameters to the xml file:

<param name="fluxPower"> 1.0f </param>

<param name="gradientPower"> 2.0f </param>

Step 4

Now we need to compile the code and add the new plugin to our input xml file as follows:

<list name="plugins">

<param>SPModelTectonicUplift</param>

<param>SPModelOrography</param>

<param>SPModelFluvialErosionVariant</param>

<!--<param>SPModelFluvialErosion</param>-->

<param>SPModelDiffusionErosion</param>

<!--<param>SPModelFaultModel</param>-->

<param>SPModelIsostaticFlexure</param>

<param>SPModelFileOutput</param>

<param>SPModelFlowHierarchyViewer</param>

</list>

For more detailed guidelines writing plugins, please refer to https://csd.vpac.org/twiki/bin/view/Stgermain/PluginsHOWTO