[libc-commits] [libc] 6b4ee56 - [libc] Add a doc describing the current status of libc runtimes build.

[Siva Chandra Reddy via libc-commits]

Author: Siva Chandra Reddy
Date: 2022-04-18T06:48:43Z
New Revision: 6b4ee566e9bf8ce989fdcab8353ef43907439aca

URL: https://github.com/llvm/llvm-project/commit/6b4ee566e9bf8ce989fdcab8353ef43907439aca
DIFF: https://github.com/llvm/llvm-project/commit/6b4ee566e9bf8ce989fdcab8353ef43907439aca.diff

LOG: [libc] Add a doc describing the current status of libc runtimes build.

A section briefly mentioning the planned future enhancements has also
been included.

Reviewed By: lntue

Differential Revision: https://reviews.llvm.org/D123761

Added: 
    libc/docs/runtimes_build.rst

Modified: 
    libc/docs/index.rst

Removed: 
    


################################################################################
diff  --git a/libc/docs/index.rst b/libc/docs/index.rst
index 4d8e6e87c1357..a0629fe515893 100644
--- a/libc/docs/index.rst
+++ b/libc/docs/index.rst
@@ -83,3 +83,4 @@ Other Interesting Documentation
     redirectors
     source_layout
     strings
+    runtimes_build

diff  --git a/libc/docs/runtimes_build.rst b/libc/docs/runtimes_build.rst
new file mode 100644
index 0000000000000..06f674b8b5db0
--- /dev/null
+++ b/libc/docs/runtimes_build.rst
@@ -0,0 +1,36 @@
+Building libc using the runtimes build setup
+============================================
+
+The runtimes build of the LLVM toolchain first builds clang and then builds the
+various runtimes (like ``libc++`` and ``compiler-rt``) and LLVM binutils (like
+``llvm-objcopy`` and ``llvm-readelf``) using the freshly built clang. One can
+build libc also as in the same manner. As of this writing, only the ABI agnostic
+parts of the libc are included when built in that manner. This allows interested
+users to continue using their system libc's headers while linking to LLVM libc's
+implementations when they are available. To build libc using the runtimes build
+setup, one needs to include the ``libc`` project in the list of the enabled
+runtimes when configuring the build:
+
+.. code-block:: shell
+
+   $> cmake ../llvm -GNinja -DLLVM_ENABLE_PROJECTS="llvm;clang" \
+      -DLLVM_ENABLE_RUNTIMES=libc
+
+Note that Ninja is used as the generator in the above CMake command. Hence, to
+actually build the libc, one has to build the Ninja target named ``llvmlibc``:
+
+.. code-block:: shell
+
+   $> ninja llvmlibc
+
+If a 
diff erent generator is used, then the build command should be suitably
+adapted to build the target ``llvmlibc``. Building that target will produce a
+static archive which includes all ABI agnostic functions available in LLVM libc.
+
+Future direction
+----------------
+
+We plan to enhance the runtimes build of LLVM libc to include ABI sensitive
+parts and to also generate the public headers. Likewise, we would like to
+provide an option to build other runtimes like ``libc++`` and ``compiler-rt``
+against LLVM libc.