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

Reviewed By: jeffbailey

Differential Revision: https://reviews.llvm.org/D141037

diff --git a/libc/docs/full_cross_build.rst b/libc/docs/full_cross_build.rst
new file mode 100644 (file)
index 0000000..2f95f5b
--- /dev/null
+++ b/libc/docs/full_cross_build.rst
@@ -0,0 +1,64 @@
+.. _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``.

diff --git a/libc/docs/full_host_build.rst b/libc/docs/full_host_build.rst
new file mode 100644 (file)
index 0000000..835c009
--- /dev/null
+++ b/libc/docs/full_host_build.rst
@@ -0,0 +1,91 @@
+.. _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.

diff --git a/libc/docs/fullbuild_mode.rst b/libc/docs/fullbuild_mode.rst
index a5c51aa..0af923d 100644 (file)
--- a/libc/docs/fullbuild_mode.rst
+++ b/libc/docs/fullbuild_mode.rst
@@ -4,80 +4,16 @@
 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

diff --git a/libc/docs/index.rst b/libc/docs/index.rst
index 10e30a3..31bc1e2 100644 (file)
--- a/libc/docs/index.rst
+++ b/libc/docs/index.rst
@@ -46,7 +46,7 @@ stages there is no ABI stability in any form.
 
 .. toctree::
    :hidden:
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: Using
 
    usage_modes