En esta página

Qt para Windows: implementación

Esta documentación describe el proceso de implementación para Windows. A lo largo del documento hacemos referencia a la aplicación de ejemplo «Plug & Paint» para ilustrar el proceso de implementación.

Nota: Añade tu directorio de compilación de Qt a la lista de directorios excluidos de cualquier aplicación antivirus que se ejecute en tu sistema.

La herramienta de implementación de Windows

La forma recomendada y más sencilla de implementar una aplicación Qt en Windows es utilizar la herramienta windeployqt, que recopila automáticamente todas las bibliotecas Qt, los complementos, los módulos Qml y las dependencias de tiempo de ejecución necesarios en una carpeta de implementación lista para ejecutarse.

Crea un árbol de instalación para aplicaciones de escritorio de Windows, que se puede incluir fácilmente en un paquete de instalación.

Nota: Es posible quela aplicación requiera bibliotecas adicionales de terceros (por ejemplo, bibliotecas de bases de datos), que windeployqt no tiene en cuenta.

Configuración del entorno de compilación

Si has instalado Qt a través de Qt Online Installer, debes configurar el entorno de compilación antes de ejecutar windeployqt. Para ello, ejecuta:

<qt-installation-folder>/bin/qtenv2.bat

Uso

windeployqt se encuentra en <qt-installation-folder>/bin/; toma como argumento un archivo .exe o un directorio que contenga un archivo .exe, y analiza el ejecutable en busca de dependencias.

Ten en cuenta lo siguiente:

  • Si se pasa un directorio con el argumento --qmldir, windeployqt utiliza la herramienta qmlimportscanner para analizar los archivos QML del directorio en busca de dependencias de importación de QML. A continuación, las dependencias identificadas se copian al directorio del ejecutable.
  • Si Qt se compiló con el modificador de configuración -relocatable desactivado, windeployqt sustituye las rutas locales fijas de Qt6Core.dll por rutas relativas.
  • En el caso de las aplicaciones de escritorio para Windows, windeployqt copia de forma predeterminada los archivos de tiempo de ejecución del compilador necesarios, a menos que se especifique la opción « --no-compiler-runtime ». Para las compilaciones de versión final que utilizan Microsoft Visual C++, esto significa que la herramienta espera que el instalador de la aplicación incluya los paquetes redistribucibles oficiales de Visual C++.

    Si el paquete redistribuible no está disponible, windeployqt puede recurrir a las DLL de tiempo de ejecución compartidas del compilador que se encuentren en el equipo del desarrollador. Estas DLL individuales no están destinadas ni autorizadas para su redistribución, y no deben distribuirse directamente. Solo debe utilizarse el instalador oficial de Microsoft Redistributable para la implementación en los sistemas de los usuarios finales.

Casos de uso habituales

Implementación de una aplicación estándar de « Qt Widgets »
windeployqt.exe .\build\MyApp.exe
Implementación de una aplicación « Qt Quick » con fuentes QML
windeployqt.exe --qmldir .\qml .\build\MyApp.exe
Generación de un manifiesto appx para la creación del paquete

Utiliza esta opción cuando prepares tu aplicación para empaquetarla como un paquete appx de Windows.

La opción « --appx » crea un archivo « AppxManifest.xml », y « --appx-certificate » especifica el certificado que se va a incrustar en el manifiesto.

windeployqt.exe --appx --appx-certificate MyCompany.cer .\build\MyApp.exe
Realización de una prueba sin cambios

Una simulación simula la implementación sin copiar ni actualizar nada.

windeployqt.exe --dry-run MyApp.exe

Opciones

