[libc-commits] [libc] f0b58c1 - [libc][docs][NFC] Expand entrypoints technical reference (#4) (#188255)
via libc-commits
libc-commits at lists.llvm.org
Wed Mar 25 00:05:57 PDT 2026
Author: Jeff Bailey
Date: 2026-03-25T07:05:52Z
New Revision: f0b58c16e10c401bb772db55f3ef8a9803afef65
URL: https://github.com/llvm/llvm-project/commit/f0b58c16e10c401bb772db55f3ef8a9803afef65
DIFF: https://github.com/llvm/llvm-project/commit/f0b58c16e10c401bb772db55f3ef8a9803afef65.diff
LOG: [libc][docs][NFC] Expand entrypoints technical reference (#4) (#188255)
Expanded entrypoints.rst with details about definitions, registration
rules, and the lifecycle of an entrypoint.
Updated multiple documents to remove redundant technical details and
link to the centralized entrypoints reference:
- libc/docs/dev/cmake_build_rules.rst
- libc/docs/dev/implementation_standard.rst
- libc/docs/porting.rst
- libc/docs/dev/source_tree_layout.rst
Added:
Modified:
libc/docs/dev/cmake_build_rules.rst
libc/docs/dev/entrypoints.rst
libc/docs/dev/fuzzing.rst
libc/docs/dev/implementation_standard.rst
libc/docs/dev/source_tree_layout.rst
libc/docs/dev/undefined_behavior.rst
libc/docs/porting.rst
Removed:
################################################################################
diff --git a/libc/docs/dev/cmake_build_rules.rst b/libc/docs/dev/cmake_build_rules.rst
index 2248ff40da237..a47fbf0dc12a8 100644
--- a/libc/docs/dev/cmake_build_rules.rst
+++ b/libc/docs/dev/cmake_build_rules.rst
@@ -12,20 +12,17 @@ task.
Targets for entrypoints
-----------------------
-Every entrypoint in LLVM-libc has its own build target. This target is listed
-using the ``add_entrypoint_object`` rule. This rule generates a single object
-file containing the implementation of the entrypoint.
+Every entrypoint in LLVM-libc has its own build target, listed using the
+``add_entrypoint_object`` rule. This rule generates a single object file
+containing the implementation.
-Targets for redirecting entrypoints are also listed using the
-``add_entrypoint_object`` rule. However, one will have to additionally specify
-the ``REDIRECTED`` option with the rule.
+For more technical details on how to register entrypoints, see the
+:ref:`entrypoints` documentation.
Targets for entrypoint libraries
--------------------------------
Standards like POSIX require that a libc provide certain library files like
``libc.a``, ``libm.a``, etc. The targets for such library files are listed in
-the ``lib`` directory as ``add_entrypoint_library`` targets. An
-``add_entrypoint_library`` target takes a list of ``add_entrypoint_object``
-targets and produces a static library containing the object files corresponding
-to the ``add_entrypoint_targets``.
+the ``lib`` directory as ``add_entrypoint_library`` targets.
+
diff --git a/libc/docs/dev/entrypoints.rst b/libc/docs/dev/entrypoints.rst
index 3c24a922a2947..7933d9bc51c42 100644
--- a/libc/docs/dev/entrypoints.rst
+++ b/libc/docs/dev/entrypoints.rst
@@ -1,8 +1,116 @@
.. _entrypoints:
+========================
Entrypoints in LLVM libc
-------------------------
+========================
A public function or a global variable provided by LLVM-libc is called an
-entrypoint. The notion of entrypoints is ingrained in LLVM-libc's
-source layout, build system and source code.
+*entrypoint*. The notion of entrypoints is central to LLVM-libc's source layout,
+build system, and configuration management. This document provides a technical
+reference for how entrypoints are defined, implemented, and integrated into
+the final library.
+
+What is an Entrypoint?
+----------------------
+
+In a typical C library, all functions are part of a monolithic archive. In
+LLVM-libc, each function (e.g., ``malloc``, ``printf``, ``isalpha``) is treated
+as a discrete "entrypoint" unit. This allows for:
+
+- **Granular build targets**: You can build just the objects you need.
+- **Configuration-driven selection**: Different operating systems and
+ architectures can pick specific implementations for the same function.
+- **Support for multiple build modes**: Selectively replacing parts of a host's
+ libc in :ref:`overlay_mode` or building a complete library in :ref:`full_host_build`.
+
+The Lifecycle of an Entrypoint
+------------------------------
+
+1. **Implementation**: The function is implemented in a ``.cpp`` file using
+ LLVM-libc's coding and implementation standards.
+2. **Registration**: The entrypoint is defined as a CMake target using the
+ ``add_entrypoint_object`` rule.
+3. **Configuration**: The target name is added to an ``entrypoints.txt`` file
+ to include it in a specific OS/Architecture configuration.
+
+Implementation Standards
+------------------------
+
+Implementations live in the ``src/`` directory, organized by the public header
+they belong to (e.g., ``src/ctype/isalpha.cpp`` for ``ctype.h``).
+
+Header File Structure
+^^^^^^^^^^^^^^^^^^^^^
+
+Every entrypoint has an internal implementation header file (e.g.,
+``src/ctype/isalpha.h``). This header declares the function within the
+``LIBC_NAMESPACE_DECL`` namespace::
+
+ namespace LIBC_NAMESPACE_DECL {
+ int isalpha(int c);
+ } // namespace LIBC_NAMESPACE_DECL
+
+Source File Structure
+^^^^^^^^^^^^^^^^^^^^^
+
+The implementation file (e.g., ``src/ctype/isalpha.cpp``) defines the function
+using the ``LLVM_LIBC_FUNCTION`` macro. This macro handles C-linkage and
+aliasing::
+
+ namespace LIBC_NAMESPACE_DECL {
+ LLVM_LIBC_FUNCTION(int, isalpha, (int c)) {
+ // ... implementation ...
+ }
+ } // namespace LIBC_NAMESPACE_DECL
+
+For more details on implementation conventions, see the
+:ref:`implementation_standard` page.
+
+Registration: CMake Rules
+-------------------------
+
+Entrypoints are registered as CMake targets to make them available to the
+build system. These rules are usually defined in the ``CMakeLists.txt`` file
+within the function's source directory.
+
+``add_entrypoint_object``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This rule generates a single object file containing the implementation of the
+entrypoint.
+
+.. code-block:: cmake
+
+ add_entrypoint_object(
+ isalpha
+ SRCS isalpha.cpp
+ HDRS isalpha.h
+ DEPENDS
+ .some_internal_dependency
+ )
+
+For redirecting entrypoints (e.g., when one function is a simple alias for
+another), the ``REDIRECTED`` option can be specified to the rule.
+
+``add_entrypoint_library``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Standard library files like ``libc.a`` and ``libm.a`` are produced by
+aggregating multiple entrypoint objects. The ``add_entrypoint_library`` target
+takes a list of ``add_entrypoint_object`` targets and produces a static library.
+
+Configuration: ``entrypoints.txt``
+----------------------------------
+
+The final selection of which entrypoints are included in a specific build is
+determined by ``entrypoints.txt`` files located in the ``libc/config`` tree.
+
+- **Location**: Typically found in ``libc/config/<os>/entrypoints.txt`` or
+ ``libc/config/<os>/<arch>/entrypoints.txt``.
+- **Role**: This file acts as the "source of truth" for what is supported on a
+ given platform. A typical bring-up procedure involves progressively adding
+ targets to this file as they are implemented and tested.
+
+If you are implementing a new entrypoint, you must add its target name to the
+relevant ``entrypoints.txt`` files for it to be included in the library build.
+For more details on platform configuration, see the :ref:`porting` guide.
diff --git a/libc/docs/dev/fuzzing.rst b/libc/docs/dev/fuzzing.rst
index 5cca67826f150..926704cd6984a 100644
--- a/libc/docs/dev/fuzzing.rst
+++ b/libc/docs/dev/fuzzing.rst
@@ -1,3 +1,5 @@
+.. _fuzzing:
+
Fuzzing for LLVM-libc functions
===============================
diff --git a/libc/docs/dev/implementation_standard.rst b/libc/docs/dev/implementation_standard.rst
index d06a997a35328..a334cf1a11b3a 100644
--- a/libc/docs/dev/implementation_standard.rst
+++ b/libc/docs/dev/implementation_standard.rst
@@ -1,13 +1,16 @@
+.. _implementation_standard:
+
Convention for implementing entrypoints
=======================================
-LLVM-libc entrypoints are defined in the entrypoints document. In this document,
-we explain how the entrypoints are implemented. The source layout document
-explains that, within the high level ``src`` directory, there exists one
-directory for every public header file provided by LLVM-libc. The
-implementations of entrypoints live in the directory for the header they belong
-to. Some entrypoints are platform specific, and so their implementations are in
-a subdirectory with the name of the platform (e.g. ``stdio/linux/remove.cpp``).
+The implementations of LLVM-libc entrypoints live in the ``src/`` directory,
+organized by the public header they belong to. Some entrypoints are platform-
+specific, and so their implementations are in a subdirectory with the name of
+the platform (e.g., ``stdio/linux/remove.cpp``).
+
+For a complete overview of what an entrypoint is and how it is managed in the
+build system, see the :ref:`entrypoints` documentation.
+
Implementation of entrypoints can span multiple ``.cpp`` and ``.h`` files, but
there will be at least one header file with name of the form
diff --git a/libc/docs/dev/source_tree_layout.rst b/libc/docs/dev/source_tree_layout.rst
index 8430a7478cf05..b621b9d5ba88d 100644
--- a/libc/docs/dev/source_tree_layout.rst
+++ b/libc/docs/dev/source_tree_layout.rst
@@ -90,8 +90,9 @@ public libraries ``libc.a``, ``libm.a`` etc.
The ``src`` directory
---------------------
-This directory contains the implementations of the llvm-libc entrypoints. It is
-further organized as follows:
+This directory contains the implementations of the llvm-libc entrypoints. For
+more details on what an entrypoint is and how it is implemented, see the
+:ref:`entrypoints` documentation. It is further organized as follows:
1. There is a top-level CMakeLists.txt file.
2. For every public header file provided by llvm-libc, there exists a
diff --git a/libc/docs/dev/undefined_behavior.rst b/libc/docs/dev/undefined_behavior.rst
index bd1a6fe3ef214..d10aeee323a0b 100644
--- a/libc/docs/dev/undefined_behavior.rst
+++ b/libc/docs/dev/undefined_behavior.rst
@@ -1,3 +1,5 @@
+.. _undefined_behavior:
+
===========================
Defining Undefined Behavior
===========================
diff --git a/libc/docs/porting.rst b/libc/docs/porting.rst
index 976f8e487efbd..98e1da47273e3 100644
--- a/libc/docs/porting.rst
+++ b/libc/docs/porting.rst
@@ -49,29 +49,19 @@ architecture.
The entrypoints.txt file
------------------------
-One of the important pieces of config information is listed in a file named
-``entrypoints.txt``. This file lists the targets for the entrypoints (see
-:ref:`entrypoints`) you want to include in the static archive of the libc (for
-the :ref:`overlay_mode` and/or the :ref:`full_host_build`.) If you are doing an
-architecture specific bring up, then an ``entrypoints.txt`` file should be
-created in the architecture subdirectory for each architecture. Else, having a
-single ``entrypoints.txt`` in the operating system directory is sufficient.
-
-The Linux config has an ``entrypoint.txt`` for each individual target
-architecture separately: `aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_,
-`arm32 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/arm>`_ and
-`x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_. On the
-other hand, the Windows config has a single ``entrypoints.txt``
-`file <https://github.com/llvm/llvm-project/tree/main/libc/config/windows/entrypoints.txt>`_.
-
-A typical bring up procedure will normally bring up a small group of entrypoints
-at a time. The usual practice is to progressively add the targets for those
-entrypoints to the ``entrypoints.txt`` file as they are being brought up. The
-same is the case if one is implementing a new entrypoint - the target for the
-new entrypoint should be added to the relevant ``entrypoints.txt`` file. If
-the implementation of the new entrypoint supports multiple operating systems and
-target architectures, then multiple ``entrypoints.txt`` files will have to be
-updated.
+The ``entrypoints.txt`` file lists the targets for the entrypoints to be
+included in the build for a specific platform. For more technical details on
+what entrypoints are and how they are registered as targets, see the
+:ref:`entrypoints` documentation.
+
+If you are doing an architecture specific bring-up, then an ``entrypoints.txt``
+file should be created in the architecture subdirectory for each architecture.
+Else, having a single ``entrypoints.txt`` in the operating system directory is
+sufficient.
+
+A typical bring-up procedure will normally involve progressively adding targets
+to this file as they are implemented and tested.
+
The headers.txt file
--------------------
More information about the libc-commits
mailing list