replica
/
hanchenye-llvm-project
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[docs] Typographical and rewording fixes. 

llvm-svn: 190333
This commit is contained in:
Sean Silva 2013-09-09 19:30:44 +00:00
parent fff7f8a4ed
commit 7a8b6ca2d1
1 changed files with 42 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
clang/docs/CrossCompilation.rst
View File

@ -5,20 +5,21 @@ Cross-compilation using Clang/LLVM
Introduction Introduction
============ ============
This document will guide you in choosing the right cross-compilation options This document will guide you in choosing the right Clang options
to hopefully help you target your code to a different architecture. It assumes for cross-compiling your code to a different architecture. It assumes you
you already know how to compile the code in question for the host architecture, 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. and that you know how to choose additional include and library paths.
However, this document is `not` a `HowTo` and wont help you setting your build However, this document is *not* a "how to" and won't help you setting your
system or Makefiles, nor choosing the right CMake options. Also, it does not build system or Makefiles, nor choosing the right CMake options, etc.
cover all the possible options, nor it contains specific examples for specific Also, it does not cover all the possible options, nor does it contain
architectures. There are other documents in LLVM that do that in greater specific examples for specific architectures. For a concrete example, the
details (ex. http://llvm.org/docs/HowToCrossCompileLLVM.html). `instructions for cross-compiling LLVM itself
<http://llvm.org/docs/HowToCrossCompileLLVM.html>`_ may be of interest.
After reading this document, you should be familiar with the main issues After reading this document, you should be familiar with the main issues
related to, and what main compiler options Clang provides for performing related to cross-compilation, and what main compiler options Clang provides
cross-compilation. for performing cross-compilation.
Cross compilation issues Cross compilation issues
======================== ========================
@ -30,36 +31,36 @@ that compiler, that will know about its location and find all it needs to
when compiling your code. when compiling your code.
On the other hand, Clang/LLVM is natively a cross-compiler, meaning that 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 -target one set of programs can compile to all targets by setting the ``-target``
option. That makes it a lot easier to programers wishing to compile to option. That makes it a lot easier for programers wishing to compile to
different platforms and architectures, and to compiler developers that different platforms and architectures, and for compiler developers that
only have to maintain one build system, and to OS distributions, that only have to maintain one build system, and for OS distributions, that
need only one set of main packages. need only one set of main packages.
But, as is true to any cross-compiler, and given the complexity of But, as is true to any cross-compiler, and given the complexity of
different architectures, OSs and options, it's not always easy finding different architectures, OS's and options, it's not always easy finding
the headers, libraries or binutils to generate target specific code. the headers, libraries or binutils to generate target specific code.
So you'll need special options to help Clang understand what target So you'll need special options to help Clang understand what target
you're compiling to, where are your tools, etc. you're compiling to, where your tools are, etc.
Another problem is that compilers come with standard libraries only (like Another problem is that compilers come with standard libraries only (like
icompiler-rt, libcxx, libgcc, libm, etc), so you'll have to find and make ``compiler-rt``, ``libcxx``, ``libgcc``, ``libm``, etc), so you'll have to
available to the build system, every other library required to build your find and make available to the build system, every other library required
software, that is specific to your target. It's not enough to have your to build your software, that is specific to your target. It's not enough to
host's libraries installed. have your host's libraries installed.
Finally, not all toolchains are the same, and consequently, not every Clang Finally, not all toolchains are the same, and consequently, not every Clang
option will work magically. Some options, like --sysroot (which option will work magically. Some options, like ``--sysroot`` (which
effectively changes the logical root for headers and libraries), assume effectively changes the logical root for headers and libraries), assume
all your binaries and libraries are in the same directory, which may not 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 true when your cross-compiler was installed by the distribution's package
management. So, for each specific case, you may use more than one management. So, for each specific case, you may use more than one
option, and in most cases, you'll end up setting include paths (-I) and option, and in most cases, you'll end up setting include paths (``-I``) and
library paths (-L) manually. library paths (``-L``) manually.
To sum up, different toolchains can: To sum up, different toolchains can:
* be host/target specific or more flexible * be host/target specific or more flexible
* be in a single directory, or spread out your system * be in a single directory, or spread out across your system
* have different sets of libraries and headers by default * have different sets of libraries and headers by default
* need special options, which your build system won't be able to figure * need special options, which your build system won't be able to figure
out by itself out by itself
@ -77,11 +78,11 @@ go ahead, creating code for the host platform, which will break later
on when assembling or linking. on when assembling or linking.
The triple has the general format ``<arch><sub>-<vendor>-<sys>-<abi>``, where: The triple has the general format ``<arch><sub>-<vendor>-<sys>-<abi>``, where:
* ``arch`` = x86, arm, thumb, mips, etc. * ``arch`` = ``x86``, ``arm``, ``thumb``, ``mips``, etc.
* ``sub`` = for ex. on ARM: v5, v6m, v7a, v7m, etc. * ``sub`` = for ex. on ARM: ``v5``, ``v6m``, ``v7a``, ``v7m``, etc.
* ``vendor`` = pc, apple, nvidia, ibm, etc. * ``vendor`` = ``pc``, ``apple``, ``nvidia``, ``ibm``, etc.
* ``sys`` = none, linux, win32, darwin, cuda, etc. * ``sys`` = ``none``, ``linux``, ``win32``, ``darwin``, ``cuda``, etc.
* ``abi`` = eabi, gnu, android, macho, elf, etc. * ``abi`` = ``eabi``, ``gnu``, ``android``, ``macho``, ``elf``, etc.
The sub-architecture options are available for their own architectures, The sub-architecture options are available for their own architectures,
of course, so "x86v7a" doesn't make sense. The vendor needs to be of course, so "x86v7a" doesn't make sense. The vendor needs to be
@ -92,9 +93,9 @@ The system name is generally the OS (linux, darwin), but could be special
like the bare-metal "none". like the bare-metal "none".
When a parameter is not important, they can be omitted, or you can When a parameter is not important, they can be omitted, or you can
choose "unknown" and the defaults will be used. If you choose a parameter choose ``unknown`` and the defaults will be used. If you choose a parameter
that Clang doesn't know, like "blerg", it'll ignore and assume `Unknown`, that Clang doesn't know, like ``blerg``, it'll ignore and assume
which is not always desired, so be careful. ``unknown``, which is not always desired, so be careful.
Finally, the ABI option is something that will pick default CPU/FPU, Finally, the ABI option is something that will pick default CPU/FPU,
define the specific behaviour of your code (PCS, extensions), define the specific behaviour of your code (PCS, extensions),
@ -118,17 +119,17 @@ 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 code for your specific hardware, which may mean orders of magnitude
slower than you expect. slower than you expect.
For example, if your target is "arm-none-eabi", the default CPU will For example, if your target is ``arm-none-eabi``, the default CPU will
be "arm7tdmi" using soft float, which is extremely slow on modern cores, be ``arm7tdmi`` using soft float, which is extremely slow on modern cores,
whereas if your triple is "armv7a-none-eabi", it'll be Cortex-A8 with whereas if your triple is ``armv7a-none-eabi``, it'll be Cortex-A8 with
NEON, but still using soft-float, which is much better, but still not NEON, but still using soft-float, which is much better, but still not
great. great.
Toolchain Options Toolchain Options
----------------- -----------------
There are four main options to control access to your cross-compiler: There are three main options to control access to your cross-compiler:
``--sysroot``, ``-I`` and ``-L``. The two last ones are well known, ``--sysroot``, ``-I``, and ``-L``. The two last ones are well known,
but they're particularly important for additional libraries but they're particularly important for additional libraries
and headers that are specific to your target. and headers that are specific to your target.
@ -145,7 +146,7 @@ There are two main ways to have a cross-compiler:
#. When you have installed via a package manager (modern Linux #. When you have installed via a package manager (modern Linux
distributions have cross-compiler packages available), make distributions have cross-compiler packages available), make
sure the target triple you set is `also` the prefix of your sure the target triple you set is *also* the prefix of your
cross-compiler toolchain. cross-compiler toolchain.
In this case, Clang will find the other binaries (assembler, In this case, Clang will find the other binaries (assembler,
@ -163,7 +164,7 @@ Target-Specific Libraries
All libraries that you compile as part of your build will be All libraries that you compile as part of your build will be
cross-compiled to your target, and your build system will probably cross-compiled to your target, and your build system will probably
find them in the right place. But all dependencies that are find them in the right place. But all dependencies that are
normally checked against (like libxml or libz etc) will match normally checked against (like ``libxml`` or ``libz`` etc) will match
against the host platform, not the target. against the host platform, not the target.
So, if the build system is not aware that you want to cross-compile So, if the build system is not aware that you want to cross-compile
@ -172,7 +173,7 @@ will fail during build time, not configure time.
Also, finding the libraries for your target are not as easy Also, finding the libraries for your target are not as easy
as for your host machine. There aren't many cross-libraries available as for your host machine. There aren't many cross-libraries available
as packages to most OSs, so you'll have to either cross-compile them 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, from source, or download the package for your target platform,
extract the libraries and headers, put them in specific directories extract the libraries and headers, put them in specific directories
and add ``-I`` and ``-L`` pointing to them. and add ``-I`` and ``-L`` pointing to them.
@ -199,5 +200,5 @@ uses hard-float), Clang will pick the ``armv7l-linux-gnueabi-ld``
The same is true if you're compiling for different ABIs, like ``gnueabi`` The same is true if you're compiling for different ABIs, like ``gnueabi``
and ``androideabi``, and might even link and run, but produce run-time and ``androideabi``, and might even link and run, but produce run-time
errors, which are much harder to track and fix. errors, which are much harder to track down and fix.