forked from qt-creator/qt-creator
b8dbac0b9c
Only methods as programming functions are affected. Besides renaming
some actions like "Switch Between Function Declaration/Definition" this
mostly touches (api) code comments.
This is a follow-up patch to commit 872bfb7.
Change-Id: Icb65e8d73b59a022f8885b14df497169543a3b92
Reviewed-by: hjk <hjk121@nokiamail.com>
280 lines
12 KiB
Plaintext
280 lines
12 KiB
Plaintext
/**************************************************************************
|
|
**
|
|
** Copyright (c) 2013 Digia Plc and/or its subsidiary(-ies).
|
|
** Contact: http://www.qt-project.org/legal
|
|
**
|
|
** This file is part of Qt Creator
|
|
**
|
|
**
|
|
** GNU Free Documentation License
|
|
**
|
|
** Alternatively, this file may be used under the terms of the GNU Free
|
|
** Documentation License version 1.3 as published by the Free Software
|
|
** Foundation and appearing in the file included in the packaging of this
|
|
** file.
|
|
**
|
|
**
|
|
**************************************************************************/
|
|
|
|
/*!
|
|
\page plugin-specifications.html
|
|
\title 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 \c .pluginspec extension.
|
|
|
|
\section2 Main Tag
|
|
|
|
The root tag is \c plugin. It has the mandatory attributes \c name
|
|
and \c version, and the optional attributes \c compatVersion, \c experimental
|
|
and \c disabledByDefault.
|
|
\table
|
|
\header
|
|
\li Tag
|
|
\li Meaning
|
|
\row
|
|
\li plugin
|
|
\li Root element in a plugin's XML file.
|
|
\endtable
|
|
\table
|
|
\header
|
|
\li Attribute
|
|
\li Meaning
|
|
\row
|
|
\li name
|
|
\li This 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 \c{lib[name].[dll|.so|.dylib]}. (Depending on platform.
|
|
If you use the same string as the \c TARGET in your plugin's
|
|
.pro-file, you are fine.)
|
|
\row
|
|
\li version
|
|
\li Version string in the form \c{x.y.z_n}, used for identifying
|
|
the plugin. Also see \l{A Note on Plugin Versions}.
|
|
\row
|
|
\li compatVersion
|
|
\li Optional. If not given, it is implicitly
|
|
set to the same value as \c 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 \c version of \c{2.1.1} and a
|
|
\c compatVersion of \c{2.0.0} means that this version \c{2.1.1} of the plugin
|
|
is binary backward compatible with all versions of the plugin down to \c{2.0.0}
|
|
(inclusive).
|
|
\row
|
|
\li experimental
|
|
\li Optional. Can be \c true or \c false, defaults to \c 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.
|
|
\row
|
|
\li disabledByDefault
|
|
\li Optional. Can be \c true or \c false, defaults to \c 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.
|
|
\endtable
|
|
|
|
\section2 Plugin-describing Tags
|
|
|
|
These are direct children of the \c plugin tag, and are solely used
|
|
for more detailed (user centric) description of the plugin. All of these
|
|
are optional.
|
|
\table
|
|
\header
|
|
\li Tag
|
|
\li Meaning
|
|
\row
|
|
\li category
|
|
\li Defaults to \c Utilities. Is used to put related plugins
|
|
under the same tree node in the plugin overview \gui{About Plugins...}.
|
|
\row
|
|
\li vendor
|
|
\li String that describes the plugin creator/vendor,
|
|
like \c{MyCompany}.
|
|
\row
|
|
\li copyright
|
|
\li A short copyright notice, like \c{(C) 2007-2008 MyCompany}.
|
|
\row
|
|
\li platform
|
|
\li 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.
|
|
\row
|
|
\li license
|
|
\li Possibly multi-line license information about the plugin.
|
|
Should still be kept relatively short, since the UI is not
|
|
designed for long texts.
|
|
\row
|
|
\li description
|
|
\li Possibly 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.
|
|
\row
|
|
\li url
|
|
\li Link to further information about the plugin, like
|
|
\c{http://www.mycompany-online.com/products/greatplugin}.
|
|
\endtable
|
|
|
|
\section2 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 \c dependency tag,
|
|
with required attributes \c name and \c version. All \c dependency tags
|
|
must be enclosed in a single \c dependencyList tag, which is an optional
|
|
child of the \c 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 \c dependency tag) is denoted as \c dependencyName
|
|
and the required version of the plugin is denoted as \c dependencyVersion.
|
|
A plugin with given \c name, \c version and \c compatVersion
|
|
(as defined in the attributes of the plugin's \c plugin tag) matches
|
|
the dependency if
|
|
\list
|
|
\li its \c name matches \c dependencyName, and
|
|
\li \c {compatVersion <= dependencyVersion <= version}.
|
|
\endlist
|
|
For example a dependency
|
|
\code
|
|
<dependency name="SomeOtherPlugin" version="2.3.0_2"/>
|
|
\endcode
|
|
would be matched by a plugin with
|
|
\code
|
|
<plugin name="SomeOtherPlugin" version="3.1.0" compatVersion="2.2.0">
|
|
\endcode
|
|
since the name matches, and the version \c{2.3.0_2} given in the dependency tag
|
|
lies in the range of \c{2.2.0} and \c{3.1.0}.
|
|
|
|
\table
|
|
\header
|
|
\li Tag
|
|
\li Meaning
|
|
\row
|
|
\li dependency
|
|
\li Describes a dependency on another plugin.
|
|
\endtable
|
|
\table
|
|
\header
|
|
\li Attribute
|
|
\li Meaning
|
|
\row
|
|
\li name
|
|
\li The name of the plugin, on which this plugin relies.
|
|
\row
|
|
\li version
|
|
\li The version to which the plugin must be compatible to
|
|
fill the dependency, in the form \c{x.y.z_n}.
|
|
Can be empty if the version does not matter.
|
|
\row
|
|
\li type
|
|
\li Optional. Value \c required or \c optional. Defines if the dependency is
|
|
a hard requirement or optional. Defaults to \c{required}.
|
|
\endtable
|
|
|
|
\section3 Optional Dependencies
|
|
|
|
A plugin can specify that a dependency on another plugin is optional, by adding the
|
|
\c {type="optional"} attribute to the \c dependency tag:
|
|
|
|
\list
|
|
\li If the dependency can be resolved, the plugin and
|
|
its dependency are loaded and initialized as for \c required dependencies.
|
|
\li If the dependency cannot be resolved, the plugin is loaded and initialized
|
|
as if the dependency was not declared at all.
|
|
\endlist
|
|
|
|
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
|
|
\l{The Plugin Manager, the Object Pool, and Registered Objects}{global object pool}
|
|
via ExtensionSystem::PluginManager::getObjectByName() or
|
|
ExtensionSystem::PluginManager::getObjectByClassName(), and use QMetaObject functions to call
|
|
functions on it.
|
|
|
|
\section2 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 \c{-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
|
|
\l{ExtensionSystem::IPlugin::initialize()}{initialize()} function.
|
|
|
|
All command line argument definitions are enclosed by a single \c argumentList
|
|
tag. The individual command line arguments are defined by the \c argument tag,
|
|
with required attribute \c name and an optional attribute \c parameter if the
|
|
command line argument takes an additional parameter. The text that is enclosed
|
|
in the \c argument tag is used as a (one-line) description in the command line
|
|
argument help.
|
|
|
|
\table
|
|
\header
|
|
\li Tag
|
|
\li Meaning
|
|
\row
|
|
\li argument
|
|
\li Describes a command line argument that the plugin wants to handle.
|
|
\endtable
|
|
\table
|
|
\header
|
|
\li Attribute
|
|
\li Meaning
|
|
\row
|
|
\li name
|
|
\li The command line argument itself, including the \c - prefix, e.g.
|
|
\c{-my-parameter}.
|
|
\row
|
|
\li parameter
|
|
\li Optional. If this is given, the command line argument expects an
|
|
additional parameter, e.g. \c{-my-parameter somevalue}. The
|
|
value of this attribute is used as a very short description of the
|
|
parameter for the user.
|
|
\endtable
|
|
|
|
\section2 Example \c Test.pluginspec
|
|
|
|
\code
|
|
<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>
|
|
\endcode
|
|
|
|
\section2 A Note on Plugin Versions
|
|
|
|
Plugin versions are in the form \c{x.y.z_n} where, \c x, \c y, \c z and \c 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, \c{2.10_2} is equal to \c{2.10.0_2}, and \c 1 is the same as \c{1.0.0_0}.
|
|
|
|
*/
|