[Yocto 시리즈 6] local.conf와 bblayers.conf 이해 — 빌드를 조종하는 두 파일

5회차에서 source oe-init-build-env가 자동으로 만들어 준 build/conf/local.conf와 bblayers.conf, 기억나시죠? 그때는 손대지 않고 넘어갔지만, 실무에서 이 두 파일은 빌드 시간·디스크 사용량·재현성을 좌우하는 조종석이에요. 이번 회차에서는 이 두 설정 파일과 그 안의 핵심 변수들을 하나씩 뜯어보고, 소스를 더 빠르고 안정적으로 받는 미러 설정까지 정리합니다. 개념 편이 아니라 "빌드가 느리다·디스크가 찬다" 같은 실제 고민을 푸는 회차예요.

 📑 목차

• 1. 빌드를 조종하는 두 파일 — local.conf와 bblayers.conf
• 2. MACHINE과 빌드 병렬화 — 무엇을, 얼마나 빠르게
• 3. 캐시와 다운로드를 빌드 밖으로 — DL_DIR·SSTATE_DIR·TMPDIR
• 4. 소스를 더 빨리·안정적으로 — 미러 설정
• 🧪 직접 해보기

 1. 빌드를 조종하는 두 파일 — local.conf와 bblayers.conf

1.1 두 파일의 역할 분담

2회차에서 .conf 파일이 "위치에 따라 역할이 나뉘는 전역 변수"라고 정리했어요. 그중 빌드 디렉터리의 conf/ 아래 두 파일이 우리가 매일 만지는 것입니다. 공식 문서의 정의부터 볼게요.

"conf/local.conf: This configuration file contains all the local user configurations for your build environment."
"conf/bblayers.conf: This configuration file defines layers, which are directory trees, traversed (or walked) by BitBake."
— Reference Manual, "The Build Directory — build/conf/"

한 줄로 구분하면 이래요. local.conf는 "어떻게 빌드할지"(타깃 머신, 병렬도, 캐시 경로 등 내 빌드 환경의 모든 사용자 설정)를, bblayers.conf는 "무엇을 재료로 쓸지"(BitBake가 탐색할 레이어 목록)를 정합니다. 빌드가 이상하게 돌면 원인은 십중팔구 이 두 파일 중 하나예요.

1.2 bblayers.conf와 BBLAYERS — 레이어 목록

bblayers.conf의 핵심은 BBLAYERS 변수 하나예요. BitBake가 레시피와 설정을 찾아 뒤질 레이어들의 경로 목록입니다. 갓 만들어진 빌드에서는 이런 모습이에요.

build/conf/bblayers.conf

BBLAYERS ?= " \
  /home/user/poky/meta \
  /home/user/poky/meta-poky \
  /home/user/poky/meta-yocto-bsp \
  "

4회차에서 poky를 clone했을 때 본 meta·meta-poky·meta-yocto-bsp가 그대로 올라와 있죠. 나중에 벤더 BSP 레이어나 우리 팀 레이어를 추가할 때, 이 목록에 경로를 직접 손으로 넣는 대신 bitbake-layers add-layer <경로> 명령을 쓰는 게 표준이에요(8회차에서 커스텀 레이어와 함께 자세히 다룹니다). 명령이 BBLAYERS를 안전하게 갱신해 주기 때문에 오타로 빌드가 깨질 위험이 없거든요.

🔨 지금은 편집하지 말고 눈으로만 확인하세요. bitbake-layers show-layers를 실행하면 현재 BBLAYERS에 등록된 레이어와 각 레이어의 우선순위(2회차의 BBFILE_PRIORITY)가 표로 나옵니다.

 2. MACHINE과 빌드 병렬화 — 무엇을, 얼마나 빠르게

2.1 MACHINE — 무엇을 위해 빌드하는가

local.conf에서 가장 먼저 확인할 변수는 MACHINE이에요. "이 이미지를 어떤 하드웨어(또는 에뮬레이터)용으로 빌드할 것인가"를 정합니다. 5회차에서 QEMU 부팅에 썼던 그 값이에요. 기본 local.conf에는 이렇게 주석과 함께 들어 있습니다.

build/conf/local.conf

MACHINE ??= "qemux86-64"

