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

[tschuett]

libc++ and binutils are future work?

cmake -S llvm -B build

could save you some lines.

[tschuett]

libc/docs/fullbuild_mode.rst

55

we

[sivachandra]

Fix typo.

[sivachandra]

In D137061#3895678, @tschuett wrote:

libc++ and binutils are future work?

Yes, libc++ is future work. Binutils can be installed now along with the rest of the toolchain. I would think that it is really an exercise for the user :)

[tschuett]

In D137061#3896832, @sivachandra wrote:

In D137061#3895678, @tschuett wrote:

libc++ and binutils are future work?

Yes, libc++ is future work. Binutils can be installed now along with the rest of the toolchain. I would think that it is really an exercise for the user :)

I misunderstood the semantics of sysroot. Still nice!

[jeffbailey]

libc/docs/fullbuild_mode.rst

74–76

Rather than the coming soon page, I'd rather we just not include this sentence and not create the other file. I might be just traumatized from the 90's when we had a whole decade of "This site under construction"

[sivachandra]

libc/docs/fullbuild_mode.rst

74–76

It is also out there: https://reviews.llvm.org/D137090 - I missed adding you to the review, done now. I added that "Coming soon, stay tuned" page to make this patch complete.

[sivachandra]

Add a short section talking about Linux headers.

libc/docs/fullbuild_mode.rst

 .. _fullbuild_mode:
 
 ==============
 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.

libc/examples/README.md

+Coming soon, stay tuned!