En esta página

qt_deploy_runtime_dependencies

Implementa los complementos de Qt y las bibliotecas de Qt y ajenas a Qt que necesita un ejecutable.

El comando está definido en el componente « Core » del paquete « Qt6 », que se puede cargar de la siguiente manera:

find_package(Qt6 REQUIRED COMPONENTS Core)

A diferencia de la mayoría de los demás comandos de CMake proporcionados por Qt, qt_deploy_runtime_dependencies() solo se puede invocar desde un script de implementación. El proyecto no puede invocarlo directamente durante la fase de configuración.

Este comando se introdujo en Qt 6.3.

Nota: Normalmente no es necesario llamar aeste comando directamente. Lo utilizan internamente otros comandos de nivel superior, pero puede resultar útil para los proyectos que deseen implementar una lógica de implementación más personalizada.

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 resultar conveniente instalar también las bibliotecas y los complementos de los que depende. Cuando la aplicación es un paquete de macOS o un ejecutable de Windows, se puede llamar a ` qt_deploy_runtime_dependencies() ` desde un script de instalación para implementar esas dependencias. Instalará las bibliotecas Qt que no sean del sistema, además de un conjunto adecuado de complementos de Qt.

En Linux, el comando implementará bibliotecas adicionales, más allá de las relacionadas con Qt, que se incluyan en el proyecto. Sin embargo, cuando se ejecute en macOS o Windows, el comando utilizará macdeployqt o windeployqt, que solo implementarán bibliotecas específicas de Qt.

Este comando solo tiene en cuenta las dependencias de tiempo de ejecución para las que existen relaciones de enlace en los binarios subyacentes. No instala módulos QML; para ello, consulta qt_deploy_qml_imports().

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 de forma más dinámica, ` $<TARGET_FILE:MyApp>`. No se admite la especificación de nombres de destino sin formato que no estén envueltos en una expresión generadora como ` $<TARGET_FILE:> `.

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

También puede ser conveniente instalar dependencias para otros binarios relacionados con executable. Por ejemplo, los complementos proporcionados por el proyecto podrían tener otras dependencias, pero, dado que esos complementos no se vincularán directamente al ejecutable, qt_deploy_runtime_dependencies() no los detectará automáticamente. Las opciones ADDITIONAL_EXECUTABLES, ADDITIONAL_LIBRARIES y ADDITIONAL_MODULES pueden utilizarse para especificar binarios adicionales cuyas dependencias también deben implementarse (la instalación de los propios binarios nombrados sigue siendo responsabilidad del proyecto). La nomenclatura de estas palabras clave sigue las convenciones de CMake, por lo que los complementos de Qt se especificarían utilizando ADDITIONAL_MODULES. Cada valor debe ser una ruta relativa a la ubicación de 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 sin formato que no estén envueltos en una expresión generadora, como $<TARGET_FILE_NAME:>.

Al instalar una aplicación para Windows, es habitual necesitar un archivo qt.conf cuando se sigue la estructura de directorios de instalación predeterminada de CMake. Si se especifica la opción « GENERATE_QT_CONF », se creará un archivo « qt.conf » adecuado en el mismo directorio que « executable ». Las rutas de ese archivo « qt.conf » se basarán en las variables « CMAKE_INSTALL_xxxDIR », cuyos valores predeterminados los proporciona el módulo GNUInstallDirs de CMake.

Puedes anular algunos de esos valores por defecto con los parámetros de la siguiente tabla, todos los cuales deben ser relativos a la ubicación de instalación base.

parámetroVariable afectadaNotas
BIN_DIRQT_DEPLOY_BIN_DIR
LIBEXEC_DIRQT_DEPLOY_LIBEXEC_DIRdesde Qt 6.7
LIB_DIRQT_DEPLOY_LIB_DIR
PLUGINS_DIRQT_DEPLOY_PLUGINS_DIR
QML_DIRQT_DEPLOY_QML_DIR

