CodeTheRobot
Course outline

ROS 2 Lyrical Luth · Lesson 05 of 86

Creating your first package (ament_cmake and ament_python)

ros2 pkg create, package.xml, CMakeLists.txt, setup.py and the two build types.

Estimated time · 60–90 min

Learning goals

What you will understand

  • Explain creating your first package (ament_cmake and ament_python) 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

A package is the unit of ROS 2 software. C++ packages use the build type ament_cmake and are described by package.xml plus CMakeLists.txt; Python packages use ament_python and are described by package.xml plus setup.py. ros2 pkg create generates the skeleton for either.

package.xml states the name, version, license and dependencies (<depend>rclcpp</depend>). The dependency must also be found in CMakeLists.txt with find_package for C++. Package names use lowercase letters, digits and underscores.

Guided lesson

Work through these steps

  1. 1.

    Source the ROS 2 Lyrical environment in a fresh terminal.

  2. 2.

    Read the creating your first package (ament_cmake and ament_python) example and identify what each line does.

  3. 3.

    Build only the affected package, source the workspace overlay, and run the example.

  4. 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/src
# Packages are created inside src.
ros2 pkg create --build-type ament_cmake --license Apache-2.0 robot_nodes --dependencies rclcpp std_msgs
# Generate a C++ package that depends on rclcpp and std_msgs.
ros2 pkg create --build-type ament_python --license Apache-2.0 robot_tools --dependencies rclpy
# Generate a Python package that depends on rclpy.
ls robot_nodes
# You will see CMakeLists.txt, package.xml, include/ and src/.
cd ~/robot_ws && colcon build --symlink-install
# Build both new packages.
source install/setup.bash
# Make them discoverable.
ros2 pkg list | grep robot_
# Confirm both packages are registered.

What the example is doing

  1. 1.The ros2 commands query the running graph; they do not prove that a node's internal behavior is correct.
  2. 2.Build from the workspace root, then source install/setup.bash so the shell can discover the new package.
  3. 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.

sourcecompilerprogramBUILD AND RUN

Demo for Creating your first package (ament_cmake and ament_python). Expected result: robot_nodes robot_tools

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/src
# TODO: create the C++ package robot_nodes (ament_cmake) depending on rclcpp and std_msgs
# TODO: create the Python package robot_tools (ament_python) depending on rclpy
cd ~/robot_ws && colcon build && source install/setup.bash
ros2 pkg list | grep robot_

Expected output

robot_nodes
robot_tools
Stuck? Show the full solution (try it yourself first)
cd ~/robot_ws/src
ros2 pkg create --build-type ament_cmake --license Apache-2.0 robot_nodes --dependencies rclcpp std_msgs
ros2 pkg create --build-type ament_python --license Apache-2.0 robot_tools --dependencies rclpy
cd ~/robot_ws && colcon build && source install/setup.bash
ros2 pkg list | grep robot_

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

Create one ament_cmake and one ament_python package, add a print or log line to each, build, and run both with ros2 run. Open both package.xml files and list which line names each dependency.

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.