Create Your First
Workspace & Package

What You'll Learn Today

This tutorial has been made for beginners who are just starting with ROS 2 and are entirely unaware of its features and functionalities. Let's dive in and explore what ROS 2 is and how it works.

ROS 2 Distributions

Open this link: https://docs.ros.org/en/foxy/Releases.html. After you scroll down you will find a list of distributions as shown:

Among these, the distributions highlighted green are currently supported by the manufacturers. Some are supported for 5 years while others for shorter durations. It is always recommended to use a distribution with a longer support window so you can receive updates for longer.

If you scroll down you'll find a section titled "Future Distributions":

A distribution named Jazzy Jalisco is visible here. Released in 2024 with an EOL of 2029 — the most recent long-term support distribution. This tutorial uses Jazzy as it's the most current and will remain relevant longer.

Installing ROS 2 Jazzy

Open your browser and search "ROS2 Jazzy Documentation". The following result will appear:

Click the first link. The following documentation page will open:

Click on "Installation". The following page will open:

Under the Installation heading, click on "Ubuntu Linux → deb packages":

Scroll down to find a set of commands:

Open your terminal and copy-paste these commands one by one from start to finish. You'll also find a command to install development tools:

Finally, you'll see two installation options — Desktop Install or Base Install:

Verifying Your Installation

After running all commands, set up the environment and verify:

source /opt/ros/jazzy/setup.bash

ros2

If you see the following output, ROS 2 is successfully installed:

usage: ros2 [-h] [--use-python-default-buffering] ...

ros2 is an extensible command-line tool for ROS 2.

Commands:
  action     Various action related sub-commands
  bag        Various rosbag related sub-commands
  component  Various component related sub-commands
  node       Various node related sub-commands
  pkg        Various package related sub-commands
  run        Run a package specific executable
  topic      Various topic related sub-commands
  ...
  Call `ros2 <command> -h` for more detailed usage.

If instead you see ros2: command not found — the installation did not complete successfully.

Installing Supporting Tools

We also need VS Code and gedit (text editor) for this tutorial. Install them:

sudo snap install code --classic

sudo apt install gedit

Verify gedit by typing gedit — a text editor window will open:

Close gedit and continue with the tutorial.

Understanding Basic Terminal Commands

Before we learn ROS 2, we need to understand some basic Linux terminal commands. Close the current terminal and open a fresh one.

Creating Folders — mkdir

Let's create a folder named my_first_folder:

mkdir my_first_folder

Open the Files app and you'll see the folder was created:

Navigating Directories — cd

To create a folder inside another folder, you first change your working directory using cd:

cd my_first_folder/

You'll see my_first_folder highlighted in the terminal prompt, confirming you're now inside it:

Now create a folder inside it:

mkdir folder_1

To go back one directory level (back to root), use:

cd ..

Now create a second folder at the root level:

To visualize the folder hierarchy we've created:

Listing Files — ls

To view files inside your current directory from the terminal, type:

ls

Navigating into my_first_folder and using ls shows its contents:

Creating a Workspace and Package in ROS 2

Close the current terminal and open a fresh one before continuing.

Setting Up the ROS 2 Environment

Before using ROS 2, you must source its environment every time you open a terminal:

source /opt/ros/jazzy/setup.bash

This is repetitive — let's automate it. Open the .bashrc file with gedit:

gedit .bashrc

Scroll to the bottom and add the source command:

Save the file, close gedit and the terminal. Open a new terminal and type ros2 — it should work without manually sourcing. The ROS 2 environment is now automatically set up every time.

Creating the Workspace

First install the colcon build tool:

sudo apt update

sudo apt install python3-colcon-common-extensions

A ROS 2 workspace is a directory where packages and nodes are organized. Create one named ws_1:

mkdir ws_1

cd ws_1

mkdir src

Verify with ls to see the src folder was created:

Now build the workspace:

colcon build

Run ls again. You'll see 3 new folders were auto-generated — build, install, and log:

To use custom nodes from this workspace, you need to source it. Add this to .bashrc just like we did for ROS 2 itself:

cd ..

gedit .bashrc

Add at the end:

source ~/ws_1/install/setup.bash

Save and close. Now you won't have to source your workspace manually every session.

Creating a Package

Packages live inside the src folder of your workspace. Navigate there:

cd ws_1/src/

Running ls shows nothing — the src folder is still empty:

There are two types of packages: Python and C++. This tutorial creates a Python package named my_first_package:

ros2 pkg create my_first_package --build-type ament_python --dependencies rclpy

Run ls and you'll see the package folder:

The package isn't fully built yet. Move back to the workspace root and build:

cd ..

colcon build

Finally, verify the package was created successfully by navigating into it and running ls:

The presence of auto-generated files and folders confirms the package was built successfully. You're ready for Part 2.