Versioning

As with all software, it is important to know what version of code is actually running. Thunder allows all plugins to be versioned and this version information can be retrieved at runtime.

Build Reference

When building Thunder, the CMake option -DBUILD_REFERENCE should be set to the git hash of the code being built:

if (BUILD_REFERENCE)
    add_definitions (-DBUILD_REFERENCE=${BUILD_REFERENCE})
endif()

This value will be printed in the logs at Thunder startup. In addition, the -DTREE_REFERENCE option can be set to point to the repository the code was built from if desired.

If not set, both values default to the string engineering_build_for_debug_purpose_only

When building plugins, BUILD_REFERENCE should also be defined independently at configure time (since plugin code will be built from a different repository than the main Thunder core). This can be retrieved at runtime from the Controller plugin

Plugin Versioning

All plugins will have a static metadata object defined that contains information about the plugin. This includes the version number of the plugin in the format Major.Minor.Patch. Here, the TestPlugin version number is set to 1.0.0.

It is recommended to follow semantic versioning as defined at semver.org:

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes
2. MINOR version when you add functionality in a backward compatible manner
3. PATCH version when you make backward compatible bug fixes

Note

All plugin libraries will be loaded and unloaded at Thunder startup in order to retrieve this version information. If the plugin has been deactivated and the library has been replaced/upgraded, then the version information will not update until the plugin is activated again.

static Metadata<TestPlugin> metadata(
    // Version
    1, 0, 0,
    // Preconditions
    {},
    // Terminations
    {},
    // Controls
    {});

At runtime, this version information can be retrieved from the Controller plugin. The hash value comes from the BUILD_REFERENCE definition.

Request

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "Controller.1.status@TestPlugin",
    "params": {}
}

Response

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        {
            "callsign": "TestPlugin",
            "locator": "libThunderTestPlugin.so",
            "classname": "TestPlugin",
            "startmode": "Activated",
            "configuration": {},
            "state": "activated",
            "observers": 0,
            "module": "Plugin_TestPlugin",
            "version": {
                "hash": "759f83de30e18f80cce018d855240a2b4020e092",
                "major": 1,
                "minor": 0,
                "patch": 0
            }
        }
    ]
}

JSON-RPC Interface Versioning

It is possible to version JSON-RPC interfaces independently of the plugin. This information can then be retrieved from the Controller plugin at runtime.

If using a JSON-RPC interface that has been autogenerated from a COM-RPC interface (strongly recommended!), then the version number of the interface should be defined as part of the @json tag

namespace Thunder {
namespace Exchange {
    /* @json 1.0.0 */
    struct EXTERNAL ITestPlugin : virtual public Core::IUnknown {
        enum {
            ID = ID_TEST_PLUGIN
        };

        /* @brief Return a test value */
        virtual Core::hresult Test(string& result /* @out */) = 0;
    };
}
}

The code-generator will then autogenerate the version information in the generated JSON interface. E.G

uint8_t major = Exchange::JTestPlugin::Version::Major;