Porting GHC to a new platform

NOTE: Versions supported: 6.11+.

This section describes how to port GHC to a currently
unsupported platform. To avoid confusion, when we say
"architecture" we are referring to the processor, and
we use the term "platform" to refer to the combination
of architecture and operating system.

The first step in porting to a new platform is to get an
unregisterised build working. An unregisterised build is one that
compiles via vanilla C only. This costs about a factor of two in
performance, but since unregisterised compilation is usually just a step
on the way to a full registerised port, we don't mind too much.

You should go through this process even if your architecture is already
has registerised support in GHC, but your OS currently isn't supported.
In this case you probably won't need to port any of the
architecture-specific parts of the code, and you can proceed straight
from the unregisterised build to build a registerised compiler.

Notes on GHC portability in general: we've tried to stick
to writing portable code in most parts of the system, so it
should compile on any POSIXish system with gcc, but in our
experience most systems differ from the standards in one way or
another. Deal with any problems as they arise - if you get
stuck, ask the experts on glasgow-haskell-users@….

Lots of useful information about the innards of GHC is available in
the Commentary, which might be helpful if you run into some
code which needs tweaking for your system.

Cross-compiling to produce an unregisterised GHC

NOTE! These instructions apply to GHC 6.11 and (hopefully) later.

In this section, we explain how to bootstrap GHC on a new platform,
using unregisterised intermediate C files. We haven't put a great
deal of effort into automating this process, for two reasons: it is
done very rarely, and the process usually requires human intervention
to cope with minor porting issues anyway.

The following step-by-step instructions should result in a fully
working, albeit unregisterised, GHC. Firstly, you need a machine that
already has a working GHC (we'll call this the host machine), in
order to cross-compile the intermediate C files that we will use to
bootstrap the compiler on the target machine. We'll assume that you
are porting to platform plat, e.g. plat may be
x86_64-unknown-linux.

On the target machine

Unpack a source tree (preferably a released
version). We will call the path to the root of this
tree <T>.

In the instructions that follow, "<T>$ cmd" means that the current directory should be <T> when executing the command "cmd".

If your target platform requires it, then you may need to set CFLAGS appropriately here, e.g.

You might need to update configure.ac to recognise the new
platform, and re-generate configure with autoreconf.

If necessary on your platform, you may again need to create a mk/build.mk
to pass any necessary flags to gcc, e.g.:

SRC_CC_OPTS += -m64

As of June 23rd, 2009, GHC HQ has exorcised and split out GMP from the runtime
system into the separate 'integer-gmp' package. If you are bootstrapping a
compiler and are going to use integer-gmp for your Integer type, instead of
'integer-simple' which is a pure Haskell equivalent, then you will need to
run configure in libraries/integer-gmp here as well:

<T>$ cd libraries/integer-gmp
<T>$ ./configure
<T>$ cd ../..

ToDo: explain how to use the 'integer-simple' package.

Then:

<T>$ make bootstrapping-files

On the host machine

Unpack a source tree (exactly the same version as before). Call this directory <H>.

Copy <T>/includes/ghcautoconf.h,
<T>/includes/DerivedConstants.h, and
<T>/includes/GHCConstants.h to <H>/includes.
Note that we are building on the host machine, using the
target machine's configuration files. This
is so that the intermediate C files generated here will
be suitable for compiling on the target system.

Now build the compiler:

<H>$ make

You may need to work around problems that occur due to differences
between the host and target platforms. You may also need to use make -k
in order to ignore unimportant build failures in the RTS.

Don't bother with running make install in the newly bootstrapped
tree; just use the compiler in that tree to build a fresh compiler
from scratch, this time without booting from C files. Before doing
this, you might want to check that the bootstrapped compiler is
generating working binaries:

Once you have the unregisterised compiler up and running, you can use
it to start a registerised port. The following sections describe the
various parts of the system that will need architecture-specific
tweaks in order to get a registerised build going.

Porting the RTS

The following files need architecture-specific code for a registerised
build:

includes/MachRegs.h

Defines the STG-register to machine-register
mapping. You need to know your platform's C calling
convention, and which registers are generally available
for mapping to global register variables. There are
plenty of useful comments in this file.

includes/TailCalls.h

Macros that cooperate with the mangler (see The mangler)
to make proper tail-calls work.

rts/Adjustor.c

Support for foreign import "wrapper".
Not essential for getting GHC bootstrapped, so this file
can be deferred until later if necessary.

rts/StgCRun.c

The little assembly layer between the C world and
the Haskell world. See the comments and code for the
other architectures in this file for pointers.

rts/sm/MBlock.h, rts/sm/MBlock.c

These files are really OS-specific rather than
architecture-specific. In MBlock.h
is specified the absolute location at which the RTS
should try to allocate memory on your platform (try to
find an area which doesn't conflict with code or dynamic
libraries). In Mblock.c you might
need to tweak the call to mmap() for
your OS.

The mangler

The mangler is abstracted to a certain extent over some
architecture-specific things such as the particular assembler
directives used to herald symbols. Take a look at the definitions for
other architectures and use these as a starting point for porting it to
your platform.

The splitter

The splitter is another evil Perl script
(driver/split/ghc-split.lprl). It cooperates with the
mangler to support object splitting. Object splitting is what happens
when the -split-objs option is passed to GHC: the object file is
split into many smaller objects. This feature is used when building
libraries, so that a program statically linked against the library
will pull in less of the library.

The splitter has some platform-specific stuff; take a look and tweak
it for your system.

The native code generator

The native code generator isn't essential to getting a
registerised build going, but it's a desirable thing to have
because it can cut compilation times in half. The native code
generator is described in detail in Commentary/Compiler/Backends/NCG.

GHCi

To support GHCi, you need to port the dynamic linker
(rts/Linker.c). The linker currently supports the
ELF and PEi386 object file formats - if your platform uses one of
these then things will be significantly easier. The majority of Unix
platforms use the ELF format these days. Even so, there are some
machine-specific parts of the ELF linker: for example, the code for
resolving particular relocation types is machine-specific, so some
porting of this code to your architecture and/or OS will probably be
necessary.

If your system uses a different object file format, then
you have to write a linker -- good luck!