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 -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.