DynObj - C++ Cross platform plugin objects

Building and using the library

Directory layout of the library:
  • doc
    • doxygen - docs generated from doxygen
  • src
    • DynObj - main source of DynObj library
      • samples - samples of using library here
      • tools - source for the pdoh tool
      • msdev - Visual C++ project for DynObj and samples here
    • pi - sources for platform independence layer
    • utils - utility like C++ classes
A description of the pdoh tool is available here.

Build model

Plugin are usually opened while the application is running, so there is no build-time link between the main application and the plugins. When a plugin module is loaded, by default, the linker is instructed not to backlink into the application (Unix). On Windows, backlinking is not possible.

An application can expose functionality to plugins through interfaces. DoRunTimeI provides a way to make named instances of objects known globally.

Compiler defines

A number of compiler defines controls how libraries and main applications are built. The defines are described in detail in src/DynObj/DoSetup.h (and under DynObj defines in doxygen doc).

When compiling a library DO_MODULE should be defined. Also, the name of the library should be stored in DO_LIB_NAME (i.e. #define DO_LIB_NAME "DynStr").

The main application should define DO_MAIN.

The default settings in DoSetup.h are OK when compiling the samples. In general the defines are used like this (example DO_USE_DYNSHARED):
  • #define DO_USE_DYNSHARED - The option is not used
  • #define DO_USE_DYNSHARED 0 - The option is not used
  • #define DO_USE_DYNSHARED 1 - The option is activated
This allows having sensible defaults and for overriding them reliably from outside in a build environment.

Building the DynObj library

There are two build methods provided with the library:
  • Cross-platform GNU makefile - This works for the g++ compiler on Unices and Windows (mingw).
  • Visual C++ - Solution and project files for for Visual C++ on Windows.

Building a plugin (module)

The compiler define DO_MODULE should be set.
A plugin module requires compiling with:
  • DynObj.cpp
  • vt_test.cpp

Building a main application (using plugins/modules)

The compiler define DO_MAIN should be set.
The main application links against one of two static libraries:
  • dolibdort - Enables using DynObj:s and DoRunTime
  • doliblt - A minimalistic library without support for DoRunTime
The libraries are projects in the Visual C++ solution file.
To build the libraries using the makefile:

$ cd src/DynObj
$ make dolibdort
$ make doliblt

The DynStr library

A run-time plugin class for strings is provided: DynStr. This enables plugins to use a C++ string class in a safe way, internally and in function calls.

The DynStr library is built with:

$ cd src/DynObj
$ make ds

Building the samples

The samples defines a PersonI and ProfessionI interfaces. Then three slightly different implementations are provided in three plugins: pimpl1, pimpl2, pimpl3

Three different main applications are provided as well: main1, main2, main3.

There are sub-projects for each of them in the VC++ solution file.

From the command prompt:

$ cd samples
$ make pimpl1
$ make pimpl2
$ make pimpl3
$ make bmain1
$ make bmain2
$ make bmain3

The pdoh tool

This tool takes a C++ header or source file and outputs a modified version of the file, provided it finds // %%DYNOBJ tags in it. It basically scans for class and struct declarations and collects inheritance information.

The pdoh tool can generate these sections:
  • A general section (in a header file). This part is used by both the plugin and the main application. It contains class declarations, type IDs and the bridge from C++ types to type IDs.
  • An implement section (by default in a header file). This part is used only by the plugin. To keep things simple, the code is generated inside the header file (that keeps things in one place) and the plugin must trigger inclusion of this section with a #define DO_IMPLEMENT_NAMEOFLIB.
  • A library section. This goes into a source file and makes up the part that the user of the plugin communicates with directly. The most important function is the one that receives a type ID/ type string and instantiates this object to the caller.

By default pdoh sends its output to stdout. Use option -o to overwrite the input file, or -oNewFile.h to write to another file. To generate less comments in the output -b can be used.

pdoh can be integrated into a build environment, it is a simple file scanner so it is fast. If it does not find any //%%DYNOBJ tags it will not generate any output.

If the tags have not been modified since the previous run (on the same file), it will also not generate any output (so it does not affect file time stamps when there is no need for it).