【ROS2】ament_CMake (2-example)

ament_cmake 是 ROS 2 中最核心的 C++ 包构建工具，基于 CMake 扩展但针对 ROS 2 生态做了深度适配。它不仅简化了编译、链接、安装等流程，还原生支持依赖管理、测试、代码检查等功能。以下从 包结构、核心配置文件、详细用法（含示例）、扩展功能 四个方面详细讲解。

一、标准包结构（基于 ament_cmake）

一个典型的 ament_cmake 包需遵循固定结构，确保构建系统能正确识别文件：

my_ament_package/
├── CMakeLists.txt        # 核心构建配置文件
├── package.xml           # 包元信息（依赖、名称等）
├── include/              # 头文件目录（必须包含包名子目录，避免冲突）
│   └── my_ament_package/
│       └── my_node.hpp   # 示例头文件
├── src/                  # 源文件目录
│   └── my_node.cpp       # 示例源文件（节点实现）
├── src/library/          # （可选）如果包含库文件
│   └── my_lib.cpp
├── test/                 # （可选）测试用例目录
│   └── test_my_node.cpp
└── launch/               # （可选）启动文件目录（非构建必需，用于运行）
    └── my_node.launch.py

说明：

• include 下必须嵌套包名子目录（如 my_ament_package），避免不同包的头文件重名冲突；
• src 存放可执行文件或库的源文件；
• test 存放单元测试代码，由 ament_cmake 集成的测试框架自动识别。

二、核心配置文件 1：package.xml（元信息与依赖）

package.xml 是包的“身份证”，用于声明包的基本信息、依赖关系，ament_cmake 会通过它解析构建和运行时依赖。

完整示例（带注释）：

<?xml version="1.0"?>
<!-- 遵循 ROS 2 包格式 3（最新版本） -->
<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
<package format="3">
  <!-- 1. 基本信息 -->
  <name>my_ament_package</name>  <!-- 包名（必须唯一，与 CMakeLists.txt 中 project 一致） -->
  <version>0.1.0</version>       <!-- 版本号（遵循语义化版本） -->
  <description>A simple ament_cmake package for ROS 2</description>  <!-- 描述 -->
  <maintainer email="user@example.com">Your Name</maintainer>  <!-- 维护者 -->
  <license>Apache-2.0</license>  <!-- 许可证（ROS 2 推荐 Apache 2.0） -->

  <!-- 2. 构建工具依赖（必须包含 ament_cmake） -->
  <buildtool_depend>ament_cmake</buildtool_depend>  <!-- 构建工具本身的依赖 -->
  <buildtool_depend>ament_cmake_gtest</buildtool_depend>  <!-- （可选）如果需要 GTest 测试 -->

  <!-- 3. 编译/运行依赖（根据实际功能添加） -->
  <!-- 依赖 ROS 2 核心库（如 rclcpp 是 C++ 节点库） -->
  <depend>rclcpp</depend>
  <!-- 依赖消息接口（如 std_msgs 包含 String 等基础消息） -->
  <depend>std_msgs</depend>

  <!-- 4. 导出配置（告诉其他包如何依赖当前包） -->
  <export>
    <build_type>ament_cmake</build_type>  <!-- 声明构建类型为 ament_cmake -->
  </export>
</package>

关键标签说明：

• <buildtool_depend>：构建过程中需要的工具（如 ament_cmake 是构建工具，ament_cmake_gtest 是测试工具）；
• <depend>：当前包编译和运行时都需要的依赖（如 rclcpp 既是编译时链接库，也是运行时依赖）；
• <export>：声明包的构建类型，确保其他包依赖它时能正确解析构建规则。

三、核心配置文件 2：CMakeLists.txt（构建逻辑）

CMakeLists.txt 是 ament_cmake 的“核心大脑”，定义了从编译到安装的完整流程。基于 CMake 语法，但通过 ament_* 扩展命令实现 ROS 2 特有的功能。