General
OpciónDescripción
-?, -h, --helpMostrar ayuda sobre las opciones de la línea de comandos.
--help-allMostrar la ayuda completa, incluidas las opciones genéricas de Qt.
-v, --versionMostrar información sobre la versión.
Control de entrada y salida
OpciónDescripción
--dir <path>Utiliza este directorio como destino de implementación en lugar del directorio de binarios.
--libdir <path>Copia las bibliotecas de Qt en este directorio.
--plugindir <path>Copia los complementos de Qt en este directorio.
--qml-deploy-dir <path>Copia los archivos QML en este directorio.
--translationdir <path>Copia las traducciones en este directorio.
Resolución de la ruta de Qt
OpciónDescripción
--qtpaths <path>Utiliza un archivo « qtpaths.exe » específico para resolver las Qt Locations.
Configuración de compilación
OpciónDescripción
--debugSe asumen binarios de depuración.
--releaseSuponer que se utilizan binarios de versión final.
--pdbImplementar archivos « .pdb » de MSVC.
Comportamiento de la implementación
OpciónDescripción
--forceSobrescribir los archivos existentes.
--dry-runSimular la implementación sin copiar ni actualizar nada.
--ignore-library-errorsContinuar aunque falten algunas bibliotecas.
--jsonMostrar la información de implementación en formato JSON.
--appxCrea un archivo ` AppxManifest.xml ` para la Tienda de Windows.
--nopatchqtOmitir la aplicación de parches a la biblioteca « QtCore ».
--no-librariesOmitir la implementación de la biblioteca.
--verbose <level>Nivel de detalle (0–2).
Complementos
OpciónDescripción
--no-pluginsOmitir la implementación del complemento.
--include-soft-pluginsIncluir todos los complementos relevantes en función de las dependencias no estrictas.
--skip-plugin-types <types>Una lista separada por comas de categorías específicas de complementos que no se deben añadir a la implementación.
--add-plugin-types <types>Una lista separada por comas de tipos de complementos que se deben añadir a la implementación.
--include-plugins <plugins>Una lista separada por comas de complementos específicos (por nombre) que se deben añadir a la implementación.
--exclude-plugins <plugins>Una lista separada por comas de complementos específicos (por nombre) que no se deben añadir a la implementación.
QML
OpciónDescripción
--qmldir <directory>Busca importaciones de QML a partir de este directorio.
--qmlimporttimeout <ms>Establece el tiempo de espera, en milisegundos, para la ejecución de « qmlimportscanner ». El valor por defecto es 30 000 ms. Aumenta este valor si « qmlimportscanner » agota el tiempo de espera en bases de código QML grandes o complejas.
--qmlimport <directory>Ruta de búsqueda adicional para módulos QML.
--no-quick-importOmitir la implementación de las importaciones de Qt Quick.
Traducciones
OpciónDescripción
--translations <languages>Una lista de idiomas, separados por comas, para los que se van a implementar las traducciones.
--no-translationsOmitir traducciones.
Componentes del sistema y de tiempo de ejecución
OpciónDescripción
--no-system-d3d-compilerOmitir el compilador D3D del sistema.
--no-system-dxc-compilerOmitir el compilador DXC del sistema.
--compiler-runtimeImplementar el compilador en tiempo de ejecución (solo para escritorio).
--no-compiler-runtimeNo implementar el compilador en tiempo de ejecución (solo para escritorio).
--no-opengl-swOmitir el renderizador OpenGL de software.
--no-ffmpegOmitir las bibliotecas FFmpeg.
--force-opensslImplementar el complemento OpenSSL, pero ignorar la dependencia de la biblioteca.
--openssl-root <directory>Directorio que contiene las bibliotecas de OpenSSL.
--appx-certificate <.cer file>Ruta al certificado appx para firmar el paquete appx.
Lista de archivos resultante
OpciónDescripción
--list <option>Imprime solo los nombres de los archivos en la salida estándar.

Opciones:

  • source: ruta absoluta de los archivos de origen.
  • target: ruta absoluta de los archivos de destino.
  • relative: rutas de los archivos de destino, relativas al directorio de destino.
  • mapping: muestra la fuente y el destino relativo, adecuado para su uso dentro de un archivo de asignación Appx.

Enlazado estático

Para compilar aplicaciones estáticas, compila Qt de forma estática configurándolo con -static:

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

Si más adelante necesitas reconfigurar y volver a compilar Qt desde la misma ubicación, asegúrate de eliminar todo rastro de la configuración anterior.

Enlazar la aplicación con la versión estática de Qt

A modo de ejemplo, en esta sección se compilará el ejemplo «Plug & Paint» utilizando un Qt compilado de forma estática.

Una vez finalizada la compilación de Qt, compila la aplicación «Plug & Paint ». En esta sección se da por hecho que la versión estática de Qt se ha instalado en C:\path\to \static \Qt . En primer lugar, debemos acceder al directorio que contiene la aplicación:

cd examples\tools\plugandpaint

Ahora, creamos un directorio de compilación y ejecutamos 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 querrás enlazar con las bibliotecas de versión final, y lo hemos especificado mediante la variable ` CMAKE_BUILD_TYPE `. Ahora, siempre que todo se haya compilado y enlazado sin errores, deberíamos tener un archivo ` plugandpaint.exe ` listo para su implementación. Para comprobar que la aplicación cuenta con las bibliotecas necesarias, copia el ejecutable en un equipo que no tenga instalado Qt ni ninguna aplicación de Qt, y ejecútalo en ese equipo.