MACHINE 값은 아무 문자열이나 되는 게 아니라, BBLAYERS에 등록된 레이어들의 conf/machine/<이름>.conf에 정의가 있어야 해요. poky 기본 제공 값으로는 에뮬레이터용 qemux86-64(64비트 x86)·qemuarm64(64비트 ARM) 등이 있고, 실제 보드용은 BSP 레이어를 추가하면 늘어납니다. 예를 들어 라즈베리파이 4를 빌드하려면 meta-raspberrypi 레이어를 BBLAYERS에 넣고 MACHINE = "raspberrypi4-64"로 바꾸는 식이에요. MACHINE 하나 바꾸면 커널·부트로더·이미지 포맷이 전부 그 보드에 맞게 재구성됩니다 — 2회차에서 본 "보드가 바뀌면 BSP 레이어만 교체"가 실제로 일어나는 지점이에요. 머신 설정과 BSP는 15회차에서 본격적으로 다룹니다.

💡 ??= 와 ?=가 낯설 텐데, BitBake의 조건부 대입이에요. ?=는 "이 변수가 아직 없으면 이 값을 쓴다"(기본값), ??=는 그보다 더 약한 기본값으로 파싱 마지막에 적용됩니다. 그냥 =로 값을 주면 무조건 그 값으로 덮어써요. local.conf에서 값을 확정하고 싶으면 MACHINE = "qemux86-64"처럼 =를 쓰면 됩니다.

2.2 BB_NUMBER_THREADS와 PARALLEL_MAKE — 빌드 병렬화의 두 축

빌드 속도를 결정하는 두 변수예요. 이름이 비슷해서 헷갈리기 쉬운데, 병렬화가 일어나는 층위가 다릅니다. 공식 정의를 나란히 보면 명확해요.

"BB_NUMBER_THREADS: The maximum number of tasks BitBake should run in parallel at any one time. The OpenEmbedded build system automatically configures this variable to be equal to the number of cores on the build system."
— Reference Manual, Variables Glossary

BB_NUMBER_THREADS는 서로 다른 레시피의 태스크를 동시에 몇 개 돌릴지예요. 3회차에서 본 태스크 파이프라인(fetch·compile·install…)이 레시피마다 있는데, 의존성이 없는 것들을 이 개수만큼 병렬 실행합니다. 반면 PARALLEL_MAKE는 레시피 하나를 컴파일할 때 make -j에 넘길 병렬 작업 수예요. 문서 표현으로는 이렇습니다.

"…each package is still built and installed via several parallel jobs specified by the PARALLEL_MAKE variable, which is by default the number of CPU threads on the system."
— 같은 문서, BB_NUMBER_THREADS 항목

즉 BB_NUMBER_THREADS는 "레시피 사이" 병렬, PARALLEL_MAKE는 "레시피 안" 병렬입니다. 둘 다 기본값이 호스트의 코어/스레드 수라서 대개 손댈 필요가 없어요. 값을 명시하고 싶으면 이렇게 씁니다.

BB_NUMBER_THREADS = "8"
PARALLEL_MAKE = "-j 8"

PARALLEL_MAKE는 값에 -j 플래그를 그대로 포함한다는 점에 주의하세요. 그런데 왜 손대냐고요? 자동 기본값은 두 변수를 곱한 만큼(코어 수 × 코어 수)의 프로세스가 순간적으로 뜰 수 있어서, RAM이 빠듯한 머신에서는 메모리 부족으로 컴파일러가 죽는(OOM) 일이 생겨요. 이때 PARALLEL_MAKE를 코어 수보다 낮게 잡아 부하를 눌러 주는 게 실무의 대표적 튜닝입니다.

 3. 캐시와 다운로드를 빌드 밖으로 — DL_DIR·SSTATE_DIR·TMPDIR

3.1 세 디렉터리의 역할

5회차에서 빌드를 한 번 돌리면 build/ 아래에 downloads/·sstate-cache/·tmp/가 자란다고 했죠. 각각을 가리키는 변수가 DL_DIR·SSTATE_DIR·TMPDIR이에요. 공식 문서의 설명입니다.

"build/downloads/: This directory contains downloaded upstream source tarballs. You can reuse the directory for multiple builds or move the directory to another location."
"build/sstate-cache/: This directory contains the shared state cache. You can reuse the directory for multiple builds or move the directory to another location."
"build/tmp/: The OpenEmbedded build system creates and uses this directory for all the build system's output. The TMPDIR variable points to this directory."
— Reference Manual, "The Build Directory"

성격이 뚜렷하게 갈려요. downloads/(DL_DIR)는 인터넷에서 받은 원본 소스 아카이브, sstate-cache/(SSTATE_DIR)는 3회차에서 배운 태스크 결과 캐시, tmp/(TMPDIR)는 실제 빌드 산출물 전부(work 디렉터리, 최종 이미지 등)입니다. 앞의 두 개는 문서가 대놓고 "여러 빌드에서 재사용하거나 다른 위치로 옮겨도 된다"고 안내하고, tmp/는 그런 문구가 없어요 — 이 차이가 다음 절의 핵심입니다.

