Qt para Windows - Implantación

Esta documentación describe el proceso de despliegue para Windows. Nos referimos a la aplicación de ejemplo Plug & Paint a lo largo del documento para demostrar el proceso de despliegue.

La herramienta de despliegue de Windows

La herramienta de despliegue de Windows windeployqt está diseñada para automatizar el proceso de creación de una carpeta desplegable que contenga las dependencias relacionadas con Qt(bibliotecas, importaciones QML, plugins y traducciones) necesarias para ejecutar la aplicación desde esa carpeta. Crea un árbol de instalación para las aplicaciones de escritorio de Windows, que puede agruparse fácilmente en un paquete de instalación.

La herramienta se encuentra en QTDIR/bin/windeployqt. Debe ejecutarse en el entorno de compilación para que funcione correctamente. Si se utiliza Qt Online Installer, debe utilizarse el script QTDIR/bin/qtenv2.bat para configurarlo.

windeployqt toma un archivo .exe o un directorio que contenga un archivo .exe como argumento, y escanea el ejecutable en busca de dependencias. Si se pasa un directorio con el argumento --qmldir, windeployqt utiliza la herramienta qmlimportscanner para escanear los archivos QML dentro del directorio en busca de dependencias de importación QML. A continuación, las dependencias identificadas se copian en el directorio del ejecutable.

En caso de que Qt haya sido construido con el parámetro de configuración -relocatable desactivado, windeployqt reemplaza las rutas locales codificadas en Qt6Core.dll por rutas relativas.

Para las aplicaciones de escritorio de Windows, los archivos de ejecución necesarios para el compilador también se copian en la carpeta desplegable de forma predeterminada (a menos que se especifique la opción --no-compiler-runtime ). En el caso de las compilaciones de lanzamiento que utilizan Microsoft Visual C++, se trata de los paquetes redistribuibles de Visual C++, destinados a la instalación recursiva por parte del instalador de la aplicación en el equipo de destino. En caso contrario, se utilizan las bibliotecas compartidas del compilador en tiempo de ejecución.

La aplicación puede requerir librerías adicionales de terceros (por ejemplo, librerías de bases de datos), que no son tenidas en cuenta por windeployqt.

Los argumentos adicionales se describen en la salida de ayuda de la herramienta:

Usage: windeployqt.exe [options] [files]
Qt Deploy Tool 6.11.0

The simplest way to use windeployqt is to add the bin directory of your Qt
installation (e.g. <QT_DIR\bin>) to the PATH variable and then run:
windeployqt <path-to-app-binary>

If your application uses Qt Quick, run:
windeployqt --qmldir <path-to-app-qml-files> <path-to-app-binary>

