From 8216947d4df12c76a35cbcfa32c7708f1c02438e Mon Sep 17 00:00:00 2001 From: Renato Golin Date: Sun, 8 Sep 2013 20:44:48 +0000 Subject: Cross-compilation doc git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@190282 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/HowToCrossCompileLLVM.rst | 178 +++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 4 + 2 files changed, 182 insertions(+) create mode 100644 docs/HowToCrossCompileLLVM.rst (limited to 'docs') diff --git a/docs/HowToCrossCompileLLVM.rst b/docs/HowToCrossCompileLLVM.rst new file mode 100644 index 0000000000..0e3298f793 --- /dev/null +++ b/docs/HowToCrossCompileLLVM.rst @@ -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= + * -DLLVM_TABLEGEN=/llvm-tblgen + * -DCLANG_TABLEGEN=/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 + +If you're using Clang as the cross-compiler, run: + + .. code-block:: bash + + $ CC='clang' CXX='clang++' cmake -G Ninja + +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 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. diff --git a/docs/index.rst b/docs/index.rst index 4bf86a2bd9..af54fddaa0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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. -- cgit v1.2.3