Extending the oac-tree with plugins

Plugins allow users to extend the functionality of the oac-tree by providing new instructions or variables. This documentation provides a step-by-step guide on how to create a plugin and integrate it into the oac-tree. Creating a plugin to access another library in the oac-tree is simple when following a structured approach: first, implement the instruction/variable interface; then register the instruction/variable; and finally deploy the plugin in the plugin folder.

Implementation

Start by creating a new project (E.g. oac-tree-plugin-examplelib). This page uses the following directory structure for the source files (but this is not mandatory): src > lib > oac-tree. Inside the oac-tree folder, you may create additional directories for different parts of the library you wish to create the plugin for.

To implement instructions and variables you can take a look at their respective sections: Instruction, Variable.

The absolute mininum that you have to implement are the following virtual functions:

For instructions:

  • ExecutionStatus Instruction::ExecuteSingleImpl(UserInterface& ui, Workspace& ws)

For variables:

  • bool Variable::GetValueImpl(sup::dto::AnyValue& value) const

  • bool Variable::SetValueImpl(const sup::dto::AnyValue& value)

Registration

To register an instruction, include the instruction registry header file, and declare a static initialisation flag in the instruction’s source file.

#include <sup/oac-tree/instruction_registry.h>

static bool _example_initialised_flag = RegisterGlobalInstruction<ExampleInstruction>();

In the same way, a variable is registered by including the variable registry header file, and similarly declaring a flag in the variable’s source file.

#include <sup/oac-tree/variable_registry.h>

static bool _example_initialised_flag = RegisterGlobalVariable<ExampleVariable>();

Plugin deployment

To deploy the plugin, install the shared library in an appropriate folder. If you want to avoid having to specify the full pathname in the XML procedure later, use a folder that is used by the operating system to look for shared libraries (or add the path to LD_LIBRARY_PATH).

Usage

To use variables and instructions of any plugin within your procedure, declare the plugin right after declaring the procedure, in said procedure’s xml file.

<Plugin>liboac-tree-example.so</Plugin>