qt_generate_deploy_qml_app_script
为 QML 应用程序生成部署脚本。
该命令定义在Qt6 包的Qml 组件中，可按以下方式加载：
find_package(Qt6 REQUIRED COMPONENTS Qml)该命令在 Qt 6.3 中引入。
警告：如果您 使用的 CMake 版本低于 3.19，请确保在调用此函数之前，先向qt_add_executable() 传递MANUAL_FINALIZATION 选项，然后调用qt_finalize_target()。
语法
qt_generate_deploy_qml_app_script(
TARGET <target>
OUTPUT_SCRIPT <var>
[NO_UNSUPPORTED_PLATFORM_ERROR]
[NO_TRANSLATIONS]
[NO_COMPILER_RUNTIME]
[NO_PLUGINS] # since Qt 6.10
[EXCLUDE_PLUGIN_TYPES type_or_target...] # since Qt 6.10
[INCLUDE_PLUGIN_TYPES type_or_target...] # since Qt 6.10
[EXCLUDE_PLUGINS name...] # since Qt 6.10
[INCLUDE_PLUGINS name...] # since Qt 6.10
[DEPLOY_TOOL_OPTIONS ...]
[DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM]
[PRE_INCLUDE_REGEXES regexes...]
[PRE_EXCLUDE_REGEXES regexes...]
[POST_INCLUDE_REGEXES regexes...]
[POST_EXCLUDE_REGEXES regexes...]
[POST_INCLUDE_FILES files...]
[POST_EXCLUDE_FILES files...]
)如果禁用了无版本号的命令，请改用qt6_generate_deploy_qml_app_script() 。它支持与本命令相同的参数集。
说明
安装一个同时作为 QML 模块的可执行目标时，除了目标本身之外，还需要部署多项内容。Qt 库和项目中的其他库、Qt 插件，以及应用程序所用所有 QML 模块的运行时组件，可能都需要一并安装。 此外，macOS 应用程序包的安装布局与其他平台也存在差异。qt_generate_deploy_qml_app_script() 是一个便捷命令，旨在简化该过程，类似于qt_generate_deploy_app_script()针对非 QML 应用程序所做的工作。
该命令要求应用程序尽可能严格遵循 Qt 推荐的安装目录结构。该结构基于 CMake 的默认安装布局，由GNUInstallDirs确定（macOS 应用程序包除外，其遵循 Apple 的要求）。Qml 模块将安装到该平台对应的适当位置。 对于 macOS 应用程序包，每个 QML 模块的 `qmldir ` 文件将安装在 `Resources/qml ` 下的相应子目录中，而该模块的插件（如有）将安装在 `PlugIns` 下。假设应用程序包直接安装到基础安装位置（参见下文的示例）。 对于所有其他平台，qmldir 和模块的插件都会安装在qml 下的相应子目录中，该路径相对于基础安装位置。
qt_generate_deploy_qml_app_script() 会生成一个脚本，其名称将存储在由OUTPUT_SCRIPT 选项指定的变量中。该脚本仅在 CMake 生成时写入。它旨在与install(SCRIPT)命令配合使用，该命令应在通过install(TARGETS) 安装应用程序目标之后执行。
部署脚本将调用qt_deploy_qml_imports()，并为标准安装布局提供一组合适的选项。对于 macOS 应用程序包和 Windows 目标，它随后还将调用qt_deploy_runtime_dependencies()，同样为标准安装布局提供合适的选项。
若在qt_deploy_runtime_dependencies 不支持的平台上调用qt_generate_deploy_qml_app_script() ，将导致致命错误，除非指定了NO_UNSUPPORTED_PLATFORM_ERROR 选项。当指定该选项且项目是为不支持的平台构建时，既不会安装QML模块，也不会安装常规运行时依赖项。若要确保QML模块仍被安装，请同时指定NO_UNSUPPORTED_PLATFORM_ERROR 和DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM 选项。 后者将确保作为项目组成部分构建的 QML 模块仍会被安装。
在 macOS 以外的平台上，Qt 翻译文件会自动部署。若要禁止此行为，请指定NO_TRANSLATIONS 。使用qt_deploy_translations()以自定义方式部署翻译文件。
对于 Windows 桌面应用程序，编译器所需的运行时文件也会默认安装。若要阻止此行为，请指定NO_COMPILER_RUNTIME 。
从 Qt 6.7 开始，您可以使用 `DEPLOY_TOOL_OPTIONS ` 向底层部署工具传递额外选项。此设置仅在底层部署工具为 `macdeployqt` 或 `windeployqt` 时生效。
注意： 包含空格的值 （如代码签名标识）只有在将QTP0007设置为NEW 时，才会原样传递给部署工具。若采用OLD 行为，此类值将不加引号写入生成的脚本，并在空格处被拆分——此前项目通常通过添加额外一层引号来解决此问题。 将策略设置为“NEW ”时，请移除该额外的引号。
注意：无版本的 ` qt_generate_deploy_qml_app_script() ` 会根据`QTP0008` 的值，通过函数或宏转发其参数。在 `OLD ` 行为下，包含反斜杠或 `${var} ` 引用的值会在宏展开时被求值，因此类似 `foo\\.dylib ` 的正则表达式会丢失一层转义。这会影响 `DEPLOY_TOOL_OPTIONS ` 以及正则表达式和文件列表参数。 直接调用qt6_generate_deploy_qml_app_script() 可避免此问题。
可以指定选项PRE_INCLUDE_REGEXES 、PRE_EXCLUDE_REGEXES 、POST_INCLUDE_REGEXES 、POST_EXCLUDE_REGEXES 、POST_INCLUDE_FILES 和POST_EXCLUDE_FILES 来控制运行时依赖项的部署。这些选项并不适用于所有平台，且会未经修改地转发给qt_deploy_runtime_dependencies()。
选项EXCLUDE_PLUGINS 、EXCLUDE_PLUGIN_TYPES 、INCLUDE_PLUGINS 和INCLUDE_PLUGIN_TYPES 用于选择 Qt 插件。有关这些选项的文档，请参阅qt_deploy_runtime_dependencies()。
您可以通过NO_PLUGINS 选项完全禁用插件部署。
若要部署非 QML 应用程序，请改用qt_generate_deploy_app_script()。对同一目标同时调用qt_generate_deploy_qml_app_script() 和qt_generate_deploy_app_script()会导致错误。
示例
以下示例演示了如何部署一个Qt Quick 应用程序。
cmake_minimum_required(VERSION 3.16...3.22)
project(MyThings)
find_package(Qt6 6.3 REQUIRED COMPONENTS Core Qml)
qt_standard_project_setup()
qt_add_executable(MyApp main.cpp)
qt_add_qml_module(MyApp
URI Application
VERSION 1.0
QML_FILES main.qml MyThing.qml
)
install(TARGETS MyApp
BUNDLE DESTINATION .
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)
qt_generate_deploy_qml_app_script(
TARGET MyApp
OUTPUT_SCRIPT deploy_script
NO_UNSUPPORTED_PLATFORM_ERROR
DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM
)
install(SCRIPT ${deploy_script})以下示例展示了如何向底层部署工具传递额外选项。
# Pass the values on to the deploy tool unchanged, see \l {QTP0007}.
qt_policy(SET QTP0007 NEW)
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()
qt_generate_deploy_qml_app_script(
...
DEPLOY_TOOL_OPTIONS ${deploy_tool_options_arg}
)
install(SCRIPT ${deploy_script})另请参阅 qt_standard_project_setup()、qt_generate_deploy_app_script()、QTP0007 和QTP0008。
© 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.
