警告

您正在阅读的 ROS 2 文档版本已达到 EOL（生命周期结束），不再受官方支持。如果您想了解最新信息，请访问 Jazzy.

ROS 2 入门指南

本指南旨在为新开发人员加入 ROS 2 团队时的入职培训提供补充。它主要供 ROS 2 团队使用，但也可能对其他团队有用。

申请访问 GitHub 组织

我们的代码联合在几个 GitHub 组织中，您需要访问这些组织，这样就可以使用分支而不是分叉来提交拉取请求：

• https://github.com/ros2

• https://github.com/ament

• https://github.com/osrf (可选，根据需要）

申请进入建筑工地

构建农场位于：ci.ros2.org

如需申请访问，请发送电子邮件至 玫瑰@osrfoundation.组织.

如何提供访问权限？

您的 GitHub 用户名必须以与现有用户相同的权限添加到 Jenkins (https://ci.ros2.org/configureSecurity/).任何现有用户都可以这样做。

如何访问运行 ci.ros2.org 的机器？

只有当你在 OSRF 工作或被要求登录机器时才会这样做。要想 ssh 进入 AWS 上的节点，你需要向 Tully Foote (tfootote@osrfoundation.组织).

申请访问 Google 驱动器 ROS 2 文件夹

只有当您在 OSRF 工作或需要访问特定文件时才会这样做。如需申请访问，请发送电子邮件至 玫瑰@osrfoundation.组织 (邮件列表上的任何人都可以分享）。

选择 DDS 域 ID

ROS 2 使用 DDS 作为底层传输，DDS 支持根据 "域 ID"（用于计算组播端口）对网络进行物理分割。我们在每台机器（或每组机器）上使用一个唯一的值，以防止每组 ROS 2 节点干扰其他开发者的测试。我们通过 ROS_DOMAIN_ID 环境变量，并使用文档来确保我们不会不小心选择了与别人相同的环境变量。不过，这只对将在 OSRF 网络上工作的人很重要，但在同一网络上有多个 ROS 2 用户的任何组织中进行设置也不失为一个好主意。

获取个人 ROS_DOMAIN_ID

前往 ROS 2 指定域 ID 电子表格 并预约 ID，或发送电子邮件至 玫瑰@osrfoundation.组织 并要求为您分配一个。号码在 128 以下为佳。

为确保始终设置，请在您的 ~/.bashrc 或同等学历：

出口 ROS_DOMAIN_ID=<your_domain_id>；

观察 ROS 2 存储库

我们尝试将责任分散到整个团队，因此我们要求每个人都关注 ROS 2 的主要资源库。

• 我现在在看什么？

  • https://github.com/watching

• 如何观看资源库？

  • https://help.github.com/articles/watching-repositories/

• 我应该关注哪些软件源？

  • 中列出的所有资源库 ros2.repos 文件包括已注释的内容、

  • 此外，ROS 2 组织还提供了所有这些额外的资源库：

    • https://github.com/ros2/ci

    • https://github.com/ros2/design

    • https://github.com/ros2/ros_astra_camera

    • https://github.com/ros2/ros_core_documentation

    • https://github.com/ros2/ros2

    • https://github.com/ros2/sros2

    • https://github.com/ros2/turtlebot2_demo

    • https://github.com/ros2/joystick_drivers

开发人员工作流程

我们使用以下工具跟踪与即将发布的版本和大型项目相关的未结票据和活动 PR GitHub 项目板.

通常的工作流程是（这份清单正在编制中）：

• 讨论设计（GitHub 票据，必要时召开会议）

• 将实施工作分配给团队成员

• 在功能分支上编写实施方案

  • 请查看 开发人员指南 指导原则和最佳做法

• 编写测试

• 启用并运行衬垫

• 使用 胶管 测试 (见 科尔康教程)

• 当所有内容都在本地构建完成且无警告、所有测试都通过后，在功能分支上运行 CI：

  • 转至 ci.ros2.org

  • 登录（右上角）

  • 点击 ci_launcher 工作

  • 单击 "使用参数构建"（左侧栏）

  • 在第一个方框 "CI_BRANCH_TO_TEST "中输入功能分支名称

  • 点击 构建 按钮

• 如果您的用例需要运行代码覆盖：

  • 转至 ci.ros2.org

  • 登录（右上角）

  • 点击 ci_linux 覆盖范围 工作

  • 单击 "使用参数构建"（左侧栏）

  • 确保 "CI_BUILD_ARGS "和 "CI_TEST_ARGS "保留默认值

  • 点击 构建 按钮

  • 本文件末尾有说明如何 解读报告结果 和 计算覆盖率

• 如果构建的 CI 作业没有警告、错误和测试失败，请将作业链接发布到您的 PR 或汇总所有 PR 的高级票据上（请参阅示例 这里)

  • 请注意，这些徽章的标记在 ci_launcher 工作

• 要让 PR 接受审查，您需要贴上 "审查中 "的标签：

  • 通过 GitHub 界面

    • 点击标签旁边的""。

    • 如果适用，去掉 "进行中 "标签

    • 添加 "审查中 "标签

  • 如果 PR 是项目委员会的一部分：

    • 将卡片从 "进行中 "拖至 "审查中"

• 当 PR 获得批准后：

  • 提交 PR 的人使用 "压扁并合并 "选项合并 PR，以便我们保持历史记录的完整性

    • 如果提交值得分开：将所有挑刺/linters/typo 合并，然后合并剩余的提交集

      • 注意：每个 PR 都应针对特定功能，因此压扁和合并在 99% 的情况下都有意义

• 合并后删除分支

GitHub 提示

使用以下方法将 PR 与它们所解决的问题联系起来 关键词 和票据编号。一旦拉取请求被合并，该问题就会关闭。

• 在同一个软件仓库中："修正 #216

• 在另一个软件仓库中"fixes ros2/rosidl#216"

建设农场简介

建设农场位于 ci.ros2.org.

每天晚上，我们都会运行夜间工作，在不同平台的不同场景中构建和运行所有测试。此外，在合并之前，我们会在这些平台上测试所有拉取请求。

这就是当前的目标平台和架构集，尽管它会随着时间的推移而变化：

• Ubuntu 16.04 Xenial

  • amd64

  • aarch64

• macOS 10.12 Sierra

  • amd64

• Windows 10

  • amd64

建筑工地上有几类工作：

• 手动任务（由开发人员手动触发）：

  • ci_linux: 在 Ubuntu Xenial 上构建 + 测试代码

  • ci_linux-aarch64：在 ARM 64 位机器（arch64）上的 Ubuntu Xenial 上构建和测试代码

  • ci_linux_coverage：构建 + 测试 + 生成测试覆盖率

  • ci_osx：在 MacOS 10.12 上构建和测试代码

  • ci_windows：在 Windows 10 上构建和测试代码

  • ci_launcher：触发上述所有工作

• 夜间运行（每晚运行）：

  • 调试：使用 CMAKE_BUILD_TYPE=Debug 生成并测试代码

    • nightly_linux_debug

    • nightly_linux-aarch64_debug

    • nightly_osx_debug

    • nightly_win_deb

  • 发布：使用 CMAKE_BUILD_TYPE=Release 构建并测试代码

    • nightly_linux_release

    • nightly_linux-aarch64_release

    • nightly_osx_release

    • 每晚赢利

  • 重复：构建然后运行每个测试，最多 20 次或直到失败为止（又称 "松散性猎手"）。

    • nightly_linux_repeated

    • nightly_linux-aarch64_repeated

    • 每晚重复

    • nightly_win_rep

  • 覆盖范围

    • nightly_linux_coverage：构建 + 测试代码 + 分析 c/c++ 和 python 的覆盖率

      • 结果作为 cobertura 报告导出

• 打包（每晚运行，针对 fastrtps；结果捆绑到存档中）：

  • 包装 Linux

  • 包装

  • 打包窗口

关于覆盖运行的说明

ROS 2 软件包的组织方式是，特定软件包的测试代码不仅包含在该软件包中，也可能存在于其他软件包中。换句话说：软件包可以在测试阶段使用属于其他软件包的代码。

为了达到 ROS 2 核心软件包中所有可用代码的覆盖率，建议使用一组固定的建议软件源进行构建。这组资源库在 Jenkins 的覆盖作业默认参数中已定义。

如何从建筑群报告中读取覆盖率

查看特定软件包的覆盖范围报告：

• 当 ci_linux 覆盖范围 构建完成后，点击 覆盖范围 报告

• 向下滚动到 覆盖范围 细目 由 包装 桌

• 在表格中，查看名为 "姓名 "的第一列

构建库中的覆盖报告包括 ROS 工作区中使用的所有软件包。覆盖率报告包括同一软件包对应的不同路径：

• 用表格命名条目： src.*.<repository_name>.<package_name>.* 这些与软件包中针对自身源代码的可用单元测试运行相对应

• 用表格命名条目： build.<repository_name>.<package_name>.* 这些与软件包中针对其在构建或配置时生成的文件的可用单元测试运行相对应

• 用表格命名条目： install.<package_name>.* 这些对应于来自其他软件包测试运行的系统/集成测试

如何从建筑群报告中计算覆盖率

使用自动脚本获取综合单位覆盖率：

• 从 ci_linux_coverage Jenkins 构建中复制构建的 URL

• 下载 get_coverage_ros2_pkg 脚本

• 执行脚本： ./get_coverage_ros2_pkg.py <jenkins_build_url>； <ros2_package_name>； (阅读说明)

• 抓取脚本输出中 "合并单元测试 "最后一行的结果

替代方法：从覆盖率报告中获取综合单位覆盖率（需要手动计算）：

• 完成 ci_linux_coverage 的构建后，点击 科贝图拉 覆盖范围 报告

• 向下滚动到 覆盖范围 细目 由 包装 桌

• 在该表的第一列 "名称 "下查找（其中<package_name>是正在测试的软件包）：

  • 模式下的所有目录 src.*.<repository_name>.<package_name>.* 抓取 "线条 "栏中的两个绝对值。

  • 模式下的所有目录 build/.<repository_name>.* 抓取 "线条 "栏中的两个绝对值。

• 根据前面的选择：对于每个单元格，第一个值是已测试行数，第二个值是代码总行数。将所有行汇总，得出测试行总数和被测代码行总数。除以得出覆盖率。

如何使用 lcov 在本地测量覆盖率 (Ubuntu)

要在自己的机器上测量覆盖率，请安装 lcov.代码块:: bash

sudo apt install -y lcov

本节其余部分假定您在 colcon 工作区中工作。在调试中使用覆盖标志进行编译。您可以随意使用 colcon 标志来针对特定软件包进行编译。

胶管 构建 --cmake-args -dcmake_build_type（构建类型=调试 -dcmake_cxx_flags。="；${cmake_cxx_flags} --覆盖范围"； -dcmake_c_flags="；${CMAKE_C_FLAGS} --覆盖范围"；

lcov 需要一个初始基线，您可以使用以下命令生成初始基线。根据需要更新输出文件的位置。

lcov --无外部 --捕捉 --初始 --目录 . --输出文件 ~/ros2_base.info

运行与覆盖率测量相关的软件包测试。例如，如果测量 rclcpp 还有 test_rclcpp

胶管 测试 --软件包--选择 rclcpp test_rclcpp

用类似的命令捕捉 lcov 结果，这次去掉了 --初始 旗子

lcov --无外部 --捕捉 --目录 . --输出文件 ~/ros2.info

合并跟踪 .info 文件：

lcov --添加跟踪文件 ~/ros2_base.info --添加跟踪文件 ~/ros2.info --输出文件 ~/ros2_coverage.info

生成 html，方便对覆盖线进行可视化和注释。

mkdir -p 覆盖率 genhtml ~/ros2_coverage.info --输出目录 覆盖率

学习 ROS 2 的高级概念

所有 ROS 2 设计文件可在以下网站获取 https://design.ros2.org/ 并在 https://docs.ros2.org/.