1. 다운로드, 모듈 발견, 이미지 포함은 서로 다른 사건이다
west.yml의 projects: 항목은 west가 관리하는 Git 저장소를 정의한다. west update는 해당 revision을 작업공간에 가져온다. 그러나 그 저장소가 Zephyr 모듈인지 결정하는 것은 별도의 메타데이터와 통합 파일이다. 발견된 모듈의 CMake·Kconfig가 구성에 들어가도, 조건부 Kconfig가 꺼진 소스는 빌드되지 않을 수 있다. net-tools 같은 도구용 west 프로젝트는 펌웨어 모듈일 필요가 없다.
화살표는 처리 경로이며 모든 west 프로젝트가 마지막 상자에 이른다는 뜻은 아닙니다. 좁은 화면에서는 가로로 이동하세요.
projects:에 URL·revision·path를 기록어디서 어떤 저장소를 가져올지west update가 해당 Git 프로젝트를 배치파일이 있다는 사실만 성립| 질문 | 확인 대상 | 그것만으로 아직 모르는 것 |
|---|---|---|
| 저장소가 배치됐나? | west.yml, west list, 로컬 path | Zephyr module로 분류됐는지 |
| 모듈로 발견됐나? | zephyr/module.yml(또는 .yaml) 또는 fallback 통합 파일 | 기능 설정이 켜졌는지 |
| 소스가 이미지에 있나? | 생성된 .config, CMake 대상과 링크 산출물 | 런타임 기능이 실제로 성공하는지 |
근거: 3.7.0 Modules vs west projects, 3.7.0 모듈 발견 경로, 3.7.0 west update 역할.
2. zephyr/module.yml은 저장소와 빌드 파일의 연결표다
3.7.0 문서에서 모듈의 기본 위치는 저장소 루트 아래 zephyr/module.yml이다. name을 명시하면 checkout 폴더명이 바뀌어도 모듈 이름은 안정된다. build.cmake는 CMakeLists.txt가 있는 디렉터리, build.kconfig는 Kconfig 파일을 가리킨다. 생략하면 각각 zephyr, zephyr/Kconfig가 기본값이다.
파일 배치 예시와 빌드에서 해석하는 역할입니다. 작은 화면에서는 위아래로 이어집니다. 특정 제품 저장소의 실제 파일을 복사한 것은 아닙니다.
foo-lib/
├── include/foo_lib/api.h
├── src/filter.c
└── zephyr/
├── module.yml
├── CMakeLists.txt
└── Kconfigmodule.yml은 모듈 이름과 통합 파일 경로를 지정합니다.
Kconfig는 빌드 선택지를 정의합니다.
CMakeLists.txt는 선택된 소스를 라이브러리로 추가합니다.
src/filter.c는 선택·컴파일 전까지 단지 저장소의 파일입니다.
가령 모듈 이름이 foo-lib라면 CMake/Kconfig 변수 이름에는 대문자와 밑줄을 쓰는 ZEPHYR_FOO_LIB_MODULE_DIR이 생긴다. 모듈 내부 CMake는 ZEPHYR_CURRENT_MODULE_DIR로 자신의 루트를 참조할 수 있다. 다른 폴더명으로 checkout되거나 EXTRA_ZEPHYR_MODULES로 덮어도 파일 상대경로를 안정적으로 다룰 수 있다.
| 키 | 3.7.0의 의미 | 확인 실수 |
|---|---|---|
name | 빌드에서 참조할 모듈 이름 | 생략하면 checkout 디렉터리명이 이름이 됨 |
build.cmake | CMakeLists.txt가 있는 디렉터리; 기본 zephyr | 파일 경로를 적거나 잘못된 폴더를 지정 |
build.kconfig | Kconfig 파일; 기본 zephyr/Kconfig | CMake 포함과 설정 선택을 같은 것으로 취급 |
build.depends | 필요한 다른 모듈의 존재·처리 순서 요구 | 소스 링크 의존성과 혼동 |
build.settings.*_root | 보드·SoC·DTS·snippet 등의 추가 루트 | 루트 경로와 실제 하위 폴더 구조 불일치 |
3. west 없이도 모듈을 넣을 수 있고, west 프로젝트여도 빠질 수 있다
기본 경로에서 Zephyr 빌드는 west list로 프로젝트 경로를 얻고, 각 경로에 zephyr/module.yml이 있는지 확인한다. v3.7.0 발견 스크립트는 zephyr/module.yaml도 읽지만 공식 문서의 기본 표기는 .yml이다. 메타데이터 파일이 둘 다 없다면 zephyr/CMakeLists.txt와 zephyr/Kconfig가 둘 다 있는지 검사한다. 이 조건도 충족하지 못하면 그 west 프로젝트는 모듈 목록에 들어가지 않는다. 이 fallback은 문서와 실제 scripts/zephyr_module.py의 process_module()에 함께 나타난다.
west를 쓰지 않으면 ZEPHYR_MODULES에 모듈 디렉터리 절대경로 목록을 줄 수 있다. 이 값을 명시하면 west 기반 자동 목록을 그대로 이어 붙이는 방식이 아니므로 필요한 모듈 전체를 고려해야 한다. 기존 west 모듈 목록에 한 저장소를 추가하려는 경우에는 EXTRA_ZEPHYR_MODULES가 의도에 맞는다. 3.7.0 문서는 같은 이름이 west와 EXTRA 양쪽에 있으면 EXTRA 쪽이 우선한다고 설명한다.
각 선택의 입력과 유지되는 범위를 함께 읽으세요. 좁은 화면에서는 카드가 세로로 이어집니다.
west list의 프로젝트를 스캔module.yml 또는 fallback 쌍이 있는 경로만 모듈EXTRA_ZEPHYR_MODULESwest가 찾은 모듈에 별도 경로 추가같은 모듈 이름이면 추가 경로가 우선ZEPHYR_MODULES필요한 모듈 경로 목록을 직접 제공west 없이도 가능; 목록의 완전성은 앱 책임| 방법 | 모듈 후보의 출처 | 주의할 경계 |
|---|---|---|
| west 기본 | 현재 workspace 프로젝트 | project가 있다고 module이 되는 것은 아님 |
EXTRA_ZEPHYR_MODULES | west 후보 + 별도 절대경로 | 동일 이름 우선순위와 revision 확인 |
ZEPHYR_MODULES | 직접 지정한 경로 목록 | 자동 목록의 다른 필수 모듈을 빠뜨릴 수 있음 |
| west 없는 빌드 | ZEPHYR_MODULES 또는 모듈 없음 | 필요한 Kconfig·코드가 외부에 있으면 빌드 실패 가능 |
근거: 3.7.0 west 기반 판별, west 없는 목록 지정, EXTRA의 추가·우선 규칙, v3.7.0 발견 스크립트.
4. 발견된 모듈도 설정이 꺼지면 그 소스는 컴파일되지 않는다
다음은 설명용 최소 배치다. 정확히 이 파일들을 실제 보드에서 빌드했다는 뜻은 아니다. 경로는 위 그림 2의 저장소 구조에 맞춘다. module.yml은 모듈 통합 경로를 고르고, Kconfig의 FOO_LIB은 앱이 기능을 선택하도록 하며, CMake는 그 값이 켜졌을 때만 filter.c를 라이브러리 소스로 넣는다.
# foo-lib/zephyr/module.yml
name: foo-lib
build:
cmake: zephyr
kconfig: zephyr/Kconfig
# foo-lib/zephyr/Kconfig
config FOO_LIB
bool "Foo filter helper"
default n
# foo-lib/zephyr/CMakeLists.txt
if(CONFIG_FOO_LIB)
zephyr_library()
zephyr_library_sources(${ZEPHYR_CURRENT_MODULE_DIR}/src/filter.c)
endif()
# application/prj.conf — 기능을 실제로 선택할 때
CONFIG_FOO_LIB=ymodule.yml과 CMakeLists.txt가 보이는데도 기능이 없으면 먼저 생성된 build/zephyr/.config에서 CONFIG_FOO_LIB=y가 확정됐는지 확인한다. 그 다음 CMake가 filter.c를 대상에 추가했는지 빌드 로그 또는 컴파일 명령에서 살핀다. 최종 링크 포함은 생성 산출물에서 확인한다. 모듈이 “발견”됐다고 해서 개별 기능이 “선택”된 것은 아니다.
| 저장소·통합 파일 | 설정·CMake | 예상 결과 |
|---|---|---|
| west 프로젝트만 존재 | module.yml·fallback 쌍 없음 | 모듈로 발견되지 않음 |
| 모듈로 발견됨 | CONFIG_FOO_LIB=n | 위 예시의 filter.c는 대상에 추가되지 않음 |
| 모듈로 발견됨 | CONFIG_FOO_LIB=y | 위 예시에서 filter.c가 라이브러리 소스가 됨 |
| 모듈 CMake만 있음 | metadata도 Kconfig도 없음 | fallback 조건을 충족하지 못함 |
근거: 3.7.0 기본 통합 파일 경로, 모듈 CMake/Kconfig 변수, v3.7.0 process_module().
5. “가져왔는데 없다”를 한 단계씩 좁힌다
저장소가 없으면 먼저 manifest와 west update 결과를 본다. 저장소가 있으면 모듈 판별 파일 경로를 확인한다. 모듈이 발견되면 생성된 Kconfig 설정과 CMake 소스 선택을 본다. 링커까지 진행했는데 기능이 없으면 그때 런타임 초기화·API 경로를 살핀다. 이 순서라면 모든 문제를 “west가 모듈을 못 읽는다”로 뭉뚱그리지 않는다.
| 증상 | 먼저 볼 증거 | 다음 질문 |
|---|---|---|
| 저장소 디렉터리가 없음 | manifest의 projects·revision, west list | 현재 workspace의 프로젝트인가? |
| 저장소는 있는데 모듈로 안 보임 | zephyr/module.yml/module.yaml 또는 CMakeLists/Kconfig 쌍 | 파일 위치·이름이 3.7.0 탐색 규칙과 맞나? |
| 모듈 이름/경로가 예상과 다름 | name, ZEPHYR_*_MODULE_DIR, EXTRA 우선순위 | 폴더명 기본값이나 중복 이름인가? |
| Kconfig 옵션이 없음 | build.kconfig 위치·생성 설정 | 해당 Kconfig 파일이 빌드에 포함됐나? |
| 옵션은 켰는데 코드가 없음 | build/zephyr/.config와 CMake 조건 | 소스 대상·최종 링크까지 이어졌나? |
경로 두 개를 혼동하지 않기: EXTRA_ZEPHYR_MODULES는 발견할 모듈 경로를 추가한다. build.settings.board_root 같은 module.yml 항목은 발견된 모듈 내부의 보드·SoC·DTS 자료 위치를 추가한다. 후자는 모듈 자체를 찾는 입력이 아니다.
6. 내 앱의 외부 코드와 Zephyr 기본 manifest 편입은 범위가 다르다
제품 앱의 사설 모듈을 EXTRA_ZEPHYR_MODULES나 자체 manifest로 연결하는 것과, Zephyr 프로젝트의 기본 manifest에 새 외부 저장소를 넣는 것은 별도의 결정이다. 후자는 Zephyr 3.7.0 문서에서 독립 저장소 수명주기, 유지보수자, 라이선스, 통합 테스트, 프로젝트 심의 절차를 요구한다. 모든 앱 모듈이 기본 manifest에 들어가야 한다는 뜻은 아니다.
외부 모듈의 module.yml은 build.depends로 다른 모듈의 존재와 처리 순서를 요구할 수 있다. 다만 이것만으로 사용한 모든 심볼이 링크되거나 런타임 초기화 순서까지 검증되는 것은 아니다. 모듈 간 경계는 고정 revision, Kconfig 선택, 실제 빌드 결과와 통합 테스트를 함께 남겨야 재현 가능하다.
7. Zephyr v3.7.0에 고정한 근거
본문의 모듈 판별 규칙, YAML 키, CMake 변수 이름과 west 경로는 고정된 3.7.0 문서 및 v3.7.0 태그의 scripts/zephyr_module.py와 대조했다. 예시의 foo-lib은 설명을 위해 만든 가상 저장소다. Zephyr 앱을 실제로 빌드·실행한 기록은 아니다.