In this section you will learn to create a workspace and learn how to set up an overlay fordevelopment and testing.
A workspace is a directory containing ROS 2 packages.Before using ROS 2, it’s necessary to source your ROS 2 installation workspace in theterminal you plan to work in. This makes ROS 2’s packages available foryou to use in that terminal.
Note
A workspace is a directory with a particular structure. Commonlythere is a src
subdirectory. Inside that subdirectory is where thesource code of ROS packages will be located. Typically the directorystarts otherwise empty.
The ROS2 build tool colcon does out of source builds meaning that build targetsare placed in a different directory. By default it will create thefollowing directories as siblings of the src
directory:
The
build
directory will be where intermediate files are stored.For each package a subfolder will be created in which e.g. CMake isinvoked.The
install
directory is where each package will be installed to.By default each package will be installed into a separatesubdirectory.The
log
directory contains various logging information about eachcolcon
invocation.
8.1.1. Source your ROS 2 underlay environment#
It is important that we have sourced the environment for an existing ROS2 installation that will provide our workspace with the necessary builddependencies for the example packages.This is achieved by sourcing the setup scriptprovided by a binary installation or a source installation, ie. another ROS workspace.We call this environment an underlay.
$ source /opt/ros/humble/setup.bash
The workspace you will create will act as an overlay - a secondaryworkspace where you can add new packages without interfering with theunderlay, in this case the existing ROS 2 Humble environment that you’re extending.
Note
Keep in mind that an underlay for a new overlay workspacedoes not necessarily have to be the mainROS 2 installation, it could also be another ROS 2 environment.
Your underlay must contain the dependencies of all the packages in youroverlay. Packages in your overlay will override packages in theunderlay. It’s also possible to have several layers of underlays andoverlays, with each successive overlay using the packages of its parentunderlays.
8.1.2. Create a new workspace directory#
Best practice is to create a new directory for every new workspace. Thename doesn’t matter, but it is helpful to have it indicate the purposeof the workspace.Let’s choose the directory name ros2_ws
, for “development workspace”:
$ mkdir -p ~/ros2_ws/src$ cd ~/ros2_ws/src
Another best practice is to put any packages in your workspace into thesrc
directory. The above code creates a src
directory insideros2_ws
and then navigates into it.
This workspace, ros2_ws
, will be an overlay on top of the existingROS 2 underlay.In general, it is recommended to use an overlay whenyou plan to iterate on a small number of packages, rather than puttingall of your packages into the same workspace.
8.1.3. Add package source code to your workspace#
In later sections of this manualyou will create your own packages,but for now you will practice putting a workspace togetherusing existing package source code.
If you went through theBeginner: CLI Tools tutorials, you’ll be familiar with turtlesim
.Let’s make our own turtlesim package.To do this, we’ll clone the source code of the official turtlesim
ROS package from itsgithub repository and place it in our workspace’s src
directory.A repo can have multiple branches and for many ROS packagesthere will be a branch that matches your ROS 2 distribution.So, when you git clone
this repo, add the-b
argument followed by that branch name to checkout the correct version.
In the ros2_ws/src
directory, run the following command:
$ git clone https://github.com/ros/ros_tutorials.git -b humble
Now ros_tutorials
is cloned in your workspace.The ros_tutorials
repository contains the turtlesim
package, which we’ll use in therest of this tutorial.
Note that the created ros_tutorials
directory contains more packagesub directories that also have a package.xml
,but these will be ignored by colcon
because they contain an (empty) COLCON_IGNORE
file.
So far you have populated your workspace with a sample package, but itisn’t a fully-functional workspace yet. You need to resolve thedependencies first and then build the workspace.
8.1.4. Resolve package dependencies#
Before building the workspace,it is important to make sure that all the dependenciesfor the packages in your new workspace have been installed.Otherwise, it may be impossible to build the project,for example because certain C++ libraries or ROS message definitionsfrom other packages are still missing.
Tip
You may have all the dependencies already, but bestpractice is to check for dependencies every time you clone. Youwouldn’t want a build to fail after a long wait only to realize thatyou have missing dependencies.
Packages declare their dependencies in the package.xml
file (you willlearn more about packages in the next tutorial).We can use the rosdep
command to look through all sourcedirectories for dependency declarations in package.xml
files,and automatically install the missing packages for us.
From the root of your workspace (ros2_ws
), run the rosdep
command as follows:
# cd if you're still in the `src/` directory with the `ros_tutorials` clone$ cd ..$ rosdep install -i --from-path src --rosdistro humble -y
If you already have all your dependencies, the console will return:
#All required rosdeps installed successfully
8.1.5. Build the workspace with colcon
#
From the root of your workspace (ros2_ws
), you can now build yourpackages using the command:
$ colcon build
The console will return the following message:
Starting >>> turtlesimFinished <<< turtlesim [5.49s]Summary: 1 package finished [5.58s]
Note
Other useful arguments for colcon build
:
--symlink-install
allows the installed files to be changed by changing the files in thesrc/
directory(e.g. Python files or other non-compiled resources) for faster developmentwithout needing to rebuild every time.This is mostly useful for Python ROS packages,but not so much for C++ ROS Packages.--packages-up-to
builds the package you want, plus all itsdependencies, but not the whole workspace (saves time).--event-handlers console_direct+
shows console output whilebuilding (can otherwise be found in thelog
directory).--executor sequential
processes the packages one by one instead ofusing parallelism.
Once the build is finished, we can inspect the content of the workspace root directory(~/ros2_ws
):
$ lsbuild install log src
As we can see, colcon
has created the three derived directoriesbuild/
, log/
and install/
from our initial src/
directory.
Tip
You can enable TAB-completion for
colcon
in yourbash
shell.If thecolcon-argcomplete
package is installed,you could addcolcon-argcomplete.bash
to your~/.bashrc
file.If you do not want to build a specific package place an empty filenamed
COLCON_IGNORE
in its directory, and it will be ignored bycolcon
.
8.1.6. Source the workspace as an overlay#
When colcon
has completed building successfully, the output will be in the install
directory.Before you can use any of the installed executables or libraries,you will need to add them to your path and library paths.colcon
will have generated bash/bat files in the install
directory to help set up the environment.These files will add all of the required elements to your path and library paths as well asprovide any bash or shell commands exported by packages.
Before sourcing the overlay, it is very important that you open a newterminal, separate from the one where you built the workspace. Sourcingan overlay in the same terminal where you built, or likewise buildingwhere 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/humble/setup.bash
Go into the root of your workspace:
$ cd ~/ros2_ws
In the root, source your overlay:
$ source install/local_setup.bash
Note
Sourcing the local_setup
of the overlay will only add the packagesavailable in the overlay to your environment. setup
sources theoverlay as well as the underlay it was created in, allowing you toutilize both workspaces.
So, sourcing your main ROS 2 installation’s setup
and then theros2_ws
overlay’s local_setup
, like you just did, is the same asjust sourcing ros2_ws
’s setup
, because that includes theenvironment of its underlay.
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 notyour 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 fromthe underlay.
The overlay takes precedence over the underlay.
8.1.7. Modify the package in the overlay#
You can modify turtlesim
in your overlay by editing the title bar onthe 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.
Find 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 andrun it again.
Return to the second terminal (where the overlay is sourced) and runturtlesim 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 terminalearlier, the overlay of your ros2_ws
environment takes precedence overthe contents of the underlay.
To see that your underlay is still intact, open a brand new terminal andsource only your ROS 2 installation. Run turtlesim again:
$ ros2 run turtlesim turtlesim_node
You can see that modifications in the overlay did not actually affectanything in the underlay.
8.1.8. Summary#
In this tutorial, you sourced your main ROS 2 distro install as yourunderlay and created an overlay by cloning and building packages in anew workspace. The overlay gets prepended to the path and takesprecedence over the underlay, as you saw with your modified turtlesim.
Using overlays is recommended for working on a small number of packagesso you don’t have to put everything in the same workspace and rebuild ahuge workspace on every iteration.