Easier debugging when using cmake commands generated by mrdocs

[anarthal]

I've had a hard time figuring out what was going wrong in #761, in part because CMake generated files seem to be deleted as soon as mrdocs return. When things go wrong, it's very difficult to find out what happened.

In particular, I had to invent an ugly workaround to copy compile_commands.json to a location where mrdocs wouldn't delete it.

I think mrdocs shouldn't be trying to hide CMake generated files. They are a valuable tool when things go wrong (e.g. imagine a non-Boost user submitting a bug report).

[alandefreitas]

I think mrdocs shouldn't be trying to hide CMake generated files

Yes. We could leave it there when the process fails. We must remove it when it succeeds because no one wants those temp files in the output directory.

[anarthal]

Note that configuring cmake for the first time takes non-trivial amount of time, in the order of several seconds for Boost libs depending on Asio. Would not deleting temp files provide an improve in performance for rebuilds? Rebuilds being slow is one of my main pains with quickbook, and I think antora+mrdocs are in the same order of magnitude.

I don't know if this is fact is relevant or not - keeping the cache might involve other problems.

[alandefreitas]

Would not deleting temp files provide an improve in performance for rebuilds?

Mmmm... That's a different issue. There are implications in terms of performance and correctness.

In terms of correctness, the command in mrdocs.yml is valid when it works for the first time. Because reusing the cache in CMake is not reproducible, CMake doesn't guarantee it will even attempt to have the same results. So there's this problem: people often want to clear their caches when trying something new to ensure the command works when being run for the first time.

In terms of performance, MrDocs assumes the command in mrdocs.yml will usually work once it's set up, so I think that's the answer in that regard.

There's also a matter of correctness and separation of concerns when not using CMake directly. One thing is CMake expecting the user to remove ./build for a complete rebuild. Another thing is expecting the user to remove a temporary MrDocs directory they shouldn't even know exists.