使用 colcon 构建软件包

**目标：**使用``colcon``构建一个ROS 2工作空间。

教程级别: 初学者

**时间：**20分钟

这是一个简要教程，介绍如何使用``colcon``创建和构建ROS 2工作空间。它是一个实用教程，不旨在取代核心文档。

背景

colcon``是对ROS构建工具``catkin_make、catkin_make_isolated、``catkin_tools``和``ament_tools``的改进。有关colcon设计的更多信息，请参阅`此文档 <https://design.ros2.org/articles/build_tool.html>`__。

源代码可以在`colcon GitHub组织 <https://github.com/colcon>`__中找到。

先决条件

安装 colcon

sudo apt install python3-colcon-common-extensions

安装 ROS 2

要构建示例，您需要安装 ROS 2。

请按照 安装说明 进行操作。

注意

如果从Debian软件包安装，请参考 桌面安装 进行教程。

基础知识

ROS工作空间是一个具有特定结构的目录。通常有一个 src 子目录。在该子目录下是ROS软件包的源代码所在位置。通常该目录开始时为空。

colcon进行外部构建。默认情况下，它会创建以下目录作为 src 目录的同级目录：

  • build 目录将用于存储中间文件。对于每个软件包，将在其中创建一个子文件夹，例如在该子文件夹中调用 CMake。

  • install 目录是每个软件包将要安装到的位置。默认情况下，每个软件包将被安装到单独的子目录中。

  • log 目录包含有关每个 colcon 调用的各种日志信息。

注解

与 catkin 相比，没有 devel 目录。

创建一个工作空间

首先，创建一个目录（ros2_ws）来容纳我们的工作空间：

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws

此时，工作空间中只包含一个空目录 src：

.
└── src

1 directory, 0 files

添加一些源文件

将 examples 存储库克隆到工作区的 src 目录中：

git clone https://github.com/ros2/examples src/examples -b humble

现在工作区应该有 ROS 2 示例的源代码：

.
└── src
    └── examples
        ├── CONTRIBUTING.md
        ├── LICENSE
        ├── rclcpp
        ├── rclpy
        └── README.md

4 directories, 3 files

源目录

很重要的是，我们已经为现有的 ROS 2 安装环境提供了所需的构建依赖项，以便为示例软件包提供支持。这可以通过对二进制安装或源码安装提供的设置脚本进行实现，即使用另一个 colcon 工作区提供的设置脚本（参见 Installation）。我们称这个环境为 源目录。

我们的工作空间``ros2_ws``将作为现有ROS 2安装的**覆盖层**。一般而言，建议在计划迭代少量软件包时使用覆盖层，而不是将所有软件包放入同一个工作空间中。

构建工作空间

注意

要在Windows上构建软件包，您需要处于Visual Studio环境中，请参阅 构建ROS 2代码 获取更多详细信息。

在工作空间的根目录下运行``colcon build``命令。由于``ament_cmake``等构建类型不支持``devel``空间的概念，而且需要安装软件包，因此colcon支持选项``--symlink-install``。这允许通过更改``source``空间中的文件（例如Python文件或其他非编译资源）来更改已安装文件，以便实现更快的迭代。

colcon build --symlink-install

在构建完成后，我们应该能够看到 build、install 和 log 目录：

.
├── build
├── install
├── log
└── src

4 directories, 0 files

运行测试

为了对刚刚构建的软件包运行测试，请执行以下操作：

colcon test

加载环境变量

当colcon成功构建完成后，输出将位于``install``目录中。在您可以使用任何已安装的可执行文件或库之前，您需要将它们添加到您的路径和库路径中。colcon会在``install``目录中生成bash/bat文件来帮助设置环境。这些文件将会将所有所需的元素添加到您的路径和库路径中，并提供由软件包导出的任何bash或shell命令。

source install/setup.bash

试用演示

在环境配置完成后，我们可以运行由colcon构建的可执行文件。让我们从示例中运行一个订阅者节点：

ros2 run examples_rclcpp_minimal_subscriber subscriber_member_function

在另一个终端中，让我们运行一个发布者节点（不要忘记配置脚本）：

ros2 run examples_rclcpp_minimal_publisher publisher_member_function

你应该能够看到发布者和订阅者的消息，并且消息编号会递增。

创建你自己的包

colcon使用在`REP 149 <https://www.ros.org/reps/rep-0149.html>`__中定义的``package.xml``规范（也支持`format 2 <https://www.ros.org/reps/rep-0140.html>`__）。

colcon支持多种构建类型。推荐的构建类型是``ament_cmake``和``ament_python``。还支持纯``cmake``包。

``ament_python``构建的一个示例是`ament_index_python包 <https://github.com/ament/ament_index/tree/humble/ament_index_python>`__，其中setup.py是构建的主要入口点。

诸如`demo_nodes_cpp <https://github.com/ros2/demos/tree/humble/demo_nodes_cpp>`__的包使用``ament_cmake``构建类型，并使用CMake作为构建工具。

为了方便起见，您可以使用``ros2 pkg create``工具基于模板创建一个新的包。

注解

对于``catkin``用户来说，这相当于``catkin_create_package``。

设置 colcon_cd

命令 colcon_cd 允许您快速将当前工作目录更改为包的目录。例如，colcon_cd some_ros_package 可快速将您导航到目录 ~/ros2_ws/src/some_ros_package。

echo "source /usr/share/colcon_cd/function/colcon_cd.sh" >> ~/.bashrc
echo "export _colcon_cd_root=/opt/ros/humble/" >> ~/.bashrc

根据您安装 colcon_cd 的方式和工作空间的位置，上述说明可能有所不同，请参考 文档 以获取更多详细信息。要在Linux和macOS上撤消此操作，请找到系统的shell启动脚本并删除附加的source和export命令。

设置 colcon 的选项自动补全

如果已安装 colcon-argcomplete 包，则命令 colcon 支持命令补全，适用于 bash 和类似 bash 的 shell。

echo "source /usr/share/colcon_argcomplete/hook/colcon-argcomplete.bash" >> ~/.bashrc

根据您安装 colcon 的方式和工作空间的位置，上述说明可能会有所不同，请参考 文档 获取更多详细信息。要在 Linux 和 macOS 上撤消此操作，请找到您系统的 shell 启动脚本并删除附加的源命令。

提示

  • 如果您不想构建特定的软件包，请在目录中放置一个名为“COLCON_IGNORE”的空文件，它将不会被索引。

  • 如果您想避免在CMake软件包中配置和构建测试，您可以传递参数：--cmake-args -DBUILD_TESTING=0。

  • 如果您想从软件包中运行单个特定测试：

    colcon test --packages-select YOUR_PKG_NAME --ctest-args -R YOUR_TEST_IN_PKG