qt_deploy_runtime_dependencies

部署 Qt 插件，以及可执行程序所需的 Qt 及非 Qt 库。

此命令在 Qt6 软件包的 Core 组件中定义，加载方式如下

find_package(Qt6 REQUIRED COMPONENTS Core)

与 Qt 提供的大多数其他 CMake 命令不同，qt_deploy_runtime_dependencies() 只能从部署脚本中调用。它不能在配置阶段直接由项目调用。

此命令是在 Qt 6.3 中引入的。

注意：通常不需要直接调用此命令。它由其他高级命令内部使用，但希望实现更定制化部署逻辑的项目可能发现它很有用。

概述

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

描述

安装应用程序时，可能还需要安装它所依赖的库和插件。当应用程序是 macOS 应用程序包或 Windows 可执行文件时，可以从安装时脚本调用 qt_deploy_runtime_dependencies() 来部署这些依赖项。它将安装非系统 Qt 库以及适当的 Qt 插件集。

在 Linux 上，该命令将部署与项目一起包含的额外库，而不仅限于与 Qt 相关的库。然而，在 macOS 或 Windows 上执行时，该命令将使用 macdeployqt 或 windeployqt，这只会部署特定于 Qt 的库。

此命令仅考虑与底层二进制文件中存在的链接关系相关的运行时依赖项。它不会部署 QML 模块，有关 QML 模块的信息，请参阅 qt_deploy_qml_imports()。

参数

必须提供 EXECUTABLE 选项。

executable 参数应是指向构建目录中可执行文件的路径。例如，${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe，或更动态地 $<TARGET_FILE:MyApp>。不支持使用未包裹在生成器表达式（如 <TARGET_FILE>）中的原始目标名称。

对于 macOS 应用程序包，executable 参数应是指向基础安装位置的相对路径的应用程序包目录。例如 MyApp.app，或更动态地 $<TARGET_FILE_NAME:MyApp>.app。不支持使用未包裹在生成器表达式（如 <TARGET_FILE_NAME>）中的原始目标名称。

可能还需要安装与其他可执行文件相关的依赖项。例如，项目提供的插件可能还有其他依赖项，但由于这些插件不会直接链接到可执行文件，qt_deploy_runtime_dependencies() 不会自动检测到它们。《ADDITIONAL_EXECUTABLES》、《ADDITIONAL_LIBRARIES》和《ADDITIONAL_MODULES》选项可用于指定依赖项也应部署的附加二进制文件（安装命名二进制文件本身仍然是项目的责任）。这些关键字的命名遵循CMake的约定，因此Qt插件将使用《ADDITIONAL_MODULES》来指定。每个值应相对于基本安装位置作为路径。这些值可以使用生成表达式，就像使用《EXECUTABLE》选项一样。不支持使用生成表达式包围的目标名称，如《》，而非包围。

在安装Windows应用程序时，遵循CMake的默认安装目录结构通常需要qt.conf 文件。如果指定了《GENERATE_QT_CONF》选项，则适当的《qt.conf》文件将被写入与《executable》相同的目录。该《qt.conf》文件中的路径将基于《CMAKE_INSTALL_xxxDIR》变量，其默认值由CMake的《GNUInstallDirs》模块提供。

您可以使用以下表格中的参数覆盖一些默认值，所有这些都与基本安装位置相关。

参数	影响变量	说明
`BIN_DIR`	`QT_DEPLOY_BIN_DIR`
`LIBEXEC_DIR`	`QT_DEPLOY_LIBEXEC_DIR`	自Qt 6.7以来
`LIB_DIR`	`QT_DEPLOY_LIB_DIR`
`PLUGINS_DIR`	`QT_DEPLOY_PLUGINS_DIR`
`QML_DIR`	`QT_DEPLOY_QML_DIR`

qt.conf 文件在以下情况下始终写入：executable 是macOS应用程序包，无论是否提供《GENERATE_QT_CONF》。在这种情况下，《..._DIR》选项也被忽略，因为应用程序包的目录布局由Apple的要求决定。

通过提供《VERBOSE》选项，可以启用有关部署步骤的更详细输出。或者，可以在第一次调用 find_package(Qt6) 之前在项目中设置《QT_ENABLE_VERBOSE_DEPLOYMENT》变量，以使部署输出默认情况下是详细的。

默认情况下，qt_deploy_runtime_dependencies() 命令会覆盖现有文件（可能仍会发出一些警告）。使用《NO_OVERWRITE》选项防止覆盖现有文件。注意，此选项目前仅影响macOS和Windows部署。

默认情况下，如果《executable》是macOS应用程序包，则仅部署符合Apple应用商店要求的Qt插件和Qt库。可以通过提供《NO_APP_STORE_COMPLIANCE》选项来禁用此约束。

在macOS以外的平台上，Qt翻译将自动部署。要抑制此行为，指定《NO_TRANSLATIONS》。使用qt_deploy_translations()以自定义方式部署翻译。

对于Windows桌面应用程序，默认情况下还会安装编译器所需的运行时文件。为了防止这种情况，指定《NO_COMPILER_RUNTIME》。

自Qt 6.7以来，您可以使用《DEPLOY_TOOL_OPTIONS》将额外的选项传递给底层部署工具。此操作仅在底层部署工具是macdeployqt或windeployqt时才有效。

在 Linux 上，部署运行时依赖是基于 CMake 的 file(GET_RUNTIME_DEPENDENCIES) 命令。选项 PRE_INCLUDE_REGEXES、PRE_EXCLUDE_REGEXES、POST_INCLUDE_REGEXES、POST_EXCLUDE_REGEXES、POST_INCLUDE_FILES 和 POST_EXCLUDE_FILES 仅在此上下文中才有意义，并且无变更地转发到 file(GET_RUNTIME_DEPENDENCIES)。请参阅该命令的文档以获取详细信息。

在 Linux 上，默认情况下不会部署位于系统库目录中的运行时依赖。如果指定了 POST_EXCLUDE_REGEXES，则不会执行此自动排除。

POST_EXCLUDE_REGEXES 的默认值是从 QT_DEPLOY_IGNORED_LIB_DIRS 的值构建的。

示例

以下示例展示了如何部署应用程序 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

以下示例展示了如何使用 DEPLOY_TOOL_OPTIONS 参数将不同的选项传递给 macdeployqt 和 windeployqt。

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

# 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
)")

另请参阅 qt_generate_deploy_app_script()、qt_deploy_qt_conf() 和 qt_deploy_qml_imports()。