Configuring your shell environment for ROS 2

3.2.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 Pixi environment. Any commands that you enter are assumed to be entered from a Pixi shell. Please refer to the Setup ROS (for the RSP course) guide to start a Pixi shell first.

3.2.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 3.7.1.

3.2.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, which will configure environment variables in the active shell, such as PATH to find new ROS commands. 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.2.1.3. Sourcing your ROS Workspace#

If you would install ROS Humble directly on a Ubuntu computer using Ubuntu’s package manager, all the managed ROS packages will be installed in /opt/ros/humble/. To activate the default ROS Humble workspace, you would 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

For RSP students, since you are using ROS from a provided Pixi environment, the directory /opt/ros/ does not exist on your computer.

In fact, your Pixi environment automatically sources the default ROS Humble environment already for you when you run pixi shell -m ~/ro47003_pixi_ws. Therefore, once you activated the Pixi environment, it will immediately act as a ROS environment and have the default ROS commands available, without you needing to run this source command.

Be aware though that this step is still happening “under the hood” when using Pixi. In real-world robotics development, it is common to have ROS directly installed on the computer without Pixi, and forgetting to source the default ROS environment in every terminal is a very common novice ROS user mistake!

Note that the exact command would depend 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. So on ROS Jazzy, the command would have become source /opt/ros/jazzy/setup.bash.

Note

Just to illustrate if you would not be using Pixi, here are examples of the general pattern to activate the ROS workspace on each major OS:

  # 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

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

  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.

If you’re not sure if you already sourced the setup.bash in a shell, that’s okay, you can also just try to run the command again. The command is idempotent: running it twice in a row will behave the same as running it once. You can run it a million additional times in a row and it won’t make any difference.

3.2.1.4. Check ROS environment variables#

As stated above, 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, check that your environment is properly set up by inspecting if and how ROS related environment variables have been set. For example, using the following command:

$ env | grep -i ROS

Exercise 3.1

Check in your activated ROS Humble environment that variables like ROS_VERSION, ROS_PYTHON_VERSION and ROS_DISTRO 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

RSP students: remember that activating a Pixi shell with the course’s provided Pixi environment should automatically activate the ROS in that terminal too!

Now open a new terminal, without activating ROS (or Pixi) there. Confirm that these ROS environment variables are not set by default in a regular shell. Only when you activate ROS will the sourced setup files configure these variables.

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 ever use ROS installed on Ubuntu via the package manager, you may be tempted to automatically source the setup file every time you open a new shell. For example, 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 may have additional workspaces available, which should perhaps 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.2.1.5. 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.