ROS Workspace

The concept of a workspace is independent of the ROS version. In other words, it doesn’t matter whether you’re using ROS 1 or ROS 2, both rely on the workspace concept.

The key word in this definition is directory. A ROS workspace is, at its core, simply a folder in your file system that contains ROS packages.

But you may be wondering: what is a ROS package? That is a fair question. For now, think of a package as a self-contained unit that groups code, configuration files, and other resources related to a particular piece of functionality. We will explore the concept of packages properly later in the note about ROS Packages.

Underlay

I know what you may be thinking: we are defining this unknown thing called an “underlay” while mentioning another undefined term, “overlay”.

Let us take it one step at a time. In a typical ROS 2 setup, the main ROS installation acts as the underlay. For ROS 2 Jazzy Jalisco installed through Ubuntu packages, that installation is usually located at:

ls /opt/ros/jazzy/

This installation contains the ROS packages and tools that our own workspace may depend on.

Overlay

The overlay is normally the workspace in which you develop your own packages. It can use everything provided by the underlay while adding packages of its own. For example, the ROS 2 Jazzy installation under /opt/ros/jazzy/ may act as the underlay, while a workspace (e.g. ~/my_ws) under your home directory acts as the overlay.

Although the terms underlay and overlay are not frequently used in everyday ROS conversations, people usually mean the overlay workspace when they refer simply to a workspace, since that is where active development normally takes place.

Creating an overlay workspace is almost as simple as creating a directory with the Bash command mkdir. By convention, a ROS 2 workspace contains a directory named src, which is where the source code for its packages lives.

Follow along: Open a terminal and run the following commands to create your workspace and move into it:

mkdir -p ~/ros2_ws/src

cd ~/ros2_ws

The -p option tells mkdir to create any missing parent directories. It also prevents an error if the directory already exists.

At this point, the workspace looks like this:

ros2_ws/
└── src/

There are no packages inside it yet, but the basic workspace structure is already in place.

The build tool normally used in ROS 2 is called colcon↗, short for collective construction. colcon is an evolution of previous ROS build tools, including catkin_make, catkin_make_isolated, catkin_tools, and ament_tools.

In simple terms, colcon builds, tests, and installs the packages inside a workspace. Internally, it uses the appropriate build system depending on the type of package. C++ packages commonly use ament_cmake↗, which is based on CMake↗, while Python packages commonly use ament_python, which is based on setuptools↗. We will explore colcon, build systems, and package types in more detail later in the note about ROS Packages. For now, let us build our workspace.

If you are following along, open a new terminal and run:

cd ~/ros2_ws

colcon build --symlink-install

The --symlink-install option tells colcon to create symbolic links to certain files in their original locations instead of copying them into the installation directory. This is useful during development because some changes can be reflected without rebuilding or copying the files again.

After running the build command, the workspace will contain the following directories:

ros2_ws/
├── build/    # intermediate files generated while building each package.
├── install/  # installed results of the build, including executables, libraries, resources, and environment setup files.
├── log/      # logs generated by `colcon`, which are particularly useful when investigating build failures.
└── src/      # contains the source code for the packages in the workspace.

For more information about the motivation behind colcon, see A universal build tool↗.

After building the workspace, notice that colcon created an install/ directory. Among the files placed there are setup scripts that allow the workspace to be used from a terminal.

Building and sourcing are therefore two separate steps:

1. Building creates and installs the results of the packages in the workspace.
2. Sourcing makes those installed results available to the current terminal.

Our workspace is currently empty, so the previous build may have completed without needing anything from ROS 2. Once we add packages, however, the relationship between the underlay and the overlay becomes important.

Remember that ~/ros2_ws is our overlay and the ROS 2 installation under /opt/ros/jazzy/ is its underlay. Packages in the overlay may depend on packages and build systems provided by that underlay. For this reason, we normally source the underlay before building the overlay:

source /opt/ros/jazzy/setup.bash

cd ~/ros2_ws

colcon build --symlink-install

After the build finishes, we source the overlay to make its packages available in the current terminal:

source install/local_setup.bash

Sourcing workspaces is cumulative, and the order matters: first the underlay, then the overlay.

source /opt/ros/jazzy/setup.bash

source ~/ros2_ws/install/local_setup.bash

Alternatively, the overlay provides a setup.bash file that also includes the underlay chain associated with it:

source ~/ros2_ws/install/setup.bash

For now, you can think of sourcing as the step that makes a ROS installation or workspace available to the current terminal. Each new terminal starts with its own environment, so the required setup files must be sourced again.

The exact effect of sourcing, the differences between the generated setup files, and how ROS discovers installed packages will make more sense once we introduce packages. We will revisit all of this in more detail in ROS Packages.

See Source the overlay↗ in the official documentation.

Manually sourcing the ROS 2 underlay every time you open a new terminal can become repetitive. As a developer convenience, you can ask Bash to run the sourcing command automatically whenever a new terminal starts.

Adding this command to ~/.bashrc is not required by ROS. It is simply a Bash configuration that automatically sources the ROS environment and saves you from typing the command each time you open a terminal.

echo 'source /opt/ros/jazzy/setup.bash' >> ~/.bashrc

The ~/.bashrc file contains commands that Bash executes when opening a new interactive terminal. After adding the line, every new Bash terminal will automatically source the ROS 2 Jazzy underlay.

To apply the change to the terminal that is already open, run:

source ~/.bashrc

Automatic sourcing is convenient when you normally work with one ROS distribution. However, if you use multiple ROS distributions or switch between different workspace chains, it can make the active environment less obvious. In those cases, sourcing the required setup files manually may be clearer and less error-prone.