qt_deploy_runtime_dependencies

Déployer les plugins Qt, ainsi que les bibliothèques Qt et non-Qt requises par un exécutable.

La commande est définie dans le composant « Core » du paquet « Qt6 », qui peut être chargé comme suit :

find_package(Qt6 REQUIRED COMPONENTS Core)

Contrairement à la plupart des autres commandes CMake fournies par Qt, qt_deploy_runtime_dependencies() ne peut être appelée qu’à partir d’un script de déploiement. Elle ne peut pas être appelée directement par le projet pendant la phase de configuration.

Cette commande a été introduite dans Qt 6.3.

Syntaxe

qt_deploy_runtime_dependencies(
    EXECUTABLE executable
    [ADDITIONAL_EXECUTABLES files...]
    [ADDITIONAL_LIBRARIES files...]
    [ADDITIONAL_MODULES files...]
    [GENERATE_QT_CONF]
    [BIN_DIR bin_dir]
    [LIBEXEC_DIR libexec_dir]
    [LIB_DIR lib_dir]
    [PLUGINS_DIR plugins_dir]
    [QML_DIR qml_dir]
    [VERBOSE]
    [NO_OVERWRITE]
    [NO_APP_STORE_COMPLIANCE]
    [NO_PLUGINS]                                  # since Qt 6.10
    [EXCLUDE_PLUGIN_TYPES type...]                # since Qt 6.10
    [INCLUDE_PLUGIN_TYPES type...]                # since Qt 6.10
    [EXCLUDE_PLUGINS name...]                     # since Qt 6.10
    [INCLUDE_PLUGINS name...]                     # since Qt 6.10
    [NO_TRANSLATIONS]
    [NO_COMPILER_RUNTIME]
    [DEPLOY_TOOL_OPTIONS]
    [PRE_INCLUDE_REGEXES regexes...]
    [PRE_EXCLUDE_REGEXES regexes...]
    [POST_INCLUDE_REGEXES regexes...]
    [POST_EXCLUDE_REGEXES regexes...]
    [POST_INCLUDE_FILES files...]
    [POST_EXCLUDE_FILES files...]
)

Description

Lors de l’installation d’une application, il peut être souhaitable d’installer également les bibliothèques et les plugins dont elle dépend. Lorsque l’application est un bundle macOS ou un exécutable Windows, la commande ` qt_deploy_runtime_dependencies() ` peut être appelée depuis un script d’installation pour déployer ces dépendances. Elle installera les bibliothèques Qt non système ainsi qu’un ensemble approprié de plugins Qt.

Sous Linux, la commande déploiera des bibliothèques supplémentaires, au-delà de celles liées à Qt, qui sont incluses dans le projet. Cependant, lorsqu’elle est exécutée sur macOS ou Windows, la commande utilisera soit ` macdeployqt `, soit ` windeployqt`, qui ne déploieront que les bibliothèques spécifiques à Qt.

Cette commande ne prend en compte que les dépendances d'exécution pour lesquelles il existe des relations de liaison dans les binaires sous-jacents. Elle ne déploie pas les modules QML ; pour cela, voir qt_deploy_qml_imports().

Arguments

L’option EXECUTABLE doit être fournie.

