Plugin Creation

Previous: Localisation

Next: Extra Python modules

Index

Introduction

Plugins are used to extend the functionality of LabRPS. LabRPS has several types of plugins. For example, WindLab plugin, SeismicLab plugin, SeaLab plugin, and many others. LabRPS is already distributed with many different plugins. You can also search various plugins on the LabRPS official site or the LabRPS Addons GitHub repository to see if someone has already created a plugin that suits your needs. If not, this article will guide you through the process of creating your plugin. This page will show you how to add a new plugin to LabRPS. Plugins are containers for LabRPS features. They can be coded in C++, or in a mix of C++ and Python, which has the advantage to ally the speed of C++ to the flexibility of Python. They can be installed from the Addon Manager or installed manually by downloading from some online repository. For now, plugins cannot be developed in Python-only. If this is your first coding contribution to LabRPS, make sure you download and compile the LabRPS source code first.

LabRPS Plugins

In LabRPS, a plugin is a dynamic library that is discovered and loaded at run time as opposed to a dynamic library that an application is linked against at build time. LabRPS Plugins can therefore be written by users, using the well-defined plugin API that LabRPS provides. This allows the users to extend the functionality of the API in designated ways. LabRPS plugin system consists of two major features: The Plugin API which is the API that users must compile and link against in order to create a plugin and the Plugin Manager which is an object (a singleton) in the LabRPS code that manages the life cycle of all plugins, that is, loading, registration, and unloading. This object can also be called the Plugin Registry.

The plugin structure, required files, and locations

You need a folder, with any name you like, placed in the user Mod directory. it is recommended to give this folder the name of the plugin. The location you place your plugin folder under the Mod directory depends on the type of plugin you are developing. If your plugin is a WindLab plugin, you should put your plugin folder under /Mod/WindLabPlugins. This folder should contain a MyFirstPlugin.txt text file. This file contains meta-information describing your plugin. Just copy this file from any other existing plugin and modify it for your needs. The MyFirstPlugin.txt file is executed when LabRPS scans the directory to discover available plugins. That's all it needs for LabRPS to find your plugin. Until now, the file that represents your plugin have not been created yet. A plugin in LabRPS is a dynamic library such as a .dll file on Windows, .dylib on Mac, or .so on Linux. In order to create thise library you need to add a .cpp (MyFirstPlugin.cpp) file to your folder. LabRPS uses CMake as its main build system, as it's available on all major operating systems. Compiling with CMake is usually very simple. So, you need to add the CMakeLists.txt to the folder.

The user Mod directory is a sub-directory of the user application data directory (you can find the latter by typing App.getUserAppDataDir() in the Python console):

• On Linux it is usually /home/<username>/.local/share/LabRPS/Mod/.
• On Windows it is %APPDATA%\LabRPS\Mod\, which is usually C:\Users\<username>\Appdata\Roaming\LabRPS\Mod\.
• On macOS it is usually /Users/<username>/Library/Application Support/LabRPS/Mod/.

Your plugin folder should look like this on windows:

/Mod/
 +-- WindLabPlugins/
                   +-- MyFirstPlugin/
                                    +-- MyFirstPlugin.txt
                                    +-- MyFirstPlugin.cpp
                                    +-- CMakeLists.txt

The MyFirstPlugin.txt file

# -*- coding: utf-8 -*-
# (c) My Name 2080

__Name__ = "MyFirstPlugin"
__Comment__ = "This plugin adds great functionalities to LabRPS"
__License__ = "LGPL v 2.1"
__Web__ = ""
__Wiki__ = "https://wiki.labrps.com/Plugin_MyFirst"
__Icon__  = ""
__Help__ = ""
__Author__ = "My Name"
__Version__ = "1.0"
__Status__ = ""
__Requires__ = ""
__Files__ = "MyFirstPlugin.dll"
__Date__ = "25-08-2024"
__Phenomenon__ = "Wind Velocity"
__RPSVersion__ = "0.1"

The MyFirstPlugin.cpp file

#include <Mod/WindLabAPI/App/RPSWindLabPluginAPI.h>

PLUGIN_NAME("MyFirstPlugin");
RANDOM_PHENOMENON("Wind Velocity");
PLUGIN_AUTHOR("My Name");
PLUGIN_DESCRIPTION("This plugin adds a great feature for the simulation of random wind velocity");
PLUGIN_VERSION("1.00");
LABRPS_VERSION("0.1");
API_VERSION("0.1");
PLUGIN_RELEASE_DATE("15/06/2080");

PLUGIN_INIT_TYPE()
{ 
    return 1;
}

PLUGIN_INIT()
{
    return 1;
}


INSTALL_PLUGIN()
{
    return 1;
}

UNINSTALL_PLUGIN()
{
    return 1;
}

The CMakeLists.txt file

include_directories(
    ${CMAKE_BINARY_DIR}
    ${CMAKE_SOURCE_DIR}/src
    ${CMAKE_BINARY_DIR}/src
    ${CMAKE_CURRENT_BINARY_DIR}
)

set(MyFirstPlugin_LIBS
    LabRPSGui
    WindLabAPI
    GeneralTools
    WindLabTools
)

SET(MyFirstPlugin_SRCS
MyFirstPlugin.cpp
)

SET(Metadata_Files
MyFirstPlugin.txt

)

add_library(MyFirstPlugin SHARED ${MyFirstPlugin_SRCS} ${Metadata_Files})
target_link_libraries(MyFirstPlugin ${MyFirstPlugin_LIBS})

SET_BIN_DIR(MyFirstPlugin MyFirstPlugin /Plugins/WindLabWorkbench/MyFirstPlugin)

rps_copy_sources(MyFirstPlugin "${CMAKE_BINARY_DIR}/Plugins/WindLabWorkbench/MyFirstPlugin" ${Metadata_Files})
INSTALL(TARGETS MyFirstPlugin DESTINATION "${CMAKE_INSTALL_PREFIX}/Plugins/WindLabWorkbench/MyFirstPlugin")
INSTALL(FILES MyFirstPlugin.txt DESTINATION "${CMAKE_INSTALL_PREFIX}/Plugins/WindLabWorkbench/MyFirstPlugin")

You can choose any license you like for your plugin, but be aware that if you wish to see your plugin integrated into and distributed with the LabRPS source code at some point, it needs to be LGPL2+ like the example above. See License.

Previous: Localisation

Next: Extra Python modules

Index

Power user documentation

• LabRPS scripting: Python, Introduction to Python, Python scripting tutorial, LabRPS Scripting Basics

---

• Modules: Units, Quantity
• Workbenches: Gui Commands, Commands

---

• Parametric objects: Scripted objects, Viewproviders
• Graphical interface: Interface creation, Interface creation completely in Python, PySide, PySide examples beginner, intermediate, advanced
• Macros: Macros, How to install macros

---

• Other: Expressions

---

• Hubs: User hub, Power users hub, Developer hub