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_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...]
)描述
在安装应用程序时,可能需要同时安装其依赖的库和插件。当应用程序是 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:> 。
此外,可能还需要安装与executable 相关的其他二进制文件的依赖项。例如,项目提供的插件可能会有进一步的依赖项,但由于这些插件不会直接链接到可执行文件,因此qt_deploy_runtime_dependencies() 不会自动发现它们。 可以使用ADDITIONAL_EXECUTABLES 、ADDITIONAL_LIBRARIES 和ADDITIONAL_MODULES 选项来指定应一并部署其依赖项的其他二进制文件(安装这些指定二进制文件本身仍由项目负责)。 这些关键字的命名遵循 CMake 的约定,因此 Qt 插件应使用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应用程序包,则不会生成qt.conf 文件,此时GENERATE_QT_CONF 和..._DIR 这两个选项将被忽略。应用程序包的目录结构由Apple的要求决定,Qt会直接在这些标准位置查找库、插件和资源,而无需qt.conf 文件。
通过提供VERBOSE 选项,可以启用关于部署步骤的更详细的输出。或者,可以在首次调用find_package(Qt6) 之前在项目中设置QT_ENABLE_VERBOSE_DEPLOYMENT变量,以使部署输出默认显示详细信息。
qt_deploy_runtime_dependencies() 命令默认会覆盖现有文件(仍可能会发出一些警告)。使用NO_OVERWRITE 选项可防止覆盖现有文件。请注意,此选项目前仅影响 macOS 和 Windows 部署。
默认情况下,如果executable 是 macOS 应用程序包,则仅部署符合 Apple App Store 要求的 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` 时生效。
注意:当从 qt_generate_deploy_script() 的CONTENT 调用此命令时, 应将DEPLOY_TOOL_OPTIONS 的值包裹在单引号字符串中,以确保生成的部署脚本中保留空格。此外,每个包含空格的值(如代码签名标识)都应使用反斜杠转义的引号进行包裹。
在 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 的值生成。
控制 Qt 插件的部署
Qt 插件会自动部署到QT_DEPLOY_PLUGINS_DIR 中。
您可以通过NO_PLUGINS 参数禁用插件部署。
您可以使用INCLUDE_PLUGIN_TYPES 参数包含特定类型的所有插件。您可以使用EXCLUDE_PLUGIN_TYPES 参数排除特定类型的所有插件。这两个参数都接受插件类型,例如imageformats 。
您可以使用参数INCLUDE_PLUGINS 和EXCLUDE_PLUGINS 包含或排除特定的插件。这两个参数都接受插件名称,例如qjpeg 。
注意:插件 名称不可与插件目标混淆。例如,Qt6::QJpegPlugin 目标的插件名称是qjpeg 。
注意:参数 EXCLUDE_PLUGINS 、EXCLUDE_PLUGIN_TYPES 、INCLUDE_PLUGINS 和INCLUDE_PLUGIN_TYPES 仅在 Windows 和 Linux 系统上有效。
示例
以下示例演示了如何部署应用程序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以下示例展示了如何使用DEPLOY_TOOL_OPTIONS 参数向 macdeployqt 和 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
)")另请参阅 qt_generate_deploy_app_script()、qt_deploy_qt_conf()、qt_deploy_qml_imports() 以及QTP0007。
© 2026 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.