Nav2开发指南

这个部分包括开发Nav2的指南，例如如何从源代码构建、如何使用开发容器，以及如何参与其中。

• Build and Install
  • Install
  • Build
  • Generate Doxygen
  • Help
• Dev Containers
  • What, Why, How?
  • Prerequisites
  • Getting started
  • Security
• Getting Involved
  • Getting Involved
  • Process
  • Licensing
  • Developer Certification of Origin (DCO)

Generate Doxygen   

docker创建Nav2 

        使用Docker容器映像构建Nav2提供了一个可重复和可复制的环境，可以自动化和自我记录整个设置过程。您可以利用项目的Docker文件来构建和安装适用于各种发行版的Nav2，而不是手动调用上面文档中记录的开发工具。

        参见

        有关安装Docker或了解Docker文件的更多信息，请参阅官方文档：

        Docker引擎

        Dockerfile参考

        一旦您的系统设置完毕，您可以从存储库的根目录构建Nav2的Dockerfile：

export ROS_DISTRO=rolling
git clone https://github.com/ros-planning/navigation2.git --branch main
docker build --tag navigation2:$ROS_DISTRO \
  --build-arg FROM_IMAGE=ros:$ROS_DISTRO \
  --build-arg OVERLAY_MIXINS="release ccache lld" \
  --cache-from ghcr.io/ros-planning/navigation2:main \
  ./navigation2

        上述docker build命令使用指定路径到存储库的Dockerfile来创建一个带标签的映像，通过附加参数设置构建时变量，例如传递一组colcon mixins来配置工作空间的构建。检查Dockerfile中的指令，了解所有可用的构建时变量。该命令还指定了一个外部缓存源，以从Nav2的容器注册表中拉取最新的缓存映像，加快构建过程的速度。

        提示：上述缓存的映像用于Nav2 CI，但也可与Nav2 Dev容器一起使用！

生成 Doxygen 

        在Nav2存储库的根目录下运行该命令。它将生成一个包含文档的目录。文档的浏览器入口点是index.html.doxygen/doc/*

Dev Containers开发容器

        您可以使用开发容器构建项目，如果您更喜欢简化的设置体验。这意味着您可以使用与团队其他成员相同的工具和依赖项，包括我们的持续集成（CI）工作流程，而无需担心在您的主机上安装依赖项。此外，使用开发容器使得在本地或远程开发环境之间轻松切换变得简单，例如 GitHub Codespaces。

以下是关于开发容器的更多信息： 开发容器         一项开放规范，用于为容器提供特定于开发的内容和设置 在容器内进行开发         学习如何使用 Visual Studio Code 在 Docker 容器内进行开发 GitHub Codespaces 概览         一个托管在云端的开发环境

What, Why, How?

        让我们简要解释一下开发容器是什么，为什么要使用它们，以及它们的工作原理。

这里我们假设使用VS Code，但这同样适用于其他工具和服务，包括其他命令行界面、集成开发环境等，比如： 开发容器CLI         开放规范的参考实现 JetBrains Space | 在开发环境中进行开发         使用JetBrains产品与开发容器 支持工具         支持开发容器规范的工具和服务列表

What is a Dev Container?

        开发容器是一个 Docker 容器，其中包含您开发项目所需的所有工具和依赖项。它在一个自包含的环境中运行，并与其他容器和您的主机机器隔离开来。这使您可以在任何地方可靠地开发项目，尤其是针对 ROS（机器人操作系统）所针对的 Linux 发行版，而不受主机操作系统的限制。

Why use a Dev Container?

        开发容器提供了一个通用且一致的开发环境。它确保团队中的每个人都使用相同的工具和依赖项。它还使得在不同项目之间轻松切换变得容易，因为每个项目可以使用不同的容器。如果您在多个项目上工作，并且这些项目使用相同工具和依赖项的不同版本，比如不同版本的 ROS，这将特别有用。

How do Dev Containers work?

        当您在VS Code中打开项目时，VS Code会检查项目根目录下嵌套的开发容器配置。如果找到配置文件，它可以提示您在一个容器中重新打开项目。如果选择这样做，它会启动容器，连接到容器，并将您的项目文件夹挂载到容器内。然后您可以在容器中像本地一样使用VS Code。在设置容器时，VS Code 还可以尝试传递您本地环境的一些有用方面，比如 git 用户配置、X11 sockets 等。

这与早期用于定制和运行 Docker 容器进行开发的工具非常相似：

rocker | ROS + Docker

        一个用于运行带有叠加层和便捷选项（例如 GUI 界面等）的 Docker 容器的工具。

        由 Open Robotics 开发

ADE开发环境

        一个基于 Docker 的模块化工具，以确保开发者拥有共同、一致的开发环境。

        由 Apex.AI 开发

Prerequisites

要使用开发容器，您需要以下内容：

        在主机机器上安装并运行 Docker 引擎

        在任何远程机器上安装 Visual Studio Code

        在 VS Code 中安装开发容器扩展

或者，您可以直接从项目存储库使用 GitHub Codespaces，或者使用任何其他远程主机： 为存储库创建一个 Codespace         如何通过 GitHub CLI、VS Code 或 Web 浏览器为存储库创建 Codespace 在远程 Docker 主机上进行开发         如何使用 SSH 隧道或 TCP sockets 将 VS Code 连接到远程 Docker 主机

Getting started

        开始使用开发容器非常简单，只需在 VS Code 中打开项目，有两种方法：按照提示重新在容器中打开项目，或者显式地打开命令面板（Ctrl+Shift+P），然后选择 Remote-Containers: Reopen in Container。这将创建一个新的容器，在项目的默认 .devcontainer/devcontainer.json 配置文件中安装任何指定的扩展，并将项目的根目录挂载为工作区文件夹。容器创建完成后，VS Code 将连接到容器，然后您可以开始开发了。

单击 VS Code 中的“启动开发容器（显示日志）”通知允许您实时观察整个过程，就像看制作香肠一样，而在命令面板中键入“Dev Containers: Show Log”将列出所有可用命令，以便稍后查看和重新访问这些日志文件。

        在等待初始设置完成时，随意伸展一下，喝杯咖啡，或继续阅读以下指南，了解更多关于创建和使用开发容器的内容，或者如何在无头开发环境中可视化和利用图形用户界面。

        开发容器指南

               使用开发容器和支持工具开发 Nav2 的方法

Security安全

在启动派生的开发容器之前，请确保信任工作区的作者和内容。

     在使用开发容器时需要注意：它们是强大的工具，但可能构成安全风险，因为由于IDE扩展支持的任意代码执行能力，使自动化和便利性变得困难重重。在启动开发容器之前，请确保信任工作区和作者。例如，在审查拉取请求时，请验证补丁仍然是良性的，并且不会引入任何恶意代码。尽管在编译和运行打补丁的代码时需要保持警惕，但是使用具有提升的权限或文件系统访问权限的容器则需要更加谨慎。

关于信任工作区和扩展的更多信息通常可以在以下位置找到：         工作区信任         VS Code 用户指南：关于信任和配置工作区