f0b58c16e1
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
117 lines
4.1 KiB
ReStructuredText
117 lines
4.1 KiB
ReStructuredText
.. _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 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.
|