diff options
Diffstat (limited to 'doc/src/deployment/deployment-plugins.qdoc')
-rw-r--r-- | doc/src/deployment/deployment-plugins.qdoc | 154 |
1 files changed, 75 insertions, 79 deletions
diff --git a/doc/src/deployment/deployment-plugins.qdoc b/doc/src/deployment/deployment-plugins.qdoc index ff2bc1c88..69d8f1ba6 100644 --- a/doc/src/deployment/deployment-plugins.qdoc +++ b/doc/src/deployment/deployment-plugins.qdoc @@ -28,111 +28,107 @@ /*! \page deployment-plugins.html \title Deploying Plugins - \brief A guide to plugins-specific aspects of deploying Qt and Qt Application + \brief A guide to the plugin-specific aspects of deploying Qt and Qt Applications. - This document explains how to deploy plugin libraries that Qt or - your application should load at runtime. If you use - \l{How to Create Qt Plugins#Static Plugins}{static plugins}, then the - plugin code is already part of your application executable, and no - separate deployment steps are required. - - \tableofcontents + This topic explains how to deploy plugin libraries for Qt or your application to load at + runtime. If you use \l{How to Create Qt Plugins#Static Plugins}{static plugins}, then the + plugin code is already part of your application executable and no separate deployment steps + are required. \section1 The Plugin Directory - When the application is run, Qt will first treat the application's - executable directory as the base directory for searching for plugins. - For example if the - application is in \c{C:\Program Files\MyApp} and has a style plugin, - Qt will look in \c{C:\Program Files\MyApp\styles}. (See - QCoreApplication::applicationDirPath() for how to find out where - the application's executable is.) Qt will also look in the - directory specified by - QLibraryInfo::location(QLibraryInfo::PluginsPath), which typically - is located in \c QTDIR/plugins (where \c QTDIR is the directory - where Qt is installed). If you want Qt to look in additional - places you can add as many paths as you need with calls to - QCoreApplication::addLibraryPath(). And if you want to set your - own path or paths you can use QCoreApplication::setLibraryPaths(). - You can also use a \c qt.conf file to override the hard-coded - paths that are compiled into the Qt library. For more information, - see the \l {Using qt.conf} documentation. Yet another possibility - is to set the \c QT_PLUGIN_PATH environment variable before running - the application. If set, Qt will look for plugins in the - paths (separated by the system path separator) specified in the variable. - \note \c QT_PLUGIN_PATH should not be exported as a system-wide - environment variable since it can interfere with other Qt installations. + In Qt, when an application starts, the application's executable directory is the base directory + where Qt searches for plugins. + + For example, on Windows, if the application is in \c{C:\Program Files\MyApp} and it has a style + plugin, Qt looks in \c{C:\Program Files\MyApp\styles}. + + To find out where your application's executable is located, see + QCoreApplication::applicationDirPath(). + + Qt also looks in the directory specified by QLibraryInfo::location(QLibraryInfo::PluginsPath), + which typically is located in \c QTDIR/plugins; \c QTDIR is the directory where Qt is installed. + If you want Qt to look in additional places you can add as many paths as you need with calls to + QCoreApplication::addLibraryPath(). If you want to set your own path(s), you can use + QCoreApplication::setLibraryPaths(). + + Alternatively, you can use a \c qt.conf file to override the hard-coded paths that are compiled + into the Qt library. For more information, see \l {Using qt.conf}. + + Another possibility is to set the \c QT_PLUGIN_PATH environment variable before you run the + application; multiple paths can be separated with a system path separator. When set, Qt looks + for plugins in the paths specified in this variable. + + \note Do not export \c QT_PLUGIN_PATH as a system-wide environment variable because it can + interfere with other Qt installations. \section1 Loading and Verifying Plugins Dynamically - When loading plugins, the Qt library does some sanity checking to - determine whether or not the plugin can be loaded and used. This - provides the ability to have multiple versions and configurations of - the Qt library installed side by side. + When loading plugins, the Qt library does some sanity checking to determine whether the plugin + can be loaded and used. This sanity check enables you to have multiple Qt versions and + configurations installed side by side. - \list - \li Plugins linked with a Qt library that has a higher version number - will not be loaded by a library with a lower version number. + The following rules apply: - \br - \b{Example:} Qt 5.0.0 will \e{not} load a plugin built with Qt 5.0.1. + \list + \li Plugins linked with a Qt library that has a higher version number will not be loaded by a + library with a lower version number. - \li Plugins linked with a Qt library that has a lower major version - number will not be loaded by a library with a higher major version - number. + \br + \b{Example:} Qt 5.0.0 will \e{not} load a plugin built with Qt 5.0.1. - \br - \b{Example:} Qt 5.0.1 will \e{not} load a plugin built with Qt 4.8.2. - \br - \b{Example:} Qt 5.1.1 will load plugins built with Qt 5.1.0 and Qt 5.0.3. + \li Plugins linked with a Qt library that has a lower major version number will not be loaded + by a library with a higher major version number. + \br + \b{Example:} Qt 5.0.1 will \e{not} load a plugin built with Qt 4.8.2. + \br + \b{Example:} Qt 5.1.1 will load plugins built with Qt 5.1.0 and Qt 5.0.3. \endlist - When building plugins to extend an application, it is important to ensure - that the plugin is configured in the same way as the application. This means - that if the application was built in release mode, plugins should be built - in release mode, too. Except for Unix operating systems, plugins build in - a different mode will not get loaded by the plugin system. + When building plugins to extend an application, it's important to ensure that the plugin is + configured in the same way as the application. This means that if the application was built in + release mode, plugins should be built in release mode, too. Except for Unix operating systems, + where the plugin system will not load plugins built in a different mode from the application. - If you configure Qt to be built in both debug and release modes, - but only build applications in release mode, you need to ensure that your - plugins are also built in release mode. By default, if a debug build of Qt is - available, plugins will \e only be built in debug mode. To force the - plugins to be built in release mode, add the following line to the plugin's - project file: + If you configure Qt to be built in both debug and release modes, but only build your + applications in release mode, you need to ensure that your plugins are also built in release + mode. By default, if a debug build of Qt is available, plugins will \e only be built in debug + mode. To force the plugins to be built in release mode, add the following line to the plugin's + project (\c{.pro}) file: \code CONFIG += release \endcode - This will ensure that the plugin is compatible with the version of the library - used in the application. + This ensures that the plugin is compatible with the version of the library used in the + application. \section1 Debugging Plugins - There are a number of issues that may prevent correctly-written plugins from - working with the applications that are designed to use them. Many of these - are related to differences in the way that plugins and applications have been - built, often arising from separate build systems and processes. + There are a number of issues that may prevent correctly-written plugins from working with the + applications that are designed to use them. Many of these are related to differences in the way + that plugins and applications have been built, often arising from separate build systems and + processes. + + To obtain diagnostic information from Qt, about each plugin it tries to load, use the + \c QT_DEBUG_PLUGINS environment variable. Set this variable to a non-zero value in the + environment where your application is launched. - The following table contains descriptions of the common causes of problems - developers experience when creating plugins: + The following table describes the common causes of problems developers experience when creating + plugins and possible solutions. \table - \header \li Problem \li Cause \li Solution - \row \li Plugins sliently fail to load even when opened directly by the - application. \QD shows the plugin libraries in its - \gui{Help|About Plugins} dialog, but no plugins are listed under each - of them. - \li The application and its plugins are built in different modes. - \li Either share the same build information or build the plugins in both - debug and release modes by appending the \c debug_and_release to - the \l{qmake Variable Reference#CONFIG}{CONFIG} variable in each of - their project files. + \header + \li Problem \li Cause \li Solution + \row + \li Plugins sliently fail to load even when opened directly by the application. + \QD shows the plugin libraries in its \uicontrol{Help|About Plugins} dialog, but no + plugins are listed under each of them. + \li The application and its plugins are built in different modes. + \li Either share the same build information or build the plugins in both debug and release + modes by appending the \c debug_and_release to the + \l{qmake Variable Reference#CONFIG}{CONFIG} variable in each of their project files. \endtable - You can also use the \c QT_DEBUG_PLUGINS environment variable to obtain - diagnostic information from Qt about each plugin it tries to load. Set this - variable to a non-zero value in the environment from which your application is - launched. */ |