libc/docs/clang_tidy_checks.rst

   1 LLVM libc clang-tidy checks
   2 ===========================
   3 These are the clang-tidy checks designed to help enforce implementation
   4 standards.
   5 The configuration file is ``src/.clang-tidy``.
   6
   7 restrict-system-libc-header
   8 ---------------------------
   9 One of libc-project’s design goals is to use kernel headers and compiler
  10 provided headers to prevent code duplication on a per platform basis. This
  11 presents a problem when writing implementations since system libc headers are
  12 easy to include accidentally and we can't just use the ``-nostdinc`` flag.
  13 Improperly included system headers can introduce runtime errors because the C
  14 standard outlines function prototypes and behaviors but doesn’t define
  15 underlying implementation details such as the layout of a struct.
  16
  17 This check prevents accidental inclusion of system libc headers when writing a
  18 libc implementation.
  19
  20 .. code-block:: c++
  21
  22    #include <stdio.h>            // Not allowed because it is part of system libc.
  23    #include <stddef.h>           // Allowed because it is provided by the compiler.
  24    #include "internal/stdio.h"   // Allowed because it is NOT part of system libc.
  25
  26
  27 implementation-in-namespace
  28 ---------------------------
  29
  30 It is part of our implementation standards that all implementation pieces live
  31 under the ``__llvm_libc`` namespace. This prevents polution of the global
  32 namespace. Without a formal check to ensure this, an implementation might
  33 compile and pass unit tests, but not produce a usable libc function.
  34
  35 This check that ensures any function call resolves to a function within the
  36 ``__llvm_libc`` namespace.
  37
  38 .. code-block:: c++
  39
  40     // Correct: implementation inside the correct namespace.
  41     namespace __llvm_libc {
  42         void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {}
  43         // Namespaces within __llvm_libc namespace are allowed.
  44         namespace inner{
  45             int localVar = 0;
  46         }
  47         // Functions with C linkage are allowed.
  48         extern "C" void str_fuzz(){}
  49     }
  50
  51     // Incorrect: implementation not in a namespace.
  52     void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {}
  53
  54     // Incorrect: outer most namespace is not correct.
  55     namespace something_else {
  56         void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {}
  57     }
  58
  59
  60 callee-namespace
  61 ----------------
  62 LLVM-libc is distinct because it is designed to maintain interoperability with
  63 other libc libraries, including the one that lives on the system. This feature
  64 creates some uncertainty about which library a call resolves to especially when
  65 a public header with non-namespaced functions like ``string.h`` is included.
  66
  67 This check ensures any function call resolves to a function within the
  68 __llvm_libc namespace.
  69
  70 .. code-block:: c++
  71
  72     namespace __llvm_libc {
  73
  74     // Allow calls with the fully qualified name.
  75     __llvm_libc::strlen("hello");
  76
  77     // Allow calls to compiler provided functions.
  78     (void)__builtin_abs(-1);
  79
  80     // Bare calls are allowed as long as they resolve to the correct namespace.
  81     strlen("world");
  82
  83     // Disallow calling into functions in the global namespace.
  84     ::strlen("!");
  85
  86     } // namespace __llvm_libc