Capas en Yocto: Cómo crear y gestionar capas personalizadas

¿Qué es exactamente una capa de Yocto? Hay tantos directorios meta-xxx — ¿qué hace cada uno?

Una capa de Yocto es un directorio que agrupa recetas, configuraciones y parches relacionados en un módulo reutilizable. Apilas capas para construir una imagen Linux personalizada — soporte de tu placa, tus aplicaciones, la configuración de tu distribución — sin tocar el código fuente de Poky. Este artículo cubre cómo funciona el modelo de capas, cómo crear capas personalizadas, cómo añadir capas BSP externas como meta-raspberrypi, y cómo depurar errores comunes de capas.

¿Qué es una capa de Yocto?

Una capa es un directorio que agrupa recetas, archivos de configuración y parches relacionados en un módulo lógico.

El sistema de compilación de Yocto funciona apilando múltiples capas unas sobre otras. Cada capa puede sobrescribir o extender lo que hay debajo. Esto es lo que te permite personalizar tu sistema sin tocar el código fuente upstream.

Una capa de mayor prioridad puede sobrescribir una receta en una capa de menor prioridad. Si la misma receta existe en múltiples capas, la de mayor prioridad gana.

¿Por qué son necesarias las capas?

• Reutilizabilidad — la misma capa puede compartirse entre múltiples proyectos
• Mantenibilidad — tus cambios permanecen separados de upstream. Cuando actualizas Poky, tus personalizaciones no se borran
• Colaboración en equipo — el trabajo de BSP, aplicaciones y configuración de distribución pueden ser de diferentes personas
• Control de versiones — cada capa puede vivir en su propio repositorio Git

Tipos de capas y estructura

Tipos de capas

En tus propios proyectos, siempre crea una capa personalizada y pon tus recetas y parches allí.

Estructura de directorios

Todas las capas siguen la misma estructura básica:

meta-mylayer/
├── conf/
│   └── layer.conf          # Configuración de la capa (obligatorio)
├── COPYING.MIT             # Archivo de licencia
├── README                  # Descripción de la capa
├── recipes-bsp/            # Recetas BSP
├── recipes-core/           # Recetas del sistema central
├── recipes-example/        # Recetas de ejemplo
│   └── myapp/
│       ├── myapp_1.0.bb
│       └── files/
├── recipes-kernel/         # Recetas relacionadas con el kernel
├── recipes-graphics/       # Recetas gráficas
└── classes/                # Archivos de clase compartidos (.bbclass)

La nomenclatura de directorios recipes-* es una convención. BitBake descubre automáticamente las recetas dentro de directorios que coinciden con este patrón.

Dentro de layer.conf

conf/layer.conf es la tarjeta de identidad de la capa. Sin él, Yocto no reconoce el directorio como una capa.

# conf/layer.conf

# Añadir la ruta de esta capa a BBPATH
BBPATH .= ":${LAYERDIR}"

