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

Michael Jones via libc-commits libc-commits at lists.llvm.org
Thu Dec 18 14:34:36 PST 2025 

https://github.com/michaelrj-google updated https://github.com/llvm/llvm-project/pull/168637

>From 1f244e495cd19a0ba5d961dccc7f4fa08ed8d63b Mon Sep 17 00:00:00 2001
From: Michael Jones <michaelrj at google.com>
Date: Tue, 4 Nov 2025 17:50:00 +0000
Subject: [PATCH 1/2] [libc][docs] Update website to reflect new strategy

The LLVM-libc goals are updated to better reflect the strategy shared
at the LLVM dev meeting 2025.
---
 libc/docs/hand_in_hand.rst | 17 ++++++++++++++++
 libc/docs/index.rst        | 41 +++++++++++++++++---------------------
 2 files changed, 35 insertions(+), 23 deletions(-)
 create mode 100644 libc/docs/hand_in_hand.rst

diff --git a/libc/docs/hand_in_hand.rst b/libc/docs/hand_in_hand.rst
new file mode 100644
index 0000000000000..e0e05ffef6203
--- /dev/null
+++ b/libc/docs/hand_in_hand.rst
@@ -0,0 +1,17 @@
+.. _hand_in_hand:
+
+============
+Hand-in-Hand
+============
+
+TODO: Docs about hand in hand.
+
+Hand-in-hand is a way for other LLVM projects to use libc's high quality internal APIs.
+
+It's intended to be header only and stable at head, but not necessarily safe for mixing and matching.
+
+Libc++ uses it for from_chars<float>
+OpenMP uses it for printf on GPUs
+WIP to let clang use it for constexpr math.
+
+External projects shouldn't rely on the interface being stable.
diff --git a/libc/docs/index.rst b/libc/docs/index.rst
index 7238d1383511e..f88b64ff18472 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,24 @@ 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>`.
+
 
+TODO: Finish list of where LLVM-libc is used.
+LLVM-libc is currently used in Google servers, Pixel Buds, and other Google
+projects. There is an experiemental config to use LLVM-libc in Emscripten.
+Pieces of LLVM-libc are being used in Bionic (Android's libc) and Fuchsia.
 
 .. toctree::
    :hidden:
@@ -65,6 +59,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:

>From 6bcb5b55b7d45aab681911d652c5639b3508e229 Mon Sep 17 00:00:00 2001
From: Michael Jones <michaelrj at google.com>
Date: Thu, 18 Dec 2025 22:31:13 +0000
Subject: [PATCH 2/2] update and finish the hand-in-hand doc

---
 libc/docs/hand_in_hand.rst | 36 ++++++++++++++++++++++++++++++------
 libc/docs/index.rst        |  9 ++++++---
 2 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/libc/docs/hand_in_hand.rst b/libc/docs/hand_in_hand.rst
index e0e05ffef6203..5b3ee514b20a0 100644
--- a/libc/docs/hand_in_hand.rst
+++ b/libc/docs/hand_in_hand.rst
@@ -4,14 +4,38 @@
 Hand-in-Hand
 ============
 
-TODO: Docs about 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.
 
-Hand-in-hand is a way for other LLVM projects to use libc's high quality internal APIs.
+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.
 
-It's intended to be header only and stable at head, but not necessarily safe for mixing and matching.
+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.
 
-Libc++ uses it for from_chars<float>
+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 to let clang use it for constexpr math.
+[WIP] clang uses it for constexpr math.
 
-External projects shouldn't rely on the interface being stable.
+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 f88b64ff18472..f640d994e47f4 100644
--- a/libc/docs/index.rst
+++ b/libc/docs/index.rst
@@ -25,11 +25,14 @@ 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.".
 
-TODO: Finish list of where LLVM-libc is used.
 LLVM-libc is currently used in Google servers, Pixel Buds, and other Google
-projects. There is an experiemental config to use LLVM-libc in Emscripten.
-Pieces of LLVM-libc are being used in Bionic (Android's libc) and Fuchsia.
+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:

More information about the libc-commits mailing list