From f871895b57e287384037ac6f9b96583b0cc73e2d Mon Sep 17 00:00:00 2001 From: simonmar Date: Thu, 28 Aug 2003 16:30:45 +0000 Subject: [PATCH] [project @ 2003-08-28 16:30:45 by simonmar] - 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. --- docs/building/building.sgml | 305 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 258 insertions(+), 47 deletions(-) diff --git a/docs/building/building.sgml b/docs/building/building.sgml index bd5246c..913cb1b 100644 --- a/docs/building/building.sgml +++ b/docs/building/building.sgml @@ -720,6 +720,17 @@ $ cvs checkout nofib/spectral + alex + alex + project + + The Alex lexical + analyser generator for Haskell. + + + + ghc ghc project @@ -1075,6 +1086,15 @@ $ cvs checkout nofib/spectral + x86_64-unknown-linux + x86_64-unknown-linux + + GHC currently works unregisterised. A registerised + port is in progress. + + + + mips-sgi-irix5 mips-sgi-irix[5-6] @@ -1101,8 +1121,8 @@ $ cvs checkout nofib/spectral powerpc-apple-darwin powerpc-apple-darwin - Supported registerised. No native code - generator. + Supported registerised. Native code generator is + almost working. @@ -1203,12 +1223,9 @@ $ cvs checkout nofib/spectral GCC 3.2 is currently known to have problems building GHC on Sparc, but is stable on x86. - GCC 3.3 currently cannot be used to build GHC, due to - some problems with the new C preprocessor. - If your GCC dies with “internal error” on some GHC source file, please let us know, so we can report - it and get things improved. (Exception: on iX86 + it and get things improved. (Exception: on x86 boxes—you may need to fiddle with GHC's option; see the User's Guide) @@ -3601,17 +3618,16 @@ $ make install-docs target machine, and compiling them using gcc to get a working GHC. - 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. - 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 . The following steps should result in a working GHC build with full libraries: @@ -3696,44 +3712,239 @@ foo% make install way to a full registerised port, we don't mind too much. - 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. - - 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. - - 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: + Cross-compiling to produce an unregisterised GHC + + 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. + + + + 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: -# 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 + + + + 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: -# build.mk for GHC 5.xx and 6.x -GhcUnregisterised=YES +GhcUnregisterised = YES +GhcLibWays = +SplitObjs = NO +GhcWithNativeCodeGen = NO +GhcWithInterpreter = NO + + + + Bootstrap GHC from the .hc files: - Versions 5.xx and 6.x only: use the option - instead of - when running - ./configure. + +$ ./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: + + +$ 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. + + + + The build may not go through cleanly. We've tried to stick to writing portable code in most parts of the compiler, -- 1.7.10.4