RobotnixAcademy

Unit 14 · lab

Lab: Build a ROS 2 Workspace and Prove the Overlay Is Real

This lab moves from reading about workspaces to creating one.

You will create robot_ws, create the robotnix_bringup package, build it with colcon, prove the package is visible only after the overlay is sourced, then reproduce and repair a fresh-shell package lookup failure.

Your final artifact is a Workspace Build and Overlay Record.

Choose your lane

Local Jazzy lane

Use this lane if you have Ubuntu 24.04 with ROS 2 Jazzy and colcon available.

You will execute the commands yourself and preserve your actual output.

Supplied-evidence lane

If you do not have a local Jazzy environment, write the package files and command sequence, then use the supplied build and lookup transcripts in this lab.

Label them supplied workspace evidence. Do not claim the commands ran on your computer.

Guided example: package built, package not visible

Evidence:

Summary: 1 package finished

A fresh shell then runs:

source /opt/ros/jazzy/setup.bash
ros2 pkg prefix robotnix_bringup

and receives:

Package not found

A weak repair is:

rebuild again

The build already succeeded.

The better next action is:

source ~/robot_ws/install/setup.bash

then:

ros2 pkg prefix robotnix_bringup

The lesson is that build state and shell overlay visibility are different.

Part 1: Create the workspace

Local lane:

mkdir -p ~/robot_ws/src
cd ~/robot_ws
pwd

Your path should end in:

robot_ws

Record the initial tree:

robot_ws/
└── src/

Supplied lane: use that same tree as the starting evidence.

Part 2: Source Jazzy

Run or record:

source /opt/ros/jazzy/setup.bash
echo $ROS_DISTRO

Expected distribution for this course:

jazzy

If your local environment reports another distribution, stop and label the mismatch instead of pretending you are following the Jazzy lane.

Part 3: Create the package in the correct directory

Run:

cd ~/robot_ws/src
ros2 pkg create \
  --build-type ament_cmake \
  robotnix_bringup

Verify:

~/robot_ws/src/robotnix_bringup/package.xml
~/robot_ws/src/robotnix_bringup/CMakeLists.txt

Record the package's location and build type.

If the package was created outside src, repair the location before building.

Part 4: Replace generated metadata with intentional metadata

Edit package.xml so it contains:

  • package name robotnix_bringup;
  • real description of the bringup role;
  • a selected license for the project;
  • ament_cmake build-tool dependency;
  • runtime dependencies you intend to use in Week 15, including demo_nodes_cpp, launch, and launch_ros.

Do not leave TODO description/license markers in your final record.

Then reduce CMakeLists.txt to the package's current job:

cmake_minimum_required(VERSION 3.8)
project(robotnix_bringup)

find_package(ament_cmake REQUIRED)

ament_package()

Week 15 will add the launch install rule.

Part 5: Build the selected package

From the workspace root:

cd ~/robot_ws
colcon build --packages-select robotnix_bringup

Local lane: preserve your actual summary.

Supplied lane: use:

Starting >>> robotnix_bringup
Finished <<< robotnix_bringup [0.42s]

Summary: 1 package finished [0.53s]

The exact times are supplied example values. The load-bearing evidence is that the selected package finished successfully.

Part 6: Inspect the generated workspace layers

Record the post-build tree:

robot_ws/
├── build/
├── install/
├── log/
└── src/

For each directory, write one sentence explaining its role.

Then identify which of the four is the canonical source-authoring layer.

Part 7: Demonstrate the unsourced-overlay failure

Open a fresh local terminal, or use this supplied fresh-shell record.

Source only Jazzy:

source /opt/ros/jazzy/setup.bash

Then:

ros2 pkg prefix robotnix_bringup

Supplied result:

Package not found

Before doing anything else, record:

build evidence exists
local overlay not sourced in this shell

Do not delete build or rebuild yet.

Part 8: Source the overlay and verify the prefix

Run:

source ~/robot_ws/install/setup.bash
ros2 pkg prefix robotnix_bringup

Supplied result:

/home/student/robot_ws/install/robotnix_bringup

Your local path may differ.

Record the resolved prefix.

This proves the current shell can resolve the installed package from the workspace overlay.

It does not prove the package contains a launch file yet.

Part 9: Create a second failure case

Pretend the package was accidentally created here:

~/robotnix_bringup

instead of:

~/robot_ws/src/robotnix_bringup

Write the expected consequence for:

cd ~/robot_ws
colcon build --packages-select robotnix_bringup

Then write the repair.

Do not solve this by adding random colcon flags. The package belongs in the workspace source tree.

Part 10: Build the Workspace Build and Overlay Record

Your artifact must contain:

Workspace tree

Before and after the build.

Package identity

  • package name;
  • build type;
  • responsibility;
  • source path.

Package files

Include your package.xml dependency summary and the relevant CMakeLists.txt lines.

Build evidence

Record the exact colcon command and either your local result or supplied result label.

Directory roles

Explain src, build, install, and log.

Overlay failure

Preserve the fresh-shell package-not-found result.

Overlay repair

Preserve the source command and successful package-prefix lookup.

Wrong-location case

Explain why a package outside src is not part of the workspace build.

Java boundary

Write one sentence explaining why building robotnix_bringup does not compile or create a Java ROS 2 node.

Success criteria

Your record is complete when another student can answer:

  • Where does authored package source live?
  • What did colcon generate?
  • Which package was selected for the build?
  • Which shell commands source the underlay and overlay?
  • Why could the package exist on disk but still be invisible to ROS package lookup?
  • Which command proved the overlay package prefix?
  • What would make a newly edited installed resource stale?
  • What exact responsibility belongs to robotnix_bringup?

A strong workspace record makes the build reproducible without relying on your terminal history or memory.