[libc-commits] [libc] ab25ed2 - [libc] Add documentation for clang-tidy checks.

[Paula Toth via libc-commits]

Author: Paula Toth
Date: 2020-07-06T18:15:35-07:00
New Revision: ab25ed26c67e5d540e6628fa5e5982e7e9b90a38

URL: https://github.com/llvm/llvm-project/commit/ab25ed26c67e5d540e6628fa5e5982e7e9b90a38
DIFF: https://github.com/llvm/llvm-project/commit/ab25ed26c67e5d540e6628fa5e5982e7e9b90a38.diff

LOG: [libc] Add documentation for clang-tidy checks.

Reviewers: sivachandra

Reviewed By: sivachandra

Subscribers: tschuett, ecnelises, libc-commits

Tags: #libc-project

Differential Revision: https://reviews.llvm.org/D82846

Added: 
    libc/docs/clang_tidy_checks.rst

Modified: 
    

Removed: 
    


################################################################################
diff  --git a/libc/docs/clang_tidy_checks.rst b/libc/docs/clang_tidy_checks.rst
new file mode 100644
index 000000000000..ffdc45bdd977
--- /dev/null
+++ b/libc/docs/clang_tidy_checks.rst
@@ -0,0 +1,86 @@
+LLVM libc clang-tidy checks
+===========================
+These are the clang-tidy checks designed to help enforce implementation
+standards.
+The configuration file is ``src/.clang-tidy``.
+
+restrict-system-libc-header
+---------------------------
+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
+---------------------------
+
+It is part of our implementation standards that all implementation pieces live
+under the ``__llvm_libc`` namespace. This prevents polution of the global
+namespace. Without a formal check to ensure this, an implementation might
+compile and pass unit tests, but not produce a usable libc function.
+
+This check that ensures any function call resolves to a function within the
+``__llvm_libc`` namespace.
+
+.. code-block:: c++
+
+    // Correct: implementation inside the correct namespace.
+    namespace __llvm_libc {
+        void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {}
+        // Namespaces within __llvm_libc 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.
+    void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {}
+
+    // Incorrect: outer most namespace is not correct.
+    namespace something_else {
+        void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {}
+    }
+
+
+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
+__llvm_libc namespace.
+
+.. code-block:: c++
+
+    namespace __llvm_libc {
+
+    // Allow calls with the fully qualified name.
+    __llvm_libc::strlen("hello");
+
+    // Allow calls to compiler provided functions.
+    (void)__builtin_abs(-1);
+
+    // Bare calls are allowed as long as they resolve to the correct namespace.
+    strlen("world");
+
+    // Disallow calling into functions in the global namespace.
+    ::strlen("!");
+
+    } // namespace __llvm_libc