|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \page deployment-plugins.html |
|
44 \title Deploying Plugins |
|
45 \brief A guide to plugins-specific aspects of deploying Qt and Qt Application |
|
46 |
|
47 This document explains how to deploy plugin libraries that Qt or |
|
48 your application should load at runtime. If you use |
|
49 \l{How to Create Qt Plugins#Static Plugins}{static plugins}, then the |
|
50 plugin code is already part of your application executable, and no |
|
51 separate deployment steps are required. |
|
52 |
|
53 \tableofcontents |
|
54 |
|
55 \section1 The Plugin Directory |
|
56 |
|
57 When the application is run, Qt will first treat the application's |
|
58 executable directory as the \c{pluginsbase}. For example if the |
|
59 application is in \c{C:\Program Files\MyApp} and has a style plugin, |
|
60 Qt will look in \c{C:\Program Files\MyApp\styles}. (See |
|
61 QCoreApplication::applicationDirPath() for how to find out where |
|
62 the application's executable is.) Qt will also look in the |
|
63 directory specified by |
|
64 QLibraryInfo::location(QLibraryInfo::PluginsPath), which typically |
|
65 is located in \c QTDIR/plugins (where \c QTDIR is the directory |
|
66 where Qt is installed). If you want Qt to look in additional |
|
67 places you can add as many paths as you need with calls to |
|
68 QCoreApplication::addLibraryPath(). And if you want to set your |
|
69 own path or paths you can use QCoreApplication::setLibraryPaths(). |
|
70 You can also use a \c qt.conf file to override the hard-coded |
|
71 paths that are compiled into the Qt library. For more information, |
|
72 see the \l {Using qt.conf} documentation. Yet another possibility |
|
73 is to set the \c QT_PLUGIN_PATH environment variable before running |
|
74 the application. If set, Qt will look for plugins in the |
|
75 paths (separated by the system path separator) specified in the variable. |
|
76 |
|
77 \section1 Loading and Verifying Plugins Dynamically |
|
78 |
|
79 When loading plugins, the Qt library does some sanity checking to |
|
80 determine whether or not the plugin can be loaded and used. This |
|
81 provides the ability to have multiple versions and configurations of |
|
82 the Qt library installed side by side. |
|
83 |
|
84 \list |
|
85 \o Plugins linked with a Qt library that has a higher version number |
|
86 will not be loaded by a library with a lower version number. |
|
87 |
|
88 \br |
|
89 \bold{Example:} Qt 4.3.0 will \e{not} load a plugin built with Qt 4.3.1. |
|
90 |
|
91 \o Plugins linked with a Qt library that has a lower major version |
|
92 number will not be loaded by a library with a higher major version |
|
93 number. |
|
94 |
|
95 \br |
|
96 \bold{Example:} Qt 4.3.1 will \e{not} load a plugin built with Qt 3.3.1. |
|
97 \br |
|
98 \bold{Example:} Qt 4.3.1 will load plugins built with Qt 4.3.0 and Qt 4.2.3. |
|
99 |
|
100 \o The Qt library and all plugins are built using a \e {build |
|
101 key}. The build key in the Qt library is examined against the build |
|
102 key in the plugin, and if they match, the plugin is loaded. If the |
|
103 build keys do not match, then the Qt library refuses to load the |
|
104 plugin. |
|
105 |
|
106 \br \bold{Rationale:} See the \l{#The Build Key}{The Build Key} section below. |
|
107 \endlist |
|
108 |
|
109 When building plugins to extend an application, it is important to ensure |
|
110 that the plugin is configured in the same way as the application. This means |
|
111 that if the application was built in release mode, plugins should be built |
|
112 in release mode, too. |
|
113 |
|
114 If you configure Qt to be built in both debug and release modes, |
|
115 but only build applications in release mode, you need to ensure that your |
|
116 plugins are also built in release mode. By default, if a debug build of Qt is |
|
117 available, plugins will \e only be built in debug mode. To force the |
|
118 plugins to be built in release mode, add the following line to the plugin's |
|
119 project file: |
|
120 |
|
121 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 3 |
|
122 |
|
123 This will ensure that the plugin is compatible with the version of the library |
|
124 used in the application. |
|
125 |
|
126 \section2 The Build Key |
|
127 |
|
128 When loading plugins, Qt checks the build key of each plugin against its |
|
129 own configuration to ensure that only compatible plugins are loaded; any |
|
130 plugins that are configured differently are not loaded. |
|
131 |
|
132 The build key contains the following information: |
|
133 \list |
|
134 \o Architecture, operating system and compiler. |
|
135 |
|
136 \e {Rationale:} |
|
137 In cases where different versions of the same compiler do not |
|
138 produce binary compatible code, the version of the compiler is |
|
139 also present in the build key. |
|
140 |
|
141 \o Configuration of the Qt library. The configuration is a list |
|
142 of the missing features that affect the available API in the |
|
143 library. |
|
144 |
|
145 \e {Rationale:} |
|
146 Two different configurations of the same version of |
|
147 the Qt library are not binary compatible. The Qt library that |
|
148 loads the plugin uses the list of (missing) features to |
|
149 determine if the plugin is binary compatible. |
|
150 |
|
151 \e {Note:} There are cases where a plugin can use features that are |
|
152 available in two different configurations. However, the |
|
153 developer writing plugins would need to know which features are |
|
154 in use, both in their plugin and internally by the utility |
|
155 classes in Qt. The Qt library would require complex feature |
|
156 and dependency queries and verification when loading plugins. |
|
157 Requiring this would place an unnecessary burden on the developer, and |
|
158 increase the overhead of loading a plugin. To reduce both |
|
159 development time and application runtime costs, a simple string |
|
160 comparision of the build keys is used. |
|
161 |
|
162 \o Optionally, an extra string may be specified on the configure |
|
163 script command line. |
|
164 |
|
165 \e {Rationale:} |
|
166 When distributing binaries of the Qt library with an |
|
167 application, this provides a way for developers to write |
|
168 plugins that can only be loaded by the library with which the |
|
169 plugins were linked. |
|
170 \endlist |
|
171 |
|
172 For debugging purposes, it is possible to override the run-time build key |
|
173 checks by configuring Qt with the \c QT_NO_PLUGIN_CHECK preprocessor macro |
|
174 defined. |
|
175 |
|
176 \section1 The Plugin Cache |
|
177 |
|
178 In order to speed up loading and validation of plugins, some of |
|
179 the information that is collected when plugins are loaded is cached |
|
180 through QSettings. This includes information about whether or not |
|
181 a plugin was successfully loaded, so that subsequent load operations |
|
182 don't try to load an invalid plugin. However, if the "last modified" |
|
183 timestamp of a plugin has changed, the plugin's cache entry is |
|
184 invalidated and the plugin is reloaded regardless of the values in |
|
185 the cache entry, and the cache entry itself is updated with the new |
|
186 result. |
|
187 |
|
188 This also means that the timestamp must be updated each time the |
|
189 plugin or any dependent resources (such as a shared library) is |
|
190 updated, since the dependent resources might influence the result |
|
191 of loading a plugin. |
|
192 |
|
193 Sometimes, when developing plugins, it is necessary to remove entries |
|
194 from the plugin cache. Since Qt uses QSettings to manage the plugin |
|
195 cache, the locations of plugins are platform-dependent; see |
|
196 \l{QSettings#Platform-Specific Notes}{the QSettings documentation} |
|
197 for more information about each platform. |
|
198 |
|
199 For example, on Windows the entries are stored in the registry, and the |
|
200 paths for each plugin will typically begin with either of these two strings: |
|
201 |
|
202 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 6 |
|
203 |
|
204 \section1 Debugging Plugins |
|
205 |
|
206 There are a number of issues that may prevent correctly-written plugins from |
|
207 working with the applications that are designed to use them. Many of these |
|
208 are related to differences in the way that plugins and applications have been |
|
209 built, often arising from separate build systems and processes. |
|
210 |
|
211 The following table contains descriptions of the common causes of problems |
|
212 developers experience when creating plugins: |
|
213 |
|
214 \table |
|
215 \header \o Problem \o Cause \o Solution |
|
216 \row \o Plugins sliently fail to load even when opened directly by the |
|
217 application. \QD shows the plugin libraries in its |
|
218 \gui{Help|About Plugins} dialog, but no plugins are listed under each |
|
219 of them. |
|
220 \o The application and its plugins are built in different modes. |
|
221 \o Either share the same build information or build the plugins in both |
|
222 debug and release modes by appending the \c debug_and_release to |
|
223 the \l{qmake Variable Reference#CONFIG}{CONFIG} variable in each of |
|
224 their project files. |
|
225 \row \o A valid plugin that replaces an invalid (or broken) plugin fails to load. |
|
226 \o The entry for the plugin in the plugin cache indicates that the original |
|
227 plugin could not be loaded, causing Qt to ignore the replacement. |
|
228 \o Either ensure that the plugin's timestamp is updated, or delete the |
|
229 entry in the \l{#The Plugin Cache}{plugin cache}. |
|
230 \endtable |
|
231 |
|
232 You can also use the \c QT_DEBUG_PLUGINS environment variable to obtain |
|
233 diagnostic information from Qt about each plugin it tries to load. Set this |
|
234 variable to a non-zero value in the environment from which your application is |
|
235 launched. |
|
236 */ |