Explore mrdocs as compiler mode #1073
Description
Peter Dimov suggested this idea that we treat mrdocs like a compiler and emit "object" files that are later also "linked" with mrdocs to produce the reference.
The goal is to make it easy to integrate, as it would provide an alternative to compiling commands.json. Instead, CMake will invoke mrdocs as if it were clang, with identical command-line options.
Clang already does something similar to that with
clang++ -std=c++20 -fsyntax-only -Xclang -ast-dump=json main.cpp
IIRC, clang-doc operates like a compiler, although I've never seen people pass it to CMake as if it were a compiler.
That gives you the AST in JSON. However,
- This AST would still need to be flattened into the corpus,
- We would still need a "linker" to merge these flat ASTs,
- the mrdocs post-processing steps (like identifying SFINAE, etc) are also still not here, and
- The handlebars generators would need to use this JSON as input in a post-processing step.
We should discuss many open questions here:
- The exact specification of this feature
- Who's going to work on that, when, and what are the intermediary steps or the subissues
- Whether this is intended as another operation mode or a replacement for all operation modes
- Whether these (the compiler and the linker) would be different binaries, as this could make it easier to trick CMake. IIRC, emscripten uses this strategy.
- How do config files work in this context, or what is the best way to pass options to mrdocs and it's being invoked by cmake
Reflection would also help implement this feature, as it simplifies the implementation of serialization algorithms. Mrdocs-as-compiler requires us to bring back the code that transforms the metadata into a binary serialized file and vice versa.