qt_generate_deploy_qml_app_script

Genera un script de despliegue para una aplicación QML.

El comando está definido en el componente Qml del paquete Qt6, que puede cargarse de este modo:

find_package(Qt6 REQUIRED COMPONENTS Qml)

Este comando se introdujo en Qt 6.3.

Sinopsis

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

Si los comandos sin versión están deshabilitados, utilice qt6_generate_deploy_qml_app_script() en su lugar. Admite el mismo conjunto de argumentos que este comando.

Descripción

Instalar un objetivo ejecutable que también es un módulo QML requiere desplegar una serie de cosas además del objetivo en sí. Las librerías Qt y otras librerías del proyecto, los plugins Qt, y las partes de tiempo de ejecución de todos los módulos QML que utiliza la aplicación pueden necesitar ser instalados también. El diseño instalado también va a ser diferente para los paquetes de aplicaciones macOS en comparación con otras plataformas. qt_generate_deploy_qml_app_script() es un comando práctico destinado a simplificar ese proceso, similar a lo que qt_generate_deploy_app_script() hace para aplicaciones que no son QML.

El comando espera que la aplicación siga bastante de cerca la estructura de directorios de instalación recomendada por Qt. Esta estructura se basa en la distribución de instalación por defecto de CMake, determinada por GNUInstallDirs (excepto para los paquetes de aplicaciones macOS, que siguen los requisitos de Apple). Los módulos QML se instalan en la ubicación adecuada para cada plataforma. Para los paquetes de macOS, el archivo qmldir de cada módulo QML se instala en el subdirectorio adecuado debajo de Resources/qml y el complemento del módulo (si está presente) se instala en PlugIns. Se supone que el paquete de aplicaciones se instala directamente en la ubicación de la instalación base (véase el ejemplo a continuación). Para el resto de plataformas, tanto qmldir como el plugin del módulo se instalan en el subdirectorio apropiado bajo qml, que a su vez es relativo a la ubicación de la instalación base.

qt_generate_deploy_qml_app_script() genera un script cuyo nombre se almacenará en la variable nombrada por la opción OUTPUT_SCRIPT. Ese script sólo se escribe en el momento de generar CMake. Está pensado para ser utilizado con el comando install(SCRIPT), que debería venir después de que el objetivo de la aplicación haya sido instalado utilizando install(TARGETS).

El script de despliegue llamará a qt_deploy_qml_imports() con un conjunto adecuado de opciones para el diseño de instalación estándar. Para paquetes de aplicaciones macOS y objetivos Windows, también se llamará a qt_deploy_runtime_dependencies(), de nuevo con las opciones adecuadas para el diseño de instalación estándar.

Llamar a qt_generate_deploy_qml_app_script() para una plataforma que no está soportada por qt_deploy_runtime_dependencies resultará en un error fatal, a menos que se proporcione la opción NO_UNSUPPORTED_PLATFORM_ERROR. Cuando se da la opción y el proyecto se construye para una plataforma no soportada, no se instalarán ni los módulos QML ni las dependencias regulares de tiempo de ejecución. Para garantizar la instalación de los módulos QML, especifique las opciones NO_UNSUPPORTED_PLATFORM_ERROR y DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM. Esta última opción garantizará que se sigan instalando los módulos QML creados como parte del proyecto.

La opción MACOS_BUNDLE_POST_BUILD habilita un paso adicional cuando target es un paquete de aplicaciones macOS. Se creará una regla posterior a la compilación que utilizará el script de despliegue para desplegar suficientes módulos QML importados como para permitir que la aplicación se ejecute directamente desde el directorio de compilación (básicamente, sólo los archivos qmldir y los enlaces simbólicos a los plugins). Esto suele ser deseable para apoyar el desarrollo de la aplicación. MACOS_BUNDLE_POST_BUILD se ignora para el resto de plataformas.

En plataformas distintas de macOS, las traducciones de Qt se despliegan automáticamente. Para inhibir este comportamiento, especifique NO_TRANSLATIONS. Utilice qt_deploy_translations() para desplegar las traducciones de forma personalizada.

Para las aplicaciones de escritorio de Windows, los archivos de tiempo de ejecución necesarios para el compilador también se instalan de forma predeterminada. Para evitarlo, especifique NO_COMPILER_RUNTIME.

Desde Qt 6.7, puede utilizar DEPLOY_TOOL_OPTIONS para pasar opciones adicionales a la herramienta de despliegue subyacente. Esto sólo tiene efecto si la herramienta de despliegue subyacente es macdeployqt o windeployqt.

Las opciones PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, POST_EXCLUDE_REGEXES, POST_INCLUDE_FILES, y POST_EXCLUDE_FILES pueden especificarse para controlar el despliegue de dependencias en tiempo de ejecución. Estas opciones no se aplican a todas las plataformas y se reenvían sin modificar a qt_deploy_runtime_dependencies().

Las opciones EXCLUDE_PLUGINS, EXCLUDE_PLUGIN_TYPES, INCLUDE_PLUGINS, y INCLUDE_PLUGIN_TYPES se utilizan para seleccionar plugins de Qt. Ver qt_deploy_runtime_dependencies() para su documentación.

Puede desactivar el despliegue de plugins con la opción NO_PLUGINS.

Para desplegar una aplicación no QML, utilice qt_generate_deploy_app_script() en su lugar. Es un error llamar tanto a qt_generate_deploy_qml_app_script() como a qt_generate_deploy_app_script() para el mismo objetivo.

Ejemplo

El siguiente ejemplo muestra cómo desplegar una aplicación 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
    MACOS_BUNDLE_POST_BUILD
    NO_UNSUPPORTED_PLATFORM_ERROR
    DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM
)
install(SCRIPT ${deploy_script})

El siguiente ejemplo muestra cómo pasar opciones adicionales a la herramienta de despliegue subyacente.

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