diff --git a/libc/docs/CMakeLists.txt b/libc/docs/CMakeLists.txt index 5b89511c33bdc..68fe9fc545781 100644 --- a/libc/docs/CMakeLists.txt +++ b/libc/docs/CMakeLists.txt @@ -86,7 +86,7 @@ if (SPHINX_FOUND) # docgen invocation. add_custom_target(${stem_rst} - COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/../utils/docgen/docgen.py ${stem}.h > + COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/../utils/docgen/docgen.py ${stem}.h > ${CMAKE_CURRENT_BINARY_DIR}/headers/${stem}.rst) # depend on the docgen invocation. add_dependencies(docs-libc-html ${stem_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 +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 `__ +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`. + +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: diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py index 5a57987b3c51e..59cfbd54561c7 100755 --- a/libc/utils/docgen/docgen.py +++ b/libc/utils/docgen/docgen.py @@ -1,4 +1,4 @@ -#!/usr/bin/env python +#!/usr/bin/env python3 # # ====- Generate documentation for libc functions ------------*- python -*--==# #