Yocto bbappend: Guía práctica con 5 patrones

Cuando necesitas personalizar una receta existente en Yocto, nunca edites el archivo .bb directamente. Tus cambios se perderán la próxima vez que hagas pull de las actualizaciones upstream.

En su lugar, usa archivos .bbappend. Estos "añaden" contenido a la receta original, así que tus personalizaciones sobreviven a las actualizaciones upstream.

Esta guía cubre bbappend desde lo básico hasta 5 patrones prácticos, basándose en Yocto Scarthgap 5.0 LTS.

Qué es un archivo bbappend

Un archivo .bbappend añade variables y tareas a una receta .bb que reside en otra capa.

El mecanismo es simple. Cuando BitBake carga una receta, busca archivos .bbappend que coincidan y añade su contenido al final de la receta antes de procesarla. Esto significa que las configuraciones del .bbappend pueden sobrescribir la receta original.

meta-poky/recipes-example/someapp/someapp_1.0.bb        ← receta original
meta-mylayer/recipes-example/someapp/someapp_%.bbappend  ← tus adiciones

Esta separación importa por dos razones.

Coexistencia con upstream: Ejecutar git pull en meta-poky no tocará tus personalizaciones en meta-mylayer
Visibilidad de cambios: Puedes ver qué capas modifican qué con bitbake-layers show-appends

Para la creación de capas, consulta la guía de creación de capas.

Reglas de nomenclatura de archivos

El nombre del archivo bbappend debe coincidir con el nombre del archivo de la receta objetivo.

Coincidencia exacta de versión

someapp_1.0.bbappend  → se aplica solo a someapp_1.0.bb
someapp_1.1.bbappend  → se aplica solo a someapp_1.1.bb

Si la versión no coincide exactamente, el bbappend se ignora silenciosamente.

Uso del comodín `%` (Recomendado)

Actualizar el nombre del bbappend cada vez que cambia la versión de la receta es tedioso. El comodín % coincide con cualquier versión.

someapp_%.bbappend  → se aplica a someapp_1.0.bb, someapp_2.3.bb, etc.

Verificar tu bbappend

Comprueba que tu bbappend sea reconocido con estos comandos.

bash

# Listar todos los archivos bbappend y sus recetas objetivo
bitbake-layers show-appends

# Mostrar todas las versiones de una receta específica (útil para depurar discrepancias de versión)
bitbake-layers show-recipes someapp

Operaciones con variables

Las operaciones más comunes en archivos bbappend son añadir valores a variables y sobrescribirlas.

Añadir valores (:append)

:append agrega un valor al final de una variable. Debes incluir un espacio al inicio. A diferencia de +=, :append no inserta un espacio automáticamente.

bash

# Correcto (espacio al inicio)
SRC_URI:append = " file://my-patch.patch"

# Incorrecto (sin espacio — se fusiona con el valor anterior y falla)
SRC_URI:append = "file://my-patch.patch"

También puedes usar +=, que auto-inserta un espacio, pero :append es preferido porque es más explícito.

bash

# Esto también funciona (+= auto-inserta un espacio)
SRC_URI += "file://my-patch.patch"

Eliminar valores (:remove)

bash

DISTRO_FEATURES:remove = "bluetooth wifi"

Sobrescribir valores

bash

# Sobrescritura completa
SOME_VARIABLE = "new-value"

FILESEXTRAPATHS — Ruta de búsqueda para archivos adicionales

Cuando tu bbappend añade archivos (parches, archivos de configuración, etc.), necesitas indicar a BitBake dónde encontrarlos.

bash

FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

Esta sola línea tiene tres detalles críticos.

Usa := (expansión inmediata): ${THISDIR} se refiere al directorio que contiene el archivo actual. Con expansión diferida (=), se resolvería al directorio del archivo .bb en su lugar
Los dos puntos finales : son obligatorios: FILESEXTRAPATHS es una lista separada por dos puntos. Sin los dos puntos, las rutas se fusionan y fallan
Usa :prepend: Asegura que tu ruta se busque antes que las rutas predeterminadas

Extender tareas

Puedes añadir procesamiento a las tareas de recetas (do_install, do_configure, etc.) con bbappend.

bash

do_install:append() {
    install -d ${D}${sysconfdir}
    install -m 0644 ${WORKDIR}/myconfig.conf ${D}${sysconfdir}/
}

:append añade al final de la tarea. El procesamiento original de la tarea se conserva.

Usa :prepend para añadir procesamiento antes de la tarea original.

bash

do_configure:prepend() {
    # Se ejecuta antes del do_configure original
    cp ${WORKDIR}/my-makefile ${S}/Makefile
}

5 patrones prácticos

Aquí tienes cinco casos de uso reales para archivos bbappend.

Patrón 1: Aplicar un parche

El caso de uso más básico. Aplica una corrección de error o parche de funcionalidad al código fuente upstream.

Estructura de directorios:

meta-mylayer/
  recipes-example/
    someapp/
      someapp_%.bbappend
      someapp/
        0001-fix-memory-leak.patch

bash

# someapp_%.bbappend
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI:append = " file://0001-fix-memory-leak.patch"

${PN} se expande al nombre del paquete (someapp en este caso). ${THISDIR}/${PN} apunta al subdirectorio someapp/ junto al archivo bbappend.

Patrón 2: Añadir un archivo de configuración

Despliega un archivo de configuración personalizado en el dispositivo objetivo.

