Skip to content

Commit d24899b

Browse files
rengolinrengolin
committed
Cross-compilation doc
llvm-svn: 190282
1 parent f70e35d commit d24899b

File tree

2 files changed

+182
-0
lines changed

2 files changed

+182
-0
lines changed

‎llvm/docs/HowToCrossCompileLLVM.rst

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
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.

‎llvm/docs/index.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ representation.
6666

6767
CMake
6868
HowToBuildOnARM
69+
HowToCrossCompileLLVM
6970
CommandGuide/index
7071
GettingStarted
7172
GettingStartedVS
@@ -95,6 +96,9 @@ representation.
9596
:doc:`HowToBuildOnARM`
9697
Notes on building and testing LLVM/Clang on ARM.
9798

99+
:doc:`HowToCrossCompileLLVM`
100+
Notes on cross-building and testing LLVM/Clang.
101+
98102
:doc:`GettingStartedVS`
99103
An addendum to the main Getting Started guide for those using Visual Studio
100104
on Windows.

0 commit comments

Comments
 (0)