Rename the `__tuple` directory in libc++ headers to `__tuple_dir`
to avoid file collision when installing. Historically, `__tuple` has
been a file and it has been replaced by a directory
in 2d52c6bfae801b016dd3627b8c0e7c4a99405549. Replacing a regular file
with a directory (or more importantly, the other way around when
downgrading) is not universally supported. Since this is an internal
header, its actual name should not matter, so just rename it to avoid
problems.
Differential Revision: https://reviews.llvm.org/D139270
This makes it possible for programmers to run IWYU and get more accurate
standard library inclusions. Prior to this commit, the following program
would be transformed thusly:
```cpp
// Before
#include <algorithm>
#include <vector>
void f() {
auto v = std::vector{0, 1};
std::find(std::ranges::begin(v), std::ranges::end(v), 0);
}
```
```cpp
// After
#include <__algorithm/find.h>
#include <__ranges/access.h>
#include <vector>
...
```
There are two ways to fix this issue: to use [comment pragmas](https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUPragmas.md)
on every private include, or to write a canonical [mapping file](https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUMappings.md)
that provides the tool with a manual on how libc++ is laid out. Due to
the complexity of libc++, this commit opts for the latter, to maximise
correctness and minimise developer burden.
To mimimise developer updates to the file, it makes use of wildcards
that match everything within listed subdirectories. A script has also
been added to ensure that the mapping is always fresh in CI, and makes
the process a single step.
Finally, documentation has been added to inform users that IWYU is
supported, and what they need to do in order to leverage the mapping
file.
Closes#56937.
Differential Revision: https://reviews.llvm.org/D138189
