1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qt-generate-deploy-qml-app-script.html
\ingroup cmake-commands-qtqml
\title qt_generate_deploy_qml_app_script
\target qt6_generate_deploy_qml_app_script
\summary {Generate a deployment script for a QML application.}
\include cmake-find-package-qml.qdocinc
\cmakecommandsince 6.3
\include cmake-qml-qt-finalize-target-warning.qdocinc warning
\section1 Synopsis
\badcode
qt_generate_deploy_qml_app_script(
TARGET <target>
OUTPUT_SCRIPT <var>
[NO_UNSUPPORTED_PLATFORM_ERROR]
[NO_TRANSLATIONS]
[NO_COMPILER_RUNTIME]
[DEPLOY_TOOL_OPTIONS ...]
[DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM]
[MACOS_BUNDLE_POST_BUILD]
[PRE_INCLUDE_REGEXES regexes...]
[PRE_EXCLUDE_REGEXES regexes...]
[POST_INCLUDE_REGEXES regexes...]
[POST_EXCLUDE_REGEXES regexes...]
[POST_INCLUDE_FILES files...]
[POST_EXCLUDE_FILES files...]
)
\endcode
\versionlessCMakeCommandsNote qt6_generate_deploy_qml_app_script()
\section1 Description
Installing an executable target that is also a QML module requires deploying
a number of things in addition to the target itself. Qt libraries and other
libraries from the project, Qt plugins, and the runtime parts of all QML modules
the application uses may all need to be installed too. The installed layout
is also going to be different for macOS app bundles compared to other platforms.
The \c{qt_generate_deploy_qml_app_script()} is a convenience command intended
to simplify that process, similar to what
\l{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} does for
non-QML applications.
The command expects the application to follow Qt's recommended install
directory structure fairly closely. That structure is based on CMake's default
install layout, as determined by \l{GNUInstallDirs} (except for macOS app
bundles, which follow Apple's requirements instead). QML modules are installed
to the appropriate location for the platform. For macOS bundles, each QML
module's \c{qmldir} file is installed under the appropriate subdirectory below
\c{Resources/qml} and the module's plugin (if present) is installed under
\c{PlugIns}. The app bundle is assumed to be installed directly to the base
installation location (see the \l{Example} further below). For all other platforms,
both the \c{qmldir} and the module's plugin are installed under the appropriate
subdirectory below \c{qml}, which itself is relative to the base installation
location.
\c{qt_generate_deploy_qml_app_script()} generates a script whose name will be
stored in the variable named by the \c{OUTPUT_SCRIPT} option. That script
is only written at CMake generate-time. It is intended to be used with the
\l{install(SCRIPT)} command, which should come after the application's target
has been installed using \l{install(TARGETS)}.
The deployment script will call
\l{qt6_deploy_qml_imports}{qt_deploy_qml_imports()} with a suitable set of
options for the standard install layout. For macOS app bundles and Windows
targets, it will then also call
\l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}, again
with suitable options for the standard install layout.
Calling \c{qt_generate_deploy_qml_app_script()} for a platform that is not
supported by \c{qt_deploy_runtime_dependencies} will result in a fatal error,
unless the \c{NO_UNSUPPORTED_PLATFORM_ERROR} option is given. When the option
is given and the project is built for an unsupported platform, neither QML modules
nor regular runtime dependencies will be installed.
To ensure that the QML modules are still installed, specify both the
\c{NO_UNSUPPORTED_PLATFORM_ERROR} and
\c{DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM} options.
The latter option will ensure that QML modules built as part of the project
are still installed.
The \c{MACOS_BUNDLE_POST_BUILD} option enables an extra step when \c{target}
is a macOS app bundle. A post-build rule will be created which uses the
deployment script to deploy enough of the imported QML modules to allow the
application to run directly from the build directory (essentially just the
\c{qmldir} files and symlinks to plugins). This is usually desirable to support
development of the application. \c{MACOS_BUNDLE_POST_BUILD} is ignored for all
other platforms.
On platforms other than macOS, Qt translations are automatically deployed. To
inhibit this behavior, specify \c{NO_TRANSLATIONS}. Use
\l{qt_deploy_translations}{qt_deploy_translations()} to deploy translations in a
customized way.
For Windows desktop applications, the required runtime files for the compiler
are also installed by default. To prevent this, specify \c{NO_COMPILER_RUNTIME}.
Since Qt 6.7, you can use \c{DEPLOY_TOOL_OPTIONS} to pass additional options to
the underlying deployment tool. This only has an effect if the underlying
deployment tool is either macdeployqt or windeployqt.
The options \c{PRE_INCLUDE_REGEXES}, \c{PRE_EXCLUDE_REGEXES},
\c{POST_INCLUDE_REGEXES}, \c{POST_EXCLUDE_REGEXES}, \c{POST_INCLUDE_FILES}, and
\c{POST_EXCLUDE_FILES} can be specified to control the deployment of runtime
dependencies. These options do not apply to all platforms and are forwarded
unmodified to
\l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}.
For deploying a non-QML application, use
\l{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()}
instead. It is an error to call both \c{qt_generate_deploy_qml_app_script()}
and \l{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} for the
same target.
\sa {qt6_standard_project_setup}{qt_standard_project_setup()},
{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()}
\section1 Example
The following example shows how to deploy a QtQuick app.
\badcode
cmake_minimum_required(VERSION 3.16...3.22)
project(MyThings)
find_package(Qt6 6.3 REQUIRED COMPONENTS Core Qml)
qt_standard_project_setup()
qt_add_executable(MyApp main.cpp)
qt_add_qml_module(MyApp
URI Application
VERSION 1.0
QML_FILES main.qml MyThing.qml
)
install(TARGETS MyApp
BUNDLE DESTINATION .
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)
qt_generate_deploy_qml_app_script(
TARGET MyApp
OUTPUT_SCRIPT deploy_script
MACOS_BUNDLE_POST_BUILD
NO_UNSUPPORTED_PLATFORM_ERROR
DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM
)
install(SCRIPT ${deploy_script})
\endcode
The following example shows how to pass additional options to the underlying
deployment tool.
\badcode
set(deploy_tool_options_arg "")
if(APPLE)
set(deploy_tool_options_arg --hardened-runtime)
elseif(WIN32)
set(deploy_tool_options_arg --no-compiler-runtime)
endif()
qt_generate_deploy_qml_app_script(
...
DEPLOY_TOOL_OPTIONS ${deploy_tool_options_arg}
)
install(SCRIPT ${deploy_script})
\endcode
*/
|
