빌드 경계 지도
Zephyr 애플리케이션의 빌드는 workspace의 Git 상태, 보드와 애플리케이션 선택, CMake 구성, Kconfig와 Devicetree의 생성 결과, 컴파일·링크를 차례로 확인해야 이해된다. west는 이 작업을 위한 workspace 관리 명령과 Zephyr 확장 명령을 제공하지만, west build가 모듈을 자동으로 west update하는 것은 아니다.
아래 그림은 두 명령의 경계를 나누고 각 단계가 남기는 증거를 표시한다. 입력 설정이 곧 런타임 장치의 준비 상태라는 뜻은 아니다. 최종 이미지에서 코드가 실행되는지는 생성된 설정, 링크 결과, 보드의 실제 동작을 별도로 확인해야 한다.
workspace 동기화, 구성, 빌드, 보드 기록은 서로 다른 확인 지점이다. 작은 화면에서는 그림을 좌우로 스크롤해 읽을 수 있다.
west 명령 순서
아래는 Zephyr v3.7.0을 선택한 workspace에서 공식 nRF52840 DK 보드 표기를 사용한 실행 설명 예제다. 이 글을 만들면서 명령을 실행하거나 보드에 기록한 결과가 아니다.
west init -m https://github.com/zephyrproject-rtos/zephyr --mr v3.7.0 zephyrproject
cd zephyrproject
west update
cd zephyr
west build -b nrf52840dk/nrf52840 samples/hello_world
west build -t menuconfig
west flash
west init은 manifest 저장소를 선택해 workspace를 만들고, west update는 해당 manifest가 가리키는 프로젝트와 revision을 로컬에 맞춘다. west build는 지정된 애플리케이션과 보드로 CMake 구성을 만들고 빌드를 실행한다. 이미 build 디렉터리가 있으면 조건에 따라 증분 빌드를 하므로, 보드·입력을 바꿀 때는 기존 CMake cache를 함께 확인해야 한다.
보드 이름의 슬래시도 입력의 일부다. Zephyr v3.7.0의 nRF52840 DK 문서는 nrf52840dk/nrf52840을 사용한다. 기존 글의 nrf52840dk_nrf52840은 이 버전 문서의 빌드 대상 표기가 아니다. west build -t menuconfig는 이미 선택된 build 디렉터리의 Kconfig 설정 화면을 여는 빌드 타깃이고, west flash는 그 build의 runner 설정으로 보드에 기록한다.
애플리케이션 CMake와 manifest는 역할이 다르다
애플리케이션의 CMakeLists.txt는 Zephyr 빌드 시스템을 불러오고 애플리케이션 소스를 app 타깃에 붙인다. 기존 글의 유용한 최소 예제를 아래에 유지했다. 이 코드는 설명용 예제로, 고정 커밋의 파일을 그대로 인용한 발췌가 아니다.
cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_app)
target_sources(app PRIVATE src/main.c)
find_package(Zephyr)가 Zephyr 구성에 들어가며, target_sources(app ...)가 애플리케이션 소스를 빌드에 넣는다. 실제 구성은 보드 타깃, Kconfig fragment, Devicetree overlay와 모듈 검색 결과에 따라 달라진다.
저장소의 west.yml은 workspace의 프로젝트·revision을 설명한다. 애플리케이션의 CMake 파일도 아니고, 링크 결과물에 같은 이름으로 반드시 남는 파일도 아니다. 아래 YAML은 기존 글에서 가져온 별도 제품 manifest의 설명용 예제이며, Zephyr 원본 west.yml의 발췌가 아니다.
manifest:
projects:
- name: zephyr
revision: v3.7.0
url: https://github.com/zephyrproject-rtos/zephyr
import: true
import: true는 선택한 Zephyr revision의 west.yml에 정의된 모듈을 함께 불러옵니다. 이 항목이 없으면 이 예제는 Zephyr 프로젝트 하나만 선언합니다. 이런 제품 manifest를 쓴다면 west update 후 로컬 Zephyr checkout과 외부 모듈의 실제 revision을 확인한다. YAML의 선언만으로 빌드 디렉터리나 펌웨어 안에 해당 소스가 들어갔다고 증명되지는 않는다.
입력 뒤에 남는 생성 산출물
빌드 문제가 생겼을 때는 마지막으로 확인 가능한 산출물부터 되짚는다. 경로는 일반적인 단일 이미지 build 디렉터리 예시다. -d로 다른 빌드 디렉터리를 지정했다면 그 아래를 확인한다.
| 단계 | 대표 입력 | 확인할 증거 | 답할 질문 |
|---|---|---|---|
| Workspace 동기화 | manifest와 Git revision | west manifest, west list, 로컬 Git HEAD | 기대하던 모듈 revision이 실제 checkout에 있는가? |
| CMake 구성 | 보드·앱·CMake 변수 | build/CMakeCache.txt | 현재 build 디렉터리가 어느 보드와 앱을 가리키는가? |
| Kconfig 해석 | board defconfig, prj.conf, fragment | build/zephyr/.config, generated autoconf.h | 요청한 symbol의 최종 값과 의존 조건은 무엇인가? |
| Devicetree 해석 | board DTS와 overlay | build/zephyr/zephyr.dts, generated Devicetree header | 병합된 node/property가 기대한 값인가? |
| 컴파일·링크 | 생성된 빌드 규칙과 소스 | build/zephyr/zephyr.elf, zephyr.map | 원하는 코드와 section이 실제 이미지에 들어갔는가? |
| 보드 기록 | 빌드 이미지와 runner 선택 | build/zephyr/runners.yaml, west flash -H | 어느 runner가 어느 이미지를 기록하는가? |
원본 C 파일만 읽으면 가능한 구현을 알 수 있다. .config, zephyr.dts, generated headers, map/ELF를 함께 보면 선택된 이번 빌드를 확인할 수 있다. 이 구분이 기존 글의 가장 유용한 진단 습관이다.
실패를 단계별로 좁히는 표
| 증상 | 먼저 확인할 경계 | 확인 방법 | 다음 판단 |
|---|---|---|---|
| 모듈 경로 또는 헤더를 찾지 못함 | manifest / workspace | west list와 로컬 project revision 비교 | manifest 전환 후 west update 여부 확인 |
| 보드를 찾지 못함 | board target / CMake cache | west boards, west build -b nrf52840dk/nrf52840 ... | v3.7.0의 qualifier와 build 디렉터리 재사용 확인 |
| 설정한 기능이 빠짐 | Kconfig / Devicetree 생성 | .config와 zephyr.dts 비교 | 의존 조건과 overlay 병합 결과 확인 |
| 컴파일 또는 링크 실패 | 생성 규칙 / 소스 | 첫 진단 메시지, zephyr.map 또는 미생성 결과 | 설정 누락과 코드 오류를 분리 |
| 빌드는 성공했지만 기록 실패 | runner / 연결 | west flash -H와 runner 설정 확인 | 프로브·포트·이미지 선택 확인 |
빌드 성공 뒤 보드에서 기능이 보이지 않는다면 곧바로 west 결함으로 단정하지 않는다. 먼저 해당 symbol/node와 링크된 코드가 이미지에 들어갔는지 확인하고, 그 뒤 장치 초기화와 런타임 로그로 넘어간다.
sysbuild는 여러 이미지의 바깥 경계다
west build --sysbuild는 하나 이상의 Zephyr 빌드와 필요한 다른 빌드를 상위 빌드에서 관리한다. 예를 들어 MCUboot와 애플리케이션을 함께 구성할 때 각 Zephyr image/domain은 자체 설정과 결과물을 가진다. 한 이미지의 .config를 전체 결과로 읽으면 다른 이미지의 설정을 놓친다.
west build -b nrf52840dk/nrf52840 --sysbuild samples/hello_world
west build --sysbuild --domain hello_world
west flash --domain hello_world
첫 줄은 설명용 명령이며, 두 번째와 세 번째 줄의 hello_world domain은 해당 sysbuild 구성에 실제로 존재할 때 사용하는 예시다. sysbuild는 각 이미지의 runners.yaml을 통합 관점의 domains.yaml로 다룬다. 기록 전에 어떤 domain의 이미지를 선택했는지 확인한다.
고정 버전 근거와 출처 경계
이 글의 동작 설명은 Zephyr 공식 문서 3.7.0과 Git 태그 v3.7.0의 peeled commit 36940db938a8f4a1e919496793ed439850a221c2을 기준으로 한다. 새 원문 코드 줄을 인용하지 않았으므로 위 명령과 CMake 조각을 upstream 발췌로 해석하면 안 된다.
Linux 빌드와 비교해 확인할 점
Linux와 마찬가지로 소스 파일이 있다는 사실만으로 특정 바이너리에 포함되었다고 결론 내릴 수 없다. Zephyr에서는 보드 타깃, Kconfig, Devicetree와 CMake의 조합이 작은 펌웨어 이미지를 강하게 제한하므로, 최종 .config와 merged DTS를 비교하는 일이 특히 중요하다. 이는 빌드 입력을 검증하는 방법의 차이이며, 모든 Zephyr 객체가 동일한 런타임 상태 머신을 따른다는 뜻은 아니다.
재현 기록과 점검 순서
빌드 오류 보고에는 Zephyr commit 또는 태그, manifest 프로젝트 revision, west build 전체 명령, 보드 qualifier, build 디렉터리, .config, zephyr.dts, 첫 오류 메시지와 생성 이미지 이름을 같이 남긴다. 보드 기록 문제라면 runner와 연결 프로브도 추가한다. west flash -H는 정보를 표시하기 전에 빌드를 다시 수행할 수 있으므로, 재현 로그에서는 이 동작도 구분한다. 이렇게 남기면 소스의 가능성과 실제 이미지의 선택을 뒤섞지 않고 재현할 수 있다.
west list로 workspace 프로젝트를 확인한다.build/CMakeCache.txt에서 보드·앱·빌드 디렉터리를 확인한다..config와zephyr.dts에서 설정과 하드웨어 병합 결과를 확인한다.zephyr.map과 ELF에서 링크된 코드와 section을 확인한다.- 기록 단계에서는
west flash -H로 runner 선택을 확인한다.