【ROS2】初级：客户端-使用colcon构建包

最新推荐文章于 2025-10-01 08:36:05 发布

原创最新推荐文章于 2025-10-01 08:36:05 发布 · 1.4k 阅读

23 ·

CC 4.0 BY-SA版权

使用 `colcon` 构建包

背景
先决条件
- 安装 colcon
- 安装 ROS 2
基础
- 创建工作空间 Create a workspace
- 添加一些来源 Add some sources
- 来源一个垫层 Source an underlay
- 建立工作空间 Build the workspace
- 运行测试
- 环境来源 Source the environment
- 尝试演示
创建您自己的包 Create your own package
设置 colcon_cd
设置 colcon 标签补全 Setup colcon tab completion
小贴士 Tips

目标：使用 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。https://docs.ros.org/en/jazzy/Installation.html

遵循安装说明。

注意

如果从 Debian 包安装，本教程需要桌面安装。https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debians.html#linux-install-debians-install-ros-2-packages

基础知识

ROS 工作空间是具有特定结构的目录。通常有一个 src 子目录。源代码包将位于该子目录内。通常，目录开始时是空的。

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

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

便条

与 catkin 相比，没有 devel 目录。

创建工作空间

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

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

在这一点上，工作空间包含一个单一的空目录 src ：

添加一些源

让我们克隆示例https://github.com/ros2/examples仓库到工作空间的 src 目录：

cxy@ubuntu2404-cxy:~/ros2_ws$ git clone https://github.com/ros2/examples src/examples -b jazzy
正克隆到 'src/examples'...
remote: Enumerating objects: 8519, done.
remote: Counting objects: 100% (2746/2746), done.
remote: Compressing objects: 100% (467/467), done.
remote: Total 8519 (delta 2417), reused 2462 (delta 2257), pack-reused 5773
接收对象中: 100% (8519/8519), 1.33 MiB | 1.18 MiB/s, 完成.
处理 delta 中: 100% (6141/6141), 完成.

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

源一个垫层

重要的是我们已经为现有的 ROS 2 安装源了环境，这将为我们的工作空间提供示例包所需的构建依赖项。这是通过源安装或二进制安装提供的设置脚本来实现的，即另一个 colcon 工作空间（见安装https://docs.ros.org/en/jazzy/Installation.html）。我们称这个环境为底层。

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

构建工作空间

注意

在 Windows 上构建包，您需要处于 Visual Studio 环境中，请参阅构建 ROS 2 代码以获取更多详细信息。https://docs.ros.org/en/jazzy/Installation/Alternatives/Windows-Development-Setup.html#windows-dev-build-ros2

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

colcon build --symlink-install

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

cxy@ubuntu2404-cxy:~/ros2_ws$ colcon build --symlink-install
Starting >>> examples_rclcpp_async_client
Starting >>> examples_rclcpp_cbg_executor                    
Starting >>> examples_rclcpp_minimal_action_client
Starting >>> examples_rclcpp_minimal_action_server
Starting >>> examples_rclcpp_minimal_client
Starting >>> examples_rclcpp_minimal_composition                             
Starting >>> examples_rclcpp_minimal_publisher
Starting >>> examples_rclcpp_minimal_service
Starting >>> examples_rclcpp_minimal_subscriber
Starting >>> examples_rclcpp_minimal_timer
Starting >>> examples_rclcpp_multithreaded_executor                           
Starting >>> examples_rclcpp_wait_set
[Processing: examples_rclcpp_async_client, examples_rclcpp_cbg_executor, examples_rclcpp_minimal_action_client, examples_rclcpp_minimal_action_server, examples_rclcpp_minimal_client, examples_rclcpp_minimal_composition, examples_rclcpp_minimal_publisher, examples_rclcpp_minimal_service, examples_rclcpp_minimal_subscriber, examples_rclcpp_minimal_timer, examples_rclcpp_multithreaded_executor, examples_rclcpp_wait_set]
[Processing: examples_rclcpp_async_client, examples_rclcpp_cbg_executor, examples_rclcpp_minimal_action_client, examples_rclcpp_minimal_action_server, examples_rclcpp_minimal_client, examples_rclcpp_minimal_composition, examples_rclcpp_minimal_publisher, examples_rclcpp_minimal_service, examples_rclcpp_minimal_subscriber, examples_rclcpp_minimal_timer, examples_rclcpp_multithreaded_executor, examples_rclcpp_wait_set]
Finished <<< examples_rclcpp_minimal_client [1min 2s]
Starting >>> examples_rclpy_executors
Finished <<< examples_rclcpp_async_client [1min 3s]
Finished <<< examples_rclcpp_minimal_timer [1min 2s]
Finished <<< examples_rclcpp_minimal_service [1min 2s]
Starting >>> examples_rclpy_guard_conditions
Starting >>> examples_rclpy_minimal_action_client
Starting >>> examples_rclpy_minimal_action_server
Finished <<< examples_rclcpp_minimal_publisher [1min 10s]
Starting >>> examples_rclpy_minimal_client
Finished <<< examples_rclcpp_minimal_action_server [1min 12s]
Starting >>> examples_rclpy_minimal_publisher
Finished <<< examples_rclcpp_minimal_action_client [1min 13s]
Starting >>> examples_rclpy_minimal_service
Finished <<< examples_rclcpp_multithreaded_executor [1min 15s]
Starting >>> examples_rclpy_minimal_subscriber
Finished <<< examples_rclcpp_cbg_executor [1min 16s]
Starting >>> examples_rclpy_pointcloud_publisher
--- stderr: examples_rclpy_guard_conditions  
/usr/lib/python3/dist-packages/setuptools/command/develop.py:40: EasyInstallDeprecationWarning: easy_install command is deprecated.
!!


        ********************************************************************************
        Please avoid running ``setup.py`` and ``easy_install``.
        Instead, use pypa/build, pypa/installer or other
        standards-based tools.


        See https://github.com/pypa/setuptools/issues/917 for details.
        ********************************************************************************


