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 .. note::
  12    Fullbuild requires running headergen, which is a python program that depends on
  13    pyyaml. The minimum versions are listed on the :ref:`header_generation`
  14    page, as well as additional information.
  15
  16 In this document, we will present recipes to cross build the full libc. When we
  17 say *cross build* a full libc, we mean that we will build the full libc for a
  18 target system which is not the same as the system on which the libc is being
  19 built. For example, you could be building for a bare metal aarch64 *target* on a
  20 Linux x86_64 *host*.
  21
  22 There are two main recipes to cross build the full libc. Each one serves a
  23 different use case. Below is a short description of these recipes to help users
  24 pick the recipe that best suites their needs and contexts.
  25
  26 * **Standalone cross build** - Using this recipe one can build the libc using a
  27   compiler of their choice. One should use this recipe if their compiler can
  28   build for the host as well as the target.
  29 * **Bootstrap cross build** - In this recipe, one will build the ``clang``
  30   compiler and the libc build tools for the host first, and then use them to
  31   build the libc for the target. Unlike with the standalone build recipe, the
  32   user does not have explicitly build ``clang`` and other build tools.
  33   They get built automatically before building the libc. One should use this
  34   recipe if they intend use the built ``clang`` and the libc as part of their
  35   toolchain for the target.
  36
  37 The following sections present the two recipes in detail.
  38
  39 Standalone cross build
  40 ======================
  41
  42 In the *standalone crossbuild* recipe, the system compiler or a custom compiler
  43 of user's choice is used to build the libc. The necessary build tools for the
  44 host are built first, and those build tools are then used to build the libc for
  45 the target. Both these steps happen automatically, as in, the user does not have
  46 to explicitly build the build tools first and then build the libc. A point to
  47 keep in mind is that the compiler used should be capable of building for the
  48 host as well as the target.
  49
  50 CMake configure step
  51 --------------------
  52
  53 Below is the CMake command to configure the standalone crossbuild of the libc.
  54
  55 .. code-block:: sh
  56
  57   $> cd llvm-project  # The llvm-project checkout
  58   $> mkdir build
  59   $> cd build
  60   $> C_COMPILER=<C compiler> # For example "clang"
  61   $> CXX_COMPILER=<C++ compiler> # For example "clang++"
  62   $> cmake ../runtimes  \
  63      -G Ninja \
  64      -DLLVM_ENABLE_RUNTIMES=libc  \
  65      -DCMAKE_C_COMPILER=$C_COMPILER \
  66      -DCMAKE_CXX_COMPILER=$CXX_COMPILER \
  67      -DLLVM_LIBC_FULL_BUILD=ON \
  68      -DLIBC_TARGET_TRIPLE=<Your target triple> \
  69      -DCMAKE_BUILD_TYPE=<Release|Debug>
  70
  71 We will go over the special options passed to the ``cmake`` command above.
  72
  73 * **Enabled Runtimes** - Since we want to build LLVM-libc, we list
  74   ``libc`` as the enabled runtime.
  75 * **The full build option** - Since we want to build the full libc, we pass
  76   ``-DLLVM_LIBC_FULL_BUILD=ON``.
  77 * **The target triple** - This is the target triple of the target for which
  78   we are building the libc. For example, for a Linux 32-bit Arm target,
  79   one can specify it as ``arm-linux-eabi``.
  80
  81 Build step
  82 ----------
  83
  84 After configuring the build with the above ``cmake`` command, one can build the
  85 the libc for the target with the following command:
  86
  87 .. code-block:: sh
  88
  89    $> ninja libc libm
  90
  91 The above ``ninja`` command will build the libc static archives ``libc.a`` and
  92 ``libm.a`` for the target specified with ``-DLIBC_TARGET_TRIPLE`` in the CMake
  93 configure step.
  94
  95 Bootstrap cross build
  96 =====================
  97
  98 In this recipe, the clang compiler and the ``libc-hdrgen`` binary, both are
  99 built automatically before building the libc for the target.
 100
 101 CMake configure step
 102 --------------------
 103
 104 .. code-block:: sh
 105
 106   $> cd llvm-project  # The llvm-project checkout
 107   $> mkdir build
 108   $> cd build
 109   $> C_COMPILER=<C compiler> # For example "clang"
 110   $> CXX_COMPILER=<C++ compiler> # For example "clang++"
 111   $> TARGET_TRIPLE=<Your target triple>
 112   $> cmake ../llvm \
 113      -G Ninja \
 114      -DCMAKE_C_COMPILER=$C_COMPILER \
 115      -DCMAKE_CXX_COMPILER=$CXX_COMPILER \
 116      -DLLVM_ENABLE_PROJECTS=clang \
 117      -DLLVM_ENABLE_RUNTIMES=libc \
 118      -DLLVM_LIBC_FULL_BUILD=ON \
 119      -DLLVM_RUNTIME_TARGETS=$TARGET_TRIPLE \
 120      -DCMAKE_BUILD_TYPE=Debug
 121
 122 Note how the above cmake command differs from the one used in the other recipe:
 123
 124 * ``clang`` is listed in ``-DLLVM_ENABLE_PROJECTS`` and ``libc`` is
 125   listed in ``-DLLVM_ENABLE_RUNTIMES``.
 126 * The CMake root source directory is ``llvm-project/llvm``.
 127 * The target triple is specified with ``-DLLVM_RUNTIME_TARGETS``.
 128
 129 Build step
 130 ----------
 131
 132 The build step is similar to the other recipe:
 133
 134 .. code-block:: sh
 135
 136   $> ninja libc
 137
 138 The above ninja command should build the libc static archives for the target
 139 specified with ``-DLLVM_RUNTIME_TARGETS``.
 140
 141 Building for bare metal
 142 =======================
 143
 144 To build for bare metal, all one has to do is to specify the
 145 `system <https://clang.llvm.org/docs/CrossCompilation.html#target-triple>`_
 146 component of the target triple as ``none``. For example, to build for a
 147 32-bit arm target on bare metal, one can use a target triple like
 148 ``arm-none-eabi``. Other than that, the libc for a bare metal target can be
 149 built using any of the three recipes described above.
 150
 151 Building for the GPU
 152 ====================
 153
 154 To build for a GPU architecture, it should only be necessary to specify the
 155 target triple as one of the supported GPU targets. Currently, this is either
 156 ``nvptx64-nvidia-cuda`` for NVIDIA GPUs or ``amdgcn-amd-amdhsa`` for AMD GPUs.
 157 More detailed information is provided in the :ref:`GPU
 158 documentation<libc_gpu_building>`.