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