Tu compilación de Yocto falló. La terminal está llena de mensajes de error. Buscas en internet y encuentras respuestas para Kirkstone o Dunfell, pero nada para Scarthgap.
Esta guía cubre los errores de compilación más comunes de Yocto organizados por tipo de tarea, basada en Scarthgap 5.0 LTS (BitBake 2.8). Empieza con las herramientas de depuración y luego salta a la tarea que falló.
Si eres nuevo en Yocto, comienza con la guía de inicio.
Archivos de log y herramientas de depuración
Antes de perseguir errores, aprende dónde buscar y qué herramientas usar.
Ubicación de los archivos de log
BitBake genera un archivo de log para cada tarea.
tmp/work/<ARCH>/<RECIPE>/<VERSION>/temp/
├── log.do_fetch ← log de ejecución de do_fetch
├── log.do_compile ← log de ejecución de do_compile
├── run.do_compile ← el script real que se ejecutó
└── ...
Los archivos log.do_* son enlaces simbólicos que apuntan a la última ejecución. Cuando una compilación falla, empieza aquí.
# Ejemplo: revisar el log de do_compile de curl
cat tmp/work/core2-64-poky-linux/curl/8.7.1/temp/log.do_compile
bitbake-getvar (Inspección de variables)
Muestra el valor final de una variable y qué archivo lo estableció.
# Verificar una variable específica de receta
bitbake-getvar -r curl SRC_URI
# Verificar una variable global
bitbake-getvar DISTRO_FEATURES
Esto muestra el valor después de que todas las operaciones :append y :prepend se han aplicado. Úsalo para verificar que las variables están configuradas como esperas.
devshell (Shell de desarrollo)
Lanza un shell interactivo con las mismas variables de entorno que usa BitBake. Esencial para reproducir y corregir errores de compilación.
bitbake curl -c devshell
Dentro del devshell, las variables de entorno como CC, CFLAGS y LDFLAGS están configuradas exactamente como BitBake las configuraría. Ejecuta make clean && make para reproducir el problema y probar soluciones.
bitbake -e (Volcado completo del entorno)
Cuando necesitas ver funciones Python o el historial completo de expansión que bitbake-getvar no cubre.
bitbake -e curl | grep ^SRC_URI=
Errores de do_fetch
Fallos en la descarga del código fuente. Normalmente relacionados con la red.
URL modificada o eliminada
ERROR: curl-8.7.1-r0 do_fetch: Fetcher failure for URL: 'https://example.com/old-url/curl-8.7.1.tar.gz'
El host upstream cambió su estructura de URL. Corrige el SRC_URI de la receta o configura un mirror de fuentes.
# conf/local.conf — configuración de mirror de fuentes
SOURCE_MIRROR_URL = "http://mirror.example.com/sources/"
INHERIT += "own-mirrors"
Protocolo git:// obsoleto
GitHub dejó de soportar el protocolo git:// en 2021. Las recetas más antiguas pueden seguir usando git://github.com/....
ERROR: curl-8.7.1-r0 do_fetch: Fetcher failure: fetch command failed with exit code 128
Usa un bbappend para cambiar a https:// o añadir el parámetro protocol.
# Corregir protocolo mediante bbappend
SRC_URI:remove = "git://github.com/example/repo.git;branch=main"
SRC_URI:append = " git://github.com/example/repo.git;protocol=https;branch=main"
Problemas de conectividad de red
Para compilaciones detrás de un proxy o firewall.
# conf/local.conf — configuración de proxy
HTTP_PROXY = "http://proxy.example.com:8080"
HTTPS_PROXY = "http://proxy.example.com:8080"
Para fallos de red temporales, simplemente vuelve a ejecutar la compilación. BitBake reanuda desde la tarea fallida automáticamente.
Discrepancia de checksum
ERROR: curl-8.7.1-r0 do_fetch: Checksum mismatch!
El tarball upstream fue reemplazado. El mensaje de error muestra el checksum correcto — actualiza SRC_URI[sha256sum] en la receta. Pero primero verifica que el cambio sea legítimo, no un ataque a la cadena de suministro.
Errores de do_patch
Fallos en la aplicación de parches. Más comunes al actualizar versiones de recetas.
El parche no se aplica
ERROR: curl-8.7.1-r0 do_patch: Command Error: 'quilt push' failed
Hunk #1 FAILED at 42.
El código upstream cambió y el contexto del parche ya no coincide.
Cómo solucionarlo:
- Usa devshell para investigar
bitbake curl -c devshell
# Dentro del devshell
quilt push # ver qué parche falla
quilt push -f # forzar la aplicación y revisar los archivos de rechazo
- Examina los archivos
*.rejpara ver qué no pudo aplicarse - Corrige manualmente el parche y colócalo en el directorio de archivos de la receta
Problemas de orden de parches
Cuando SRC_URI lista múltiples parches, se aplican en orden. Si los parches dependen entre sí, el orden importa.
SRC_URI = "... \
file://0001-first-fix.patch \
file://0002-depends-on-first.patch"
Errores de do_compile
Fallos de compilación. Las causas varían ampliamente.
Condiciones de carrera en compilación paralela
Los errores de compilación intermitentes suelen ser condiciones de carrera en la compilación paralela.
fatal error: some_header.h: No such file or directory
Un archivo fuente intenta incluir un encabezado que aún no se ha generado porque otro trabajo de make todavía lo está compilando.
# Diagnóstico: establecer PARALLEL_MAKE a 1 para la receta problemática
PARALLEL_MAKE:pn-problematic-recipe = "-j1"
Si -j1 tiene éxito, es una condición de carrera paralela. La solución correcta es añadir la dependencia faltante al Makefile de la receta.
OOM (Sin memoria)
error: internal compiler error: Killed (program cc1plus)
Killed es la firma del OOM killer. Confirma con dmesg.
dmesg | grep -i "oom\|killed"
La solución es reducir el paralelismo. Consulta la guía de optimización de velocidad de compilación para detalles sobre el ajuste de BB_NUMBER_THREADS.
# conf/local.conf — reducir paralelismo
BB_NUMBER_THREADS = "4"
PARALLEL_MAKE = "-j4"
Conflictos de encabezados del host
/usr/local/include/iconv.h:... error: ...
Los encabezados en /usr/local/include/ de la máquina host interfieren con la compilación cruzada. Esto está documentado en las FAQ oficiales de Yocto.
Soluciona renombrando los encabezados conflictivos del host o usando un entorno de compilación limpio.
Errores de do_package_qa
Fallos en las verificaciones de QA (Aseguramiento de Calidad). La compilación en sí tuvo éxito, pero el paquete tiene problemas de integridad.
installed-vs-shipped
ERROR: QA Issue: <package>: Files/directories were installed but not shipped in any package
Se instalaron archivos mediante do_install pero no están incluidos en ninguna variable FILES:${PN}.
# Solución: añadir la ruta a FILES
FILES:${PN} += "${datadir}/myapp"
already-stripped
WARNING: QA Issue: File '/usr/bin/myapp' from myapp was already stripped
El binario fue stripped durante la compilación. Yocto hace strip automáticamente, así que hacer strip en la receta es redundante.
# Solución: deshabilitar el strip en la receta
INHIBIT_PACKAGE_STRIP = "1"
ldflags
ERROR: QA Issue: No GNU_HASH in the ELF binary
El enlazador no usó los LDFLAGS correctos. El sistema de compilación está ignorando ${LDFLAGS}.
# Solución: pasar LDFLAGS a make
EXTRA_OEMAKE += "LDFLAGS='${LDFLAGS}'"
Deshabilitar verificaciones QA temporalmente
Puedes suprimir verificaciones QA específicas mientras investigas la causa raíz.
# Suprimir advertencias QA para una receta específica (medida temporal)
INSANE_SKIP:${PN} += "already-stripped ldflags"
Otros errores comunes
Errores fuera de la ejecución de tareas — problemas de entorno y configuración de capas.
No se puede conectar al servidor de BitBake
ERROR: Unable to connect to bitbake server, or start one
Un proceso previo de BitBake terminó de forma anormal y dejó un archivo de bloqueo.
# Eliminar el archivo de bloqueo
rm -f build/bitbake.lock
Si eso no ayuda, busca otros procesos de BitBake.
ps aux | grep bitbake
Discrepancia de LAYERSERIES_COMPAT
ERROR: Layer 'meta-custom' is not compatible with the current set of layers
El conf/layer.conf de la capa no incluye scarthgap en LAYERSERIES_COMPAT.
# meta-custom/conf/layer.conf
LAYERSERIES_COMPAT_meta-custom = "scarthgap"
Para tus propias capas, añade la línea anterior. Para capas de terceros, busca una versión compatible con Scarthgap o haz fork y corrige. Si te encuentras con esto durante una migración desde Kirkstone, consulta la lista de verificación de migración para la lista completa de cambios.
Nothing RPROVIDES
ERROR: Nothing RPROVIDES 'python3-requests'
El paquete requerido no es proporcionado por ninguna receta. Dos causas principales.
- Capa no registrada en
bblayers.conf
# Verificar capas registradas
bitbake-layers show-layers
# Añadir una capa
bitbake-layers add-layer ../meta-python
- Discrepancia en el nombre del paquete
Los nombres de paquetes en Yocto pueden diferir de los nombres de distribución.
# Buscar un paquete
oe-pkgdata-util find-path /usr/bin/python3
Espacio en disco agotado
No space left on device
Una compilación completa de core-image-sato requiere aproximadamente 90 GB. Habilitar rm_work reduce esto a aproximadamente 22 GB. Consulta la guía de optimización de velocidad de compilación para más detalles.
# conf/local.conf
INHERIT += "rm_work"
RM_WORK_EXCLUDE += "my-custom-recipe"
Conclusión
Los errores de compilación de Yocto se pueden acotar por tipo de tarea.
| Tarea | Causas comunes | Primera verificación |
|---|---|---|
| do_fetch | Cambios de URL, red, checksums | URL del mensaje de error, configuración de mirror |
| do_patch | Discrepancia de contexto | devshell con quilt push |
| do_compile | Condiciones de carrera, OOM | Reintentar con -j1, revisar dmesg para OOM |
| do_package_qa | FILES no configurado, LDFLAGS | Nombre de verificación en el mensaje de error QA |
El flujo de trabajo de depuración se reduce a tres pasos.
- Lee el log:
tmp/work/<ARCH>/<RECIPE>/<VERSION>/temp/log.do_* - Verifica variables:
bitbake-getvar -r <recipe> <variable> - Reproduce el entorno:
bitbake <recipe> -c devshell
Domina estos tres y podrás resolver la mayoría de los errores de compilación por tu cuenta.
Entender los internos del sistema de compilación hace que el diagnóstico de errores sea mucho más rápido. Estos libros cubren la arquitectura de Yocto en profundidad.