Skip to main content

2.4 Workspace Hygiene

As you start creating your own ROS 2 nodes, you'll need a way to organize, build, and manage them. A ROS 2 workspace is a directory that contains your ROS 2 packages. Proper workspace management, or "workspace hygiene," is essential for avoiding conflicts and ensuring that your code is portable and easy to share [1].

A ROS 2 workspace has a specific structure:

  • src/: This is where you put the source code for your ROS 2 packages. Each package is a directory within src/.
  • build/: This directory is created by colcon during the build process. It contains intermediate build files. You can safely delete this directory and rebuild.
  • install/: This directory is also created by colcon. It contains the final, installed versions of your packages, including executables, libraries, and Python modules. This is the directory that you will "source" to use your packages.
  • log/: This directory contains log files from the build process.

The Colcon Build System​

colcon (collective construction) is the recommended build tool for ROS 2. It is a command-line tool that automates the process of building and installing your ROS 2 packages [2]. colcon is language-agnostic and can build packages written in C++, Python, or a mix of both.

A typical workflow with colcon looks like this:

  1. Create a workspace directory:

    mkdir -p ~/ros2_ws/src
    cd ~/ros2_ws

  2. Add packages to the src directory: You can either create your own packages here or clone existing packages from a source like GitHub.

  3. Build the workspace:

    colcon build

    colcon will automatically find all the packages in the src directory, build them in the correct order based on their dependencies, and install the results into the install directory.

  4. Source the overlay: After a successful build, you need to "source" the setup.bash file in the install directory. This adds your newly built packages to your shell's environment, allowing you to run your nodes.

Sourcing Overlays: The Key to a Functional Workspace​

The command source install/setup.bash is a crucial and often misunderstood step. ROS 2 uses a system of overlays. You can have multiple ROS 2 installations and workspaces on your system, and you can "layer" them on top of each other. When you source a setup file, you are telling your shell to add the packages from that workspace to its environment, "overlaying" them on top of any previously sourced workspaces [3].

This means that if you open a new terminal, the packages in your workspace will not be available until you source the setup.bash file again. This is a common source of "command not found" errors for beginners.

To avoid having to source the file in every new terminal, you can add the source command to your shell's startup script (e.g., ~/.bashrc for Bash or ~/.zshrc for Zsh):

~/.bashrc
echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc

This ensures that your workspace is automatically sourced every time you open a new terminal.

Verifying Your Environment​

You can check which ROS 2 packages are available in your current environment by using the ROS_PACKAGE_PATH environment variable:

echo $ROS_PACKAGE_PATH

This will show you a colon-separated list of paths where ROS 2 will look for packages. When you source your workspace's setup.bash file, you should see the install directory of your workspace added to this path. This is how you can confirm that your workspace is correctly sourced and ready to use. Proper workspace hygiene is the foundation for building complex, multi-package robotics applications.

References​

[1] "Creating a workspace," ROS 2 Documentation. [Online]. Available: https://docs.ros.org/en/humble/Tutorials/Beginner-Workspace/Creating-A-Workspace.html. [2] "colcon," colcon documentation. [Online]. Available: https://colcon.readthedocs.io/. [3] "Sourcing an overlay," ROS 2 Documentation. [Online]. Available: https://docs.ros.org/en/humble/Tutorials/Beginner-Workspace/Creating-A-Workspace.html#source-the-overlay.

Ask