package.xml — bản khai lý lịch của một package ROS2

Trong hai file cấu hình của một package (CMakeLists.txt/setup.py và package.xml), package.xml là file duy nhất bắt buộc với mọi package, bất kể C++ hay Python. Đây là bản khai để colcon, rosdep và các công cụ ROS2 khác hiểu package của bạn là gì và cần gì để chạy.

Khái niệm chính

<?xml version="1.0"?>
<package format="3">
  <name>my_cpp_pkg</name>
  <version>0.0.1</version>
  <description>Package mẫu minh hoạ package.xml</description>
  <maintainer email="[email protected]">Tên bạn</maintainer>
  <license>Apache-2.0</license>

  <buildtool_depend>ament_cmake</buildtool_depend>

  <depend>rclcpp</depend>
  <depend>std_msgs</depend>

  <test_depend>ament_lint_auto</test_depend>

  <export>
    <build_type>ament_cmake</build_type>
  </export>
</package>

• name / version / description / maintainer / license — thông tin định danh, rosdep/công cụ đóng gói dùng để tra cứu
• buildtool_depend — công cụ build cần dùng (ament_cmake hoặc ament_python), khớp với --build-type lúc ros2 pkg create
• export> <build_type> — dòng này là thứ thực sự quyết định colcon build package theo kiểu nào, phải khớp với buildtool_depend ở trên

Nguyên lý hoạt động

Ba (thực ra bốn) loại depend hay nhầm lẫn:

Thẻ	Khi nào cần	Ví dụ
<depend>	Dùng lúc build và lúc chạy	rclcpp, std_msgs
<build_depend>	Chỉ cần lúc build, không cần lúc chạy	thư viện header-only chỉ dùng để biên dịch
<exec_depend>	Chỉ cần lúc chạy, không cần lúc build	một node Python gọi package khác qua ros2 run, không link tĩnh
<test_depend>	Chỉ cần khi chạy test	ament_lint_auto, ament_cmake_gtest

Phần lớn trường hợp thực tế chỉ cần <depend> — nó tương đương khai cả build_depend lẫn exec_depend cùng lúc, dùng an toàn khi không chắc dependency đó cần ở giai đoạn nào.

Tóm lại: <depend> sai hoặc thiếu không làm CMakeLists.txt/setup.py báo lỗi ngay — nó âm thầm làm colcon build tính sai thứ tự build giữa các package, hoặc khiến rosdep install bỏ sót một thư viện hệ thống cần cài. Đây là lý do package.xml nên khai đầy đủ ngay từ đầu, không để "sau tính sau".

rosdep dùng chính package.xml để cài dependency hệ thống:

cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y

Lệnh này quét toàn bộ package.xml trong src/, tra cứu từng <depend> trong cơ sở dữ liệu rosdep để biết cần cài gói hệ thống nào (qua apt) tương ứng.

Kiến thức kỹ thuật

Thông số

Ngoài các thẻ đã nêu, package.xml format hiện hành còn hỗ trợ một số thẻ ít gặp hơn nhưng hữu ích:

Thẻ/Thông số	Ý nghĩa
format="3" (thuộc tính <package>)	Định dạng hiện hành, hỗ trợ đầy đủ các loại depend đã nêu
format="1" (cũ, không nên dùng)	Không phân biệt loại depend, mọi dependency coi như <depend>
<doc_depend>	Dependency chỉ cần khi sinh tài liệu (documentation), hiếm dùng
<buildtool_export_depend>	Buildtool dependency cần "xuất khẩu" cho package khác dùng lại thư viện của bạn

Ứng dụng thực tế

Trong quy trình CI/CD build image Docker cho robot, package.xml của toàn bộ workspace thường được dùng làm nguồn duy nhất để tự động sinh danh sách cài đặt hệ thống — script CI chạy rosdep install ngay trong lúc build Docker image, đảm bảo image luôn cài đúng và đủ dependency theo đúng khai báo trong code, không cần duy trì song song 1 danh sách apt install thủ công dễ bị lệch (out of sync) so với dependency thực tế trong package.xml mỗi khi thêm package mới.

Ví dụ thực tế

$ rosdep install --from-paths src --ignore-src -r -y

Output:
#All required rosdeps installed successfully

reading in sources list data from /etc/ros/rosdep/sources.list.d
Hit https://raw.githubusercontent.com/ros/rosdistro/...
executing command [apt-get install -y libpcl-dev]
executing command [apt-get install -y ros-humble-nav2-msgs]

rosdep tự dịch tên dependency ROS2 (VD: nav2_msgs) sang đúng tên gói apt hệ thống (ros-humble-nav2-msgs) — tránh phải tự tra cứu và gõ tay từng lệnh apt install cho hàng chục dependency của một workspace lớn.

Lỗi thường gặp

• Thiếu <depend> cho 1 package thực sự dùng trong code — build vẫn có thể thành công nếu dependency đó đã cài sẵn trên máy dev, nhưng colcon sẽ tính sai thứ tự build và rosdep install bỏ sót nó trên máy khác — lỗi âm thầm, chỉ lộ ra khi triển khai ở môi trường mới.
• <export><build_type> không khớp <buildtool_depend> — VD: khai buildtool_depend là ament_python nhưng export/build_type lại ghi ament_cmake — gây colcon build sai kiểu package, lỗi khó hiểu vì trông như package Python nhưng bị xử lý như C++.
• Quên cập nhật <version> khi phát hành bản mới — với package dùng để phân phối/đóng gói, version không khớp giữa package.xml và tag git thực tế gây nhầm lẫn khi truy vết lỗi giữa các phiên bản.
• Bỏ trống <license> — một số công cụ đóng gói/kiểm tra tuân thủ (compliance) sẽ cảnh báo hoặc từ chối package thiếu thông tin giấy phép khi build cho mục đích phân phối rộng rãi.

Kết luận

package.xml là file bắt buộc duy nhất của mọi package ROS2, đóng vai trò "hộ chiếu" khai báo dependency cho cả colcon (tính thứ tự build) lẫn rosdep (cài dependency hệ thống). Khai đúng loại depend (build/exec/test) ngay từ đầu tránh được nhiều lỗi âm thầm chỉ lộ ra khi triển khai ở môi trường khác. Bài tiếp theo trong chuyên mục nói về Launch File — cách khởi động nhiều node cùng lúc với đúng tham số, thay vì phải gõ tay từng lệnh ros2 run.