!!
  easy_install.initialize_options(self)
/usr/lib/python3/dist-packages/setuptools/command/easy_install.py:363: UserWarning: Unbuilt egg for pytest-repeat [unknown version] (/usr/lib/python3/dist-packages)
  self.local_index = Environment(self.shadow_path + sys.path)
---
Finished <<< examples_rclpy_guard_conditions [16.9s]
Starting >>> launch_testing_examples
--- stderr: examples_rclpy_minimal_action_server
/usr/lib/python3/dist-packages/setuptools/command/develop.py:40: EasyInstallDeprecationWarning: easy_install command is deprecated.
!!


        ********************************************************************************
        Please avoid running ``setup.py`` and ``easy_install``.
        Instead, use pypa/build, pypa/installer or other
        standards-based tools.


        See https://github.com/pypa/setuptools/issues/917 for details.
        ********************************************************************************


!!
  easy_install.initialize_options(self)
/usr/lib/python3/dist-packages/setuptools/command/easy_install.py:363: UserWarning: Unbuilt egg for pytest-repeat [unknown version] (/usr/lib/python3/dist-packages)
  self.local_index = Environment(self.shadow_path + sys.path)
---
Finished <<< examples_rclpy_minimal_action_server [16.7s]
--- stderr: examples_rclpy_minimal_publisher
/usr/lib/python3/dist-packages/setuptools/command/develop.py:40: EasyInstallDeprecationWarning: easy_install command is deprecated.
!!


        ********************************************************************************
        Please avoid running ``setup.py`` and ``easy_install``.
        Instead, use pypa/build, pypa/installer or other
        standards-based tools.


        See https://github.com/pypa/setuptools/issues/917 for details.
        ********************************************************************************


!!
  easy_install.initialize_options(self)
/usr/lib/python3/dist-packages/setuptools/command/easy_install.py:363: UserWarning: Unbuilt egg for pytest-repeat [unknown version] (/usr/lib/python3/dist-packages)
  self.local_index = Environment(self.shadow_path + sys.path)
---
Finished <<< examples_rclpy_minimal_publisher [7.75s]
--- stderr: examples_rclpy_executors
/usr/lib/python3/dist-packages/setuptools/command/develop.py:40: EasyInstallDeprecationWarning: easy_install command is deprecated.
!!


        ********************************************************************************
        Please avoid running ``setup.py`` and ``easy_install``.
        Instead, use pypa/build, pypa/installer or other
        standards-based tools.


        See https://github.com/pypa/setuptools/issues/917 for details.
        ********************************************************************************


!!
  easy_install.initialize_options(self)
/usr/lib/python3/dist-packages/setuptools/command/easy_install.py:363: UserWarning: Unbuilt egg for pytest-repeat [unknown version] (/usr/lib/python3/dist-packages)
  self.local_index = Environment(self.shadow_path + sys.path)
---
Finished <<< examples_rclpy_executors [17.2s]
--- stderr: examples_rclpy_minimal_service
/usr/lib/python3/dist-packages/setuptools/command/develop.py:40: EasyInstallDeprecationWarning: easy_install command is deprecated.
!!


        ********************************************************************************
        Please avoid running ``setup.py`` and ``easy_install``.
        Instead, use pypa/build, pypa/installer or other
        standards-based tools.


        See https://github.com/pypa/setuptools/issues/917 for details.
        ********************************************************************************


!!
  easy_install.initialize_options(self)
/usr/lib/python3/dist-packages/setuptools/command/easy_install.py:363: UserWarning: Unbuilt egg for pytest-repeat [unknown version] (/usr/lib/python3/dist-packages)
  self.local_index = Environment(self.shadow_path + sys.path)
---
Finished <<< examples_rclpy_minimal_service [6.21s]
--- stderr: examples_rclpy_minimal_client
/usr/lib/python3/dist-packages/setuptools/command/develop.py:40: EasyInstallDeprecationWarning: easy_install command is deprecated.
!!


        ********************************************************************************
        Please avoid running ``setup.py`` and ``easy_install``.
        Instead, use pypa/build, pypa/installer or other
        standards-based tools.


        See https://github.com/pypa/setuptools/issues/917 for details.
        ********************************************************************************


!!
  easy_install.initialize_options(self)
/usr/lib/python3/dist-packages/setuptools/command/easy_install.py:363: UserWarning: Unbuilt egg for pytest-repeat [unknown version] (/usr/lib/python3/dist-packages)
  self.local_index = Environment(self.shadow_path + sys.path)
---
Finished <<< examples_rclpy_minimal_client [9.41s]
--- stderr: examples_rclpy_minimal_action_client
/usr/lib/python3/dist-packages/setuptools/command/develop.py:40: EasyInstallDeprecationWarning: easy_install command is deprecated.
!!


        ********************************************************************************
        Please avoid running ``setup.py`` and ``easy_install``.
        Instead, use pypa/build, pypa/installer or other
        standards-based tools.


        See https://github.com/pypa/setuptools/issues/917 for details.
        ********************************************************************************


!!
  easy_install.initialize_options(self)
/usr/lib/python3/dist-packages/setuptools/command/easy_install.py:363: UserWarning: Unbuilt egg for pytest-repeat [unknown version] (/usr/lib/python3/dist-packages)
  self.local_index = Environment(self.shadow_path + sys.path)
---
Finished <<< examples_rclpy_minimal_action_client [17.4s]
--- stderr: examples_rclpy_minimal_subscriber
/usr/lib/python3/dist-packages/setuptools/command/develop.py:40: EasyInstallDeprecationWarning: easy_install command is deprecated.
!!


        ********************************************************************************
        Please avoid running ``setup.py`` and ``easy_install``.
        Instead, use pypa/build, pypa/installer or other
        standards-based tools.


        See https://github.com/pypa/setuptools/issues/917 for details.
        ********************************************************************************


!!
  easy_install.initialize_options(self)
/usr/lib/python3/dist-packages/setuptools/command/easy_install.py:363: UserWarning: Unbuilt egg for pytest-repeat [unknown version] (/usr/lib/python3/dist-packages)
  self.local_index = Environment(self.shadow_path + sys.path)
---
Finished <<< examples_rclpy_minimal_subscriber [4.80s]
--- stderr: examples_rclpy_pointcloud_publisher
/usr/lib/python3/dist-packages/setuptools/command/develop.py:40: EasyInstallDeprecationWarning: easy_install command is deprecated.
!!


        ********************************************************************************
        Please avoid running ``setup.py`` and ``easy_install``.
        Instead, use pypa/build, pypa/installer or other
        standards-based tools.


        See https://github.com/pypa/setuptools/issues/917 for details.
        ********************************************************************************


!!
  easy_install.initialize_options(self)
/usr/lib/python3/dist-packages/setuptools/command/easy_install.py:363: UserWarning: Unbuilt egg for pytest-repeat [unknown version] (/usr/lib/python3/dist-packages)
  self.local_index = Environment(self.shadow_path + sys.path)
---
Finished <<< examples_rclpy_pointcloud_publisher [4.05s]
Finished <<< examples_rclcpp_wait_set [1min 21s]
--- stderr: launch_testing_examples          
/usr/lib/python3/dist-packages/setuptools/command/develop.py:40: EasyInstallDeprecationWarning: easy_install command is deprecated.
!!


        ********************************************************************************
        Please avoid running ``setup.py`` and ``easy_install``.
        Instead, use pypa/build, pypa/installer or other
        standards-based tools.


        See https://github.com/pypa/setuptools/issues/917 for details.
        ********************************************************************************


!!
  easy_install.initialize_options(self)
/usr/lib/python3/dist-packages/setuptools/command/easy_install.py:363: UserWarning: Unbuilt egg for pytest-repeat [unknown version] (/usr/lib/python3/dist-packages)
  self.local_index = Environment(self.shadow_path + sys.path)
---
Finished <<< launch_testing_examples [2.93s]
Finished <<< examples_rclcpp_minimal_subscriber [1min 24s]
Finished <<< examples_rclcpp_minimal_composition [1min 26s]                                


