- Qt 6.10
- Qt Qml
- qt_generate_deploy_qml_app_script
- Qt 6.10.3 Reference Documentation

# 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.

Warning: If you are using a CMake version lower than 3.19, make sure that you pass the `MANUAL_FINALIZATION` option to qt6_add_executable(), and then call qt6_finalize_target() before calling this function.

## Synopsis

     qt_generate_deploy_qml_app_script(
         TARGET <target>
         OUTPUT_SCRIPT <var>
         [NO_UNSUPPORTED_PLATFORM_ERROR]
         [NO_TRANSLATIONS]
         [NO_COMPILER_RUNTIME]
         [NO_PLUGINS]                                  # since Qt 6.10
         [EXCLUDE_PLUGIN_TYPES type_or_target...]      # since Qt 6.10
         [INCLUDE_PLUGIN_TYPES type_or_target...]      # since Qt 6.10
         [EXCLUDE_PLUGINS name...]                     # since Qt 6.10
         [INCLUDE_PLUGINS name...]                     # since Qt 6.10
         [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().

The options `EXCLUDE_PLUGINS`, `EXCLUDE_PLUGIN_TYPES`, `INCLUDE_PLUGINS`, and `INCLUDE_PLUGIN_TYPES` are used to select Qt plugins. See qt_deploy_runtime_dependencies() for their documentation.

You can turn off plugin deployment altogether with the `NO_PLUGINS` option.

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

See also qt_standard_project_setup() and qt_generate_deploy_app_script().