Changes

Page history
Instructions for 6.11 authored by ian@well-typed.com's avatar ian@well-typed.com
Show whitespace changes
Inline Side-by-side
building/porting.md
View page @ 22c4d8da
......@@ -82,39 +82,21 @@ libraries:
## Porting GHC to a new platform
**NOTE**: Versions supported: between 6.0.1 and 6.6.2. We are working
on getting bootstrapping working again in the 6.8 series, see [\#1346](https://gitlab.haskell.org//ghc/ghc/issues/1346).
**NOTE**: Versions supported: 6.11+.
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. By contrast, a registerised build uses
the following architecture-specific hacks for speed:
- Global register variables: certain abstract machine "registers" are
mapped to real machine registers, depending on how many machine
registers are available (see [includes/MachRegs.h](/trac/ghc/browser/ghc/includes/MachRegs.h)).
- Assembly-mangling: when compiling via C, we feed the assembly
generated by gcc though a Perl script known as the *mangler* (see
[driver/mangler/ghc-asm.lprl](/trac/ghc/browser/ghc/driver/mangler/ghc-asm.lprl). The mangler rearranges
the assembly to support tail-calls and various other optimisations.
compiles via vanilla C only. Tist 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.
In an unregisterised build, neither of these hacks are
used -- the idea is that the C code generated by the
compiler should compile using gcc only. The lack of these
optimisations 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.
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
......@@ -132,11 +114,7 @@ code which needs tweaking for your system.
### Cross-compiling to produce an unregisterised GHC
NOTE! These instructions apply to GHC 6.4 and (hopefully)
later. If you need instructions for an earlier version of GHC, try
to get hold of the version of this document that was current at the
time. It should be available from the appropriate download page on
the [GHC homepage](http://www.haskell.org/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,
......@@ -148,10 +126,9 @@ 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.
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.
**On the target machine**
......@@ -162,7 +139,8 @@ tree `<T>`.
```wiki
$ cd <T>
$ ./configure --enable-hc-boot --enable-hc-boot-unregisterised
$ sh boot
$ ./configure --enable-hc-boot
```
......@@ -170,8 +148,7 @@ You might need to update `configure.ac` to recognise the new
platform, and re-generate `configure` with `autoreconf`.
```wiki
$ cd <T>/includes
$ make
$ make bootstrapping-files
```
**On the host machine**
......@@ -181,6 +158,7 @@ Unpack a source tree (same released version, with the extra libs). Call this di
```wiki
$ cd <H>
$ sh boot
$ ./configure
```
......@@ -191,19 +169,18 @@ Create `<H>/mk/build.mk`, with the following contents:
GhcUnregisterised = YES
GhcLibHcOpts = -O -fvia-C -keep-hc-files
GhcRtsHcOpts = -keep-hc-files
GhcLibWays =
GhcLibWays = v
SplitObjs = NO
GhcWithNativeCodeGen = NO
GhcWithInterpreter = NO
GhcStage1HcOpts = -O
GhcStage2HcOpts = -O -fvia-C -keep-hc-files
SRC_HC_OPTS += -H32m
GhcBootLibs = YES
GhcWithSMP = NO
```
Edit `<H>/mk/config.mk`:
Edit `<H>/mk/project.mk`:
- change `TARGETPLATFORM` appropriately, and set the variables
involving `TARGET` or `Target` to the correct values for
......@@ -222,76 +199,90 @@ is so that the intermediate C files generated here will
be suitable for compiling on the target system.
Touch the generated configuration files, just to make
sure they don't get replaced during the build:
Now build the compiler:
```wiki
$ cd <H>/includes
$ touch ghcautoconf.h DerivedConstants.h GHCConstants.h mkDerivedConstants.c
$ touch mkDerivedConstantsHdr mkDerivedConstants.o mkGHCConstants mkGHCConstants.o
$ make
```
Now build the compiler:
You may need to work around problems that occur due to differences
between the host and target platforms.
```wiki
$ cd <H>/utils/mkdependC && make boot && make
$ cd <H>/includes && make boot && make
$ cd <H>/compat && make boot && make
$ cd <H>/utils && make boot && make
$ cd <H>/compiler && make boot && make
$ cd <H>/rts && make boot && make
$ cd <H>/libraries
$ make boot && make
$ cd <H>
$ rm -f list mkfiles boot.tar.gz
$ find . -name "*.hc" >> list
$ find . -name "*_stub.*" >> list
$ find . -name package-data.mk >> list
$ find . -name package.conf >> list
$ find . -name package.conf.inplace >> list
$ echo compiler/main/Config.hs >> list
$ find . -name .depend | sed -e 's/^/mkdir -p `dirname /' -e 's/$/`/' >> mkfiles
$ find . -name .depend | sed "s/^/touch /" >> mkfiles
$ echo mkfiles >> list
$ tar -zcf boot.tar.gz -T list
```
**On the target machine**
```wiki
$ cd <H>/compiler
$ make boot stage=2 && make stage=2
$ cd <T>
$ cp /bin/pwd utils/ghc-pwd/ghc-pwd
```
```wiki
$ cd <H>/compat
$ make clean
$ rm .depend
$ make boot UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
$ cd <H>/utils
$ make clean
$ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
$ sh boot
$ ./configure --enable-hc-boot
```
Unpack `<H>/boot.tar.gz` to `<T>/`.
```wiki
$ cd <H>
$ make hc-file-bundle Project=Ghc
$ tar --touch -zxf boot.tar.gz
$ sh mkfiles
```
Unpack `<H>/*-hc.tar.gz` to `<T>/..`.
Put this in `<T>/mk/build.mk`:
```wiki
$ tar xzf <H>/*-hc.tar.gz -C <T>/..
GHC = false
GHC_PKG_INPLACE =
GHC_CABAL_INPLACE =
DUMMY_GHC_INPLACE =
UNLIT =
NO_INCLUDE_DEPS = YES
GhcUnregisterised = YES
GhcLibWays = v
SplitObjs = NO
GhcWithNativeCodeGen = NO
GhcWithInterpreter = NO
GhcWithSMP = NO
ghc_stage2_v_EXTRA_CC_OPTS += -Lgmp -lgmp -lm -lutil -lrt
```
**On the target machine**
```wiki
$ for c in libraries/*/configure; do ( cd `dirname $c`; ./configure ); done
```
```wiki
$ sed -i .bak "s/<H>/<T>/g" */*/package-data.mk */*/*/package-data.mk
$ touch -r compiler/stage2/package-data.mk */*/package-data.mk */*/*/package-data.mk
```
At this stage we simply need to bootstrap a compiler
from the intermediate C files we generated above. The
process of bootstrapping from C files is automated by the
script in `distrib/hc-build`, and is
described in [Booting/porting from C (.hc) files](#Booting/portingfromC(.hc)files).
Now make bootstrapping files; what we're really doing here is making
libffi, and libgmp if necessary:
```wiki
$ ./distrib/hc-build --enable-hc-boot-unregisterised
$ make bootstrapping-files
```
However, since this is a bootstrap on a new machine, the automated
process might not run to completion the first time. For that reason,
you might want to treat the `hc-build` script as a list of
instructions to follow, rather than as a fully automated script. This
way you'll be able to restart the process part-way through if you need
to fix anything on the way.
```wiki
$ make all_ghc_stage2 2>&1 | tee log
```
Don't bother with running `make install` in the newly bootstrapped
......@@ -304,7 +295,7 @@ generating working binaries:
$ cat >hello.hs
main = putStrLn "Hello World!\n"
^D
$ <T>/compiler/ghc-inplace hello.hs -o hello
$ <T>/inplace/bin/ghc-stage2 hello.hs -o hello
$ ./hello
Hello World!
```
......
......