blob: e655d8920ad0ee9c7359b491a44b4946f31ebbb5 [file] [log] [blame]
Renato Golinf54e02f2013-09-08 20:44:39 +00001===================================================================
Sean Silva5e2ce202013-09-09 19:50:47 +00002Cross-compilation using Clang
Renato Golinf54e02f2013-09-08 20:44:39 +00003===================================================================
4
5Introduction
6============
7
Sean Silva055d4382013-09-09 19:30:44 +00008This document will guide you in choosing the right Clang options
9for cross-compiling your code to a different architecture. It assumes you
10already know how to compile the code in question for the host architecture,
Renato Golinf54e02f2013-09-08 20:44:39 +000011and that you know how to choose additional include and library paths.
12
Sean Silva055d4382013-09-09 19:30:44 +000013However, this document is *not* a "how to" and won't help you setting your
14build system or Makefiles, nor choosing the right CMake options, etc.
15Also, it does not cover all the possible options, nor does it contain
16specific examples for specific architectures. For a concrete example, the
17`instructions for cross-compiling LLVM itself
18<http://llvm.org/docs/HowToCrossCompileLLVM.html>`_ may be of interest.
Renato Golinf54e02f2013-09-08 20:44:39 +000019
20After reading this document, you should be familiar with the main issues
Sean Silva055d4382013-09-09 19:30:44 +000021related to cross-compilation, and what main compiler options Clang provides
22for performing cross-compilation.
Renato Golinf54e02f2013-09-08 20:44:39 +000023
24Cross compilation issues
25========================
26
27In GCC world, every host/target combination has its own set of binaries,
28headers, libraries, etc. So, it's usually simple to download a package
29with all files in, unzip to a directory and point the build system to
30that compiler, that will know about its location and find all it needs to
31when compiling your code.
32
33On the other hand, Clang/LLVM is natively a cross-compiler, meaning that
Sean Silva055d4382013-09-09 19:30:44 +000034one set of programs can compile to all targets by setting the ``-target``
35option. That makes it a lot easier for programers wishing to compile to
36different platforms and architectures, and for compiler developers that
37only have to maintain one build system, and for OS distributions, that
Renato Golinf54e02f2013-09-08 20:44:39 +000038need only one set of main packages.
39
40But, as is true to any cross-compiler, and given the complexity of
Sean Silva055d4382013-09-09 19:30:44 +000041different architectures, OS's and options, it's not always easy finding
Renato Golinf54e02f2013-09-08 20:44:39 +000042the headers, libraries or binutils to generate target specific code.
43So you'll need special options to help Clang understand what target
Sean Silva055d4382013-09-09 19:30:44 +000044you're compiling to, where your tools are, etc.
Renato Golinf54e02f2013-09-08 20:44:39 +000045
46Another problem is that compilers come with standard libraries only (like
Sean Silva055d4382013-09-09 19:30:44 +000047``compiler-rt``, ``libcxx``, ``libgcc``, ``libm``, etc), so you'll have to
48find and make available to the build system, every other library required
49to build your software, that is specific to your target. It's not enough to
50have your host's libraries installed.
Renato Golinf54e02f2013-09-08 20:44:39 +000051
52Finally, not all toolchains are the same, and consequently, not every Clang
Sean Silva055d4382013-09-09 19:30:44 +000053option will work magically. Some options, like ``--sysroot`` (which
Renato Golinf54e02f2013-09-08 20:44:39 +000054effectively changes the logical root for headers and libraries), assume
55all your binaries and libraries are in the same directory, which may not
56true when your cross-compiler was installed by the distribution's package
57management. So, for each specific case, you may use more than one
Sean Silva055d4382013-09-09 19:30:44 +000058option, and in most cases, you'll end up setting include paths (``-I``) and
59library paths (``-L``) manually.
Renato Golinf54e02f2013-09-08 20:44:39 +000060
61To sum up, different toolchains can:
62 * be host/target specific or more flexible
Sean Silva055d4382013-09-09 19:30:44 +000063 * be in a single directory, or spread out across your system
Renato Golinf54e02f2013-09-08 20:44:39 +000064 * have different sets of libraries and headers by default
65 * need special options, which your build system won't be able to figure
66 out by itself
67
68General Cross-Compilation Options in Clang
69==========================================
70
71Target Triple
72-------------
73
74The basic option is to define the target architecture. For that, use
75``-target <triple>``. If you don't specify the target, CPU names won't
76match (since Clang assumes the host triple), and the compilation will
77go ahead, creating code for the host platform, which will break later
78on when assembling or linking.
79
80The triple has the general format ``<arch><sub>-<vendor>-<sys>-<abi>``, where:
Sean Silva055d4382013-09-09 19:30:44 +000081 * ``arch`` = ``x86``, ``arm``, ``thumb``, ``mips``, etc.
82 * ``sub`` = for ex. on ARM: ``v5``, ``v6m``, ``v7a``, ``v7m``, etc.
83 * ``vendor`` = ``pc``, ``apple``, ``nvidia``, ``ibm``, etc.
84 * ``sys`` = ``none``, ``linux``, ``win32``, ``darwin``, ``cuda``, etc.
85 * ``abi`` = ``eabi``, ``gnu``, ``android``, ``macho``, ``elf``, etc.
Renato Golinf54e02f2013-09-08 20:44:39 +000086
87The sub-architecture options are available for their own architectures,
88of course, so "x86v7a" doesn't make sense. The vendor needs to be
89specified only if there's a relevant change, for instance between PC
90and Apple. Most of the time it can be omitted (and Unknown)
91will be assumed, which sets the defaults for the specified architecture.
92The system name is generally the OS (linux, darwin), but could be special
93like the bare-metal "none".
94
95When a parameter is not important, they can be omitted, or you can
Sean Silva055d4382013-09-09 19:30:44 +000096choose ``unknown`` and the defaults will be used. If you choose a parameter
97that Clang doesn't know, like ``blerg``, it'll ignore and assume
98``unknown``, which is not always desired, so be careful.
Renato Golinf54e02f2013-09-08 20:44:39 +000099
100Finally, the ABI option is something that will pick default CPU/FPU,
101define the specific behaviour of your code (PCS, extensions),
102and also choose the correct library calls, etc.
103
104CPU, FPU, ABI
105-------------
106
107Once your target is specified, it's time to pick the hardware you'll
108be compiling to. For every architecture, a default set of CPU/FPU/ABI
109will be chosen, so you'll almost always have to change it via flags.
110
111Typical flags include:
112 * ``-mcpu=<cpu-name>``, like x86-64, swift, cortex-a15
113 * ``-fpu=<fpu-name>``, like SSE3, NEON, controlling the FP unit available
114 * ``-mfloat-abi=<fabi>``, like soft, hard, controlling which registers
115 to use for floating-point
116
117The default is normally the common denominator, so that Clang doesn't
118generate code that breaks. But that also means you won't get the best
119code for your specific hardware, which may mean orders of magnitude
120slower than you expect.
121
Sean Silva055d4382013-09-09 19:30:44 +0000122For example, if your target is ``arm-none-eabi``, the default CPU will
123be ``arm7tdmi`` using soft float, which is extremely slow on modern cores,
124whereas if your triple is ``armv7a-none-eabi``, it'll be Cortex-A8 with
Renato Golinf54e02f2013-09-08 20:44:39 +0000125NEON, but still using soft-float, which is much better, but still not
126great.
127
128Toolchain Options
129-----------------
130
Sean Silva055d4382013-09-09 19:30:44 +0000131There are three main options to control access to your cross-compiler:
132``--sysroot``, ``-I``, and ``-L``. The two last ones are well known,
Renato Golinf54e02f2013-09-08 20:44:39 +0000133but they're particularly important for additional libraries
134and headers that are specific to your target.
135
136There are two main ways to have a cross-compiler:
137
138#. When you have extracted your cross-compiler from a zip file into
139 a directory, you have to use ``--sysroot=<path>``. The path is the
140 root directory where you have unpacked your file, and Clang will
141 look for the directories ``bin``, ``lib``, ``include`` in there.
142
143 In this case, your setup should be pretty much done (if no
144 additional headers or libraries are needed), as Clang will find
145 all binaries it needs (assembler, linker, etc) in there.
146
147#. When you have installed via a package manager (modern Linux
148 distributions have cross-compiler packages available), make
Sean Silva055d4382013-09-09 19:30:44 +0000149 sure the target triple you set is *also* the prefix of your
Renato Golinf54e02f2013-09-08 20:44:39 +0000150 cross-compiler toolchain.
151
152 In this case, Clang will find the other binaries (assembler,
153 linker), but not always where the target headers and libraries
154 are. People add system-specific clues to Clang often, but as
155 things change, it's more likely that it won't find than the
156 other way around.
157
158 So, here, you'll be a lot safer if you specify the include/library
159 directories manually (via ``-I`` and ``-L``).
160
161Target-Specific Libraries
162=========================
163
164All libraries that you compile as part of your build will be
165cross-compiled to your target, and your build system will probably
166find them in the right place. But all dependencies that are
Sean Silva055d4382013-09-09 19:30:44 +0000167normally checked against (like ``libxml`` or ``libz`` etc) will match
Renato Golinf54e02f2013-09-08 20:44:39 +0000168against the host platform, not the target.
169
170So, if the build system is not aware that you want to cross-compile
171your code, it will get every dependency wrong, and your compilation
172will fail during build time, not configure time.
173
174Also, finding the libraries for your target are not as easy
175as for your host machine. There aren't many cross-libraries available
Sean Silva055d4382013-09-09 19:30:44 +0000176as packages to most OS's, so you'll have to either cross-compile them
Renato Golinf54e02f2013-09-08 20:44:39 +0000177from source, or download the package for your target platform,
178extract the libraries and headers, put them in specific directories
179and add ``-I`` and ``-L`` pointing to them.
180
181Also, some libraries have different dependencies on different targets,
182so configuration tools to find dependencies in the host can get the
183list wrong for the target platform. This means that the configuration
184of your build can get things wrong when setting their own library
185paths, and you'll have to augment it via additional flags (configure,
186Make, CMake, etc).
187
188Multilibs
189---------
190
191When you want to cross-compile to more than one configuration, for
192example hard-float-ARM and soft-float-ARM, you'll have to have multiple
193copies of you libraries and (possibly) headers.
194
195Some Linux distributions have support for Multilib, which handle that
196for you in an easier way, but if you're not careful and, for instance,
197forget to specify ``-ccc-gcc-name armv7l-linux-gnueabihf-gcc`` (which
198uses hard-float), Clang will pick the ``armv7l-linux-gnueabi-ld``
199(which uses soft-float) and linker errors will happen.
200
201The same is true if you're compiling for different ABIs, like ``gnueabi``
202and ``androideabi``, and might even link and run, but produce run-time
Sean Silva055d4382013-09-09 19:30:44 +0000203errors, which are much harder to track down and fix.
Renato Golinf54e02f2013-09-08 20:44:39 +0000204