Skip to main content

Code Autoformatting in VSCode

To use the autoformatting in VSCode, follow these steps:

  1. Install VSCode
  2. Install VSCode extensions: C/C++, C/C++ Extension Pack, clangd, Run on Save (VSCode might prompt you to disable intelliSenseEngine, do it)
  3. Set up clangd config for C/C++ code formatting: create file $HOME/.clang-format in your home directory and paste the clang settings inside
  4. Set up clangd as the default formatter: File -> Preferences -> Settings and set Editor: Default Formatter to clangd.
  5. Set up code formatting on save: File -> Preferences -> Settings and check Editor: Format on Save.

Now when you save a file (Ctrl + s), you code should automatically reformat.

Working with Multi-Packages​

However, clangd requires file compile_commands.json generated by cmake run with CMAKE_EXPORT_COMPILE_COMMANDS=ON.

In our setup, this is done automatically when colcon build is run, but one compile_commands.json is generated for each ROS package in workspace/build/_package_/compile_commands.json.

The following setup process links the workspace/build/_package_/compile_commands.json into the relevant ROS package whenever the package is built. The package-specific compile_commands.json is then loaded by clangd.

  1. In the ROS2 package, open .gitignore and add the following line, if you don't have it in your .global_gitignore
compile_commands.json
  1. In the ROS2 package, open CMakeLists.txt and add the following lines right after the project(you_project_name) (this will create and link a compile_commands.json file in the package source dir after every colcon build)
# --- Export & Symlink compile_commands.json ---
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

set(SOURCE_JSON "${CMAKE_SOURCE_DIR}/compile_commands.json")
set(BINARY_JSON "${CMAKE_BINARY_DIR}/compile_commands.json")

add_custom_target(symlink_compile_commands ALL
    COMMAND ${CMAKE_COMMAND} -E create_symlink ${BINARY_JSON} ${SOURCE_JSON}
    COMMENT "Symlinking compile_commands.json to source directory"
    VERBATIM
)
  1. Open the ROS2 package in VSCode.
  2. Code formatting shall work for you now. You may verify that by changing ColumnLimit: 50 in $HOME/.clang-format, saving a file, and checking that each row has max. 50 characters. Revert this change back to ColumnLimit: 160 afterwards.

We recommend opening a ROS2 package not from the workspace symlink, but from the source of your ~/git folder.

VSCode Tasks​

  • We can automate a lot of tasks by integrating external tools via VSCode Tasks. Configuration lives in .vscode/tasks.json, where each tool or task is defined as a JSON entry. You can either create this file manually or let VSCode generate a skeleton via Terminal → Configure Tasks.

  • We recommend having at least the following three tasks: Build, Build in Debug mode, and Run Tests.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "detail": "Build workspace (default)",
      "type": "shell",
      "command": "./build.sh",
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "problemMatcher": "$gcc"
    },
    {
      "label": "debug",
      "detail": "Build workspace (debug)",
      "type": "shell",
      "command": "./build.sh",
      "options": {
        "env": {
          "BUILD_TYPE": "Debug"
        }
      },
      "group": {
        "kind": "build",
        "isDefault": false
      },
      "problemMatcher": "$gcc"
    },
    {
      "label": "test",
      "detail": "Run all unit tests and show results.",
      "type": "shell",
      "command": "./test.sh",
      "group": {
        "kind": "test",
        "isDefault": true
      }
    }
  ]
}

Both build.sh and test.sh should be placed in the project root directory and marked as executable (chmod +x build.sh test.sh). Their contents are as follows: build.sh

#!/bin/bash
set -e

# Set the default build type
BUILD_TYPE=${BUILD_TYPE:-RelWithDebInfo}
colcon build \
        --parallel-workers 8 \
        --symlink-install \
        --cmake-args "-DCMAKE_BUILD_TYPE=$BUILD_TYPE" "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON"

test.sh

#!/bin/bash
set -e

if [ -f install/setup.bash ]; then source install/setup.bash; fi

colcon test-result --delete-yes
colcon test --event-handlers console_direct+ --ctest-args -V --color-output
colcon test-result --all --verbose

You can run these tasks via Ctrl+Shift+P → Tasks: Run Task and selecting the desired task, or use Ctrl+Shift+B to directly run the default build task.

note

Scripts colcon configuration settings will be merged with colcon_defaults.yaml settings if the file exists. Command-line arguments (the ones in the scripts) have the highest precedence and will override any conflicting values in the defaults file; however, any extra non-conflicting arguments specified in the defaults file will still be added to the build command.