No se escribe ningún archivo ` qt.conf ` si ` executable ` es un paquete de aplicación de macOS, y en ese caso se ignoran tanto la opción ` GENERATE_QT_CONF ` como la opción ` ..._DIR `. La estructura de directorios de un paquete de aplicación viene dictada por los requisitos de Apple, y Qt encuentra las bibliotecas, los complementos y los recursos en esas ubicaciones convencionales sin necesidad de un archivo ` qt.conf`.

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

El comando ` qt_deploy_runtime_dependencies() ` sobrescribe los archivos existentes de forma predeterminada (aunque es posible que se muestren algunas advertencias). Utiliza la opción ` NO_OVERWRITE ` para evitar que se sobrescriban los archivos existentes. Ten en cuenta que, actualmente, esta opción solo afecta a las implementaciones en macOS y Windows.

Por defecto, si executable es un paquete de aplicación de macOS, solo se implementan los complementos y las bibliotecas de Qt que cumplen los requisitos de la App Store de Apple. Se puede especificar la opción NO_APP_STORE_COMPLIANCE para desactivar esa restricción.

En plataformas distintas de macOS, las traducciones de Qt se implementan automáticamente. Para desactivar este comportamiento, especifica NO_TRANSLATIONS. Utiliza qt_deploy_translations() para implementar las traducciones de forma personalizada.

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

Desde Qt 6.7, puede utilizar ` DEPLOY_TOOL_OPTIONS ` para pasar opciones adicionales a la herramienta de implementación subyacente. Esto solo surte efecto si la herramienta de implementación subyacente es `macdeployqt` o `windeployqt`.

Nota: Cuando este comando se invoca desde el ` CONTENT ` de `qt_generate_deploy_script()`, los valores de ` DEPLOY_TOOL_OPTIONS ` deben escribirse entre comillas simples para que se conserven los espacios en blanco en el script de implementación generado. Además, cada valor que contenga un espacio, como una identidad de firma de código, debe escribirse entre comillas escapadas con barra invertida.

En Linux, el despliegue de las dependencias de 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 solo tienen sentido en este contexto y se reenvían sin modificaciones a file(GET_RUNTIME_DEPENDENCIES). Consulte la documentación de dicho comando para obtener más detalles.

En Linux, las dependencias de tiempo de ejecución que se encuentran en los directorios de bibliotecas del sistema no se implementan de forma predeterminada. Si se especifica POST_EXCLUDE_REGEXES, no se lleva a cabo esta exclusión automática.

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

Control de la implementación de los complementos de Qt

Los complementos de Qt se implementan automáticamente en QT_DEPLOY_PLUGINS_DIR.

Puedes desactivar el despliegue de complementos con el argumento NO_PLUGINS.

Se pueden incluir todos los complementos de un tipo específico mediante el argumento ` INCLUDE_PLUGIN_TYPES `. Se pueden excluir todos los complementos de un tipo específico mediante el argumento ` EXCLUDE_PLUGIN_TYPES `. Ambos argumentos admiten tipos de complementos, p. ej., ` imageformats`.

Se pueden incluir o excluir complementos específicos mediante los argumentos « INCLUDE_PLUGINS » y « EXCLUDE_PLUGINS ». Ambos argumentos admiten nombres de complementos, por ejemplo, « qjpeg ».

Nota: No hay que confundir los nombresde los complementos con los objetivos de los complementos. Por ejemplo, el nombre del complemento del objetivo Qt6::QJpegPlugin es qjpeg.

Nota: Los argumentos EXCLUDE_PLUGINS, EXCLUDE_PLUGIN_TYPES, INCLUDE_PLUGINS y INCLUDE_PLUGIN_TYPES solo funcionan en Windows y Linux.

Ejemplo

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

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

Véase también qt_generate_deploy_app_script(), qt_deploy_qt_conf(), qt_deploy_qml_imports() y 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.