# 1. PX4 최상위 디렉토리(Root) 및 빌드 생태계 구조

터미널에서 git clone을 통해 PX4-Autopilot을 내려받고 첫 디렉토리(ls -al)를 열면 수십 개의 폴더와 메타 파일들이 쏟아진다. 이 최상위 루트(Root) 계층은 실제 C++ 애플리케이션 코드가 존재하는 곳이 아니라, 이 거대한 프로젝트를 지탱하는 ‘국가의 헌법과 인프라 파이프라인’ 역할을 담당한다. 각 폴더와 파일들이 어떠한 거시적 목적을 위해 존재하는지 전체 그림(Big Picture)을 파악하라.

최상위 디렉토리 지형도 (Root Topology)

1. src/ (소스의 심장): 비행 제어, 센서 드라이버, 수학 라이브러리 등 펌웨어의 순수 논리(C/C++)가 집약된 절대 영역이다. 하드웨어 플랫폼에 종속되지 않는 범용 알고리즘들이 살고 있다.
2. boards/ (하드웨어 여권): px4_fmu-vX 같은 수백 가지 픽스호크 보드들의 하드웨어 스펙, 핀(Pin) 맵핑 정보, 타이머 할당 테이블이 정의된 곳이다. src/의 코드가 어떤 하드웨어라는 ’몸통’에 담길지 결정하는 형틀(Mold)이다.
3. platforms/ (운영체제 추상화): NuttX, POSIX(리눅스/macOS), QURT 등 코드가 올라탈 운영체제(OS)의 API 차이를 메워주는 어댑터(Adapter) 계층이다. 스레드(Thread)를 여는 방식이 OS마다 다름을 이 폴더 안에서 캡슐화한다.
4. msg/ (uORB 신경망 사전): 비행기 상태, 센서 데이터의 포맷을 정의한 .msg 텍스트 파일들의 집합소다. 컴파일 시 이 파일들이 파싱되어 수만 줄의 C++ 헤더 구조체로 자동 번역된다.
5. Tools/ (무기창고): 컴파일 스크립트, QGroundControl 통신용 패킷 생성기, SITL 파라미터 주입기 등 파이썬(Python)과 배시(Bash) 기반의 비자동화 도구들이 똬리를 틀고 있는 보급기지다.
6. ROMFS/ (최초의 숨결): 펌웨어가 플래시 블록에 구워진 직후 시스템 부팅 시 가장 먼저 실행되는 .px4 시작 쉘 스크립트(rc.S)와 파라미터 초기화 테이블들이 들어있는 읽기 전용 파일 시스템이다.

빌드 통제 메타데이터: CMakeLists.txt 와 .gitmodules
최상위 폴더에 위치한 수렴점은 바로 CMakeLists.txt 파일이다. 이 파일은 단순히 빌드를 지시하는 것이 아니라, boards/에서 전달받은 Kconfig 플래그를 해석하여 src/ 디렉토리 하위의 수많은 모듈 중 어떤 녀석을 포함하고 잘라낼지 결정하는 최고 사령관 역할을 수행한다.
또한 .gitmodules 파일은 가장 무서운 지뢰밭이다. 이 파일은 NuttX 커널, uAVCAN 프로토콜, EKF2 추정기 소스 코드가 존재하는 외부 저장소(External Repository)의 정확한 주소와 버전 해시(Commit Hash)를 고정해 두고 있다. 이 파이프라인 뼈대가 없으면 PX4 빌드의 생태계는 그 즉시 붕괴한다.