|
| 1 | +--- |
| 2 | +title: Configure VS Code for ROS 2 |
| 3 | +date: 2026-04-13 |
| 4 | +--- |
| 5 | + |
| 6 | +This tutorial provides a comprehensive guide to configuring Visual Studio Code (VS Code) for effective ROS 2 development. It covers essential setup steps including debugging C++ nodes with GDB, optimizing build processes using colcon's symlink-install, and automating common workflows through VS Code's tasks.json. Additionally, it explores the features of the official ROS 2 extension to further streamline your development environment. By following these best practices, developers can significantly improve their productivity and more easily identify runtime errors in their robotic systems. |
| 7 | + |
| 8 | +> This tutorial assumes you already have ROS 2 and Visual Studio Code installed and properly set up on your system. |
| 9 | +
|
| 10 | +In this tutorial, we'll walk through setting up a development environment in Visual Studio Code (VS Code) to debug and compile ROS 2 packages effectively. We'll start with configuring debugging tools to help identify runtime errors and then explore how to streamline your build process using VS Code's task configurations. |
| 11 | + |
| 12 | +## Debugging in VS Code |
| 13 | + |
| 14 | +Let's begin with debugging. |
| 15 | + |
| 16 | +Open VS Code and load a ROS 2 package. For this example, we'll be using a simple publisher node written in C++. We'll start by intentionally commenting out the line that creates the publisher to simulate a bug. Even though the code appears fine to C++ linting tools, compiling it with `colcon build` will complete successfully. |
| 17 | + |
| 18 | + |
| 19 | + |
| 20 | + |
| 21 | +However, when you try to run the node, you’ll get a segmentation fault. This error isn't informative, so we'll set up proper debugging using `gdb` and VS Code. |
| 22 | + |
| 23 | + |
| 24 | + |
| 25 | + |
| 26 | +### Using GDB |
| 27 | + |
| 28 | +First, build your ROS 2 workspace with debugging symbols: |
| 29 | + |
| 30 | +```bash |
| 31 | +colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug |
| 32 | +``` |
| 33 | + |
| 34 | +Then, run the node using `gdbserver`: |
| 35 | + |
| 36 | +```bash |
| 37 | +ros2 run --prefix 'gdbserver localhost:3000' <your_package> <your_node> |
| 38 | +``` |
| 39 | + |
| 40 | +If `gdbserver` is not installed, you can install it with: |
| 41 | + |
| 42 | +```bash |
| 43 | +sudo apt update |
| 44 | +sudo apt install gdbserver |
| 45 | +``` |
| 46 | + |
| 47 | +So here we see processing our node listening on Port 3000, but now we need to configure our Vs code |
| 48 | + |
| 49 | +to communicate with the debugger. |
| 50 | + |
| 51 | + |
| 52 | + |
| 53 | + |
| 54 | +Now, configure VS Code to connect to the `gdbserver`. Create a `.vscode/launch.json` file: |
| 55 | + |
| 56 | +```json |
| 57 | +{ |
| 58 | + "version": "0.2.0", |
| 59 | + "configurations": [ |
| 60 | + { |
| 61 | + "name": "Attach to gdbserver", |
| 62 | + "type": "cppdbg", |
| 63 | + "request": "launch", |
| 64 | + "miDebuggerServerAddress": "localhost:3000", |
| 65 | + "program": "/path/to/install/<your_package>/lib/<your_package>/<your_node>", |
| 66 | + "cwd": "${workspaceFolder}", |
| 67 | + "MIMode": "gdb", |
| 68 | + "externalConsole": false, |
| 69 | + "stopAtEntry": false |
| 70 | + } |
| 71 | + ] |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | + |
| 76 | + |
| 77 | +Once saved, go to the Debug tab in VS Code and click **Start Debugging**. The debug pane shows variables, their values, and the call stack—helping identify issues such as an uninitialized publisher. |
| 78 | + |
| 79 | + |
| 80 | + |
| 81 | + |
| 82 | +## Simlink Install with colcon |
| 83 | +By default, when you run `colcon build`, the build system **copies** the compiled binaries, libraries, and resources into the `install/` directory. While this works fine, it can be **inefficient and slow**—especially during iterative development—because every time you rebuild, files are duplicated into the install space. |
| 84 | +To improve build efficiency, use the `--symlink-install` flag with colcon. This creates symbolic links instead of copying files into the `install/` directory: |
| 85 | + |
| 86 | +```bash |
| 87 | +colcon build --symlink-install |
| 88 | +``` |
| 89 | + |
| 90 | +If you've already built the workspace, delete `build/`, `install/`, and `log/` directories first: |
| 91 | + |
| 92 | +```bash |
| 93 | +rm -rf build/ install/ log/ |
| 94 | +``` |
| 95 | + |
| 96 | +Then rerun the build command with the symlink flag. |
| 97 | + |
| 98 | +## Automating Builds and Debugging with `tasks.json` |
| 99 | + |
| 100 | +Now, it can be inconvenient to remember and re-type long commands like `colcon build --symlink-install`, especially if you often switch between workspaces. VS Code allows us to automate such tasks using a `tasks.json` file. |
| 101 | + |
| 102 | +### Creating a Build Task |
| 103 | + |
| 104 | +Open your workspace in VS Code. In the file explorer, navigate to the `.vscode/` directory. If it doesn’t exist, create it. Inside that directory, create a file named `tasks.json`. |
| 105 | + |
| 106 | +Here’s an example configuration: |
| 107 | + |
| 108 | +```json |
| 109 | +{ |
| 110 | + "version": "2.0.0", |
| 111 | + "tasks": [ |
| 112 | + { |
| 113 | + "label": "build", |
| 114 | + "type": "shell", |
| 115 | + "command": "source /opt/ros/humble/setup.bash && colcon build --symlink-install", |
| 116 | + "group": { |
| 117 | + "kind": "build", |
| 118 | + "isDefault": true |
| 119 | + }, |
| 120 | + "problemMatcher": [] |
| 121 | + }, |
| 122 | + { |
| 123 | + "label": "build (debug)", |
| 124 | + "type": "shell", |
| 125 | + "command": "source /opt/ros/humble/setup.bash && colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug", |
| 126 | + "group": "build", |
| 127 | + "problemMatcher": [] |
| 128 | + }, |
| 129 | + { |
| 130 | + "label": "debug-helper", |
| 131 | + "type": "shell", |
| 132 | + "command": "echo "\nRun your node with:\nros2 run --prefix 'gdbserver localhost:3000' <your_package> <your_node>\n\nThen update launch.json to point to the right executable."", |
| 133 | + "group": "build", |
| 134 | + "problemMatcher": [] |
| 135 | + } |
| 136 | + ] |
| 137 | +} |
| 138 | +``` |
| 139 | + |
| 140 | +> **Tip:** If you want to source your full `.bashrc` instead of just ROS setup, modify the `command` line: |
| 141 | +> |
| 142 | +> ```bash |
| 143 | +> source ~/.bashrc && colcon build --symlink-install |
| 144 | +> ``` |
| 145 | +
|
| 146 | +To run these tasks: |
| 147 | +- Go to **Terminal → Run Build Task** or press **Ctrl+Shift+B**. |
| 148 | +- Choose `build`, `build (debug)`, or `debug-helper`. |
| 149 | +
|
| 150 | +This automates builds and reminds you of necessary debug setup steps. |
| 151 | +
|
| 152 | +> **Important**: Make sure VS Code is opened in your **ROS 2 workspace root**. If you're in the wrong directory, `colcon build` may fail or build the wrong packages. |
| 153 | +
|
| 154 | +--- |
| 155 | +
|
| 156 | +## Using the ROS 2 VS Code Extension |
| 157 | +
|
| 158 | +The [ROS Tools extension](https://marketplace.visualstudio.com/items?itemName=ms-iot.vscode-ros) in VS Code offers convenient tools for interacting with ROS 2. |
| 159 | +
|
| 160 | +### Common ROS Commands in VS Code |
| 161 | +
|
| 162 | +Press **F1** and type `ROS` to view available commands: |
| 163 | +
|
| 164 | +- **ROS: Show Status** – Displays current ROS nodes, topics, and status. |
| 165 | +- **ROS: Create ROS Terminal** – Opens a terminal with the correct ROS environment sourced. |
| 166 | +- **ROS: Run a ROS Executable** – Lets you select a package and node to run from a dropdown. |
| 167 | +- **ROS: Update C++ Properties** – Updates your `c_cpp_properties.json` file to enable IntelliSense in C++ ROS projects. |
| 168 | +- **ROS: Install ROS Dependencies (rosdep)** – Installs missing dependencies in your workspace using `rosdep install`. |
| 169 | +
|
| 170 | +> Even if you’re using ROS 2 (e.g., Humble), some commands still reference `rosrun` from ROS 1. These labels are legacy but still work for launching executables. |
| 171 | +
|
| 172 | +### Running a Node via Extension |
| 173 | +
|
| 174 | +1. Press **F1** → `ROS: Run a ROS Executable`. |
| 175 | +2. Choose your package. |
| 176 | +3. Select the executable (e.g., `minimal_publisher`). |
| 177 | +4. If needed, enter arguments. |
| 178 | +5. A terminal will open and run the node with the correct environment. |
| 179 | +
|
| 180 | +### Creating a ROS-Sourced Terminal |
| 181 | +
|
| 182 | +Select **ROS: Create ROS Terminal** from the F1 menu. This opens a new terminal tab with ROS environment variables sourced, allowing you to run commands like: |
| 183 | +
|
| 184 | +```bash |
| 185 | +ros2 topic echo /your_topic |
| 186 | +``` |
| 187 | +
|
| 188 | +### Updating C++ IntelliSense |
| 189 | +
|
| 190 | +If your C++ symbols or headers aren’t resolving correctly, use: |
| 191 | +
|
| 192 | +```text |
| 193 | +ROS: Update C++ Properties |
| 194 | +``` |
| 195 | +
|
| 196 | +This command re-generates `c_cpp_properties.json` with include paths specific to your workspace and ROS installation. |
| 197 | +
|
| 198 | +--- |
| 199 | +
|
| 200 | +## Troubleshooting and Best Practices |
| 201 | +
|
| 202 | +- Always open VS Code in your **workspace root** directory. |
| 203 | +- Use `--symlink-install` to reduce rebuild times. |
| 204 | +- Use `launch.json` to attach VS Code’s debugger to ROS nodes. |
| 205 | +- Keep reusable scripts or environment helpers in your workspace for consistency. |
| 206 | +
|
| 207 | +--- |
| 208 | +
|
| 209 | +## Summary |
| 210 | +In summary, setting up a robust development environment in VS Code is crucial for efficient ROS 2 development. By using GDB for debugging, symlink-install for faster builds, and automating tasks with `tasks.json`, you can create a more responsive and error-resistant workflow. The ROS 2 extension further enhances this by providing integrated tools for common ROS operations. |
| 211 | +
|
| 212 | +## See Also |
| 213 | +* [Debugging ROS 2](https://docs.ros.org/en/rolling/Tutorials/Debugging-ROS-2.html) |
| 214 | +* [colcon documentation](https://colcon.readthedocs.io/en/released/index.html) |
| 215 | +
|
| 216 | +## Further Reading |
| 217 | +* [VS Code launch.json reference](https://code.visualstudio.com/docs/editor/debugging) |
| 218 | +* [ROS 2 Tools Extension on Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-iot.vscode-ros) |
| 219 | +
|
0 commit comments