3.2 빌드 디렉터리 밖으로 빼기 — 재다운로드·재빌드 절약

downloads/와 sstate-cache/를 빌드 디렉터리 밖의 공용 경로로 빼면, 빌드 디렉터리를 통째로 지우거나 새 빌드 디렉터리를 만들어도 소스 재다운로드와 재빌드를 건너뛸 수 있어요. local.conf에 이렇게 지정합니다.

DL_DIR = "/home/user/yocto/downloads"
SSTATE_DIR = "/home/user/yocto/sstate-cache"

왜 유용하냐면 — Yocto를 쓰다 보면 "tmp가 꼬인 것 같다" 싶을 때 tmp/를 통째로 지우는 일이 잦아요. 그런데 sstate-cache/가 빌드 디렉터리 밖에 살아 있으면, 지운 tmp/는 sstate에서 순식간에 복원됩니다(3회차의 setscene). downloads/도 마찬가지로 몇 GB짜리 소스 재다운로드를 통째로 아끼고요. 반대로 TMPDIR은 빌드의 실제 작업장이라 옮길 이유가 거의 없고, 오히려 빠른 로컬 SSD에 두는 게 이득이에요.

📌 실무 팁 — 팀 작업이라면 이 두 경로를 여러 개발자가 공유하는 서버 볼륨에 두는 게 정석이에요. 한 사람이 받은 소스와 빌드한 결과를 팀 전체가 재사용하니, 신규 입사자의 첫 빌드도 극적으로 짧아집니다. sstate를 원격으로 공유하는 SSTATE_MIRRORS는 5회차에서 맛봤고, 소스 쪽 공유가 다음 장의 미러예요. 단, 여러 빌드가 동시에 같은 SSTATE_DIR에 쓰는 건 괜찮지만 같은 TMPDIR은 절대 공유하면 안 됩니다 — 빌드끼리 서로의 작업장을 덮어써요.

 4. 소스를 더 빨리·안정적으로 — 미러 설정

4.1 왜 미러가 필요한가

DL_DIR이 "이미 받은 소스를 재사용하는 로컬 캐시"라면, 미러는 "어디서 받을지"를 다루는 원격 축이에요. Yocto 빌드는 수백 개 레시피의 소스를 각자의 업스트림(프로젝트 홈페이지, GitHub 등)에서 받는데, 여기엔 현실적인 문제가 둘 있어요. 첫째, 오래된 레시피의 업스트림 URL이 사라져 do_fetch가 실패하는 일이 잦고, 둘째, 수많은 사이트에서 제각각 받으니 느리고 불안정합니다. 미러는 이 둘을 푸는 장치예요. 공식 문서는 두 종류를 구분합니다.

4.2 PREMIRRORS — 업스트림보다 먼저 뒤지는 곳

"BitBake checks pre-mirrors before looking upstream for any source files. Pre-mirrors are appropriate when you have a shared directory that is not a directory defined by the DL_DIR variable."
— Overview Manual, "Source Mirror(s)"

PREMIRRORS에 등록된 곳은 업스트림보다 먼저 조회돼요. 회사에 "모든 소스를 모아 둔 사내 미러 서버"가 있다면 여기 등록하는 게 정석입니다. 그러면 빌드가 외부 인터넷 대신 빠른 사내망에서 소스를 받아, 속도도 빠르고 업스트림이 죽어도 영향을 안 받아요. 폐쇄망(에어갭) 빌드 환경에서는 사실상 필수 설정입니다.

4.3 MIRRORS — 업스트림이 죽었을 때의 대체

"Regular mirrors can be any site across the Internet that is used as an alternative location for source code should the primary site not be functioning for some reason or another."
— 같은 문서

MIRRORS는 순서가 반대예요. 업스트림(레시피의 SRC_URI)을 먼저 시도하고, 그게 실패했을 때 대체 위치로 조회됩니다. poky는 기본적으로 Yocto·OpenEmbedded 프로젝트가 운영하는 소스 미러를 MIRRORS에 넣어 두기 때문에, 여러분이 아무 설정을 안 해도 사라진 업스트림 URL 상당수가 이 대체 미러 덕에 조용히 복구돼요. 즉 PREMIRRORS → 업스트림(SRC_URI) → MIRRORS 순서로 소스를 찾는 셈입니다. 이 순서 감각만 잡아 두면 "분명 URL이 죽었는데 왜 빌드가 되지?" 같은 상황이 이해돼요.

4.4 미러 지정 문법 맛보기

