ros2-env

A zsh plugin to manage ROS 2 environment and workspaces

What is this and why do I need it?

If you are working with ROS, you probably have more than one workspace (different projects, robots, maybe even different versions of the same package). This means having to manually source the current workspace we are working on, which is no bueno. Moreover, when using colcon to build the workspace, you need to manually cd to the workspace's dir and run the command there.

Over the years working with ROS 1 and 2, I have seen (and created) multiple solutions, "hacks", aliases, functions and tears, usually included in the shell configuration to tackle these problems. This plugin is a cured compilation of all that.

The ros2-env plugin allows you to define a list of workspaces, and to assign a name to each one of them. Then you can "activate" one of the workspaces, sourcing it and making it the target for the colcon utility functions that are also provided by this plugin.

It is also possible to select a base ROS 2 distro (rolling, jazzzy, etc.) for each workspace, as well as a list of parent workspaces to overlay on top of them. You can find more info and some examples below.

The active workspace is stored in the environment variable $ROSWS_ACTIVE_WS, which can be changed with the rosws command described below.

Disclaimer

This workspace management part of the ros2-env plugin is heavily inspired by wd. Most of the functions, completions and even the tests have been extracted from this repository. Check it out if you still don't know about that amazing plugin!

Installation

Install for Oh-My-Zsh (recomended)

To install with Oh-My-Zsh, first clone the repo from an interactive Zsh session:

# make sure your $ZSH_CUSTOM is set
ZSH_CUSTOM=${ZSH_CUSTOM:-~/.oh-my-zsh/custom}

# now, clone the plugin
git clone https://github.com/butakus/ros2-env $ZSH_CUSTOM/plugins/ros2-env

Then, add the plugin to your Oh-My-Zsh plugins list in your .zshrc

# in your .zshrc, add this plugin to your plugins list
plugins=(... ros2-env)

Manual installation

To install manually, first clone the repo:

git clone https://github.com/butakus/ros2-env ${ZDOTDIR:-~}/.zplugins/ros2-env

Then, in your .zshrc, add the following line:

source ${ZDOTDIR:-~}/.zplugins/ros2-env/ros2-env.plugin.zsh

Colcon build utility

Build the active workspace with the cb (colcon build) command. No matter where you are.

Usage (cb)

• Compile the current active workspace:

cb

• Compile any workspace by name:

cb foo
cb bar

Note: If you build any listed workspace with cb ws_name, the just-built workspace will be sourced and set as the active one:

# Active workspace is 'foo'
cb bar
# Now 'bar' is sourced and 'foo' is not.

Cleaning workspaces

If sometimes you feel the need to clear all the compilation files that are generated in the build, install and log subdirectories, this comes in handy (sometimes we just need a compilation break):

Usage (colcon_clean)

• Clean the compilation files from the current active workspace:

colcon_clean

• Clean any workspace by name:

colcon_clean foo
colcon_clean bar

This command is simmilar to colcon clean plugin, except you don't need to cd to the workspace's root dir. On the other hand, it is not possible to clean specific packages (the whole workspace is cleaned).

Workspace management

Similar to wd, this plugin provides a rosws command that allows you to change the active workspace, and to manage the list of registered workspaces. Only one workspace can be active at the same time.

Usage (rosws)

Add current working directory to list of workspaces:

rosws add foo

If a workspace with the same name exists, use rosws add foo --force to overwrite it.

Note: The workspace cannot contain colons (':') in neither the name nor the path. This will conflict in how rosws stores the workspaces.

You can omit the workspace name to automatically use the current directory's name instead.

Add a new workspace under a specific ROS 2 distro:

rosws add foo rolling

This will configure workspace foo with ROS 2 rolling as the base. When building and sourcing the foo workspace, the base environment from /opt/ros/<distro>/setup.zsh will be sourced first.

Note: By default, the rosws add command will link the new workspace with whatever environment is set in the $ROS_DISTRO environment variable.

Make foo the active workspace:

rosws foo
# or
rosws activate foo

Remove workspace:

rosws rm foo

List all registered workspaces:

rosws list

Workspaces are stored in ~/.config/ros2-env/workspaces by default.

Show information of given workspace:

rosws show foo

Show path (pwd) of given workspace:

rosws path foo

Remove workspaces pointing to non-existent directories.

rosws clean

Use rosws clean --force to not be prompted with confirmation.

Change directory to the workspace:

You can also cd to any directory inside the workspace, with autocompletion.

rosws cd foo
# Or
rosws cd foo src/awesome_package

Using rosws cd without any additional argument will cd into the current active workspace.

Print usage info:

rosws help

The usage will be printed also if you call rosws with no command

Print the running version of rosws:

rosws --version

Configuration

The configuration file where workspaces are registered is stored by default in ~/.config/ros2-env/workspaces. It is possible to modify this by setting the environment variable $ROSWS_CONFIG.

Colcon parameters

It is also possible to control the arguments passed to colcon when using the cb command, by setting the $CB_EXTRA_ARGS environment variable. For example:

export CB_EXTRA_ARGS="--symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release"

By default, this variable only includes the --symlink-install option.

Note: In the future, cb will allow adding extra arguments that will be passed to colcon, to avoid setting the environment variable.

ROS 2 distro

It is possible to select a different distro (rolling, jazzy, etc.) when adding a new workspace. By default, the value stored in $ROS_DISTRO is used. Example:

# Add foo workspace with the ROS 2 humble setup
rosws add foo humble

When a workspace is activated, the system will first load the environment for its corresponding ROS distro from /opt/ros/<distro>/setup.zsh, and then it will source the workspace environment.

If you want to only load the distribution environment, you can do it by using the rosws distro command:

rosws distro <distro>

This will source the environment in /opt/ros/<distro>/setup.zsh, also setting the $ROS_DISTRO variable.

Chained workspaces

When adding a new workspace, in addition to setting the base ROS 2 distro, it is also possible to set a list of parent workspaces (or underlay workspaces), that will be sourced before the overlay.

To do this, just pass the paths of the parent workspaces (in order) after the ROS distro. Example:

rosws add foo rolling ~/ros2/base_ws ~/ros2/sim_ws

This will set "base_ws" and "sim_ws" as underlays of the newly created foo workspace. When activating (sourcing) or building foo with cb, the underlays will be sourced first in the following order:

rolling --> base_ws --> sim_ws --> foo