1=================================================================== 2How To Cross-Compile Clang/LLVM using Clang/LLVM 3=================================================================== 4 5Introduction 6============ 7 8This document contains information about building LLVM and 9Clang on host machine, targeting another platform. 10 11For more information on how to use Clang as a cross-compiler, 12please check https://clang.llvm.org/docs/CrossCompilation.html. 13 14TODO: Add MIPS and other platforms to this document. 15 16Cross-Compiling from x86_64 to ARM 17================================== 18 19In this use case, we'll be using CMake and Ninja, on a Debian-based Linux 20system, cross-compiling from an x86_64 host (most Intel and AMD chips 21nowadays) to a hard-float ARM target (most ARM targets nowadays). 22 23The packages you'll need are: 24 25 * ``cmake`` 26 * ``ninja-build`` (from backports in Ubuntu) 27 * ``gcc-4.7-arm-linux-gnueabihf`` 28 * ``gcc-4.7-multilib-arm-linux-gnueabihf`` 29 * ``binutils-arm-linux-gnueabihf`` 30 * ``libgcc1-armhf-cross`` 31 * ``libsfgcc1-armhf-cross`` 32 * ``libstdc++6-armhf-cross`` 33 * ``libstdc++6-4.7-dev-armhf-cross`` 34 35Configuring CMake 36----------------- 37 38For more information on how to configure CMake for LLVM/Clang, 39see :doc:`CMake`. 40 41The CMake options you need to add are: 42 43 * ``-DCMAKE_SYSTEM_NAME=<target-system>`` 44 * ``-DCMAKE_INSTALL_PREFIX=<install-dir>`` 45 * ``-DLLVM_HOST_TRIPLE=arm-linux-gnueabihf`` 46 * ``-DLLVM_TARGETS_TO_BUILD=ARM`` 47 48Note: ``CMAKE_CROSSCOMPILING`` is always set automatically when ``CMAKE_SYSTEM_NAME`` is set. Don't put ``-DCMAKE_CROSSCOMPILING=TRUE`` in your options. 49 50Also note that ``LLVM_HOST_TRIPLE`` specifies the triple of the system 51that the cross built LLVM is going to run on - the flag is named based 52on the autoconf build/host/target nomenclature. (This flag implicitly sets 53other defaults, such as ``LLVM_DEFAULT_TARGET_TRIPLE``.) 54 55If you're compiling with GCC, you can use architecture options for your target, 56and the compiler driver will detect everything that it needs: 57 58 * ``-DCMAKE_CXX_FLAGS='-march=armv7-a -mcpu=cortex-a9 -mfloat-abi=hard'`` 59 60However, if you're using Clang, the driver might not be up-to-date with your 61specific Linux distribution, version or GCC layout, so you'll need to fudge. 62 63In addition to the ones above, you'll also need: 64 65 * ``--target=arm-linux-gnueabihf`` or whatever is the triple of your cross GCC. 66 * ``'--sysroot=/usr/arm-linux-gnueabihf'``, ``'--sysroot=/opt/gcc/arm-linux-gnueabihf'`` 67 or whatever is the location of your GCC's sysroot (where /lib, /bin etc are). 68 * Appropriate use of ``-I`` and ``-L``, depending on how the cross GCC is installed, 69 and where are the libraries and headers. 70 71You may also want to set the ``LLVM_NATIVE_TOOL_DIR`` option - pointing 72at a directory with prebuilt LLVM tools (``llvm-tblgen``, ``clang-tblgen`` 73etc) for the build host, allowing you to them reuse them if available. 74E.g. ``-DLLVM_NATIVE_TOOL_DIR=<path-to-native-llvm-build>/bin``. 75If the option isn't set (or the directory doesn't contain all needed tools), 76the LLVM cross build will automatically launch a nested build to build the 77tools that are required. 78 79The CXX flags define the target, cpu (which in this case 80defaults to ``fpu=VFP3`` with NEON), and forcing the hard-float ABI. If you're 81using Clang as a cross-compiler, you will *also* have to set ``--sysroot`` 82to make sure it picks the correct linker. 83 84When using Clang, it's important that you choose the triple to be *identical* 85to the GCC triple and the sysroot. This will make it easier for Clang to 86find the correct tools and include headers. But that won't mean all headers and 87libraries will be found. You'll still need to use ``-I`` and ``-L`` to locate 88those extra ones, depending on your distribution. 89 90Most of the time, what you want is to have a native compiler to the 91platform itself, but not others. So there's rarely a point in compiling 92all back-ends. For that reason, you should also set the 93``TARGETS_TO_BUILD`` to only build the back-end you're targeting to. 94 95You must set the ``CMAKE_INSTALL_PREFIX``, otherwise a ``ninja install`` 96will copy ARM binaries to your root filesystem, which is not what you 97want. 98 99Hacks 100----- 101 102There are some bugs in current LLVM, which require some fiddling before 103running CMake: 104 105#. If you're using Clang as the cross-compiler, there is a problem in 106 the LLVM ARM back-end that is producing absolute relocations on 107 position-independent code (``R_ARM_THM_MOVW_ABS_NC``), so for now, you 108 should disable PIC: 109 110 .. code-block:: bash 111 112 -DLLVM_ENABLE_PIC=False 113 114 This is not a problem, since Clang/LLVM libraries are statically 115 linked anyway, it shouldn't affect much. 116 117#. The ARM libraries won't be installed in your system. 118 But the CMake prepare step, which checks for 119 dependencies, will check the *host* libraries, not the *target* 120 ones. Below there's a list of some dependencies, but your project could 121 have more, or this document could be outdated. You'll see the errors 122 while linking as an indication of that. 123 124 Debian based distros have a way to add ``multiarch``, which adds 125 a new architecture and allows you to install packages for those 126 systems. See https://wiki.debian.org/Multiarch/HOWTO for more info. 127 128 But not all distros will have that, and possibly not an easy way to 129 install them in any anyway, so you'll have to build/download 130 them separately. 131 132 A quick way of getting the libraries is to download them from 133 a distribution repository, like Debian (http://packages.debian.org/jessie/), 134 and download the missing libraries. Note that the ``libXXX`` 135 will have the shared objects (``.so``) and the ``libXXX-dev`` will 136 give you the headers and the static (``.a``) library. Just in 137 case, download both. 138 139 The ones you need for ARM are: ``libtinfo``, ``zlib1g``, 140 ``libxml2`` and ``liblzma``. In the Debian repository you'll 141 find downloads for all architectures. 142 143 After you download and unpack all ``.deb`` packages, copy all 144 ``.so`` and ``.a`` to a directory, make the appropriate 145 symbolic links (if necessary), and add the relevant ``-L`` 146 and ``-I`` paths to ``-DCMAKE_CXX_FLAGS`` above. 147 148 149Running CMake and Building 150-------------------------- 151 152Finally, if you're using your platform compiler, run: 153 154 .. code-block:: bash 155 156 $ cmake -G Ninja <source-dir> -DCMAKE_BUILD_TYPE=<type> <options above> 157 158If you're using Clang as the cross-compiler, run: 159 160 .. code-block:: bash 161 162 $ CC='clang' CXX='clang++' cmake -G Ninja <source-dir> -DCMAKE_BUILD_TYPE=<type> <options above> 163 164If you have ``clang``/``clang++`` on the path, it should just work, and special 165Ninja files will be created in the build directory. I strongly suggest 166you to run ``cmake`` on a separate build directory, *not* inside the 167source tree. 168 169To build, simply type: 170 171 .. code-block:: bash 172 173 $ ninja 174 175It should automatically find out how many cores you have, what are 176the rules that needs building and will build the whole thing. 177 178You can't run ``ninja check-all`` on this tree because the created 179binaries are targeted to ARM, not x86_64. 180 181Installing and Using 182-------------------- 183 184After the LLVM/Clang has built successfully, you should install it 185via: 186 187 .. code-block:: bash 188 189 $ ninja install 190 191which will create a sysroot on the install-dir. You can then tar 192that directory into a binary with the full triple name (for easy 193identification), like: 194 195 .. code-block:: bash 196 197 $ ln -sf <install-dir> arm-linux-gnueabihf-clang 198 $ tar zchf arm-linux-gnueabihf-clang.tar.gz arm-linux-gnueabihf-clang 199 200If you copy that tarball to your target board, you'll be able to use 201it for running the test-suite, for example. Follow the guidelines at 202https://llvm.org/docs/lnt/quickstart.html, unpack the tarball in the 203test directory, and use options: 204 205 .. code-block:: bash 206 207 $ ./sandbox/bin/python sandbox/bin/lnt runtest nt \ 208 --sandbox sandbox \ 209 --test-suite `pwd`/test-suite \ 210 --cc `pwd`/arm-linux-gnueabihf-clang/bin/clang \ 211 --cxx `pwd`/arm-linux-gnueabihf-clang/bin/clang++ 212 213Remember to add the ``-jN`` options to ``lnt`` to the number of CPUs 214on your board. Also, the path to your clang has to be absolute, so 215you'll need the `pwd` trick above. 216