(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.

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.