Options:
 -?, -h, --help                            Displays help on commandline
                                           options.
 --help-all                                Displays help, including generic Qt
                                           options.
 -v, --version                             Displays version information.
 --dir <directory>                         Use directory instead of binary
                                           directory.
 --qmake <path>                            Use specified qmake instead of
                                           qmake from PATH. Deprecated, use
                                           qtpaths instead.
 --qtpaths <path>                          Use specified qtpaths.exe instead
                                           of qtpaths.exe from PATH.
 --libdir <path>                           Copy libraries to path.
 --plugindir <path>                        Copy plugins to path.
 --translationdir <path>                   Copy translations to path.
 --qml-deploy-dir <path>                   Copy qml files to path.
 --debug                                   Assume debug binaries.
 --release                                 Assume release binaries.
 --pdb                                     Deploy .pdb files (MSVC).
 --force                                   Force updating files.
 --dry-run                                 Simulation mode. Behave normally,
                                           but do not copy/update any files.
 --no-patchqt                              Do not patch the Qt6Core library.
 --ignore-library-errors                   Ignore errors when libraries cannot
                                           be found.
 --no-plugins                              Skip plugin deployment.
 --include-soft-plugins                    Include in the deployment all
                                           relevant plugins by taking into
                                           account all soft dependencies.
 --skip-plugin-types <plugin types>        A comma-separated list of plugin
                                           types that are not deployed
                                           (qmltooling,generic).
 --add-plugin-types <plugin types>         A comma-separated list of plugin
                                           types that will be added to
                                           deployment
                                           (imageformats,iconengines)
 --include-plugins <plugins>               A comma-separated list of
                                           individual plugins that will be
                                           added to deployment (scene2d,qjpeg)
 --exclude-plugins <plugins>               A comma-separated list of
                                           individual plugins that will not be
                                           deployed (qsvg,qpdf)
 --no-libraries                            Skip library deployment.
 --qmldir <directory>                      Scan for QML-imports starting from
                                           directory.
 --qmlimport <directory>                   Add the given path to the QML
                                           module search locations.
 --no-quick-import                         Skip deployment of Qt Quick
                                           imports.
 --translations <languages>                A comma-separated list of languages
                                           to deploy (de,fi).
 --no-translations                         Skip deployment of translations.
 --no-system-d3d-compiler                  Skip deployment of the system D3D
                                           compiler.
 --no-system-dxc-compiler                  Skip deployment of the system DXC
                                           (dxcompiler.dll, dxil.dll).
 --compiler-runtime                        Deploy compiler runtime (Desktop
                                           only).
 --no-compiler-runtime                     Do not deploy compiler runtime
                                           (Desktop only).
 --json                                    Print to stdout in JSON format.
 --no-opengl-sw                            Do not deploy the software
                                           rasterizer library.
 --no-ffmpeg                               Do not deploy the FFmpeg libraries.
 --force-openssl                           Deploy openssl plugin but ignore
                                           openssl library dependency
 --openssl-root <directory>                Directory containing openSSL
                                           libraries.
 --list <option>                           Print only the names of the files
                                           copied.
                                           Available options:
                                            source:   absolute path of the
                                           source files
                                            target:   absolute path of the
                                           target files
                                            relative: paths of the target
                                           files, relative
                                                      to the target directory
                                            mapping:  outputs the source and
                                           the relative
                                                      target, suitable for use
                                           within an
                                                      Appx mapping file
 --verbose <level>                         Verbose level (0-2).

Qt libraries can be added by passing their name (-xml) or removed by passing
the name prepended by --no- (--no-xml).

Arguments:
[files]                                   Binaries or directory containing
                                          the binary.

Enlace estático

Para construir aplicaciones estáticas, construya Qt estáticamente configurando Qt con -static:

cd C:\path\to\Qt
configure -static <any other options you need>

Si más tarde necesita reconfigurar y reconstruir Qt desde la misma ubicación, asegúrese de que se eliminan todos los rastros de la configuración anterior.

Vinculación de la aplicación a la versión estática de Qt

Como ejemplo, esta sección construirá el ejemplo Plug & Paint contra una versión estática de Qt.

Una vez que Qt termine de construirse, construye la aplicación Plug & Paint. Esta sección asume que la versión estática de Qt ha sido instalada en C:\path\to \static \Qt . Primero debemos entrar en el directorio que contiene la aplicación:

cd examples\tools\plugandpaint

Ahora, creamos un directorio de compilación y llamamos a qt-cmake para generar los archivos del sistema de compilación.

md build_static
cd build_static
C:\path\to\static\Qt\bin\qt-cmake .. -DCMAKE_BUILD_TYPE=Release -GNinja
ninja

Probablemente quieras enlazar contra las librerías de lanzamiento, y especificamos esto con la variable CMAKE_BUILD_TYPE. Ahora, siempre que todo haya compilado y enlazado sin errores, deberíamos tener un archivo plugandpaint.exe listo para ser desplegado. Para comprobar que la aplicación tiene las librerías necesarias, copia el ejecutable a una máquina que no tenga Qt ni ninguna aplicación Qt instalada, y ejecútalo en esa máquina.

Recuerda que si tu aplicación depende de librerías específicas del compilador, éstas deben ser redistribuidas junto con tu aplicación. Puedes comprobar con qué bibliotecas está enlazando tu aplicación utilizando la herramienta depends. Para más información, lee la sección Dependencias de la aplicación.