meta-mylayer/
  recipes-core/
    busybox/
      busybox_%.bbappend
      files/
        custom-inittab

bash

# busybox_%.bbappend
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
SRC_URI:append = " file://custom-inittab"

do_install:append() {
    install -m 0644 ${WORKDIR}/custom-inittab ${D}${sysconfdir}/inittab
}

Patrón 3: Añadir un servicio systemd

Añade un archivo de servicio systemd a una aplicación existente para inicio automático. Consulta la guía de inicio automático con systemd para el tutorial completo de la receta.

meta-mylayer/
  recipes-example/
    myapp/
      myapp_%.bbappend
      files/
        myapp.service

bash

# myapp_%.bbappend
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
SRC_URI:append = " file://myapp.service"

SYSTEMD_SERVICE:${PN} = "myapp.service"
SYSTEMD_AUTO_ENABLE:${PN} = "enable"

FILES:${PN} += "${systemd_system_unitdir}/myapp.service"

do_install:append() {
    install -d ${D}${systemd_system_unitdir}
    install -m 0644 ${WORKDIR}/myapp.service ${D}${systemd_system_unitdir}/
}

Nota: este patrón asume que la receta .bb original ya incluye inherit systemd. La directiva inherit solo es válida en archivos .bb y .bbclass — no está oficialmente soportada en archivos .bbappend. Si la receta original no hereda la clase systemd, necesitarás modificar la propia receta en lugar de usar un bbappend.

Patrón 4: Cambiar opciones de compilación

Usa PACKAGECONFIG para modificar las opciones de compilación de una receta.

bash

# curl_%.bbappend
# Habilitar soporte OpenSSL
PACKAGECONFIG:append = " openssl"

# Deshabilitar soporte GnuTLS
PACKAGECONFIG:remove = "gnutls"

PACKAGECONFIG es un mecanismo de gestión de opciones soportado por muchas recetas. Las opciones disponibles se definen en el archivo .bb de la receta como entradas PACKAGECONFIG[xxx].

Para recetas basadas en autotools, también puedes añadir opciones de configuración directamente.

bash

EXTRA_OECONF:append = " --enable-my-feature"

Patrón 5: Añadir dependencias

Añade dependencias en tiempo de compilación o ejecución.

bash

# mypackage_%.bbappend

# Dependencia en tiempo de compilación
DEPENDS:append = " libssl"

# Dependencia en tiempo de ejecución (${PN} especifica qué paquete)
RDEPENDS:${PN}:append = " python3"

RDEPENDS requiere ${PN} porque es una variable por paquete. Sin ${PN}, BitBake no sabe a qué paquete pertenece la dependencia.

Solución de problemas comunes

bbappend no se está aplicando

bash

# Verifica si el bbappend es reconocido
bitbake-layers show-appends | grep someapp

# Verifica si la capa está registrada en bblayers.conf
bitbake-layers show-layers

Las causas más comunes son la discrepancia de versión (no usar %) y que la capa no esté registrada.

Los valores de las variables se ven incorrectos

bash

# Comando de depuración recomendado en Scarthgap
bitbake-getvar -r someapp SRC_URI
bitbake-getvar -r someapp FILESEXTRAPATHS

bitbake-getvar muestra el valor final de una variable y qué archivo lo estableció.

Archivo no encontrado (error do_fetch)

Normalmente es un error de configuración de FILESEXTRAPATHS.

¿Usaste := en vez de =?
¿Olvidaste los dos puntos finales :?
¿La ruta del directorio files/ coincide con lo que apunta FILESEXTRAPATHS?

Conclusión

bbappend es la forma correcta de personalizar recetas existentes en Yocto. Los elementos esenciales son pocos.

Nombra los archivos recipename_%.bbappend (usa el comodín %)
Para archivos adicionales, configura FILESEXTRAPATHS:prepend := "${THISDIR}/files:" (:= y los dos puntos finales son obligatorios)
Añade valores con :append (no olvides el espacio al inicio)
Extiende tareas con do_install:append() { ... }
Depura con bitbake-layers show-appends y bitbake-getvar

Una vez que domines lo básico, considera también optimizar tu entorno de compilación.

Para profundizar en bbappend y la personalización de recetas, estos libros son excelentes referencias. Yocto Project Customization se enfoca específicamente en patrones de diseño de capas personalizadas.

Yocto Project Customization for Linux (Apress, 2025)

Mastering Embedded Linux Development 4th Ed (2024)

Embedded Linux Development Using Yocto Project 3rd Ed (2023)

—

Qué es un archivo bbappend

Reglas de nomenclatura de archivos

Coincidencia exacta de versión

Uso del comodín % (Recomendado)

Verificar tu bbappend

Operaciones con variables

Añadir valores (:append)

Eliminar valores (:remove)

Sobrescribir valores

FILESEXTRAPATHS — Ruta de búsqueda para archivos adicionales

Extender tareas

5 patrones prácticos

Patrón 1: Aplicar un parche

Patrón 2: Añadir un archivo de configuración

Patrón 3: Añadir un servicio systemd

Patrón 4: Cambiar opciones de compilación

Patrón 5: Añadir dependencias

Solución de problemas comunes

bbappend no se está aplicando

Los valores de las variables se ven incorrectos

Archivo no encontrado (error do_fetch)

Conclusión

Uso del comodín `%` (Recomendado)