debug-support.md

Debug ROS Nodes

One of the key goals of vscode-ros is to provide a streamlined debugging experience for ROS nodes. To achieve this, this extension aims to help developers utilize the debugging capabilities provided by Visual Studio Code. This document covers instructions of how to use such functionalities.

Read more about the design and related discussions on the debugging functionalities in our design document.

Attach

vscode-ros enables a bootstrapped debugging experience for debugging a ROS (Python or C++) node by attaching to the process.

To get started, create a ros-type debug configuration with an attach request: (use Ctrl-Space to bring up the autocomplete dropdown)

Attaching to a Python node

Attaching to a C++ node

Launch

vscode-ros enables a streamlined debugging experience for debugging a ROS (Python or C++) node in a ROS launch file similar to a native debug flow.

To get started, create a ros-type debug configuration with a launch request:

Prerequisite

There needs to be a running instance of rosmaster. The launch-debug flow provided by vscode-ros will not spawn a rosmaster.

Launch and debug Python and C++ nodes

Use tasks to automatically build before starting debug session

The first thing you need to do is to create build task for your package(s) with enabled debug symbols. In the example below you can see a catkin_make build task that passes additional -DCMAKE_BUILD_TYPE=Debug argument that switches build to use Debug configuration, which is the most suitable configuration for debugging, because it has 0 optimization level and includes debug symbols. Another option is to use -DCMAKE_BUILD_TYPE=RelWithDebInfo that also enables debug symbols, but uses Release settings for everything else and has optimizations enabled. RelWithDebInfo might be a go to build configuration for Windows users in order to avoid slowness of the debug CRT on Windows OS. You can read more about CMAKE_BUILD_TYPE here

Note: you might need to remove the old build folder to force rebuild in new configuraiton.

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "make_debug",
            "type": "catkin_make",
            "args": [
                "--directory",
                "${workspaceFolder}",
                "-DCMAKE_BUILD_TYPE=Debug", // This extra argument enables built with debug symbols
            ],
            "problemMatcher": [
                "$catkin-gcc"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
        },
    ]
}

The next step would be to configure .vscode/launch.json and customize preLaunchTask to use make_debug task we created above.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "ROS: Launch",
            "type": "ros",
            "request": "launch",
            "target": "${workspaceFolder}/launch/some.launch", // <<< Configure path to your launch file
            "preLaunchTask": "make_debug", // <<< This is the task that will run before debugging starts
        }
    ]
}

Use tasks to automatically build and start rosmaster

This is current BLOCKED BY VSCode Bug 70283. This bug will prevent the second debugging session from starting if roscore background task is already running

This section continues setup that was described above, so please complete that section and ensure you can build and debug with manually started roscore

We are going to define a new task named make_debug_and_core that is going to start both make_debug and roscore: roscore tasks. roscore: roscore is a background task that will continue running even after debuging session is over

{
    "version": "2.0.0",
    "tasks": [
        /// ... `make_debug` task definition as before
        {
            "label": "make_debug_and_core",
            "dependsOn": [
                "make_debug",
                "roscore: roscore", // This task is provided by vscode-ros
            ]
        },
    ]
}

The next step would be to switch preLaunchTask to use make_debug_and_core task we created above.

{
    "version": "0.2.0",
    "configurations": [
        {
            // ... same as before
            "preLaunchTask": "make_debug_and_core",
        }
    ]
}

Note

1. Debugging functionality provided by vscode-ros has dependencies on VS Code’s C++ and Python extensions, and those have dependencies on the version of VS Code. To ensure everything works as expected, please make sure to have everything up-to-date.
2. To debug a C++ executable, please make sure the binary is built with debug symbols (e.g. -DCMAKE_BUILD_TYPE=RelWithDebInfo, read more about CMAKE_BUILD_TYPE here).
3. To use VS Code's C++ extension with MSVC on Windows, please make sure the VS Code instance is launched from a Visual Studio command prompt.