Build a Workspace Using Colcon

Intro

Using colcon to build packages

colcon is an iteration on the ROS build tools catkin_make, catkin_make_isolated, catkin_tools and ament_tools

Install colcon

• Install colcon

sudo apt install python3-colcon-common-extensions

Add some sources

• Clone the ros_tutorials repo, which contains turtlesim package, into the src folder

git clone https://github.com/ros/ros_tutorials.git -b humble

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

4 directories, 3 files

Resolve dependencies

• From the root of your workspace, resolve any missing package dependencies (which are declared in the package.xml file

# cd if you're still in the ``src`` directory with the ``ros_tutorials`` clone
cd ..
rosdep install -i --from-path src --rosdistro humble -y

Note: if you get the your rosdep installation has not been initialized yet error, run:

sudo rosdep init
rosdep update

Build the workspace

• Build the workspace by running colcon build in the root of the workspace

colcon build

Other Colcon build arguments

• --packages-up-to builds the package you want, plus all its dependencies, but not the whole workspace (saves time)
• --symlink-install saves you from having to rebuild every time you tweak python scripts
• --event-handlers console_direct+ shows console output while building (can otherwise be found in the log directory)
• --executor sequential processes the packages one by one instead of using parallelism

• colcon will have generated bash/bat files in the install directory to help set up 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

Other 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.
• If you want to avoid configuring and building tests in CMake packages, you can pass: --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  

.
├── build
├── install
├── log
└── src

4 directories, 0 files

• The directory structure of your ROS2 workspace (training_ws) should look like this:

Directory Structure

training_ws/
├── build/                   
├── install/                 
│   └── setup.bash     
├── log/                     
└── src/                     
    └── ros_tutorials/       
        ├── turtlesim/       
        └── other_packages/  

• build/: Contains the build files generated by colcon build.
• install/: Contains the installed packages and setup files necessary for running the workspace.
• log/: Contains logs of the build process for debugging and analysis.
• src/: The source directory where all ROS2 packages are placed. In this case, it contains the cloned ros_tutorials repository, which includes the turtlesim package.

Source the environment

• Open a new terminal and source the setup file for your main ROS 2 installation.

source /opt/ros/humble/setup.bash

• Next, source the setup file from the training_ws overlay to enable access to the packages within the training_ws workspace.

# cd into ros2_ws
source install/local_setup.bash

Try some demos

• run turtle_sim package

ros2 run turtlesim turtlesim_node

• run a subscriber node from the examples

ros2 run examples_rclcpp_minimal_subscriber subscriber_member_function

• In another terminal, run a publisher node

source install/setup.bash
ros2 run examples_rclcpp_minimal_publisher publisher_member_function