|Version 7 (modified by simonmar, 4 years ago) (diff)|
This page describes how to do cross-compilation with GHC. That is:
- Building GHC as a cross-compiler: Create a compiler that runs on one platform, but targets another. Examples are building a GHC that:
- runs on Mac OS X, but targets iOS
- runs on x86_64 linux, but targets i386
- runs on some existing GHC supported platform, but targets a smaller embedded platform
- Cross-compiling GHC itself: Build on one platform a compiler that runs on, and targets another. Examples:
- TakeoffGW is a distribution of Unix tools for Windows, built by cross-compiling on a Linux machine. They would like to be able to build and distribute GHC this way. It might be useful for us to be able to cross-compile a Windows GHC from Linux too.
- build a 64-bit GHC on OS X, by cross-compiling using the 32-bit version.
- We could port to Win64 (#1884) by cross-compiling using a 32-bit Windows GHC.
- Other porting tasks might be easier, given a suitable cross-compilation toolchain.
Terminology and background
(For more background and design docs see CrossCompilation.)
Traditional cross-compilation terminology defines three platforms:
- build - the platform we're building on
- host - the platform the compiler will run on
- target - the platform the compiler we're building will generate code for
These are the platforms given to the configure script when configuring the build.
GHC does not support all three platforms being different. The rule is:
- build must equal host
We'll see why that is if we consider which platforms the various parts of the build use.
- Stage 0: the GHC that is already on the build system (the one you specify using --with-ghc when configuring the build), comes with a set of built libs, could be older than the version of GHC being built
- libs boot: libs that the current version of GHC being built relies on that are either absent or too old in older versions of GHC that might be being used as Stage 0. These libs are built with Stage 0 GHC, and linked into the Stage 1 GHC being built.
- Stage 1: the first GHC built, compiled by the Stage 0 GHC, and linked with both libs from that GHC installation, and the boot libs.
- libs install: libs that are built by the Stage 1 GHC, and installed by make install.
- Stage 2: the final GHC built, compiled by the Stage 1 GHC, and linked with libs-install
|Stage 0||libs boot||Stage 1||libs install||Stage 2|
(this is not the only way we could have done it, for more rationale see CrossCompilation)
So in order to use the stage 1 compiler to build libs-install, we must be able to run it, and hence host must be the same as build. You never need to specify host, just specify target when making a cross-compiler.
So considering the two cases we identified at the top of the page:
- Building GHC as a cross-compiler - this is the stage 1 compiler
- Cross-compiling GHC itself - this is the stage 2 compiler
both of these cases are handled in the same way.
Tools to install
First you want to install a C compiler and related tools that generate code for your target platform. You'll need:
- C libraries
(basically gcc + binutils + libc). These need to be installed somewhere different from your native gcc & binutils so they don't conflict. We assume that your gcc knows where its libraries live, otherwise you will probably need to add more flags to your build.mk settings to tell it.
(ToDo: what if we're using LLVM?)
Also install the other tools needed to build GHC on your platform: see Building/Preparation.
Configuring the build
To configure the build:
./configure --target=<target> --with-gcc=<gcc> --with-ld=<ld> --with-nm=<nm> --with-objdump=<objdump>
Note: if you are cross-compiling for a platform that doesn't have a native code generator or registerised LLVM support, then you should add
(the build system will probably do this automatically for you anyway, but it doesn't hurt to be explicit)
If you are only interested in building a cross-compiler, then you can add
Stage1Only = YES
to your mk/build.mk, and the build system will stop before building stage 2. The resulting cross-compiler and tools can be installed as usual with 'make install'.
Extra packages can be installed using cabal with your cross-compiler. The recipe is:
$ cabal --with-ghc=<cross-ghc> --with-ld=<ld> ...
You can do this even without installing your cross-compiler, just use $TOP/inplace/bin/ghc-stage1 as <cross-ghc>.
(the --with-ld option shouldn't really be required, hopefully this will get fixed at some point).