CMake caches several information in the file CMakeCache.txt. This are e.g. directories where specific package have been found and definitions passed using -D.
A few examples when you want to use --cmake-clean-cache:
- a previously found package should be searched again since you want it to be found/used from a different location
- you have passed a definition before which you don't want to be set anymore moving forward
CMake automatically runs the configure step when any included CMake file has changed. But sometimes your logic depends on additional/external state/files and you need CMake to run the configure step again. (There are ways to tell CMake that changing a specific non-CMake file should trigger a reconfigure.) So if you need the configure step to run again but CMake doesn't do it automatically you can either touch and included CMake file or just pass --cmake-force-configure.
A case where you might want to invoke make clean is to recheck if you code has any compiler warnings. Once a source file has been compiled it commonly isn't being recompiled until it (or any included headers)) changed. On that first build you might see a compiler warning but on consecutive builds (assuming the files haven't changes) you wouldn't see the compiler warning again. Passing --cmake-clean-first is a good way to ensure all files are being recompiled.
Sometimes the build directory contains additional state from previous builds which might affect following builds (e.g. an earlier version of the package created some files in the build directory). Those wouldn't be cleaned up and could affect following builds even after the logic creating them has been removed. So this would be a case where deleting the whole build directory would help.
Another case I would recommend deleting the build directory is when you run into problem you don't understand. It is also to reproduce a problem using a fresh build before reporting it in a ticket. Starting with a fresh build might resolve whatever awkward state has built up over time / based on what was done in the past.
If you do have ccache setup a full rebuild isn't that costly since a lot of the build artifacts have been cached before so it usually won't take the full amount of time for a fresh build.
Originally posted by Dirk Thomas with karma: 16276 on 2019-09-27
This answer was ACCEPTED on the original site
Post score: 5
Original comments
Comment by DanRose on 2019-09-27:
Wow! Thank you, Dirk. This is one of the most clarifying and actionable explanations I've ever gotten about anything!