v1.2.0 Summary Chapter 8: Plug-ins and UI translations 8. Introduction 8.1. Extending features with plug-ins
You're browsing the documentation of a version that is still under development, the features described here may change or even be removed.

8.1. Extending features with plug-ins

Plugins are the best way to add a specific set of features to the software without changing its core code. So, pgModeler has a simple structure that provides means to create third-party plugins. The first step in the development of a plugin that handles pgModeler internals is to take a good reading on pgModeler's API as well as the Qt plug-in system. You can generate the pgModeler's code documentation by using the doxygen utility running the command doxygen doxygen.conf at pgModeler's source code root. Once generated, the code documentation is stored in the folder docs under the source code directory.

Details about configuring and installing the doxygen application can be seen on its official website. Steps on how to retrieve the source code of pgModeler can be seen on the download page. Once provided with the basic information about plugins, you can start to create your own extended features.

In the Qt framework, and consequently, in pgModeler, a plugin is basically a C++ class implemented in a library installed in a path that is accessible by the application. The C++ class that implements the plug-in must follow two basic rules: inherit the class PgModelerGuiPlugin overloading all its pure virtual methods and use the macros Q_INTERFACES and Q_PLUGIN_METADATA in its declaration. Another rule is that the plug-ins in pgModeler must have a basic directory structure in order to be properly loaded when the application starts:

[PGMODELER_PLUGINS_DIR]/
    |
    + - pluginA/
    |
    + ---- (lib)*(pluginA.)(so|dylib|dll) (library)
    |
    + ---- res/
             |
             +--- pluginA.qrc (resource file)
	                  |
                          +--- /pluginA (context)
                                        |
                                        +--- pluginA.png (icon)


On the above schema, the directory named pluginA is located on the root directory used by pgModeler to load plug-ins. This directory stores all the assets and components of the extension. Inside that folder, there is a res subdirectory in which all the icons used by the plugin are stored. In the same folder, we have the library that implements all the plugin's logic. The name of the library that stores the plugin's code is platform-dependent and can be: libpluginA.so (Linux), pluginA.dll (Windows), and libpluginA.dylib (macOS).

Since the plug-in needs to access the tool's features exposed by its classes, there are two ways to accomplish this: build the plugin with pgModeler or build the plugin using a pre-installed copy of pgModeler and its source. The next subsection explains both building modes.

8.1.1. Building plug-ins

As told previously, pgModeler plug-ins can be built in two different ways:

  1. Together with a pgModeler building process which generates the entire tool including its plugins. This compilation mode doesn't require any special procedure and the complete steps for the tool's building are available in the installation instructions.

  2. Standalone building, which means, compiling a plug-in against an existing pgModeler installation. This compilation mode requires the use of the pgModeler's source code and its shared libraries located in the installation folder.

In this procedure, we assume that you already have the Qt framework installed, a clean installation of pgModeler, and unrestricted access to its libraries (.so, .dylib, or .dll). So, to build a single plug-in and make it recognizable by pgModeler, you'll need first to download the tool's source code. Just make sure to download the source related to the same version as your pgModeler installation or the building process may fail. Second, clone the source code repository anywhere in your system since it's from there that we'll run the steps to achieve our goal.

For the steps below, as a convenience, we have aliased some paths to shorten the commands executed, make sure to replace them with the real paths according to your system.

  1. Cloning the source code:

    Alternatively, you can download a tarball or zip package and extract it anywhere, skipping to step 2.

    git clone https://github.com/pgmodeler/pgmodeler.git
    

    a) Check out the tag related to the pgModeler installed on your system. Supposing that the version in your system is 0.9.4, the checkout command must be:

    git checktout v1.1.0
    
  2. Cloning the plug-ins repository:

    git clone https://github.com/pgmodeler/plugins.git
    
  3. Running qmake with custom parameters to allow a standalone build:

    $QT_ROOT\bin\qmake plugins.pro PGMODELER_PLUGINS=$PGMODELER_PLUGINS_ROOT
                                   PGMODELER_SRC=$PGMODELER_SOURCE_ROOT
                                   PGMODELER_LIBS=$PGMODELER_LIBRARIES_ROOT
    

    In the command above, the variable $QT_ROOT must be replaced by the path to the binaries of your Qt installation.

The argument PGMODELER_PLUGINS must point to the path where all pgModeler plug-ins are stored in your installation, also known as, the plug-ins root directory. If you don't know where they are installed, just run pgModeler, open the settings dialog, and locate the Plug-ins settings. In the command above, replace $PGMODELER_PLUGINS_ROOT with the path presented in the field Plug-ins root directory on plug-ins settings.

The argument PGMODELER_SRC must point to the pgModeler source code (either that you've cloned or extracted). Don't forget to replace the variable $PGMODELER_SOURCE_ROOT with that path. Finally, the argument PGMODELER_LIBS must point to the path where all shared libraries (.so, .dll, or .dylib) related to pgModeler are installed. Replace the variable $PGMODELER_LIBRARIES_ROOT by that path.

  1. Build and install the plug-ins. From the folder where the plug-ins repository was cloned, run:

    make && make install
    

If the build process succeeds, you will see that some files are installed in the plug-ins root directory in your pgModeler installation. Now, just run pgModeler to test if the plug-ins are working properly. In case of any problem with any plug-in, pgModeler will refuse to load it and present a detailed error dialog. You can use the presented information to ask for help. If want to build a third-party plug-in that isn't officially distributed, just put its source code folder where all the other plug-ins' sources reside. From that plug-in source code folder, run steps 3 and 4, not forgetting to replace the plugins.pro, in step 3, with the project settings (.pro) related to the plug-in.

pgModeler gives complete access to its classes and doesn't prohibit the plug-ins to read and write files outside their own paths, this way you must take extreme caution when developing a plug-in or even when installing an extension from suspicious sources since this may harm your computer or cause data loss.

How to create Qt plug-ins

http://doc.qt.io/qt-6/plugins-howto.html

Doxygen utility

http://www.doxygen.nl

Oct 31, 2024 at 09:12