Recuerda que, si tu aplicación depende de bibliotecas específicas del compilador, estas deben redistribuirse junto con tu aplicación. Puedes comprobar con qué bibliotecas se vincula tu aplicación utilizando la herramienta depends. Para obtener más información, consulta la sección «Dependencias de la aplicación ».

Dado que no podemos implementar complementos utilizando el método de enlace estático, la aplicación que hemos preparado está incompleta. Se ejecutará, pero la funcionalidad estará desactivada debido a la falta de complementos. Para implementar aplicaciones basadas en complementos, debemos utilizar el método de bibliotecas compartidas.

Bibliotecas compartidas

Nos enfrentamos a dos retos a la hora de implementar la aplicación « plugandpaint » mediante el enfoque de bibliotecas compartidas: el tiempo de ejecución de Qt debe redistribuirse correctamente junto con el ejecutable de la aplicación, y los complementos deben instalarse en la ubicación correcta del sistema de destino para que la aplicación pueda encontrarlos.

Compilación de Qt como biblioteca compartida

Para este ejemplo, suponemos que Qt está instalado como biblioteca compartida —que es la configuración predeterminada al instalar Qt— en el directorio C:\path\to \Qt .

Enlazando la aplicación con Qt como biblioteca compartida

Una vez comprobado que Qt se ha compilado como biblioteca compartida, podemos compilar la aplicación plugandpaint. En primer lugar, debemos acceder al directorio que contiene la aplicación:

cd examples\tools\plugandpaint

Ahora crea un directorio de compilación específico y ejecuta qt-cmake para generar los archivos del sistema de compilación:

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

Si todo se ha compilado y enlazado sin errores, obtendremos el ejecutable plugandpaint.exe y los archivos de los complementos pnp_basictools.dll y pnp_extrafilters.dll.

Creación del paquete de la aplicación

Para implementar la aplicación, debemos asegurarnos de copiar las DLL de Qt pertinentes (correspondientes a los módulos de Qt utilizados en la aplicación) y el complemento para la plataforma Windows, qwindows.dll, así como el ejecutable, en el mismo árbol de directorios, dentro del subdirectorio release.

A diferencia de los complementos de usuario, los complementos de Qt deben colocarse en subdirectorios que coincidan con el tipo de complemento. La ubicación correcta para el complemento de plataforma es un subdirectorio denominado platforms. La sección «Complementos de Qt» contiene información adicional sobre los complementos y cómo los busca Qt.

Si se utiliza OpenGL dinámico, es posible que también desee incluir la biblioteca necesaria para OpenGL basado en software, siempre que la aplicación sea compatible con ella.

Si Qt se ha configurado para enlazarse con ICU u OpenSSL, es posible que también sea necesario añadir las DLL correspondientes a la carpeta release. Sin embargo, los paquetes binarios de Qt para Windows no lo requieren. Si ha configurado Qt con una versión específica de ICU u OpenSSL, windeployqt debería detectar las DLL de las bibliotecas correspondientes si se encuentran en el directorio « [bin] » de Qt. Para obtener más detalles, consulte también «Bibliotecas de terceros».

Recuerda que, si tu aplicación depende de bibliotecas específicas del compilador, estas deben redistribuirse junto con tu aplicación. Puedes comprobar a qué bibliotecas está vinculada tu aplicación utilizando la herramienta depends. Para obtener más información, consulta la sección «Dependencias de la aplicación ».

Hablaremos de los complementos en breve, pero primero comprobaremos que la aplicación funcione en un entorno de producción: Copia el ejecutable y las DLL de Qt en un equipo que no tenga instalado Qt ni ninguna aplicación de Qt, o, si quieres realizar la prueba en el equipo de compilación, asegúrate de que dicho equipo no tenga Qt en su entorno.

Si la aplicación se inicia sin problemas, significa que hemos creado con éxito una versión enlazada dinámicamente de la aplicación « plugandpaint ». Sin embargo, la funcionalidad de la aplicación seguirá sin estar disponible, ya que aún no hemos desplegado los complementos asociados.

Los complementos funcionan de forma diferente a las DLL normales, por lo que no podemos limitarnos a copiarlos en el mismo directorio que el ejecutable de nuestra aplicación, como hicimos con las DLL de Qt. Al buscar complementos, la aplicación busca en un subdirectorio llamado « plugins » dentro del directorio del ejecutable de la aplicación.

Por lo tanto, para que nuestra aplicación pueda utilizar los complementos, debemos crear el subdirectorio « plugins » y copiar en él los DLL pertinentes:

plugins\pnp_basictools.dll
plugins\pnp_extrafilters.dll

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

ComponenteNombre del archivo
El ejecutableplugandpaint.exe
El complemento «Basic Tools»plugins\pnp_basictools.dll
El complemento ExtraFiltersplugins\pnp_extrafilters.dll
El complemento de la plataforma Qt para Windowsplatforms\qwindows.dll
El complemento de estilo Qt para Windows Vistastyles\qwindowsvistastyle.dll
El módulo « Qt Core »Qt6Core.dll
El módulo « Qt GUI »Qt6Gui.dll
El módulo « Qt Widgets »Qt6Widgets.dll

Es posible que se necesiten otros complementos en función 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 que se utilice Visual Studio 17 (2022)):

ComponenteNombre del archivo
El tiempo de ejecución de Cvcruntime140.dll
El tiempo de ejecución de C++msvcp170.dll

Si se ha utilizado OpenGL dinámico, el archivo también puede contener:

ComponenteNombre del archivo
Biblioteca del renderizador de software de OpenGLopengl32sw.dll

Por último, si Qt se ha configurado para utilizar ICU, el archivo debe contener:

Nombre del archivo
icudtXX.dllicuinXX.dllicuucXX.dll

Para comprobar que la aplicación ya se puede implementar correctamente, puedes extraer este archivo en un equipo que no tenga Qt ni ningún compilador instalado e intentar ejecutarlo.

Una alternativa a colocar los complementos en el subdirectorio «plugins» es añadir una ruta de búsqueda personalizada al iniciar la aplicación mediante QCoreApplication::addLibraryPath() o QCoreApplication::setLibraryPaths().

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

Una de las ventajas de utilizar complementos es que se pueden poner fácilmente a disposición de toda una familia de aplicaciones.

A menudo resulta más cómodo 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 buscará los complementos en ella, además de buscar en el subdirectorio ` plugins ` del propio directorio de la aplicación. Se pueden añadir tantas rutas adicionales como se desee.

Generación del manifiesto de la aplicación de Windows

Al compilar en Windows, Qt genera e incorpora automáticamente un manifiesto de aplicación para los objetivos ejecutables.

El manifiesto generado:

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

Si ya se ha proporcionado un archivo .manifest personalizado en las fuentes de destino, Qt no lo anula.

Al declarar la compatibilidad con Windows 10/11, se habilita el comportamiento moderno de Windows, lo que incluye:

  • Activación del comportamiento moderno del gestor de ventanas
  • Compatibilidad con la función « WS_EX_LAYERED » en ventanas secundarias (compatible desde Windows 8, pero limitada por la detección de compatibilidad)
  • Compatibilidad con rutas largas (> 260 caracteres)
  • Configuración explícita del nivel de ejecución

Sin una declaración de compatibilidad adecuada, Windows podría aplicar el 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 de Windows de cuatro partes

Por defecto, el identificador es:

com.yourcompany.<target_name>

Se puede anular para cada destino utilizando la propiedad « QT_WINDOWS_APP_PROJECT_IDENTIFIER »:

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

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

Major.Minor.Build.Revision

Cada segmento debe ser un número entero comprendido entre 0 y 65 535.

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

  • Si falta → se establece por defecto en 1.0.0.0
  • Menos de cuatro segmentos → se rellenan con ceros
  • Más de cuatro segmentos → se trunca
  • Valores < 0 → se limitan a 0
  • Valores > 65535 → se limitan 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 indica que es compatible con Windows 10 y Windows 11.

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

{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a} El GUID corresponde a 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.

Reconocimiento de rutas largas

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

Permite utilizar rutas de archivo de más de 260 caracteres, siempre que el sistema operativo lo admita.

Nivel de ejecución

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

El nivel predeterminado es « asInvoker ».

Para configurar el nivel de ejecución, utiliza 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 ».

Cómo 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 de Windows que utiliza el manifiesto generado automáticamente con un identificador y un 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

Al implementar 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 respecto a ensamblados «side-by-side», 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 diferentes a las de la aplicación que la utiliza, es necesario incrustar el archivo de manifiesto en el binario de la DLL. Para incrustar manifiestos, se dispone de las siguientes opciones de CONFIG:

embed_manifest_dll
embed_manifest_exe

Ambas opciones están activadas de forma predeterminada. Para desactivar « embed_manifest_exe », añade

CONFIG -= embed_manifest_exe

a tu archivo .pro.

Puedes encontrar más información sobre los archivos de manifiesto y los ensamblados «side-by-side» en la página de documentación sobre ensamblados «side-by-side».

La forma correcta de incluir las bibliotecas de tiempo de ejecución en tu aplicación es asegurarte 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 correspondiente del paquete redistribuible de Visual C++ (VCRedist) con su aplicación y asegurarse de que se ejecute cuando el usuario instale su aplicación.

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

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

