[[project @ 2003-08-28 16:30:45 by simonmar]
simonmar**20030828163045
- Revamp the "Porting GHC" guide, now that I've gone through the process
of doing a cross-compile using unregisterised HC files and written
down a set of instructions that should work.
- Update a few odds and ends that have become out of date.
] {
hunk ./docs/building/building.sgml 722
+
+ alex
+ alex
+ project
+
+ The Alex lexical
+ analyser generator for Haskell.
+
+
+
hunk ./docs/building/building.sgml 1088
+
+ x86_64-unknown-linux
+ x86_64-unknown-linux
+
+ GHC currently works unregisterised. A registerised
+ port is in progress.
+
+
+
hunk ./docs/building/building.sgml 1124
- Supported registerised. No native code
- generator.
+ Supported registerised. Native code generator is
+ almost working.
hunk ./docs/building/building.sgml 1226
- GCC 3.3 currently cannot be used to build GHC, due to
- some problems with the new C preprocessor.
-
hunk ./docs/building/building.sgml 1228
- it and get things improved. (Exception: on iX86
+ it and get things improved. (Exception: on x86
hunk ./docs/building/building.sgml 3621
- NOTE: GHC versions 5.xx and later are
- significantly harder to bootstrap from C than earlier versions.
- We recommend starting from version 4.08.2 if you need to
- bootstrap in this way.
+ NOTE: GHC versions 5.xx were hard to bootstrap
+ from C. We recommend using GHC 6.0.1 or
+ later.
hunk ./docs/building/building.sgml 3625
- HC files are architecture-dependent (but not
- OS-dependent), so you have to get a set that were generated on
- similar hardware. There may be some supplied on the GHC
- download page, otherwise you'll have to compile some up
- yourself, or start from unregisterised HC
- files - see .
+ HC files are platform-dependent, so you have to get a set
+ that were generated on similar hardware. There may be some
+ supplied on the GHC download page, otherwise you'll have to
+ compile some up yourself, or start from
+ unregisterised HC files - see .
hunk ./docs/building/building.sgml 3715
- Building an unregisterised port
-
- The first step is to get some unregisterised HC files.
- Either (a) download them from the GHC site (if there are
- some available for the right version of GHC), or
- (b) build them yourself on any machine with a working
- GHC. If at all possible this should be a machine with the
- same word size as the target.
+ Cross-compiling to produce an unregisterised GHC
hunk ./docs/building/building.sgml 3717
- There is a script available which should automate the
- process of doing the 2-stage bootstrap necessary to get the
- unregisterised HC files - it's available in fptools/distrib/cross-port
- in CVS.
+ 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.
hunk ./docs/building/building.sgml 3724
- Now take these unregisterised HC files to the target
- platform and bootstrap a compiler from them as per the
- instructions in . In
- build.mk, you need to tell the build
- system that the compiler you're building is
- (a) unregisterised itself, and (b) builds
- unregisterised binaries. This varies depending on the GHC
- version you're bootstraping:
+ 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.
+
+
+
+ On the target machine:
+
+
+
+ Unpack a source tree (preferably a released
+ version). We will call the path to the root of this
+ tree T.
+
+
+
+
+$ ./configure --enable-hc-boot --enable-hc-boot-unregisterised
+
+
+ You might need to update
+ configure.in to recognise the new
+ architecture, and re-generate
+ configure with
+ autoreconf.
+
+
+
+
+$ cd T/ghc/includes
+$ make config.h
+
+
+
+
+
+
+ On the host machine:
+
+
+
+ Unpack a source tree (same released version). Call
+ this directory H.
+
+
+
+
+$ cd H
+$ ./configure
+
+
+
+
+ Create
+ H/mk/build.mk,
+ with the following contents:
hunk ./docs/building/building.sgml 3786
-# build.mk for GHC 4.08.x
-GhcWithRegisterised=NO
+GhcUnregisterised = YES
+GhcLibHcOpts = -O -H32m -keep-hc-files
+GhcLibWays =
+SplitObjs = NO
+GhcWithNativeCodeGen = NO
+GhcWithInterpreter = NO
+GhcStage1HcOpts = -O -H32m -fasm
+GhcStage2HcOpts = -O -fvia-C -keep-hc-files
hunk ./docs/building/building.sgml 3795
+
+
+
+ Copy
+ T/ghc/includes/config.h
+ to
+ H/ghc/includes.
+ Note that we are building on the host machine, using the
+ target machine's config.h file. This
+ is so that the intermediate C files generated here will
+ be suitable for compiling on the target system.
+
+
+
+ Edit
+ H/mk/config.mk:
+
+
+ change TARGETPLATFORM
+ appropriately.
+
+
+ copy LeadingUnderscore
+ setting from target.
+
+
+
+
+
+
+$ cd H/glafp-utils && make boot && make
+
+
+
+
+
+$ cd H/ghc && make boot && make
+
+
+ Don't worry if the build falls over in the RTS, we
+ don't need the RTS yet.
+
+
+
+
+$ cd H/libraries
+$& make boot && make
+
+
+
+
+
+$ cd H/ghc
+$ make boot stage=2 && make stage=2
+
+
+
+
+
+$ cd H/ghc/utils
+$ make clean
+$ make -k HC=H/ghc/compiler/stage1/ghc-inplace \
+ EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
+
+
+
+
+
+$ cd H
+$ make hc-file-bundle Project=Ghc
+
+
+
+
+ copy
+ H/*-hc.tar.gz
+ to T/...
+
+
+
+
+
+ On the target machine:
+
+ At this stage we simply need to bootstrap a compiler
+ from the intermediate C files we generated above. It is
+ possible to follow the instructions for bootstrapping from C
+ files in , but we find
+ that the script hc-build is more suited
+ to booting a registerised compiler on an already-working
+ platform. The following instructions duplicate some of what
+ the hc-build script does, but the process
+ is made simpler by just aiming to get a working compiler,
+ then using this to bootstrap a completely fresh tree.
+
+
+
+
+$ cd T/.. && tar xvzf ghc-*-hc.tar.gz
+
+
+
+
+ Create
+ T/mk/build.mk,
+ with the following contents:
hunk ./docs/building/building.sgml 3903
-# build.mk for GHC 5.xx and 6.x
-GhcUnregisterised=YES
+GhcUnregisterised = YES
+GhcLibWays =
+SplitObjs = NO
+GhcWithNativeCodeGen = NO
+GhcWithInterpreter = NO
hunk ./docs/building/building.sgml 3909
+
+
+
+ Bootstrap GHC from the .hc files:
+
+
+$ ./configure --enable-hc-boot --enable-hc-boot-unregisterised
+$ make -C glafp-utils boot all
+$ make -C ghc boot
+$ make -C libraries boot all
+$ make -C ghc all
+
+
+
+
+ You should now have a working GHC binary. You
+ might want to try using this GHC to compile a Hello
+ World, to make sure it's doing something
+ reasonable:
hunk ./docs/building/building.sgml 3929
- Versions 5.xx and 6.x only: use the option
- instead of
- when running
- ./configure.
+
+$ cat >hello.hs
+main = putStrLn "Hello World!\n"
+^D
+$ T/ghc/compiler/ghc-inplace hello.hs -o hello
+$ ./hello
+Hello World!\n
+
+
+
+
+ Now, use this compiler
+ (T/ghc/compiler/ghc-inplace)
+ to build another GHC tree from scratch, as
+ normal.
+
+
+
+
}