Configurar un dispositivo Linux embebido
La compilación cruzada de Qt para un dispositivo concreto requiere una cadena de herramientas y un sysroot. Se espera que la cadena de herramientas contenga una versión de gcc, u otro compilador, y las herramientas asociadas creadas para la compilación cruzada. Esto significa que estas herramientas se ejecutan en el sistema anfitrión (normalmente x64), al tiempo que generan binarios para la arquitectura de destino (por ejemplo, ARM de 32 o 64 bits). El sysroot contiene los encabezados y las bibliotecas para el sistema de destino, lo que permite compilar y enlazar bibliotecas y aplicaciones en el sistema anfitrión.
Esta página de introducción describe el enfoque genérico, en el que no se utilizan sistemas de compilación de distribuciones, como Yocto o Buildroot. Siempre es posible realizar una compilación cruzada e implementar Qt en un dispositivo, siempre que se disponga de una cadena de herramientas y un sysroot adecuados.
Advertencia: Esta página solo ofrece una visión general genérica y de alto nivel. Hay una gran cantidad de detalles que pueden variar en función del entorno de compilación, el dispositivo de destino y la cadena de herramientas. En caso de duda, consulta a tu integrador de sistemas. Para obtener imágenes de referencia precompiladas y SDK, consulta la Boot to Qt oferta.
Al ejecutar aplicaciones basadas en Qt sin un sistema de ventanas, como X11 o Wayland, algunos dispositivos requieren código de adaptación específico del fabricante para la compatibilidad con EGL y OpenGL ES. Esto se proporciona en forma de backends para el complemento de plataforma EGLFS. Esto no es relevante para plataformas no aceleradas, como aquellas que utilizan el complemento de plataforma LinuxFB, destinado exclusivamente al renderizado basado en software. A partir de Qt 6, muchos sistemas embebidos utilizan drm para configurar un modo de vídeo, gestionar los conectores de pantalla y las superficies gráficas. Por ejemplo, un dispositivo basado en i.MX8 de NXP o una Raspberry Pi 4 utilizarán este enfoque y, por lo tanto, el backend más utilizado para EGLFS es eglfs_kms, que permite el renderizado basado en EGL y OpenGL ES con drm, utilizando gbm para la gestión de superficies y búferes. Los dispositivos más antiguos, como el i.MX6 de NXP, seguirán utilizando el enfoque heredado, específico del fabricante de la GPU, para conectar las superficies de ventana EGL al búfer de fotogramas, utilizando backends eglfs dedicados, como eglfs_viv.
Nota: Hay que tener en cuenta que Qt es solo un componente de la pila de software de un dispositivo embebido. Especialmente cuando se trata de gráficos acelerados, Qt espera una pila gráfica funcional, con una configuración adecuada para los componentes del espacio de usuario y del núcleo, como el controlador de pantalla. Estos componentes quedan fuera del ámbito de Qt, y es responsabilidad del integrador de sistemas garantizar que el sistema base sea plenamente funcional y óptimo, incluidos los gráficos acelerados.
Para obtener más información sobre la configuración de gráficos y entrada para sistemas Linux embebidos, consulta Qt para Linux embebido.
Archivos de la cadena de herramientas frente a especificaciones de dispositivos
En Qt 5, lo habitual era utilizar una especificación de dispositivo del directorio qtbase/mkspecs/devices. Estas contienen los parámetros adecuados del compilador y del enlazador para un dispositivo concreto, además de garantizar que se seleccionen las bibliotecas EGL y OpenGL ES correctas, en caso de que se encuentren en una ubicación no estándar en el sysroot.
Por ejemplo, se podría haber configurado una compilación de Qt 5 para una Raspberry Pi 2 con un comando `configure` como el siguiente:
./configure -release -opengl es2 -device linux-rasp-pi2-g++ -device-option CROSS_COMPILE=$TOOLCHAIN/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf- -sysroot $ROOTFS -prefix /usr/local/qt5Nota: `configure` siempre utiliza el generador y la herramienta de compilación Ninja si hay disponible un ejecutable ` ninja `. Ninja es multiplataforma, cuenta con numerosas funciones, ofrece un gran rendimiento y se recomienda en todas las plataformas. El uso de otros generadores podría funcionar, pero no cuenta con soporte oficial.
Con Qt 6 y CMake, este enfoque ya no es suficiente por sí solo. En su lugar, es necesario proporcionar un archivo de cadena de herramientas de CMake antes de que pueda llevarse a cabo la configuración. Es en este archivo donde se realizan las personalizaciones relativas a las opciones del compilador y del enlazador, así como a las particularidades específicas de la cadena de herramientas y del sysroot.
En las secciones siguientes presentaremos un archivo de cadena de herramientas que puede utilizarse en muchos casos, con una personalización mínima. Se basa en el enfoque presentado en esta entrada del blog.
Nota: El archivo de cadena de herramientas que se presenta a continuación es un ejemplo que, a menudo, requerirá una mayor personalización para un dispositivo concreto. Los usuarios y los integradores de sistemas también tienen libertad para crear sus propios archivos de cadena de herramientas de la forma que consideren más adecuada.
Aunque CMake es el único sistema de compilación compatible para compilar Qt propiamente dicho, en Qt 6.0 las aplicaciones aún pueden compilarse utilizando « qmake ». Para conseguir una configuración de « qmake » que funcione con la compilación cruzada, será necesario especificar algunos de los argumentos heredados en CMake o en «configure».
Herramientas del host
La compilación cruzada de Qt requiere que se disponga de una compilación de Qt en el sistema anfitrión. Consulte «Compilación cruzada de Qt » para obtener más detalles.
Configuración de Qt
Supongamos que se dispone de lo siguiente:
- una cadena de herramientas y un sysroot en
$HOME/rpi-sdk, - una copia de Qt, como mínimo el módulo qtbase, en
$HOME/qt-cross, - una compilación de Qt para el sistema de destino en
$HOME/qt-host.
Además, antes de la configuración hay que decidir lo siguiente:
- ¿Dónde se instalará la compilación de Qt en el sistema local una vez finalizada la compilación? En el ejemplo utilizaremos
$HOME/qt6-rpi. - ¿Dónde se implementará la compilación de Qt en el dispositivo? En el ejemplo utilizaremos
/usr/local/qt6.
En el ejemplo vamos a utilizar un SDK de Raspberry Pi 4 (cadena de herramientas + sysroot) generado mediante Yocto, pero las instrucciones aquí son totalmente genéricas, sin dependencia alguna de Yocto. Los pasos son los mismos con cualquier otra cadena de herramientas y sysroot, una vez que se haya actualizado el archivo de la cadena de herramientas con el compilador cruzado correcto y las demás rutas.
Tras crear y cambiar al directorio « build »:
$HOME/qt-cross/qtbase/configure -release -opengl es2 -nomake examples -nomake tests \
-qt-host-path $HOME/qt-host \
-extprefix $HOME/qt6-rpi \
-prefix /usr/local/qt6 \
-- -DCMAKE_TOOLCHAIN_FILE=$HOME/qt-cross/toolchain.cmakeEn la práctica, este comando `configure` equivale a la siguiente llamada directa a CMake:
cmake -GNinja -DCMAKE_BUILD_TYPE=Release -DINPUT_opengl=es2 -DQT_BUILD_EXAMPLES=OFF -DQT_BUILD_TESTS=OFF \
-DQT_HOST_PATH=$HOME/qt-host \
-DCMAKE_STAGING_PREFIX=$HOME/qt6-rpi \
-DCMAKE_INSTALL_PREFIX=/usr/local/qt6 \
-DCMAKE_TOOLCHAIN_FILE=$HOME/qt-cross/toolchain.cmake \
$HOME/qt-cross/qtbaseSi se dispone del archivo de cadena de herramientas adecuado, esto es suficiente para generar una compilación de Qt que permita posteriormente compilar aplicaciones mediante CMake. Para que las aplicaciones también se puedan compilar con qmake, es necesario especificar la especificación de dispositivo y las opciones de dispositivo al estilo de Qt 5, además de todos los argumentos mostrados anteriormente:
$HOME/qt-cross/qtbase/configure ...
...
-device linux-rasp-pi4-v3d-g++ \
-device-option CROSS_COMPILE=$HOME/rpi_sdk/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi- \
-device-option DISTRO_OPTS="hard-float" \
...Por defecto, al realizar una compilación cruzada, solo se compilan las bibliotecas y herramientas de Qt que se supone que deben ejecutarse en el dispositivo de destino. Las herramientas relacionadas con la compilación, como moc y uic, no se compilan. La compilación de dichas herramientas se puede habilitar estableciendo QT_FORCE_BUILD_TOOLS en ON.
Nota: Cuando se habilita QT_FORCE_BUILD_TOOLS, los binarios de destino de herramientas como qmake se instalarán en la ubicación de preparación. Por lo tanto, si se utiliza qmake para compilar aplicaciones, ejecute en su lugar el script host-qmake.
Una vez completada la configuración sin errores, ejecute cmake --build . --parallel para compilar. Una vez compilada, ejecute cmake --install . para instalar los resultados en $HOME/qt6-rpi. Desde allí, la compilación de Qt se puede implementar en el dispositivo utilizando rsync, scp u otro método.
Si se compilan módulos Qt individuales, se puede utilizar el script qt-configure-module del directorio bin de la ubicación de preparación ($HOME/qt6-rpi en el ejemplo) para configurar módulos adicionales, como qtdeclarative, qtquick3d, etc. A continuación, se pueden compilar utilizando cmake --build . e instalar en la ubicación de preparación ejecutando cmake --install .
Nota: Antes de iniciar la compilación, comprueba siempre con atención el resultado del paso de configuración: ¿tiene habilitadas todas las funciones esperadas? Realizar una compilación e implementarla en el dispositivo no sirve de nada si no se han habilitado las funciones esenciales en el momento de la configuración.
Por ejemplo, si se desea utilizar gráficos acelerados a través de OpenGL, presta especial atención a las siguientes características:
EGL .................................... yes
OpenGL:
Desktop OpenGL ....................... no
OpenGL ES 2.0 ........................ yes
OpenGL ES 3.0 ........................ yes
...
evdev .................................. yes
libinput ............................... yes
...
EGLFS .................................. yes
EGLFS details:
EGLFS OpenWFD ........................ no
EGLFS i.Mx6 .......................... no
EGLFS i.Mx6 Wayland .................. no
EGLFS RCAR ........................... no
EGLFS EGLDevice ...................... yes
EGLFS GBM ............................ yes
EGLFS VSP2 ........................... no
EGLFS Mali ........................... no
EGLFS Raspberry Pi ................... no
EGLFS X11 ............................ no
LinuxFB ................................ yesEn el ejemplo de la Raspberry Pi 4, esperamos que EGL, OpenGL ES y EGLFS GBM aparezcan todos como « yes »; de lo contrario, el complemento de plataforma EGLFS y su backend eglfs_kms no funcionarán en el dispositivo. Para que funcionen el ratón, el teclado y la entrada táctil, debe estar habilitado « evdev » o « libinput ».
Del mismo modo, si se prevé utilizar X11 como sistema de ventanas (o como uno de ellos) en el dispositivo, asegúrese de que las características relacionadas con xcb y X11 estén marcadas como yes.
Un ejemplo de archivo de cadena de herramientas
Supondremos que hay un sysroot y una cadena de herramientas disponibles en $HOME/rpi-sdk. TARGET_SYSROOT y CROSS_COMPILER deben ajustarse a la cadena de herramientas y al sysroot que se estén utilizando. El ejemplo que se muestra aquí solo es válido para un SDK específico generado por Yocto. Lo mismo ocurre con CMAKE_C_COMPILER y CMAKE_CXX_COMPILER.
No dependemos de ningún script de envoltura que proporcione variables de entorno como PKG_CONFIG_*. En su lugar, la ruta a los archivos .pc se especifica en el archivo de la cadena de herramientas. Es probable que otro sysroot requiera ajustes en PKG_CONFIG_LIBDIR. Por ejemplo, con un sysroot generado a partir de una imagen de Raspberry Pi OS (antes Raspbian), se utilizaría /usr/lib/arm-gnueabihf/pkgconfig en su lugar.
Las opciones del compilador y del enlazador del ejemplo no son necesariamente óptimas. Ajústalas según sea necesario para el dispositivo de destino.
Para obtener más información sobre los detalles de CMake en el archivo de cadena de herramientas del ejemplo, consulta esta entrada de blog y la documentación de CMake.
cmake_minimum_required(VERSION 3.18)
include_guard(GLOBAL)
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)
set(TARGET_SYSROOT /home/user/rpi-sdk/sysroots/cortexa7t2hf-neon-vfpv4-poky-linux-gnueabi)
set(CROSS_COMPILER /home/user/rpi-sdk/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi)
set(CMAKE_SYSROOT ${TARGET_SYSROOT})
set(ENV{PKG_CONFIG_PATH} "")
set(ENV{PKG_CONFIG_LIBDIR} ${CMAKE_SYSROOT}/usr/lib/pkgconfig:${CMAKE_SYSROOT}/usr/share/pkgconfig)
set(ENV{PKG_CONFIG_SYSROOT_DIR} ${CMAKE_SYSROOT})
set(CMAKE_C_COMPILER ${CROSS_COMPILER}/arm-poky-linux-gnueabi-gcc)
set(CMAKE_CXX_COMPILER ${CROSS_COMPILER}/arm-poky-linux-gnueabi-g++)
set(QT_COMPILER_FLAGS "-march=armv7-a -mfpu=neon -mfloat-abi=hard")
set(QT_COMPILER_FLAGS_RELEASE "-O2 -pipe")
set(QT_LINKER_FLAGS "-Wl,-O1 -Wl,--hash-style=gnu -Wl,--as-needed")
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
include(CMakeInitializeConfigs)
function(cmake_initialize_per_config_variable _PREFIX _DOCSTRING)
if (_PREFIX MATCHES "CMAKE_(C|CXX|ASM)_FLAGS")
set(CMAKE_${CMAKE_MATCH_1}_FLAGS_INIT "${QT_COMPILER_FLAGS}")
foreach (config DEBUG RELEASE MINSIZEREL RELWITHDEBINFO)
if (DEFINED QT_COMPILER_FLAGS_${config})
set(CMAKE_${CMAKE_MATCH_1}_FLAGS_${config}_INIT "${QT_COMPILER_FLAGS_${config}}")
endif()
endforeach()
endif()
if (_PREFIX MATCHES "CMAKE_(SHARED|MODULE|EXE)_LINKER_FLAGS")
foreach (config SHARED MODULE EXE)
set(CMAKE_${config}_LINKER_FLAGS_INIT "${QT_LINKER_FLAGS}")
endforeach()
endif()
_cmake_initialize_per_config_variable(${ARGV})
endfunction()Compilación de aplicaciones para el dispositivo de destino
Una vez finalizada la compilación de Qt e instalada en la ubicación de preparación, se pueden compilar ejemplos o aplicaciones.
Con CMake, utilice el script « qt-cmake » generado en el directorio « bin » de la ubicación de preparación ($HOME/qt6-rpi en el ejemplo) para configurar y, a continuación, ejecute « ninja ». Por ejemplo:
$HOME/qt6-rpi/bin/qt-cmake .
cmake --build .A continuación, el binario de la aplicación resultante se puede implementar en el dispositivo. Resulta muy práctico utilizar el script auxiliar « qt-cmake », ya que este garantiza que se cargue el archivo de la cadena de herramientas que se utilizó para compilar Qt, por lo que no es necesario especificarlo repetidamente para cada aplicación.
A diferencia de lo que ocurre con Qt en sí, la compilación de aplicaciones con qmake sigue siendo compatible en Qt 6.0, siempre que se disponga de una especificación de dispositivo adecuada y se hayan pasado los argumentos heredados apropiados a CMake o a configure al configurar Qt. Si se cumplen todas estas condiciones, al ejecutar qmake y make también se generará un binario de la aplicación para el dispositivo de destino.
Valores predeterminados para los complementos de plataforma y EGLFS
Una vez configurado, se selecciona un complemento de plataforma por defecto. Este se utiliza al iniciar una aplicación sin el argumento ` -platform ` y sin tener establecida la variable de entorno ` QT_QPA_PLATFORM `.
Del mismo modo, el complemento de plataforma EGLFS cuenta con varios backends. El valor por defecto se elige en función de la disponibilidad y de un orden de prioridad predefinido. Si drm y gbm están disponibles, el valor por defecto será el backend eglfs_kms. Esto siempre se puede anular en tiempo de ejecución estableciendo la variable de entorno QT_QPA_EGLFS_INTEGRATION.
Para cambiar estos valores predeterminados para la compilación, sin tener que forzar un valor específico en tiempo de ejecución, se dispone de las dos siguientes variables de caché de CMake una vez que se ha ejecutado CMake por primera vez:
QT_QPA_DEFAULT_PLATFORM(STRING) - El nombre del complemento de plataforma predeterminado.QT_QPA_DEFAULT_EGLFS_INTEGRATION(STRING) — El backend EGLFS predeterminado.
Estas variables también se pueden configurar dentro del archivo de la cadena de herramientas.
Para obtener más información sobre la configuración de Qt, consulta Opciones de configuración de 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.