[libc-commits] [clang-tools-extra] [libc] [libc][docs][NFC] Remove dead files and consolidate check.rst (PR #194442)

[Jeff Bailey via libc-commits]

================
@@ -289,3 +289,123 @@ Example usage:
 Having hidden visibility on the namespace ensures extern declarations in a given TU
 have known visibility and never generate GOT indirections. The attribute guarantees
 this independently of global compile options and build systems.
+
+.. _clang_tidy_checks:
+
+Static Analysis & Clang-Tidy
+=============================
+
+Configuration
+-------------
+
+LLVM libc uses layered ``.clang-tidy`` configuration files:
+
+- ``libc/.clang-tidy``: baseline checks for the ``libc`` subtree (currently
+  focuses on identifier naming conventions).
+- ``libc/src/.clang-tidy``: adds LLVM-libc-specific checks (``llvmlibc-*``) for
+  implementation code under ``libc/src`` and also enables
+  ``readability-identifier-naming`` and ``llvm-header-guard``. Diagnostics from
+  ``llvmlibc-*`` checks are treated as errors.
+
+LLVM-libc checks
+----------------
+
+restrict-system-libc-headers
+----------------------------
+Check name: ``llvmlibc-restrict-system-libc-headers``.
+
+One of libc-project's design goals is to use kernel headers and compiler
+provided headers to prevent code duplication on a per platform basis. This
+presents a problem when writing implementations since system libc headers are
+easy to include accidentally and we can't just use the ``-nostdinc`` flag.
+Improperly included system headers can introduce runtime errors because the C
+standard outlines function prototypes and behaviors but doesn't define
+underlying implementation details such as the layout of a struct.
+
+This check prevents accidental inclusion of system libc headers when writing a
+libc implementation.
+
+.. code-block:: c++
+
+   #include <stdio.h>            // Not allowed because it is part of system libc.
+   #include <stddef.h>           // Allowed because it is provided by the compiler.
+   #include "internal/stdio.h"   // Allowed because it is NOT part of system libc.
+
+implementation-in-namespace
+---------------------------
+Check name: ``llvmlibc-implementation-in-namespace``.
+
+All LLVM-libc implementation constructs must be enclosed in the
+``LIBC_NAMESPACE_DECL`` namespace. See :ref:`code_style` for the full technical
+rationale and macro definitions.
+
+This check ensures that top-level declarations in a translation unit are
+enclosed within the ``LIBC_NAMESPACE_DECL`` namespace.
+
+.. code-block:: c++
+
+    // Correct: implementation inside the correct namespace.
+    namespace LIBC_NAMESPACE_DECL {
+        LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {}
+        // Namespaces within LIBC_NAMESPACE namespace are allowed.
+        namespace inner{
+            int localVar = 0;
+        }
+        // Functions with C linkage are allowed.
+        extern "C" void str_fuzz(){}
+    }
+
+    // Incorrect: implementation not in a namespace.
+    LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {}
+
+    // Incorrect: outer most namespace is not correct.
+    namespace something_else {
+        LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {}
+    }
+
+callee-namespace
+----------------
+Check name: ``llvmlibc-callee-namespace``.
+
+LLVM-libc is distinct because it is designed to maintain interoperability with
+other libc libraries, including the one that lives on the system. This feature
+creates some uncertainty about which library a call resolves to especially when
+a public header with non-namespaced functions like ``string.h`` is included.
+
+This check ensures any function call resolves to a function within the
+LIBC_NAMESPACE namespace.
+
+There are exceptions for the following functions:
+``__errno_location`` so that ``errno`` can be set;
+``malloc``, ``calloc``, ``realloc``, ``aligned_alloc``, and ``free`` since they
+are always external and can be intercepted.
+
+.. code-block:: c++
+
+    namespace LIBC_NAMESPACE_DECL {
+
+    // Allow calls with the fully qualified name.
+    LIBC_NAMESPACE::strlen("hello");
----------------
kaladron wrote:

If we want to match glibc's behaviour where a user binary can provide its own malloc, we might want to be explicit here that memory allocation functions MUST be called by the public libc function, and the rest MUST NOT?

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