完整示例（带详细注释）：

# 1. 声明 CMake 最低版本（ROS 2 推荐 3.5 及以上）
cmake_minimum_required(VERSION 3.5)

# 2. 声明包名（必须与 package.xml 中的 <name> 一致）
project(my_ament_package)

# 3. 查找依赖（必须包含 ament_cmake 和 package.xml 中声明的所有 depend）
# 查找 ament_cmake 核心模块
find_package(ament_cmake REQUIRED)
# 查找 ROS 2 C++ 客户端库（对应 package.xml 中的 <depend>rclcpp</depend>）
find_package(rclcpp REQUIRED)
# 查找标准消息库（对应 package.xml 中的 <depend>std_msgs</depend>）
find_package(std_msgs REQUIRED)
# （可选）如果需要测试，查找 GTest 集成模块
find_package(ament_cmake_gtest REQUIRED)

# 4. 配置头文件目录（让编译器能找到 include 下的头文件）
# 语法：include_directories(目录路径)
include_directories(
  include  # 对应 ./include 目录
)

# 5. 编译目标（可执行文件或库）
## 5.1 编译可执行文件（如一个 ROS 2 节点）
# 语法：add_executable(可执行文件名 源文件路径)
add_executable(my_node src/my_node.cpp)

# 5.2 为可执行文件链接依赖（关键步骤！自动处理头文件和库链接）
# 语法：ament_target_dependencies(目标名 依赖包1 依赖包2 ...)
# 作用：替代 CMake 原生的 target_include_directories 和 target_link_libraries，自动注入依赖
ament_target_dependencies(my_node
  rclcpp  # 依赖 rclcpp 库
  std_msgs  # 依赖 std_msgs 消息
)

## 5.3 （可选）编译共享库（如果需要被其他包引用）
# 语法：add_library(库名 SHARED 源文件)
add_library(my_lib SHARED src/library/my_lib.cpp)
# 为库链接依赖
ament_target_dependencies(my_lib
  rclcpp
)

# 6. 安装文件（必须！否则安装后无法找到可执行文件/库/头文件）
## 6.1 安装可执行文件（默认安装到 install/lib/${PROJECT_NAME} 目录，ROS 2 规范）
install(TARGETS
  my_node  # 目标可执行文件
  DESTINATION lib/${PROJECT_NAME}  # 安装路径（PROJECT_NAME 即包名）
)

## 6.2 （可选）安装共享库（供其他包链接）
install(TARGETS
  my_lib
  EXPORT export_${PROJECT_NAME}  # 导出库，供其他包查找
  ARCHIVE DESTINATION lib
  LIBRARY DESTINATION lib
  RUNTIME DESTINATION bin
)

## 6.3 安装头文件（供其他包引用）
install(DIRECTORY include/  # 源目录（注意末尾的 /，表示复制目录内内容）
  DESTINATION include  # 安装到 install/include 目录
)

# 7. 导出依赖信息（供其他包依赖当前包时使用）
## 7.1 导出头文件目录
ament_export_include_directories(include)
## 7.2 导出库（如果有）
ament_export_libraries(my_lib)
## 7.3 导出当前包的依赖（确保依赖传递）
ament_export_dependencies(rclcpp std_msgs)
## 7.4 （可选）导出库的配置（供 find_package 查找）
ament_export_targets(export_${PROJECT_NAME} HAS_LIBRARY_TARGET)

# 8. 添加测试（可选，但推荐）
## 8.1 创建测试用例可执行文件
ament_add_gtest(test_my_node test/test_my_node.cpp)  # 测试文件路径
## 8.2 为测试用例链接依赖
ament_target_dependencies(test_my_node
  rclcpp
  std_msgs
  my_lib  # 如果测试依赖自己的库
)
## 8.3 安装测试用例（可选）
install(TARGETS
  test_my_node
  DESTINATION lib/${PROJECT_NAME}
)

# 9. 必须放在文件末尾！生成包配置文件（如 .pc 文件、CMake 模块）
ament_package()

