qt_generate_deploy_qml_app_script

Generate a deployment script for a QML application.

The command is defined in the Qml component of the Qt6 package, which can be loaded like so:

 find_package(Qt6 REQUIRED COMPONENTS Qml)

This command was introduced in Qt 6.3.

Synopsis

 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...]
 )

If versionless commands are disabled, use qt6_generate_deploy_qml_app_script() instead. It supports the same set of arguments as this command.

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 qt_generate_deploy_qml_app_script() is a convenience command intended to simplify that process, similar to what 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 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 qmldir file is installed under the appropriate subdirectory below Resources/qml and the module's plugin (if present) is installed under PlugIns. The app bundle is assumed to be installed directly to the base installation location (see the Example further below). For all other platforms, both the qmldir and the module's plugin are installed under the appropriate subdirectory below qml, which itself is relative to the base installation location.

qt_generate_deploy_qml_app_script() generates a script whose name will be stored in the variable named by the OUTPUT_SCRIPT option. That script is only written at CMake generate-time. It is intended to be used with the install(SCRIPT) command, which should come after the application's target has been installed using install(TARGETS).

The deployment script will call 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 qt_deploy_runtime_dependencies(), again with suitable options for the standard install layout.

Calling qt_generate_deploy_qml_app_script() for a platform that is not supported by qt_deploy_runtime_dependencies will result in a fatal error, unless the 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 NO_UNSUPPORTED_PLATFORM_ERROR and 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 MACOS_BUNDLE_POST_BUILD option enables an extra step when 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 qmldir files and symlinks to plugins). This is usually desirable to support development of the application. 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 NO_TRANSLATIONS. Use 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 NO_COMPILER_RUNTIME.

Since Qt 6.7, you can use 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 PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, POST_EXCLUDE_REGEXES, POST_INCLUDE_FILES, and 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 qt_deploy_runtime_dependencies().

For deploying a non-QML application, use qt_generate_deploy_app_script() instead. It is an error to call both qt_generate_deploy_qml_app_script() and qt_generate_deploy_app_script() for the same target.

Example

The following example shows how to deploy a QtQuick app.

 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})

The following example shows how to pass additional options to the underlying deployment tool.

 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})