bitbake bbappend, 레시피를 덮지 않고 고치려면

업스트림·벤더 레이어의 .bb를 통째로 복사해 고치면, 다음 버전 머지마다 수동 재병합이 됩니다. Yocto Development Tasks Manual은 전체 레시피 오버레이를 피하고 .bbappend로 필요한 부분만 확장·오버라이드하라고 합니다. BitBake append는 대응 .bb와 같은 루트 이름을 쓰며, 정보는 원본 레시피에 붙거나 덮어씁니다.

이 글은 **경로는? · FILESEXTRAPATHS는? · 우선순위는?**만 다룹니다. yocto-systemd 글은 inherit systemd·SYSTEMD_SERVICE·유닛 설치 경로(이미지 init) 축입니다. 여기서는 패치·추가 파일·변수 조정을 레시피 복사 없이 넣는 축입니다. 특정 보드 후기·창작 시리얼 스토리는 없습니다.

근거: Understanding and Creating Layers (§3.5 Appending…, §3.6 Prioritizing…), Yocto terms — Append Files.

경로는?

한 줄 답: 레이어 안에서 원본과 같은 recipes-* 하위 경로·같은 루트 파일명으로 .bbappend를 둡니다. 버전은 맞추거나, %는 .bbappend 바로 앞에만 씁니다.

이름 규칙(문서 요지):

원본 레시피	append 예	의미
`someapp_3.1.bb`	`someapp_3.1.bbappend`	버전 고정 매칭
`someapp_6.2.bb` 등 6.*	`someapp_6.%.bbappend`	메이저(여기선 6) 유지 시 마이너 포괄
(대응 `.bb` 없음)	—	파싱 시작 시 에러. 이름 맞추기·`BBMASK`·폐기

레이아웃 스케치(개념 — formfactor 문서 예와 같은 패턴):

meta-mylayer/
  conf/layer.conf
  recipes-bsp/formfactor/
    formfactor_0.0.bbappend          # 원본 meta/.../formfactor_0.0.bb 에 대응
    formfactor/                      # FILESEXTRAPATHS가 가리킬 디렉터리
      machconfig                 # 또는 machine 서브디렉터리(아래)

실무 체크:

루트 이름 일치 — foo_1.2.bb ↔ foo_1.2.bbappend. 확장자만 다릅니다.
버전 업 — 원본이 foo_1.3.bb로 바뀌면 append도 이름을 맞추거나 % 범위를 재검토합니다. 문서: 이름 불일치는 BitBake가 startup error로 잡습니다.
% 위치 — someapp_6.%.bbappend처럼 접미사 직전만. 경로 중간·앞쪽 와일드카드는 해당되지 않습니다.
경로 미러 — 원본이 recipes-core/base-files/면 커스텀 레이어도 같은 recipes-core/base-files/ 아래에 둡니다. bitbake-layers show-appends로 매핑을 확인합니다.
변수만 바꿀 때 — 추가 file://가 없으면 FILESEXTRAPATHS 없이도 append만으로 SRC_URI:append, EXTRA_OECONF:append 등이 가능합니다(문서: 많은 append는 파일 경로 확장 없음).

vs yocto-systemd: 그 글의 “파일은 어디에?”는 이미지 안 ${D}${systemd_system_unitdir} 입니다. 이 절의 “경로”는 메타데이터 트리에서 .bbappend·files 디렉터리를 어디에 두느냐입니다.

FILESEXTRAPATHS는?

한 줄 답: append에서 file:// 패치·설정 파일을 찾게 하려면 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"(또는 ${BPN})로 검색 경로를 앞에 붙입니다. :=·끝 콜론·:prepend가 핵심입니다.

문서가 권하는 최소 형태:

# meta-mylayer/recipes-bsp/formfactor/formfactor_0.0.bbappend
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"

포인트:

THISDIR — BitBake가 정의. 직접 설정하지 않습니다. append 파일이 있는 디렉터리로 펼쳐집니다.
:=(즉시 확장) — THISDIR 참조 때문에 즉시 대입이 중요합니다. 늦게 펼치면 경로가 어긋날 수 있습니다.
끝 : — FILESPATH식 콜론 리스트를 유지합니다.
:prepend — 최종 목록에서 우리 경로가 먼저 검색되게 합니다.
${PN} vs ${BPN} — 공식 예는 formfactor에 ${PN}, best-practice 절에는 ${BPN}도 씁니다. 패키지 이름에 접미가 붙는 레시피는 ${BPN}(베이스 이름) 쪽이 안전한 경우가 많습니다. bitbake -e <recipe> | grep ^FILESEXTRAPATHS=로 확인합니다.
머신 한정 파일 — 문서: 파일을 ${THISDIR}/${PN}/ 루트에만 두면 그 레이어가 켜진 모든 머신에 잡힐 수 있습니다. 특정 머신만이면 ${PN}/<machine>/ 서브디렉터리에 두고 FILESOVERRIDES가 고르게 합니다.

