使用“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。

Follow the installation instructions.

Attention

If installing from deb packages, this tutorial requires the desktop installation.

基础知识

ROS 工作区是一个具有特定结构的目录。 通常有一个“src”子目录。 该子目录中是 ROS 包的源代码所在位置。 通常，该目录开始时为空。

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

  • “build”目录将存储中间文件。

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

Note

Compared to catkin there is no devel directory.

创建工作区

首先，创建一个目录 (ros2_ws) 来包含我们的工作区：

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

此时工作区包含一个空目录“src”：

.
└── src

1 directory, 0 files

添加一些来源

Let’s clone the examples repository into the src directory of the workspace:

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 安装之上的 覆盖。 通常，当您计划迭代少量包时，建议使用覆盖，而不是将所有包放入同一个工作区。

构建工作区

要在 Windows 上构建软件包，您需要处于 Visual Studio 环境中，有关更多详细信息，请参阅：ref:“构建 ROS 2 代码 <windows-dev-build-ros2>”。

在工作区的根目录中，运行“colcon build”。 由于诸如“ament_cmake”之类的构建类型不支持“devel”空间的概念并且需要安装软件包，因此 colcon 支持选项“–symlink-install”。 这允许通过更改“源”空间中的文件（例如 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 中定义的 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”。

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

根据您安装“colcon_cd”的方式以及工作区的位置，上述说明可能会有所不同，请参阅“文档<https://colcon.readthedocs.io/en/released/user/installation.html#quick-directory-changes>”了解更多详细信息。 要在 Linux 和 macOS 中撤消此操作，请找到系统的 shell 启动脚本并删除附加的源和导出命令。

设置 colcon 制表符补全

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