ROS 2开发者指南 [1644]
目录 []
这个页面定义了我们在开发ROS 2时采用的实践和策略。 [1645]
质量实践 [1651]
根据它们所遵循的开发实践，软件包可以根据不同的质量水平进行分类，根据《REP 2004：软件包质量分类指南 <https://www.ros.org/reps/rep-2004.html>》中的准则进行分类。这些分类根据版本管理、测试、文档编写等方面的策略进行区分。 [1652]
以下部分是我们遵循的特定开发规则，以确保核心软件包具有最高质量（“一级”）。我们建议所有ROS开发人员努力遵守以下政策，以确保ROS生态系统的质量。 [1653]
版本管理 [1654]
我们将使用`语义化版本指南 <http://semver.org/>`__（semver）进行版本管理。 [1655]
我们还将遵守一些基于``semver``的ROS特定规则，这些规则是在``semver``完整意义上建立的。 [1656]
不应该在已发布的ROS发行版中进行主要版本增加（即破坏性变更） [1657]
对于编译代码，ABI（应用二进制接口）被视为公共接口的一部分。任何需要重新编译依赖代码的更改都被视为主要更改（破坏性的） [1661]
ABI破坏性更改可以在次要版本升级之前（加入滚动发布）进行 [1662]
尽管 Dashing 和 Eloquent 的主要版本组件为``0``，我们仍对核心包的API稳定性进行强制执行，尽管 SemVer 规范 中有关初始开发的规定 [1663]
随后，软件包应努力达到成熟状态并增加到版本``1.0.0``以符合``semver``的规范 [1664]
注意事项 [1665]
这些规则是*尽力而为*的。在极端情况下，可能需要在一个主要版本/发布中打破API的兼容性。对于非计划中的兼容性断裂，是将主版本号还是次版本号增加将根据具体情况进行评估。 [1666]
例如，考虑一个涉及发布的 X-turtle 和对应的主版本号为``1.0.0``的 Y-turtle 的情况。 [1667]
如果在 X-turtle 中发现必须打破API兼容性的问题，显然不能选择升级到``2.0.0``，因为``2.0.0``已经存在。 [1668]
在这种情况下处理X-turtle版本的解决方案，都是非理想的，包括： [1669]
增加X-turtle的次要版本：非理想，因为它违反了语义化版本规范（SemVer）中破坏性变更必须增加主要版本的原则。 [1670]
将X-turtle的主要版本升级到超过Y-turtle（
3.0.0）：非理想，因为旧发行版的版本将会高于已有的新发行版版本，这将使得特定版本条件代码失效/破坏。 [1671]
开发人员将需要决定使用哪种解决方案，或者更重要的是，他们愿意违背哪个原则。我们不能建议选用其中一种，但无论哪种情况，我们都要求采取明确的措施手动向用户传达中断情况及其解释（不仅仅是版本号的增加）。 [1672]
如果没有 Y-turtle，即使修复只是一个补丁，X-turtle 也必须升级到 2.0.0。这种情况符合 SemVer 规则，但违反了我们自己的规定，即在发布的分发版中不应引入主要增量。 [1673]
这就是为什么我们将版本规则视为“尽力而为”。尽管上述例子不太可能出现，但准确定义我们的版本系统非常重要。 [1674]
公共 API 声明 [1675]
根据 semver，每个软件包必须明确声明一个公共 API。我们将使用软件包的质量声明中的“公共 API 声明”部分来声明哪些符号是公共 API 的一部分。 [1676]
对于大多数 C 和 C++ 包，声明是其安装的任何头文件。然而，定义一组被视为私有的符号也是可以接受的。在头文件中避免私有符号可以帮助实现 ABI 的稳定性，但并非必需。 [1677]
对于其他语言如 Python，必须明确定义公共 API，以便清楚地知道哪些符号可以依赖于版本指南。公共 API 还可以扩展到构建工件，如配置变量、CMake 配置文件等，以及可执行文件、命令行选项和输出。包的文档应清楚地说明公共 API 的任何元素。如果你使用的内容在包的文档中没有明确列出作为公共 API 的一部分，那么你不能指望它在次要或修补版本之间不发生变化。 [1678]
废弃策略 [1679]
在可能的情况下，我们还将使用主要版本增量的滴答滴答废弃和迁移策略。新的废弃将在新的发行版中提出，伴随着编译器警告，表示该功能正在被废弃。在下一个发布中，该功能将被完全移除（不再有警告）。 [1680]
示例函数 foo 已弃用，并被函数 bar 替代： [1681]
版本 [1523] |
API [1682] |
|---|---|
X-turtle [1683] |
void foo(); [1684] |
Y-龟 [1685] |
[[已弃用("使用bar()")]] void foo(); <br> void bar(); [1686] |
Z-龟 [1687] |
void bar(); [1688] |
在发行版发布之后，我们不能添加废弃项。然而，废弃项不一定需要引发主要版本的升级。如果在发行版发布之前进行次要版本的升级，就可以引入废弃项（类似于破坏ABI的更改）。 [1689]
例如，如果X-turtle作为``2.0.0``开始开发，可以在X-turtle发布之前的``2.1.0``中添加废弃项。 [1690]
我们将尽可能在不同发行版之间保持兼容性。然而，与语义化版本控制（SemVer）相关的注意事项一样，特定情况下可能无法完全遵守打勾或废弃项。 [1691]
变更控制流程 [1692]
所有更改都必须通过拉取请求进行。 [1693]
我们将在ROSCore仓库的拉取请求中执行`开发者证书 (DCO) <https://developercertificate.org/>`_ 的强制要求。 [1694]
对于每个拉取请求，始终在所有 一级支持平台 上运行CI作业，并在拉取请求中包含作业链接。（如果您无权访问Jenkins作业，将有人为您触发作业。） [1698]
需要至少来自未参与拉取请求撰写的其他开发人员的1个批准才能被视为已批准。在合并之前需要批准。 [1699]
软件包可以选择增加此数字。 [1700]
在合并相关更改之前，必须先提出对文档（API文档、功能文档、发布说明等）所需的任何更改。 [1701]
文档 [1708]
所有的软件包都应该在其README中包含或从其README中链接到以下文档元素： [1709]
描述和目的 [1710]
公共API的定义和描述 [1711]
示例 [1507]
如何构建和安装（应该引用外部工具/工作流程） [1712]
如何构建和运行测试 [1713]
如何构建文档 [1714]
如何进行开发（对于描述诸如``python setup.py develop``之类的内容很有用） [1715]
许可证和版权声明 [1716]
每个源文件必须有一个许可证和版权声明，通过自动化检查工具进行检查。 [1717]
每个软件包必须有一个LICENSE文件，通常是Apache 2.0许可证，除非该软件包有现有的宽松许可证（例如，rviz使用三条款的BSD许可证）。 [1718]
每个软件包应该对自身和其目的进行描述，尽量假设读者没有关于ROS或其他相关项目的先前知识而意外发现该软件包。 [1719]
每个软件包应该定义和描述其公共API，以便用户可以合理地预期语义版本控制政策所覆盖的内容。即使在C和C++中，公共API可以通过API和ABI检查来强制执行，这也是一个很好的机会来描述代码的结构和每个部分的功能。 [1720]
理应很容易通过任何软件包的文档了解如何构建、运行、构建并运行测试，并构建文档。显然，我们应该避免在常见工作流程中重复自己，比如在工作空间中构建软件包，但基本工作流程应该被描述或引用。 [1721]
最后，它应该包含开发者的任何文档。这可能包括使用类似 python setup.py develop 的方法测试代码的工作流程，或者可能意味着描述如何利用软件包提供的扩展点。 [1722]
示例： [1723]
功能：https://docs.ros.org/hydro/api/capabilities/html/ [1724]
这个例子展示了描述公共API的文档 [1725]
catkin_tools：https://catkin-tools.readthedocs.org/en/latest/development/extending_the_catkin_command.html [1726]
这是描述软件包扩展点的示例 [1727]
（API文档尚未自动生成） [1728]
测试 [1729]
所有的软件包都应该具备一定程度的 系统测试、集成测试和/或单元测试。 [1730]
**单元测试**应该始终位于被测试的软件包中，并且应该使用诸如``Mock``之类的工具，尝试在构建的场景中测试代码库的狭窄部分。单元测试不应引入非测试工具的测试依赖，例如 gtest、nosestest、pytest、mock 等... [1731]
**集成测试**可以测试代码的各个部分之间或代码与系统之间的交互。它们通常以我们期望用户使用它们的方式测试软件接口。与单元测试类似，集成测试应该位于被测试的软件包中，除非绝对必要，否则不应引入非工具测试依赖，即所有非工具依赖都应在极端审查下才被允许，因此应尽量避免使用。 [1732]
**系统测试**旨在测试软件包之间的端到端情况，并应位于它们自己的软件包中，以避免软件包膨胀或耦合以及避免循环依赖。 [1733]
通常情况下，应尽量减少外部或跨包的测试依赖，以避免循环依赖和紧密耦合的测试包。 [1734]
所有的包都应该有一些单元测试和可能的集成测试，但其数量取决于包的质量分类。以下小节适用于“Level 1”包： [1735]
代码覆盖率 [1736]
我们将提供行覆盖率，并保证行覆盖率达到95%以上。如果有合理降低百分比目标的情况，必须明确记录。我们可以提供分支覆盖率，或者将某些代码排除在覆盖率之外（测试代码、调试代码等）。在合并更改之前，我们要求覆盖率要增加或保持不变，但在适当的理由下，可能会接受降低代码覆盖率的更改（例如，删除以前覆盖的代码可能会导致百分比下降）。 [1737]
一般实践 [1743]
一些实践适用于所有 ROS 2 开发。 [1744]
这些实践不会影响软件包质量等级（如 REP 2004 中所述），但在开发过程中仍然强烈推荐。 [1745]
问题 [1746]
在提交问题时，请确保： [1747]
提供足够的信息让其他人能够理解问题。在ROS 2中，以下几点对于缩小问题原因范围非常有帮助。在每个类别中尽可能尝试多种替代方案将特别有帮助。 [1748]
包含一系列重现问题的步骤。 [1754]
如果遇到错误，请考虑提供一个`简短、自包含、正确（可编译）的示例 <http://sscce.org/>`__。如果其他人能够轻松地重现错误，问题更有可能被解决。 [1755]
提及已尝试过的故障排除步骤，包括： [1756]
分支 [1759]
注解
这只是一些指南。选择分支名称以匹配其自身工作流程是包维护者的责任。 [1760]
在一个包的源代码库中，为其所针对的每个ROS发行版创建**单独的分支**是一种良好的做法。这些分支通常以它们所针对的发行版命名。例如，针对Humble发行版的开发可以创建一个名为``humble``的分支。 [1761]
从这些分支中也可以发布版本，以适应相应的发行版。针对特定ROS发行版的开发可以在相应的分支上进行。例如：针对``foxy``的开发提交将被放到``foxy``分支，并且针对``foxy``的软件包发布将从同一分支进行。 [1762]
注解
这需要软件包维护者根据需要执行回溯或向前移植，以保持所有分支与功能的同步。维护者还必须对所有仍然进行软件包发布的分支进行常规维护（修复错误等）。 [1763]
例如，如果某个功能已合并到特定于Rolling的分支（例如``rolling``或``main``），并且该功能也适用于Humble发行版（不会破坏API等），那么将该功能回溯到Humble特定分支是一种良好的做法。 [1764]
如果存在新功能或错误修复，则维护者可以为这些旧的发行版进行发布。 [1765]
关于 main 和 rolling 呢？ [1766]
main 通常目标为 Rolling <../../Releases/Release-Rolling-Ridley>`（即下一个尚未发布的ROS版本），但维护者可能决定从 ``rolling` 分支进行开发和发布。 [1767]
拉取请求 [1768]
一个拉取请求应该只关注一个更改。不同的更改应该放入不同的拉取请求中。参见 GitHub完美拉取请求指南。 [1769]
补丁应该尽量保持最小的大小，并避免任何不必要的更改。 [1770]
拉取请求必须包含最少数量的有意义的提交。 [1771]
在拉取请求正在审核中时，您可以创建新的提交。 [1772]
在合并拉取请求之前，所有的更改应该被压缩成少量的语义提交，以保持历史清晰。 [1773]
在审核期间避免压缩提交记录。您的审阅人员可能不会注意到您所做的更改，从而引入混淆的可能性。而且，无论如何在合并之前都要进行压缩；提前压缩没有任何好处。 [1774]
任何开发者都可以审核并批准拉取请求（请参阅 General Principles）。 [1775]
当您正在处理尚未准备好审核或合并的更改时，请使用草稿拉取请求。当这些更改准备好进行审核时，将拉取请求从草稿状态移出。请注意，如果您想从草稿拉取请求中获得特定人员的早期反馈意见，可以在拉取请求的描述或评论中提及他们。 [1776]
如果您的拉取请求依赖于其他拉取请求，请通过在拉取请求的描述顶部添加
- Depends on <link>来链接到每个所依赖的拉取请求。这样做有助于审阅人员了解拉取请求的上下文。 [1777]当您开始审查拉取请求时，请在拉取请求上发表评论，以便其他开发人员知道您正在进行审查。 [1778]
拉取请求审查不是只读的，审查人员会发表评论，然后等待作者处理。作为审查人员，可以自由地进行一些小的改进（拼写错误、样式问题等）。作为拉取请求的发起人，如果您在一个分支上工作，请勾选`允许来自上游贡献者的编辑 <https://github.com/blog/2247-improving-collaboration-with-forks>`__ 选项，这将有助于前述情况。作为审查人员，也可以自由地进行一些较大的改进，但考虑将它们放在一个单独的分支中（在评论中提到新的分支，或者从新分支向原始分支发起另一个拉取请求）。 [1779]
任何开发人员（作者、审查人员或其他人）都可以合并任何已批准的拉取请求。 [1780]
库版本管理 [1781]
我们将同时对一个包中的所有库进行版本控制。这意味着库的版本继承自该包。这样可以防止库和包的版本分歧，并与共享同一个代码仓库的包发布策略保持一致。如果您需要库具有不同的版本，请考虑将它们拆分为不同的包。 [1782]
开发过程 [1783]
默认分支（大多数情况下是滚动分支）必须始终构建，通过所有测试并且没有警告信息。如果出现任何回归问题，最重要的是至少恢复到先前的状态。 [1784]
始终使用启用了测试的构建。 [1785]
在对更改进行推送之前，始终在本地运行测试，并确保它们在拉取请求中正常工作。除了使用自动化测试外，还要手动运行修改后的代码路径，以确保补丁按预期工作。 [1786]
对于每个拉取请求，始终运行适用于所有平台的CI作业，并在拉取请求中包含作业链接。 [1787]
有关推荐的软件开发工作流程的更多详细信息，请参阅“软件开发生命周期”_部分。 [1788]
RMW API的更改 [1789]
当更新 RMW API 时，需要同时更新Tier 1中间件库的RMW实现。例如，RMW API 中引入了新函数 rmw_foo()，必须在以下软件包中实现（截至ROS Galactic版本）： [1790]
如果可行的话，也应考虑更新非一级中间件库（例如，根据更改的大小）。有关中间件库及其等级的列表，请参阅 REP-2000。 [1794]
跟踪任务 [1795]
为了帮助组织ROS 2的工作，核心ROS 2开发团队使用看板式 GitHub项目看板。 [1796]
然而，并不是所有问题和拉取请求都在项目看板上跟踪。一个看板通常表示一个即将发布的版本或特定的项目。可以通过浏览 ROS 2存储库的个别问题页面 来浏览票证。 [1797]
任何给定的ROS 2项目看板中的列名称和用途可能会有所不同，但通常遵循相同的一般结构： [1798]
待办事项：与项目相关的问题，可以分配处理 [1799]
进行中：正在进行工作的活动拉取请求 [1800]
审核中：工作已完成且准备好进行审核的拉取请求，以及目前正在进行主动审核的请求 [1801]
完成：合并/关闭拉取请求和相关问题（仅供参考） [1802]
如果要请求更改权限，请在您感兴趣的工单上发表评论即可。根据复杂程度，描述您打算如何解决问题可能会很有用。我们将更新状态（如果您没有权限），然后您可以开始处理拉取请求。如果您经常做出贡献，我们可能会直接授予您管理标签等权限。 [1803]
文件系统布局 [1812]
软件包和存储库的文件系统布局应遵循相同的约定，以便为浏览我们的源代码的用户提供一致的体验。 [1813]
包布局 [1814]
src: 包含所有的 C 和 C++ 代码 [1815]同时包含未安装的 C/C++ 头文件 [1816]
include: 包含所有已安装的 C 和 C++ 头文件 [1817]<package name>：对于所有已安装的 C 和 C++ 标头，它们应该由包名进行命名空间分隔 [1818]
<package_name>：包含所有 Python 代码 [1819]test：包含所有自动化测试和测试数据 [1820]config：包含配置文件，例如 YAML 参数文件和 RViz 配置文件 [1821]doc：包含所有的文档 [1822]launch：包含所有的启动文件 [1823]package.xml：根据`REP-0140 <https://www.ros.org/reps/rep-0140.html>`_定义的（可能会更新用于原型设计） [1824]CMakeLists.txt：仅限使用 CMake 的 ROS 软件包 [1825]setup.py：仅适用于仅使用Python代码的ROS软件包 [1826]README：可以作为项目的首页在GitHub上显示 [1827]CONTRIBUTING：描述贡献准则 [1831]这可能涉及许可证的含义，例如使用 Apache 2 许可证时 [1832]
LICENSE：此软件包的许可证副本或许可证 [1833]
上游软件包 [16102]
Debian和Ubuntu上游的软件包 [16103]
感谢Jochen Sprickerhof和Leopold Palomo-Avellaneda的辛勤努力，一些`ROS 2软件包现在可以从Debian和Ubuntu的主要存储库中获取<https://wiki.debian.org/DebianScience/Robotics/ROS2/Packages>`_。`这里有Jochen在ROSCon 2015上的简要概述<https://vimeo.com/142151399#t=29m15s>`_。原始的ROS软件包已经根据Debian的准则进行了修改，包括将软件包拆分为多个部分，在某些情况下更改名称，根据FHS准则安装到/usr，并在共享库上使用soversions。 [16104]
此外，一些引导依赖项，如命令行工具如``vcstool``和``colcon``以及一些库如``osrf-pycommon``和``ament``也被上游打包。 [16105]
与来自http://packages.ros.org的OSRF提供的ROS软件包不同，上游存储库中的软件包没有附加到特定的:doc:ROS分发版。相反，它们代表了时间上的快照，将定期在Debian不稳定版本中更新，然后在不同的Debian和Ubuntu发行版中的各个时间点被锁定。 [16106]
不要混合使用 [16107]
我们强烈建议不要在同一系统上混合使用来自上游Debian/Ubuntu和来自http://packages.ros.org的ROS软件包。在某些情况下，这样的混合系统可能会正常工作，但两组软件包之间可能会产生负面互动。我们正在与Jochen和他的朋友合作，通过文档和软件包冲突规范来最小化问题的可能性，但我们预计一些风险仍然存在，包括一些相当微妙的问题。 [16108]
因此，我们建议您选择要么从上游安装软件包，要么从http://packages.ros.org安装，但不要同时两者兼而有之。不仅不应该同时安装来自两者的软件包，而且如果您打算使用上游软件包，那么您甚至不应该在apt源中具有http://packages.ros.org条目（即在``/etc/apt/sources*``中的任何文件中）。同时启用两者可能会导致两个来源之间名称重叠的软件包混合，例如``python3-rospkg``。 [16109]
开发者工作流程 [16114]
我们使用 GitHub项目面板 来跟踪与即将发布的版本和较大项目相关的未解决问题和活动中的PR。 [16115]
通常的工作流程是： [16116]
讨论设计（在适当的存储库上的GitHub票证，并在需要时在 https://github.com/ros2/design 上创建设计PR） [16117]
在一个分支上的特性分支上编写实现 [16118]
编写测试 [16120]
启用并运行代码检查工具 [16121]
一旦本地构建没有警告并且所有测试都通过，请在你的功能分支上运行CI： [16123]
访问 ci.ros2.org [16124]
登录（右上角） [16125]
点击
ci_launcher作业 [16126]点击"使用参数构建"（左列） [16127]
在第一个框中输入"CI_BRANCH_TO_TEST"，输入您的特性分支名称 [16128]
点击
build按钮 [16129]
(如果您不是ROS 2的贡献者，您无法访问CI工作区。在这种情况下，请联系您的PR审查者为您运行CI) [16130]
如果您的使用场景需要运行代码覆盖率: [16131]
如果 CI 作业在没有警告、错误和测试失败的情况下构建成功，请在您的 PR 或汇总所有 PR 的高级票证上发布您作业的链接（参见示例 here) [16135]
请注意，这些徽章的 Markdown 代码位于“ci_launcher”作业的控制台输出中 [16136]
当 PR 被批准后： [16137]
合并后删除该分支 [16140]
架构开发实践 [16141]
本节描述了在对ROS 2进行重大架构更改时应采用的理想生命周期。 [16142]
软件开发生命周期 [16143]
本节逐步描述了如何规划、设计和实现一个新功能： [16144]
编写设计文档 [16155]
设计文档不得包含机密信息。是否需要为您的更改编写设计文档取决于任务的大小。 [16156]
您正在进行小的更改或修复错误： [16157]
不需要设计文档，但应在适当的存储库中打开一个问题来跟踪工作并避免重复努力。 [16158]
您正在实施新功能或希望为OSRF拥有的基础架构（如Jenkins CI）做贡献： [16159]
需要设计文档，并应贡献给 ros2/design，以便在 https://design.ros2.org/ 上访问。 [16160]
您应该fork存储库并提交拉取请求，详细说明设计。 [16161]
在拉取请求或提交消息中提及相关的ros2问题（例如，
任务ros2/ros2#<问题编号>的设计文档）。详细说明可在`ROS 2 Contribute <https://design.ros2.org/contribute.html>`__页面找到。设计评论将直接在拉取请求上进行。 [16162]
如果任务计划在特定版本的ROS中发布，应在拉取请求中包含这些信息。 [16163]
设计文档审查 [16164]
一旦设计准备好进行审查，应打开拉取请求并指定适当的审阅者。建议将项目所有者（即所有受影响软件包的维护者，根据``package.xml``维护者字段定义，参见`REP-140 <https://www.ros.org/reps/rep-0140.html#maintainer-multiple-but-at-least-one>`__）作为审阅者。 [16165]
如果设计文档很复杂或者审阅人员的日程安排有冲突，可以设置一个可选的设计审查会议。在这种情况下， [16166]
会议之前 [16167]
在会议期间 [16173]
任务负责人主导会议，提出他们的想法，并管理讨论，以确保在规定时间内达成一致意见 [16174]
会议之后 [16175]
一旦达成共识： [16184]
确保已合并`ros2/design <https://github.com/ros2/design/>`__的拉取请求（如果适用） [16185]
更新并关闭与此设计任务相关的 GitHub 问题 [16186]
实现 [16148]
开始之前，请参阅 Pull requests 部分以了解最佳实践。 [16187]
对于每个需要修改的存储库： [16188]
修改代码，完成后或定期备份工作，然后进入下一步。 [16189]
使用``git add -i``进行自我审查，并将更改添加到暂存区。 [16190]
使用``git commit -s``创建一个新的带有签名的提交。 [16191]
构建农场介绍 [16207]
构建农场位于 ci.ros2.org。 [16208]
每晚我们运行夜间任务，对各种场景和平台进行构建和运行所有测试。此外，在合并之前，我们还会将所有拉取请求与这些平台进行测试。 [16209]
这是当前的目标平台和架构设置，尽管它会随时间变化而发展: [16210]
构建农场上有几类工作： [16215]
手动工作（由开发人员手动触发）： [16216]
每晚运行的夜间任务： [16222]
打包（每晚运行；结果打包成一个归档文件）： [16238]
通过提供源码和二进制包的构建、持续集成、测试和分析，另外两个构建农场支持 ROS / ROS 2 生态系统。 [16241]
有关详细信息、常见问题和故障排除，请参阅：构建农场。 [16242]
覆盖率运行注意事项 [16243]
ROS 2软件包的组织方式是，给定软件包的测试代码不仅包含在该软件包内，还可以存在于其他软件包中。换句话说，在测试阶段，软件包可以执行属于其他软件包的代码。 [16244]
为了达到ROS 2核心软件包中所有可用代码的覆盖率，建议使用一组固定的建议存储库运行构建。该集合在Jenkins中的覆盖率作业的默认参数中定义。 [16245]
如何从构建工厂报告中读取覆盖率 [16246]
查看给定包的覆盖率报告： [16247]
当``ci_linux_coverage``构建完成后，点击``Coverage Report`` [16248]
向下滚动到``Coverage Breakdown by Package``表格 [16249]
在表格中，查看名为"Name"的第一列 [16250]
构建工厂中的覆盖率报告包括在ROS工作空间中使用的所有软件包。覆盖率报告包括与同一软件包对应的不同路径： [16251]
如何从构建农场报告中计算覆盖率 [16255]
使用自动脚本获取组合单元覆盖率： [16256]
替代方法：从覆盖率报告中获取组合单元覆盖率（需要手动计算）： [16261]
如何使用 lcov（Ubuntu）在本地测量覆盖率 [16267]
要在自己的机器上测量覆盖率，请安装``lcov``。 [16268]
sudo apt install -y lcov
本节的其余部分假设您正在使用自己的 colcon 工作空间。使用覆盖率标志进行调试编译。可以使用 colcon 标志来针对特定的软件包。 [16269]
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS="${CMAKE_CXX_FLAGS} --coverage" -DCMAKE_C_FLAGS="${CMAKE_C_FLAGS} --coverage"
lcov 需要一个初始基准，您可以使用以下命令生成。根据您的需要更新输出文件位置。 [16270]
lcov --no-external --capture --initial --directory . --output-file ~/ros2_base.info
运行测试以获得与覆盖率测量相关的软件包。例如，如果同时测量``rclcpp``和``test_rclcpp`` [16271]
colcon test --packages-select rclcpp test_rclcpp
使用类似的命令捕获 lcov 结果，但这次不使用``--initial``标志。 [16272]
lcov --no-external --capture --directory . --output-file ~/ros2.info
合并追踪的 .info 文件： [16273]
lcov --add-tracefile ~/ros2_base.info --add-tracefile ~/ros2.info --output-file ~/ros2_coverage.info
生成 HTML，以便轻松可视化和标注覆盖的代码行。 [16274]
mkdir -p coverage
genhtml ~/ros2_coverage.info --output-directory coverage