추가 파일까지 넣는 패턴(문서 xserver-xf86-config 요지):

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

SRC_URI:append:mymachine = " file://extra.conf"

do_install:append:mymachine() {
    install -d ${D}${sysconfdir}/
    install -m 0644 ${UNPACKDIR}/extra.conf ${D}${sysconfdir}/
}

검증:

bitbake-layers show-appends | less
# 또는 레시피 환경에서 경로 확인
bitbake -e <recipe-name> | grep -E '^FILESEXTRAPATHS='

우선순위는?

한 줄 답: 같은 이름 .bb가 여러 레이어에 있으면 BBFILE_PRIORITY 숫자가 큰 레이어의 레시피가 이깁니다. 같은 레시피에 append가 여러 개면 우선순위가 적용 순서에도 영향을 줍니다. 높은 우선순위 레이어의 :prepend가 나중에 적용되어 FILESEXTRAPATHS 앞쪽에 남습니다.

conf/layer.conf 요지:

# bitbake-layers create-layer 기본 예: priority 6
BBFILE_PRIORITY_mylayer = "6"

정리 표:

상황	동작(문서)
동일 레시피 이름, 여러 레이어	더 큰 `BBFILE_PRIORITY`의 `.bb` 사용
동일 레시피에 여러 `.bbappend`	우선순위가 적용 순서에 영향
`:prepend` + 파일 검색	높은 우선순위 append가 나중에 prepend → 경로가 리스트 앞
`.conf` / `.bbclass`	레이어 priority가 현재는 우선순위에 쓰이지 않음(문서 명시)
낮은 PV + 높은 priority	가능 — 높은 priority의 낮은 버전이 이길 수 있음

확인 명령:

bitbake-layers show-layers
bitbake-layers show-appends
bitbake-layers show-overlayed

충돌 완화:

원본 .bb를 복사해 덮지 않기 — append로 변수·파일만 조정(best practice).
커스텀 레이어 priority를 BSP/distro보다 의도에 맞게 두고, show-layers로 숫자 확인.
append끼리 FILESEXTRAPATHS가 꼬이면 -e로 어느 레이어가 앞에 붙었는지 보고, 필요 시 우선순위·:append/오버라이드를 정리.
더 이상 필요 없는 orphan append는 이름 맞추기 또는 BBMASK(문서가 허용하는 우회).

FAQ

yocto-systemd 글과 무엇이 다른가요?

그 글은 레시피에서 systemd 유닛을 패키징·이미지 init을 켜는 방법입니다. 이 글은 upstream .bb를 복사하지 않고 .bbappend로 패치·파일·변수를 붙이는 경로·FILESEXTRAPATHS·레이어 우선순위입니다. systemd 유닛을 남의 레시피에 넣으려면 보통 이 글의 append + 그 글의 inherit systemd 조합이 됩니다.

`${PN}` 디렉터리에 파일을 안 넣으면?

FILESEXTRAPATHS만 있고 실제 파일이 없거나, SRC_URI에 file://를 안 넣으면 fetch가 기대 파일을 못 찾거나 아무 파일도 추가하지 않습니다. 경로 prepend와 SRC_URI(및 설치 태스크) 를 같이 맞춥니다.

`%`와 정확한 버전 중 어떤 것을?

자주 올리는 마이너만 따라가려면 _.%.bbappend가 편합니다. 메이저 점프·호환 깨짐이 있으면 정확한 버전 append로 강제해, 업그레이드 때 이름을 맞추며 내용을 재검토합니다.

전체 레시피를 레이어에 복사하는 경우는?

문서 best practice는 피하라입니다. 불가피한 fork면 유지 비용을 감수하고, 가능하면 차분을 append로 되돌립니다.

출처 (Sources)

Yocto Dev Manual — Understanding and Creating Layers — §3.2 best practices(오버레이 금지·FILESEXTRAPATHS), §3.5 .bbappend, §3.6 BBFILE_PRIORITY, bitbake-layers
Yocto Ref Manual — Terms (Append Files / Layer)
인접 축: yocto-systemd — inherit systemd·유닛 설치·INIT_MANAGER(이 글과 분리)