ROS workspace and package structure - Step-by-Step Execution

Concept Flow - ROS workspace and package structure

Create Workspace Directory

↓

Create src Folder Inside Workspace

↓

Create Package Inside src

↓

Add Package Files (CMakeLists.txt, package.xml)

↓

Build Workspace with colcon or catkin

↓

Source Workspace Setup File

↓

Use Package in ROS Environment

This flow shows how you set up a ROS workspace, add packages, build them, and prepare your environment to use them.

Execution Sample

ROS

mkdir -p ~/ros_ws/src
cd ~/ros_ws/src
ros2 pkg create my_package
cd ~/ros_ws
colcon build
source install/setup.bash

This sequence creates a workspace, adds a package, builds the workspace, and sets up the environment.

Execution Table

Step	Action	Directory/Files Created	Command Output	Effect
1	Create workspace directory	~/ros_ws	No output	Workspace folder created
2	Create src folder inside workspace	~/ros_ws/src	No output	Source folder created
3	Create package inside src	~/ros_ws/src/my_package	Package created with CMakeLists.txt and package.xml	Package folder and files created
4	Build workspace	~/ros_ws	Build successful	Packages compiled and install folder created
5	Source setup file	~/ros_ws	No output	Environment variables set for ROS usage
6	Use package in ROS environment	N/A	ROS recognizes my_package	Package ready to run nodes or tools
7	Exit	N/A	N/A	Setup complete, ready for development

💡 All steps completed successfully, workspace and package ready for use

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	After Step 5	Final
Workspace Directory	None	~/ros_ws	~/ros_ws	~/ros_ws	~/ros_ws	~/ros_ws	~/ros_ws
src Folder	None	None	~/ros_ws/src	~/ros_ws/src	~/ros_ws/src	~/ros_ws/src	~/ros_ws/src
Package Folder	None	None	None	~/ros_ws/src/my_package	~/ros_ws/src/my_package	~/ros_ws/src/my_package	~/ros_ws/src/my_package
Build Status	Not built	Not built	Not built	Not built	Built	Built	Built
Environment Sourced	No	No	No	No	No	Yes	Yes

Key Moments - 3 Insights

Why do we need the 'src' folder inside the workspace?

The 'src' folder is where ROS expects all packages to be placed. Step 2 shows creating it before adding packages in Step 3.

What happens if we don't source the setup file after building?

Without sourcing (Step 5), ROS won't know about your new packages, so commands won't find them. The environment variables are set only after sourcing.

Why do we run 'colcon build' in the workspace root and not inside 'src'?

The build tool expects to be run from the workspace root to find the 'src' folder and build all packages inside it, as shown in Step 4.

Visual Quiz - 3 Questions

Look at the execution table, after which step is the package folder created?

A Step 2

B Step 4

C Step 3

D Step 5

💡 Hint

Check the 'Directory/Files Created' column for when 'my_package' appears

At which step does the environment become aware of the new package?

A Step 3

B Step 5

C Step 4

D Step 6

💡 Hint

Look at the 'Environment Sourced' variable in variable_tracker after each step

If you skip creating the 'src' folder, what will happen when you run 'colcon build'?

A Build will fail because no packages found

B Build will succeed with no packages

C Build will create 'src' automatically

D Build will ignore missing 'src' and build anyway

💡 Hint

Refer to Step 2 and Step 4 in execution_table about folder structure and build

Concept Snapshot

ROS workspace setup:
1. Create workspace folder (e.g., ~/ros_ws)
2. Inside it, create 'src' folder
3. Create packages inside 'src' with package.xml and CMakeLists.txt
4. Build workspace with 'colcon build'
5. Source 'install/setup.bash' to use packages
Key: 'src' holds packages; build from workspace root; source env after build

Full Transcript

This visual execution shows how to set up a ROS workspace and package structure step-by-step. First, you create a workspace directory, then inside it, a 'src' folder where packages live. Next, you create a package inside 'src' which includes important files like package.xml and CMakeLists.txt. After that, you build the workspace using 'colcon build' from the workspace root. Finally, you source the setup file to update your environment so ROS recognizes your new package. The execution table tracks each step's action, files created, and effects. The variable tracker shows how workspace directories, package folders, build status, and environment sourcing change over time. Key moments clarify why 'src' is needed, why sourcing is important, and why building happens from the workspace root. The quiz tests understanding of when folders are created, when environment updates happen, and consequences of missing 'src'. This guide helps beginners visualize the workspace and package setup process in ROS clearly and confidently.

