[libc-commits] [libc] 0ca779f - [libc][docs] Update website to reflect new strategy (#168637)

[via libc-commits]

Author: Michael Jones
Date: 2025-12-19T22:12:31Z
New Revision: 0ca779fae7b51c054956aca389722d4d73a46af1

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

LOG: [libc][docs] Update website to reflect new strategy (#168637)

The LLVM-libc goals are updated to better reflect the strategy shared
at the LLVM dev meeting 2025.

Added: 
    libc/docs/hand_in_hand.rst

Modified: 
    libc/docs/index.rst

Removed: 
    


################################################################################
diff  --git a/libc/docs/hand_in_hand.rst b/libc/docs/hand_in_hand.rst
new file mode 100644
index 0000000000000..81e6bdafc3b7e
--- /dev/null
+++ b/libc/docs/hand_in_hand.rst
@@ -0,0 +1,41 @@
+.. _hand_in_hand:
+
+============
+Hand-in-Hand
+============
+
+Hand-in-Hand is the name of the mechanism that allows other LLVM projects to use
+LLVM-libc's internal C++ APIs instead of calling the public libc interface.
+This is useful for cases where the C interface doesn't match the desired
+interface.
+
+The original use case for the Hand-in-Hand interface was to let libc++ use
+LLVM-libc's string to float conversion internals. The libc interface (strtof)
+takes a null terminated string with no maximum length while the libc++ interface
+(from_chars<float>) takes a string with a start and an end. If libc++ had used
+the public interface it would have had to allocate a new null terminated string
+before calling strtof, but with Hand-in-Hand libc++ handles its own parsing
+and then passes the parsed information to LLVM-libc's conversion code. This is
+better for performance and cuts down on code duplication in the LLVM repository.
+
+Hand-in-Hand works by LLVM-libc exposing a set of headers in the /libc/shared/
+directory. These headers make the interface more explicit and easier to
+maintain. The client library includes the shared headers by depending on the
+llvm-libc-common-utilities target which sets up the necessary includes and
+defines. The client library then includes "shared/<header>" to get the necessary
+components. All of the functions shared via Hand-in-Hand are header only.
+
+The Hand-in-Hand interface is intended to be an internal implementation detail,
+and is has no guarantees of stability. When the internal LLVM-libc interface is
+changed the other users inside of the LLVM repository are updated in the same
+commit. This allows LLVM-libc to update their interface without breaking their
+users.
+
+Current Hand-in-Hand users:
+Libc++ uses it for from_chars<float/double>
+OpenMP uses it for printf on GPUs
+[WIP] clang uses it for APFloat functions.
+
+For more information check out the 2024 talk about the original Project:
+  * `slides <https://llvm.org/devmtg/2024-10/slides/techtalk/Jones-DiBella-hand-in-hand.pdf>`__
+  * `video <https://www.youtube.com/watch?v=VAEO86YtTHA>`__

diff  --git a/libc/docs/index.rst b/libc/docs/index.rst
index 7238d1383511e..f640d994e47f4 100644
--- a/libc/docs/index.rst
+++ b/libc/docs/index.rst
@@ -2,12 +2,6 @@
 The LLVM C Library
 ==================
 
-.. warning::
-  LLVM-libc is not yet ABI stable; currently only static linking is supported.
-  LLVM-libc developers retain the right to modify the ABI of types used
-  throughout the library. Another libc should be preferred if ABI stability is
-  a requirement.
-
 .. note::
   LLVM-libc is not fully complete right now. Some programs may fail to build due
   to missing functions. If you would like to help us finish LLVM-libc, check
@@ -18,24 +12,27 @@ The LLVM C Library
 Introduction
 ============
 
-LLVM-libc aspires to a unique place in the software ecosystem.  The goals are:
-
-- Fully compliant with current C23 and POSIX.1-2024 standards.
-- Easily decomposed and embedded: Supplement or replace system C library
-  functionality easily.  This is useful to get consistent math precision across
-  systems, or updated memory operations for newer microarchitectures.  These
-  pieces will work on Linux, MacOS, Windows, and Fuchsia.
-- The creation of fully static binaries without license implications.
-- Increase whole program optimization opportunities for static binaries through
-  ability to inline math and memory operations.
-- Reduce coding errors by coding in modern C++ through the use of lightweight
-  containers during coding that can be optimized away at runtime.
-- Permit fuzzing and sanitizer instrumentation of user binaries including the
-  libc functions.
-- A complete testsuite that tests both the public interface and internal
-  algorithms.
-- `Fuzzing <https://github.com/llvm/llvm-project/tree/main/libc/fuzzing>`__
+LLVM-libc is an implementation of the C standard library written in C++ focused
+on embodying three main principles:
+
+- Modular
+- Multiplatform
+- Community Oriented
+
+Our current goal is to support users who want to make libc part of their
+application. This can be through static linking libc into the application, which
+is common for containerized servers or embedded devices. It can also be through
+using the LLVM-libc internal sources as a library, such as through the
+:ref:`Hand-in-Hand interface<hand_in_hand>`.
+
+For more details please watch the talk "`Climbing the ladder of Complete <https://www.youtube.com/watch?v=HtCMCL13Grg>`__ by Michael Jones.".
 
+LLVM-libc is currently used in Google servers, Pixel Buds, and other Google
+projects. Through Project Hand-in-Hand LLVM-libc's code is used in other LLVM
+projects, specifically libc++ and the offloading runtime. There is an
+experiemental config to use LLVM-libc in Emscripten and the ARM embedded
+toolchain. Pieces of LLVM-libc are being used in Bionic (Android's libc) and
+Fuchsia.
 
 .. toctree::
    :hidden:
@@ -65,6 +62,7 @@ LLVM-libc aspires to a unique place in the software ecosystem.  The goals are:
    gpu/index.rst
    uefi/index.rst
    configure
+   hand_in_hand
 
 .. toctree::
    :hidden: