CMake support in Visual Studio 2017 – what’s new in the RC.2 update

In case you missed the latest Visual Studio news, there is a new update for Visual Studio 2017 RC available. You can either upgrade your existing installation or, if you’re starting fresh, install it from the Visual Studio 2017 RC download page. This release comes with several enhancements in Visual Studio’s CMake experience that further simplify the development experience of C++ projects authored using CMake.

If you’re just getting started with CMake in Visual Studio, a better resource will be the overview blogpost for CMake suport in Visual Studio that will walk you through the full experience including the latest updates mentioned in this post. Additionally, if you’re interested in the “Open Folder” capability for C++ codebases that are not using CMake or MSBuild, check out the Open Folder for C++ overview blogpost.

This RC update adds support to the following areas:

Opening multiple CMake projects

You can now open folders with an unlimited number of CMake projects. Visual Studio will detect all the “root” CMakeLists.txt files in your workspace and configure them appropriately. CMake operations (configure, build, debug) as well as C++ IntelliSense and browsing are available to all CMake projects in your workspace.

cmake-rc2-multipleroots

When more than one CMake project uses the same CMake configuration name, all of them get configured and built (each in their own independent build root folder) when that particular configuration is selected. You also are able to debug the targets from all of the CMake projects that participate in that CMake configuration.

cmake-rc2-configurationdropdown

cmake-rc2-buildprojects

In case you prefer project isolation, you can still create CMake configurations that are unique to a specific CMakeLists.txt file (via the CMakeSettings.json file). In that case, when the particular configuration is selected, only that CMake project will be available for building and debugging and CMake-based C++ IntelliSense will only be available to its source files.

Editing CMake projects

CMakeLists.txt and *.cmake file syntax colorization. Now, when opening a CMake project file, the editor will provide basic syntax colorization and IntelliSense based on TextMate.

cmake-rc2-syntaxcolorization

Improved display of CMake warnings and errors in Error List and Output Window. CMake errors and warnings are now populated in Error List window and double-clicking on one in either Error List or Output Window will open the CMake file at the appropriate line.

cmake-rc2-errorlist

Configuring CMake

Cancel CMake generation. As soon as you open a folder with a CMake project or operate changes on a CMakeLists.txt file, the configuration step will automatically start. If for any reason, you don’t expect it to succeed yet, you can cancel the operation either from the yellow info-bar in the editor or by right-clicking on the root CMakeLists.txt and selecting the option “Cancel Cache Generation”

cmake-rc2-cancel-editorbar

Default CMake configurations have been updated. By default, VS offers a preset list of CMake configurations that define the set of switches used to run CMake.exe to generate the CMake cache. Starting with this release, these configurations are “x86-Debug”, “x86-Release”, “x64-Debug” and “x64-Release”. Note that if you already created a CMakeSettings.json file, you will be unaffected by this change.

CMake configurations can now specify configuration type (e.g. Debug, Release). As part of a configuration definition inside the CMakeSettings.json, you can specify which configuration type you want the build to be (Debug, MinSizeRel, Release, RelWithDebInfo). This setting is also reflected by C++ IntelliSense.

CMakeSettings.json example:
cmake-rc2-configurationtype

All CMake operations have been centralized under a “CMake” main menu. Now you can easily access the most common CMake operations for all the CMakeLists.txt files in your workspace from a central main menu called “CMake”.

cmake-rc2-cmake-mainmenu

Use “Change CMake Settings” command to create or edit the CMakeSettings.json file. When you invoke “Change CMake Settings” from either the main menu or the context menu for a CMakeLists.txt, the CMakeSettings.json corresponding to the selected CMakeLists.txt will be open in the editor. If this file does not exist yet, it will be created and saved in the same folder with the CMakeLists.txt.

More granular CMake cache operations are now available. Both in the main menu as well as in the CMakeLists.txt context menu, there are several new operations available to interact with the CMake cache:

  • Generate Cache: forces the generate step to rerun even if VS considers the environment up-to-date
  • Clean Cache: deletes the build root folder such that the next configuration runs clean
  • View Cache: opens the CMakeCache.txt file from the build root folder. You can technically edit the file and save, but we recommend using the CMakeSettings.json file to direct changes into the cache (as any changes to CMakeCache.txt are wiped when you clean the cache)
  • Open Cache Folder: Open an Explorer window to the build root folder

Building and debugging CMake targets

Build individual CMake targets. VS now allows you to select which target you want to build in addition to opting for a full build.

cmake-rc2-buildtarget

CMake install. The option to install the final binaries based on the rules described in the CMakeLists.txt files is now available as a separate command.

Debug settings for individual CMake targets. You can now customize the debugger settings for any executable CMake target in your project. When selecting “Debug and Launch Settings” context menu for a specific target, a file launch.vs.json is created that is prepopulated with information about the CMake target you have selected and allows you to specify additional parameters like arguments or debugger type.

cmake-rc2-debugsettings

Launch.vs.json:

{
  "version": "0.2.1",
  "defaults": {},
  "configurations": [
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "tests\\hellotest",
      "name": "tests\\hellotest with args",
      "args": ["argument after argument"]
    }
  ]
}

As soon as you save the launch.vs.json file, an entry is created in the Debug Target dropdown with the new name. By editing the launch.vs.json file, you can create as many debug configurations as you like for any number of CMake targets.

cmake-rc2-debugtarget

What’s next

Download Visual Studio 2017 RC.2 today, try it with your favorite CMake project and then share your experience. We’re interested in hearing both about the good and the bad as well as how you see this experience evolving beyond the upcoming Visual Studio 2017 RTM release.

We hope you enjoy these updates and you’ll keep the feedback coming.