四、核心命令详解（结合示例）

ament_cmake 扩展了多个关键命令，简化了 ROS 2 特有的构建逻辑，以下是最常用的几个：

1. find_package(ament_cmake REQUIRED)

• 作用：加载 ament_cmake 核心模块，是使用 ament_cmake 的前提。
• 必须在 project() 之后、其他构建逻辑之前调用。

2. ament_target_dependencies(target dep1 dep2 ...)

• 作用：自动处理目标（可执行文件/库）的依赖，替代 CMake 原生的 target_include_directories（头文件路径）和 target_link_libraries（库链接）。
• 示例：

  ament_target_dependencies(my_node rclcpp std_msgs)
  

  等价于手动添加 rclcpp 和 std_msgs 的头文件路径，并链接它们的库，无需开发者手动计算路径。

3. ament_package()

• 作用：生成包的配置文件（如 my_ament_packageConfig.cmake、.pc 文件），让其他包能通过 find_package(my_ament_package) 找到当前包。
• 必须放在 CMakeLists.txt 的最后一行，否则可能遗漏配置。

4. ament_add_gtest(test_name test_file.cpp)

• 作用：集成 GTest 测试框架，自动编译测试文件并生成测试目标。
• 示例中 ament_add_gtest(test_my_node test/test_my_node.cpp) 会生成一个名为 test_my_node 的测试可执行文件，可通过 colcon test 运行。

五、扩展功能：代码检查与文档生成

ament_cmake 支持通过扩展模块实现代码规范检查和文档生成，只需在 CMakeLists.txt 中添加少量配置。

1. 代码检查（以 cpplint 为例）

• 步骤 1：在 package.xml 中添加依赖：

  <buildtool_depend>ament_cmake_cpplint</buildtool_depend>
  

• 步骤 2：在 CMakeLists.txt 中启用：

  find_package(ament_cmake_cpplint REQUIRED)
  # 检查 src 和 include 目录下的代码
  ament_cpplint(
    src/
    include/my_ament_package/
  )
  

• 效果：编译时自动检查代码是否符合 Google C++ 规范，报错会终止构建。

2. 文档生成（Doxygen）

• 步骤 1：在 package.xml 中添加依赖：

  <buildtool_depend>ament_cmake_doxygen</buildtool_depend>
  

• 步骤 2：在 CMakeLists.txt 中启用：

  find_package(ament_cmake_doxygen REQUIRED)
  # 生成文档（默认读取 Doxyfile 配置，若无则用默认值）
  ament_doxygen_generate_docs(
    INPUT_FILES include/my_ament_package/my_node.hpp  # 要生成文档的文件
    OUTPUT_DIRECTORY doc  # 文档输出目录
  )
  

• 效果：运行 colcon build 后，在 build/my_ament_package/doc 下生成 HTML 文档。

六、实际使用流程（总结）

1. 按照标准结构创建包（include、src、package.xml、CMakeLists.txt）；
2. 在 package.xml 中声明依赖（buildtool_depend 和 depend）；
3. 在 CMakeLists.txt 中配置编译、链接、安装和导出逻辑（核心是 ament_target_dependencies 和 ament_package()）；
4. （可选）添加测试和代码检查；
5. 通过 colcon build 编译，colcon test 运行测试，source install/setup.bash 生效。

七、优势总结

• 依赖管理自动化：无需手动计算头文件和库路径，ament_target_dependencies 一键搞定；
• 标准化路径：统一安装路径（如可执行文件到 lib/<package>），避免混乱；
• 功能扩展性：无缝集成测试、代码检查、文档生成，符合 ROS 2 开发规范；
• 跨平台兼容：继承 CMake 跨平台特性，支持 Linux、Windows、macOS。

掌握 ament_cmake 是 ROS 2 C++ 开发的基础，其设计哲学是“约定大于配置”，通过固定规范减少开发者的构建配置工作量。