qt_generate_deploy_qml_app_script

Génère un script de déploiement pour une application QML.

La commande est définie dans le composant Qml du paquetage Qt6, qui peut être chargé comme suit :

find_package(Qt6 REQUIRED COMPONENTS Qml)

Cette commande a été introduite dans Qt 6.3.

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

Si les commandes sans version sont désactivées, utilisez qt6_generate_deploy_qml_app_script() à la place. Elle supporte le même ensemble d'arguments que cette commande.

Description de la commande

L'installation d'une cible exécutable qui est également un module QML nécessite le déploiement d'un certain nombre de choses en plus de la cible elle-même. Les bibliothèques Qt et les autres bibliothèques du projet, les plugins Qt et les parties runtime de tous les modules QML utilisés par l'application peuvent tous avoir besoin d'être installés également. La disposition installée sera également différente pour les paquets d'applications macOS par rapport à d'autres plates-formes. La commande qt_generate_deploy_qml_app_script() est une commande de commodité destinée à simplifier ce processus, similaire à ce que qt_generate_deploy_app_script() fait pour les applications non-QML.

La commande s'attend à ce que l'application suive de près la structure du répertoire d'installation recommandée par Qt. Cette structure est basée sur la structure d'installation par défaut de CMake, telle que déterminée par GNUInstallDirs (sauf pour les paquets d'applications macOS, qui suivent plutôt les exigences d'Apple). Les modules QML sont installés à l'emplacement approprié pour la plateforme. Pour les bundles macOS, le fichier qmldir de chaque module QML est installé dans le sous-répertoire approprié sous Resources/qml et le plugin du module (s'il est présent) est installé sous PlugIns. Le bundle d'applications est supposé être installé directement à l'emplacement de l'installation de base (voir l'exemple ci-dessous). Pour toutes les autres plateformes, qmldir et le module complémentaire sont installés dans le sous-répertoire approprié sous qml, qui est lui-même relatif à l'emplacement d'installation de base.

qt_generate_deploy_qml_app_script() génère un script dont le nom sera stocké dans la variable nommée par l'option OUTPUT_SCRIPT. Ce script n'est écrit qu'au moment de la génération de CMake. Il est destiné à être utilisé avec la commande install(SCRIPT), qui doit venir après que la cible de l'application ait été installée avec install(TARGETS).

Le script de déploiement appellera qt_deploy_qml_imports() avec un ensemble approprié d'options pour l'installation standard. Pour les bundles d'applications macOS et les cibles Windows, il appellera également qt_deploy_runtime_dependencies(), toujours avec les options appropriées pour l'installation standard.

Appeler qt_generate_deploy_qml_app_script() pour une plateforme qui n'est pas supportée par qt_deploy_runtime_dependencies résultera en une erreur fatale, à moins que l'option NO_UNSUPPORTED_PLATFORM_ERROR ne soit donnée. Lorsque l'option est donnée et que le projet est construit pour une plate-forme non prise en charge, ni les modules QML ni les dépendances d'exécution normales ne seront installés. Pour s'assurer que les modules QML sont toujours installés, spécifiez les options NO_UNSUPPORTED_PLATFORM_ERROR et DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM. Cette dernière option garantit que les modules QML construits dans le cadre du projet sont toujours installés.

L'option MACOS_BUNDLE_POST_BUILD permet une étape supplémentaire lorsque target est un bundle d'applications macOS. Une règle post-construction sera créée qui utilise le script de déploiement pour déployer suffisamment de modules QML importés pour permettre à l'application de fonctionner directement à partir du répertoire de construction (essentiellement juste les fichiers qmldir et les liens symboliques vers les plugins). Ceci est généralement souhaitable pour soutenir le développement de l'application. MACOS_BUNDLE_POST_BUILD est ignoré pour toutes les autres plateformes.

Sur les plateformes autres que macOS, les traductions de Qt sont automatiquement déployées. Pour inhiber ce comportement, spécifiez NO_TRANSLATIONS. Utilisez qt_deploy_translations() pour déployer les traductions de manière personnalisée.

Pour les applications de bureau Windows, les fichiers d'exécution requis pour le compilateur sont également installés par défaut. Pour éviter cela, spécifiez NO_COMPILER_RUNTIME.

Depuis Qt 6.7, vous pouvez utiliser DEPLOY_TOOL_OPTIONS pour transmettre des options supplémentaires à l'outil de déploiement sous-jacent. Cela n'a d'effet que si l'outil de déploiement sous-jacent est macdeployqt ou windeployqt.

Les options PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, POST_EXCLUDE_REGEXES, POST_INCLUDE_FILES, et POST_EXCLUDE_FILES peuvent être spécifiées pour contrôler le déploiement des dépendances d'exécution. Ces options ne s'appliquent pas à toutes les plateformes et sont transmises sans modification à qt_deploy_runtime_dependencies().

Les options EXCLUDE_PLUGINS, EXCLUDE_PLUGIN_TYPES, INCLUDE_PLUGINS, et INCLUDE_PLUGIN_TYPES sont utilisées pour sélectionner les plugins Qt. Voir qt_deploy_runtime_dependencies() pour leur documentation.

Vous pouvez désactiver le déploiement des plugins avec l'option NO_PLUGINS.

Pour déployer une application non-QML, utilisez qt_generate_deploy_app_script() à la place. C'est une erreur d'appeler à la fois qt_generate_deploy_qml_app_script() et qt_generate_deploy_app_script() pour la même cible.

Exemple de déploiement d'une application

L'exemple suivant montre comment déployer une application Qt Quick.

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

L'exemple suivant montre comment passer des options supplémentaires à l'outil de déploiement sous-jacent.

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