qt_deploy_runtime_dependencias

Despliega los plugins Qt y las librerías Qt y no Qt que necesita un ejecutable.

El comando está definido en el componente Core del paquete Qt6, que puede cargarse de esta forma:

find_package(Qt6 REQUIRED COMPONENTS Core)

A diferencia de la mayoría de los otros comandos CMake proporcionados por Qt, qt_deploy_runtime_dependencies() sólo puede ser llamado desde un script de despliegue. No puede ser llamado directamente por el proyecto durante la etapa de configuración.

Este comando fue introducido en Qt 6.3.

Sinopsis

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

Descripción

Al instalar una aplicación, puede ser conveniente instalar también las bibliotecas y plugins de los que depende. Cuando la aplicación es un paquete de aplicaciones para macOS o un ejecutable para Windows, se puede llamar a qt_deploy_runtime_dependencies() desde un script de instalación para desplegar esas dependencias. Se instalarán las bibliotecas Qt que no sean del sistema, además de un conjunto adecuado de plugins Qt.

En Linux, el comando desplegará bibliotecas adicionales, además de las relacionadas con Qt, que se incluyen con el proyecto. Sin embargo, cuando se ejecuta en macOS o Windows, el comando utilizará macdeployqt o windeployqt, que sólo desplegará las bibliotecas específicas de Qt.

Este comando sólo tiene en cuenta las dependencias en tiempo de ejecución para las que existen relaciones de enlace en los binarios subyacentes. No despliega módulos QML, véase qt_deploy_qml_imports() para ello.

Argumentos

Se debe proporcionar la opción EXECUTABLE.

El argumento executable debe ser la ruta al archivo ejecutable en el directorio de compilación. Por ejemplo, ${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe, o más dinámicamente $<TARGET_FILE:MyApp>. No se admite la especificación de nombres de destino sin procesar no envueltos en una expresión generadora como $<TARGET_FILE:>.

Para los paquetes de aplicaciones de macOS, el argumento executable debe ser una ruta al directorio del paquete, relativa a la ubicación de la instalación base. Por ejemplo MyApp.app, o más dinámicamente $<TARGET_FILE_NAME:MyApp>.app. No se admite la especificación de nombres de destino sin procesar no envueltos en una expresión generadora como $<TARGET_FILE_NAME:>.

También puede ser deseable instalar dependencias para otros binarios relacionados con executable. Por ejemplo, los plugins proporcionados por el proyecto pueden tener otras dependencias, pero como esos plugins no estarán enlazados directamente con el ejecutable, qt_deploy_runtime_dependencies() no los descubrirá automáticamente. Las opciones ADDITIONAL_EXECUTABLES, ADDITIONAL_LIBRARIES, y ADDITIONAL_MODULES pueden usarse para especificar binarios adicionales cuyas dependencias también deben desplegarse (la instalación de los binarios nombrados sigue siendo responsabilidad del proyecto). El nombre de estas palabras clave sigue las convenciones de CMake, por lo que los plugins Qt se especificarían usando ADDITIONAL_MODULES. Cada valor debe ser una ruta relativa a la ubicación de la instalación base. Los valores pueden utilizar expresiones generadoras, al igual que con la opción EXECUTABLE. No se admite la especificación de nombres de destino en bruto no envueltos en una expresión generadora como $<TARGET_FILE_NAME:>.

Cuando se instala una aplicación Windows, es común necesitar un archivo qt.conf cuando se sigue la estructura de directorios de instalación por defecto de CMake. Si se da la opción GENERATE_QT_CONF, se escribirá un archivo qt.conf apropiado en el mismo directorio que executable. Las rutas en ese archivo qt.conf se basarán en las variables CMAKE_INSTALL_xxxDIR, cuyos valores predeterminados son proporcionados por el módulo GNUInstallDirs de CMake.

Puede anular algunos de esos valores predeterminados con los parámetros de la siguiente tabla, todos los cuales se espera que sean relativos a la ubicación de la instalación base.

Siempre se escribe un archivo qt.conf si executable es un paquete de aplicaciones macOS, independientemente de si se proporciona o no GENERATE_QT_CONF. Las opciones de ..._DIR también se ignoran en ese caso, ya que la disposición de directorios de un paquete de aplicaciones viene dictada por los requisitos de Apple.

Se puede habilitar una salida más detallada sobre los pasos de despliegue proporcionando la opción VERBOSE. Alternativamente, la variable QT_ENABLE_VERBOSE_DEPLOYMENT puede establecerse en el proyecto antes de la primera llamada a find_package(Qt6) para que la salida de despliegue sea verbosa por defecto.

El comando qt_deploy_runtime_dependencies() sobrescribe los archivos existentes por defecto (algunas advertencias pueden ser emitidas). Utilice la opción NO_OVERWRITE para evitar sobrescribir los archivos existentes. Tenga en cuenta que esta opción sólo afecta actualmente a las implantaciones en macOS y Windows.

Por defecto, si executable es un paquete de aplicaciones para macOS, sólo se despliegan los plugins de Qt y las bibliotecas de Qt que cumplen los requisitos de la tienda de aplicaciones de Apple. Se puede dar la opción NO_APP_STORE_COMPLIANCE para desactivar esa restricción.

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.

En Linux, el despliegue de dependencias en tiempo de ejecución se basa en el comando file(GET_RUNTIME_DEPENDENCIES) de CMake. Las opciones PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, POST_EXCLUDE_REGEXES, POST_INCLUDE_FILES, y POST_EXCLUDE_FILES sólo tienen sentido en este contexto y se reenvían inalteradas a file(GET_RUNTIME_DEPENDENCIES). Consulte la documentación de ese comando para obtener más detalles.

En Linux, las dependencias de tiempo de ejecución que se encuentran en directorios de bibliotecas del sistema no se despliegan por defecto. Si se especifica POST_EXCLUDE_REGEXES, no se realiza esta exclusión automática.

El valor por defecto de POST_EXCLUDE_REGEXES se construye a partir del valor de QT_DEPLOY_IGNORED_LIB_DIRS.

Control del despliegue de plugins Qt

Los plugins Qt se despliegan automáticamente en QT_DEPLOY_PLUGINS_DIR.

Puede desactivar el despliegue de plugins con el argumento NO_PLUGINS.

Puedes incluir todos los plugins de un tipo específico con el argumento INCLUDE_PLUGIN_TYPES. Puede excluir todos los plugins de un tipo específico con el argumento EXCLUDE_PLUGIN_TYPES. Ambos argumentos toman tipos de plugins, por ejemplo imageformats.

Puede incluir o excluir plugins específicos con los argumentos INCLUDE_PLUGINS y EXCLUDE_PLUGINS. Ambos argumentos toman nombres de plugins, por ejemplo qjpeg.

Ejemplo

El siguiente ejemplo muestra cómo desplegar una aplicación 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

El siguiente ejemplo muestra cómo utilizar el parámetro DEPLOY_TOOL_OPTIONS para pasar diferentes opciones a macdeployqt y windeployqt.

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

# 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
)")