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
|
/****************************************************************************
**
** Copyright (C) 2021 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 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
\preliminarycmakecommand
\include cmake-qml-qt-finalize-target-warning.cmake
\section1 Synopsis
\badcode
qt_generate_deploy_qml_app_script(
TARGET target
FILENAME_VARIABLE var_name
[NO_UNSUPPORTED_PLATFORM_ERROR]
[DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM]
[MACOS_BUNDLE_POST_BUILD]
)
\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{FILENAME_VARIABLE} 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{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{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.
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
\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
FILENAME_VARIABLE deploy_script
MACOS_BUNDLE_POST_BUILD
NO_UNSUPPORTED_PLATFORM_ERROR
DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM
)
install(SCRIPT ${deploy_script})
\endcode
*/
|
