[libc-commits] [libc] 733ac92 - [libc] Add two more recipes to do a cross build.

Tue Apr 18 12:40:22 PDT 2023

Author: Siva Chandra Reddy
Date: 2023-04-18T12:40:14-07:00
New Revision: 733ac920be3f2cb0d9ab6481e63cb7b6509fbc15

URL: https://github.com/llvm/llvm-project/commit/733ac920be3f2cb0d9ab6481e63cb7b6509fbc15
DIFF: https://github.com/llvm/llvm-project/commit/733ac920be3f2cb0d9ab6481e63cb7b6509fbc15.diff

LOG: [libc] Add two more recipes to do a cross build.

Reviewed By: jeffbailey

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

Added: 
    

Modified: 
    libc/docs/full_cross_build.rst

Removed: 
    


################################################################################
diff  --git a/libc/docs/full_cross_build.rst b/libc/docs/full_cross_build.rst
index 431edb6e9b11..cb824730603a 100644

--- a/libc/docs/full_cross_build.rst
+++ b/libc/docs/full_cross_build.rst
@@ -8,30 +8,67 @@ Full Cross Build
    :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*.
+In this document, we will present recipes to cross build the full libc. When we
+say *cross build* a full libc, we mean that we will build the full 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
-==========================================
+There are three main recipes to cross build the full libc. Each one serves a
+
diff erent use case. Below is a short description of these recipes to help users
+pick the recipe that best suites their needs and contexts.
 
-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.
+* **Standalone cross build** - Using this recipe one can build the libc using a
+  compiler of their choice. One should use this recipe if their compiler can
+  build for the host as well as the target.
+* **Runtimes cross build** - In this recipe, one will have to first build the
+  libc build tools for the host separately and then use those build tools to
+  build the libc. Users can use the compiler of their choice to build the
+  libc build tools as well as the libc. One should use this recipe if they
+  have to use a host compiler to build the build tools for the host and then
+  use a target compiler (which is 
diff erent from the host compiler) to build
+  the libc.
+* **Bootstrap cross build** - In this recipe, one will build the ``clang``
+  compiler and the libc build tools for the host first, and then use them to
+  build the libc for the target. Unlike with the runtimes build recipe, the
+  user does not have explicitly build ``clang`` and other libc build tools.
+  They get built automatically before building the libc. One should use this
+  recipe if they intend use the built ``clang`` and the libc as part of their
+  toolchain for the target.
+
+The following sections present the three recipes in detail.
+
+Standalone cross build
+======================
+
+In the *standalone crossbuild* recipe, the system compiler or a custom compiler
+of user's choice is used to build the libc. The necessary build tools for the
+host are built first, and those build tools are then used to build the libc for
+the target. Both these steps happen automatically, as in, the user does not have
+to explicitly build the build tools first and then build the libc. A point to
+keep in mind is that the compiler used should be capable of building for the
+host as well as the target.
+
+CMake configure step
+--------------------
+
+Below is the CMake command to configure the standalone crossbuild of the libc.
 
 .. code-block:: sh
 
   $> cd llvm-project  # The llvm-project checkout
   $> mkdir build
   $> cd build
+  $> C_COMPILER=<C compiler> # For example "clang"
+  $> CXX_COMPILER=<C++ compiler> # For example "clang++"
   $> cmake ../llvm  \
      -G Ninja \
      -DLLVM_ENABLE_PROJECTS=libc  \
-     -DCMAKE_C_COMPILER=clang \
-     -DCMAKE_CXX_COMPILER=clang++  \
+     -DCMAKE_C_COMPILER=$C_COMPILER \
+     -DCMAKE_CXX_COMPILER=$CXX_COMPILER \
      -DLLVM_LIBC_FULL_BUILD=ON \
-     -DLIBC_TARGET_TRIPLE=<Your target triple>
+     -DLIBC_TARGET_TRIPLE=<Your target triple> \
+     -DCMAKE_BUILD_TYPE=<Release|Debug>
 
 We will go over the special options passed to the ``cmake`` command above.
 
@@ -43,18 +80,146 @@ We will go over the special options passed to the ``cmake`` command above.
   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
-=================
+Build step
+----------
 
 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
