Visual Studio 2017 RC is an important release when it comes to its support for CMake. The “Tools for CMake” VS component is now ready for public preview and we’d like to invite all of you to bring your CMake projects into VS and give us feedback on your experience.
For an overview of the general Visual Studio CMake experience, head over to the announcement post for CMake support in Visual Studio that has been updated to include all the capabilities discussed in this post. Additionally, if you’re interested in the “Open Folder” capability for C++ projects that are not using CMake or MSBuild, check out the Open Folder for C++ announcement blog.
The RC release brings support for:
Editing CMake projects
Default CMake configurations. As soon as you open a folder containing a CMake project, Solution Explorer will display the files in that folder and you can open any one of them in the editor. In the background, VS will start indexing the C++ sources in your folder. It will also run CMake.exe to collect more information about your CMake project (CMake cache will be generated in the process). CMake is invoked with a specific set of switches that are defined as part of a default CMake configuration that VS creates under the name “Visual Studio 15 x86”.
CMake configuration switch. You can switch between CMake configurations from the C++ Configuration dropdown in the General tab. If a configuration does not have the needed information for CMake to correctly create its cache, you can further customize it – how to configure CMake is explained later in the post.
Auto-update CMake cache. If you make changes to the CMakeLists.txt files or change the active configuration, the CMake generation step will automatically rerun. You can track its progress in the CMake output pane of the Output Window.
When the generation step completes, the notification bar in editors is dismissed, the Startup Item dropdown will contain the updated list of CMake targets and C++ IntelliSense will incrementally update with the latest changes you made (e.g. adding new files, changing compiler switches, etc.)
Configure CMake projects
Configure CMake via CMakeSettings.json. If your CMake project requires additional settings to configure the CMake cache correctly, you can customize these settings by creating a CMakeSettings.json file in the same folder with the root CMakeLists.txt. In this file you can specify as many CMake configurations as you need – you will be able to switch between them at any time.
You can create the CMakeSettings.json file by selecting the Project>Edit Settings>path-to-CMakeLists (configuration-name) menu entry.
CMakeSettings.json example
{
"configurations": [
{
"name": "my-config",
"generator": "Visual Studio 15 2017",
"buildRoot": "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}",
"cmakeCommandArgs": "",
"variables": [
{
"name": "VARIABLE",
"value": "value"
}
]
}
]
}If you already have CMake.exe working on the command line, creating a new CMake configuration in the CMakeSettings.json should be trivial:
- name: is the configuration name that will show up in the C++ configuration dropdown. This property value can also be used as a macro ${name} to specify other property values e.g. see “buildRoot” definition
- generator: maps to -G switch and specifies the generator to be used. This property can also be used as a macro ${generator} to help specify other property values. VS currently supports the following CMake generators:
- “Visual Studio 14 2015”
- “Visual Studio 14 2015 ARM”
- “Visual Studio 14 2015 Win64”
- “Visual Studio 15 2017”
- “Visual Studio 15 2017 ARM”
- “Visual Studio 15 2017 Win64”
- buildRoot: maps to -DCMAKE_BINARY_DIR switch and specifies where the CMake cache will be created. If the folder does not exist, it will be created
- variables: contains a name+value pair of CMake variables that will get passed as -Dname=value to CMake. If your CMake project build instructions specify adding any variables directly to the CMake cache file, it is recommended that you add them here instead.
- cmakeCommandArgs: specifies any additional switches you want to pass to CMake.exe
CMakeSettings.json file IntelliSense. When you have the JSON editor installed (it comes with the Web Development Workload), JSON intelliSense will assist you while making changes to the CMakeSettings.json file.
Environment variable support and macros. CMakeSettings.json supports consuming environment variables for any of the configuration properties. The syntax to use is ${env.FOO} to expand the environment variable %FOO%.
You also have access to built-in macros inside this file:
- ${workspaceRoot}– provides the full path to the workspace folder
- ${workspaceHash}– hash of workspace location; useful for creating a unique identifier for the current workspace (e.g. to use in folder paths)
- ${projectFile}– the full path for the root CMakeLists.txt
- ${projectDir}– the full path to the folder of the root CMakeLists.txt file
- ${thisFile}– the full path to the CMakeSettings.json file
- ${name}– the name of the configuration
- ${generator}– the name of the CMake generator used in this configuration
Building and debugging CMake projects
Customize build command. By default, VS invokes MSBuild with the following switches: -m -v:minimal. You can customize this command, by changing the “buildCommandArgs” configuration property in CMakeSettings.json
CMakeSettings.json
{
"configurations": [
{
"name": "x86",
"generator": "Visual Studio 15 2017",
"buildRoot": "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}",
"cmakeCommandArgs": "",
"buildCommandArgs": "-m:8 -v:minimal -p:PreferredToolArchitecture=x64"
}
]
}Call to action
Download Visual Studio 2017 RC today and try the “Open Folder” experience for CMake projects. For an overview of the CMake experience, also check out the CMake support in Visual Studio blog post.
If you’re using CMake when developing your C++ projects, we would love to hear from you! Please share your feedback in the comments below or through the “Send Feedback” icon in VS.