Changes between Version 17 and Version 18 of Building/Porting


Ignore:
Timestamp:
May 17, 2009 1:30:34 PM (6 years ago)
Author:
igloo
Comment:

Instructions for 6.11

Legend:

Unmodified
Added
Removed
Modified
  • Building/Porting

    v17 v18  
    1717
    1818 * Your platform isn't supported by GHC.  You will need to do an
    19    ''unregisterised bootstrap'', proceed to 
     19   ''unregisterised bootstrap'', proceed to
    2020   [[ref(Porting GHC to a new platform)]].
    2121
     
    7777== Porting GHC to a new platform ==
    7878
    79 '''NOTE''': Versions supported: between 6.0.1 and 6.6.2.  We are working
    80 on getting bootstrapping working again in the 6.8 series, see #1346.
     79'''NOTE''': Versions supported: 6.11+.
    8180
    8281The first step in porting to a new platform is to get an
    8382''unregisterised'' build working.  An unregisterised build is one that
    84 compiles via vanilla C only.  By contrast, a registerised build uses
    85 the following architecture-specific hacks for speed:
    86 
    87  * Global register variables: certain abstract machine "registers" are
    88    mapped to real machine registers, depending on how many machine
    89    registers are available (see [[GhcFile(includes/MachRegs.h)]]).
    90 
    91  * Assembly-mangling: when compiling via C, we feed the assembly
    92    generated by gcc though a Perl script known as the ''mangler'' (see
    93    [[GhcFile(driver/mangler/ghc-asm.lprl)]].  The mangler rearranges
    94    the assembly to support tail-calls and various other optimisations.
    95 
    96 In an unregisterised build, neither of these hacks are
    97 used -- the idea is that the C code generated by the
    98 compiler should compile using gcc only.  The lack of these
    99 optimisations costs about a factor of two in performance, but
    100 since unregisterised compilation is usually just a step on the
    101 way to a full registerised port, we don't mind too much.
    102 
    103 You should go through this process even if your
    104 architecture is already has registerised support in GHC, but
    105 your OS currently isn't supported.  In this case you probably
    106 won't need to port any of the architecture-specific parts of the
    107 code, and you can proceed straight from the unregisterised build
    108 to build a registerised compiler.
     83compiles via vanilla C only. Tist costs about a factor of two in
     84performance, but since unregisterised compilation is usually just a step
     85on the way to a full registerised port, we don't mind too much.
     86
     87You should go through this process even if your architecture is already
     88has registerised support in GHC, but your OS currently isn't supported.
     89In this case you probably won't need to port any of the
     90architecture-specific parts of the code, and you can proceed straight
     91from the unregisterised build to build a registerised compiler.
    10992
    11093Notes on GHC portability in general: we've tried to stick
     
    121104=== Cross-compiling to produce an unregisterised GHC ===
    122105
    123 NOTE!  These instructions apply to GHC 6.4 and (hopefully)
    124 later.  If you need instructions for an earlier version of GHC, try
    125 to get hold of the version of this document that was current at the
    126 time.  It should be available from the appropriate download page on
    127 the [http://www.haskell.org/ghc/ GHC homepage].
     106NOTE! These instructions apply to GHC 6.11 and (hopefully) later.
    128107
    129108In this section, we explain how to bootstrap GHC on a new platform,
     
    135114The following step-by-step instructions should result in a fully
    136115working, albeit unregisterised, GHC.  Firstly, you need a machine that
    137 already has a working GHC (we'll call this the
    138 ''host'' machine), in order to cross-compile the
    139 intermediate C files that we will use to bootstrap the compiler on the
    140 ''target'' machine.
     116already has a working GHC (we'll call this the ''host'' machine), in
     117order to cross-compile the intermediate C files that we will use to
     118bootstrap the compiler on the ''target'' machine.
    141119
    142120'''On the target machine'''
     
    148126{{{
    149127$ cd <T>
    150 $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised
     128$ sh boot
     129$ ./configure --enable-hc-boot
    151130}}}
    152131
     
    155134
    156135{{{
    157 $ cd <T>/includes
    158 $ make
     136$ make bootstrapping-files
    159137}}}
    160138
     
    165143{{{
    166144$ cd <H>
     145$ sh boot
    167146$ ./configure
    168147}}}
     
    174153GhcLibHcOpts = -O -fvia-C -keep-hc-files
    175154GhcRtsHcOpts = -keep-hc-files
    176 GhcLibWays =
     155GhcLibWays = v
    177156SplitObjs = NO
    178157GhcWithNativeCodeGen = NO
     
    181160GhcStage2HcOpts = -O -fvia-C -keep-hc-files
    182161SRC_HC_OPTS += -H32m
    183 GhcBootLibs = YES
    184162GhcWithSMP = NO
    185163}}}
    186164
    187 Edit {{{<H>/mk/config.mk}}}:
     165Edit {{{<H>/mk/project.mk}}}:
    188166 * change {{{TARGETPLATFORM}}} appropriately, and set the variables
    189167   involving {{{TARGET}}} or {{{Target}}} to the correct values for
     
    201179be suitable for compiling on the target system.
    202180
    203 Touch the generated configuration files, just to make
    204 sure they don't get replaced during the build:
    205 {{{
    206 $ cd <H>/includes
    207 $ touch ghcautoconf.h DerivedConstants.h GHCConstants.h mkDerivedConstants.c
    208 $ touch mkDerivedConstantsHdr mkDerivedConstants.o mkGHCConstants mkGHCConstants.o
    209 }}}
    210 
    211181Now build the compiler:
    212182
    213183{{{
    214 $ cd <H>/utils/mkdependC && make boot && make
    215 $ cd <H>/includes && make boot && make
    216 $ cd <H>/compat && make boot && make
    217 $ cd <H>/utils && make boot && make
    218 $ cd <H>/compiler && make boot && make
    219 $ cd <H>/rts && make boot && make
    220 $ cd <H>/libraries
    221 $ make boot && make
    222 }}}
    223 
    224 {{{
    225 $ cd <H>/compiler
    226 $ make boot stage=2 && make stage=2
    227 }}}
    228 
    229 {{{
    230 $ cd <H>/compat
    231 $ make clean
    232 $ rm .depend
    233 $ make boot UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
    234 $ cd <H>/utils
    235 $ make clean
    236 $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
    237 }}}
     184$ make
     185}}}
     186
     187You may need to work around problems that occur due to differences
     188between the host and target platforms.
    238189
    239190{{{
    240191$ cd <H>
    241 $ make hc-file-bundle Project=Ghc
    242 }}}
    243 
    244 Unpack {{{<H>/*-hc.tar.gz}}} to {{{<T>/..}}}.
    245 
    246 {{{
    247 $ tar xzf <H>/*-hc.tar.gz -C <T>/..
     192$ rm -f list mkfiles boot.tar.gz
     193$ find . -name "*.hc" >> list
     194$ find . -name "*_stub.*" >> list
     195$ find . -name package-data.mk >> list
     196$ find . -name package.conf >> list
     197$ find . -name package.conf.inplace >> list
     198$ echo compiler/main/Config.hs >> list
     199$ find . -name .depend | sed -e 's/^/mkdir -p `dirname /' -e 's/$/`/' >> mkfiles
     200$ find . -name .depend | sed "s/^/touch /" >> mkfiles
     201$ echo mkfiles >> list
     202$ tar -zcf boot.tar.gz -T list
    248203}}}
    249204
    250205'''On the target machine'''
    251206
    252 At this stage we simply need to bootstrap a compiler
    253 from the intermediate C files we generated above.  The
    254 process of bootstrapping from C files is automated by the
    255 script in {{{distrib/hc-build}}}, and is
    256 described in [[ref(Booting/porting from C (.hc) files)]].
    257 
    258 {{{
    259 $ ./distrib/hc-build --enable-hc-boot-unregisterised
    260 }}}
    261 
    262 However, since this is a bootstrap on a new machine, the automated
    263 process might not run to completion the first time.  For that reason,
    264 you might want to treat the {{{hc-build}}} script as a list of
    265 instructions to follow, rather than as a fully automated script.  This
    266 way you'll be able to restart the process part-way through if you need
    267 to fix anything on the way.
     207{{{
     208$ cd <T>
     209$ cp /bin/pwd utils/ghc-pwd/ghc-pwd
     210}}}
     211
     212{{{
     213$ sh boot
     214$ ./configure --enable-hc-boot
     215}}}
     216
     217Unpack {{{<H>/boot.tar.gz}}} to {{{<T>/}}}.
     218
     219{{{
     220$ tar --touch -zxf boot.tar.gz
     221$ sh mkfiles
     222}}}
     223
     224Put this in `<T>/mk/build.mk`:
     225{{{
     226GHC = false
     227GHC_PKG_INPLACE =
     228GHC_CABAL_INPLACE =
     229DUMMY_GHC_INPLACE =
     230UNLIT =
     231NO_INCLUDE_DEPS = YES
     232GhcUnregisterised = YES
     233GhcLibWays = v
     234SplitObjs = NO
     235GhcWithNativeCodeGen = NO
     236GhcWithInterpreter = NO
     237GhcWithSMP = NO
     238ghc_stage2_v_EXTRA_CC_OPTS += -Lgmp -lgmp -lm -lutil -lrt
     239}}}
     240
     241{{{
     242$ for c in libraries/*/configure; do ( cd `dirname $c`; ./configure ); done
     243}}}
     244
     245{{{
     246$ sed -i .bak "s/<H>/<T>/g" */*/package-data.mk */*/*/package-data.mk
     247$ touch -r compiler/stage2/package-data.mk */*/package-data.mk */*/*/package-data.mk
     248}}}
     249
     250Now make bootstrapping files; what we're really doing here is making
     251libffi, and libgmp if necessary:
     252
     253{{{
     254$ make bootstrapping-files
     255}}}
     256
     257{{{
     258$ make all_ghc_stage2 2>&1 | tee log
     259}}}
    268260
    269261Don't bother with running {{{make install}}} in the newly bootstrapped
     
    277269main = putStrLn "Hello World!\n"
    278270^D
    279 $ <T>/compiler/ghc-inplace hello.hs -o hello
     271$ <T>/inplace/bin/ghc-stage2 hello.hs -o hello
    280272$ ./hello
    281273Hello World!