Creating a workspace — ROS 2 Documentation: Foxy documentation (2024)

1 Source ROS 2 environment

Your main ROS 2 installation will be your underlay for this tutorial.(Keep in mind that an underlay does not necessarily have to be the main ROS 2 installation.)

Depending on how you installed ROS 2 (from source or binaries), and which platform you’re on, your exact source command will vary:

source /opt/ros/foxy/setup.bash

Consult the installation guide you followed if these commands don’t work for you.

2 Create a new directory

Best practice is to create a new directory for every new workspace.The name doesn’t matter, but it is helpful to have it indicate the purpose of the workspace.Let’s choose the directory name ros2_ws, for “development workspace”:

mkdir -p ~/ros2_ws/srccd ~/ros2_ws/src

Another best practice is to put any packages in your workspace into the src directory.The above code creates a src directory inside ros2_ws and then navigates into it.

3 Clone a sample repo

Ensure you’re still in the ros2_ws/src directory before you clone.

In the rest of the beginner developer tutorials, you will create your own packages, but for now you will practice putting a workspace together using existing packages.

If you went through the Beginner: CLI Tools tutorials, you’ll be familiar with turtlesim, one of the packages in ros_tutorials.

A repo can have multiple branches.You need to check out the one that targets your installed ROS 2 distro.When you clone this repo, add the -b argument followed by that branch.

In the ros2_ws/src directory, run the following command:

git clone https://github.com/ros/ros_tutorials.git -b foxy-devel

Now ros_tutorials is cloned in your workspace. The ros_tutorials repository contains the turtlesim package, which we’ll use in the rest of this tutorial. The other packages in this repository are not built because they contain a COLCON_IGNORE file.

So far you have populated your workspace with a sample package, but it isn’t a fully-functional workspace yet.You need to resolve the dependencies first and then build the workspace.

4 Resolve dependencies

Before building the workspace, you need to resolve the package dependencies.You may have all the dependencies already, but best practice is to check for dependencies every time you clone.You wouldn’t want a build to fail after a long wait only to realize that you have missing dependencies.

From the root of your workspace (ros2_ws), run the following command:

# cd if you're still in the ``src`` directory with the ``ros_tutorials`` clonecd ..rosdep install -i --from-path src --rosdistro foxy -y

If you installed ROS 2 on Linux from source or the “fat” archive, you will need to use the rosdep command from their installation instructions.Here are the from-source rosdep section and the “fat” archive rosdep section.

If you already have all your dependencies, the console will return:

#All required rosdeps installed successfully

Packages declare their dependencies in the package.xml file (you will learn more about packages in the next tutorial).This command walks through those declarations and installs the ones that are missing.You can learn more about rosdep in another tutorial (coming soon).

5 Build the workspace with colcon

From the root of your workspace (ros2_ws), you can now build your packages using the command:

colcon build

The console will return the following message:

Starting >>> turtlesimFinished <<< turtlesim [5.49s]Summary: 1 package finished [5.58s]

Once the build is finished, enter ls in the workspace root (~/ros2_ws) and you will see that colcon has created new directories:

build install log src

The install directory is where your workspace’s setup files are, which you can use to source your overlay.

6 Source the overlay

Before sourcing the overlay, it is very important that you open a new terminal, separate from the one where you built the workspace.Sourcing an overlay in the same terminal where you built, or likewise building where an overlay is sourced, may create complex issues.

In the new terminal, source your main ROS 2 environment as the “underlay”, so you can build the overlay “on top of” it:

source /opt/ros/foxy/setup.bash

Go into the root of your workspace:

cd ~/ros2_ws

In the root, source your overlay:

source install/local_setup.bash

Now you can run the turtlesim package from the overlay:

ros2 run turtlesim turtlesim_node

But how can you tell that this is the overlay turtlesim running, and not your main installation’s turtlesim?

Let’s modify turtlesim in the overlay so you can see the effects:

• You can modify and rebuild packages in the overlay separately from the underlay.

• The overlay takes precedence over the underlay.

7 Modify the overlay

You can modify turtlesim in your overlay by editing the title bar on the turtlesim window.To do this, locate the turtle_frame.cpp file in ~/ros2_ws/src/ros_tutorials/turtlesim/src.Open turtle_frame.cpp with your preferred text editor.

On line 52 you will see the function setWindowTitle("TurtleSim");.Change the value "TurtleSim" to "MyTurtleSim", and save the file.

Return to the first terminal where you ran colcon build earlier and run it again.

Return to the second terminal (where the overlay is sourced) and run turtlesim again:

ros2 run turtlesim turtlesim_node

You will see the title bar on the turtlesim window now says “MyTurtleSim”.

Even though your main ROS 2 environment was sourced in this terminal earlier, the overlay of your ros2_ws environment takes precedence over the contents of the underlay.

To see that your underlay is still intact, open a brand new terminal and source only your ROS 2 installation.Run turtlesim again:

ros2 run turtlesim turtlesim_node

You can see that modifications in the overlay did not actually affect anything in the underlay.