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