[libcxx-commits] [libcxx] 01512d2 - [libc++] Document guidelines for symbols baked into the ABI (#118526)

[via libcxx-commits]

Author: Louis Dionne
Date: 2024-12-10T10:15:13-05:00
New Revision: 01512d29b766c80aa691daabeabc315a172dc747

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

LOG: [libc++] Document guidelines for symbols baked into the ABI (#118526)

Closes #112395

Added: 
    

Modified: 
    libcxx/docs/CodingGuidelines.rst

Removed: 
    


################################################################################
diff  --git a/libcxx/docs/CodingGuidelines.rst b/libcxx/docs/CodingGuidelines.rst
index 4d3dd12e56bf12..1bb62072e886d1 100644
--- a/libcxx/docs/CodingGuidelines.rst
+++ b/libcxx/docs/CodingGuidelines.rst
@@ -168,3 +168,19 @@ have a recommended practice where to put them, so libc++ applies it whenever it
 Applications of ``[[nodiscard]]`` are code like any other code, so we aim to test them on public interfaces. This can be
 done with a ``.verify.cpp`` test. Many examples are available. Just look for tests with the suffix
 ``.nodiscard.verify.cpp``.
+
+Don't use public API names for symbols on the ABI boundary
+==========================================================
+
+Most functions in libc++ are defined in headers either as templates or as ``inline`` functions. However, we sometimes
+need or want to define functions in the built library. Symbols that are declared in the headers and defined in the
+built library become part of the ABI of libc++, which must be preserved for backwards compatibility. This means that
+we can't easily remove or rename such symbols except in special cases.
+
+When adding a symbol to the built library, make sure not to use a public name directly. Instead, define a
+``_LIBCPP_HIDE_FROM_ABI`` function in the headers with the public name and have it call a private function in the built
+library. This approach makes it easier to make changes to libc++ like move something from the built library to the
+headers (which is sometimes required for ``constexpr`` support).
+
+When defining a function at the ABI boundary, it can also be useful to consider which attributes (like ``[[gnu::pure]]``
+and ``[[clang::noescape]]``) can be added to the function to improve the compiler's ability to optimize.