La mayoría de los errores de compilación de Yocto se diagnostican en tres pasos: leer el log de la tarea en tmp/work/, inspeccionar variables con bitbake-getvar y reproducir el entorno con devshell. Esta guía organiza los errores más comunes por la tarea que falló — do_fetch, do_patch, do_compile o do_package_qa — para que puedas ir directo a la solución.
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 está 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. La documentación oficial de Herramientas y técnicas de depuración de Yocto cubre estos temas en detalle.
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. Consulta la documentación oficial de devshell para más detalles.
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 anunció la deprecación del protocolo git:// en 2021 y lo eliminó por completo en marzo de 2022. 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 (Docker o CROPS son buenas opciones).
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 en Scarthgap requiere aproximadamente 140 GB de espacio libre. Habilitar rm_work reduce la huella final 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"
FAQ
¿Dónde están los archivos de log de compilación de Yocto?
Cada tarea genera su propio log en tmp/work/<ARCH>/<RECIPE>/<VERSION>/temp/log.do_<tarea>. Los archivos log.do_* son enlaces simbólicos a la última ejecución. Empieza aquí cuando una compilación falla.
¿Cómo depuro un error de compilación de Yocto?
Tres pasos: (1) Lee el log de la tarea en tmp/work/, (2) verifica los valores de variables con bitbake-getvar -r <receta> <variable>, (3) reproduce el entorno de compilación con bitbake <receta> -c devshell.
¿Qué significa "Killed (program cc1plus)"?
El OOM (Out of Memory) killer de Linux terminó el proceso del compilador. Confirma con dmesg | grep -i oom. Soluciona reduciendo BB_NUMBER_THREADS y PARALLEL_MAKE en conf/local.conf.
¿Cuánto espacio en disco necesita una compilación de Yocto?
Una compilación completa de core-image-sato en Scarthgap requiere aproximadamente 140 GB. Añadir INHERIT += "rm_work" en conf/local.conf reduce la huella final a unos 22 GB.
¿Cómo soluciono "Fetcher failure" en do_fetch?
Verifica si la URL upstream cambió, si se sigue usando el protocolo git:// (GitHub lo eliminó en 2022), o si se actualizó un checksum. Configura un SOURCE_MIRROR_URL en local.conf para mayor resiliencia ante cambios upstream.
¿Qué es devshell y cuándo debo usarlo?
bitbake <receta> -c devshell abre un shell con exactamente las mismas variables de entorno (CC, CFLAGS, LDFLAGS) que BitBake usa durante la compilación. Úsalo para reproducir manualmente errores de compilación y probar soluciones antes de modificar la receta.
¿Cómo soluciono "Files/directories were installed but not shipped"?
Añade la ruta faltante a la variable FILES de la receta: FILES:${PN} += "${datadir}/myapp". Esto le dice a BitBake qué archivos pertenecen a qué paquete.
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. Para la referencia oficial, consulta la documentación de Herramientas y técnicas de depuración de Yocto.
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.
Artículos relacionados: