1.. _full_cross_build: 2 3================ 4Full 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 16In this document, we will present recipes to cross build the full libc. When we 17say *cross build* a full libc, we mean that we will build the full libc for a 18target system which is not the same as the system on which the libc is being 19built. For example, you could be building for a bare metal aarch64 *target* on a 20Linux x86_64 *host*. 21 22There are two main recipes to cross build the full libc. Each one serves a 23different use case. Below is a short description of these recipes to help users 24pick 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 37The following sections present the two recipes in detail. 38 39Standalone cross build 40====================== 41 42In the *standalone crossbuild* recipe, the system compiler or a custom compiler 43of user's choice is used to build the libc. The necessary build tools for the 44host are built first, and those build tools are then used to build the libc for 45the target. Both these steps happen automatically, as in, the user does not have 46to explicitly build the build tools first and then build the libc. A point to 47keep in mind is that the compiler used should be capable of building for the 48host as well as the target. 49 50CMake configure step 51-------------------- 52 53Below 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 71We 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 81Build step 82---------- 83 84After configuring the build with the above ``cmake`` command, one can build the 85the libc for the target with the following command: 86 87.. code-block:: sh 88 89 $> ninja libc libm 90 91The 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 93configure step. 94 95Bootstrap cross build 96===================== 97 98In this recipe, the clang compiler and the ``libc-hdrgen`` binary, both are 99built automatically before building the libc for the target. 100 101CMake 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 122Note 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 129Build step 130---------- 131 132The build step is similar to the other recipe: 133 134.. code-block:: sh 135 136 $> ninja libc 137 138The above ninja command should build the libc static archives for the target 139specified with ``-DLLVM_RUNTIME_TARGETS``. 140 141Building for bare metal 142======================= 143 144To build for bare metal, all one has to do is to specify the 145`system <https://clang.llvm.org/docs/CrossCompilation.html#target-triple>`_ 146component of the target triple as ``none``. For example, to build for a 14732-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 149built using any of the three recipes described above. 150 151Building for the GPU 152==================== 153 154To build for a GPU architecture, it should only be necessary to specify the 155target 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. 157More detailed information is provided in the :ref:`GPU 158documentation<libc_gpu_building>`. 159