Summary: 22 packages finished [1min 37s]
  10 packages had stderr output: examples_rclpy_executors examples_rclpy_guard_conditions examples_rclpy_minimal_action_client examples_rclpy_minimal_action_server examples_rclpy_minimal_client examples_rclpy_minimal_publisher examples_rclpy_minimal_service examples_rclpy_minimal_subscriber examples_rclpy_pointcloud_publisher launch_testing_examples

运行测试

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

cxy@ubuntu2404-cxy:~/ros2_ws$ colcon test
Starting >>> examples_rclcpp_async_client
Starting >>> examples_rclcpp_cbg_executor
Starting >>> examples_rclcpp_minimal_action_client
Starting >>> examples_rclcpp_minimal_action_server
Starting >>> examples_rclcpp_minimal_client
Starting >>> examples_rclcpp_minimal_composition                            
Starting >>> examples_rclcpp_minimal_publisher
Starting >>> examples_rclcpp_minimal_service
Starting >>> examples_rclcpp_minimal_subscriber
Starting >>> examples_rclcpp_minimal_timer                                  
Starting >>> examples_rclcpp_multithreaded_executor
Starting >>> examples_rclcpp_wait_set
Finished <<< examples_rclcpp_minimal_action_client [6.66s]                   
Finished <<< examples_rclcpp_minimal_action_server [6.63s]
Starting >>> examples_rclpy_executors
Starting >>> examples_rclpy_guard_conditions                                 
Finished <<< examples_rclcpp_multithreaded_executor [6.56s]
Finished <<< examples_rclcpp_minimal_composition [6.67s]
Finished <<< examples_rclcpp_minimal_timer [6.59s]
Starting >>> examples_rclpy_minimal_action_client                           
Starting >>> examples_rclpy_minimal_action_server                            
Starting >>> examples_rclpy_minimal_client
Finished <<< examples_rclcpp_async_client [7.28s]
Finished <<< examples_rclcpp_minimal_service [7.12s]
Starting >>> examples_rclpy_minimal_publisher
Starting >>> examples_rclpy_minimal_service
Finished <<< examples_rclcpp_minimal_subscriber [7.56s]                      
Finished <<< examples_rclcpp_cbg_executor [7.71s]
Finished <<< examples_rclcpp_minimal_client [7.65s]
Starting >>> examples_rclpy_minimal_subscriber                                    
Starting >>> examples_rclpy_pointcloud_publisher
Starting >>> launch_testing_examples                                               
Finished <<< examples_rclcpp_wait_set [8.43s]
Finished <<< examples_rclcpp_minimal_publisher [10.0s]                               
Finished <<< examples_rclpy_guard_conditions [4.80s]                       
Finished <<< examples_rclpy_minimal_action_client [4.34s]
Finished <<< examples_rclpy_executors [4.83s]
Finished <<< examples_rclpy_minimal_action_server [4.32s]
Finished <<< examples_rclpy_minimal_publisher [4.27s]
Finished <<< examples_rclpy_minimal_client [4.30s]
Finished <<< examples_rclpy_minimal_service [4.42s]                             
Finished <<< examples_rclpy_minimal_subscriber [3.62s]                             
Finished <<< examples_rclpy_pointcloud_publisher [3.81s]                             
[Processing: launch_testing_examples]                     
--- stderr: launch_testing_examples                           


=============================== warnings summary ===============================
test/test_flake8.py: 12 warnings
  Warning: This process (pid=10200) is multi-threaded, use of fork() may lead to deadlocks in the child.


-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
---
Finished <<< launch_testing_examples [51.1s]


Summary: 22 packages finished [1min 0s]
  1 package had stderr output: launch_testing_examples

加载环境

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

cxy@ubuntu2404-cxy:~/ros2_ws$ 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 规范（也支持格式 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/jazzy/ament_index_python ，其中 setup.py 是构建的主要入口点。

一个像 demo_nodes_cpp https://github.com/ros2/demos/tree/jazzy/demo_nodes_cpp 这样的包使用 ament_cmake 构建类型，并使用 CMake 作为构建工具。

为了方便，您可以使用工具 ros2 pkg create 根据模板创建一个新包。

便条

对于 catkin 用户，这相当于 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/jazzy/" >> ~/.bashrc


echo "source /usr/share/colcon_cd/function/colcon_cd.sh" >> ~/.bashrc
echo "export _colcon_cd_root=/home/cxy/ros2_ws/" >> ~/.bashrc

根据您安装 colcon_cd 的方式以及您的工作区所在的位置，上述指令可能会有所不同，请参阅文档了解更多详情。要在 Linux 和 macOS 中撤销此操作，请找到系统的 shell 启动脚本并移除附加的 source 和 export 命令。

设置 `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