미러는 "이런 URL 패턴은 저런 위치로 바꿔 찾아라"는 치환 규칙 목록이에요. 형식만 감을 잡아 두세요.

PREMIRRORS:prepend = "\
    git://.*/.* http://my-server/mirror/sources/ \
    https://.*/.* http://my-server/mirror/sources/ \
"

왼쪽이 "원래 URL 패턴"(정규식), 오른쪽이 "대신 찾아갈 위치"예요. 위 예시는 모든 git·https 소스를 사내 서버의 미러 디렉터리에서 먼저 찾으라는 뜻입니다. :prepend는 2회차에서 예고한 override 문법으로 "기존 값 앞에 덧붙이기"인데, 상세 문법은 10회차(레시피 심화)에서 다뤄요. 지금은 "미러는 URL 치환 규칙이고, PREMIRRORS는 먼저·MIRRORS는 나중"이라는 큰 그림이면 충분합니다.

ℹ️ 미확인 — 위 미러 URL(http://my-server/...)은 문법 설명용 예시일 뿐 실제 동작하는 주소가 아니에요. 사내 미러 구축 방법과 정확한 경로 규칙은 환경마다 다르니, 실제 적용 시 Dev Manual의 소스 미러 관련 문서를 확인하세요.

 🧪 직접 해보기

5회차에서 만든 빌드 디렉터리에서, 설정 파일을 눈으로 확인하고 변수 값을 조회하는 데까지 해봅시다. 편집은 각자 판단에 맡길게요. 명령은 Reference Manual, "The Build Directory"와 Variables Glossary를 근거로 합니다.

1. 빌드 환경 재진입: cd poky; source oe-init-build-env — 새 셸이면 다시 source 해야 해요(5회차).
2. 두 설정 파일 열어 보기: cat conf/local.conf / cat conf/bblayers.conf — MACHINE ??= 줄과 BBLAYERS 목록을 찾아보세요.
3. 등록된 레이어 확인: bitbake-layers show-layers — BBLAYERS의 레이어들과 우선순위가 표로 나옵니다.
4. 변수 최종값 조회: bitbake -e | grep "^MACHINE=", bitbake -e | grep "^DL_DIR=", bitbake -e | grep "^BB_NUMBER_THREADS=" — -e는 파싱만 하고 빌드는 안 하는 안전한 명령으로, 모든 설정이 합쳐진 최종 변수 값을 보여줘요(어느 파일이 그 값을 정했는지 주석도 함께).
5. (선택) 캐시 경로 빼 보기: DL_DIR·SSTATE_DIR을 빌드 밖 경로로 local.conf에 추가한 뒤, 4번의 bitbake -e 조회로 값이 바뀌었는지 확인.

✍️ 내 실행 결과

1. 빌드 환경 재진

2. 두 설정 파일 열어 보기

cat conf/local.conf

cat conf/bblayers.conf

3. 등록된 레이어 확인

bitbake-layers show-layers

4. 변수 최종값 조회

5. 캐시 경로 빼 보기

 마무리

이번 회차에서는 빌드를 조종하는 두 파일 — local.conf(어떻게 빌드할지)와 bblayers.conf(무엇을 재료로)를 뜯고, 실무에서 가장 자주 만지는 변수들을 정리했어요. MACHINE으로 타깃을 정하고, BB_NUMBER_THREADS·PARALLEL_MAKE로 병렬도를 조절하고, DL_DIR·SSTATE_DIR을 빌드 밖으로 빼 재다운로드·재빌드를 아끼고, 미러(PREMIRRORS·MIRRORS)로 소스를 빠르고 안정적으로 받는 — 빌드 시간·디스크·재현성을 좌우하는 손잡이들이었습니다.

다음 7회차에서는 지금까지 bitbake <타깃>과 bitbake -e 정도만 써 본 BitBake 명령어를 체계적으로 정리합니다. -c로 특정 태스크만 실행하기, -g로 의존성 그래프 뽑기, cleanall/cleansstate로 깨끗이 지우기 등 — 디버깅과 일상 작업에 매일 쓰는 옵션들이에요.

 참고 링크

• Yocto Project Reference Manual — The Build Directory (scarthgap) (local.conf·bblayers.conf·downloads·sstate-cache·tmp)
• Yocto Project Reference Manual — Variables Glossary (scarthgap) (BB_NUMBER_THREADS·PARALLEL_MAKE·DL_DIR·SSTATE_DIR·MACHINE)
• Yocto Project Overview and Concepts Manual — Source Mirror(s) (scarthgap) (PREMIRRORS·MIRRORS)