/usr/share/doc/clang-3.7-doc/html/CrossCompilation.html is in clang-3.7-doc 1:3.7.1-2ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Cross-compilation using Clang — Clang 3.7 documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '3.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="top" title="Clang 3.7 documentation" href="index.html" />
<link rel="next" title="Thread Safety Analysis" href="ThreadSafetyAnalysis.html" />
<link rel="prev" title="Attributes in Clang" href="AttributeReference.html" />
</head>
<body role="document">
<div class="header" role="banner"><h1 class="heading"><a href="index.html">
<span>Clang 3.7 documentation</span></a></h1>
<h2 class="heading"><span>Cross-compilation using Clang</span></h2>
</div>
<div class="topnav" role="navigation" aria-label="top navigation">
<p>
«  <a href="AttributeReference.html">Attributes in Clang</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="ThreadSafetyAnalysis.html">Thread Safety Analysis</a>  »
</p>
</div>
<div class="content">
<div class="section" id="cross-compilation-using-clang">
<h1>Cross-compilation using Clang<a class="headerlink" href="#cross-compilation-using-clang" title="Permalink to this headline">¶</a></h1>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>This document will guide you in choosing the right Clang options
for cross-compiling your code to a different architecture. It assumes you
already know how to compile the code in question for the host architecture,
and that you know how to choose additional include and library paths.</p>
<p>However, this document is <em>not</em> a “how to” and won’t help you setting your
build system or Makefiles, nor choosing the right CMake options, etc.
Also, it does not cover all the possible options, nor does it contain
specific examples for specific architectures. For a concrete example, the
<a class="reference external" href="http://llvm.org/docs/HowToCrossCompileLLVM.html">instructions for cross-compiling LLVM itself</a> may be of interest.</p>
<p>After reading this document, you should be familiar with the main issues
related to cross-compilation, and what main compiler options Clang provides
for performing cross-compilation.</p>
</div>
<div class="section" id="cross-compilation-issues">
<h2>Cross compilation issues<a class="headerlink" href="#cross-compilation-issues" title="Permalink to this headline">¶</a></h2>
<p>In GCC world, every host/target combination has its own set of binaries,
headers, libraries, etc. So, it’s usually simple to download a package
with all files in, unzip to a directory and point the build system to
that compiler, that will know about its location and find all it needs to
when compiling your code.</p>
<p>On the other hand, Clang/LLVM is natively a cross-compiler, meaning that
one set of programs can compile to all targets by setting the <code class="docutils literal"><span class="pre">-target</span></code>
option. That makes it a lot easier for programers wishing to compile to
different platforms and architectures, and for compiler developers that
only have to maintain one build system, and for OS distributions, that
need only one set of main packages.</p>
<p>But, as is true to any cross-compiler, and given the complexity of
different architectures, OS’s and options, it’s not always easy finding
the headers, libraries or binutils to generate target specific code.
So you’ll need special options to help Clang understand what target
you’re compiling to, where your tools are, etc.</p>
<p>Another problem is that compilers come with standard libraries only (like
<code class="docutils literal"><span class="pre">compiler-rt</span></code>, <code class="docutils literal"><span class="pre">libcxx</span></code>, <code class="docutils literal"><span class="pre">libgcc</span></code>, <code class="docutils literal"><span class="pre">libm</span></code>, etc), so you’ll have to
find and make available to the build system, every other library required
to build your software, that is specific to your target. It’s not enough to
have your host’s libraries installed.</p>
<p>Finally, not all toolchains are the same, and consequently, not every Clang
option will work magically. Some options, like <code class="docutils literal"><span class="pre">--sysroot</span></code> (which
effectively changes the logical root for headers and libraries), assume
all your binaries and libraries are in the same directory, which may not
true when your cross-compiler was installed by the distribution’s package
management. So, for each specific case, you may use more than one
option, and in most cases, you’ll end up setting include paths (<code class="docutils literal"><span class="pre">-I</span></code>) and
library paths (<code class="docutils literal"><span class="pre">-L</span></code>) manually.</p>
<dl class="docutils">
<dt>To sum up, different toolchains can:</dt>
<dd><ul class="first last simple">
<li>be host/target specific or more flexible</li>
<li>be in a single directory, or spread out across your system</li>
<li>have different sets of libraries and headers by default</li>
<li>need special options, which your build system won’t be able to figure
out by itself</li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="general-cross-compilation-options-in-clang">
<h2>General Cross-Compilation Options in Clang<a class="headerlink" href="#general-cross-compilation-options-in-clang" title="Permalink to this headline">¶</a></h2>
<div class="section" id="target-triple">
<h3>Target Triple<a class="headerlink" href="#target-triple" title="Permalink to this headline">¶</a></h3>
<p>The basic option is to define the target architecture. For that, use
<code class="docutils literal"><span class="pre">-target</span> <span class="pre"><triple></span></code>. If you don’t specify the target, CPU names won’t
match (since Clang assumes the host triple), and the compilation will
go ahead, creating code for the host platform, which will break later
on when assembling or linking.</p>
<dl class="docutils">
<dt>The triple has the general format <code class="docutils literal"><span class="pre"><arch><sub>-<vendor>-<sys>-<abi></span></code>, where:</dt>
<dd><ul class="first last simple">
<li><code class="docutils literal"><span class="pre">arch</span></code> = <code class="docutils literal"><span class="pre">x86</span></code>, <code class="docutils literal"><span class="pre">arm</span></code>, <code class="docutils literal"><span class="pre">thumb</span></code>, <code class="docutils literal"><span class="pre">mips</span></code>, etc.</li>
<li><code class="docutils literal"><span class="pre">sub</span></code> = for ex. on ARM: <code class="docutils literal"><span class="pre">v5</span></code>, <code class="docutils literal"><span class="pre">v6m</span></code>, <code class="docutils literal"><span class="pre">v7a</span></code>, <code class="docutils literal"><span class="pre">v7m</span></code>, etc.</li>
<li><code class="docutils literal"><span class="pre">vendor</span></code> = <code class="docutils literal"><span class="pre">pc</span></code>, <code class="docutils literal"><span class="pre">apple</span></code>, <code class="docutils literal"><span class="pre">nvidia</span></code>, <code class="docutils literal"><span class="pre">ibm</span></code>, etc.</li>
<li><code class="docutils literal"><span class="pre">sys</span></code> = <code class="docutils literal"><span class="pre">none</span></code>, <code class="docutils literal"><span class="pre">linux</span></code>, <code class="docutils literal"><span class="pre">win32</span></code>, <code class="docutils literal"><span class="pre">darwin</span></code>, <code class="docutils literal"><span class="pre">cuda</span></code>, etc.</li>
<li><code class="docutils literal"><span class="pre">abi</span></code> = <code class="docutils literal"><span class="pre">eabi</span></code>, <code class="docutils literal"><span class="pre">gnu</span></code>, <code class="docutils literal"><span class="pre">android</span></code>, <code class="docutils literal"><span class="pre">macho</span></code>, <code class="docutils literal"><span class="pre">elf</span></code>, etc.</li>
</ul>
</dd>
</dl>
<p>The sub-architecture options are available for their own architectures,
of course, so “x86v7a” doesn’t make sense. The vendor needs to be
specified only if there’s a relevant change, for instance between PC
and Apple. Most of the time it can be omitted (and Unknown)
will be assumed, which sets the defaults for the specified architecture.
The system name is generally the OS (linux, darwin), but could be special
like the bare-metal “none”.</p>
<p>When a parameter is not important, it can be omitted, or you can
choose <code class="docutils literal"><span class="pre">unknown</span></code> and the defaults will be used. If you choose a parameter
that Clang doesn’t know, like <code class="docutils literal"><span class="pre">blerg</span></code>, it’ll ignore and assume
<code class="docutils literal"><span class="pre">unknown</span></code>, which is not always desired, so be careful.</p>
<p>Finally, the ABI option is something that will pick default CPU/FPU,
define the specific behaviour of your code (PCS, extensions),
and also choose the correct library calls, etc.</p>
</div>
<div class="section" id="cpu-fpu-abi">
<h3>CPU, FPU, ABI<a class="headerlink" href="#cpu-fpu-abi" title="Permalink to this headline">¶</a></h3>
<p>Once your target is specified, it’s time to pick the hardware you’ll
be compiling to. For every architecture, a default set of CPU/FPU/ABI
will be chosen, so you’ll almost always have to change it via flags.</p>
<dl class="docutils">
<dt>Typical flags include:</dt>
<dd><ul class="first last simple">
<li><code class="docutils literal"><span class="pre">-mcpu=<cpu-name></span></code>, like x86-64, swift, cortex-a15</li>
<li><code class="docutils literal"><span class="pre">-mfpu=<fpu-name></span></code>, like SSE3, NEON, controlling the FP unit available</li>
<li><code class="docutils literal"><span class="pre">-mfloat-abi=<fabi></span></code>, like soft, hard, controlling which registers
to use for floating-point</li>
</ul>
</dd>
</dl>
<p>The default is normally the common denominator, so that Clang doesn’t
generate code that breaks. But that also means you won’t get the best
code for your specific hardware, which may mean orders of magnitude
slower than you expect.</p>
<p>For example, if your target is <code class="docutils literal"><span class="pre">arm-none-eabi</span></code>, the default CPU will
be <code class="docutils literal"><span class="pre">arm7tdmi</span></code> using soft float, which is extremely slow on modern cores,
whereas if your triple is <code class="docutils literal"><span class="pre">armv7a-none-eabi</span></code>, it’ll be Cortex-A8 with
NEON, but still using soft-float, which is much better, but still not
great.</p>
</div>
<div class="section" id="toolchain-options">
<h3>Toolchain Options<a class="headerlink" href="#toolchain-options" title="Permalink to this headline">¶</a></h3>
<p>There are three main options to control access to your cross-compiler:
<code class="docutils literal"><span class="pre">--sysroot</span></code>, <code class="docutils literal"><span class="pre">-I</span></code>, and <code class="docutils literal"><span class="pre">-L</span></code>. The two last ones are well known,
but they’re particularly important for additional libraries
and headers that are specific to your target.</p>
<p>There are two main ways to have a cross-compiler:</p>
<ol class="arabic">
<li><p class="first">When you have extracted your cross-compiler from a zip file into
a directory, you have to use <code class="docutils literal"><span class="pre">--sysroot=<path></span></code>. The path is the
root directory where you have unpacked your file, and Clang will
look for the directories <code class="docutils literal"><span class="pre">bin</span></code>, <code class="docutils literal"><span class="pre">lib</span></code>, <code class="docutils literal"><span class="pre">include</span></code> in there.</p>
<p>In this case, your setup should be pretty much done (if no
additional headers or libraries are needed), as Clang will find
all binaries it needs (assembler, linker, etc) in there.</p>
</li>
<li><p class="first">When you have installed via a package manager (modern Linux
distributions have cross-compiler packages available), make
sure the target triple you set is <em>also</em> the prefix of your
cross-compiler toolchain.</p>
<p>In this case, Clang will find the other binaries (assembler,
linker), but not always where the target headers and libraries
are. People add system-specific clues to Clang often, but as
things change, it’s more likely that it won’t find than the
other way around.</p>
<p>So, here, you’ll be a lot safer if you specify the include/library
directories manually (via <code class="docutils literal"><span class="pre">-I</span></code> and <code class="docutils literal"><span class="pre">-L</span></code>).</p>
</li>
</ol>
</div>
</div>
<div class="section" id="target-specific-libraries">
<h2>Target-Specific Libraries<a class="headerlink" href="#target-specific-libraries" title="Permalink to this headline">¶</a></h2>
<p>All libraries that you compile as part of your build will be
cross-compiled to your target, and your build system will probably
find them in the right place. But all dependencies that are
normally checked against (like <code class="docutils literal"><span class="pre">libxml</span></code> or <code class="docutils literal"><span class="pre">libz</span></code> etc) will match
against the host platform, not the target.</p>
<p>So, if the build system is not aware that you want to cross-compile
your code, it will get every dependency wrong, and your compilation
will fail during build time, not configure time.</p>
<p>Also, finding the libraries for your target are not as easy
as for your host machine. There aren’t many cross-libraries available
as packages to most OS’s, so you’ll have to either cross-compile them
from source, or download the package for your target platform,
extract the libraries and headers, put them in specific directories
and add <code class="docutils literal"><span class="pre">-I</span></code> and <code class="docutils literal"><span class="pre">-L</span></code> pointing to them.</p>
<p>Also, some libraries have different dependencies on different targets,
so configuration tools to find dependencies in the host can get the
list wrong for the target platform. This means that the configuration
of your build can get things wrong when setting their own library
paths, and you’ll have to augment it via additional flags (configure,
Make, CMake, etc).</p>
<div class="section" id="multilibs">
<h3>Multilibs<a class="headerlink" href="#multilibs" title="Permalink to this headline">¶</a></h3>
<p>When you want to cross-compile to more than one configuration, for
example hard-float-ARM and soft-float-ARM, you’ll have to have multiple
copies of your libraries and (possibly) headers.</p>
<p>Some Linux distributions have support for Multilib, which handle that
for you in an easier way, but if you’re not careful and, for instance,
forget to specify <code class="docutils literal"><span class="pre">-ccc-gcc-name</span> <span class="pre">armv7l-linux-gnueabihf-gcc</span></code> (which
uses hard-float), Clang will pick the <code class="docutils literal"><span class="pre">armv7l-linux-gnueabi-ld</span></code>
(which uses soft-float) and linker errors will happen.</p>
<p>The same is true if you’re compiling for different ABIs, like <code class="docutils literal"><span class="pre">gnueabi</span></code>
and <code class="docutils literal"><span class="pre">androideabi</span></code>, and might even link and run, but produce run-time
errors, which are much harder to track down and fix.</p>
</div>
</div>
</div>
</div>
<div class="bottomnav" role="navigation" aria-label="bottom navigation">
<p>
«  <a href="AttributeReference.html">Attributes in Clang</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="ThreadSafetyAnalysis.html">Thread Safety Analysis</a>  »
</p>
</div>
<div class="footer" role="contentinfo">
© Copyright 2007-2015, The Clang Team.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.6.
</div>
</body>
</html>
|