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 模块，请参见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:> ）中的原始目标名称。

可能还需要安装与executable 相关的其他二进制文件的依赖关系。例如，项目提供的插件可能有进一步的依赖关系，但由于这些插件不会直接链接到可执行文件，因此qt_deploy_runtime_dependencies() 不会自动发现它们。ADDITIONAL_EXECUTABLES 、ADDITIONAL_LIBRARIES 和ADDITIONAL_MODULES 选项可用于指定其他二进制文件，这些二进制文件的依赖关系也应被部署（安装命名的二进制文件本身仍是项目的责任）。这些关键字的命名遵循 CMake 的约定，因此 Qt XML 插件应使用ADDITIONAL_MODULES 来指定。每个值都应是相对于基本安装位置的路径。这些值可以使用生成器表达式，与EXECUTABLE 选项相同。不支持指定未封装在生成器表达式（如$<TARGET_FILE_NAME:> ）中的原始目标名称。

在安装 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

如果executable 是 macOS 应用程序捆绑包，无论是否提供GENERATE_QT_CONF ，都会写入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()。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.