[libc-commits] [PATCH] D82846: [libc] Add documentation for clang-tidy checks.

[Paula Toth via Phabricator via libc-commits]

PaulkaToast created this revision.
PaulkaToast added a reviewer: sivachandra.
PaulkaToast added a project: libc-project.
Herald added subscribers: libc-commits, ecnelises, tschuett.

Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D82846

Files:
  libc/docs/clang_tidy_checks.rst


Index: libc/docs/clang_tidy_checks.rst
===================================================================
--- /dev/null
+++ libc/docs/clang_tidy_checks.rst
@@ -0,0 +1,87 @@
+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
+---------------------------
+
+An advantage of writing a libc in C++ is the ability to use namespaces in our
+implementation. However, implemented entry points must be included within the
+correct namespace in order to export the C symbols properly. 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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D82846.274351.patch
Type: text/x-patch
Size: 3482 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/libc-commits/attachments/20200630/1d7d452c/attachment-0001.bin>