libc/docs/full_cross_build.rst

   1 .. _full_cross_build:
   2
   3 ================
   4 Full Cross Build
   5 ================
   6
   7 .. contents:: Table of Contents
   8    :depth: 1
   9    :local:
  10
  11 In this document, we will present recipes to cross build the full libc. When we
  12 say *cross build* a full libc, we mean that we will build the full libc for a
  13 target system which is not the same as the system on which the libc is being
  14 built. For example, you could be building for a bare metal aarch64 *target* on a
  15 Linux x86_64 *host*.
  16
  17 There are three main recipes to cross build the full libc. Each one serves a
  18 different use case. Below is a short description of these recipes to help users
  19 pick the recipe that best suites their needs and contexts.
  20
  21 * **Standalone cross build** - Using this recipe one can build the libc using a
  22   compiler of their choice. One should use this recipe if their compiler can
  23   build for the host as well as the target.
  24 * **Runtimes cross build** - In this recipe, one will have to first build the
  25   libc build tools for the host separately and then use those build tools to
  26   build the libc. Users can use the compiler of their choice to build the
  27   libc build tools as well as the libc. One should use this recipe if they
  28   have to use a host compiler to build the build tools for the host and then
  29   use a target compiler (which is different from the host compiler) to build
  30   the libc.
  31 * **Bootstrap cross build** - In this recipe, one will build the ``clang``
  32   compiler and the libc build tools for the host first, and then use them to
  33   build the libc for the target. Unlike with the runtimes build recipe, the
  34   user does not have explicitly build ``clang`` and other libc build tools.
  35   They get built automatically before building the libc. One should use this
  36   recipe if they intend use the built ``clang`` and the libc as part of their
  37   toolchain for the target.
  38
  39 The following sections present the three recipes in detail.
  40
  41 Standalone cross build
  42 ======================
  43
  44 In the *standalone crossbuild* recipe, the system compiler or a custom compiler
  45 of user's choice is used to build the libc. The necessary build tools for the
  46 host are built first, and those build tools are then used to build the libc for
  47 the target. Both these steps happen automatically, as in, the user does not have
  48 to explicitly build the build tools first and then build the libc. A point to
  49 keep in mind is that the compiler used should be capable of building for the
  50 host as well as the target.
  51
  52 CMake configure step
  53 --------------------
  54
  55 Below is the CMake command to configure the standalone crossbuild of the libc.
  56
  57 .. code-block:: sh
  58
  59   $> cd llvm-project  # The llvm-project checkout
  60   $> mkdir build
  61   $> cd build
  62   $> C_COMPILER=<C compiler> # For example "clang"
  63   $> CXX_COMPILER=<C++ compiler> # For example "clang++"
  64   $> cmake ../llvm  \
  65      -G Ninja \
  66      -DLLVM_ENABLE_PROJECTS=libc  \
  67      -DCMAKE_C_COMPILER=$C_COMPILER \
  68      -DCMAKE_CXX_COMPILER=$CXX_COMPILER \
  69      -DLLVM_LIBC_FULL_BUILD=ON \
  70      -DLIBC_TARGET_TRIPLE=<Your target triple> \
  71      -DCMAKE_BUILD_TYPE=<Release|Debug>
  72
  73 We will go over the special options passed to the ``cmake`` command above.
  74
  75 * **Enabled Projects** - Since we want to build the libc project, we list
  76   ``libc`` as the enabled project.
  77 * **The full build option** - Since we want to build the full libc, we pass
  78   ``-DLLVM_LIBC_FULL_BUILD=ON``.
  79 * **The target triple** - This is the target triple of the target for which
  80   we are building the libc. For example, for a Linux 32-bit Arm target,
  81   one can specify it as ``arm-linux-eabi``.
  82
  83 Build step
  84 ----------
  85
  86 After configuring the build with the above ``cmake`` command, one can build the
  87 the libc for the target with the following command:
  88
  89 .. code-block:: sh
  90
  91    $> ninja libc libm
  92
  93 The above ``ninja`` command will build the libc static archives ``libc.a`` and
  94 ``libm.a`` for the target specified with ``-DLIBC_TARGET_TRIPLE`` in the CMake
  95 configure step.
  96
  97 Runtimes cross build
  98 ====================
  99
 100 The *runtimes cross build* is very similar to the standalone crossbuild but the
 101 user will have to first build the libc build tools for the host separately. One
 102 should use this recipe if they want to use a different host and target compiler.
 103 Note that the libc build tools MUST be in sync with the libc. That is, the
 104 libc build tools and the libc, both should be built from the same source
 105 revision. At the time of this writing, there is only one libc build tool that
 106 has to be built separately. It is done as follows:
 107
 108 .. code-block:: sh
 109
 110   $> cd llvm-project  # The llvm-project checkout
 111   $> mkdir build-libc-tools # A different build directory for the build tools
 112   $> cd build-libc-tools
 113   $> HOST_C_COMPILER=<C compiler for the host> # For example "clang"
 114   $> HOST_CXX_COMPILER=<C++ compiler for the host> # For example "clang++"
 115   $> cmake ../llvm  \
 116      -G Ninja \
 117      -DLLVM_ENABLE_PROJECTS=libc  \
 118      -DCMAKE_C_COMPILER=$HOST_C_COMPILER \
 119      -DCMAKE_CXX_COMPILER=$HOST_CXX_COMPILER  \
 120      -DLLVM_LIBC_FULL_BUILD=ON \
 121      -DCMAKE_BUILD_TYPE=Debug # User can choose to use "Release" build type
 122   $> ninja libc-hdrgen
 123
 124 The above commands should build a binary named ``libc-hdrgen``. Copy this binary
 125 to a directory of your choice.
 126
 127 CMake configure step
 128 --------------------
 129
 130 After copying the ``libc-hdrgen`` binary to say ``/path/to/libc-hdrgen``,
 131 configure the libc build using the following command:
 132
 133 .. code-block:: sh
 134
 135   $> cd llvm-project  # The llvm-project checkout
 136   $> mkdir build
 137   $> cd build
 138   $> TARGET_C_COMPILER=<C compiler for the target>
 139   $> TARGET_CXX_COMPILER=<C++ compiler for the target>
 140   $> HDRGEN=</path/to/libc-hdrgen>
 141   $> TARGET_TRIPLE=<Your target triple>
 142   $> cmake ../runtimes  \
 143      -G Ninja \
 144      -DLLVM_ENABLE_RUNTIMES=libc  \
 145      -DCMAKE_C_COMPILER=$TARGET_C_COMPILER \
 146      -DCMAKE_CXX_COMPILER=$TARGET_CXX_COMPILER \
 147      -DLLVM_LIBC_FULL_BUILD=ON \
 148      -DLIBC_HDRGEN_EXE=$HDRGEN \
 149      -DLIBC_TARGET_TRIPLE=$TARGET_TRIPLE \
 150      -DCMAKE_BUILD_TYPE=Debug # User can choose to use "Release" build type
 151
 152 Note the differences in the above cmake command versus the one used in the
 153 CMake configure step of the standalone build recipe:
 154
 155 * Instead of listing ``libc`` in ``LLVM_ENABLED_PROJECTS``, we list it in
 156   ``LLVM_ENABLED_RUNTIMES``.
 157 * Instead of using ``llvm-project/llvm`` as the root CMake source directory,
 158   we use ``llvm-project/runtimes`` as the root CMake source directory.
 159 * The path to the ``libc-hdrgen`` binary built earlier is specified with
 160   ``-DLIBC_HDRGEN_EXE=/path/to/libc-hdrgen``.
 161
 162 Build step
 163 ----------
 164
 165 The build step in the runtimes build recipe is exactly the same as that of
 166 the standalone build recipe:
 167
 168 .. code-block:: sh
 169
 170     $> ninja libc libm
 171
 172 As with the standalone build recipe, the above ninja command will build the
 173 libc static archives for the target specified with ``-DLIBC_TARGET_TRIPLE`` in
 174 the CMake configure step.
 175
 176
 177 Bootstrap cross build
 178 =====================
 179
 180 In this recipe, the clang compiler and the ``libc-hdrgen`` binary, both are
 181 built automatically before building the libc for the target.
 182
 183 CMake configure step
 184 --------------------
 185
 186 .. code-block:: sh
 187
 188   $> cd llvm-project  # The llvm-project checkout
 189   $> mkdir build
 190   $> cd build
 191   $> C_COMPILER=<C compiler> # For example "clang"
 192   $> CXX_COMPILER=<C++ compiler> # For example "clang++"
 193   $> TARGET_TRIPLE=<Your target triple>
 194   $> cmake ../llvm \
 195      -G Ninja \
 196      -DCMAKE_C_COMPILER=$C_COMPILER \
 197      -DCMAKE_CXX_COMPILER=$CXX_COMPILER \
 198      -DLLVM_ENABLE_PROJECTS=clang \
 199      -DLLVM_ENABLE_RUNTIMES=libc \
 200      -DLLVM_LIBC_FULL_BUILD=ON \
 201      -DLLVM_RUNTIME_TARGETS=$TARGET_TRIPLE \
 202      -DCMAKE_BUILD_TYPE=Debug
 203
 204 Note how the above cmake command differs from the one used in the other two
 205 recipes:
 206
 207 * ``clang`` is listed in ``-DLLVM_ENABLE_PROJECTS`` and ``libc`` is
 208   listed in ``-DLLVM_ENABLE_RUNTIMES``.
 209 * The CMake root source directory is ``llvm-project/llvm``.
 210 * The target triple is specified with ``-DLLVM_RUNTIME_TARGETS``.
 211
 212 Build step
 213 ----------
 214
 215 The build step is similar to the other two recipes:
 216
 217 .. code-block:: sh
 218
 219   $> ninja libc
 220
 221 The above ninja command should build the libc static archives for the target
 222 specified with ``-DLLVM_RUNTIME_TARGETS``.
 223
 224 Building for bare metal
 225 =======================
 226
 227 To build for bare metal, all one has to do is to specify the
 228 `system <https://clang.llvm.org/docs/CrossCompilation.html#target-triple>`_
 229 component of the target triple as ``none``. For example, to build for a
 230 32-bit arm target on bare metal, one can use a target triple like
 231 ``arm-none-eabi``. Other than that, the libc for a bare metal target can be
 232 built using any of the three recipes described above.