docs/HowToCrossCompileLLVM.rst

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