Qt para Linux - Despliegue

Esta documentación trata temas específicos de la implementación de Qt para Linux. Demostraremos los procedimientos en términos de despliegue de la aplicación de ejemplo Plug & Paint que viene con el paquete fuente de Qt.

Debido a la proliferación de sistemas Unix (como Unix comerciales o distribuciones de Linux), el despliegue en Unix es un tema complejo. Antes de empezar, ten en cuenta que los programas compilados para un tipo de Unix probablemente no se ejecutarán en un sistema Unix diferente. Por ejemplo, a menos que utilice un compilador cruzado, no puede compilar su aplicación en Irix y distribuirla en AIX.

Bibliotecas compartidas

Tenemos dos desafíos al desplegar la aplicación plugandpaint utilizando el enfoque de bibliotecas compartidas: El tiempo de ejecución de 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

Asumimos que ya has instalado Qt como una librería compartida, que es el valor por defecto al instalar Qt, en el directorio /path/to/Qt.

Enlazando la aplicación a Qt como librería compartida

Después de asegurarnos de que Qt está construido como una librería compartida, podemos construir la aplicación plugandpaint. Primero, debemos ir al directorio que contiene la aplicación:

cd /path/to/Qt/examples/tools/plugandpaint

Ahora ejecuta qmake para crear un nuevo makefile para la aplicación, y haz un clean build para crear el ejecutable enlazado dinámicamente:

make clean
qmake -config release
make

Esto construye el núcleo de la aplicación, lo siguiente construirá los plugins:

cd ../plugandpaint/plugins
make clean
qmake -config release
make

Si todo compila y enlaza sin errores, obtendremos un ejecutable plugandpaint y los archivos plugin 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. Consulte la documentación de su sistema de destino para obtener información sobre cómo crear un paquete.

Para desplegar la aplicación, debemos asegurarnos de copiar las librerías Qt relevantes (correspondientes a los módulos Qt utilizados en la aplicación), el plugin de plataforma y el ejecutable en el mismo árbol de directorios. Recuerda que si tu aplicación depende de librerías específicas del compilador, éstas también deben ser redistribuidas junto con tu aplicación. Para más información, consulta la sección Dependencias de la aplicación.

Cubriremos los plugins en breve, pero el principal problema con las librerías compartidas es que debes asegurarte de que el enlazador dinámico encontrará las librerías Qt. A menos que se le indique lo contrario, el enlazador dinámico no busca en el directorio donde reside su aplicación. Hay muchas maneras de resolver esto:

• Puedes instalar las librerías Qt en una de las rutas de librerías del sistema (por ejemplo, /usr/lib en la mayoría de los sistemas).
• Puede pasar una ruta predeterminada a la opción de línea de comandos -rpath al enlazar la aplicación. Esto le dirá al enlazador dinámico que busque en este directorio cuando inicie su aplicación.
• Puedes escribir un script de inicio para tu aplicación, donde 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 su aplicación se ejecutará con "Establecer ID de usuario en ejecución", y si será propiedad de root, entonces LD_LIBRARY_PATH será ignorado en algunas plataformas. En este caso, el uso del enfoque LD_LIBRARY_PATH no es una opción).

La desventaja del primer enfoque es que el usuario debe tener privilegios de superusuario. La desventaja del segundo enfoque es que el usuario puede no tener privilegios para instalar en la ruta predeterminada. En cualquier caso, los usuarios no tienen la opción de instalar en su directorio personal. Recomendamos utilizar el tercer enfoque, ya que es el más flexible. Por ejemplo, un script plugandpaint.sh tendrá 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 "$@"

Ejecutando este script en lugar del ejecutable, te aseguras de que las librerías Qt serán encontradas por el enlazador dinámico. Ten en cuenta que sólo tienes que renombrar el script para usarlo con otras aplicaciones.

Cuando busca plugins, la aplicación busca en un subdirectorio de plugins dentro del directorio del ejecutable de la aplicación. O bien tienes que copiar manualmente los plugins en el directorio plugins, o puedes establecer el DESTDIR en los archivos de proyecto de los plugins:

DESTDIR = /path/to/Qt/plugandpaint/plugins

Un archivo que distribuya todas las librerías Qt, y todos los plugins, necesarios para ejecutar la aplicación plugandpaint, tendría que incluir los siguientes archivos:

En la mayoría de los sistemas, la extensión para bibliotecas compartidas es .so. Una excepción notable es HP-UX, que utiliza .sl.

Recuerde que si su aplicación depende de librerías específicas del compilador, éstas deben ser redistribuidas junto con su aplicación. Para más información, consulte la sección Dependencias de la aplicación.

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

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

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

Enlace estático

La vinculación estática es a menudo la forma más segura y fácil de distribuir una aplicación en Unix, ya que le libera de la tarea de distribuir las bibliotecas Qt y asegurarse de que se encuentran en la ruta de búsqueda por defecto para las bibliotecas en el sistema de destino.

Construyendo Qt estáticamente

Para usar este enfoque, debe empezar por construir una versión _estática_ de las librerías Qt. Siga los pasos en Qt para Linux - Construyendo desde el código fuente, pero recuerde añadir un argumento -static para configurar:

mkdir -p ~/dev/qt-build
cd ~/dev/qt-build
/tmp/qt-everywhere-src-6.11.0/configure -static

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

Una vez construido Qt estáticamente, el siguiente paso es regenerar el makefile y reconstruir la aplicación. Primero, debemos ir al directorio que contiene la aplicación:

cd /path/to/Qt/examples/widgets/tools/plugandpaint/app

Ahora ejecuta qmake para crear un nuevo makefile para la aplicación, y haz una construcción limpia para crear el ejecutable enlazado estáticamente:

make clean
PATH=/path/to/Qt/bin:$PATH
export PATH
qmake -config release
make

Probablemente quieras enlazar contra las librerías de lanzamiento, y puedes especificarlo al invocar qmake. Ten en cuenta que debemos establecer la ruta al Qt estático que acabamos de construir.

Para comprobar que la aplicación realmente enlaza estáticamente con Qt, ejecuta la herramienta ldd (disponible en la mayoría de Unixes):

ldd ./application

Comprueba que las librerías Qt no se mencionan en la salida.

Ahora, siempre que todo haya compilado y enlazado sin errores, deberíamos tener un archivo plugandpaint listo para su despliegue. Una forma fácil de comprobar que la aplicación realmente se puede ejecutar de forma autónoma es copiarla a una máquina que no tenga Qt ni ninguna aplicación Qt instalada, y ejecutarla 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. Para más información, consulte la sección Dependencias de la aplicación.

El ejemplo Plug & Paint consta de varios componentes: El núcleo de la aplicación(Plug & Paint), y los plugins Basic Tools y Extra Filters. Dado que no podemos desplegar plugins utilizando 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á deshabilitada debido a los plugins que faltan. Para desplegar aplicaciones basadas en plugins debemos utilizar el enfoque de biblioteca compartida.

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 los Unix):

ldd ./application

Esto listará todas las dependencias de bibliotecas compartidas para su aplicación. Dependiendo de la configuración, estas bibliotecas deben redistribuirse junto con su aplicación. En particular, la biblioteca estándar de C++ debe redistribuirse si estás compilando tu aplicación con un compilador que es incompatible bíblicamente con el compilador del sistema. Cuando sea posible, la solución más segura es enlazar estáticamente con estas bibliotecas.

Probablemente querrás enlazar dinámicamente con las bibliotecas X11 normales, ya que algunas implementaciones intentarán abrir otras bibliotecas compartidas con dlopen(), y si esto falla, la biblioteca X11 podría hacer que tu aplicación se bloqueara.

También vale la pena mencionar que Qt buscará ciertas extensiones X11, como Xinerama y Xrandr, y posiblemente las extraiga, incluyendo todas las bibliotecas con las que se enlazan. Si no puedes garantizar la presencia de una determinada extensión, 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 en binario. Por extraño que parezca, algunos vendedores de software han tenido éxito compilando su software en máquinas muy antiguas y han tenido mucho cuidado de no actualizar ningún software que se ejecute en ellas.

Al enlazar tu aplicación con las librerías estáticas de Qt, debes enlazar explícitamente con las librerías dependientes mencionadas anteriormente. Hazlo añadiéndolas a la variable LIBS en tu archivo de proyecto.

Plugins Qt

Todas las aplicaciones Qt GUI requieren un plugin que implemente la capa Qt Platform Abstraction (QPA) en Qt. Para Linux/X11, el nombre del plugin de plataforma es libqxcb.so. 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 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 estar localizado dentro de un subdirectorio específico (como imageformats o sqldrivers) dentro de su directorio de distribución.

La ruta de búsqueda de los plugins de Qt (así como algunas otras rutas) está codificada en la biblioteca QtCore. Por defecto, la primera ruta de búsqueda de plugins será /path/to/Qt/plugins. Como se mencionó anteriormente, el uso de rutas predeterminadas tiene ciertas desventajas, por lo que es necesario examinar varias alternativas para asegurarse de que se encuentran los plugins de Qt:

• Usando qt.conf. Este es el enfoque recomendado ya que proporciona la mayor flexibilidad.
• Usando QApplication::addLibraryPath() o QApplication::setLibraryPaths().
• Utilizando una utilidad de instalación de terceros o el gestor de paquetes del sistema de destino para cambiar las rutas codificadas en la biblioteca QtCore.

El documento How to Create Qt Plugins (Cómo crear plugins Qt ) describe los aspectos a los que debe prestar atención cuando cree e implemente plugins para aplicaciones Qt.

Tutorial: Crear un paquete DEB

Esta sección describe cómo crear un paquete DEB para tu aplicación Qt en Linux usando la API de despliegue CMake disponible en Qt 6.5 o posterior. No existe una herramienta dedicada a linuxdeployqt. La solución actual sólo se basa en la funcionalidad incorporada de CMake.

Ejemplo de configuración de proyecto

Comience con un simple proyecto 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 despliegue para crear un directorio autocontenido:

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

Construir e instalar el proyecto:

qt-cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/tmp/my-application ..
cmake --build .
cmake --install .

El script de despliegue:

• Crea un archivo qt.conf junto al ejecutable que contiene información sobre la disposición del directorio. Esto es necesario en tiempo de ejecución para encontrar los plugins y los activos. Consulte la documentación qt.conf para más detalles.
• Inspecciona el ejecutable y los plugins Qt utilizados con el archivo incorporado de CMake (GET_RUNTIME_DEPENDENCIES) para determinar qué bibliotecas Qt desplegar.
• Instala los plugins Qt y las librerías Qt necesarias.

El directorio de instalación puede ahora copiarse a una máquina diferente, y la aplicación debería seguir funcionando.

Paso 2: Crear el paquete DEB

Después de la instalación, empaqueta el directorio usando CPack. Añada lo siguiente a su proyecto 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)

Reconfigure el proyecto, navegue al directorio de construcción (debe contener el archivo CPackConfig.cmake ), y ejecute CPack para generar el paquete DEB:

cpack -G DEB

Para inspeccionar el contenido del paquete:

dpkg -c my_app-1.0-Linux.deb

Para instalar el paquete:

sudo dpkg -i my_app-1.0-Linux.deb