qt_deploy_runtime_dependencies

Déploie les plugins Qt, les bibliothèques Qt et non-Qt nécessaires à un exécutable.

La commande est définie dans le composant Core du paquetage Qt6, qui peut être chargé de cette manière :

find_package(Qt6 REQUIRED COMPONENTS Core)

Contrairement à la plupart des autres commandes CMake fournies par Qt XML, qt_deploy_runtime_dependencies() ne peut être appelé 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.

Synopsis

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 de la commande

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, qt_deploy_runtime_dependencies() peut être appelé à partir d'un script d'installation pour déployer ces dépendances. Il installera les bibliothèques Qt hors système ainsi qu'un ensemble approprié de plugins Qt.

Sous Linux, la commande déploiera des bibliothèques supplémentaires, en plus 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 des relations de liaison existent dans les binaires sous-jacents. Elle ne déploie pas les modules QML, voir qt_deploy_qml_imports() pour cela.

Arguments

L'option EXECUTABLE doit être fournie.

L'argument executable doit être le chemin vers le fichier exécutable dans le répertoire de construction. Par exemple, ${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe, ou plus dynamiquement $<TARGET_FILE:MyApp>. La spécification de noms de cibles bruts non enveloppés dans une expression de générateur comme $<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 de l'installation de base. Par exemple MyApp.app, ou plus dynamiquement $<TARGET_FILE_NAME:MyApp>.app. La spécification de noms de cibles bruts non enveloppés dans une expression de générateur comme $<TARGET_FILE_NAME:> n'est pas prise en charge.

Il peut également être souhaitable d'installer des dépendances pour d'autres binaires liés au projet 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écouvrira pas automatiquement. Les options ADDITIONAL_EXECUTABLES, ADDITIONAL_LIBRARIES, et ADDITIONAL_MODULES peuvent être utilisées pour spécifier des binaires supplémentaires dont les dépendances doivent également être déployées (l'installation des binaires nommés eux-mêmes reste de la responsabilité du projet). Le nom de ces mots-clés suit les conventions de CMake, ainsi les plugins Qt seraient spécifiés en utilisant ADDITIONAL_MODULES. Chaque valeur doit être un chemin relatif à l'emplacement de l'installation de base. Les valeurs peuvent utiliser des expressions de générateur, comme avec l'option EXECUTABLE. La spécification de noms de cibles bruts non enveloppés dans une expression de générateur comme $<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 si l'on suit la structure du répertoire d'installation par défaut de CMake. Si l'option GENERATE_QT_CONF est donnée, un fichier qt.conf approprié sera écrit dans le même répertoire que le fichier executable. Les chemins 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 modifier certaines de ces valeurs par défaut à l'aide des paramètres du tableau suivant, qui doivent tous être relatifs à l'emplacement de l'installation de base.

Un fichier qt.conf est toujours écrit si executable est un bundle d'application macOS, que GENERATE_QT_CONF soit fourni ou non. Les options de ..._DIR sont également ignorées dans ce cas, puisque la disposition des répertoires d'un bundle d'applications est dictée par les exigences d'Apple.

Des informations plus détaillées sur les étapes du déploiement peuvent être activées en fournissant l'option VERBOSE. Alternativement, la variable QT_ENABLE_VERBOSE_DEPLOYMENT peut être définie dans le projet avant le premier appel à find_package(Qt6) pour que la sortie du déploiement soit verbeuse par défaut.

La commande qt_deploy_runtime_dependencies() écrase les fichiers existants par défaut (certains avertissements peuvent encore être émis). Utilisez l'option NO_OVERWRITE pour empêcher l'écrasement des fichiers existants. Notez que cette option n'affecte actuellement que les déploiements sous macOS et Windows.

Par défaut, si executable est un bundle d'applications macOS, seuls les plugins et bibliothèques Qt conformes aux exigences de l'app store d'Apple sont déployés. L'option NO_APP_STORE_COMPLIANCE peut être utilisée pour désactiver cette contrainte.

Sur les plateformes autres que macOS, les traductions 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.

Sous Linux, le déploiement des dépendances d'exécution est basé 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). Voir la documentation de cette commande pour plus de détails.

Sous Linux, les dépendances d'exécution situées dans les répertoires des 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 effectuée.

La valeur par défaut de POST_EXCLUDE_REGEXES est construite à 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 avec l'argument NO_PLUGINS.

Vous pouvez inclure tous les plugins d'un type spécifique avec l'argument INCLUDE_PLUGIN_TYPES. Vous pouvez exclure tous les plugins d'un type spécifique avec l'argument EXCLUDE_PLUGIN_TYPES. Les deux arguments prennent en compte les types de plugins, par exemple imageformats.

Vous pouvez inclure ou exclure des plugins spécifiques avec les arguments INCLUDE_PLUGINS et EXCLUDE_PLUGINS. Ces deux arguments prennent en compte les noms des plugins, par exemple qjpeg.

Exemple de déploiement

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

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 passer différentes options à macdeployqt et windeployqt.

set(deploy_tool_options_arg "")
if(APPLE)
    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
)")