1 =================================================================== 2 How To Cross-Compile Clang/LLVM using Clang/LLVM 3 =================================================================== 4 5 Introduction 6 ============ 7 8 This document contains information about building LLVM and 9 Clang on host machine, targeting another platform. 10 11 For more information on how to use Clang as a cross-compiler, 12 please check http://clang.llvm.org/docs/CrossCompilation.html. 13 14 TODO: Add MIPS and other platforms to this document. 15 16 Cross-Compiling from x86_64 to ARM 17 ================================== 18 19 In this use case, we'll be using CMake and Ninja, on a Debian-based Linux 20 system, cross-compiling from an x86_64 host (most Intel and AMD chips 21 nowadays) to a hard-float ARM target (most ARM targets nowadays). 22 23 The 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 35 Configuring CMake 36 ----------------- 37 38 For more information on how to configure CMake for LLVM/Clang, 39 see :doc:`CMake`. 40 41 The CMake options you need to add are: 42 * ``-DCMAKE_CROSSCOMPILING=True`` 43 * ``-DCMAKE_INSTALL_PREFIX=<install-dir>`` 44 * ``-DLLVM_TABLEGEN=<path-to-host-bin>/llvm-tblgen`` 45 * ``-DCLANG_TABLEGEN=<path-to-host-bin>/clang-tblgen`` 46 * ``-DLLVM_DEFAULT_TARGET_TRIPLE=arm-linux-gnueabihf`` 47 * ``-DLLVM_TARGET_ARCH=ARM`` 48 * ``-DLLVM_TARGETS_TO_BUILD=ARM`` 49 * ``-DCMAKE_CXX_FLAGS='-target armv7a-linux-gnueabihf -mcpu=cortex-a9 -I/usr/arm-linux-gnueabihf/include/c++/4.7.2/arm-linux-gnueabihf/ -I/usr/arm-linux-gnueabihf/include/ -mfloat-abi=hard -ccc-gcc-name arm-linux-gnueabihf-gcc'`` 50 51 The TableGen options are required to compile it with the host compiler, 52 so you'll need to compile LLVM (or at least ``llvm-tblgen``) to your host 53 platform before you start. The CXX flags define the target, cpu (which 54 defaults to ``fpu=VFP3`` with NEON), and forcing the hard-float ABI. If you're 55 using Clang as a cross-compiler, you will *also* have to set ``-ccc-gcc-name``, 56 to make sure it picks the correct linker. 57 58 Most of the time, what you want is to have a native compiler to the 59 platform itself, but not others. It might not even be feasible to 60 produce x86 binaries from ARM targets, so there's no point in compiling 61 all back-ends. For that reason, you should also set the 62 ``TARGETS_TO_BUILD`` to only build the ARM back-end. 63 64 You must set the ``CMAKE_INSTALL_PREFIX``, otherwise a ``ninja install`` 65 will copy ARM binaries to your root filesystem, which is not what you 66 want. 67 68 Hacks 69 ----- 70 71 There are some bugs in current LLVM, which require some fiddling before 72 running CMake: 73 74 #. If you're using Clang as the cross-compiler, there is a problem in 75 the LLVM ARM back-end that is producing absolute relocations on 76 position-independent code (``R_ARM_THM_MOVW_ABS_NC``), so for now, you 77 should disable PIC: 78 79 .. code-block:: bash 80 81 -DLLVM_ENABLE_PIC=False 82 83 This is not a problem, since Clang/LLVM libraries are statically 84 linked anyway, it shouldn't affect much. 85 86 #. The ARM libraries won't be installed in your system, and possibly 87 not easily installable anyway, so you'll have to build/download 88 them separately. But the CMake prepare step, which checks for 89 dependencies, will check the *host* libraries, not the *target* 90 ones. 91 92 A quick way of getting the libraries is to download them from 93 a distribution repository, like Debian (http://packages.debian.org/wheezy/), 94 and download the missing libraries. Note that the ``libXXX`` 95 will have the shared objects (``.so``) and the ``libXXX-dev`` will 96 give you the headers and the static (``.a``) library. Just in 97 case, download both. 98 99 The ones you need for ARM are: ``libtinfo``, ``zlib1g``, 100 ``libxml2`` and ``liblzma``. In the Debian repository you'll 101 find downloads for all architectures. 102 103 After you download and unpack all ``.deb`` packages, copy all 104 ``.so`` and ``.a`` to a directory, make the appropriate 105 symbolic links (if necessary), and add the relevant ``-L`` 106 and ``-I`` paths to ``-DCMAKE_CXX_FLAGS`` above. 107 108 109 Running CMake and Building 110 -------------------------- 111 112 Finally, if you're using your platform compiler, run: 113 114 .. code-block:: bash 115 116 $ cmake -G Ninja <source-dir> <options above> 117 118 If you're using Clang as the cross-compiler, run: 119 120 .. code-block:: bash 121 122 $ CC='clang' CXX='clang++' cmake -G Ninja <source-dir> <options above> 123 124 If you have ``clang``/``clang++`` on the path, it should just work, and special 125 Ninja files will be created in the build directory. I strongly suggest 126 you to run ``cmake`` on a separate build directory, *not* inside the 127 source tree. 128 129 To build, simply type: 130 131 .. code-block:: bash 132 133 $ ninja 134 135 It should automatically find out how many cores you have, what are 136 the rules that needs building and will build the whole thing. 137 138 You can't run ``ninja check-all`` on this tree because the created 139 binaries are targeted to ARM, not x86_64. 140 141 Installing and Using 142 -------------------- 143 144 After the LLVM/Clang has built successfully, you should install it 145 via: 146 147 .. code-block:: bash 148 149 $ ninja install 150 151 which will create a sysroot on the install-dir. You can then tar 152 that directory into a binary with the full triple name (for easy 153 identification), like: 154 155 .. code-block:: bash 156 157 $ ln -sf <install-dir> arm-linux-gnueabihf-clang 158 $ tar zchf arm-linux-gnueabihf-clang.tar.gz arm-linux-gnueabihf-clang 159 160 If you copy that tarball to your target board, you'll be able to use 161 it for running the test-suite, for example. Follow the guidelines at 162 http://llvm.org/docs/lnt/quickstart.html, unpack the tarball in the 163 test directory, and use options: 164 165 .. code-block:: bash 166 167 $ ./sandbox/bin/python sandbox/bin/lnt runtest nt \ 168 --sandbox sandbox \ 169 --test-suite `pwd`/test-suite \ 170 --cc `pwd`/arm-linux-gnueabihf-clang/bin/clang \ 171 --cxx `pwd`/arm-linux-gnueabihf-clang/bin/clang++ 172 173 Remember to add the ``-jN`` options to ``lnt`` to the number of CPUs 174 on your board. Also, the path to your clang has to be absolute, so 175 you'll need the `pwd` trick above. 176
