[libc] update host build docs

[michaelrj-google]

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

[nickdesaulniers]

It is kind of nice to have the explicit install steps listed. At least to me it gives more confidence in what is or is not being installed. At the least, can't the user just run ninja install without ninja all, and the dependencies are wired up to build first, then install?

[michaelrj-google]

I agree that it's nice to list the install steps, however whenever I hear from people who are trying it out they always ignore this step and just run ninja install. I'll leave it as it was and add ninja install as an alternative.

[llvmbot]

@llvm/pr-subscribers-libc

Author: Michael Jones (michaelrj-google)

Changes

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

---

Full diff: https://github.com/llvm/llvm-project/pull/120147.diff

2 Files Affected:

• (modified) libc/docs/dev/index.rst (+1)
• (modified) libc/docs/full_host_build.rst (+51-42)

diff --git a/libc/docs/dev/index.rst b/libc/docs/dev/index.rst
index c16121feb3a45d..9ed50bb6683aae 100644
--- a/libc/docs/dev/index.rst
+++ b/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
diff --git a/libc/docs/full_host_build.rst b/libc/docs/full_host_build.rst
index f687c2fdab213e..02c0739a6bc434 100644
--- a/libc/docs/full_host_build.rst
+++ b/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
@@ -121,36 +125,20 @@ to use the freshly built lld and compiler-rt.
    $> cd build
    $> SYSROOT=/path/to/sysroot # Remember to set this!
    $> cmake ../llvm  \
-      -G Ninja  \
-      -DLLVM_ENABLE_PROJECTS="clang;lld;libc;compiler-rt"   \
-      -DCMAKE_BUILD_TYPE=Debug  \
-      -DCMAKE_C_COMPILER=clang \
-      -DCMAKE_CXX_COMPILER=clang++ \
-      -DLLVM_LIBC_FULL_BUILD=ON \
-      -DLLVM_LIBC_INCLUDE_SCUDO=ON \
-      -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \
-      -DCOMPILER_RT_BUILD_GWP_ASAN=OFF                       \
-      -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.
+   -G Ninja  \
+   -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 \
+   -DLLVM_LIBC_INCLUDE_SCUDO=ON \
+   -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \
+   -DCOMPILER_RT_BUILD_GWP_ASAN=OFF                       \
+   -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF        \
+   -DCLANG_DEFAULT_LINKER=lld \
+   -DCLANG_DEFAULT_RTLIB=compiler-rt \
+   -DCMAKE_INSTALL_PREFIX=$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,19 @@ 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;
+   }
+

[michaelrj-google]

Planning to land after presubmits finish