February 27th, 2019

Open Existing CMake Caches in Visual Studio

Will Buik
Program Manager

Visual Studio typically manages all the details of CMake for you, under the hood, when you open a project. However, some development workflows require more fine-grained control over how CMake is invoked. The latest Visual Studio 2019 Preview lets you have complete control over CMake if your project needs more flexibility. You can now give your custom or preferred tools complete control of your project’s CMake cache and build tree instead of letting Visual Studio manage it for you.

In Visual Studio 2019 Preview 3, you can open CMake caches by opening a CMakeCache.txt file. This feature may sound familiar if you ever used the previous functionality that would attempt to clone an existing CMake cache. Opening an existing cache is much more powerful; instead of cloning the cache, Visual Studio will operate with the existing cache in place.

When you open an existing cache, Visual Studio will not attempt to manage your cache and build tree for you. Instead, your tools have complete control. This feature supports caches created by any recent version of CMake (3.8 or higher) instead of just the one that ships with Visual Studio.

Why Open a CMake Existing Cache?

When you open a CMake project, Visual Studio manages CMake for you behind the scenes. It will automatically configure the project’s cache and build tree and regenerates the cache when it is out of date due to changes to the project or CMakeSettings. This lets developers get to their code as quickly as possible without needing to worry about the details of CMake itself. Sometimes, however, giving users more control over what CMake is doing makes sense. That is where Open Existing Cache comes in.

Open Existing Cache gives you complete control over how CMake configures your project. This is essential if you use custom build frameworks, meta-build systems, or external tools to drive CMake in your development workflow. For example, if you use a script to set up your project’s environment and build tree, you can now just run that script and open the cache that it generated in Visual Studio. When you open an existing cache, Visual Studio defers to your tooling to manage the cache instead of driving CMake directly.

There are other reasons why you might want to open existing caches as well. For complex projects, the cache might be slow to generate. Now, instead of opening the project and waiting for the cache to configure once again, you can point Visual Studio towards a cache you have already configured. This also can simplify your workflow if you are working with multiple editors or prefer external tools such as CMakeGui to Visual Studio’s CMakeSettings.json to configure your CMake projects.

How Open Existing Cache Works

To get started with an existing cache, first you will need to generate one outside of the IDE. How you do this will depend completely on your development workflow. For example, you might use custom build scripts specific to your project – or a meta-build system that invokes CMake – or maybe external tools such as CMakeGui. If you are interested in trying this out with a sample project, creating a cache with CMakeGui is a good way to get started.

Once you have generated the cache you can open it directly with “File > Open > CMake” by navigating to the CMakeCache.txt file. You will notice that there is no longer a “Import Existing Cache” wizard because the cache is opened directly.

Alternatively, if you have already opened the project in Visual Studio, you can add an existing cache to it the same way you add a new configuration (click “Add Configuration” on the CMakeSettings.json file in the Solution Explorer or right click anywhere in the file’s editor pane):

Once you have done this, the project should behave exactly as if you had opened in Visual Studio and let it manage the cache for you.

Integrating External Build Tools with Visual Studio

You should have full IntelliSense, build, and debug support. One thing you may notice, however, is that cache generation is disabled:

Visual Studio doesn’t know how to generate an external cache because only your tools have the details needed to properly invoke CMake but you can configure Visual Studio to invoke them for you. To streamline your development experience, you can configure an external script from your customized build tooling to run that will generate the CMake cache on the IDE’s behalf.

Open CMakeSettings.json and add a “cacheGenerationCommand” tag. This can be set to any script or executable that generates the CMake cache. For example, to invoke a Python script that takes a single argument of where to place the cache you can do the following:

"cacheGenerationCommand": "bootstrap.py \"${projectDir}\\out\\build\\CustomCache\""

This will be run each time Visual Studio regenerates the external CMake cache. Keep in mind, you will need to ensure that this script either fails with an error code or does in fact generate a cache at “cacheRoot“. Otherwise Visual Studio’s model of your CMake project may become out of date. Visual Studio will also not automatically detect changes to your own build tooling. If you change your build tooling and want to regenerate the cache you will need to do that manually via Project > Generate Cache.

You can also integrate other custom build tasks and scripts by creating tasks.

Configuring External Caches

External caches can be managed in CMakeSettings.json just like any other configuration. When you first open a cache, a CMakeSettings.json file will be generated that looks something like this:

Cache configurations are simple since they mostly defer to other tools to set up the build. The simplest just points to the CMake cache directory with the “cacheRoot” parameter.

You can also mix and match external caches with ones managed by Visual Studio by creating additional configurations.

Remote Caches

You may have noticed that there is also a template to create a configuration for a remote external cache. This allows you to connect to an existing cache on a remote Linux machine. This can be a little trickier to set up than working with one on Windows (we’re still refining this) but it is possible so long as you have the source code on both the local and remote machine.

To open an external cache on a remote machine, first you will need to open the source directory in Visual Studio on the local Windows machine. Next, create a remote external cache configuration from the template and edit the cache with the path of the cache on the remote machine. By default, Visual Studio will not automatically synchronize the source code from local machine to the remote when working with external caches, but you can change this by setting “remoteCopySources” to “true”.

Send Us Feedback

This feature is under active development so please tell us what works well for your projects and what doesn’t. The best way to get in touch with us is to create a feedback or suggestion ticket on Developer Community. Once a ticket is created you can track our progress in fixing the issue. For other feedback or questions feel free to leave a comment or email us at cmake@microsoft.com.

Author

Will Buik
Program Manager

Will is a Program manager on Visual Studio's C++ IDE team. He works on the C++ project system and design-time language features such as IntelliSense.

1 comment

Discussion is closed. Login to edit/delete existing comments.

  • Popov, Roman I

    Nothing happens in my case. When I try to open cache for ninja build it just shows “CMakeLists.txt is still parsing…” forever.
    Is it possible to see some log file to understand what happens inside this parsing CMakeLists?