Nota: La aplicación que distribuyas debe compilarse con exactamente la misma versión del compilador y con la misma versión del tiempo de ejecución de C. Esto evita errores de implementación causados por versiones diferentes de las bibliotecas de tiempo de ejecución de C.

Dependencias de la aplicación

Bibliotecas adicionales

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

Puedes comprobar a qué bibliotecas está vinculada tu aplicación utilizando la herramienta Dependency Walker. Solo tienes que ejecutarla de la siguiente manera:

depends <application executable>

Esto te proporcionará una lista de las bibliotecas de las que depende tu aplicación, así como otra información.

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

QtVisual Studio 17 (2022)Mingw-w64
  • QT6CORE.DLL: el tiempo de ejecución de QtCore
  • QT6GUI.DLL - El tiempo de ejecución de « QtGui »
  • QT6WIDGETS.DLL - El tiempo de ejecución de « QtWidgets »
  • VCCORLIB140.DLL, VCRUNTIME140D.DLL: el tiempo de ejecución de C
  • MSVCP140.DLL: el tiempo de ejecución de C++
  • LIBWINPTHREAD-1.DLL
  • LIBGCC_S_SEH-1.DLL
  • LIBSTDC++-6.DLL

Al examinar las DLL de los complementos, aparecen exactamente las mismas dependencias.

Complementos de Qt

Todas las aplicaciones de Qt GUI requieren un complemento que implemente la capa Qt Platform Abstraction (QPA) en Qt. Para Windows, el nombre del complemento de plataforma es qwindows.dll. Este archivo debe encontrarse en un subdirectorio específico (por defecto, platforms) dentro del directorio de tu distribución. Como alternativa, es posible ajustar la ruta de búsqueda que utiliza Qt para encontrar sus complementos, tal y como se describe a continuación.

Tu aplicación también puede depender de uno o varios complementos de Qt, como el complemento de Qt Print Support, el complemento para el formato de imagen JPEG o un complemento de controlador SQL. Asegúrate de distribuir cualquier complemento de Qt que necesites junto con tu aplicación. Al igual que el complemento de plataforma, cada tipo de complemento debe estar ubicado en un subdirectorio específico (como printsupport, imageformats o sqldrivers) dentro de tu directorio de distribución.

Las bibliotecas son reubicables, a menos que Qt se haya compilado con la opción de configuración -relocatable desactivada. Las rutas de búsqueda de los complementos de Qt son relativas a la ubicación de la biblioteca QtCore y no se requieren pasos adicionales para garantizar que se encuentren los complementos tras instalar la aplicación en el equipo de destino.

Asegurarse de que se encuentren los complementos cuando se utilizan compilaciones no reubicables

En el caso de las compilaciones no reubicables, es necesario seguir unos pasos adicionales para garantizar que se encuentren los complementos una vez instalada la aplicación en el equipo de destino.

En este caso, la ruta de búsqueda de los complementos de Qt está codificada de forma fija en la biblioteca « QtCore ». Por defecto, el subdirectorio «plugins» de la instalación de Qt es la primera ruta de búsqueda de complementos. Sin embargo, las rutas predeterminadas, como la por defecto, presentan ciertas desventajas. Por ejemplo, es posible que no existan en el equipo de destino. Por ese motivo, es necesario examinar diversas alternativas para asegurarse de que se encuentren los complementos de Qt:

  • Utilizar ` qt.conf `. Este enfoque es el recomendado si tienes ejecutables en diferentes ubicaciones que comparten los mismos complementos.
  • Utilizar ` QApplication::addLibraryPath()` o ` QApplication::setLibraryPaths()`. Este enfoque se recomienda si solo se dispone de un ejecutable que vaya a utilizar el complemento.
  • Utilizar una utilidad de instalación de terceros para modificar las rutas fijas en la biblioteca ` QtCore `.

Si añades una ruta personalizada mediante QApplication::addLibraryPath, podría tener este aspecto:

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 complementos en estos directorios y en el mismo orden que el ` QStringList ` devuelto por ` QCoreApplication::libraryPaths()`. La ruta recién añadida se antepone a la de ` QCoreApplication::libraryPaths()`, lo que significa que se buscará en ella en primer lugar. Sin embargo, si utilizas ` QCoreApplication::setLibraryPaths()`, podrás determinar qué rutas y en qué orden se buscarán.

El documento «Cómo crear complementos de Qt » describe los aspectos a los que hay que prestar atención a la hora de compilar e implementar complementos para aplicaciones Qt.

© 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.