Incompatibility of std libraries

[alandefreitas]

When generating the reference for a library, we often get errors such as the following:

In file included from /usr/lib/gcc/x86_64-linux-gnu/11/include/emmintrin.h:31:
/usr/lib/gcc/x86_64-linux-gnu/11/include/xmmintrin.h:821:1: error: definition of builtin function '_mm_getcsr'
  821 | _mm_getcsr (void)
      | ^
/usr/lib/gcc/x86_64-linux-gnu/11/include/xmmintrin.h:853:1: error: definition of builtin function '_mm_setcsr'
  853 | _mm_setcsr (unsigned int __I)
      | ^
/usr/lib/gcc/x86_64-linux-gnu/11/include/xmmintrin.h:1296:1: error: definition of builtin function '_mm_sfence'
 1296 | _mm_sfence (void)
      | ^
/usr/lib/gcc/x86_64-linux-gnu/11/include/xmmintrin.h:1329:1: error: definition of builtin function '_mm_pause'
 1329 | _mm_pause (void)
      | ^
In file included from /home/ubuntu/tmpAgcCrZ/boost/libs/url/src/authority_view.cpp:16:
In file included from /home/ubuntu/tmpAgcCrZ/boost/libs/url/include/boost/url/rfc/pct_encoded_rule.hpp:16:
In file included from /home/ubuntu/tmpAgcCrZ/boost/libs/url/include/boost/url/grammar/charset.hpp:14:
In file included from /home/ubuntu/tmpAgcCrZ/boost/libs/url/include/boost/url/grammar/detail/charset.hpp:17:
In file included from /usr/lib/gcc/x86_64-linux-gnu/11/include/emmintrin.h:31:
/usr/lib/gcc/x86_64-linux-gnu/11/include/xmmintrin.h:821:1: error: definition of builtin function '_mm_getcsr'
  821 | _mm_getcsr (void)
      | ^
/usr/lib/gcc/x86_64-linux-gnu/11/include/xmmintrin.h:853:1: error: definition of builtin function '_mm_setcsr'
  853 | _mm_setcsr (unsigned int __I)
      | ^
/usr/lib/gcc/x86_64-linux-gnu/11/include/xmmintrin.h:1296:1: error: definition of builtin function '_mm_sfence'
 1296 | _mm_sfence (void)
      | ^
/usr/lib/gcc/x86_64-linux-gnu/11/include/xmmintrin.h:1329:1: error: definition of builtin function '_mm_pause'
 1329 | _mm_pause (void)
      | ^

What's happening here is:

• Locally
  • The developer writes the Antora documentation with a reference generated by the extension
  • The process works fine locally
  • The library is pushed to a repository, which triggers CI to build the docs
• Remotely
  • The Antora extension calls MrDocs
  • MrDocs parses the compile_commands.json and injects the include paths for the std library in MrDocsCompilationDatabase
  • The system std library of the container is incompatible with the clang version used by MrDocs

The problem is easy to explain but hard to solve because the developer doesn't always control the container that will generate the documentation. In particular, in the case of Boost libraries:

• The system std library in the Boost release tools container must always be compatible with the MrDocs clang compiler.
  This is rarely the case for an individual library because it is a weird combination of the compiler (almost the latest clang) and standard library (currently, whatever comes by default with Ubuntu 20.04's build-essentials). Note we're at Ubuntu 24 now.
• It's even less likely to work for all libraries if hundreds of libraries adopt the Antora + MrDocs workflow.

One solution is bundling the libcxx headers from the llvm-project with MrDocs and always using that instead of our existing process of finding the system std library. Making this relationship stable makes things easier:

• Although this doesn't ensure the developer will have tested that compiler + std library combination, it makes the combination stable: the MrDocs compiler will always use that std library so developer can test the combination that will be ultimately used.
• This means developers can ensure MrDocs won't fail by testing it in CI because it's also the standard library that will be used in whatever container.
• Note that we only need the headers for that. MrDocs doesn't need to linking step to work because it's not generating an executable.