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
.
Key | Value Type | Meaning |
---|---|---|
Name | String | This is used as an identifier for the plugin and can e.g. be referenced in other plugin's dependencies. |
Version | String | Version string in the form x.y.z_n , used for identifying the plugin. Also see A Note on Plugin Versions. |
CompatVersion | String | Optional. 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). |
Experimental | Boolean | Optional. 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. |
DisabledByDefault | Boolean | Optional. 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. |
Deprecated | Boolean | Optional. Defaults to false . Deprecated plugins are not loaded by default but must be explicitly enabled by the user. This attribute is a hint that the plugin is no longer supported and might negatively affect the user experience. |
SoftLoadable | Boolean | Optional. Defaults to false . Soft loadable plugins can be loaded during runtime without a restart. This is possible for plugins that only hook into functionality that supports updating during runtime. |
Required | Boolean | Optional. Defaults to false . Is used as a hint for the About Plugins... dialog, that the user may not manually disable this plugin. Only used for the Core plugin. |
Platform | String | Optional. A regular expression that matches the names of the platforms the plugin works on. Omitting the tag implies that the plugin is loaded on all platforms. |
Plugin-describing Keys
These are solely used for more detailed (user centric) description of the plugin. All of these are optional.
Key | Value Type | Meaning |
---|---|---|
Category | String | Defaults to Utilities . Is used to put related plugins under the same tree node in the plugin overview About Plugins.... |
Vendor | String | String that describes the plugin creator/vendor, like MyCompany . |
Copyright | String | A short copyright notice, like (C) 2016 MyCompany . |
License | String or array of strings | Possibly multi-line license information about the plugin. Should still be kept relatively short, since the UI is not designed for long texts. |
Description | String | Short description of what the plugin is supposed to provide. This is shown when running Qt Creator with -version . |
LongDescription | String or array of strings | Possibly multi-line, more extensive description of what the plugin is supposed to provide. Should still be kept relatively short, since the UI is not designed for long texts. |
Url | String | Link 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 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
matchesDependencyName
, 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
.
Key | Value Type | Meaning |
---|---|---|
Dependencies | Array of dependency objects | Describes the dependencies on other plugins. |
A dependency object is a JSON object with the following keys:
Key | Value Type | Meaning |
---|---|---|
Name | String | The name of the plugin, on which this plugin relies. |
Version | String | The 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. |
Type | String | Optional. Value Required , Optional , or Test . Defines if the dependency is a hard requirement, optional, or required for running the plugin's tests. Defaults to Required . |
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
.
Key | Value Type | Meaning |
---|---|---|
Arguments | Array of argument objects | Describes the command-line arguments that the plugin wants to handle. |
An argument object is a JSON object with the following keys:
Key | Value Type | Meaning |
---|---|---|
Name | String | The command-line argument itself, including the - prefix, e.g. -my-parameter . |
Parameter | String | Optional. 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. |
Description | String | Optional. A (one-line) description of the argument for the command-line argument help. |
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" } ] }
Other Meta Data
Key | Value Type | Meaning |
---|---|---|
Mimetypes | String or array of strings | Possibly multiple lines of XML MIME-info used for registering additional or adapting built-in MIME types. |
JsonWizardPaths | Array of strings | A list of paths relative to the plugin location or paths to the Qt resource system that are searched for template-based wizards. |
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
.
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.