Dado que no podemos desplegar plugins utilizando el enfoque de enlace estático, la aplicación que hemos preparado está incompleta. Se ejecutará, pero la funcionalidad estará deshabilitada debido a los plugins que faltan. Para desplegar aplicaciones basadas en plugins debemos utilizar el enfoque de bibliotecas compartidas.

Bibliotecas compartidas

Tenemos dos desafíos al desplegar la aplicación plugandpaint utilizando el enfoque de bibliotecas compartidas: El tiempo de ejecución Qt tiene que ser redistribuido correctamente junto con el ejecutable de la aplicación, y los plugins tienen que ser instalados en la ubicación correcta en el sistema de destino para que la aplicación pueda encontrarlos.

Construir Qt como biblioteca compartida

Para este ejemplo, asumimos que Qt está instalado como una biblioteca compartida, que es el valor por defecto al instalar Qt, en el directorio C:\path\to \Qt .

Enlazando la Aplicación a Qt como Librería Compartida

Después de asegurarnos de que Qt está construido como una biblioteca compartida, podemos construir la aplicación plugandpaint. Primero, debemos entrar en el directorio que contiene la aplicación:

cd examples\tools\plugandpaint

Ahora crea un directorio de construcción dedicado y ejecuta qt-cmake para crear los archivos del sistema de construcción:

md build_shared
cd build_shared
C:\path\to\Qt\bin\qt-cmake .. -DCMAKE_BUILD_TYPE=Release -GNinja
ninja

Si todo se compila y enlaza sin errores, obtendremos un ejecutable plugandpaint.exe y los archivos plugin pnp_basictools.dll y pnp_extrafilters.dll.

Creación del paquete de la aplicación

Para desplegar la aplicación, debemos asegurarnos de copiar las DLLs Qt relevantes (correspondientes a los módulos Qt utilizados en la aplicación) y el plugin de plataforma Windows, qwindows.dll, así como el ejecutable al mismo árbol de directorios en el subdirectorio release.

A diferencia de los plugins de usuario, los plugins de Qt deben colocarse en los subdirectorios correspondientes al tipo de plugin. La ubicación correcta para el plugin de plataforma es un subdirectorio llamado platforms. La sección Plugins de Q t tiene información adicional sobre plugins y cómo Qt los busca.

Si se usa OpenGL dinámico, es posible que se quiera incluir adicionalmente la librería necesaria OpenGL basada en software, si la aplicación es compatible con ella.

Si Qt fue configurado para enlazar contra ICU u OpenSSL, las respectivas DLL's necesitan ser añadidas a la carpeta release, también. Pero los paquetes binarios para Qt en Windows no requieren esto. Para más detalles, vea también Bibliotecas de terceros.

Recuerda que si tu aplicación depende de librerías específicas del compilador, éstas deben ser redistribuidas junto con tu aplicación. Puede comprobar con qué bibliotecas está enlazando su aplicación utilizando la herramienta depends. Para más información, consulte la sección Dependencias de la aplicación.

Cubriremos los plugins en breve, pero primero comprobaremos que la aplicación funcionará en un entorno desplegado: O bien copia el ejecutable y las DLLs de Qt a una máquina que no tenga Qt o cualquier aplicación Qt instalada, o si quieres probar en la máquina de compilación, asegúrate de que la máquina no tiene Qt en su entorno.

Si la aplicación se inicia sin problemas, entonces hemos hecho con éxito una versión enlazada dinámicamente de la aplicación plugandpaint. Pero la funcionalidad de la aplicación todavía estará ausente ya que todavía no hemos desplegado los plugins asociados.

Los plugins funcionan de forma diferente a las DLLs normales, por lo que no podemos simplemente copiarlos en el mismo directorio que el ejecutable de nuestra aplicación como hicimos con las DLLs de Qt. Cuando busca plugins, la aplicación busca en un subdirectorio plugins dentro del directorio del ejecutable de la aplicación.

Así que para hacer que los plugins estén disponibles para nuestra aplicación, tenemos que crear el subdirectorio plugins y copiar las DLLs relevantes:

plugins\pnp_basictools.dll
plugins\pnp_extrafilters.dll

Un archivo que distribuya todas las DLLs de Qt y los plugins específicos de la aplicación necesarios para ejecutar la aplicación Plug & Paint, tendría que incluir los siguientes ficheros:

Otros plugins pueden ser necesarios dependiendo de las características que utilice la aplicación (iconengines, imageformats).

Además, el archivo debe contener las siguientes bibliotecas específicas del compilador (suponiendo Visual Studio 17 (2022)):

Si se ha utilizado OpenGL dinámico, el archivo puede contener además:

Finalmente, si Qt fue configurado para usar ICU, el archivo debe contener:

Para verificar que la aplicación ahora puede ser desplegada con éxito, puede extraer este archivo en una máquina sin Qt y sin ningún compilador instalado, e intentar ejecutarla.

Una alternativa a poner los plugins en el subdirectorio de plugins es añadir una ruta de búsqueda personalizada cuando inicies tu aplicación usando QCoreApplication::addLibraryPath() o QCoreApplication::setLibraryPaths().

QCoreApplication::addLibraryPath("C:/some/other/path");

Una ventaja de utilizar plugins es que pueden ponerse fácilmente a disposición de toda una familia de aplicaciones.

A menudo es más conveniente añadir la ruta en la función main() de la aplicación, justo después de crear el objeto QApplication. Una vez añadida la ruta, la aplicación la buscará en busca de plugins, además de buscar en el subdirectorio plugins en el propio directorio de la aplicación. Se puede añadir cualquier número de rutas adicionales.

Generación del manifiesto de la aplicación Windows

Cuando se construye en Windows, Qt genera e incrusta automáticamente un manifiesto de aplicación para los objetivos ejecutables.

El manifiesto generado:

• Declara la compatibilidad con Windows 10 y Windows 11
• Habilita el reconocimiento de rutas largas
• Establece la versión de la aplicación (desde PROJECT_VERSION)
• Define un identificador de proyecto
• Configura el nivel de ejecución solicitado
• Desactiva el manifiesto generado por el enlazador por defecto (/MANIFEST:NO)

Si ya se proporciona un archivo .manifest personalizado en los fuentes de destino, Qt no lo anula.

Declarar la compatibilidad con Windows 10/11 permite el comportamiento moderno de Windows, incluyendo:

• Optar por el comportamiento moderno del gestor de ventanas
• Soporte para WS_EX_LAYERED en ventanas hijo (soportado desde Windows 8 pero limitado por la compatibilidad)
• Soporte de rutas largas (> 260 caracteres)
• Configuración explícita del nivel de ejecución

Sin una declaración de compatibilidad adecuada, Windows puede aplicar un comportamiento heredado a la aplicación.

Contenido predeterminado del manifiesto

Identidad de la aplicación

El manifiesto contiene un elemento assemblyIdentity:

<assemblyIdentity
    type="win32"
    name="com.yourcompany.myapp"
    version="1.0.0.0"
    processorArchitecture="*" />

• name - identificador del proyecto
• version - normalizado a una versión Windows de cuatro partes

Por defecto, el identificador es

com.yourcompany.<target_name>

Puede anularse por objetivo utilizando la propiedad QT_WINDOWS_APP_PROJECT_IDENTIFIER:

set_target_properties(myapp PROPERTIES
    QT_WINDOWS_APP_PROJECT_IDENTIFIER "org.example.myapp"
)

Los manifiestos de aplicaciones Windows requieren un número de versión de cuatro partes:

Major.Minor.Build.Revision

Cada segmento debe ser un número entero en el rango 0-65535.

El valor se obtiene de PROJECT_VERSION y se normaliza de la siguiente manera:

• Si falta → valor por defecto 1.0.0.0
• Menos de cuatro segmentos → rellenado con ceros
• Más de cuatro segmentos → truncado
• Valores < 0 → ajustados a 0
• Valores > 65535 → ajustados a 65535 (se emite una advertencia)

Ejemplos:

