[libc] Add document for a recipe to do a full standalone cross-build.

[sivachandra]

Fix a typo.

[jeffbailey]

libc/docs/full_host_build.rst

13

Interestingly, there doesn't seem to be anything in https://llvm.org/docs/Lexicon.html to give common words for this. I can't find anything commenting on the use of "native build" for inclusive language, but LLVM doesn't use the term. GCC does: https://gcc.gnu.org/install/build.html

I'll LGTM this, but if we find standard language inside LLVM, it would be nice to use it (and add it to the Lexicon).

libc/docs/full_cross_build.rst

+.. _full_cross_build:
+
+================
+Full Cross Build
+================
+
+.. contents:: Table of Contents
+   :depth: 1
+   :local:
+
+In this document, we will present a recipe to cross build a full libc. When we
+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.
+
+.. 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
+     -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``.
+* **The target triple** - This is the target triple of the target for which
+  we are building the libc. For example, for a Linux 32-bit Arm target,
+  one can specify it as ``arm-linux-eabi``.
+
+Build and install
+=================
+
+After configuring the build with the above ``cmake`` command, one can build the
+the libc for the target with the following command:
+
+.. code-block:: sh
+   
+   $> ninja libc
+
+The above ``ninja`` command will build the ``libc.a`` static archive for the
+target specified with ``-DLIBC_TARGET_TRIPLE`` to the ``cmake`` command.
+
+Building for bare metal
+=======================
+
+To build for bare metal, all one has to do is to specify the
+`system <https://clang.llvm.org/docs/CrossCompilation.html#target-triple>`_
+component of the target triple as ``none``. For example, to build for a
+32-bit arm target on bare metal, one can use a target triple like
+``arm-none-eabi``.

libc/docs/full_host_build.rst

+.. _full_host_build:
+
+===============
+Full Host Build
+===============
+
+.. contents:: Table of Contents
+   :depth: 1
+   :local:
+
+In this document, we will present a recipe to build the full libc for the host.
+When we say *build the libc for the host*, the goal is to build the libc for
+the same system on which the libc is being built. Also, we will take this
+opportunity to demonstrate how one can 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 a full 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
+`libc++ <https://libcxx.llvm.org/>`_ 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
+   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.
+
+.. code-block:: sh
+
+   $> cd llvm-project  # The llvm-project checkout
+   $> mkdir build
+   $> cd build
+   $> 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
+      -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
+
+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.
+
+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
+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/docs/fullbuild_mode.rst

 .. _fullbuild_mode:
 
 ==============
 Fullbuild Mode
 ==============
 
-.. 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 *fullbuild* mode of LLVM's libc is the mode in which it is to be 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
+with the system libc.) In to order use it as the only libc, one will have to
+build and install not only the static archives like ``libc.a`` from LLVM's libc,
+but also the start-up objects like ``crt1.o`` and the public headers.
 
-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.
+The full libc build can be of two types:
 
-Linux Headers
-=============
+.. toctree::
+   :maxdepth: 1
 
-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.
+   full_host_build
+   full_cross_build

libc/docs/index.rst

 =================
 
 The libc is written to be ABI independent.  Interfaces are generated using
 LLVM's tablegen, so supporting arbitrary ABIs is possible.  In it's initial
 stages there is no ABI stability in any form.
 
 .. toctree::
    :hidden:
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: Using
 
    usage_modes
    overlay_mode
    fullbuild_mode
    gpu_mode
 
 .. toctree::