Commit 855e4eac authored by Eike Ziller's avatar Eike Ziller

Add document on plugin life cycle.

Change-Id: Iec868cdb8158726d91bcece935a9d6269219c056
Reviewed-by: default avatarLeena Miettinen <riitta-leena.miettinen@nokia.com>
parent 66949f2b
/****************************************************************************
**
** 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-lifecycle.html
\title Plugin Life Cycle
To be able to write \QC plugins, you must understand the steps that the plugin
manager takes when you start or shut down \QC. This section describes
the process and the state that plugins go through in detail.
When you start \QC, the plugin manager does the following:
\list 1
\o Looks in its search paths for
all .pluginspec files, and reads them. This is the first point where
loading a plugin can fail in the worst case of a malformed plugin spec.
\o Creates an instance of the \l{ExtensionSystem::PluginSpec} class for
each plugin. This class is a container for
all the information from the plugin specification, and additionally
tracks the state of the plugin.
You can get the \l{ExtensionSystem::PluginSpec} instances via the
plugin manager's \l{ExtensionSystem::PluginManager::plugins()}{plugins()}
method, or, after a plugin is loaded, through the plugin's
\l{ExtensionSystem::IPlugin::pluginSpec()}{pluginSpec()} method.
\o Sets the plugins to \c Read state.
\o Verifies that the dependencies of each plugin
exist and are compatible. For more information about plugin dependencies,
see \l{Plugin Specifications}.
\o Sets the plugins to \c Resolved state.
\o Sorts all plugins into a list that we call the \e{load queue}, where the
dependencies of a plugin are positioned after the plugin
(but not necessarily \e directly after the plugin).
It will make sure that we load
and initialize the plugins in proper order.
\o Loads the plugins' libraries, and creates their IPlugin instances
in the order of the load queue. At this point the
plugin constructors are called. Plugins that other plugins depend on
are created first.
\o Sets the plugins to \c Loaded state.
\o Calls the \l{ExtensionSystem::IPlugin::initialize()}{initialize()} methods of
all plugins in the order of the load queue. In the initialize method,
a plugin should make sure that all exported interfaces are set up and available
to other plugins. A plugin can assume that plugins they depend on have set up
their exported interfaces. For example, the \c Core plugin sets up the
\l{Core::ActionManager}, \l{Core::EditorManager} and all other publicly available
interfaces, so other plugins can request and use them.
The \l{ExtensionSystem::IPlugin::initialize()}{initialize()} method of a plugin
is a good place for
\list
\o registering objects in the plugin manager's object pool
(see \l{The Plugin Manager, the Object Pool, and Registered Objects})
\o loading settings
\o adding new menus, and new actions to menus
\o connecting to other plugin's signals.
\endlist
\o Sets the plugins to \c Initialized state.
\o Calls the \l{ExtensionSystem::IPlugin::extensionsInitialized()}{extensionsInitialized()}
methods of all plugins in \e reverse order of the load queue. After
the extensionsInitialized method, a plugin should be fully initialized, set up
and running. A plugin can assume that plugins that depend on it are fully set up,
and can finish the initialization of parts that can be extended by other plugins.
For example, the \c Core plugin assumes that all plugins have registered
their actions, and finishes initialization of the action manager.
\o Sets the plugins to \c Running state.
\endlist
At the end of startup, the \c Core plugin's \l{Core::ICore} sends two signals.
Before the \QC UI is shown it sends \l{Core::ICore::coreAboutToOpen()}{coreAboutToOpen()},
and afterwards \l{Core::ICore::coreOpened()}{coreOpened()}.
Before shutdown, the \c Core plugin's \l{Core::ICore} sends the
\l{Core::ICore::coreAboutToClose()}{coreAboutToClose()} signal. After that, the
plugin manager starts its shutdown sequence:
\list 1
\o Calls the \l{ExtensionSystem::IPlugin::aboutToShutdown()}{aboutToShutdown()} methods of
all plugins in the order of the load queue. Plugins should perform measures
for speeding up the actual shutdown here, like disconnecting signals that
would otherwise needlessly be called.
If a plugin needs to delay the real shutdown for a while, for example if
it needs to wait for external processes to finish for a clean shutdown,
the plugin can return \l{ExtensionSystem::IPlugin::AsynchronousShutdown} from this
method. This will make the plugin manager wait with the next step, and keep the main
event loop running, until all plugins requesting AsynchronousShutdown have sent
the asynchronousShutdownFinished() signal.
\o Destroys all plugins by deleting their \l{ExtensionSystem::IPlugin}
instances in \e reverse order of the load queue. At this point the plugin destructors
are called. Plugins should clean up after themselves by freeing memory and other resources.
\endlist
*/
......@@ -180,7 +180,8 @@
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.
it passes them on to the plugin's
\l{ExtensionSystem::IPlugin::initialize()}{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,
......
......@@ -55,6 +55,7 @@ DEV_HELP_DEP_FILES = \
$$PWD/api/getting-and-building.qdoc \
$$PWD/api/first-plugin.qdoc \
$$PWD/api/plugin-specifications.qdoc \
$$PWD/api/plugin-lifecycle.qdoc \
$$PWD/api/qtcreator-dev.qdocconf
dev_html_docs.commands = $$qdoc($$OUT_PWD/doc/html-dev) $$PWD/api/qtcreator-dev.qdocconf
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment