[libc] Document and have clang-tidy checks for inclusion of our own public headers in sources and tests.

[lntue]

Discussion from #83199 and #83374.

Our public headers in libc/include/llvm-libc-* folders might be included directly in our codes and tests, but since they are copied to the ${install dir}/include folders, we might have a mixture of both #include "include/llvm-libc-*" and #include "llvm-libc-*". #83199 was trying to uniform this inclusion, by adding libc/include to our include dirs, but that broke our downstream users that are not using our cmake build system.

Since many downstream users do not use our cmake build system, and they might only have libc/ in their include dirs, we need to officially document this assumption and add clang-tidy checks to make sure that libc/include folder is not accidentally added to our include dirs.

[llvmbot]

@llvm/issue-subscribers-libc

Author: None (lntue)

Discussion from https://github.com//pull/83199 and https://github.com//pull/83374.

Our public headers in libc/include/llvm-libc-* folders might be included directly in our codes and tests, but since they are copied to the ${install dir}/include folders, we might have a mixture of both #include "include/llvm-libc-*" and #include "llvm-libc-*". #83199 was trying to uniform this inclusion, by adding libc/include to our include dirs, but that broke our downstream users that are not using our cmake build system.

Since many downstream users do not use our cmake build system, and they might only have libc/ in their include dirs, we need to officially document this assumption and add clang-tidy checks to make sure that libc/include folder is not accidentally added to our include dirs.

[frobtech]

To be specific about the policy, how it should be is as follows:

• consistent style in all source and header files that are private to the implementation
  • current style rule for that is #include "foo/bar.h" where foo is relative to <llvm-checkout>/libc. Note that in "slice" checkouts as used in Fuchsia, Pigweed, etc. only this subtree of the llvm checkout exists, and there is no expectation its checkout location starts with libc.
  • implementation files that are using standard public APIs need to use #include <stdio.h> and the like in the standard manner
  • implementation files that use the "non-public" headers that llvm-libc installs, such as llvm-libc-macros/... need to treat those like other implementation headers: #include "include/llvm-libc-macros/..."
• proper usage in installed headers, which is a general correctness principle rather than a style choice
  • when the intent is "standard use of the public API that's exported by <foo.h>", then #include <foo.h>--some public header is a vanilla user of whatever implementation everybody using #include <foo.h> gets. this is only appropriate when using the public API of <foo.h>.
  • when the intent is "use of this particular header file", then #include "relative/path/to/file.h". That is, the path relative to the installed location of the file where #include appears. this ensures that a directory tree of headers can "travel together"--if users do <foo.h> and then foo.h itself does #include "internal/bar.h" then no matter how the user's search path works and however they actually do the #include, then the implementation of foo.h will always get the internal/bar.h that travelled with that foo.h.
  • specifically, this means that #include "llvm-libc-macros/..." is correct in any public header that's at the root of the installed include tree, while #include "..." is correct for one llvm-libc-macros file to include another. But, implementation files must use #include "include/llvm-libc-macros/..." for implementation uses of the same headers.

What this means is that we need clang-tidy checks that understand whether they're looking at an installed header file or not, and apply disjoint rules to the two cases.