ROS 2 Lyrical Luth · Lesson 04 of 86

Creating a workspace with colcon

colcon build options, selecting packages, symlink install and running tests.

Estimated time · 45–75 min

Learning goals

What you will understand

Explain creating a workspace with colcon in your own words
Use it in a small robotics example
Verify the result instead of assuming it worked

Understand the idea first

The mental model

colcon is the build tool for ROS 2 workspaces. It finds every package under src, works out the dependency order, and calls each package's own build system (ament_cmake or ament_python). Run it from the workspace root only.

Useful options: --packages-select builds one package, --packages-up-to builds it and its dependencies, --symlink-install links Python and config files instead of copying (edits apply without rebuilding), and --cmake-args passes options such as -DCMAKE_BUILD_TYPE=Release. Run colcon test then colcon test-result --verbose for tests.

Guided lesson

Work through these steps

1.
Source the ROS 2 Lyrical environment in a fresh terminal.
2.
Read the creating a workspace with colcon example and identify what each line does.
3.
Build only the affected package, source the workspace overlay, and run the example.
4.
Inspect the result from a second terminal with the ros2 CLI or RViz2 and compare it with the expected result.

Worked example

Read it before you run it

cd ~/robot_ws
# colcon must run from the workspace root.
colcon build --symlink-install
# Build everything; edited Python files and configs take effect without a rebuild.
colcon build --packages-select robot_nodes
# Rebuild only one package, which is much faster.
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release
# Pass CMake options to every C++ package.
colcon test --packages-select robot_nodes
# Run that package's tests.
colcon test-result --verbose
# Show which tests passed or failed.
rosdep install --from-paths src --ignore-src -y
# Install every system dependency the packages declare.

What the example is doing

1.The ros2 commands query the running graph; they do not prove that a node's internal behavior is correct.
2.Build from the workspace root, then source install/setup.bash so the shell can discover the new package.
3.Use a second sourced terminal to inspect nodes and interfaces while the example runs.

Watch it run · Build and run

See what this code does

The terminal types this lesson's practice solution and runs it. The scene shows the kind of robot behaviour that code drives. It plays by itself and loops.

Practice code

Now type it yourself

Copy the starter into your ROS 2 package, replace every TODO, then build with colcon build and run it from a sourced terminal.

cd ~/robot_ws
source /opt/ros/lyrical/setup.bash
# TODO: build only the package robot_nodes, using symlink install
source install/setup.bash

Expected output

Summary: 1 package finished

Stuck? Show the full solution (try it yourself first)

cd ~/robot_ws
source /opt/ros/lyrical/setup.bash
colcon build --symlink-install --packages-select robot_nodes
source install/setup.bash

Expected result

How you know it worked

ROS_DISTRO is lyrical in every terminal used for the exercise.
The complete package from the exercise builds and the expected graph entity appears in a second terminal.

Practical exercise

Apply the lesson

Build a workspace with two packages using --symlink-install, change a launch file and confirm it takes effect without rebuilding, then build only one package with --packages-select and compare the time.

Before you continue

ROS_DISTRO reports lyrical in every terminal you used
The example builds and runs without errors
You checked the result with a ros2 command, RViz2 or a test, not just by reading the code

If something goes wrong

ros2 cannot find a package or executable.

Source /opt/ros/lyrical/setup.bash, build from the workspace root, then source install/setup.bash in that terminal.

Nodes run but cannot discover each other.

Confirm both terminals use Lyrical, the same ROS_DOMAIN_ID, and compatible network/discovery settings.