[libc] Update cross-compilation instructions

[jeffbailey]

Summary

• Add various options so that it uses the build lld and compiler-rt
• Add instructions on how to use the newly built libc
• Remove trailing comments in code-block for cut and pastability

[MaskRay]

libc/docs/full_host_build.rst

73

FWIW: Specifying DEFAULT_SYSROOT causes many test failures and I propose that we deprecate it (D158218).

[sivachandra]

libc/docs/full_host_build.rst

73

Thanks for the heads-up. I will work on cleaning this up.

libc/docs/full_cross_build.rst

 say *cross build* a full libc, we mean that we will build the libc for a target
 system which is not the same as the system on which the libc is being built.
 For example, you could be building for a bare metal aarch64 *target* on a Linux
 x86_64 *host*.
 
 Configure the full cross build of the libc
 ==========================================
 
-Below is a simple recipe to configure the libc for a cross build.
+Below is a simple recipe to configure the libc for a cross build.  In this,
+we've set Ninja as the generator, and are building the full libc.
 
 .. code-block:: sh
 
   $> cd llvm-project  # The llvm-project checkout
   $> mkdir build
   $> cd build
   $> cmake ../llvm  \
-     -G Ninja \ # Generator
-     -DLLVM_ENABLE_PROJECTS=libc  \ # Enable the libc project
-     -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++  \
-     -DLLVM_LIBC_FULL_BUILD=ON   \ # We are building the full libc
+     -G Ninja \
+     -DLLVM_ENABLE_PROJECTS=libc  \
+     -DCMAKE_C_COMPILER=clang \
+     -DCMAKE_CXX_COMPILER=clang++  \
+     -DLLVM_LIBC_FULL_BUILD=ON \
      -DLIBC_TARGET_TRIPLE=<Your target triple>
 
 We will go over the special options passed to the ``cmake`` command above.
 
 * **Enabled Projects** - Since we want to build the libc project, we list
   ``libc`` as the enabled project.
 * **The full build option** - Since we want to build the full libc, we pass
   ``-DLLVM_LIBC_FULL_BUILD=ON``.

libc/docs/full_host_build.rst

 .. note:: When the libc is complete enough, we should be able to include
    `libc++ <https://libcxx.llvm.org/>`_, libcxx-abi and libunwind in the
    LLVM only toolchain and use them to build and link C++ applications.
 
 Configure the full libc build
 ===============================
 
 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.
+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.
 
 .. code-block:: sh
 
    $> cd llvm-project  # The llvm-project checkout
    $> mkdir build
    $> cd build
+   $> SYSROOT=/path/to/sysroot # Remember to set this!
    $> cmake ../llvm  \
-      -G Ninja  \ # Generator
-      -DLLVM_ENABLE_PROJECTS="clang;libc;lld;compiler-rt"   \ # Enabled projects
-      -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
+      -G Ninja  \
+      -DLLVM_ENABLE_PROJECTS="clang;libc;lld;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        \
-      -DCMAKE_INSTALL_PREFIX=<SYSROOT>  # Specify a sysroot directory
+      -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.
-* **The install prefix** - This is the path to the tool chain install directory.
-  This is the directory where you intend to set up the sysroot.
+* **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
 =================
 
 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:
 
 .. 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
+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.
+
+Using your newly built libc
+===========================
+
+You can now use your newly built libc nearly like you would use any compiler
+invocation:
+
+.. code-block:: sh
+
+   $> /path/to/sysroot/bin/clang -static main.c
+
+.. warning::
+   Because the libc does not yet support dynamic linking, the -static parameter
+   must be added to all clang invocations.
+