My least favorite part is how completely impossible it is to discover all the implicit variables set by other cmake files, and there's no common convention, so some libraries are like ${ZLIB_INCLUDE_DIR} and some are #{zLib_INCLUDE_DIRS} and you have to just manually try a bunch of combinations to finally find what works because the scripts themselves use weird string based metaprogramming to build the variables themselves.

On top of that I found the documentation and the book terrible. I thought it might be easier to understand what it does by reading the source code (didn't try yet)

The documentation is "complete" in the way that some manpages are - the biggest problem with it is the lack of best practices guidance. About books, I believe that good ones exist now. The official CMake book is not among the good ones - last time I checked, it was ridiculously outdated (and IMO not even very good at the time it was written).

I have extracted some knowledge from the source code. It's more underdesigned than overdesigned and I think that's the better side to err on. Kinda awkward but you can figure it out.

Which cmake book is good?

Professional cmake seems to be the one recommended now. The author updates it regularly.

which competitors?

any thoughts on why are build tools so hard to get right?

Build2 is one that a coworker of mine likes. There are others.

What makes it hard is the problem is a lot deeper than most people realize, so most attempts are not powerful enough to be useful. They are clean until someone points out one of the many edge cases that were not thought of, and by the time you support even a few of them your clean design is a mess of uglyness.

Making it worse build systems are an afterthought to most develpers so you end up with a mess just because the programers are not taking care to write good clean code in the build system.