# Indicar a BitBake dónde encontrar recetas en esta capa
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
            ${LAYERDIR}/recipes-*/*/*.bbappend"

# Dar a esta capa un nombre de colección único
BBFILE_COLLECTIONS += "meta-mylayer"
BBFILE_PATTERN_meta-mylayer = "^${LAYERDIR}/"

# Prioridad de la capa (6–10 es típico para capas personalizadas)
BBFILE_PRIORITY_meta-mylayer = "6"

# Con qué versiones de Yocto esta capa es compatible
LAYERSERIES_COMPAT_meta-mylayer = "scarthgap"

# Otras capas de las que esta capa depende
LAYERDEPENDS_meta-mylayer = "core"

Creación de una capa personalizada

Usando bitbake-layers (Recomendado)

El enfoque más fácil y fiable es usar el comando bitbake-layers.

# Entrar al entorno de compilación
cd ~/yocto/poky
source oe-init-build-env build

# Navegar al directorio padre y crear la capa
cd ..
bitbake-layers create-layer meta-myproject

# Inspeccionar los archivos generados
ls meta-myproject/
conf  COPYING.MIT  README  recipes-example

cat meta-myproject/conf/layer.conf

Creación manual

Crear la capa manualmente es una excelente forma de entender qué hace cada pieza.

# Crear la estructura de directorios
mkdir -p meta-myproject/conf
mkdir -p meta-myproject/recipes-example/myapp

# Escribir layer.conf
cat > meta-myproject/conf/layer.conf << 'EOF'
BBPATH .= ":${LAYERDIR}"
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
            ${LAYERDIR}/recipes-*/*/*.bbappend"
BBFILE_COLLECTIONS += "meta-myproject"
BBFILE_PATTERN_meta-myproject = "^${LAYERDIR}/"
BBFILE_PRIORITY_meta-myproject = "6"
LAYERSERIES_COMPAT_meta-myproject = "scarthgap"
EOF

Añadir una capa a tu compilación

Editar bblayers.conf

# Usando el comando (recomendado)
cd ~/yocto/poky
source oe-init-build-env build
bitbake-layers add-layer ../meta-myproject

# O editar el archivo directamente
nano conf/bblayers.conf

Ejemplo de conf/bblayers.conf:

BBLAYERS ?= " \
  /home/user/yocto/poky/meta \
  /home/user/yocto/poky/meta-poky \
  /home/user/yocto/poky/meta-yocto-bsp \
  /home/user/yocto/meta-myproject \
  "

Las rutas absolutas son la práctica estándar. bitbake-layers add-layer también inserta rutas absolutas.

Verificar y eliminar capas

# Listar todas las capas activas
bitbake-layers show-layers

layer                 path                                      priority
==========================================================================
meta                  /home/user/yocto/poky/meta                 5
meta-poky             /home/user/yocto/poky/meta-poky            5
meta-yocto-bsp        /home/user/yocto/poky/meta-yocto-bsp       5
meta-myproject        /home/user/yocto/meta-myproject            6

# Eliminar una capa de la compilación (los archivos no se eliminan)
bitbake-layers remove-layer meta-myproject

Personalizar recetas existentes

Cuando necesitas modificar una receta existente, nunca edites el archivo original. Usa un archivo .bbappend en tu propia capa. Este es el patrón de personalización no destructiva de Yocto. Consulta la guía práctica de bbappend para más detalles.

Añadir una capa BSP externa

Aquí tienes un ejemplo práctico: añadir soporte para Raspberry Pi con meta-raspberrypi.

Descargar las capas

# Clonar en el mismo directorio padre que Poky
cd ~/yocto
git clone -b scarthgap git://git.yoctoproject.org/meta-raspberrypi

# meta-openembedded es una dependencia de meta-raspberrypi
git clone -b scarthgap git://git.openembedded.org/meta-openembedded

Añadir las capas y configurar

cd ~/yocto/poky
source oe-init-build-env build

# Añadir meta-oe (necesario para meta-raspberrypi)
bitbake-layers add-layer ../meta-openembedded/meta-oe

# Añadir meta-raspberrypi
bitbake-layers add-layer ../meta-raspberrypi

# Verificar
bitbake-layers show-layers

Establece la máquina objetivo en conf/local.conf:

MACHINE = "raspberrypi4-64"

Para el flujo de trabajo completo de compilación para Raspberry Pi, consulta la guía de compilación para RPi.

OpenEmbedded Layer Index

La comunidad mantiene un índice consultable de capas públicamente disponibles en el OpenEmbedded Layer Index.

Busca cosas como "raspberrypi", "qt5" o "nodejs" y encontrarás capas que proporcionan soporte. Puedes filtrar por rama de release de Yocto (Scarthgap, Kirkstone, etc.) para encontrar capas compatibles. Antes de escribir una receta desde cero, siempre consulta aquí primero.

Capas de uso común

Errores comunes y soluciones

La capa 'xxx' no es compatible

ERROR: Layer xxx is not compatible with the current version

Causa: El LAYERSERIES_COMPAT en layer.conf no coincide con la rama activa de Yocto.

Solución: Actualiza LAYERSERIES_COMPAT en el layer.conf de tu capa:

LAYERSERIES_COMPAT_meta-mylayer = "scarthgap"

La capa depende de 'xxx'

ERROR: Layer xxx depends on layer xxx

Causa: Una capa de dependencia necesaria no ha sido añadida todavía.

Solución: Añade primero la capa de dependencia con bitbake-layers add-layer.

bbappend sin receta correspondiente

WARNING: No bb files in default matched BBFILE_PATTERN

Causa: Tienes un archivo .bbappend en tu capa, pero no existe una receta .bb correspondiente en ninguna capa activa. Esto suele ocurrir después de actualizar Yocto — la receta que estabas modificando puede haber sido renombrada o eliminada.

Solución: Busca el nombre correcto de la receta en la nueva versión. Si la receta fue eliminada intencionalmente, elimina el .bbappend huérfano. Para suprimir esto como advertencia en lugar de error durante la migración, establece BB_DANGLINGAPPENDS_WARNONLY = "1" en local.conf.

Depurar conflictos de prioridad

Cuando la misma receta existe en múltiples capas, la de mayor BBFILE_PRIORITY gana. Esto puede causar comportamiento inesperado si no te das cuenta de que una receta está siendo sobrescrita.

# Mostrar todas las recetas sobrescriptas (misma receta en múltiples capas)
bitbake-layers show-overlayed

# Mostrar de qué capa viene una receta específica
bitbake-layers show-recipes "busybox"

show-overlayed es tu mejor herramienta cuando depuras "¿por qué se ignora mi receta?". Si una receta de tu capa personalizada no tiene efecto, verifica si una capa de mayor prioridad la está sobrescribiendo.

FAQ

¿Cuál es la diferencia entre una capa y una receta?

Una receta (archivo .bb) son las instrucciones de compilación para un solo paquete — de dónde obtener el código, cómo compilar y dónde instalar. Una capa es un directorio que agrupa múltiples recetas, configuraciones y parches relacionados en un módulo reutilizable. Piensa en las recetas como instrucciones individuales y las capas como carpetas organizadas que las contienen.

¿Puedo poner todo en una sola capa personalizada?

Técnicamente sí, pero no es recomendable para proyectos grandes. El patrón común es separar responsabilidades: una capa para personalizaciones BSP, otra para recetas de aplicaciones, y otra para configuración de distribución. Para proyectos pequeños o prototipos, una sola capa meta-myproject es perfectamente válida.

¿Qué número de prioridad debo usar para mi capa personalizada?

El comando bitbake-layers create-layer usa prioridad 6 por defecto. Para la mayoría de capas personalizadas, 6–10 funciona bien. La regla clave: tu capa personalizada debe tener una prioridad mayor que las capas que quieres sobrescribir. Las capas base de Poky (meta, meta-poky) usan prioridad 5, así que 6+ asegura que tus personalizaciones tomen precedencia.

¿Cómo sobrescribo una receta de otra capa?

Usa un archivo .bbappend en tu propia capa. El .bbappend extiende o sobrescribe partes específicas de la receta original sin modificar el archivo upstream. La prioridad de tu capa debe ser igual o mayor que la capa que contiene la receta original.

¿Es obligatorio LAYERSERIES_COMPAT en layer.conf?

Sí. Desde Yocto 2.4 (Rocko), LAYERSERIES_COMPAT es obligatorio cuando BBFILE_COLLECTIONS está configurado — que es toda capa. Sin él, BitBake lanza un error de compatibilidad. Configúralo con el nombre de la rama de release que estás usando (por ejemplo, scarthgap).

¿Cómo encuentro capas para un paquete o placa específica?

Consulta el OpenEmbedded Layer Index. Puedes buscar por nombre de capa, nombre de receta o nombre de máquina, y filtrar por release de Yocto. Es el directorio más completo de capas mantenidas por la comunidad.

¿Puedo mezclar capas de diferentes versiones de Yocto?

Generalmente no. Mezclar capas de diferentes releases (por ejemplo, una capa de Kirkstone con un build de Scarthgap) suele causar errores difíciles de depurar. Siempre usa capas que coincidan con tu rama de release de Yocto. Si una capa no ha sido actualizada, busca un fork compatible o consulta la guía de migración.

Conclusión

• Siempre pon tus recetas en una capa personalizada — nunca edites Poky directamente
• Usa .bbappend para modificar recetas existentes — mantén los archivos upstream intactos
• Nombra tus capas con el prefijo meta- — es la convención establecida
• Configura LAYERSERIES_COMPAT correctamente — previene errores misteriosos de compatibilidad
• Mantén cada capa en su propio repositorio Git — esencial para desarrollo en equipo

¿Listo para el siguiente paso? Aquí están las opciones:

• Escribir recetas — empaqueta tus aplicaciones en imágenes
• Guía práctica de bbappend — patrones para personalizar recetas existentes
• Compilar Linux para Raspberry Pi — despliega en hardware real

Para profundizar en Linux embebido, estos libros son excelentes referencias.

Artículos relacionados:

• Cómo escribir recetas Yocto: Guía de archivos .bb
• Yocto bbappend: Guía práctica con 5 patrones
• Primeros pasos con Yocto: Compila tu primera imagen Linux
• Errores de compilación en Yocto: Guía de depuración por tarea
• La guía completa para compilaciones Yocto 10 veces más rápidas
• Migración de Kirkstone a Scarthgap