Visual Studio Code CMake Tools Extension: Multi-root workspaces and file-based API

Erika Sweet

The February 2020 update of the Visual Studio Code CMake Tools extension is now available. This release includes two of the extension’s top feature requests: file-based API support and multi-root workspaces. For a full list of this release’s improvements check out the release notes on GitHub.

Multi-root workspace support

The latest release of the CMake Tools extension comes with support for multi-root workspaces. This means you can have two or more folders containing a root CMakeLists.txt open side-by-side in Visual Studio Code. When a workspace contains multiple folders, the CMake Tools extension will display the active folder in the left-hand side of the status bar. The active folder is the folder to which all CMake-specific commands (configure, build, debug, etc.) are applied. In the following example my active folder is CMakeProject-1.

By default, the active folder will change based on your file context. Viewing or editing a file in CMakeProject-1 will cause CMakeProject-1 to be the active folder, while viewing or editing a file in CMakeProject-2 will cause CMakeProject-2 to be the active folder. You can temporarily override the active folder by selecting the active folder in the status bar or running the CMake: Select Active Folder command.

You can also disable this behavior by setting the user-level or workspace-level setting CMake: Auto Select Active Folder to false. To open your workspace settings, use the command “Workspaces: Open Workspace Configuration File”. If cmake.autoSelectActiveFolder is set to false then your active folder will only change if you manually run the CMake: Select Active Folder command.

Finally, the CMake Tools extension has also added new commands like CMake: Configure All Projects and CMake: Build All Projects to apply existing CMake commands to all the folders in your workspace. These commands are only available when you have more than one folder open in your workspace.

Commands to configure, build, clean, rebuild and reconfigure all projects are also available from the CMake: Project Outline view.

File-based API

Thank you to @KoeMai for submitting this PR!

CMake version 3.14 introduced file-based API, which is a new way for clients (like the CMake Tools extension) to get semantic information about the underlying build system generated by CMake. It allows the client to write query files prior to build system generation. During build system generation CMake will read those query files and write object model response files for the client to read. Previously the CMake Tools extension only supported cmake-server mode, which was deprecated with CMake version 3.15. File-based API provides a faster and more streamlined way for the extension to populate the editor with information specific to your project structure because it is reading response files instead of running CMake in long-running server mode.

The latest release of the CMake Tools extension supports file-based API. The setting CMake: CMake Communication Mode has been added with the following possible values. The default value is automatic.

• automatic: uses file-api if CMake version is >= 3.14 and falls back to cmake-server if CMake version is < 3.14
• fileApi
• serverApi
• legacy: use only with old CMake versions <= 3.7. Functionality will be reduced

Feedback is welcome

Download the CMake Tools extension for Visual Studio Code today and give it a try. If you run into issues or have suggestions for the team, please report them in the issues section of the extension’s GitHub repository. You can also reach the team via email (visualcpp@microsoft.com) and Twitter (@VisualC).

Erika Sweet Senior Product Manager, C++ Team

Follow