qt_deploy_qml_imports

Deploy the runtime components of QML modules needed by an executable.

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

find_package(Qt6 REQUIRED COMPONENTS Qml)

Unlike most other CMake commands provided by Qt, qt_deploy_qml_imports() can only be called from a deployment script. It cannot be called directly by the project.

Synopsis

qt_deploy_qml_imports(
    TARGET target
    [QML_DIR qml_dir]
    [PLUGINS_FOUND var_name]
    [NO_QT_IMPORTS]
)

Description

When installing an application that uses QML, it may be non-trivial to work out which QML modules and which parts of those QML modules need to also be installed. Because QML plugins are not linked directly to an application's executable, qt_deploy_runtime_dependencies() won't find these QML modules. The qt_deploy_qml_imports() command provides the necessary logic which complements qt_deploy_runtime_dependencies() and deploys the runtime parts of all QML modules imported by the application.

The TARGET option is mandatory and should specify a target that is an executable (on macOS, it should be an app bundle) and also a QML module. All QML sources that were added to the target via qt_add_qml_module() or qt_target_qml_sources() will be recursively scanned for QML imports. The NO_IMPORT_SCAN option must not have been given to qt_add_qml_module(). The qmldir files and plugins from the imported QML modules will be deployed. The NO_QT_IMPORTS option can be given to skip deploying any QML modules provided by Qt.

By default, the runtime parts of imported QML modules will be deployed to the Resources/qml directory for a macOS app bundle target, and to the qml directory under the base installation location for other platforms. For the non-macOS case, the QML_DIR option can be used to override this default choice.

The command will store a list of all QML plugins it deploys in the variable named by the PLUGINS_FOUND option, if given. This is often passed as the ADDITIONAL_MODULES argument in a subsequent call to qt_deploy_runtime_dependencies().

Example

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
)

# The following script must only be executed at install time
set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_MyApp.cmake")

file(GENERATE OUTPUT ${deploy_script} CONTENTS "
include(\"${QT_DEPLOY_SUPPORT}\")
qt_deploy_qml_imports(
    # Deploy QML modules used by MyApp
    TARGET MyApp

    # The found QML plugins are stored in the plugins_found variable
    PLUGINS_FOUND plugins_found

    # The QML modules will be deployed into a custom directory
    QML_DIR \"myqmldir\"

    # Qt QML modules will be skipped, only project-created QML modules will be deployed
    NO_QT_IMPORTS
)
# Deploy application runtime dependencies and runtime dependencies
# of the found QML module plugins.
qt_deploy_runtime_dependencies(
    EXECUTABLE \${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>
    ADDITIONAL_MODULES \${plugins_found}
)
")

install(TARGETS MyApp)
install(SCRIPT ${deploy_script})