qt_generate_deploy_qml_app_script

为 QML 应用程序生成部署脚本。

该命令在Qt6 软件包的Qml 组件中定义，可以像这样加载：

find_package(Qt6 REQUIRED COMPONENTS Qml)

此命令在 Qt 6.3 中引入。

简介

qt_generate_deploy_qml_app_script(
    TARGET <target>
    OUTPUT_SCRIPT <var>
    [NO_UNSUPPORTED_PLATFORM_ERROR]
    [NO_TRANSLATIONS]
    [NO_COMPILER_RUNTIME]
    [DEPLOY_TOOL_OPTIONS ...]
    [DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM]
    [MACOS_BUNDLE_POST_BUILD]
    [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 应用捆绑除外，它遵循苹果的要求）。QML 模块会安装到平台的适当位置。对于 macOS 捆绑程序，每个 QML 模块的qmldir 文件都安装在Resources/qml 下的相应子目录下，模块的插件（如有）安装在PlugIns 下。应用程序捆绑包假定直接安装到基本安装位置（见下文示例）。对于所有其他平台，qmldir 和模块插件都安装在qml 下的相应子目录下，而子目录本身是相对于基本安装位置的。

qt_generate_deploy_qml_app_script() 生成一个脚本，其名称将保存在 选项命名的变量中。该脚本仅在 CMake 生成时编写。它将与OUTPUT_SCRIPT install(SCRIPT)命令一起使用，而 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 模块仍被安装。

当target 是一个 macOS 应用捆绑包时，MACOS_BUNDLE_POST_BUILD 选项会启用一个额外步骤。将创建一个编译后规则，使用部署脚本部署足够的导入 QML 模块，使应用程序能直接从编译目录运行（基本上只有qmldir 文件和指向插件的 symlinks）。在所有其他平台上，MACOS_BUNDLE_POST_BUILD 将被忽略。

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

对于 Windows 桌面应用程序，编译器所需的运行时文件也会默认安装。要避免这种情况，请指定NO_COMPILER_RUNTIME 。

自 Qt 6.7 起，您可以使用DEPLOY_TOOL_OPTIONS 向底层部署工具传递附加选项。这只有在底层部署工具是 macdeployqt 或 windeployqt 时才有效。

可以指定PRE_INCLUDE_REGEXES 、PRE_EXCLUDE_REGEXES 、POST_INCLUDE_REGEXES 、POST_EXCLUDE_REGEXES 、POST_INCLUDE_FILES 和POST_EXCLUDE_FILES 选项来控制运行时依赖项的部署。这些选项并不适用于所有平台，它们将不加修改地转发给qt_deploy_runtime_dependencies()。

要部署非 QML 应用程序，请使用qt_generate_deploy_app_script()。对同一目标同时调用qt_generate_deploy_qml_app_script() 和qt_generate_deploy_app_script()是错误的。

示例

下面的示例展示了如何部署QtQuick 应用程序。

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
    MACOS_BUNDLE_POST_BUILD
    NO_UNSUPPORTED_PLATFORM_ERROR
    DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM
)
install(SCRIPT ${deploy_script})

下面的示例展示了如何向底层部署工具传递附加选项。

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

qt_generate_deploy_qml_app_script(
    ...
    DEPLOY_TOOL_OPTIONS ${deploy_tool_options_arg}
)
install(SCRIPT ${deploy_script})