Plugin Meta Data

The meta data file of a plugin is a JSON file that contains all information that is necessary for loading the plugin's library, determining whether plugins are to be loaded and in which order (depending on e.g. dependencies). In addition, it contains textual descriptions of who created the plugin, what it is for, and where to find more information about it. The file must be located in one of the include search paths when compiling the plugin, and must have the .json extension. The JSON file is compiled into the plugin as meta data, which then is read by Qt Creator when loading plugins.

Main Keys

The main keys that are used to identify your your plugin and define default loading behavior, consist of the mandatory keys Name and Version, and the optional keys CompatVersion, Experimental, DisabledByDefault, Required and Platform.

Plugin-describing Keys

These are solely used for more detailed (user centric) description of the plugin. All of these are optional.

Dependencies

A plugin can have dependencies on other plugins. These are specified in the plugin meta data, to ensure that these other plugins are loaded before this plugin.

Dependencies are declared with the key Dependency, which contains an array of JSON objects with required keys Name and Version, and optional key Type.

The following formulas illustrate how the dependency information is matched. In the formulas the name of the required plugin (as defined in the Name of the dependency object) is denoted as DependencyName and the required version of the plugin is denoted as DependencyVersion. A plugin with given Name, Version and CompatVersion as defined in the plugin meta data matches the dependency if

• its Name matches DependencyName, and
• CompatVersion <= DependencyVersion <= Version.

For example a dependency

{
    "Name" : "SomeOtherPlugin",
    "Version" : "2.3.0_2"
}

would be matched by a plugin with

{
    "Name" : "SomeOtherPlugin",
    "Version" : "3.1.0",
    "CompatVersion" : "2.2.0",
    ...
}

since the name matches, and the version 2.3.0_2 given in the dependency tag lies in the range of 2.2.0 and 3.1.0.

A dependency object is a JSON object with the following keys:

Optional Dependencies

A plugin can specify that a dependency on another plugin is optional, by adding "Type" : "Optional" to the dependency object:

• If the dependency can be resolved, the plugin and its dependency are loaded and initialized as for Required dependencies.
• If the dependency cannot be resolved, the plugin is loaded and initialized as if the dependency was not declared at all.

The plugin is not informed about the existence of optional dependencies in any way. Since the dependency might be loaded or not, the plugin may also not link against the dependency. A common way to access objects from optional dependencies is to get the object from the global object pool via ExtensionSystem::PluginManager::getObjectByName() and use QMetaObject functions to call functions on it.

Test Dependencies

When the user runs the application with the -test command-line argument, only the specified plugins and their dependencies are loaded. This is done in order to speed up the execution of tests by avoiding the loading of unneeded plugins.

A plugin can specify additional dependencies that are required for running its tests, but not for its normal execution, by declaring dependencies with "Type" : "Test". Test dependencies are force loaded, and do not affect load order.

This type of dependency is not transitive.

Command-Line Arguments

Plugins can register command-line arguments that the user can give when starting the application. These command-line arguments are shown with a one-line description when the user runs the application with the -help command-line argument, and the plugin manager does its command line parsing and sanity checks based on that information. If the plugin manager finds matching command-line arguments for a plugin, it passes them on to the plugin's initialize() function.

Command-line arguments are defined through the key Arguments, which contains an array of argument objects. Each individual argument object has the required key Name, and optional keys Parameter and Description.

An argument object is a JSON object with the following keys:

Example Test.json

{
    "Name" : "Test",
    "Version" : "1.0.1",
    "CompatVersion" : "1.0.0",
    "Vendor" : "My Company",
    "Copyright" : "(C) 2016 MyCompany",
    "License" : [
        "This is a default license bla",
        "blubbblubb",
        "end of terms"
    ],
    "Category" : "My Company Additions",
    "Description" : [
        "This plugin is just a test.",
        "It demonstrates the great use of the plugin meta data."
    ],
    "Url" : "http://www.mycompany-online.com/products/greatplugin",
    "Arguments" : [
        {
            "Name" : "-variant",
            "Parameter" : "fancy|boring",
            "Description" : "Brings up the fancy or boring user interface"
        }
    ],
    "Dependencies" : [
        { "Name" : "SomeOtherPlugin", "Version" : "2.3.0_2" },
        { "Name" : "EvenOther", "Version" : "1.0.0" }
    ]
}

A Note on Plugin Versions

Plugin versions are in the form x.y.z_n where, x, y, z and n are non-negative integer numbers. You don't have to specify the version in this full form - any left-out part will implicitly be set to zero. So, 2.10_2 is equal to 2.10.0_2, and 1 is the same as 1.0.0_0.