Qt

Plugin Specifications

The specification of a plugin is an XML 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 (a subdir of) one of the plugin manager's plugin search paths, and must have the .pluginspec extension.

Main Tag

The root tag is plugin. It has the mandatory attributes name and version, and the optional attributes compatVersion, experimental and disabledByDefault.

TagMeaning
pluginRoot element in a plugin's XML file.
AttributeMeaning
nameThis is used as an identifier for the plugin and can e.g. be referenced in other plugin's dependencies. It is also used to construct the name of the plugin library as lib[name].[dll|.so|.dylib]. (Depending on platform. If you use the same string as the TARGET in your plugin's .pro-file, you are fine.)
versionVersion string in the form x.y.z_n, used for identifying the plugin. Also see A Note on Plugin Versions.
compatVersionOptional. If not given, it is implicitly set to the same value as version. The compatibility version states which version of this plugin the current version is binary backward compatible with and is used to resolve dependencies on this plugin. I.e. a version of 2.1.1 and a compatVersion of 2.0.0 means that this version 2.1.1 of the plugin is binary backward compatible with all versions of the plugin down to 2.0.0 (inclusive).
experimentalOptional. Can be true or false, defaults to false. Experimental plugins are not loaded by default but must be explicitly enabled by the user. This attribute should be enabled for new plugins which have the potential to negatively affect the user experience.
disabledByDefaultOptional. Can be true or false, defaults to false. If set, the respective plugin is not loaded by default but must be explicitly enabled by the user. This should be done for plugins which are not expected to be used by so many people as to justify the additional resource consumption.

Plugin-describing Tags

These are direct children of the plugin tag, and are solely used for more detailed (user centric) description of the plugin. All of these are optional.

TagMeaning
categoryDefaults to Utilities. Is used to put related plugins under the same tree node in the plugin overview About Plugins....
vendorString that describes the plugin creator/vendor, like MyCompany.
copyrightA short copyright notice, like (C) 2007-2008 MyCompany.
licensePossibly multi-line license information about the plugin. Should still be kept relatively short, since the UI is not designed for long texts.
descriptionPossibly multi-line description of what the plugin is supposed to provide. Should still be kept relatively short, since the UI is not designed for long texts.
urlLink to further information about the plugin, like http://www.mycompany-online.com/products/greatplugin.

Dependencies

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

The XML element that describes a single dependency is the dependency tag, with required attributes name and version. All dependency tags must be enclosed in a single dependencyList tag, which is an optional child of the plugin tag.

The following formulas illustrate how the dependency information is matched. In the formulas the name of the required plugin (as defined in the attributes of the dependency tag) 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 attributes of the plugin's plugin tag) matches the dependency if

  • its name matches dependencyName, and
  • compatVersion <= dependencyVersion <= version.

For example a dependency

<dependency name="SomeOtherPlugin" version="2.3.0_2"/>

would be matched by a plugin with

<plugin 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.

TagMeaning
dependencyDescribes a dependency on another plugin.
AttributeMeaning
nameThe name of the plugin, on which this plugin relies.
versionThe version to which the plugin must be compatible to fill the dependency, in the form x.y.z_n. Can be empty if the version does not matter.
typeOptional. Value required or optional. Defines if the dependency is a hard requirement or optional. Defaults to required.

Optional Dependencies

A plugin can specify that a dependency on another plugin is optional, by adding the type="optional" attribute to the dependency tag:

  • 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() or ExtensionSystem::PluginManager::getObjectByClassName(), and use QMetaObject functions to call methods on it.

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() method.

All command line argument definitions are enclosed by a single argumentList tag. The individual command line arguments are defined by the argument tag, with required attribute name and an optional attribute parameter if the command line argument takes an additional parameter. The text that is enclosed in the argument tag is used as a (one-line) description in the command line argument help.

TagMeaning
argumentDescribes a command line argument that the plugin wants to handle.
AttributeMeaning
nameThe command line argument itself, including the - prefix, e.g. -my-parameter.
parameterOptional. If this is given, the command line argument expects an additional parameter, e.g. -my-parameter somevalue. The value of this attribute is used as a very short description of the parameter for the user.

Example Test.pluginspec

<plugin name="Test" version="1.0.1" compatVersion="1.0.0">
        <vendor>MyCompany</vendor>
        <copyright>(C) 2007 MyCompany</copyright>
        <license>
    This is a default license bla
    blubbblubb
    end of terms
        </license>
        <description>
    This plugin is just a test.
    it demonstrates the great use of the plugin spec.
        </description>
        <url>http://www.mycompany-online.com/products/greatplugin</url>
        <dependencyList>
            <dependency name="SomeOtherPlugin" version="2.3.0_2"/>
            <dependency name="EvenOther" version="1.0.0"/>
        </dependencyList>
        <argumentList>
            <argument name="-variant" parameter="fancy|boring">Brings up the fancy or boring user interface</argument>
        </argumentList>
    </plugin>

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.