Configuring your shell environment for ROS 2

3.1. Configuring your shell environment for ROS 2#

This tutorial will show you how to prepare your ROS 2 environment. In this stage, we only assume:

You are familiar with working with a Linux shell, like bash.
You know what environment variables in the Linux shell are.
You have ROS 2 installed.

Note

For the Robot Software Practicals course, we assume you are working with ROS using the provided singularity image. Any commands that you enter are assumed to be entered from a singularity shell. Please refer to the Setup ROS (for the RSP course) guide to start a singularity shell first.

3.1.1. What is a ROS Workspace?#

ROS 2 relies on the notion of combining workspaces using the shell environment. “Workspace” is a ROS term for the location on your system where you’re developing with ROS 2. The workspace of your core ROS 2 installation is called the underlay. Subsequent local workspaces are called overlays, as they extend that core. When developing with ROS 2, you will typically have several workspaces active concurrently.

In more advanced use cases, workspaces can even be combined to make developing against different versions of ROS 2, or against different sets of packages, easier. It also allows the installation of several ROS 2 distributions (or “distros”, e.g. Humble and Eloquent) on the same computer and switching between them.

Creating overlays is a more advanced topic that you will learn about later in Section 8.1.

3.1.2. How to use a ROS Workspace#

If you just open a terminal on your operating system, you will not be able to just run ROS 2 commands, even if you installed ROS 2 correctly. Instead, your shell will first need to be instructed to where ROS 2 is installed, and which workspace you are using.

This is accomplished by sourcing setup files every time you open a new shell. These setup files are generated by the ROS tools when creating a new ROS workspace. Without sourcing the setup files, you won’t be able to access ROS 2 commands, or find or use ROS 2 packages. In other words, you won’t be able to use ROS 2 if you forget to source the setup files.

3.1.3. Sourcing your ROS Workspace#

Concretely, you will need to run this command on every new shell you open to have access to the ROS 2 commands from within that shell.

$ source /opt/ros/humble/setup.bash

Note

The exact command depends on the specifics of how ROS 2 is installed on your computer, including the name of your ROS distribution (e.g. humble for ROS Humble Hawksbill, jazzy for ROS Jazzy Jalisco), the underlying operating system you are using (Linux, Windows, MacOS), and where ROS was installed on your filesystem.

Here is an example of the general pattern for each OS, assume ROS 2 Humble:

Linux

  # Replace ".bash" with your shell if you're not using bash
  # Possible values are: setup.bash, setup.sh, setup.zsh
  source /opt/ros/humble/setup.bash

macOS

  . ~/ros2_install/ros2-osx/setup.bash

Windows

  call C:\dev\ros2\local_setup.bat

If you’re having problems, ensure the file path leads to your ROS 2 installation. For the remainder of this tutorial, we will assume you are using Linux.

3.1.3.1. Check environment variables#

Sourcing ROS 2 setup files will set several environment variables necessary for operating ROS 2. Only if these environment variables have been set can you run ROS 2 commands, as needed for the sections later in this manual.

If you ever have problems finding or using your ROS 2 packages, make sure that your environment is properly set up using the following command:

$ printenv | grep -i ROS

Check that variables like ROS_DISTRO and ROS_VERSION are set as follows (don’t worry if you see several other ROS variables in your terminal):

ROS_VERSION=2
ROS_PYTHON_VERSION=3
ROS_DISTRO=humble

If the environment variables are not set correctly, return to the ROS 2 package installation section of the installation guide you followed. If you need more specific help (because environment setup files can come from different places), you can get help and answers from the community.

Warning

If you don’t want to have to source the setup file every time you open a new shell, then you could add the following lines to the end of your shell startup script, ~/.bashrc, which gets automatically sourced anytime you open a new terminal:

echo Sourcing ROS Humble setup.bash ...
source /opt/ros/humble/setup.bash

However, once you do this, it is easy to forget that you added it and never internalize that this is needed. When you in the near future work on developing your own ROS code, you will have additional workspaces available, which should be enabled instead. You will be confused why your ROS workspace is not the one you expected.

For didactic purposes, it is therefore better to first build muscle memory by manually sourcing the setup files before you attempt to automate this.

3.1.4. Summary#

The ROS 2 development environment needs to be correctly configured before use. This can be done in two ways: either sourcing the setup files in every new shell you open, or adding the source command to your startup script.

If you ever face any problems locating or using packages with ROS 2, the first thing you should do is check your environment variables and ensure they are set to the version and distro you intended.