目录结构#

本文档介绍了 Autoware 中 ROS 节点的目录结构.

我们将使用包 autoware_gnss_poser 作为示例.

**请注意,此示例并不反映实际的 `autoware_gnss_poser,并且包含额外的文件和目录来演示所有可能的包结构.

C++ 包#

整个结构#

这是关于如何构建整个包的参考.
一个包可能没有此处显示的所有目录.

autoware_gnss_poser
├─ package.xml
├─ CMakeLists.txt
├─ README.md
│
├─ config
│   ├─ gnss_poser.param.yaml
│   └─ another_non_ros_config.yaml
│
├─ schema
│   └─ gnss_poser.schema.json
│
├─ doc
│   ├─ foo_document.md
│   └─ foo_diagram.svg
│
├─ include  # for exporting headers
│   └─ autoware
│       └─ gnss_poser
│           └─ exported_header.hpp
│
├─ src
│   ├─ include
│   │   ├─ gnss_poser_node.hpp
│   │   └─ foo.hpp
│   ├─ gnss_poser_node.cpp
│   └─ bar.cpp
│
├─ launch
│   ├─ gnss_poser.launch.xml
│   └─ gnss_poser.launch.py
│
└─ test
    ├─ test_foo.hpp  # or place under an `include` folder here
    └─ test_foo.cpp

包名称#

Autoware 中的所有软件包都应该以 autoware_ 为前缀.
即使软件包导出了一个节点,软件包名称 也不应 带有 _node 后缀.
软件包名称应为 `snake_case.

软件包名称	确定	另类
path_smoother	❌	autoware_path_smoother
autoware_trajectory_follower_node	❌	autoware_trajectory_follower
autoware_geography_utils	✅	-

包文件夹#

autoware_gnss_poser
├─ package.xml
├─ CMakeLists.txt
└─ README.md

包文件夹名称应与包名称相同.

`package.xml`#

应在 `` 标签中输入软件包名称
.
- <name>autoware_gnss_poser</name>

`CMakeLists.txt`#

project() 命令应该调用包名称.
- 示例： project(autoware_gnss_poser)

导出可组合节点组件可执行文件#

为了最佳实践和系统效率,建议主要使用可组合节点组件.

此方法有助于在 ROS 环境中更轻松地进行部署和维护.

ament_auto_add_library(${PROJECT_NAME} SHARED
  src/gnss_poser_node.cpp
)

rclcpp_components_register_node(${PROJECT_NAME}
  PLUGIN "autoware::gnss_poser::GNSSPoser"
  EXECUTABLE ${PROJECT_NAME}_node
)

如果您正在构建：
- 只有一个可组合节点组件可执行文件名称应以 ${PROJECT_NAME} 开头
- 多个可组合节点组件可执行文件名称由开发人员决定.
所有可组合节点组件可执行文件都应具有 _node 后缀.

导出不带组合的独立节点可执行文件 (在大多数情况下不建议这样做)#

独立可执行文件的使用应仅限于需要特定需求(如调试或工具)的情况.

导出可组合节点组件可执行文件通常是标准作用途的首选,因为它在 ROS 生态系统中具有灵活性和可扩展性.

若：

src/gnss_poser.cpp 具有 GNSSPoser 类.
src/gnss_poser_node.cpp 具有 main 函数.
没有可组合节点组件注册.

ament_auto_add_library(${PROJECT_NAME} SHARED
  src/gnss_poser.cpp
)

ament_auto_add_executable(${PROJECT_NAME}_node src/gnss_poser_node.cpp)

节点可执行文件：
- 应具有 _node 后缀.
- 应以 `${PROJECT_NAME} 开头

`config` 和 `schema`#

autoware_gnss_poser
│─ config
│   ├─ gnss_poser.param.yaml
│   └─ another_non_ros_config.yaml
└─ schema
    └─ gnss_poser.schema.json

`配置`#

ROS 参数使用扩展名 .param.yaml.
非 ROS 参数使用扩展名 .yaml.

基本原理： ROS 参数和非 ROS 参数使用不同的 linting 规则.

`模式`#

置入参数定义文件.有关详细信息,请参阅参数.

`文档`#

autoware_gnss_poser
└─ doc
    ├─ foo_document.md
    └─ foo_diagram.svg

置入文档文件并从 README 文件链接它们.

`include` 和 `src`#

除非你特别需要导出头文件,否则你不应该在 package 目录下有一个 include 目录.
在大多数情况下,请按照不导出标头进行作.
导出头文件的库包可以遵循导出头文件.

不导出标头#

autoware_gnss_poser
└─ src
    ├─ include
    │   ├─ gnss_poser_node.hpp
    │   └─ foo.hpp
    │─ gnss_poser_node.cpp
    └─ bar.cpp

OR

autoware_gnss_poser
└─ src
    ├─ gnss_poser_node.hpp
    ├─ gnss_poser_node.cpp
    ├─ foo.hpp
    └─ bar.cpp

导出节点的源文件应：
- 具有 _node 后缀.
  - 基本原理： 为了与其他源文件区分开来.
- NOT 具有 autoware_ 前缀.
  - 基本原理： 为了避免冗长.
有关如何构建 gnss_poser_node.hpp 和 gnss_poser_node.cpp 文件的更多详细信息,请参阅类设计.
如何组织 src 下的源文件取决于开发人员.
- 注意： src 下的 include 文件夹是可选的.

导出标头#

autoware_gnss_poser
└─ include
    └─ autoware
        └─ gnss_poser
            └─ exported_header.hpp

autoware_gnss_poser/include 文件夹应仅包含 autoware 文件夹.
- 基本原理： 安装 ROS debian 包时,头文件被复制到 /opt/ros/$ROS_DISTRO/include/ 目录.此结构用于避免与非 Autoware 软件包冲突.
autoware_gnss_poser/include/autoware 文件夹应包含 仅 gnss_poser `文件夹.
- 基本原理： 同样,这种结构用于避免与其他包冲突.
autoware_gnss_poser/include/autoware/gnss_poser 文件夹应包含要导出的头文件.

注意： 如果在 CMakeLists.txt 文件中使用了 ament_auto_package() 命令,并且存在 autoware_gnss_poser/include 文件夹, 这个 include 文件夹将作为 ament_auto_package.cmake 的一部分导出到 install 文件夹

参考： https://docs.ros.org/en/humble/How-To-Guides/Ament-CMake-Documentation.html#adding-targets

`发射`#

autoware_gnss_poser
└─ launch
    ├─ gnss_poser.launch.xml
    └─ gnss_poser.launch.py

您可能在此处有多个启动文件.
除非有特定原因,否则请使用 .launch.xml 扩展.
- 基本原理： 虽然 .launch.py 扩展名更灵活,但它会带来可读性成本.
避免在启动文件名中使用 autoware_ 前缀.
- 基本原理： 为了避免冗长.

`test`#

autoware_gnss_poser
└─ test
    ├─ test_foo.hpp  # or place under an `include` folder here
    └─ test_foo.cpp

放置源文件进行测试.参见单元测试了解详情.

Python 包#

警告

正在施工中