VSCode ROS2 Workspace Template

This template will get you set up using ROS2 with VSCode as your IDE.

The development environment is set up using a VSCode devcontainer, and the same configuration is also used in CI.

Features

Development environment

The devcontainer uses the Microsoft Ubuntu devcontainer image along with the ROS2 devcontainer feature.

If you want to change which version of ROS you're using, update the ROS2 feature in .devcontainer/devcontainer.json:

"ghcr.io/althack/devcontainers/ros2:0": {
  "distro": "lyrical",
  "package": "desktop"
}

This is also the ROS version used in CI, so you only need to change it in one place.

Style

ROS2-approved formatters are included in the IDE.

• c++ uncrustify; config from ament_uncrustify
• python autopep8; vscode settings consistent with the style guide

Tasks

There are many pre-defined tasks, see .vscode/tasks.json for a complete listing. Feel free to adjust them to suit your needs.

Take a look at how I develop using tasks for an idea of how I use tasks in my development.

Debugging

This template sets up debugging for python files, gdb for cpp programs, and ROS launch files.

See .vscode/launch.json for configuration details.

Continuous Integration

The template also comes with basic continuous integration set up. See .github/workflows/ros.yaml.

The build, test, and lint jobs run using the same devcontainer configuration used for development. This means changing the ROS distro in .devcontainer/devcontainer.json also changes the version used by CI.

To remove a linter, just delete its name from the matrix:

matrix:
  linter:
    - cppcheck
    - cpplint
    - uncrustify
    - lint_cmake
    - xmllint
    - flake8
    - pep257

How to use this template

Prerequisites

You should already have Docker and VSCode with the Dev Containers extension installed on your system.

• docker
• vscode
• vscode dev containers extension

If you're using Windows, I recommend using WSL2 and opening the repository from your WSL distro before reopening it in the container.

Get the template

Click on Use this template.

Create your repository

On the next dialog, name the repository you would like to start and choose its visibility.

Github will then create a new repository with the contents of this one in your account. It grabs the latest changes as the initial commit.

Clone your repo

Now you can clone your repo as normal.

Open it in vscode

Now that you've cloned your repo onto your computer, open it in VSCode (File -> Open Folder).

When you open it for the first time, you should see a popup asking if you would like to reopen it in a container. Say yes!

If you don't see the popup, open the command palette and select:

Dev Containers: Reopen in Container

VSCode will set up the container from .devcontainer/devcontainer.json, install ROS2 and the configured development tools, and install the recommended VSCode extensions.

Once that's finished, open a terminal inside VSCode and you're ready to go.

Update the template with your code

1. Specify the repositories you want to include in your workspace in src/ros2.repos, or delete src/ros2.repos and develop directly within the workspace.

2. If you are using a ros2.repos file, import the contents with Terminal -> Run Task... -> import from workspace file.

3. Install dependencies with Terminal -> Run Task... -> install dependencies.

4. Adjust the scripts to your liking. These scripts are used both within tasks and CI.

   • setup.sh - setup commands for your code. By default this imports the workspace and installs dependencies.
   • build.sh - build commands for your code. By default this uses --merge-install and --symlink-install.
   • test.sh - test commands for your code.

5. Develop!

Changing the ROS distro

The ROS distro is selected by the ROS2 feature in .devcontainer/devcontainer.json:

"ghcr.io/althack/devcontainers/ros2:0": {
  "distro": "lyrical",
  "package": "desktop"
}

Change distro to the version you want to use and rebuild the container.

Since CI uses the same devcontainer configuration, you don't need to update the ROS distro anywhere else.

GUI applications

Windows / WSL2

If you're using Windows, open the repository from your WSL2 distro and then reopen it in the devcontainer.

Current versions of VSCode Dev Containers and WSLg handle the display forwarding for you, so you shouldn't need to manually configure DISPLAY, Wayland, PulseAudio, or /mnt/wslg mounts.

Linux / X11

If you're using native Linux with X11, uncomment the X11 forwarding feature in .devcontainer/devcontainer.json:

"ghcr.io/althack/devcontainers/linux-x11-forwarding:0": {},

Some GUI applications may also need the container to share the host IPC namespace. If you run into rendering problems, try uncommenting:

"--ipc=host"

in runArgs.

NVIDIA / CUDA

CUDA support is optional.

If you want to use CUDA, uncomment the NVIDIA CUDA feature in .devcontainer/devcontainer.json:

"ghcr.io/devcontainers/features/nvidia-cuda:3": {
  "installToolkit": true
}

and allow the container to access the host GPU:

"--gpus",
"all"

You'll also need working NVIDIA drivers and the NVIDIA Container Toolkit installed on the host.

See the NVIDIA Container Toolkit installation guide for setup instructions.

I don't test all of the possible NVIDIA/CUDA host configurations, so your mileage may vary here.

Repos are not showing up in VS Code source control

VSCode doesn't necessarily know about repositories you've imported underneath the workspace.

You can add them directly using:

File -> Add Folder To Workspace

Or you can add them as git submodules.

To add all of the repos in your *.repos file as submodules, run:

python3 .devcontainer/repos_to_submodules.py

or run the task titled:

add submodules from .repos