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 http://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 * ``-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
51The TableGen options are required to compile it with the host compiler,
52so you'll need to compile LLVM (or at least ``llvm-tblgen``) to your host
53platform before you start. The CXX flags define the target, cpu (which
54defaults to ``fpu=VFP3`` with NEON), and forcing the hard-float ABI. If you're
55using Clang as a cross-compiler, you will *also* have to set ``-ccc-gcc-name``,
56to make sure it picks the correct linker.
57
58Most of the time, what you want is to have a native compiler to the
59platform itself, but not others. It might not even be feasible to
60produce x86 binaries from ARM targets, so there's no point in compiling
61all back-ends. For that reason, you should also set the
62``TARGETS_TO_BUILD`` to only build the ARM back-end.
63
64You must set the ``CMAKE_INSTALL_PREFIX``, otherwise a ``ninja install``
65will copy ARM binaries to your root filesystem, which is not what you
66want.
67
68Hacks
69-----
70
71There are some bugs in current LLVM, which require some fiddling before
72running 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
109Running CMake and Building
110--------------------------
111
112Finally, if you're using your platform compiler, run:
113
114   .. code-block:: bash
115
116     $ cmake -G Ninja <source-dir> <options above>
117
118If 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
124If you have ``clang``/``clang++`` on the path, it should just work, and special
125Ninja files will be created in the build directory. I strongly suggest
126you to run ``cmake`` on a separate build directory, *not* inside the
127source tree.
128
129To build, simply type:
130
131   .. code-block:: bash
132
133     $ ninja
134
135It should automatically find out how many cores you have, what are
136the rules that needs building and will build the whole thing.
137
138You can't run ``ninja check-all`` on this tree because the created
139binaries are targeted to ARM, not x86_64.
140
141Installing and Using
142--------------------
143
144After the LLVM/Clang has built successfully, you should install it
145via:
146
147   .. code-block:: bash
148
149     $ ninja install
150
151which will create a sysroot on the install-dir. You can then tar
152that directory into a binary with the full triple name (for easy
153identification), 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
160If you copy that tarball to your target board, you'll be able to use
161it for running the test-suite, for example. Follow the guidelines at
162http://llvm.org/docs/lnt/quickstart.html, unpack the tarball in the
163test 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
173Remember to add the ``-jN`` options to ``lnt`` to the number of CPUs
174on your board. Also, the path to your clang has to be absolute, so
175you'll need the `pwd` trick above.
176