Document editing/debugging process in VSCode for C++ and Python when developing with the standard ROS toolchain.

[Ryanf55]

Purpose

There are a few places to look on how to set up VSCode to debug C++ and Python while using a colcon workspace, but these could live with the ROS documentation. colcon and multi-project workspaces add complexity to the environment setup, so we should explain to users how to not let it get in the way of introspection.

Assumptions

• You develop on your host Tier 1 OS (Ubuntu, Windows)
• You have a src folder and a number of ROS packages
• You develop a mix of python and C++ projects
• You use VSCode
• You have the ability to upgrade CMake (for the CMake debugger in 3.30), which can be done using Kitware's apt repository if on Ubuntu 22.
• You open VSCode at the ros_ws top level workspace, and that is where you .vscode settings live.

C++

CMake Debugger

The visual CMake debugger in CMake 3.30 is awesome! But, it assumes you have a top level CMakeLists, or only one CMakeLists project. It's not clear, if you have a package that has a CMake configure error in a ROS workspace, how you get VScode to Configure with Debugger.

• https://devblogs.microsoft.com/cppblog/introducing-cmake-debugger-in-vs-code-debug-your-cmake-scripts-using-open-source-cmake-debugger/

Intellisense

VSCode needs intellisense working, but we need to set up the include paths. When you add a new package to the workspace, intellisense needs to know about it. Let's document how to set that up.

GDB

• How do we use VSCode's visual GDB debugging on a node?
• How do we use VSCode's visual GDB debugging on a gtest test?

Python

Debugger

• How do we use VSCode to set breakpoints in a python node?
• How do we use VSCode to set breakpoints in a pytest-based test?
  • This shows how to set up the debugger, but it doesn't work with imports from other packages because there is no way to run source install/setup.bash
  • Here is my proposed fix that works OK but involves a lot of code duplication

Launch

• How do we debug a launch file?

Notes

• Let's try to help users not resort to print-debugging
• Let's try not to make users have to edit any files in .vscode every time they add a new test, a new node, or a new package to the workspace. There may be limitations for how hands-off this can be, but let's document them.
• Docker and Devcontainers are out of scope of this issue, see Setup-ROS-2-with-VSCode-and-Docker-Container.rst needs a review #3664
• Requiring to source ./install/setup.bash and `source /opt/ros//setup.bash makes it hard for some VSCode operations like doing operations in tasks.json

References

• https://picknik.ai/vscode/docker/ros2/2024/01/23/ROS2-and-VSCode.html#working-in-c
• https://www.youtube.com/watch?v=hf76VY0a5Fk&ab_channel=RoboticsBack-End
• https://github.com/ms-iot/vscode-ros