This is more or less a continuation of my old discussions thread.

This is the phrase from the manual that I keep coming back to that in my opinion is way too vague:

Further, it can’t detect changes in #defines in the source code because of how preprocessing works in combination with precompiled headers.

Both someone on the LLVM Discourse and I tried to reproduce the problem explained by that phrase and couldn't, even if it looks like I could in 2024.

Can we please get an example of when this problem would happen, and some better docs on either how to avoid this, or if it's unavoidable?
To me right now it sounds like ccache isn't usable at all with PCHs, because defines are not something most project can get rid of entirely, but maybe that's not the case?

Also, you might get into trouble if header files use #pragma once instead of include guards.

For this phrase I could find the original issue where something didn't work, so that's much better, but I still didn't understand from the discussion why the problem was happening.
Is there any way for ccache to warn when such possibly "troublesome" code is found? Or at least for the docs to explain why it is a problem.