diff --git a/doc/api/plugin-specifications.qdoc b/doc/api/plugin-specifications.qdoc
new file mode 100644
index 0000000000000000000000000000000000000000..6469dff998c80178c4d68499b174ddd01f109035
--- /dev/null
+++ b/doc/api/plugin-specifications.qdoc
@@ -0,0 +1,249 @@
+/****************************************************************************
+**
+** This file is part of Qt Creator
+**
+** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
+**
+** Contact: Nokia Corporation (info@qt.nokia.com)
+**
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at info@qt.nokia.com.
+**
+****************************************************************************/
+
+/*!
+ \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 and \c experimental.
+ \table
+ \header
+ \o Tag
+ \o Meaning
+ \row
+ \o plugin
+ \o Root element in a plugin's XML file.
+ \endtable
+ \table
+ \header
+ \o Attribute
+ \o Meaning
+ \row
+ \o name
+ \o 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
+ \o version
+ \o Version string in the form \c{x.y.z_n}, used for identifying
+ the plugin. Also see \l{A Note on Plugin Versions}.
+ \row
+ \o compatVersion
+ \o 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
+ \o experimental
+ \o Optional. Can be \c yes or \c no, defaults to \c no.
+ Experimental plugins are not loaded by default but must be explicitly
+ enabled by the user.
+ \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
+ \o Tag
+ \o Meaning
+ \row
+ \o category
+ \o Defaults to \c Utilities. Is used to put related plugins
+ under the same tree node in the plugin overview \gui{About Plugins...}.
+ \row
+ \o vendor
+ \o String that describes the plugin creator/vendor,
+ like \c{MyCompany}.
+ \row
+ \o copyright
+ \o A short copyright notice, like \c{(C) 2007-2008 MyCompany}.
+ \row
+ \o license
+ \o Possibly multi-line license information about the plugin.
+ Should still be kept relatively short, since the UI is not
+ designed for long texts.
+ \row
+ \o description
+ \o 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
+ \o url
+ \o 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
+ \o its \c name matches \c dependencyName, and
+ \o \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
+ \o Tag
+ \o Meaning
+ \row
+ \o dependency
+ \o Describes a dependency on another plugin.
+ \endtable
+ \table
+ \header
+ \o Attribute
+ \o Meaning
+ \row
+ \o name
+ \o The name of the plugin, on which this plugin relies.
+ \row
+ \o version
+ \o 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
+ \o type
+ \o Optional. Value \c required or \c optional. Defines if the dependency is
+ a hard requirement or optional. Defaults to \c{required}.
+ \endtable
+
+ \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{IPlugin::initialize} method.
+
+ 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
+ \o Tag
+ \o Meaning
+ \row
+ \o argument
+ \o Describes a command line argument that the plugin wants to handle.
+ \endtable
+ \table
+ \header
+ \o Attribute
+ \o Meaning
+ \row
+ \o name
+ \o The command line argument itself, including the \c - prefix, e.g.
+ \c{-my-parameter}.
+ \row
+ \o parameter
+ \o 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}.
+
+*/
diff --git a/doc/doc.pri b/doc/doc.pri
index 8b5995c105391b51d7fd463ecaff3c25cd8ea8f1..be1c1dcf0bbaa394ab68c8bf8361cb0607428f82 100644
--- a/doc/doc.pri
+++ b/doc/doc.pri
@@ -54,6 +54,7 @@ DEV_HELP_DEP_FILES = \
$$PWD/api/creating-plugins.qdoc \
$$PWD/api/getting-and-building.qdoc \
$$PWD/api/first-plugin.qdoc \
+ $$PWD/api/plugin-specifications.qdoc \
$$PWD/api/qtcreator-dev.qdocconf
dev_html_docs.commands = $$qdoc($$OUT_PWD/doc/html-dev) $$PWD/api/qtcreator-dev.qdocconf
diff --git a/src/libs/extensionsystem/iplugin.cpp b/src/libs/extensionsystem/iplugin.cpp
index 8748d9ed0999b5e7f506d679589d4e75d5c1c595..ff2df1e11a2f763db6f5e3a1ce337015320c8061 100644
--- a/src/libs/extensionsystem/iplugin.cpp
+++ b/src/libs/extensionsystem/iplugin.cpp
@@ -48,167 +48,29 @@
\tableofcontents
\section1 Plugin Specification
- The plugin specification file is an xml file that contains all
- information that are necessary for loading the plugin's library,
- plus some textual descriptions. The file must be located in
- (a subdir of) one of the plugin manager's plugin search paths,
- and must have the \c .xml extension.
- \section2 Main Tag
- The root tag is \c plugin. It has mandatory attributes \c name
- and \c version, and an optional \c compatVersion.
- \table
- \header
- \o Tag
- \o Meaning
- \row
- \o plugin
- \o Root element in a plugin's xml file.
- \endtable
- \table
- \header
- \o Attribute
- \o Meaning
- \row
- \o name
- \o 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].
- \row
- \o version
- \o Version string in the form \c {"x.y.z_n"}, used for identifying
- the plugin.
- \row
- \o compatVersion
- \o Compatibility version. Optional. If not given, it is implicitly
- set to the same value as \c version. The compatibility version
- is used to resolve dependencies on this plugin. See
- \l {Dependencies}{Dependencies} for details.
- \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
- \o Tag
- \o Meaning
- \row
- \o vendor
- \o String that describes the plugin creator/vendor,
- like \c {MyCompany}.
- \row
- \o copyright
- \o A short copyright notice, like \c {(C) 2007-2008 MyCompany}.
- \row
- \o license
- \o Possibly multi-line license information about the plugin.
- \row
- \o description
- \o Possibly multi-line description of what the plugin is supposed
- to provide.
- \row
- \o url
- \o 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's xml file as well, to ensure that
- these other plugins are loaded before this plugin.
- Dependency information consists of the name of the required plugin
- (lets denote that as \c {dependencyName}),
- and the required version of the plugin (\c {dependencyVersion}).
- A plugin with given \c name, \c version and \c compatVersion matches
- the dependency if
- \list
- \o its \c name matches \c dependencyName, and
- \o \c {compatVersion <= dependencyVersion <= version}.
- \endlist
-
- The xml element that describes dependencies is the \c dependency tag,
- with required attributes \c name and \c version. It is an
- optional direct child of the \c plugin tag and can appear multiple times.
- \table
- \header
- \o Tag
- \o Meaning
- \row
- \o dependency
- \o Describes a dependency on another plugin.
- \endtable
- \table
- \header
- \o Attribute
- \o Meaning
- \row
- \o name
- \o The name of the plugin, on which this plugin relies.
- \row
- \o version
- \o 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
- \o type
- \o Value 'required' or 'optional'. Defines if the dependency is
- a hard requirement or optional. Defaults to 'required'.
- \endtable
-
- \section2 Example \c plugin.xml
- \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>
- </plugin>
- \endcode
- The first dependency could for example be matched by a plugin with
- \code
- <plugin name="SomeOtherPlugin" version="3.1.0" compatVersion="2.2.0">
- </plugin>
- \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".
-
- \section2 A Note on Plugin Versions
- Plugin versions are in the form \c "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, \c "2.10_2" is equal to \c "2.10.0_2", and "1" is the same as "1.0.0_0".
+ A plugin needs to provide a plugin specification file in addition
+ to the actual plugin library, so the plugin manager can find the plugin,
+ resolve its dependencies, and load it. For more information,
+ see \l{Plugin Specifications}.
\section1 Plugin Implementation
Plugins must provide one implementation of the IPlugin class, located
in a library that matches the \c name attribute given in their
- xml description. The IPlugin implementation must be exported and
- made known to Qt's plugin system via the Q_EXPORT_PLUGIN macro, see the
- Qt documentation for details on that.
+ XML description. The IPlugin implementation must be exported and
+ made known to Qt's plugin system, see the Qt Documentation on the
+ \l{http://doc.qt.nokia.com/4.7/qtplugin.html#Q_EXPORT_PLUGIN2}
+ {Q_EXPORT_PLUGIN2 macro}.
- After the plugins' xml files have been read, and dependencies have been
+ After the plugins' XML files have been read, and dependencies have been
found, the plugin loading is done in three phases:
\list 1
- \o All plugin libraries are loaded in 'root-to-leaf' order of the
+ \o All plugin libraries are loaded in \e{root-to-leaf} order of the
dependency tree.
- \o All plugins' initialize methods are called in 'root-to-leaf' order
+ \o All plugins' initialize methods are called in \e{root-to-leaf} order
of the dependency tree. This is a good place to put
objects in the plugin manager's object pool.
- \o All plugins' extensionsInitialized methods are called in 'leaf-to-root'
+ \o All plugins' extensionsInitialized methods are called in \e{leaf-to-root}
order of the dependency tree. At this point, plugins can
be sure that all plugins that depend on this plugin have
been initialized completely (implying that they have put