Using colcon to build packages：使用colcon来构建软件包

创始人

2025-05-30 09:21:34

文章目录

Colcon简介
安装Colcon
基本概念
创建一个工作空间
添加一些源文件
Source底层
构建工作空间
运行测试
Source环境
尝试演示
创建自己的软件包（package）
设置colcon_cd和tab补全
提示

参考官方文档：Using colcon to build packages

这是一个关于如何用colcon创建和构建ROS 2工作区（workspace）的简要教程。它是一个实用的教程，而不是为了取代核心文档。

Colcon简介

colcon是ROS构建工具catkin_make、catkin_make_isolated、catkin_tools和ament_tools的迭代。关于colcon设计的更多信息，请参见A universal build tool。

源代码可以在GitHub组织colcon中找到。

安装Colcon

sudo apt install python3-colcon-common-extensions

基本概念

一个ROS工作区是一个具有特定结构的目录。通常有一个src子目录。在这个子目录中，ROS软件包的源代码将被放在那里。通常情况下，该目录开始时是空的。

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

build目录将是存储中间文件的地方。每一个包都将创建一个子文件夹。
install目录是每个软件包将被安装到的地方。默认情况下，每个软件包将被安装到一个单独的子目录中。
log目录包含关于每个colcon调用的各种日志信息。

与catkin相比，没有devel目录。

创建一个工作空间

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

现在工作空间只包含一个空文件夹 src：

.
└── src1 directory, 0 files

添加一些源文件

将示例代码下载到src目录中：

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

现在工作空间应该结构如下：

.
└── src└── examples├── CONTRIBUTING.md├── LICENSE├── rclcpp├── rclpy└── README.md4 directories, 3 files

Source底层

为现有的ROS 2安装设置好环境可以为工作空间提供示例软件包构建所需的依赖项，这一点很重要。这是通过source由二进制安装或源文件安装提供的安装脚本来实现的。我们称这种环境为底层。我们的工作区 ros2_ws 将叠加在现有 ROS 2 安装之上。通常，建议在计划迭代少量包时使用叠加，而不是将所有包放入同一个工作区。

构建工作空间

在工作区的根目录中，运行 colcon build。由于 ament_cmake 等构建类型不支持开发空间的概念并且需要安装包，因此 colcon 支持选项 --symlink-install。这允许通过更改源空间中的文件（例如 Python 文件或其他未编译的资源）来更改已安装的文件，以加快迭代速度。

colcon build --symlink-install

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

.
├── build
├── install
├── log
└── src4 directories, 0 files

运行测试

要运行我们刚刚建立的软件包的测试，请运行以下命令：

colcon test

Source环境

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

. install/setup.bash

尝试演示

设置好环境后，我们可以运行由colcon构建的可执行文件。让我们运行例子中的一个订阅者节点：

ros2 run examples_rclcpp_minimal_subscriber subscriber_member_function

在另一个终端中，让我们运行一个发布者节点（不要忘了设置环境）：

ros2 run examples_rclcpp_minimal_publisher publisher_member_function

您应该看到来自发布者和订阅者的消息的数量在增加。

创建自己的软件包（package）

colcon使用REP 149中定义的package.xml规范（也支持format 2）。

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

ament_python构建的一个例子是ament_index_python package，其中setup.py是构建的主要入口。

像demo_nodes_cpp这样的包使用ament_cmake构建类型，并使用CMake作为构建工具。

为了方便起见，你可以使用 ros2 pkg create 这个工具来创建一个基于模板的新软件包。对于catkin用户，这相当于catkin_create_package。

设置colcon_cd和tab补全

命令 colcon_cd 允许你快速地将shell的当前工作目录改为软件包的目录。举例来说，colcon_cd some_ros_package将迅速把你带到~/ros2_install/src/some_ros_package目录。

echo "source /usr/share/colcon_cd/function/colcon_cd.sh" >> ~/.bashrc
echo "export _colcon_cd_root=/opt/ros/humble/" >> ~/.bashrc
echo "source /usr/share/colcon_argcomplete/hook/colcon-argcomplete.bash" >> ~/.bashrc

对于zsh，使用

echo "source /usr/share/colcon_cd/function/colcon_cd.sh" >> ~/.zshrc
echo "export _colcon_cd_root=/opt/ros/humble/" >> ~/.zshrc
echo "source /usr/share/colcon_argcomplete/hook/colcon-argcomplete.zsh" >> ~/.zshrc

提示

如果你不想构建某个特定的软件包，在这个软件包的目录中建立一个名为COLCON_IGNORE的空文件。
如果您想避免在 CMake 包中配置和构建测试，您可以传递：–cmake-args -DBUILD_TESTING=0。
如果你想从一个包中运行一个特定的测试，使用如下命令：

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