2.3        -> 2.3.0.0
1.2.3.4.5  -> 1.2.3.4
70000.1    -> 65535.1.0.0

Compatibilidad con Windows

El manifiesto declara la compatibilidad con Windows 10 y Windows 11.

<supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />

{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a} GUID se corresponde con estos sistemas operativos: Windows 10, Windows 11, Windows Server 2016, Windows Server 2019 y Windows Server 2022.

Más información en: Manifiestos de aplicaciones de Microsoft.

Conciencia de ruta larga

<ws2:longPathAware>true</ws2:longPathAware>

Permite utilizar rutas de archivo de más de 260 caracteres, cuando el sistema operativo lo admite.

Nivel de ejecución

<requestedExecutionLevel level="asInvoker" uiAccess="false" />

El nivel por defecto es asInvoker.

Para establecer el nivel de ejecución, utilice la propiedad QT_WINDOWS_APP_PROJECT_EXECUTION_LEVEL.

Valores válidos:

• asInvoker (por defecto)
• highestAvailable
• requireAdministrator

Ejemplo:

set_target_properties(myapp PROPERTIES
    QT_WINDOWS_APP_PROJECT_EXECUTION_LEVEL "requireAdministrator"
)

Si se proporciona un valor no válido, se emite una advertencia y se utiliza asInvoker.

Proporcionar un manifiesto personalizado

Qt detecta el archivo de manifiesto y omite la generación automática, si un ejecutable ya incluye un archivo .manifest en sus fuentes:

add_executable(myapp
    main.cpp
    myapp.manifest
)

Ejemplo completo

El siguiente ejemplo muestra un ejecutable Windows que utiliza el manifiesto generado automáticamente con identificador y nivel de ejecución personalizados:

cmake_minimum_required(VERSION 3.21)
project(MyApp VERSION 2.5.1)

find_package(Qt6 REQUIRED COMPONENTS Core Widgets)

qt_add_executable(MyApp
    main.cpp
)

set_target_properties(MyApp PROPERTIES
    QT_WINDOWS_APP_PROJECT_IDENTIFIER "org.example.myapp"
    QT_WINDOWS_APP_PROJECT_EXECUTION_LEVEL "highestAvailable"
)

En este ejemplo, la versión del manifiesto generado será:

2.5.1.0

Archivos de manifiesto con qmake

Cuando se despliega una aplicación compilada con Visual Studio, hay que seguir algunos pasos adicionales.

En primer lugar, debemos copiar el archivo de manifiesto creado al vincular la aplicación. Este archivo de manifiesto contiene información sobre las dependencias de la aplicación en ensamblados paralelos, como las bibliotecas de tiempo de ejecución.

El archivo de manifiesto debe copiarse en la misma carpeta que el ejecutable de la aplicación. No es necesario copiar los archivos de manifiesto de las bibliotecas compartidas (DLL), ya que no se utilizan.

Si la biblioteca compartida tiene dependencias distintas de la aplicación que la utiliza, el archivo de manifiesto debe incrustarse en el binario de la DLL. Las siguientes opciones de CONFIG están disponibles para incrustar manifiestos:

embed_manifest_dll
embed_manifest_exe

Ambas opciones están activadas por defecto. Para eliminar embed_manifest_exe, añada

CONFIG -= embed_manifest_exe

a su archivo .pro.

Encontrará más información sobre los archivos de manifiesto y los ensamblajes paralelos en la página de documentación de Ensamblajes paralelos.

La forma correcta de incluir las bibliotecas de tiempo de ejecución con su aplicación es asegurarse de que están instaladas en el sistema del usuario final.

Para instalar las bibliotecas de tiempo de ejecución en el sistema del usuario final, debe incluir el ejecutable apropiado del paquete redistribuible de Visual C++ (VCRedist) con su aplicación y asegurarse de que se ejecuta cuando el usuario instala su aplicación.

El redistribuible se llama vc_redist.x64.exe (64 bits) y se encuentra en la carpeta <Visual Studio install path>/VC/redist/<language-code>.

También puede descargarse de la web, por ejemplo https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads.

Dependencias de la aplicación

