[libcxx-commits] [PATCH] D138189: [libcxx] adds an include-what-you-use (IWYU) mapping file

[Christopher Di Bella via Phabricator via libcxx-commits]

cjdb created this revision.
Herald added a subscriber: arichardson.
Herald added a project: All.
cjdb requested review of this revision.
Herald added a project: libc++.
Herald added a subscriber: libcxx-commits.
Herald added a reviewer: libc++.

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.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D138189

Files:
  libcxx/docs/UsingLibcxx.rst
  libcxx/include/libcxx.imp
  libcxx/utils/CMakeLists.txt
  libcxx/utils/generate_iwyu_mapping.py

-------------- next part --------------
A non-text attachment was scrubbed...
Name: D138189.476029.patch
Type: text/x-patch
Size: 8057 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/libcxx-commits/attachments/20221117/420beb5d/attachment.bin>