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.batUso
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
-relocatabledesactivado, windeployqt sustituye las rutas locales fijas deQt6Core.dllpor 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.exeImplementación de una aplicación « Qt Quick » con fuentes QML
windeployqt.exe --qmldir .\qml .\build\MyApp.exeGeneració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.exeRealización de una prueba sin cambios
Una simulación simula la implementación sin copiar ni actualizar nada.
windeployqt.exe --dry-run MyApp.exeOpciones
General
| Opción | Descripción |
|---|---|
-?, -h, --help | Mostrar ayuda sobre las opciones de la línea de comandos. |
--help-all | Mostrar la ayuda completa, incluidas las opciones genéricas de Qt. |
-v, --version | Mostrar información sobre la versión. |
Control de entrada y salida
| Opción | Descripció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ón | Descripción |
|---|---|
--qtpaths <path> | Utiliza un archivo « qtpaths.exe » específico para resolver las Qt Locations. |
Configuración de compilación
| Opción | Descripción |
|---|---|
--debug | Se asumen binarios de depuración. |
--release | Suponer que se utilizan binarios de versión final. |
--pdb | Implementar archivos « .pdb » de MSVC. |
Comportamiento de la implementación
| Opción | Descripción |
|---|---|
--force | Sobrescribir los archivos existentes. |
--dry-run | Simular la implementación sin copiar ni actualizar nada. |
--ignore-library-errors | Continuar aunque falten algunas bibliotecas. |
--json | Mostrar la información de implementación en formato JSON. |
--appx | Crea un archivo ` AppxManifest.xml ` para la Tienda de Windows. |
--nopatchqt | Omitir la aplicación de parches a la biblioteca « QtCore ». |
--no-libraries | Omitir la implementación de la biblioteca. |
--verbose <level> | Nivel de detalle (0–2). |
Complementos
| Opción | Descripción |
|---|---|
--no-plugins | Omitir la implementación del complemento. |
--include-soft-plugins | Incluir 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ón | Descripció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-import | Omitir la implementación de las importaciones de Qt Quick. |
Traducciones
| Opción | Descripción |
|---|---|
--translations <languages> | Una lista de idiomas, separados por comas, para los que se van a implementar las traducciones. |
--no-translations | Omitir traducciones. |
Componentes del sistema y de tiempo de ejecución
| Opción | Descripción |
|---|---|
--no-system-d3d-compiler | Omitir el compilador D3D del sistema. |
--no-system-dxc-compiler | Omitir el compilador DXC del sistema. |
--compiler-runtime | Implementar el compilador en tiempo de ejecución (solo para escritorio). |
--no-compiler-runtime | No implementar el compilador en tiempo de ejecución (solo para escritorio). |
--no-opengl-sw | Omitir el renderizador OpenGL de software. |
--no-ffmpeg | Omitir las bibliotecas FFmpeg. |
--force-openssl | Implementar 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ón | Descripción |
|---|---|
--list <option> | Imprime solo los nombres de los archivos en la salida estándar. Opciones:
|
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\plugandpaintAhora, 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
ninjaProbablemente 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\plugandpaintAhora 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
ninjaSi 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.dllUn 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:
| Componente | Nombre del archivo | |
|---|---|---|
| El ejecutable | plugandpaint.exe | |
| El complemento «Basic Tools» | plugins\pnp_basictools.dll | |
| El complemento ExtraFilters | plugins\pnp_extrafilters.dll | |
| El complemento de la plataforma Qt para Windows | platforms\qwindows.dll | |
| El complemento de estilo Qt para Windows Vista | styles\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)):
| Componente | Nombre del archivo | |
|---|---|---|
| El tiempo de ejecución de C | vcruntime140.dll | |
| El tiempo de ejecución de C++ | msvcp170.dll | |
Si se ha utilizado OpenGL dinámico, el archivo también puede contener:
| Componente | Nombre del archivo | |
|---|---|---|
| Biblioteca del renderizador de software de OpenGL | opengl32sw.dll | |
Por último, si Qt se ha configurado para utilizar ICU, el archivo debe contener:
| Nombre del archivo | ||
|---|---|---|
| icudtXX.dll | icuinXX.dll | icuucXX.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 proyectoversion— 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.RevisionCada 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.0Compatibilidad 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)highestAvailablerequireAdministrator
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.0Archivos 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_exeAmbas opciones están activadas de forma predeterminada. Para desactivar « embed_manifest_exe », añade
CONFIG -= embed_manifest_exea 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:
| Qt | Visual Studio 17 (2022) | Mingw-w64 |
|---|---|---|
|
|
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/pluginsC:/Qt/%VERSION%/pluginsE:/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.