What is CMakeCache.txt and why it overrides my var

Question

As I am using cmake after editing CMakeLists.txt some variables wouldn't be loaded. If I had something defined with CACHE STRING it wouldn't let me to change it without forcing it or deleting cache.

So then why we have this CMakeCache.txt file. Is it even needed?

Answer 1

Motivating example

This is basically what https://stackoverflow.com/a/42160304/895245 mentions, but with a more explicit example to make it easier to understand.

Consider this use case:

git clone project
cd project
# Options ddfined with "option(" in CMakeLists.txt.
cmake -DOPT1=ON -DOPT2=OFF -DOPT3=ON .
make
# Create bugs (edit code).
make

Then, a few days later, a new directory is added to the project.

This means CMakeLists.txt was changed with a new add_subdirectory, and so we have to run cmake again to update our make files.

If we didn't have CMakeCache.txt, we would have to remember and type all options again:

git pull
cmake -DOPT1=ON -DOPT2=OFF -DOPT3=ON .
make

But because of the cache, we can do just:

cmake .
make

Answer 2

Yes, it's certainly needed. CMake uses the cache when it's re-running itself during a build because a CMakeList file changed, or when you make rebuild_cache. It also loads the cache at start of a normal configure run.

The standard worflow for using CMake is as follows:

1. Run CMake in an empty binary directory to generate the initial version of the project & cache
2. In CMake GUI or ccmake or similar, inspect the cache variables set up by the initial run and modify them as you see fit.
3. Re-run CMake (or just its Configure step if your UI offers that).
4. Repeat steps 2&3 until you're satisfied with the configuration
5. If you were only running Configure in 3, run Generate

You now have a buildsystem configured according to your taste.

For the above to work, user changes in the cache must take precedence over default cache values specified in CMakeLists.txt. Otherwise, the user changes from point 2 would be lost at next configure, overwritten by the project-specified defaults again.

That's why CMake commands set(var ... CACHE) do not modify the cache variable var if it already exists. Normally, your project should treat setting up the cache as providing user-tweakable defaults.

If you really need to override user choices in your project, you can:

• add FORCE to the set command, or
• use set without CACHE to set non-cache variables. Non-cache variables take precedence over cache variables of the same name.