[llvm] r190282 - Cross-compilation doc
Renato Golin
renato.golin at linaro.org
Sun Sep 8 13:44:48 PDT 2013
Author: rengolin
Date: Sun Sep 8 15:44:48 2013
New Revision: 190282
URL: http://llvm.org/viewvc/llvm-project?rev=190282&view=rev
Log:
Cross-compilation doc
Added:
llvm/trunk/docs/HowToCrossCompileLLVM.rst
Modified:
llvm/trunk/docs/index.rst
Added: llvm/trunk/docs/HowToCrossCompileLLVM.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/HowToCrossCompileLLVM.rst?rev=190282&view=auto
==============================================================================
--- llvm/trunk/docs/HowToCrossCompileLLVM.rst (added)
+++ llvm/trunk/docs/HowToCrossCompileLLVM.rst Sun Sep 8 15:44:48 2013
@@ -0,0 +1,178 @@
+===================================================================
+How To Cross-Compile Clang/LLVM using Clang/LLVM
+===================================================================
+
+Introduction
+============
+
+This document contains information about building LLVM and
+Clang on host machine, targeting another platform.
+
+For more information on how to use Clang as a cross-compiler,
+please check http://clang.llvm.org/docs/CrossCompilation.html.
+
+TODO: Add MIPS and other platforms to this document.
+
+Cross-Compiling from x86_64 to ARM
+==================================
+
+In this use case, we'll be using CMake and Ninja, on a Debian-based Linux
+system, cross-compiling from an x86_64 host (most Intel and AMD chips
+nowadays) to a hard-float ARM target (most ARM targets nowadays).
+
+The packages you'll need are:
+
+ * cmake
+ * ninja-build (from backports in Ubuntu)
+ * gcc-4.7-arm-linux-gnueabihf
+ * gcc-4.7-multilib-arm-linux-gnueabihf
+ * binutils-arm-linux-gnueabihf
+ * libgcc1-armhf-cross
+ * libsfgcc1-armhf-cross
+ * libstdc++6-armhf-cross
+ * libstdc++6-4.7-dev-armhf-cross
+
+Configuring CMake
+-----------------
+
+For more information on how to configure CMake for LLVM/Clang,
+see :doc:`CMake`.
+
+The CMake options you need to add are:
+ * -DCMAKE_CROSSCOMPILING=True
+ * -DCMAKE_INSTALL_PREFIX=<install-dir>
+ * -DLLVM_TABLEGEN=<path-to-host-bin>/llvm-tblgen
+ * -DCLANG_TABLEGEN=<path-to-host-bin>/clang-tblgen
+ * -DLLVM_DEFAULT_TARGET_TRIPLE=arm-linux-gnueabihf
+ * -DLLVM_TARGET_ARCH=ARM
+ * -DLLVM_TARGETS_TO_BUILD=ARM
+ * -DCMAKE_CXX_FLAGS='-target armv7a-linux-gnueabihf -mcpu=cortex-a9
+ -I/usr/arm-linux-gnueabihf/include/c++/4.7.2/arm-linux-gnueabihf/
+ -I/usr/arm-linux-gnueabihf/include/ -mfloat-abi=hard
+ -ccc-gcc-name arm-linux-gnueabihf-gcc'
+
+The TableGen options are required to compile it with the host compiler,
+so you'll need to compile LLVM (or at least `llvm-tblgen`) to your host
+platform before you start. The CXX flags define the target, cpu (which
+defaults to fpu=VFP3 with NEON), and forcing the hard-float ABI. If you're
+using Clang as a cross-compiler, you will *also* have to set ``-ccc-gcc-name``,
+to make sure it picks the correct linker.
+
+Most of the time, what you want is to have a native compiler to the
+platform itself, but not others. It might not even be feasible to
+produce x86 binaries from ARM targets, so there's no point in compiling
+all back-ends. For that reason, you should also set the "TARGETS_TO_BUILD"
+to only build the ARM back-end.
+
+You must set the CMAKE_INSTALL_PREFIX, otherwise a ``ninja install``
+will copy ARM binaries to your root filesystem, which is not what you
+want.
+
+Hacks
+-----
+
+There are some bugs in current LLVM, which require some fiddling before
+running CMake:
+
+#. If you're using Clang as the cross-compiler, there is a problem in
+ the LLVM ARM back-end that is producing absolute relocations on
+ position-independent code (R_ARM_THM_MOVW_ABS_NC), so for now, you
+ should disable PIC:
+
+ .. code-block:: bash
+
+ -DLLVM_ENABLE_PIC=False
+
+ This is not a problem, since Clang/LLVM libraries are statically
+ linked anyway, it shouldn't affect much.
+
+#. The ARM libraries won't be installed in your system, and possibly
+ not easily installable anyway, so you'll have to build/download
+ them separately. But the CMake prepare step, which check for
+ dependencies, will check the `host` libraries, not the `target`
+ ones.
+
+ A quick way of getting the libraries is to download them from
+ a distribution repository, like Debian (http://packages.debian.org/wheezy/),
+ and download the missing libraries. Note that the `libXXX`
+ will have the shared objects (.so) and the `libXXX-dev` will
+ give you the headers and the static (.a) library. Just in
+ case, download both.
+
+ The ones you need for ARM are: ``libtinfo``, ``zlib1g``,
+ ``libxml2`` and ``liblzma``. In the Debian repository you'll
+ find downloads for all architectures.
+
+ After you download and unpack all `.deb` packages, copy all
+ ``.so`` and ``.a`` to a directory, make the appropriate
+ symbolic links (if necessary), and add the relevant ``-L``
+ and ``-I`` paths to -DCMAKE_CXX_FLAGS above.
+
+
+Running CMake and Building
+--------------------------
+
+Finally, if you're using your platform compiler, run:
+
+ .. code-block:: bash
+
+ $ cmake -G Ninja <source-dir> <options above>
+
+If you're using Clang as the cross-compiler, run:
+
+ .. code-block:: bash
+
+ $ CC='clang' CXX='clang++' cmake -G Ninja <source-dir> <options above>
+
+If you have clang/clang++ on the path, it should just work, and special
+Ninja files will be created in the build directory. I strongly suggest
+you to run cmake on a separate build directory, *not* inside the
+source tree.
+
+To build, simply type:
+
+ .. code-block:: bash
+
+ $ ninja
+
+It should automatically find out how many cores you have, what are
+the rules that needs building and will build the whole thing.
+
+You can't run ``ninja check-all`` on this tree because the created
+binaries are targeted to ARM, not x86_64.
+
+Installing and Using
+--------------------
+
+After the LLVM/Clang has built successfully, you should install it
+via:
+
+ .. code-block:: bash
+
+ $ ninja install
+
+which will create a sysroot on the install-dir. You can then TarGz
+that directory into a binary with the full triple name (for easy
+identification), like:
+
+ .. code-block:: bash
+
+ $ ln -sf <install-dir> arm-linux-gnueabihf-clang
+ $ tar zchf arm-linux-gnueabihf-clang.tar.gz arm-linux-gnueabihf-clang
+
+If you copy that TarBall to your target board, you'll be able to use
+it for running the test-suite, for example. Follow the guidelines at
+http://llvm.org/docs/lnt/quickstart.html, unpack the TarBall in the
+test directory, and use options:
+
+ .. code-block:: bash
+
+ $ ./sandbox/bin/python sandbox/bin/lnt runtest nt \
+ --sandbox sandbox \
+ --test-suite `pwd`/test-suite \
+ --cc `pwd`/arm-linux-gnueabihf-clang/bin/clang \
+ --cxx `pwd`/arm-linux-gnueabihf-clang/bin/clang++
+
+Remember to add the ``-jN`` options to ``lnt`` to the number of CPUs
+on your board. Also, the path to your clang has to be absolute, so
+you'll need the `pwd` trick above.
Modified: llvm/trunk/docs/index.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=190282&r1=190281&r2=190282&view=diff
==============================================================================
--- llvm/trunk/docs/index.rst (original)
+++ llvm/trunk/docs/index.rst Sun Sep 8 15:44:48 2013
@@ -66,6 +66,7 @@ representation.
CMake
HowToBuildOnARM
+ HowToCrossCompileLLVM
CommandGuide/index
GettingStarted
GettingStartedVS
@@ -95,6 +96,9 @@ representation.
:doc:`HowToBuildOnARM`
Notes on building and testing LLVM/Clang on ARM.
+:doc:`HowToCrossCompileLLVM`
+ Notes on cross-building and testing LLVM/Clang.
+
:doc:`GettingStartedVS`
An addendum to the main Getting Started guide for those using Visual Studio
on Windows.
More information about the llvm-commits
mailing list