Using colcon to build packages
使用colcon编译包
This is a brief tutorial of how to create and build a ROS 2 workspace with colcon. It is a practical tutorial and not designed to replace the core documentation.
这是一个使用colcon如何创建和编译ROS 2工作区的简要教程。这是一个实用的教程，并非旨在取代核心文档。
ROS 2 releases before Bouncy used ament_tools described in the ament tutorial.
如果使用Bouncy或之前发行版本的ROS 2参考ament教程中ament_tools使用说明。
在Crystal和Dashing中均使用colcon进行编译。
Background背景
colcon is an iteration on the ROS build tools catkin_make, catkin_make_isolated, catkin_tools and ament_tools. For more information on the design of colcon see this document.
colcon是对ROS编译（编译）工具catkin_make，catkin_make_isolated，catkin_tools和ament_tools迭代。有关colcon设计的更多信息，请参考此文档。
The source code can be found in the colcon GitHub organization.
源代码可以在colcon GitHub组织中找到。
Prerequisites预备基础
Install colcon安装colcon
Linux
sudo apt install python3-colcon-common-extensions
python3-colcon-common-extensions is already the newest version (0.2.0-2).
OS X
python3 -m pip install colcon-common-extensions
Windows
pip install -U colcon-common-extensions
Install ROS 2安装ROS2
To build the samples, you will need to install ROS 2.
编译示例前，需要先安装ROS 2。
Follow the installation instructions.
请参考安装说明。
Attention 注意
If installing from Debian packages, this tutorial requires the desktop installation.
如果从Debian软件包安装，本教程需要桌面安装。
Basics基础知识
A ROS workspace is a directory with a particular structure. Commonly there is a src subdirectory. Inside that subdirectory is where the source code of ROS packages will be located. Typically the directory starts otherwise empty.
ROS工作空间是具有特定结构的目录。通常有一个src子目录。这个src子目录中是ROS包的源代码所在的位置。通常，通常都从这个目录开始，否则为空。
colcon does out of source builds. By default it will create the following directories as peers of the src directory:
colcon完成源代码编译。默认情况下，它将创建以下目录作为src目录的对等项：
The build directory will be where intermediate files are stored. For each package a subfolder will be created in which e.g. CMake is being invoked.
其中build目录将是存储中间文件的位置。对于每个包，将创建一个子文件夹，例如调用CMake。
The install directory is where each package will be installed to. By default each package will be installed into a separate subdirectory.
其中install目录是每个软件包将安装到的目录。默认情况下，每个包都将安装到单独的子目录中。
The log directory contains various logging information about each colcon invocation.
其中log目录包含有关每个colcon调用的各种日志记录信息。
Note 注意
Compared to catkin there is no devel directory. 与catkin相比，没有devel目录。
Create a workspace创建工作区
First, create a directory (ros2_example_ws) to contain our workspace:
首先，创建一个目录（ros2_example_ws）来包含自定义的工作区：
Linux/OS X
mkdir -p ~/ros2_example_ws/src
cd ~/ros2_example_ws
Windows
md \dev\ros2_example_ws\src
cd \dev\ros2_example_ws
At this point the workspace contains a single empty directory src:
此时工作空间包含一个空目录文件夹src：
.
└── src
1 directory, 0 files
Add some sources添加一些来源
Let’s clone the examples repository into the src directory of the workspace:
将示例库克隆到工作区的src目录中：
git clone https://github.com/ros2/examples src/examples
Attention 注意
It is recommended to checkout a branch that is compatible with the version of ROS that was installed (e.g. crystal、dashing).
建议检查与已安装的ROS版本兼容的分支（例如crystal、dashing）。
cd ~/ros2_example_ws/src/examples/
git checkout $ROS_DISTRO
cd ~/ros2_example_ws
Now the workspace should have the source code to the ROS 2 examples:
现在工作区应该有ROS 2示例的源代码：
.
└── src
└── examples
├── CONTRIBUTING.md
├── LICENSE
├── rclcpp
├── rclpy
└── README.md
4 directories, 3 files
Source an underlay导入底层
It is important that we have sourced the environment for an existing ROS 2 installation that will provide our workspace with the necessary build dependencies for the example packages. This is achieved by sourcing the setup script provided by a binary installation or a source installation, ie. another colcon workspace (see Installation). We call this environment an underlay.
重要的是，为现有的ROS 2安装提供环境，这将为编译工作区示例包提供必要的依赖性。通过获取二进制安装或源安装提供的安装脚本来实现的，即：另一个colcon工作区（请参考安装）。通常将此环境称为底层。
Our workspace, ros2_examples_ws, will be an overlay on top of the existing ROS 2 installation. In general, it is recommended to use an overlay when you plan to iterate on a small number of packages, rather than putting all of your packages into the same workspace.
工作空间ros2_examples_ws将叠加在现有的ROS 2安装之上。通常，建议在计划迭代少量软件包时使用覆盖，而不是将所有软件包放在同一个工作区中。
Build the workspace编译工作区
Attention 注意
To build packages on Windows you need to be in a Visual Studio environment, see Building the ROS 2 Code for more details.
要在Windows上编译软件包，需要在Visual Studio环境中，请参考编译ROS 2代码以获取更多详细信息。
In the root of the workspace, run colcon build. Since build types such as ament_cmake do not support the concept of the devel space and require the package to be installed, colcon supports the option --symlink-install. This allows the installed files to be changed by changing the files in the source space (e.g. Python files or other not compiled resourced) for faster iteration.
在工作区的根目录中，运行colcon build。由于编译类型ament_cmake（例如不支持devel的概念并且需要安装包），因此colcon支持选项--symlink-install。这允许通过更改source空间中的文件（例如Python文件或其他未编译的资源）来更改已安装的文件，以便更快地进行迭代。
colcon build --symlink-install
After the build is finished, we should see the build, install, and log directories:
编译完成后，可以看到build，install和log文件夹目录：
.
├── build
├── install
├── log
└── src
4 directories, 0 files
Run tests运行测试
To run tests for the packages we just built, run the following:
为刚刚编译的包运行测试，请运行以下命令：
colcon test
Source the environment导入环境
When colcon has completed building successfully, the output will be in the install directory. Before you can use any of the installed executables or libraries, you will need to add them to your path and library paths. colcon will have generated bash/bat files in the install directory to help setup the environment. These files will add all of the required elements to your path and library paths as well as provide any bash or shell commands exported by packages.
当colcon成功完成编译后，输出将在install目录中。在使用任何已安装的可执行文件或库之前，需要将它们添加到路径和库路径中。colcon将在install目录中生成bash / bat文件以帮助设置环境。这些文件将向路径和库路径添加所有必需元素，并提供由包导出的任何bash或shell命令。
Linux/OS X
. install/setup.bash
Or 或者
source install/setup.bash
Windows
call install\setup.bat
Try a demo试试示例
With the environment sourced we can run executables built by colcon. Let’s run a subscriber node from the examples:
在环境导入后，可以运行colcon编译的可执行文件。从示例中运行订阅器节点如下：
ros2 run examples_rclcpp_minimal_subscriber subscriber_member_function
In another terminal, let’s run a publisher node (don’t forget to source the setup script):
在另一个终端中，运行一个发布器节点（不要忘记导入安装脚本）：
ros2 run examples_rclcpp_minimal_publisher publisher_member_function
You should see messages from the publisher and subscriber with numbers incrementing.
应该看到来自发布器和订阅器的消息，并且数字会递增。
Create your own package创建自定义的包
colcon uses the package.xml specification defined in REP 149 (format 2 is also supported).
colcon使用REP 149中的规范定义package.xml（也支持格式2）。
colcon supports multiple build types. The recommended build types are ament_cmake and ament_python. Also supported are pure cmake packages.
colcon支持多种编译类型。推荐的编译类型是ament_cmake和ament_python。也支持纯cmake包。
An example of an ament_python build is the ament_index_python package , where the setup.py is the primary entry point for building.
ament_python编译的一个示例是ament_index_python包，其中setup.py是编译的主要入口点。
A package such as demo_nodes_cpp uses the ament_cmake build type, and uses CMake as the build tool.
诸如demo_nodes_cpp包使用ament_cmake编译类型，并使用CMake作为编译工具。
For convenience, you can use the tool ros2 pkg create to create a new package based on a template.
为方便起见，可以使用该工具ros2 pkg create基于模板创建新包。
Note 注意
For catkin users, this is the equivalent of catkin_create_package.
对于catkin用户来说，这相当于catkin_create_package。
注意区别，ROS1和ROS2，创建自定义包的区别。
Tips注意事项
If you do not want to build a specific package place an empty file named COLCON_IGNORE in the directory and it will not be indexed.
如果不想构建特定的包，请在目录中指定一个COLCON_IGNORE空文件，将不会编入索引。
If you want to avoid configuring and building tests in CMake packages you can pass: --cmake-args -DBUILD_TESTING=0.
如果想避免在CMake软件包中配置和构建测试，可以通过：--cmake-args -DBUILD_TESTING=0。
If you want to run a single particular test from a package:
如果要从包中运行单个特定测试：
colcon test --packages-select YOUR_PKG_NAME --ctest-args -R YOUR_TEST_IN_PKG
Using Ament 使用Ament
Warning 警告
As of ROS 2 Bouncy the recommended build tool is ``colcon`` described in the colcon tutorial. The current default branch as well as releases after Bouncy do not include ament_tools anymore.
从ROS 2 Bouncy开始，推荐的编译工具是 colcon教程中提及的``colcon``。当前的默认发行版以及Bouncy之后的版本不再将ament_tools包括在内。
由于介绍的教程针对Crystal和Dashing发行版本的ROS 2，所以设计ament的章节就省略了，如果需要了解更多细节，请查阅官方文档。
