[libc-commits] [libc] [llvm] [RFC][libc] Codify header inclusion policy (PR #87017)

[via libc-commits]

================
@@ -186,3 +186,30 @@ We expect contributions to be free of warnings from the `minimum supported
 compiler versions`__ (and newer).
 
 .. __: https://libc.llvm.org/compiler_support.html#minimum-supported-versions
+
+Header Inclusion Policy
+=======================
+
+Because llvm-libc supports
+`Overlay Mode <https://libc.llvm.org/overlay_mode.html>`__ and
+`Fullbuild Mode <https://libc.llvm.org/fullbuild_mode.html>`__ care must be
+taken when ``#include``'ing certain headers.
+
+The ``include/`` directory contains public facing headers that users must
+consume for fullbuild mode. As such, types defined here will have ABI
+implications as these definitions may differ from the underlying system for
+overlay mode and are NEVER appropriate to include in ``libc/src/`` without
+preprocessor guards for ``LLVM_LIBC_FULL_BUILD``.
+
+Consider the case where an implementation in ``libc/src/`` may wish to refer to
+a ``sigset_t``, what header should be included? ``<signal.h>``, ``<spawn.h>``,
+``<sys/select.h>``?
+
+None of the above. Instead, code under ``src/`` should ``#include
+"src/signal/sigset_t.h"`` which contains preprocessor guards on
----------------
lntue wrote:

We should put all of them in one top-level folder, maybe something like `libc/include_internal` or `libc/headers` / `libc/hdr` (since we already have `src`), that will be included in both tests and srcs, so that we can enforce clang-tidy check that `#include <...>` is only allowed in that folder but not anywhere else.

https://github.com/llvm/llvm-project/pull/87017