catkin-tools support for VS Code

This extension makes it easier to work with catkin-tools.

Features

Watches the build directory of the current catkin-tools workspace for changes in compile_commands.json files.
- Implements a C/C++ configuration provider using these compile commands, enabling auto completion
Provides catkin build tasks for
- Build all packages in the workspace
- Build the package containing the currently open file
Allows switching between different catkin profiles
Provides Test Explorer client to handle GTest targets

Setup / Configuration

This extension activates itself only if there is a top level .catkin_tools directory in your opened workspace. In a standard catkin layout, this means that the opened workspace should look like the following:

<workspace>/.catkin_tools
<workspace>/src
[<workspace>/devel]
[<workspace>/build]
[<workspace>/install]
[<workspace>/logs]

If you do not want to list build, devel, etc., we suggest you add them to your workspace's exclude list in your settings.json file:

...
    "files.exclude": {
        ".catkin_tools/": true,
        "build*/": true,
        "install*/": true,
        "devel*/": true,
        "logs*/": true,
    },
...

The folders for devel, build and log spaces can also be called differently, only the src space is required. This way, arbitrary catkin profiles are supported.

CMAKE_EXPORT_COMPILE_COMMANDS

Make sure that your catkin_tools workspace is set up to generate compile_commands.json files. This can be done by setting the CMAKE_EXPORT_COMPILE_COMMANDS flag to ON or 1 and re-building the workspace.
The compile_commands.json files are created for each package that is built inside the build folder.

catkin config --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
catkin build

If you have any other cmake arguments, please pass them along in the above command, for e.g. -DCMAKE_BUILD_TYPE=Debug.

An alternate option is to directly modify the cmake_args section of the .catkin_tools/profiles/<profile_name>/config.yaml file.

cmake_args:
- -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
- -DCMAKE_BUILD_TYPE=Debug

IntelliSense

Make sure to

use this extension as the configurationProvider for ms-vscode.cpptools,
use the default intellisense mode.

This can be done by adding the following lines to the c_cpp_properties.json file in the .vscode folder.

{
    "configurations": [
        {
            "configurationProvider": "b2.catkin_tools",
            "intelliSenseMode": "${default}"
        }
    ],
    "version": 4
}

GTest targets

This extensions registers itself as TestExplorer adapter. For this, all CMakeLists.txt are scanned for keywords hinting at the existence of CTest based unit tests, e.g. catkin_add_gtest. This is done with a list of regular expressions. If you have a custom macro for registering tests, you can customize this behavior via the catkin_tools.gtestMacroRegex property.

For example:

...
    "catkin_tools.gtestMacroRegex": [
        "catkin_add_gtest",
        "my_.*test"
    ]
...

in your workspace settings will list all catkin_add_gtest tests and all tests matching my_.*test, e.g. my_test and my_google_test.

C/C++ Clang Command Adapter compatibility

Using this extension with C/C++ Clang Command Adapter auto completion causes too many symbols to show up in IntelliSense auto completion. If you are using the extension, we suggest you set the option

...
"clang.completion.enable": false
...

in your workspace settings.

Tasks

You can register catkin build as a build task in the following way.

Press ctrl+shift+p > Tasks: Configure Task > catkin_build: build or catkin_build: build current package or catkin_build: run current package tests
If a tasks.json file does not exist, it will be created and a snippet similar to the following will be added. If tasks.json already exists, configuration settings are added only to the "tasks" section.

{
	"version":"2.0.0",
	"tasks":[
		{
			"type": "catkin_build",
			"task": "build",
			"problemMatcher": [
				"$catkin-gcc",
				"$catkin-cmake"
			],
			"label": "catkin_build: build",
			"group": "build"
		}
	]
}

Note: You can add multiple build tasks into a single tasks.json file by repeating the above steps.
Note: Make sure that "group": "build" is present. If not add it. The task will then be available as a build task, i.e it will appear in the drop down menu when you press ctrl+shift+b.
Note: To set a particular task as the default task, modify the "group": "build" to the following. If this is done, you can no longer choose the build tasks and only the default one will be executed when you press ctrl+shift+b.

	"group": {
           	"kind": "build",
           	"isDefault": true
       	}

Building packages

Press ctrl+shift+b. If a default build task is not set, you can can choose between the different build tasks available.

catkin_build: build will build all the packages in the workspace.
catkin_build: build current package will only build the package that the currently open file belongs to.
catkin_build: run current package tests will only build the package that the currently open file belongs to and runs tests.

tejaswid/vscode-catkin-tools