ros2 setup.cfg 各个配置项详细范例

在ROS2中，setup.cfg是Python包的构建系统配置文件，与setup.py配合使用，主要用于定义Python包的安装规则和构建参数，确保ros2 run能正确识别并运行节点。以下是其配置项的详细说明及范例：

一、核心配置项及范例

1. 安装路径配置

• 作用：指定开发模式和正式安装模式下的脚本安装路径。
• 配置项：

  [develop]
  script_dir=$base/lib/python3.8/site-packages  # 开发模式安装路径[install]
  install_scripts=$base/lib/python3.8/site-packages  # 正式安装路径
  

• 说明：
  $base为ROS2工作空间的根目录，确保脚本安装到Python的site-packages目录，便于系统查找。

2. 元数据配置

• 作用：定义包的基本信息（如名称、版本），需与package.xml保持一致。
• 配置项：

  [metadata]
  name = my_package  # 包名（必须与package.xml一致）
  version = 0.0.0    # 版本号（通常与package.xml同步）
  

• 说明：
  版本号需遵循语义化版本规范（如主版本号.次版本号.修订号），避免因版本冲突导致构建失败。

3. 构建选项配置

• 作用：控制包的构建行为，如禁用压缩安装、启用非代码文件安装等。
• 配置项：

  [options]
  zip_safe = False  # 禁用压缩安装（ROS2推荐）
  include_package_data = True  # 启用非代码文件安装
  packages = find:  # 自动查找子包
  

• 说明：
  • zip_safe=False确保ROS2能正确加载模块。
  • include_package_data=True允许安装非Python文件（如.msg、.launch文件）。

4. 可执行节点入口配置

• 作用：注册可执行节点，使ros2 run能识别并运行Python脚本。
• 配置项：

  [options.entry_points]
  console_scripts =talker = my_package.talker_node:main  # 发布者节点listener = my_package.listener_node:main  # 订阅者节点
  

• 说明：
  • 每个条目格式为<节点名> = <模块路径>:<函数名>。
  • 需在setup.py中同步配置entry_points参数，确保一致性。

5. 数据文件安装配置

• 作用：指定非代码文件（如配置文件、启动文件）的安装路径。
• 配置项（需在setup.py中配合data_files参数使用）：

  # setup.py 示例
  from setuptools import setup
  import os
  from glob import globdata_files = [('share/ament_index/resource_index/packages', ['resource/' + package_name]),('share/' + package_name, ['package.xml']),(os.path.join('share', package_name, 'launch'), glob('launch/*.launch.py')),
  ]setup(data_files=data_files,# 其他参数...
  )
  

• 说明：
  ROS2要求非代码文件必须安装到share/${package_name}下的子目录（如launch、config），需在setup.py中明确定义。

二、完整范例

以下是一个典型的setup.cfg文件内容：

[develop]
script_dir=$base/lib/python3.8/site-packages[install]
install_scripts=$base/lib/python3.8/site-packages[metadata]
name = talker_listener
version = 0.0.0[options]
zip_safe = False
include_package_data = True
packages = find:[options.entry_points]
console_scripts =talker = talker_listener.talker_node:mainlistener = talker_listener.listener_node:main

三、常见问题与调试

1. 节点无法通过ros2 run执行

• 原因：setup.cfg中未正确声明console_scripts。
• 解决：检查[options.entry_points]是否包含类似配置：

  console_scripts =my_node = my_package.my_node:main
  

2. 配置文件/接口文件未安装

• 原因：未在setup.py中指定数据文件路径。
• 解决：在setup.py中补充data_files配置：

  data_files = [('share/' + package_name, ['package.xml']),(os.path.join('share', package_name, 'launch'), glob('launch/*.launch.py')),
  ]
  

3. 版本冲突

• 原因：setup.cfg中的version与package.xml不一致。
• 解决：保持两者版本号同步，避免构建冲突。

四、最佳实践

1. 保持一致性：确保setup.cfg中的包名、版本号与package.xml一致。
2. 明确数据文件路径：在setup.py中明确定义非代码文件的安装路径。
3. 使用colcon构建：通过colcon build --packages-select <包名>进行增量构建，提高效率。
4. 验证节点注册：使用ros2 node list验证节点是否成功注册。