Qt para Linux: implementación
Esta documentación aborda cuestiones específicas relacionadas con la implementación de Qt para Linux. Mostraremos los procedimientos mediante el ejemplo de la aplicación Plug & Paint, incluida en el paquete fuente de Qt.
Debido a la proliferación de sistemas Unix (como los Unix comerciales o las distribuciones de Linux), la implementación en Unix es un tema complejo. Antes de empezar, ten en cuenta que los programas compilados para una variante de Unix probablemente no se ejecutarán en otro sistema Unix. Por ejemplo, a menos que utilices un compilador cruzado, no podrás compilar tu aplicación en Irix y distribuirla en AIX.
Bibliotecas compartidas
Nos enfrentamos a dos retos a la hora de implementar la aplicación « plugandpaint » utilizando 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
Suponemos que ya tiene instalado Qt como biblioteca compartida —que es la opción predeterminada al instalar Qt— en el directorio /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 /path/to/Qt/examples/tools/plugandpaintAhora ejecuta qmake para crear un nuevo archivo makefile para la aplicación y realiza una compilación limpia para crear el ejecutable enlazado dinámicamente:
make clean
qmake -config release
makeEsto compila la aplicación principal; lo siguiente compilará los complementos:
cd ../plugandpaint/plugins
make clean
qmake -config release
makeSi todo se ha compilado y enlazado sin errores, obtendremos un ejecutable plugandpaint y los archivos de los complementos libpnp_basictools.so y libpnp_extrafilters.so.
Creación del paquete de la aplicación
No existe una gestión de paquetes estándar en Unix, por lo que el método que presentamos a continuación es una solución genérica. Consulta la documentación de tu sistema de destino para obtener información sobre cómo crear un paquete.
Para implementar la aplicación, debemos asegurarnos de copiar las bibliotecas Qt pertinentes (correspondientes a los módulos Qt utilizados en la aplicación), el complemento de plataforma y el ejecutable en el mismo árbol de directorios. Recuerda que, si tu aplicación depende de bibliotecas específicas del compilador, estas también deben redistribuirse junto con tu aplicación. Para obtener más información, consulta la sección «Dependencias de la aplicación ».
Hablaremos de los complementos en breve, pero el principal problema con las bibliotecas compartidas es que debes asegurarte de que el enlazador dinámico encuentre las bibliotecas de Qt. A menos que se indique lo contrario, el enlazador dinámico no busca en el directorio donde reside tu aplicación. Hay muchas formas de resolver esto:
- Puedes instalar las bibliotecas de Qt en una de las rutas de bibliotecas del sistema (por ejemplo,
/usr/liben la mayoría de los sistemas). - Puedes pasar una ruta predeterminada a la opción de línea de comandos
-rpathal enlazar la aplicación. Esto indicará al enlazador dinámico que busque en este directorio al iniciar tu aplicación. - Puedes escribir un script de inicio para tu aplicación, en el que modifiques la configuración del enlazador dinámico (por ejemplo, añadiendo el directorio de tu aplicación a la variable de entorno
LD_LIBRARY_PATH.Nota: Si la aplicación se ejecuta con la opción «Establecer ID de usuario al ejecutarse» y es propiedad de root, LD_LIBRARY_PATH se ignorará en algunas plataformas. En este caso, no es posible utilizar el método de LD_LIBRARY_PATH).
La desventaja del primer método es que el usuario debe tener privilegios de superusuario. La desventaja del segundo método es que es posible que el usuario no tenga privilegios para instalar en la ruta predeterminada. En cualquier caso, los usuarios no tienen la opción de instalar en su directorio de inicio. Recomendamos utilizar el tercer método, ya que es el más flexible. Por ejemplo, un script plugandpaint.sh tendría este aspecto:
#!/bin/sh
appname=`basename $0 | sed s,\.sh$,,`
dirname=`dirname $0`
tmp="${dirname#?}"
if [ "${dirname%$tmp}" != "/" ]; then
dirname=$PWD/$dirname
fi
LD_LIBRARY_PATH=$dirname
export LD_LIBRARY_PATH
$dirname/$appname "$@"Al ejecutar este script en lugar del ejecutable, te aseguras de que el enlazador dinámico encuentre las bibliotecas de Qt. Ten en cuenta que solo tienes que cambiar el nombre del script para utilizarlo con otras aplicaciones.
A la hora de buscar complementos, la aplicación busca en un subdirectorio «plugins» dentro del directorio del ejecutable de la aplicación. O bien tienes que copiar manualmente los complementos en el directorio « plugins », o bien puedes configurar la ruta « DESTDIR » en los archivos de proyecto de los complementos:
DESTDIR = /path/to/Qt/plugandpaint/pluginsUn archivo que distribuya todas las bibliotecas Qt y todos los complementos necesarios para ejecutar la aplicación plugandpaint tendría que incluir los siguientes archivos:
| Componente | Nombre del archivo | |
|---|---|---|
| El ejecutable | plugandpaint | |
| El script para ejecutar el ejecutable | plugandpaint.sh | |
| El complemento «Basic Tools» | plugins\libpnp_basictools.so | |
| El complemento ExtraFilters | plugins\libpnp_extrafilters.so | |
| El complemento de la plataforma Qt xcb | platforms\libqxcb.so | |
| El módulo « Qt Core » | libQt6Core.so.6 | |
| El módulo « Qt GUI » | libQt6Gui.so.6 | |
| El módulo « Qt Widgets » | libQt6Widgets.so.6 | |
En la mayoría de los sistemas, la extensión para las bibliotecas compartidas es .so. Una excepción destacada es HP-UX, que utiliza .sl.
Recuerda que, si tu aplicación depende de bibliotecas específicas del compilador, estas deben seguir redistribuirse junto con tu aplicación. Para obtener más información, consulta la sección «Dependencias de la aplicación ».
Para comprobar que la aplicación ya se puede implementar correctamente, puede extraer este archivo en un equipo que no tenga Qt ni ningún compilador instalado e intentar ejecutarlo, es decir, ejecutar el script plugandpaint.sh.
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 « QApplication::addLibraryPath()» o « QApplication::setLibraryPaths()».
QCoreApplication::addLibraryPath("/some/other/path");Enlazado estático
La vinculación estática suele ser la forma más segura y sencilla de distribuir una aplicación en Unix, ya que le libera de la tarea de distribuir las bibliotecas de Qt y de asegurarse de que se encuentren en la ruta de búsqueda predeterminada para bibliotecas en el sistema de destino.
Compilación estática de Qt
Para utilizar este método, debe comenzar por compilar una versión _estática_ de las bibliotecas de Qt. Siga los pasos descritos en «Qt para Linux: compilación a partir del código fuente», pero recuerde añadir el argumento « -static » a `configure`:
mkdir -p ~/dev/qt-build
cd ~/dev/qt-build
/tmp/qt-everywhere-src-6.12.0/configure -staticEnlazar la aplicación a la versión estática de Qt
Una vez compilado Qt de forma estática, el siguiente paso es regenerar el archivo makefile y volver a compilar la aplicación. En primer lugar, debemos ir al directorio que contiene la aplicación:
cd /path/to/Qt/examples/widgets/tools/plugandpaint/appAhora ejecuta qmake para crear un nuevo archivo makefile para la aplicación y realiza una compilación limpia para crear el ejecutable enlazado de forma estática:
make clean
PATH=/path/to/Qt/bin:$PATH
export PATH
qmake -config release
makeProbablemente querrás vincularla con las bibliotecas de la versión de lanzamiento, y puedes especificarlo al ejecutar ` qmake`. Ten en cuenta que debemos establecer la ruta al Qt estático que acabamos de compilar.
Para comprobar que la aplicación realmente se vincula de forma estática con Qt, ejecuta la herramienta ` ldd ` (disponible en la mayoría de sistemas Unix):
ldd ./applicationComprueba que las bibliotecas de Qt no aparezcan mencionadas en la salida.
Ahora, siempre que todo se haya compilado y enlazado sin errores, deberíamos tener un archivo ` plugandpaint ` listo para su implementación. Una forma sencilla de comprobar que la aplicación realmente se puede ejecutar de forma independiente es copiarla en un equipo que no tenga instalado Qt ni ninguna aplicación de Qt, y ejecutarla en ese equipo.
Recuerda que, si tu aplicación depende de bibliotecas específicas del compilador, estas deben redistribuirse junto con tu aplicación. Para obtener más información, consulta la sección «Dependencias de la aplicación ».
El ejemplo «Plug & Paint » consta de varios componentes: la aplicación principal («Plug & Paint») y los complementos «Basic Tools » y «Extra Filters ». Dado que no podemos implementar los complementos mediante el método de enlace estático, el ejecutable que hemos preparado hasta ahora está incompleto. La aplicación se ejecutará, pero la funcionalidad estará desactivada debido a la falta de complementos. Para implementar aplicaciones basadas en complementos, debemos utilizar el enfoque de bibliotecas compartidas.
Dependencias de la aplicación
Bibliotecas adicionales
Para averiguar de qué bibliotecas depende su aplicación, ejecute la herramienta « ldd » (disponible en la mayoría de sistemas Unix):
ldd ./applicationEsto mostrará una lista de todas las dependencias de bibliotecas compartidas de tu aplicación. Dependiendo de la configuración, estas bibliotecas deben redistribuirse junto con tu aplicación. En particular, la biblioteca estándar de C++ debe redistribuirse si estás compilando tu aplicación con un compilador que es binariamente incompatible con el compilador del sistema. Siempre que sea posible, la solución más segura es vincular estas bibliotecas de forma estática.
Probablemente te interese vincular dinámicamente con las bibliotecas X11 habituales, ya que algunas implementaciones intentarán abrir otras bibliotecas compartidas con ` dlopen()`, y si esto falla, la biblioteca X11 podría provocar que tu aplicación se cuelgue.
También cabe mencionar que Qt buscará determinadas extensiones de X11, como Xinerama y Xrandr, y es posible que las incorpore, incluidas todas las bibliotecas a las que están enlazadas. Si no puedes garantizar la presencia de una extensión concreta, lo más seguro es desactivarla al configurar Qt (por ejemplo, ./configure -no-xrandr).
FontConfig y FreeType son otros ejemplos de bibliotecas que no siempre están disponibles o que no siempre son compatibles a nivel binario. Por extraño que pueda parecer, algunos proveedores de software han tenido éxito al compilar su software en máquinas muy antiguas y han tenido mucho cuidado de no actualizar ninguno de los programas que se ejecutan en ellas.
Al vincular tu aplicación con las bibliotecas estáticas de Qt, debes vincularla explícitamente con las bibliotecas dependientes mencionadas anteriormente. Para ello, añádelas a la variable LIBS en el archivo de tu proyecto.
Complementos de Qt
Todas las aplicaciones « Qt GUI » requieren un complemento que implemente la capa de abstracción de la plataforma Qt (QPA). Para Linux/X11, el nombre del complemento de plataforma es libqxcb.so. 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 más complementos de Qt, como el complemento del formato de imagen JPEG o un complemento de controlador SQL. Asegúrate de distribuir junto con tu aplicación cualquier complemento de Qt que necesites. Al igual que el complemento de plataforma, cada tipo de complemento debe estar ubicado en un subdirectorio específico (como imageformats o sqldrivers) dentro de tu directorio de distribución.
La ruta de búsqueda de los complementos de Qt (así como algunas otras rutas) está codificada de forma fija en la biblioteca QtCore. Por defecto, la primera ruta de búsqueda de complementos estará codificada como /path/to/Qt/plugins. Como se ha mencionado anteriormente, el uso de rutas predeterminadas presenta ciertas desventajas, por lo que debes examinar varias alternativas para asegurarte de que se encuentren los complementos de Qt:
- Utilizar `
qt.conf`. Este es el método recomendado, ya que ofrece la mayor flexibilidad. - Utilizar ` QApplication::addLibraryPath()` o ` QApplication::setLibraryPaths()`.
- Utilizar una utilidad de instalación de terceros o el gestor de paquetes del sistema de destino para modificar las rutas fijas de la biblioteca ` QtCore `.
El documento «Cómo crear complementos de Qt » describe los aspectos a los que hay que prestar atención al compilar e implementar complementos para aplicaciones Qt.
Guía paso a paso: Crear un paquete DEB
En esta sección se describe cómo crear un paquete DEB para tu aplicación Qt en Linux utilizando la API de implementación de CMake disponible en Qt 6.5 o versiones posteriores. No existe una herramienta específica de linuxdeployqt. La solución actual se basa únicamente en la funcionalidad integrada de CMake.
Configuración del proyecto de ejemplo
Empieza con un proyecto sencillo de CMake:
cmake_minimum_required(VERSION 3.22)
project(MyApp)
find_package(Qt6 REQUIRED COMPONENTS Widgets)
qt_standard_project_setup()
qt_add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE Qt::Widgets)Paso 1: Preparar la instalación
Añade comandos para instalar la aplicación y generar un script de implementación que cree un directorio autónomo:
# Install the executable to "${CMAKE_INSTALL_PREFIX}/bin".
install(TARGETS MyApp
BUNDLE DESTINATION .
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)
# Generate the deployment script for MyApp.
qt_generate_deploy_app_script(
TARGET MyApp
FILENAME_VARIABLE deploy_script
NO_UNSUPPORTED_PLATFORM_ERROR
)
# Run the deployment script during installation (on "cmake --install").
install(SCRIPT ${deploy_script})Compila e instala el proyecto:
qt-cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/tmp/my-application ..
cmake --build .
cmake --install .El script de implementación:
- Crea un archivo qt.conf junto al ejecutable que contiene información sobre la estructura del directorio. Esto es necesario en tiempo de ejecución para localizar los complementos y los recursos. Consulta la documentación de qt.conf para obtener más detalles.
- Analiza el ejecutable y los complementos de Qt utilizados mediante la función integrada de CMake (GET_RUNTIME_DEPENDENCIES) para determinar qué bibliotecas de Qt hay que implementar.
- Instala los complementos y las bibliotecas de Qt necesarios.
Ahora se puede copiar el directorio de instalación a otro equipo y la aplicación debería seguir funcionando.
Paso 2: Crear el paquete DEB
Tras la instalación, empaqueta el directorio utilizando CPack. Añade lo siguiente a tu proyecto de CMake:
set(CPACK_PACKAGE_NAME my-app)
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "My amazing application")
set(CPACK_PACKAGE_VENDOR "My Company")
set(CPACK_PACKAGE_INSTALL_DIRECTORY ${CPACK_PACKAGE_NAME})
set(CPACK_VERBATIM_VARIABLES ON)
set(CPACK_PACKAGING_INSTALL_PREFIX "/opt/myapp")
set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Package Maintainer <maintainer@example.com>")
set(CPACK_DEBIAN_PACKAGE_DEPENDS libc6 libstdc++6 libgcc-s1)
include(CPack)Reconfigura el proyecto, ve al directorio de compilación (debe contener el archivo « CPackConfig.cmake ») y ejecuta CPack para generar el paquete DEB:
cpack -G DEBPara examinar el contenido del paquete:
dpkg -c my_app-1.0-Linux.debPara instalar el paquete:
sudo dpkg -i my_app-1.0-Linux.deb© 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.