| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** 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. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \page deployment-plugins.html |
| \title Deploying Plugins |
| \brief A guide to the plugin-specific aspects of deploying Qt and Qt Applications. |
| |
| 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 |
| |
| 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 the plugin |
| can be loaded and used. This sanity check enables you to have multiple Qt versions and |
| configurations installed side by side. |
| |
| The following rules apply: |
| |
| \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. |
| |
| \br |
| \b{Example:} Qt 5.0.0 will \e{not} load a plugin built with Qt 5.0.1. |
| |
| \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'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 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 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. |
| |
| 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 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 \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 |
| |
| */ |