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