[libc-commits] [libc] c1832e9 - [libc][doc] Add macros guidelines

[Guillaume Chatelet via libc-commits]

Author: Guillaume Chatelet
Date: 2023-02-07T09:29:36Z
New Revision: c1832e903e000165a8ca808aa9204220bd22143c

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

LOG: [libc][doc] Add macros guidelines

This is a first follow up on the libc tuning RFC
https://discourse.llvm.org/t/rfc-llvm-libc-tuning/67980

Once we agree on the format. I'll land a couple of patches to match the guidelines.

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

Added: 
    

Modified: 
    libc/docs/code_style.rst

Removed: 
    


################################################################################
diff  --git a/libc/docs/code_style.rst b/libc/docs/code_style.rst
index f7852291c5303..b9c71a62b4565 100644
--- a/libc/docs/code_style.rst
+++ b/libc/docs/code_style.rst
@@ -24,6 +24,27 @@ 
diff erences are as follows:
 #. **Public names** - These are the names as prescribed by the standards and
    will follow the style as prescribed by the standards.
 
+Macro style
+===========
+
+We define two kinds of macros: **code defined** and **build defined** macros.
+
+#. **Build defined** macros are generated by `CMake` or `Bazel` and are passed
+   down to the compiler with the ``-D`` command line flag. They start with the
+   ``LIBC_COPT_`` prefix. They are used to tune the behavior of the libc.
+   They either denote an action or define a constant.
+
+#. **Code defined** macros are defined within the ``src/__support/macros``
+   folder. They all start with the ``LIBC_`` prefix. They are of two kinds
+
+   * **Properties** - Build related properties like used compiler, target
+     architecture or enabled CPU features defined by introspecting compiler
+     defined preprocessor defininitions. e.g., ``LIBC_TARGET_IS_ARM``,
+     ``LIBC_TARGET_HAS_AVX2``, ``LIBC_COMPILER_IS_CLANG``, ...
+   * **Attributes** - Compiler agnostic attributes or functions to handle
+     specific operations. e.g., ``LIBC_INLINE``, ``LIBC_NO_LOOP_UNROLL``,
+     ``LIBC_LIKELY``, ``LIBC_INLINE_ASM``.
+
 Inline functions defined in header files
 ========================================