L’argument executable doit correspondre au chemin d’accès au fichier exécutable dans le répertoire de compilation. Par exemple, ${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe, ou de manière plus dynamique, $<TARGET_FILE:MyApp>. La spécification de noms de cibles bruts non encapsulés dans une expression de générateur, tels que $<TARGET_FILE:>, n’est pas prise en charge.

Pour les bundles d’applications macOS, l’argument ` executable ` doit être un chemin vers le répertoire du bundle, relatif à l’emplacement d’installation de base. Par exemple, ` MyApp.app`, ou de manière plus dynamique, ` $<TARGET_FILE_NAME:MyApp>.app`. La spécification de noms de cibles bruts non encapsulés dans une expression génératrice, comme ` $<TARGET_FILE_NAME:> `, n’est pas prise en charge.

Il peut également être souhaitable d’installer les dépendances d’autres binaires liés à executable. Par exemple, les plugins fournis par le projet peuvent avoir d’autres dépendances, mais comme ces plugins ne seront pas liés directement à l’exécutable, qt_deploy_runtime_dependencies() ne les détectera pas automatiquement. Les options ADDITIONAL_EXECUTABLES, ADDITIONAL_LIBRARIES et ADDITIONAL_MODULES permettent de spécifier des binaires supplémentaires dont les dépendances doivent également être déployées (l’installation des binaires nommés reste toutefois à la charge du projet). La nomenclature de ces mots-clés suit les conventions de CMake ; ainsi, les plugins Qt seraient spécifiés à l’aide de ` ADDITIONAL_MODULES`. Chaque valeur doit être un chemin relatif à l’emplacement d’installation de base. Les valeurs peuvent utiliser des expressions de générateur, comme c’est le cas avec l’option ` EXECUTABLE `. La spécification de noms de cibles bruts non encapsulés dans une expression de générateur, tels que ` $<TARGET_FILE_NAME:> `, n’est pas prise en charge.

Lors de l’installation d’une application Windows, il est courant d’avoir besoin d’un fichier qt.conf lorsque l’on suit la structure de répertoires d’installation par défaut de CMake. Si l’option GENERATE_QT_CONF est fournie, un fichier qt.conf approprié sera créé dans le même répertoire que le fichier executable. Les chemins d’accès contenus dans ce fichier qt.conf seront basés sur les variables CMAKE_INSTALL_xxxDIR, dont les valeurs par défaut sont fournies par le module GNUInstallDirs de CMake.

Vous pouvez remplacer certaines de ces valeurs par défaut à l’aide des paramètres du tableau suivant, qui doivent tous être relatifs à l’emplacement d’installation de base.

Aucun fichier ` qt.conf ` n'est créé si ` executable ` est un bundle d'application macOS ; dans ce cas, les options ` GENERATE_QT_CONF ` et ` ..._DIR ` sont ignorées. La structure des répertoires d'un bundle d'application est dictée par les exigences d'Apple, et Qt trouve les bibliothèques, les plugins et les ressources à ces emplacements conventionnels sans avoir besoin d'un fichier ` qt.conf`.

Il est possible d’activer un affichage plus détaillé des étapes de déploiement en spécifiant l’option VERBOSE. Il est également possible de définir la variable QT_ENABLE_VERBOSE_DEPLOYMENT dans le projet avant le premier appel à find_package(Qt6) afin que l’affichage du déploiement soit détaillé par défaut.

La commande ` qt_deploy_runtime_dependencies() ` écrase les fichiers existants par défaut (certains avertissements peuvent toutefois s'afficher). Utilisez l'option ` NO_OVERWRITE ` pour empêcher l'écrasement des fichiers existants. Notez que cette option ne concerne actuellement que les déploiements sous macOS et Windows.

Par défaut, si executable est un bundle d’application macOS, seuls les plugins Qt et les bibliothèques Qt conformes aux exigences de l’App Store d’Apple sont déployés. L’option NO_APP_STORE_COMPLIANCE peut être spécifiée pour désactiver cette contrainte.

Sur les plateformes autres que macOS, les traductions Qt sont automatiquement déployées. Pour désactiver 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 empêcher 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 soit `macdeployqt`, soit `windeployqt`.

Sous Linux, le déploiement des dépendances d’exécution s’appuie sur la commande file(GET_RUNTIME_DEPENDENCIES) de CMake. Les options PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, POST_EXCLUDE_REGEXES, POST_INCLUDE_FILES et POST_EXCLUDE_FILES n’ont de sens que dans ce contexte et sont transmises telles quelles à file(GET_RUNTIME_DEPENDENCIES). Reportez-vous à la documentation de cette commande pour plus de détails.

Sous Linux, les dépendances d'exécution situées dans les répertoires de bibliothèques système ne sont pas déployées par défaut. Si POST_EXCLUDE_REGEXES est spécifié, cette exclusion automatique n'est pas appliquée.

La valeur par défaut de ` POST_EXCLUDE_REGEXES ` est calculée à partir de la valeur de ` QT_DEPLOY_IGNORED_LIB_DIRS`.

Contrôle du déploiement des plugins Qt

Les plugins Qt sont automatiquement déployés dans QT_DEPLOY_PLUGINS_DIR.

Vous pouvez désactiver le déploiement des plugins à l’aide de l’argument NO_PLUGINS.

Vous pouvez inclure tous les plugins d'un type spécifique à l'aide de l'argument ` INCLUDE_PLUGIN_TYPES `. Vous pouvez exclure tous les plugins d'un type spécifique à l'aide de l'argument ` EXCLUDE_PLUGIN_TYPES `. Ces deux arguments acceptent des types de plugins, par exemple ` imageformats`.

Vous pouvez inclure ou exclure des plugins spécifiques à l'aide des arguments INCLUDE_PLUGINS et EXCLUDE_PLUGINS. Ces deux arguments prennent en paramètre des noms de plugins, par exemple qjpeg.

Exemple

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

cmake_minimum_required(VERSION 3.16...3.22)
project(MyThings)

find_package(Qt6 REQUIRED COMPONENTS Core)
qt_standard_project_setup()

# Keep the QT_DEPLOY_* references below for the generated script to expand,
# see \l {QTP0008}.
qt_policy(SET QTP0008 NEW)

qt_add_executable(MyApp main.cpp)

set_target_properties(MyApp PROPERTIES
    WIN32_EXECUTABLE TRUE
    MACOSX_BUNDLE TRUE
)

# App bundles on macOS have an .app suffix
if(APPLE)
    set(executable_path "$<TARGET_FILE_NAME:MyApp>.app")
else()
    set(executable_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>")
endif()

# Helper app, not necessarily built as part of this project.
qt_add_executable(HelperApp helper.cpp)
set(helper_app_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:HelperApp>")

# Generate a deployment script to be executed at install time
qt_generate_deploy_script(
    TARGET MyApp
    OUTPUT_SCRIPT deploy_script
    CONTENT "
qt_deploy_runtime_dependencies(
    EXECUTABLE \"${executable_path}\"
    ADDITIONAL_EXECUTABLES \"${helper_app_path}\"
    GENERATE_QT_CONF
    VERBOSE
)")

# Omitting RUNTIME DESTINATION will install a non-bundle target to CMAKE_INSTALL_BINDIR,
# which coincides with the default value of QT_DEPLOY_BIN_DIR used above, './bin'.
# Installing macOS bundles always requires an explicit BUNDLE DESTINATION option.
install(TARGETS MyApp HelperApp    # Install to CMAKE_INSTALL_PREFIX/bin/MyApp.exe
                                   #                           and ./binHelperApp.exe
        BUNDLE  DESTINATION .      # Install to CMAKE_INSTALL_PREFIX/MyApp.app/Contents/MacOS/MyApp
)
install(SCRIPT ${deploy_script})    # Add its runtime dependencies

L'exemple suivant montre comment utiliser le paramètre ` DEPLOY_TOOL_OPTIONS ` pour transmettre différentes options à `macdeployqt` et `windeployqt`.

set(deploy_tool_options_arg "")
if(APPLE)
    # The CONTENT below is parsed when the generated script runs.
    # To preserve the code signing identity, it needs to be wrapped in escaped quotes.
    # In addition, all the options need to be wrapped into a single quoted string,
    # so that CMake doesn't replace each space with a semicolon in the generated text.
    set(deploy_tool_options_arg
        "-hardened-runtime \"-codesign=Developer ID Application: Joe Developer (1234567890)\""
    )
elseif(WIN32)
    set(deploy_tool_options_arg --no-compiler-runtime)
endif()

# Generate a deployment script to be executed at install time
qt_generate_deploy_script(
    TARGET MyApp
    OUTPUT_SCRIPT deploy_script
    CONTENT "
qt_deploy_runtime_dependencies(
    EXECUTABLE \"${executable_path}\"
    DEPLOY_TOOL_OPTIONS ${deploy_tool_options_arg}
    GENERATE_QT_CONF
    VERBOSE
)")