.conf와 .overlay를 재사용 가능하게 묶는다. 두 파일 자체의 의미는 Kconfig와 Devicetree 글에서 이어진다.1. Snippet은 선택되는 빌드 입력이지 새 설정 언어가 아니다
앱마다 같은 디버그 옵션과 보드 주변장치 조정을 복사한다면 수정 위치가 늘어난다. 3.7.0의 snippet은 이름이 붙은 snippet.yml에 빌드 입력을 모아 west build -S <name>으로 고른다. append.EXTRA_CONF_FILE은 Kconfig fragment를, append.EXTRA_DTC_OVERLAY_FILE은 Devicetree overlay를 추가한다. YAML이 곧바로 Kconfig 심볼이나 DTS 노드를 정의하는 것은 아니다.
화살표는 처리 관계를 나타냅니다. 결과값은 다른 설정과 보드 조건을 함께 해석한 뒤 생성 파일에서 확인합니다.
-S trace-log또는 CMake의 SNIPPET 이름 목록snippet.yml검색 root 아래 snippets/와 이름 확인.conf fragment.overlay 파일YAML의 append가 기존 빌드 입력에 경로를 더함.configDevicetree →
zephyr.dts심볼 의존성과 보드 노드까지 검증| 수단 | 결정하는 것 | 확인 파일·증거 |
|---|---|---|
| Snippet | 어떤 fragment·overlay 등을 추가할지 | snippet.yml와 선택한 이름 |
| Kconfig | 심볼의 타입·의존성과 최종 값 | 단일 이미지 기본 경로 build/zephyr/.config |
| Devicetree | 하드웨어 노드·속성의 최종 트리 | 단일 이미지 기본 경로 build/zephyr/zephyr.dts |
| Board 선택 | 기준 하드웨어 대상 | -b 인수와 생성된 보드 설정 |
2. 파일이 있어도 탐색 root 밖이면 이름으로 찾을 수 없다
3.7.0은 SNIPPET_ROOT의 각 경로 아래 snippets/에서 중첩된 snippet.yml을 찾는다. Zephyr 저장소와 앱 소스 디렉터리는 기본 root다. 다른 디렉터리는 CMake 시간에 추가할 수 있다. 외부 모듈은 자신의 zephyr/module.yml에 build.settings.snippet_root를 지정해 보유한 snippet을 노출할 수 있다. 모듈이 발견되도록 설정했다고 해서 snippet까지 발견되는 것은 아니다.
각 카드의 root 아래에 snippets/<name>/snippet.yml이 들어갑니다. 화면이 좁으면 가로로 이동하세요.
SNIPPET_ROOTzephyr/snippets/…/snippet.yml내장 snippetSNIPPET_ROOTapp/snippets/…/snippet.yml앱 가까이에 둔 재사용 입력SNIPPET_ROOT 또는 발견된 모듈의 snippet_root<root>/snippets/…/snippet.yml| 출처 | 설정 | 먼저 확인할 것 |
|---|---|---|
| Zephyr 내장 | 기본 root | v3.7.0에 실제 그 이름이 있는가? |
| 앱 자체 | 앱 디렉터리가 기본 root | snippets/ 아래 정확한 snippet.yml인가? |
| 별도 디렉터리 | SNIPPET_ROOT에 root 추가 | root 자체를 줬는가, snippets/를 중복해서 줬는가? |
| 외부 모듈 | build.settings.snippet_root | 모듈 발견과 root 경로가 모두 성립했는가? |
3.7.0 문서의 경로 표기 확인: snippet 작성 안내의 모듈 예시는 settings: snippet_root: .를 보여 주지만, 같은 버전의 모듈 메타데이터 명세와 태그된 스키마·처리 코드에서는 build.settings.snippet_root가 실제 중첩 위치다. 모듈 파일을 작성할 때 아래의 중첩 구조를 사용한다.
# <module>/zephyr/module.yml — 모듈 자체가 먼저 발견되어야 함
build:
settings:
snippet_root: . # <module>/snippets/ 아래 검색3. 작은 snippet 하나는 파일 두 개면 시작할 수 있다
다음은 앱 내부에 둔 설명용 로그 옵션 예시다. trace-log.conf는 기존 Kconfig 심볼 값을 요청한다. snippet.yml은 그 파일을 추가하는 연결표다. 다른 보드나 앱의 심볼 의존성이 값을 바꿀 수 있으므로 생성된 .config에서 확인해야 한다.
# app/snippets/trace-log/snippet.yml
name: trace-log
append:
EXTRA_CONF_FILE: trace-log.conf
# app/snippets/trace-log/trace-log.conf
CONFIG_LOG=y
# 앱을 새 빌드 디렉터리에 구성하는 예
west build -b qemu_x86 -S trace-log appDevicetree 변경도 필요하면 같은 append 아래 EXTRA_DTC_OVERLAY_FILE: some.overlay를 더하고, overlay 파일을 snippet.yml 옆에 둔다. 3.7.0 문서에서 이 경로는 snippet.yml이 있는 디렉터리를 기준으로 해석된다. Overlay의 노드·label은 다른 입력과 충돌하지 않게 snippet 이름을 접두사로 쓰고, 대상 보드에 존재하는 노드를 참조해야 한다.
| 3.7.0 키 | 추가 대상 | 검증할 결과 |
|---|---|---|
name | -S로 고를 이름 | 파일을 찾고 이름이 일치하는가? |
append.EXTRA_CONF_FILE | 앱 Kconfig fragment | 최종 .config의 심볼 값 |
append.EXTRA_DTC_OVERLAY_FILE | Devicetree overlay | 최종 zephyr.dts의 노드·속성 |
append.DTS_EXTRA_CPPFLAGS | Devicetree 전처리 인수 | 전처리 결과와 DTS 생성 오류 |
boards | 보드 이름·정규식에 조건부 입력 | 현재 -b가 조건에 맞는가? |
근거: 3.7.0 YAML 기본, overlay 상대경로, .conf 상대경로.
4. 여러 snippet의 순서와 보드 조건은 입력을 바꾼다
-S foo -S bar처럼 여러 이름을 주면 3.7.0은 적은 순서대로 처리한다. 같은 설정을 둘이 지정하면 뒤에 처리한 snippet의 값이 최종 입력을 정한다는 것이 3.7.0 작성 안내의 규칙이다. 다만 Kconfig 의존성과 Devicetree의 유효성 검사는 계속 적용되므로 실제 생성 결과를 확인해야 한다. 순서를 바꿔 비교할 때는 서로 다른 빌드 디렉터리를 쓰면 캐시와 이전 생성물을 혼동하지 않는다.
boards: 아래에는 특정 보드 이름 또는 전체 이름에 맞는 정규식을 두고 추가 설정을 지정할 수 있다. 이 설정은 snippet의 공통 append에 더해 적용된다. v3.7.0의 실제 조건 생성 코드는 ${BOARD}${BOARD_QUALIFIERS}를 비교하므로 SoC·CPU 등 qualifiers가 붙는 대상은 그 전체 문자열을 기준으로 해야 한다. 정규식도 전체 문자열에 맞도록 양 끝이 고정된다. 이 비교에 BOARD_REVISION은 포함되지 않으므로 revision별 분기가 자동으로 생긴다고 가정하지 않는다.
| 빌드 선택 | 추가 입력 | 주의할 점 |
|---|---|---|
-S foo | foo 공통 설정 | foo의 파일이 탐색 root 안에 있어야 함 |
-S foo -S bar | foo 뒤 bar | 중복 설정의 처리 순서 확인 |
-b qemu_x86 -S foo | foo 공통 + qemu_x86 조건이 있다면 추가 | 보드 조건은 공통 설정을 대체하지 않음 |
-DSNIPPET="foo;bar" | CMake를 직접 호출할 때의 이름 목록 | root와 보드도 별도로 지정해야 함 |
5. -S와 -b, --sysbuild는 다른 층의 선택이다
보드 대상은 -b가 정한다. Snippet은 그 빌드가 읽을 추가 설정 파일을 고른다. --sysbuild는 하나 이상의 이미지 빌드를 관리할 상위 빌드 시스템을 선택한다. 3.7.0에서 Sysbuild의 이미지 선택과 설정은 자체 Kconfig와 SB_CONFIG_* 이름공간을 사용한다. 앱용 EXTRA_CONF_FILE을 넣었다고 해서 모든 이미지나 Sysbuild 자체에 같은 값이 적용됐다고 해석하면 안 된다.
아래 카드는 명령 인수의 책임 경계입니다. 선택한 보드·snippet 조합이 실제로 유효한지는 생성 결과로 검증합니다.
-b Board기준 하드웨어·보드 설정 선택snippet의 boards: 조건에도 영향-S Snippet이름이 가리키는 fragment·overlay 추가Kconfig·DTS의 최종 값은 다시 확인--sysbuild여러 이미지 또는 domain의 빌드 조정SB_CONFIG_*와 이미지별 설정 범위 구분따라서 “MCUboot 이미지를 더한다”는 문제와 “앱의 로그 옵션을 여러 프로젝트에서 재사용한다”는 문제는 같은 설정 파일 하나로 해결할 범위가 아니다. Sysbuild가 활성화된 빌드라면 최상위 구성과 각 이미지의 생성 설정을 따로 확인한다.
근거: 3.7.0 snippet 목적, 3.7.0 Sysbuild 이미지·domain 정의, 3.7.0 설정 이름공간.
6. “적용되지 않는다”는 문제는 단계별 생성물로 좁힌다
먼저 같은 빌드에서 사용한 -S·-b·SNIPPET_ROOT를 기록한다. 그다음 snippet 발견, YAML과 파일 경로, 보드 조건, 최종 Kconfig·DTS를 차례로 확인한다. CONFIG_LOG=y를 요청했어도 최종 .config에 없으면 snippet 발견 실패와 Kconfig 의존성 문제를 구별해야 한다.
| 증상 | 먼저 볼 증거 | 다음 질문 |
|---|---|---|
| 이름을 찾지 못함 | -S 이름, SNIPPET_ROOT, snippets/…/snippet.yml | 검색 root 아래 정확히 배치됐나? |
| YAML은 보이는데 파일을 못 읽음 | append 키·상대경로 | 파일이 snippet.yml 곁에 있나? |
| 특정 보드에서만 빠짐 | -b와 boards: 키 | 보드 이름 또는 정규식이 맞나? |
| 심볼이 기대값이 아님 | 기본 경로 build/zephyr/.config | 다른 fragment 순서·Kconfig 의존성은? |
| DTS 노드가 기대와 다름 | 기본 경로 build/zephyr/zephyr.dts | overlay 대상 노드·중복 속성은? |
| Sysbuild에서 범위가 다름 | 최상위와 각 image의 생성 설정 | 앱 설정과 SB_CONFIG_*를 혼동했나? |
표의 build/zephyr/… 경로는 단일 이미지의 기본 빌드 디렉터리 예시다. -d로 디렉터리를 바꾸거나 Sysbuild가 이미지를 분리하면 해당 빌드의 생성 경로를 확인한다.
7. Zephyr v3.7.0에 고정한 근거
3.7.0 문서에서 snippet이 지원하는 파일·키와 선택 명령을 확인하고, 모듈의 snippet_root 중첩 위치는 같은 태그의 메타데이터 스키마와 교차 확인했다. 이 글의 도식과 표는 새로 구성한 설명이며 특정 보드의 실제 빌드 측정값은 아니다.