[all-commits] [llvm/llvm-project] ab4664: [libcxx] adds an include-what-you-use (IWYU) mappi...

[Christopher Di Bella via All-commits]

  Branch: refs/heads/main
  Home:   https://github.com/llvm/llvm-project
  Commit: ab46648082814c41f84b77a08a86403fa202f4e8
      https://github.com/llvm/llvm-project/commit/ab46648082814c41f84b77a08a86403fa202f4e8
  Author: Christopher Di Bella <cjdb at google.com>
  Date:   2022-11-22 (Tue, 22 Nov 2022)

  Changed paths:
    M libcxx/docs/UsingLibcxx.rst
    M libcxx/include/CMakeLists.txt
    A libcxx/include/libcxx.imp
    M libcxx/test/libcxx/lint/lint_headers.sh.py
    M libcxx/utils/CMakeLists.txt
    M libcxx/utils/generate_header_tests.py
    A libcxx/utils/generate_iwyu_mapping.py

  Log Message:
  -----------
  [libcxx] adds an include-what-you-use (IWYU) mapping file

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