[libc] update host build docs (#120147)

Update the host build docs to better reflect the current recommended
process.

Author: michaelrj-google

libc/docs/dev/index.rst

@@ -7,6 +7,7 @@ Developer Guides
 Navigate to the links below for information on the respective topics:
 
 .. toctree::
+   :maxdepth: 1
 
    code_style
    source_tree_layout

libc/docs/full_host_build.rst

@@ -8,7 +8,7 @@ Full Host Build
    :depth: 1
    :local:
 
-.. note:: 
+.. note::
    Fullbuild requires running headergen, which is a python program that depends on
    pyyaml. The minimum versions are listed on the :ref:`header_generation`
    page, as well as additional information.
@@ -99,11 +99,16 @@ a C++ standard library (like libc++). Hence, we do not include
    `libc++ <https://libcxx.llvm.org/>`_, libcxx-abi and libunwind in the
    LLVM only toolchain and use them to build and link C++ applications.
 
-Below is the list of commands for a simple recipe to build and install the
-libc components along with other components of an LLVM only toolchain.  In this
-we've set the Ninja generator, enabled a full compiler suite, set the build
-type to "Debug", and enabled the Scudo allocator.  The build also tells clang
-to use the freshly built lld and compiler-rt.
+Below is the cmake command for a bootstrapping build of LLVM. This will build
+clang and lld with the current system's toolchain, then build compiler-rt and
+LLVM-libc with that freshly built clang. This ensures that LLVM-libc can take
+advantage of the latest clang features and optimizations.
+
+This build also uses Ninja as cmake's generator, and sets lld and compiler-rt as
+the default for the fresh clang. Those settings are recommended, but the build
+should still work without them. The compiler-rt options are required for
+building `Scudo <https://llvm.org/docs/ScudoHardenedAllocator.html>`_ as the
+allocator for LLVM-libc.
 
 .. note::
    if your build fails with an error saying the compiler can't find
@@ -113,7 +118,6 @@ to use the freshly built lld and compiler-rt.
    this command:
    ``sudo ln -s /usr/include/<TARGET TRIPLE>/asm /usr/include/asm``
 
-.. TODO: Move from projects to runtimes for libc, compiler-rt
 .. code-block:: sh
 
    $> cd llvm-project  # The llvm-project checkout
@@ -122,8 +126,9 @@ to use the freshly built lld and compiler-rt.
    $> SYSROOT=/path/to/sysroot # Remember to set this!
    $> cmake ../llvm  \
       -G Ninja  \
-      -DLLVM_ENABLE_PROJECTS="clang;lld;libc;compiler-rt"   \
-      -DCMAKE_BUILD_TYPE=Debug  \
+      -DLLVM_ENABLE_PROJECTS="clang;lld"   \
+      -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \
+      -DCMAKE_BUILD_TYPE=Release  \
       -DCMAKE_C_COMPILER=clang \
       -DCMAKE_CXX_COMPILER=clang++ \
       -DLLVM_LIBC_FULL_BUILD=ON \
@@ -133,25 +138,8 @@ to use the freshly built lld and compiler-rt.
       -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF        \
       -DCLANG_DEFAULT_LINKER=lld \
       -DCLANG_DEFAULT_RTLIB=compiler-rt \
-      -DDEFAULT_SYSROOT=$SYSROOT \
       -DCMAKE_INSTALL_PREFIX=$SYSROOT
 
-We will go over some of the special options passed to the ``cmake`` command
-above.
-
-* **Enabled Projects** - Since we want to build and install clang, lld
-  and compiler-rt along with the libc, we specify
-  ``clang;libc;lld;compiler-rt`` as the list of enabled projects.
-* **The full build option** - Since we want to do build the full libc, we pass
-  ``-DLLVM_LIBC_FULL_BUILD=ON``.
-* **Scudo related options** - 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 to include
-  Scudo in the libc. Since the libc currently only supports static linking, we
-  also specify that we do not want to build the Scudo shared library.
-* **Default sysroot and install prefix** - This is the path to the tool chain
-  install directory.  This is the directory where you intend to set up the sysroot.
-
 Build and install
 =================
 
@@ -164,14 +152,19 @@ Build and install
    you may need to delete them from ``/usr/local/include``.
 
 After configuring the build with the above ``cmake`` command, one can build and
-install the libc, clang (and its support libraries and builtins), lld and
-compiler-rt, with the following command:
+install the toolchain with
 
 .. code-block:: sh
 
    $> ninja install-clang install-builtins install-compiler-rt  \
       install-core-resource-headers install-libc install-lld
 
+or
+
+.. code-block:: sh
+
+   $> ninja install
+
 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
@@ -190,9 +183,9 @@ These instructions should work on a Debian-based x86_64 system:
 
    $> apt download linux-libc-dev
    $> dpkg -x linux-libc-dev*deb .
-   $> mv usr/include/* /path/to/sysroot/include
-   $> rm -rf usr linux-libc-dev*deb
-   $> ln -s x86_64-linux-gnu/asm ~/Programming/sysroot/include/asm
+   $> cp -r usr/* /path/to/sysroot/
+   $> rm -r usr linux-libc-dev*deb
+   $> ln -s /path/to/sysroot/include/x86_64-linux-gnu/asm /path/to/sysroot/include/asm
 
 Using your newly built libc
 ===========================
@@ -208,3 +201,20 @@ invocation:
    Because the libc does not yet support dynamic linking, the -static parameter
    must be added to all clang invocations.
 
+
+You can make sure you're using the newly built toolchain by trying out features
+that aren't yet supported by the system toolchain, such as fixed point. The
+following is an example program that demonstrates the difference:
+
+.. code-block:: C
+
+   // $ $SYSROOT/bin/clang example.c -static -ffixed-point --sysroot=$SYSROOT
+
+   #include <stdio.h>
+   int main() {
+      printf("Hello, World!\n%.9f\n%.9lK\n",
+         4294967295.000000001,
+         4294967295.000000001ulK);
+      return 0;
+   }
+