使用“colcon”构建包

目标： 使用colcon构建 ROS 2 工作区。

教程级别： 初学者

时间： 20 分钟

这是关于如何使用 colcon 创建和构建 ROS 2 工作区的简短教程。 这是一个实用教程，并非旨在取代核心文档。

背景

colcon``是 ROS 构建工具 ``catkin_make 、 catkin_make_isolated、 catkin_tools 和 ament_tools 的迭代。

有关 colcon 设计的更多信息，请参阅 this document.

源代码可以在 colcon GitHub organization.

先决条件

安装 colcon

sudo apt install python3-colcon-common-extensions

安装 ROS 2

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

请遵循 安装说明。

基础知识

ROS 工作区是一个具有特定结构的目录。 通常有一个 src 子目录。 ROS 包的源代码将位于该子目录中。 通常，目录以空开头。

colcon 执行源外构建。 默认情况下，它将创建以下目录作为 src 目录的对等目录：

  • build 目录将是存储中间文件的地方。

对于每个包，将创建一个子文件夹，例如正在调用 CMake。 * install 目录是每个包的安装位置。 默认情况下，每个包将安装到单独的子目录中。 * log 目录包含有关每次 colcon 调用的各种日志信息。

Note

与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 rolling

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

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

4 directories, 3 files

获取底层

重要的是，我们已经获取了现有 ROS 2 安装的环境，它将为我们的工作区提供示例包所需的构建依赖项。 这是通过获取二进制安装或源安装提供的安装脚本来实现的，即另一个 colcon 工作区（请参阅：doc：Installation）。 我们将此环境称为 底层。

我们的工作区 ros2_ws 将是现有 ROS 2 安装之上的 覆盖。 通常，当您计划迭代少量包时，建议使用覆盖，而不是将所有包放入同一个工作区。

构建工作区

Attention

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

在工作区的根目录中，运行“colcon build”。 由于“ament_cmake”等构建类型不支持“devel”空间的概念，并且需要安装包，因此 colcon 支持选项“–symlink-install”。

这允许通过更改“源”空间中的文件（例如 Python 文件或其他非编译资源）来更改已安装的文件，以实现更快的迭代。

colcon build --symlink-install

Windows 不允许长路径，因此“merge-install”会将所有路径合并到“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 中定义的 package.xml 规范（format 2 也受支持）。

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

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

诸如 demo_nodes_cpp 之类的包使用 ament_cmake 构建类型，并使用 CMake 作为构建工具。

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

Note

For catkin users, this is the equivalent of catkin_create_package.

设置“colcon_cd”

命令“colcon_cd”允许您快速将 shell 的当前工作目录更改为包的目录。 例如，“colcon_cd some_ros_package”会快速将您带到目录“~/ros2_ws/src/some_ros_package”。 .. tabs:

.. group-tab:: Linux

   .. code-block:: console

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

.. group-tab:: macOS

   .. code-block:: console

     echo "source /usr/local/share/colcon_cd/function/colcon_cd.sh" >> ~/.bashrc
     echo "export _colcon_cd_root=~/ros2_install" >> ~/.bashrc

.. group-tab:: Windows

   Not yet available

根据您安装 colcon_cd 的方式以及您的工作区的位置，上述说明可能会有所不同，请参阅 文档 了解更多详细信息。 要在 Linux 和 macOS 中撤消此操作，请找到系统的 shell 启动脚本并删除附加的源和导出命令。

设置 colcon tab 补全

colcon 命令支持 bash 和类似 bash 的 shell 的命令补全。 必须安装 colcon-argcomplete 包，并且可能需要进行一些设置 <https://colcon.readthedocs.io/en/released/user/installation.html#enable-completion>`__ 才能使其正常工作。

提示

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

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

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

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