23.2.2 C++ 네이티브 패키지(`ament_cmake`)와 스크립트 기반 Python 패키지(`ament_python`) 계층 디렉터리 비교

23.2.2 C++ 네이티브 패키지(ament_cmake)와 스크립트 기반 Python 패키지(ament_python) 계층 디렉터리 비교

ROS2 모듈 시스템은 개발 언어의 실행 시맨틱(Execution semantic)과 빌드 파이프라인의 이질성에 대응하기 위해 두 가지 근본적으로 다른 패키지 계층 구조를 채택하고 있다. 이는 C++ 코드의 정적 컴파일을 요구하는 ament_cmake 체계와 인터프리터 스크립트 기반으로 동작하는 ament_python 체계로 양분된다. 본 절에서는 두 빌드 타입에 따라 생성되는 패키지 계층 디렉터리의 구조적 차이를 비교 분석한다.

1. C++ 네이티브 패키지(ament_cmake)의 정적 트리 아키텍처

C++ 네이티브 패키지 디렉터리 모델은 강력한 캡슐화와 링커(Linker) 참조 무결성을 보장하기 위해 설계되었다. ros2 pkg create --build-type ament_cmake 명령어에 의해 스캐폴딩되는 구조는 C/C++ 표준 디렉터리 레이아웃 관습을 엄격히 따른다.

my_cpp_package/
├── CMakeLists.txt
├── package.xml
├── include/
│   └── my_cpp_package/
└── src/
    └── my_node.cpp
  • CMakeLists.txt: C++ 빌드 파이프라인을 구동하는 핵심 파일이다. 소스 코드 컴파일, 라이브러리 링킹, 의존성 모듈 탐색(find_package), 설치 경로 전개(install()) 등 Ament 빌드 타임에 호출되는 모든 정적 빌드 룰(Build rules)을 내포한다.
  • 컴포넌트 분리 (include/ 및 src/):
  • src/ 디렉터리는 .cpp, .c 등의 내부 구현 코드를 격리한다. 이곳에 위치한 파일은 외부 패키지로 직접 노출되지 않는 은닉된 실행 단위를 구성한다.
  • include/<패키지명>/ 디렉터리는 공개 인터페이스인 .hpp, .h 파일들을 수용한다. 네임스페이스 오염 방지 및 모듈 간 명시적 헤더 참조를 위해 패키지명과 동일한 하위 디렉터리를 강요하는 것이 ROS2의 엄격한 규약이다.
  • package.xml: 의존성 메타데이터 스펙 버전을 준수하며, <buildtool_depend>ament_cmake</buildtool_depend> 태그 형식으로 이 패키지가 CMake 기반으로 빌드되어야 함을 선언한다.

2. 스크립트 기반 Python 패키지(ament_python)의 동적 트리 아키텍처

Python 기반 패키지는 정적 컴파일 및 바인딩 단계를 생략하고, 실행 시점 인터프리터 의존성에 맞추어 동적 언어에 특화된 포맷을 구축한다. ros2 pkg create --build-type ament_python 명령어를 통해 제공되는 템플릿 구조는 표준 파이썬 배포 도구인 setuptools의 명세와 Ament 파일시스템 추적 메커니즘을 융합한 것이다.

my_python_package/
├── package.xml
├── resource/
│   └── my_python_package
├── setup.cfg
├── setup.py
├── my_python_package/
│   ├── __init__.py
│   └── my_node.py
└── test/
  • setup.py 및 setup.cfg: C++의 CMakeLists.txt를 완벽히 대체한다. setup.py는 모듈의 의존성, 진입점(Entry Points), 배포 시 메타데이터를 파이썬 딕셔너리 형태로 서술한다. 스크립트의 빌더 역할을 수행하며, setup.cfg는 ament 워크스페이스 내에서 스크립트 실행 위치를 올바르게 안내하기 위해 전역 설치 경로(Global install path) 지시자를 포함한다.
  • 메인 패키지 모듈 (<패키지명>/): 파이썬 인터프리터가 해당 디렉터리를 정상적인 모듈로 인식할 수 있도록 __init__.py 파일을 포함하는 로컬 디렉터리 체계이다. 노드 로직을 구성하는 모든 .py 모듈은 이 루트 캡슐 내에 배치되어야 한다.
  • resource/ 디렉터리 및 마커 파일: Ament 인덱스 시스템이 빈 텍스트 마커 파일을 식별하여, 환경변수에 의존하지 않고도 해당 패키지가 워크스페이스 내에 존재함을 시스템 런타임에 빠르고 정확하게 역추적(Trace)할 수 있게 하는 ROS2 고유의 색인 기능 단위이다.

3. 계층 아키텍처의 설계 대칭성 평가

두 아키텍처는 공통적으로 package.xml 파일을 루트 경로에 두어 Colcon 빌드 시스템이 의존성 위상 그래프를 생성하는 데 기여하도록 설계되었다. 하지만 모듈화 방식에 있어서, ament_cmake 체계는 전처리-컴파일-링킹이라는 3단계 하드웨어 네이티브 사이클에 맞춰 소스코드(src)와 선언부(include)의 철저한 위상 분리를 강제하는 반면, ament_python 체계는 런타임 동적 로딩이라는 소프트웨어 네이티브 특성에 맞춰 단일 통합 모듈 디렉터리 구조와 setup.py 기반의 진입점(Entry point) 바인딩 메커니즘을 취하고 있다. 이러한 계층 구조의 이분화는 단일 ROS2 생태계에서 고성능 실시간 제어(C++)와 유연한 상위 논리(Python)를 독립적으로 보호하면서도 상호 운용성을 달성하기 위한 구조적 설계 철학을 대변한다.