Bibliotecas adicionales

Dependiendo de la configuración, las bibliotecas específicas del compilador deben redistribuirse junto con su aplicación.

Puede comprobar con qué bibliotecas enlaza su aplicación utilizando la herramienta Dependency Walker. Todo lo que tiene que hacer es ejecutarla de la siguiente manera:

depends <application executable>

Esto proporcionará una lista de las bibliotecas de las que depende tu aplicación y otra información.

Al examinar la compilación de lanzamiento del ejecutable Plug & Paint (plugandpaint.exe) con la herramienta depends, la herramienta enumera las siguientes dependencias inmediatas de bibliotecas ajenas al sistema:

En las DLL de los plugins aparecen exactamente las mismas dependencias.

Plugins Qt

Todas las aplicaciones Qt GUI requieren un plugin que implemente la capa Qt Platform Abstraction (QPA) en Qt. Para Windows, el nombre del plugin de plataforma es qwindows.dll. Este archivo debe estar ubicado dentro de un subdirectorio específico (por defecto, platforms) bajo su directorio de distribución. Alternativamente, es posible ajustar la ruta de búsqueda que Qt utiliza para encontrar sus plugins, como se describe a continuación.

Su aplicación también puede depender de uno o más plugins de Qt, como el plugin de soporte de impresión, el plugin de formato de imagen JPEG o un plugin de controlador SQL. Asegúrese de distribuir cualquier plugin Qt que necesite con su aplicación. De forma similar al plugin de plataforma, cada tipo de plugin debe ubicarse dentro de un subdirectorio específico (como printsupport, imageformats o sqldrivers) dentro de su directorio de distribución.

Las librerías son reubicables a menos que Qt haya sido construido con el parámetro de configuración -relocatable desactivado. Las rutas de búsqueda de los plugins de Qt son relativas a la ubicación de la biblioteca QtCore y no se requieren más pasos para asegurar que los plugins se encuentran después de instalar la aplicación en la máquina de destino.

Cómo asegurarse de que se encuentran los plugins cuando se utilizan compilaciones no reubicables

En el caso de las compilaciones no reubicables, se deben tomar medidas adicionales para garantizar que los plugins se encuentran una vez que la aplicación se ha instalado en el equipo de destino.

En este caso, la ruta de búsqueda de los plugins de Qt está codificada en la biblioteca QtCore. Por defecto, el subdirectorio de plugins de la instalación de Qt es la primera ruta de búsqueda de plugins. Sin embargo, las rutas predeterminadas como la que aparece por defecto tienen ciertas desventajas. Por ejemplo, pueden no existir en la máquina de destino. Por ello, es necesario examinar varias alternativas para asegurarse de que se encuentran los plugins de Qt:

• Usando qt.conf. Este enfoque es el recomendado si tienes ejecutables en diferentes lugares compartiendo los mismos plugins.
• Usando QApplication::addLibraryPath() o QApplication::setLibraryPaths(). Este método es el recomendado si sólo tienes un ejecutable que utilizará el plugin.
• Utilizando una utilidad de instalación de terceros para cambiar las rutas codificadas en la biblioteca QtCore.

Si agregas una ruta personalizada usando QApplication::addLibraryPath podria verse asi:

QCoreApplication::addLibraryPath("C:/customPath/plugins");

Entonces QCoreApplication::libraryPaths() devolvería algo como esto:

• C:/customPath/plugins
• C:/Qt/%VERSION%/plugins
• E:/myApplication/directory

El ejecutable buscará los plugins en estos directorios y en el mismo orden que el QStringList devuelto por QCoreApplication::libraryPaths(). La nueva ruta añadida se antepone a la de QCoreApplication::libraryPaths(), lo que significa que se buscará en ella en primer lugar. Sin embargo, si utiliza QCoreApplication::setLibraryPaths(), podrá determinar qué rutas y en qué orden se buscarán.

El documento How to Create Qt Plugins (Cómo crear plugins Qt ) describe las cuestiones a las que debes prestar atención cuando crees y despliegues plugins para aplicaciones Qt.