Practice

1. What is the main purpose of a ROS workspace?

easy

A. To organize multiple ROS packages and build them together

B. To store robot hardware components physically

C. To run ROS nodes directly without packages

D. To replace the operating system for robots

Solution

1. Step 1: Understand what a ROS workspace is

   A ROS workspace is a directory where you keep your ROS packages organized and ready to build.

2. Step 2: Identify the workspace role

   The workspace allows you to build all packages together and manage dependencies easily.

3. Final Answer:

   To organize multiple ROS packages and build them together -> Option A

4. Quick Check:

   Workspace = Organize and build packages [OK]

Hint: Workspace groups packages for building and management [OK]

Common Mistakes:

• Confusing workspace with physical robot parts
• Thinking workspace runs nodes directly
• Assuming workspace replaces OS

2. Which file must every ROS package contain to define its metadata?

easy

A. package.xml

B. CMakeLists.txt

C. README.md

D. setup.py

Solution

1. Step 1: Identify metadata files in ROS packages

   Every ROS package must have a package.xml file that describes the package name, version, dependencies, and other metadata.

2. Step 2: Differentiate from build files

   CMakeLists.txt is for build instructions, not metadata. README.md is documentation, and setup.py is for Python packages but not mandatory in ROS.

3. Final Answer:

   package.xml -> Option A

4. Quick Check:

   Metadata file = package.xml [OK]

Hint: Metadata always in package.xml file [OK]

Common Mistakes:

• Confusing CMakeLists.txt with metadata
• Thinking README.md defines package info
• Assuming setup.py is mandatory for all packages

3. Given a ROS workspace with packages pkg1 and pkg2, what happens after running colcon build and then source install/setup.bash?

medium

A. The packages are deleted from the workspace

B. Only pkg1 is built and pkg2 is ignored

C. The workspace is built and environment is set to use the packages

D. The ROS master node starts automatically

Solution

1. Step 1: Understand colcon build role

   This command builds all packages in the workspace, compiling code and preparing install files.

2. Step 2: Understand source install/setup.bash role

   This command sets environment variables so ROS can find and use the newly built packages.

3. Final Answer:

   The workspace is built and environment is set to use the packages -> Option C

4. Quick Check:

   Build + source = ready to use packages [OK]

Hint: Build then source to use packages in ROS [OK]

Common Mistakes:

• Thinking only one package builds
• Assuming packages get deleted after build
• Believing ROS master starts automatically

4. You created a new package inside your ROS workspace but forgot to run colcon build. What problem will you face?

medium

A. The package will run but with errors

B. The package will build automatically when you run any node

C. The package will be deleted from the workspace

D. ROS will not recognize the new package when you try to use it

Solution

1. Step 1: Understand build necessity

   ROS requires running colcon build to compile and register new packages in the workspace environment.

2. Step 2: Consequence of skipping build

   If you skip building, ROS environment does not know about the new package, so it cannot find or use it.

3. Final Answer:

   ROS will not recognize the new package when you try to use it -> Option D

4. Quick Check:

   Build missing = package not recognized [OK]

Hint: Always build after adding new packages [OK]

Common Mistakes:

• Assuming packages build automatically
• Thinking package deletion happens without build
• Believing package runs with errors without build

5. You want to add a new ROS package that depends on an existing package std_msgs. Which steps correctly update your workspace to include this dependency?

hard

A. Run rosdep install std_msgs without modifying any files

B. Add std_msgs to package.xml dependencies, update CMakeLists.txt, then run colcon build

C. Delete package.xml and create a new one with std_msgs listed

D. Only add std_msgs to README.md and run colcon build

Solution

1. Step 1: Add dependency in package.xml

   You must declare std_msgs as a dependency in package.xml so ROS knows your package needs it.

2. Step 2: Update CMakeLists.txt for build

   Modify CMakeLists.txt to find and link std_msgs during build.

3. Step 3: Build workspace

   Run colcon build to compile your package with the new dependency.

4. Final Answer:

   Add std_msgs to package.xml dependencies, update CMakeLists.txt, then run colcon build -> Option B

5. Quick Check:

   Declare dependency + update build + build workspace [OK]

Hint: Declare dependencies in package.xml and CMakeLists.txt before build [OK]

Common Mistakes:

• Only updating README.md without build changes
• Deleting package.xml unnecessarily
• Relying on rosdep without declaring dependencies