Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
cmake-deploy-variables.qdoc
Go to the documentation of this file.
1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/* NOTE: The variables documented here are available when running a deploy
5** script, they are not available at configure time (i.e. when running
6** CMake). Both these and the set of configure-time variables are all
7** members of the cmake-variables-qtcore group.
8**/
9
10/*!
11\page cmake-variable-qt-deploy-prefix.html
12\ingroup cmake-variables-qtcore
13
14\title QT_DEPLOY_PREFIX
15\target cmake-variable-QT_DEPLOY_PREFIX
16
17\summary {Base location for a deployment.}
18
19\include cmake-deploy-var-usage.qdocinc
20
21\cmakevariablesince 6.3
22
23\c{QT_DEPLOY_PREFIX} provides the base deployment directory. The other
24\c{QT_DEPLOY_..._DIR} variables should be treated as relative to this location.
25The value of \c{QT_DEPLOY_PREFIX} may be relative or absolute, so projects
26should not assume one or the other in any given situation. A relative path is
27expected to be treated as relative to the current working directory, as seen
28by the build tool (ninja, make, and so on) at install time.
29
30The default value is \c{$ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}}, which is the
31base location CMake uses during installation. If that evaluates to an empty
32string, the default value will be a dot (.) instead, which is generally the
33appropriate value when deploying as part of a post-build rule. This two-step
34fallback logic ensures that projects can assume \c{QT_DEPLOY_PREFIX} will not
35be an empty string, so it can safely be used as part of a path like
36\c{${QT_DEPLOY_PREFIX}/${QT_DEPLOY_BIN_DIR}}.
37
38To change the value of \c QT_DEPLOY_PREFIX, the project can be configured
39with a custom \l CMAKE_INSTALL_PREFIX as described in
40\l {Command Line cmake invocation}.
41
42The \l DESTDIR environment variable can also be used to modify the final
43installation, and thus deployment, location.
44
45Projects should rarely need to use this variable. In typical scenarios, deploy
46scripts should assume that the working directory is already set to the base
47install location and just use the prefix-relative \c{QT_DEPLOY_..._DIR}
48variables.
49
50\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIBEXEC_DIR,
51 QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR,
52 QT_DEPLOY_TRANSLATIONS_DIR
53*/
54
55/*!
56\page cmake-variable-qt-deploy-bin-dir.html
57\ingroup cmake-variables-qtcore
58
59\title QT_DEPLOY_BIN_DIR
60\target cmake-variable-QT_DEPLOY_BIN_DIR
61
62\summary {Prefix-relative subdirectory for deploying runtime binaries on some target platforms.}
63
64\include cmake-deploy-var-usage.qdocinc
65
66\cmakevariablesince 6.3
67
68Projects should use \c QT_DEPLOY_BIN_DIR in their deploy scripts to avoid
69hard-coding a particular directory in which to deploy the following types of
70binaries:
71
72\list
73\li Executables on all platforms.
74\li DLLs on Windows.
75\endlist
76
77\c QT_DEPLOY_BIN_DIR defaults to the value of \c${CMAKE_INSTALL_BINDIR}
78(usually \c{bin}), which is provided by CMake's \l{GNUInstallDirs} module.
79To change the value of \c QT_DEPLOY_BIN_DIR, ensure that the project sets
80\c{CMAKE_INSTALL_BINDIR} before the \c Core package is found.
81
82The \c QT_DEPLOY_BIN_DIR path is relative to \l{QT_DEPLOY_PREFIX}.
83
84This variable is not meaningful when deploying into a macOS app bundle and
85should not be used for that scenario.
86
87\section1 Example
88
89\include cmake-deploy-runtime-dependencies.qdocinc
90
91\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_LIBEXEC_DIR,
92 QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR,
93 QT_DEPLOY_TRANSLATIONS_DIR
94*/
95
96/*!
97\page cmake-variable-qt-deploy-libexec-dir.html
98\ingroup cmake-variables-qtcore
99
100\title QT_DEPLOY_LIBEXEC_DIR
101\target cmake-variable-QT_DEPLOY_LIBEXEC_DIR
102
103\summary {Prefix-relative subdirectory for deploying program executables on some target platforms.}
104
105\include cmake-deploy-var-usage.qdocinc
106
107\cmakevariablesince 6.7
108
109On Unix derivatives, projects should use \c QT_DEPLOY_LIBEXEC_DIR in their
110deploy scripts to avoid hard-coding a particular directory in which to deploy
111helper executables that are local to the project.
112
113For example, projects using QtWebEngine would deploy the \c QtWebEngineProcess
114executable to this directory.
115
116\c QT_DEPLOY_LIBEXEC_DIR defaults to the value of \c${CMAKE_INSTALL_LIBEXECDIR}
117(usually \c{libexec}), which is provided by CMake's \l{GNUInstallDirs} module.
118To change the value of \c QT_DEPLOY_LIBEXEC_DIR, ensure that the project sets
119\c{CMAKE_INSTALL_LIBEXECDIR} before the \c Core package is found.
120
121The \c QT_DEPLOY_LIBEXEC_DIR path is relative to \l{QT_DEPLOY_PREFIX}.
122
123This variable is not meaningful when deploying into a macOS app bundle and
124should not be used for that scenario.
125
126\section1 Example
127
128\include cmake-deploy-modified-variable-values.qdocinc
129
130\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR,
131 QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR
132*/
133
134/*!
135\page cmake-variable-qt-deploy-lib-dir.html
136\ingroup cmake-variables-qtcore
137
138\title QT_DEPLOY_LIB_DIR
139\target cmake-variable-QT_DEPLOY_LIB_DIR
140
141\summary {Prefix-relative subdirectory for deploying libraries on some target platforms.}
142
143\include cmake-deploy-var-usage.qdocinc
144
145\cmakevariablesince 6.3
146
147Projects should use \c QT_DEPLOY_LIB_DIR in their deploy scripts to avoid
148hard-coding a particular directory in which to deploy the following types of
149binaries:
150
151\list
152\li Shared libraries on platforms other than Windows.
153\li Import libraries on Windows.
154\endlist
155
156\c QT_DEPLOY_LIB_DIR defaults to the value of \c${CMAKE_INSTALL_LIBDIR}
157(usually \c{lib} or \c{lib64}), which is provided by
158CMake's \l{GNUInstallDirs} module.
159To change the value of \c QT_DEPLOY_LIB_DIR, ensure that the project sets
160\c{CMAKE_INSTALL_LIBDIR} before the \c Core package is found.
161
162The \c QT_DEPLOY_LIB_DIR path is relative to \l{QT_DEPLOY_PREFIX}.
163
164This variable is not meaningful when deploying into a macOS app bundle and
165should not be used for that scenario.
166
167\section1 Example
168
169\include cmake-deploy-modified-variable-values.qdocinc
170
171\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR,
172 QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR
173*/
174
175/*!
176\page cmake-variable-qt-deploy-plugins-dir.html
177\ingroup cmake-variables-qtcore
178
179\title QT_DEPLOY_PLUGINS_DIR
180\target cmake-variable-QT_DEPLOY_PLUGINS_DIR
181
182\summary {Prefix-relative subdirectory for deploying Qt plugins on some target platforms.}
183
184\include cmake-deploy-var-usage.qdocinc
185
186\cmakevariablesince 6.3
187
188Projects should use \c QT_DEPLOY_PLUGINS_DIR in their deploy scripts to avoid
189hard-coding a particular directory under which to deploy plugins.
190
191\c QT_DEPLOY_PLUGINS_DIR defaults to the value \c{plugins}. To change the value
192of \c QT_DEPLOY_PLUGINS_DIR, set it in the project deployment script
193before \c QT_DEPLOY_SUPPORT is included.
194
195The \c QT_DEPLOY_PLUGINS_DIR path is relative to \l{QT_DEPLOY_PREFIX}.
196
197This variable is not meaningful when deploying into a macOS app bundle and
198should not be used for that scenario. Apple's macOS app bundle guidelines
199require all plugins to be deployed to the \c{PlugIns} subdirectory of the
200bundle contents.
201
202\section1 Example
203
204\include cmake-deploy-modified-variable-values.qdocinc
205
206\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR,
207 QT_DEPLOY_LIBEXEC_DIR, QT_DEPLOY_LIB_DIR, QT_DEPLOY_QML_DIR,
208 QT_DEPLOY_TRANSLATIONS_DIR
209*/
210
211/*!
212\page cmake-variable-qt-deploy-qml-dir.html
213\ingroup cmake-variables-qtcore
214
215\title QT_DEPLOY_QML_DIR
216\target cmake-variable-QT_DEPLOY_QML_DIR
217
218\summary {Prefix-relative subdirectory for deploying QML plugins on some target platforms.}
219
220\include cmake-deploy-var-usage.qdocinc
221
222\cmakevariablesince 6.3
223
224Projects should use \c QT_DEPLOY_QML_DIR in their deploy scripts to avoid
225hard-coding a particular directory under which to deploy QML modules.
226
227\c QT_DEPLOY_QML_DIR defaults to the value \c{qml}. To change the value
228of \c QT_DEPLOY_QML_DIR, set it in the project deployment script
229before \c QT_DEPLOY_SUPPORT is included.
230
231The \c QT_DEPLOY_QML_DIR path is relative to \l{QT_DEPLOY_PREFIX}.
232
233This variable is not meaningful when deploying into a macOS app bundle and
234should not be used for that scenario. Apple's macOS app bundle guidelines
235require all plugins to be deployed to the \c{PlugIns} subdirectory of the
236bundle contents, and all other non-binary files should generally be under the
237\c{Resources} subdirectory. The different parts of a QML module therefore need
238to be deployed to different locations within the app bundle.
239
240\section1 Example
241
242\include cmake-deploy-modified-variable-values.qdocinc
243
244\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR,
245 QT_DEPLOY_LIBEXEC_DIR, QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR,
246 QT_DEPLOY_TRANSLATIONS_DIR
247*/
248
249/*!
250\page cmake-variable-qt-deploy-translations-dir.html
251\ingroup cmake-variables-qtcore
252
253\title QT_DEPLOY_TRANSLATIONS_DIR
254\target cmake-variable-QT_DEPLOY_TRANSLATIONS_DIR
255
256\summary {Prefix-relative subdirectory for deploying Qt translations on some target platforms.}
257
258\include cmake-deploy-var-usage.qdocinc
259
260\cmakevariablesince 6.5
261
262Projects should use \c QT_DEPLOY_TRANSLATIONS_DIR in their deploy scripts to
263avoid hard-coding a particular directory under which to deploy translations.
264
265\c QT_DEPLOY_TRANSLATIONS_DIR defaults to the value \c{translations}. To change
266the value of \c QT_DEPLOY_TRANSLATIONS_DIR, set it in the project deployment
267script before \c QT_DEPLOY_SUPPORT is included.
268
269The \c QT_DEPLOY_TRANSLATIONS_DIR path is relative to \l{QT_DEPLOY_PREFIX}.
270
271This variable is not meaningful when deploying on macOS or Windows.
272
273\section1 Example
274
275\include cmake-deploy-modified-variable-values.qdocinc
276
277\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR,
278 QT_DEPLOY_LIBEXEC_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR
279*/
280
281/*!
282\page cmake-variable-qt-deploy-ignored-lib-dirs.html
283\ingroup cmake-variables-qtcore
284
285\title QT_DEPLOY_IGNORED_LIB_DIRS
286\target cmake-variable-QT_DEPLOY_IGNORED_LIB_DIRS
287
288\summary {Directories that are excluded from runtime dependencies search}
289
290\include cmake-deploy-var-usage.qdocinc
291
292\cmakevariablesince 6.5
293
294This variable contains a list of directories that are not taken into account
295when searching for runtime dependencies with \l{qt_deploy_runtime_dependencies}.
296
297Projects may alter this variable before calling
298\l{qt_deploy_runtime_dependencies} to control from which directory runtime
299dependencies are deployed.
300
301This variable is ignored if the \c{POST_EXCLUDE_REGEXES} option is specified in
302the \l{qt_deploy_runtime_dependencies} call.
303
304This variable is not meaningful when deploying on macOS or Windows.
305
306\sa qt_deploy_runtime_dependencies
307*/