[libc++] Document how to build and run clang-tidy checks

[philnik]

Summary

Getting clang-tidy to work can be a little bit more involved than most test utilies. This documents what is required to get clang-tidy working with system packages to make it a bit easier.

[Mordante]

Thanks for working on this. LGTM, but I think a native speaker may want to have a pass over the text too.

libcxx/docs/TestingLibcxx.rst

129–130

I think the other part doesn't add much info.

132

Note it seems this gives issues on Debian, the first run works, then trying to run CMake again will try write things in
/usr/lib/llvm-16/include/c++/v1/__config_site.tmp, which for good reasons is not allowed.

Have you seen this before? If not I can file a bug report.

[philnik]

libcxx/docs/TestingLibcxx.rst

132

I've had similar problems, but I thought it was a problem with my setup. Given that you also have this problem, I'd say, file a bug report.

[philnik]

Address comments

libcxx/docs/TestingLibcxx.rst

 Take note that some CI jobs are testing the library on specific platforms and are *not* run
 in our Docker image. In the general case, it is not possible to reproduce these failures
 locally, unless they aren't specific to the platform.
 
 Also note that the Docker container shares the same filesystem as your local machine, so
 modifying files on your local machine will also modify what the Docker container sees.
 This is useful for editing source files as you're testing your code in the Docker container.
 
+Enabling clang-tidy checks
+--------------------------
+
+We have libc++-specific clang-tidy checks, which have to be compiled before running
+clang-tidy. Because of that, there are some additional requirements.
+
+To compile clang-tidy checks, `-DLIBCXX_ENABLE_CLANG_TIDY=On` has to be passed to the
+CMake invocation used to compile libc++. For the CMake invocation and compiling libc++
+to succeed, the clang-tidy headers and binaries have to be available on the system.
+Here is an overview, which packages are required on a given system:
+
+============ ================================
+platform     required packages
+============ ================================
+Debian-based clang-tidy llvm-dev libclang-dev
+============ ================================
+
+With the listed packages installed, the clang-tidy checks should compile and the
+clang-tidy checks will get executed when running the libc++ tests.
+
 Writing Tests
 =============
 
 When writing tests for the libc++ test suite, you should follow a few guidelines.
 This will ensure that your tests can run on a wide variety of hardware and under
 a wide variety of configurations. We have several unusual configurations such as
 building the tests on one host but running them on a different host, which add a
 few requirements to the test suite. Here's some stuff you should know: