Where Code Goes#
This page explains how to decide where a piece of code belongs: in an
entrypoint, in a helper next to it, in src/__support/, or in shared/. It
also covers which build modes and targets a new function is enabled for.
LLVM-libc Source Tree Layout describes the directories themselves.
Three kinds of code#
It helps to sort code in a libc into three kinds:
OS independent: pure computation with no system interaction, such as the math and string functions.
OS agnostic: standard interfaces whose behavior is the same everywhere but whose implementation needs the system, such as
fopenorassert.OS specific: interfaces that are specific to a platform. This can be a thin interface like a syscall wrapper or a substantial integration like
popen.
The source tree does not separate these three as cleanly as it should, and moving toward that separation is a long-term goal. When adding code, decide which kind it is and keep OS-specific details out of the first two.
Entrypoints do not call entrypoints#
An entrypoint is the definition of one public function. It may contain its whole implementation. As soon as any part of that implementation is needed somewhere else, that part moves into a separate internal header or library.
An entrypoint must not call another entrypoint. This is the most common
mistake in new code. Calling strlen from strdup, or fseek from
fsetpos, is the natural way to write the function. It is wrong here because
every entrypoint is a separate public symbol in its own separate object file
that each target enables or leaves out individually. A dependency between two
entrypoints means that they must be pulled in together.
Instead, put the shared logic in an internal function and call it from both entrypoints:
// src/string/string_length.h
namespace LIBC_NAMESPACE_DECL {
namespace internal {
LIBC_INLINE size_t string_length(const char *src) { ... }
} // namespace internal
} // namespace LIBC_NAMESPACE_DECL
// src/string/strlen.cpp
LLVM_LIBC_FUNCTION(size_t, strlen, (const char *src)) {
return internal::string_length(src);
}
CMake checks for this. When configured with -DLIBC_CMAKE_VERBOSE_LOGGING=ON,
it warns about any entrypoint or internal library that depends on an
entrypoint. The few permitted exceptions, currently errno and longjmp, are
listed in check_entrypoint_deps in
libc/cmake/modules/LLVMLibCObjectRules.cmake.
Some existing entrypoints break this rule. They are to be cleaned up and are not precedent for new code.
Internal libraries may depend on variable entrypoints such as environ or
stdout when they need the object itself. They may not depend on function
entrypoints.
Operating-system-specific code#
Per-OS duplication is acceptable. Operating systems differ enough that sharing an implementation between them usually costs more than it saves.
System calls are made only from wrappers in src/__support/OSUtil/<os>/; see
Syscall Wrappers. OS-agnostic code never names an OS-specific
namespace such as linux_syscalls.
There are several ways to select the implementation for the target OS. Pick the one that fits the amount of code that differs:
The whole entrypoint differs. Put each implementation in
src/<header>/<os>/<func>.cpp, and make the entrypoint insrc/<header>/CMakeLists.txtanALIASthat depends on.${LIBC_TARGET_OS}.<func>. Most syscall-backed functions work this way.The entrypoint is common and one step differs. Keep a single
src/<header>/<func>.cppthat calls aninternal::function, and provide that function as a per-OS object library selected with the sameALIASmechanism.fflushand itsfflush_internallibrary are the example.A small header-only primitive differs. Use a dispatch header that includes the right implementation, as
src/__support/OSUtil/io.hdoes.
Overlay mode and full build#
A function may be enabled in overlay mode only if it does not depend on an implementation-defined type or on library-owned state that is shared between functions. For example:
strlenandroundare pure functions, so they are fine in overlay mode.fopenandfgetcare full build only, becauseFILEis implementation defined.atexitis full build only, because it sets state thatexitmust read.strtokis fine in overlay mode. It keeps internal state, but no other function reads that state.
In each entrypoints.txt, overlay-safe functions are listed unconditionally and
the others are inside if(LLVM_LIBC_FULL_BUILD).
Both modes matter. Overlay mode is the more portable of the two and is how many users adopt the math and memory functions; a full build is where everything else is exercised. A change must build and pass its tests in both modes unless the code is full-build only. See Testing Guide.
Which targets get a new function#
A new entrypoint should be enabled on every target where it works. In practice contributors cannot test every target, so the minimum is:
For a function that needs Linux, the
entrypoints.txtfiles forx86_64,aarch64,arm, andriscvunderlibc/config/linux/. Linux on 32-bit Arm is included because its tests help cover the 32-bit Arm code that the baremetal target also uses. See Platform Support.For an OS-independent function, the Linux configurations above plus the baremetal, GPU, and other OS configurations, as described for math functions in
libc/src/math/docs/add_math_function.md.
linux/x86_64 is the most complete configuration. An entrypoint that is
present there and missing from another Linux architecture is usually an
oversight, not a decision, and adding it is a welcome change.
The public header declaration comes from libc/include/<header>.yaml. A
function that is missing there will build and pass the tests but will not appear
in the generated header.
Experimental entrypoints#
Entrypoints with known-incomplete implementations are listed inside
if(LLVM_LIBC_ENABLE_EXPERIMENTAL_ENTRYPOINTS) and are off by default. See
Extensions, stubs, and experimental entrypoints for when a function belongs there.
Configuration options#
Options in libc/config/config.json are named LIBC_CONF_* and are CMake
settings. They become LIBC_COPT_* macros on the compiler command line. See
Adding new libc configure options.
Add an option when a standard requires one behavior and a real user needs
another. Disabling floating point support in printf for small targets is the
model case. Do not add an option to avoid making a design decision.
An option that disables behavior in an entrypoint must disable the matching checks in that entrypoint’s tests under the same condition.
Bazel#
The Bazel build in utils/bazel/llvm-project-overlay/libc/ is maintained by
its downstream users, and an automated process keeps it in sync. Upstream
contributors are not required to update it, but it is appreciated.