[libc-commits] [libc] 136b927 - [libc] Add a doc about the libc fullbuild mode.

[Siva Chandra Reddy via libc-commits]

Author: Siva Chandra Reddy
Date: 2022-11-02T08:18:48-07:00
New Revision: 136b927c9e44867feb5b5d447843c5a588fb09b8

URL: https://github.com/llvm/llvm-project/commit/136b927c9e44867feb5b5d447843c5a588fb09b8
DIFF: https://github.com/llvm/llvm-project/commit/136b927c9e44867feb5b5d447843c5a588fb09b8.diff

LOG: [libc] Add a doc about the libc fullbuild mode.

Reviewed By: jeffbailey

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

Added: 
    libc/examples/README.md

Modified: 
    libc/docs/fullbuild_mode.rst

Removed: 
    


################################################################################
diff  --git a/libc/docs/fullbuild_mode.rst b/libc/docs/fullbuild_mode.rst
index 635dc8b66417f..a5c51aa4cb079 100644
--- a/libc/docs/fullbuild_mode.rst
+++ b/libc/docs/fullbuild_mode.rst
@@ -4,4 +4,80 @@
 Fullbuild Mode
 ==============
 
-Coming soon, stay tuned!
+.. contents:: Table of Contents
+  :depth: 4
+  :local:
+
+The *fullbuild* mode of LLVM's libc is the mode in which it is being used as
+the only libc (as opposed to the :ref:`overlay_mode` in which it is used along
+with the system libc.) Hence, to start using it that way, you will have to build
+and install the ``libc.a`` static archive from LLVM's libc as well as the
+start-up objects and public headers provided by it. In this document, we will
+present a way to set up a *sysroot* (see the documentation of the ``--sysroot``
+option here: `<https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html>`_)
+which includes not only the components of LLVM's libc, but also full a LLVM only
+toolchain consisting of the `clang <https://clang.llvm.org/>`_ compiler, the
+`lld <https://lld.llvm.org/>`_ linker and the
+`compiler-rt <https://compiler-rt.llvm.org/>`_ runtime libraries. LLVM's libc
+is not yet complete enough to allow using and linking a C++ application against
+a C++ standard library (like libc++). Hence, we do not include a C++ standard
+library in the sysroot.
+
+.. note:: When the libc is complete enough, we should be able to include
+   `libc++ <https://libcxx.llvm.org/>`_, libcxx-abi and libunwind in the
+   toolchain and use them to build and link C++ applications.
+
+Building the full libc
+======================
+
+LLVM's libc uses `Scudo <https://llvm.org/docs/ScudoHardenedAllocator.html>`_
+as its allocator. So, when building the full libc, we should specify that we
+want Scudo to be included in the libc. Since the libc currently only supports
+static linking, we also specify that we do not want a shared library for Scudo.
+A typical ``cmake`` configure step will look like this:
+
+.. code-block:: sh
+
+  $> cd llvm-project  # The llvm-project checkout
+  $> mkdir build
+  $> cd build
+  $> cmake ../llvm -G Ninja                                \
+     -DLLVM_ENABLE_PROJECTS="clang;libc;lld;compiler-rt"   \
+     -DCMAKE_BUILD_TYPE=<Debug|Release>                    \ # Select build type
+     -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
+     -DLLVM_LIBC_FULL_BUILD=ON      \  # We want the full libc
+     -DLLVM_LIBC_INCLUDE_SCUDO=ON   \  # Include Scudo in the libc
+     -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \
+     -DCOMPILER_RT_BUILD_GWP_ASAN=OFF                       \
+     -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF        \
+     -DCMAKE_INSTALL_PREFIX=<SYSROOT>  # Specify a sysroot directory
+
+Since we want to include ``clang``, ``lld`` and ``compiler-rt`` in our
+toolchain, we list them in ``LLVM_ENABLE_PROJECTS`` along with ``libc``. The
+option ``CMAKE_INSTALL_PREFIX`` specifies the sysroot directory in which to
+install the new toolchain.
+
+Installation
+============
+
+To build and install the libc, clang (and its support libraries and builtins),
+lld and compiler-rt, run the following command after the above ``cmake``
+command:
+
+.. code-block:: sh
+
+   $> ninja install-clang install-builtins install-compiler-rt  \
+      install-core-resource-headers install-libc install-lld
+
+Once the above command completes successfully, the ``<SYSROOT>`` directory you
+have specified with the CMake configure step above will contain a full LLVM-only
+toolchain with which you can build practical/real-world C applications. See
+`<https://github.com/llvm/llvm-project/tree/main/libc/examples>`_ for examples
+of how to start using this new toolchain.
+
+Linux Headers
+=============
+
+If you are using the full libc on Linux, then you will also need to install
+Linux headers in your sysroot. It is left to the reader to figure out the best
+way to install Linux headers on the system they want to use the full libc on.

diff  --git a/libc/examples/README.md b/libc/examples/README.md
new file mode 100644
index 0000000000000..ecdbe33656939
--- /dev/null
+++ b/libc/examples/README.md
@@ -0,0 +1 @@
+Coming soon, stay tuned!