대상: ROS (특히 ROS1 Melodic/Noetic) 환경에서 catkin 빌드 시스템의 구조를 정확히 이해하고 싶은 개발자
환경: Ubuntu 20.04 / ROS Noetic / catkin_make
1. 문제/주제 요약
ROS 프로젝트를 시작할 때 대부분 이렇게 합니다:
mkdir -p ~/catkin_ws/src
cd ~/catkin_ws
catkin_make
그런데 막상 catkin_ws 내부 구조와 catkin_package()의 역할,CMakeLists.txt와 package.xml의 관계를 제대로 이해하지 못한 채
“그냥 복붙해서 빌드된다” 수준으로만 쓰는 경우가 많습니다.
이 글에서는 catkin 워크스페이스 구조와 패키지 구성 요소를
폴더 단위로 명확하게 설명합니다.
2. 배경 및 개념 정리
(1) catkin이란?
catkin은 ROS에서 사용하는 CMake 기반 빌드 시스템입니다.
여러 패키지를 한 워크스페이스 안에서 의존성 순서대로 자동 빌드해주는 역할을 합니다.
즉, catkin = ROS용 CMake + 의존성 관리 + 환경설정 자동화 도구.
(2) 워크스페이스 구조 개요
catkin 워크스페이스는 최소 아래 3단계 구조를 가집니다.
catkin_ws/ ← 워크스페이스 루트
├── src/ ← ROS 패키지들이 들어가는 곳
│ ├── CMakeLists.txt ← catkin 빌드 지시용 심볼릭 파일
│ └── my_robot_pkg/
│ ├── package.xml
│ ├── CMakeLists.txt
│ ├── src/
│ ├── include/
│ └── launch/
├── build/ ← 빌드 중간 파일 (catkin_make 자동 생성)
└── devel/ ← 빌드 결과물, 실행 파일 및 환경 설정
3. catkin 워크스페이스 생성 및 빌드
(1) 워크스페이스 생성
mkdir -p ~/catkin_ws/src
cd ~/catkin_ws
catkin_make
이 명령은 build/, devel/ 폴더를 자동으로 생성하고,
빌드 결과를 devel에 설치합니다.
(2) 환경 설정
빌드 후 다음 명령을 실행해야 ROS가 새 패키지를 인식합니다:
source ~/catkin_ws/devel/setup.bash
이걸 .bashrc에 추가해두면 매번 자동으로 적용됩니다:
echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc
4. ROS 패키지 구조
워크스페이스 안의 패키지 단위가 실제 ROS 기능의 단위입니다.
(1) 예시 구조
my_robot_pkg/
├── package.xml ← 패키지 메타정보 (의존성, 버전 등)
├── CMakeLists.txt ← 빌드 규칙
├── src/ ← C++ 노드 코드
│ └── main.cpp
├── include/my_robot_pkg/ ← 헤더 파일
│ └── my_header.h
├── launch/ ← launch 파일
│ └── my_robot.launch
└── scripts/ ← Python 노드 (실행권한 필요)
└── talker.py
(2) package.xml — 의존성 정의
package.xml은 패키지의 이름, 버전, 의존성, 라이선스 등을 정의합니다.
<package format="2">
<name>my_robot_pkg</name>
<version>0.0.1</version>
<description>My robot test package</description>
<maintainer email="dev@robot.com">Developer</maintainer>
<license>MIT</license>
<buildtool_depend>catkin</buildtool_depend>
<build_depend>roscpp</build_depend>
<exec_depend>roscpp</exec_depend>
</package>
의존성은 roscpp, rospy, std_msgs, sensor_msgs 등으로 자유롭게 추가할 수 있습니다.
(3) CMakeLists.txt — 빌드 규칙
CMakeLists.txt는 패키지 빌드 방법을 지정합니다.
기본 형태:
cmake_minimum_required(VERSION 3.0.2)
project(my_robot_pkg)
find_package(catkin REQUIRED COMPONENTS
roscpp
std_msgs
)
catkin_package(
INCLUDE_DIRS include
CATKIN_DEPENDS roscpp std_msgs
)
include_directories(
include
${catkin_INCLUDE_DIRS}
)
add_executable(my_robot_node src/main.cpp)
target_link_libraries(my_robot_node ${catkin_LIBRARIES})
이 파일의 핵심 역할은 세 가지입니다:
- catkin 의존성 불러오기 (
find_package) - catkin 시스템에 이 패키지 등록 (
catkin_package) - 실행 바이너리 빌드 및 링크 (
add_executable+target_link_libraries)
5. 빌드 및 실행
(1) 빌드
cd ~/catkin_ws
catkin_make
패키지 단위 빌드만 하려면:
catkin_make --pkg my_robot_pkg
(2) 실행
환경 로드 후:
source ~/catkin_ws/devel/setup.bash
rosrun my_robot_pkg my_robot_node
또는 launch 파일로:
roslaunch my_robot_pkg my_robot.launch
6. 추가 팁 / 자주 하는 실수
- ⚠️
package.xml의 의존성이 누락되면#include오류 발생
→catkin_make에서 “package not found” 에러 확인 - ⚠️ 새 패키지 생성 후 catkin_make를 반드시 다시 실행해야 ROS가 인식함
- ✅ 워크스페이스 내 여러 패키지 간 의존성이 있을 때,
catkin_make가 자동으로 순서를 정해 빌드해준다. - ✅ Python 노드는 실행권한 필수:
chmod +x scripts/talker.py
7. 정리
- catkin 워크스페이스는
src,build,devel의 3단 구조로 관리된다. - 각 패키지는
package.xml(의존성)과CMakeLists.txt(빌드 규칙)으로 정의된다. catkin_make는 전체 워크스페이스의 빌드를 자동으로 관리한다.- 실무에서는 catkin 구조를 이해하면, 의존성 충돌 / 빌드 실패 / 노드 미인식 문제를 쉽게 해결할 수 있다.