+   $> ninja libc libm
+
+The above ``ninja`` command will build the libc static archives ``libc.a`` and
+``libm.a`` for the target specified with ``-DLIBC_TARGET_TRIPLE`` in the CMake
+configure step.
+
+Runtimes cross build
+====================
+
+The *runtimes cross build* is very similar to the standalone crossbuild but the
+user will have to first build the libc build tools for the host separately. One
+should use this recipe if they want to use a 
diff erent host and target compiler.
+Note that the libc build tools MUST be in sync with the libc. That is, the
+libc build tools and the libc, both should be built from the same source
+revision. At the time of this writing, there is only one libc build tool that
+has to be built separately. It is done as follows:
+
+.. code-block:: sh
+
+  $> cd llvm-project  # The llvm-project checkout
+  $> mkdir build-libc-tools # A 
diff erent build directory for the build tools
+  $> cd build-libc-tools
+  $> HOST_C_COMPILER=<C compiler for the host> # For example "clang"
+  $> HOST_CXX_COMPILER=<C++ compiler for the host> # For example "clang++"
+  $> cmake ../llvm  \
+     -G Ninja \
+     -DLLVM_ENABLE_PROJECTS=libc  \
+     -DCMAKE_C_COMPILER=$HOST_C_COMPILER \
+     -DCMAKE_CXX_COMPILER=$HOST_CXX_COMPILER  \
+     -DLLVM_LIBC_FULL_BUILD=ON \
+     -DCMAKE_BUILD_TYPE=Debug # User can choose to use "Release" build type
+  $> ninja libc-hdrgen
+
+The above commands should build a binary named ``libc-hdrgen``. Copy this binary
+to a directory of your choice.
+
+CMake configure step
+--------------------
+
+After copying the ``libc-hdrgen`` binary to say ``/path/to/libc-hdrgen``,
+configure the libc build using the following command:
+
+.. code-block:: sh
+
+  $> cd llvm-project  # The llvm-project checkout
+  $> mkdir build
+  $> cd build
+  $> TARGET_C_COMPILER=<C compiler for the target>
+  $> TARGET_CXX_COMPILER=<C++ compiler for the target>
+  $> HDRGEN=</path/to/libc-hdrgen>
+  $> TARGET_TRIPLE=<Your target triple>
+  $> cmake ../runtimes  \
+     -G Ninja \
+     -DLLVM_ENABLE_RUNTIMES=libc  \
+     -DCMAKE_C_COMPILER=$TARGET_C_COMPILER \
+     -DCMAKE_CXX_COMPILER=$TARGET_CXX_COMPILER \
+     -DLLVM_LIBC_FULL_BUILD=ON \
+     -DLIBC_HDRGEN_EXE=$HDRGEN \
+     -DLIBC_TARGET_TRIPLE=$TARGET_TRIPLE \
+     -DCMAKE_BUILD_TYPE=Debug # User can choose to use "Release" build type
+
+Note the 
diff erences in the above cmake command versus the one used in the
+CMake configure step of the standalone build recipe:
+
+* Instead of listing ``libc`` in ``LLVM_ENABLED_PROJECTS``, we list it in
+  ``LLVM_ENABLED_RUNTIMES``.
+* Instead of using ``llvm-project/llvm`` as the root CMake source directory,
+  we use ``llvm-project/runtimes`` as the root CMake source directory.
+* The path to the ``libc-hdrgen`` binary built earlier is specified with
+  ``-DLIBC_HDRGEN_EXE=/path/to/libc-hdrgen``.
+
+Build step
+----------
+
+The build step in the runtimes build recipe is exactly the same as that of
+the standalone build recipe:
+
+.. code-block:: sh
+
+    $> ninja libc libm
+
+As with the standalone build recipe, the above ninja command will build the
+libc static archives for the target specified with ``-DLIBC_TARGET_TRIPLE`` in
+the CMake configure step.
+
+
+Bootstrap cross build
+=====================
+
+In this recipe, the clang compiler and the ``libc-hdrgen`` binary, both are
+built automatically before building the libc for the target.
+
+CMake configure step
+--------------------
+
+.. code-block:: sh
+
+  $> cd llvm-project  # The llvm-project checkout
+  $> mkdir build
+  $> cd build
+  $> C_COMPILER=<C compiler> # For example "clang"
+  $> CXX_COMPILER=<C++ compiler> # For example "clang++"
+  $> TARGET_TRIPLE=<Your target triple>
+  $> cmake ../llvm \
+     -G Ninja \
+     -DCMAKE_C_COMPILER=$C_COMPILER \
+     -DCMAKE_CXX_COMPILER=$CXX_COMPILER \
+     -DLLVM_ENABLE_PROJECTS=clang \
+     -DLLVM_ENABLE_RUNTIMES=libc \
+     -DLLVM_LIBC_FULL_BUILD=ON \
+     -DLLVM_RUNTIME_TARGETS=$TARGET_TRIPLE \
+     -DCMAKE_BUILD_TYPE=Debug
+
+Note how the above cmake command 
diff ers from the one used in the other two
+recipes:
+
+* ``clang`` is listed in ``-DLLVM_ENABLE_PROJECTS`` and ``libc`` is
+  listed in ``-DLLVM_ENABLE_RUNTIMES``.
+* The CMake root source directory is ``llvm-project/llvm``.
+* The target triple is specified with ``-DLLVM_RUNTIME_TARGETS``.
+
+Build step
+----------
+
+The build step is similar to the other two recipes:
+
+.. 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.
+The above ninja command should build the libc static archives for the target
+specified with ``-DLLVM_RUNTIME_TARGETS``.
 
 Building for bare metal
 =======================
@@ -63,4 +228,5 @@ 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``.
+``arm-none-eabi``. Other than that, the libc for a bare metal target can be
+built using any of the three recipes described above.


        
