X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;ds=sidebyside;f=docs%2Fbuilding%2Fbuilding.xml;h=6b8efa752b389c79b4de42d9657617b0f4cb3f77;hb=f53e3de5fac3c5eb12f94ee6b26488b1d07d361e;hp=97b5a697e19024ddca863efd60ebae125af03dcc;hpb=666e12912f5306132faecfef3f18e7ba3181a312;p=ghc-hetmet.git diff --git a/docs/building/building.xml b/docs/building/building.xml index 97b5a69..6b8efa7 100644 --- a/docs/building/building.xml +++ b/docs/building/building.xml @@ -165,10 +165,15 @@ supported method, and you may encounter difficulties. Full instructions are in . - Which version of GHC you need will depend on the - packages you intend to build. GHC itself will normally - build using one of several older versions of itself - check - the announcement or release notes for details. + GHC can be built using either an earlier released + version of GHC (currently 5.04 and later are supported), or + bootstrapped using a GHC built from exactly the same + sources. Note that this means you cannot in general build + GHC using an arbitrary development snapshot, or a build from + say last week. It might work, it might not - we don't + guarantee anything. To be on the safe side, start your + build using the most recently released stable version of + GHC. @@ -504,12 +509,12 @@ $ make install Like the source tree, the top level of your build tree must be (a linked copy of) the root directory of the GHC source tree.. Inside Makefiles, the root of your build tree is called - $(FPTOOLS_TOP)FPTOOLS_TOP. + $(GHC_TOP)GHC_TOP. In the rest of this document path names are relative to - $(FPTOOLS_TOP) unless + $(GHC_TOP) unless otherwise stated. For example, the file mk/target.mk is actually - $(FPTOOLS_TOP)/mk/target.mk. + $(GHC_TOP)/mk/target.mk. @@ -545,15 +550,15 @@ $ make install rather than darcs sources, you can skip this step. Change directory to - $(FPTOOLS_TOP) and + $(GHC_TOP) and issue the command $ autoreconf autoreconf (with no arguments). This GNU program (recursively) converts - $(FPTOOLS_TOP)/configure.ac and - $(FPTOOLS_TOP)/aclocal.m4 + $(GHC_TOP)/configure.ac and + $(GHC_TOP)/aclocal.m4 to a shell script called - $(FPTOOLS_TOP)/configure. + $(GHC_TOP)/configure. If autoreconf bleats that it can't write the file configure, then delete the latter and try again. Note that you must use autoreconf, and not the old autoconf! If you erroneously use the latter, you'll get @@ -564,7 +569,7 @@ $ make install libraries, have their own configure script. autoreconf takes care of that, too, so all you have to do is calling autoreconf in the top-level directory - $(FPTOOLS_TOP). + $(GHC_TOP). These steps are completely platform-independent; they just mean that the human-written files (configure.ac and @@ -784,7 +789,7 @@ $ make install You can also use build.mk to override anything that configure got wrong. One place where this happens often is with the definition of - FPTOOLS_TOP_ABS: this + GHC_TOP_ABS: this variable is supposed to be the canonical path to the top of your source tree, but if your system uses an automounter then the correct directory is hard to find automatically. If you find @@ -1252,7 +1257,7 @@ $ mkshadowdir . /scratch/joe-bloggs/myghc-x86 Makefile for an imaginary small program, small. Each program or library in the GHC source tree typically has its own directory, in this case we'll - use $(FPTOOLS_TOP)/small. + use $(GHC_TOP)/small. Inside the small/ directory there will be a Makefile, looking something like this: @@ -1524,7 +1529,7 @@ directive. boilerplate.mk If you look at - $(FPTOOLS_TOP)/mk/boilerplate.mk + $(GHC_TOP)/mk/boilerplate.mk you will find that it consists of the following sections, each held in a separate file: @@ -2179,8 +2184,7 @@ directive. Tools for building the Documentation The following additional tools are required if you want to - format the documentation that comes with the - fptools projects: + format the documentation that comes with GHC: @@ -2213,11 +2217,9 @@ directive. Haddock is a Haskell documentation tool that we use for automatically generating documentation from the - library source code. It is an fptools - project in itself. To build documentation for the - libraries (fptools/libraries) you - should check out and build Haddock in - fptools/haddock. Haddock requires GHC + library source code. To build documentation for the + libraries ($(GHC_TOP)/libraries) you + should build and install Haddock. Haddock requires GHC to build. @@ -2354,24 +2356,25 @@ $ make install Porting GHC This section describes how to port GHC to a currenly - unsupported platform. There are two distinct - possibilities: + 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. + + There are two distinct porting scenarios: - The hardware architecture for your system is already - supported by GHC, but you're running an OS that isn't - supported (or perhaps has been supported in the past, but - currently isn't). This is the easiest type of porting job, - but it still requires some careful bootstrapping. Proceed to - . + Your platform is already supported, but you want to + compile up GHC using just a C compiler. This is a + straightforward bootstrap from HC files, and is described in + . - Your system's hardware architecture isn't supported by - GHC. This will be a more difficult port (though by comparison - perhaps not as difficult as porting gcc). Proceed to . + Your platform isn't supported by GHC. You will need to + do an unregisterised bootstrap, proceed + to . @@ -2392,25 +2395,40 @@ $ make install later. HC files are platform-dependent, so you have to get a set - that were generated on the same platform. 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 . + that were generated on the same platform. + There may be some supplied on the GHC download page, otherwise + you'll have to compile some up yourself. The following steps should result in a working GHC build with full libraries: - Unpack the HC files on top of a fresh source tree - (make sure the source tree version matches the version of - the HC files exactly!). This will - place matching .hc files next to the - corresponding Haskell source (.hs or - .lhs) in the compiler subdirectory - ghc/compiler and in the libraries - (subdirectories of + Make a set of HC files. On an identical system with + GHC already installed, get a GHC source tree and put the + following in mk/build.mk: + + +SRC_HC_OPTS = -H32m -O -fasm -Rghc-timing -keep-hc-files +GhcLibHcOpts = -O +GhcLibWays = +SplitObjs = NO + + + Build GHC as normal, and then make + hc-file-bundle Project=ghc to creates the tar file + containing the hc files. + + + + On the target system, unpack the HC files on top of a + fresh source tree (make sure the source tree version matches + the version of the HC files exactly!). + This will place matching .hc files next + to the corresponding Haskell source + (.hs or .lhs) in + the compiler subdirectory ghc/compiler + and in the libraries (subdirectories of libraries). @@ -2442,10 +2460,10 @@ $ make install - Porting GHC to a new architecture + Porting GHC to a new platform - The first step in porting to a new architecture is to get - an unregisterised build working. An + 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: @@ -2476,6 +2494,13 @@ $ make install 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 @@ -2531,14 +2556,14 @@ $ make install $ ./configure --enable-hc-boot --enable-hc-boot-unregisterised You might need to update - configure.in to recognise the new - architecture, and re-generate + configure.ac to recognise the new + platform, and re-generate configure with autoreconf. -$ cd T/ghc/includes +$ cd T/includes $ make @@ -2573,7 +2598,8 @@ GhcWithInterpreter = NO GhcStage1HcOpts = -O GhcStage2HcOpts = -O -fvia-C -keep-hc-files SRC_HC_OPTS += -H32m -GhcBootLibs = YES +GhcBootLibs = YES +GhcWithSMP = NO @@ -2600,9 +2626,9 @@ GhcBootLibs = YES Copy - T/ghc/includes/ghcautoconf.h, T/ghc/includes/DerivedConstants.h, and T/ghc/includes/GHCConstants.h + T/includes/ghcautoconf.h, T/includes/DerivedConstants.h, and T/includes/GHCConstants.h to - H/ghc/includes. + 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 @@ -2612,27 +2638,21 @@ GhcBootLibs = YES Touch the generated configuration files, just to make sure they don't get replaced during the build: -$ cd H/ghc/includes +$ cd H/includes $ touch ghcautoconf.h DerivedConstants.h GHCConstants.h mkDerivedConstants.c $ touch mkDerivedConstantsHdr mkDerivedConstants.o mkGHCConstants mkGHCConstants.o - - Note: it has been reported that these files still get - overwritten during the next stage. We have installed a fix - for this in GHC 6.4.2, but if you are building a version - before that you need to watch out for these files getting - overwritte by the Makefile in - ghc/includes. If your system supports - it, you might be able to prevent it by making them - immutable: -$ chflags uchg ghc/includes/{ghcautoconf.h,DerivedConstants.h,GHCConstants.h} Now build the compiler: -$ 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/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 + Don't worry if the build falls over in the RTS, we + don't need the RTS yet. @@ -2641,7 +2661,7 @@ $ make boot && make -$ cd H/ghc/compiler +$ cd H/compiler $ make boot stage=2 && make stage=2 @@ -2650,7 +2670,7 @@ $ make boot stage=2 && make stage=2 $ make clean $ rm .depend $ make boot UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files' -$ cd H/ghc/utils +$ cd H/utils $ make clean $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files' @@ -2854,15 +2874,15 @@ Hello World! GHCi To support GHCi, you need to port the dynamic linker - (fptools/ghc/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 + ($(GHC_TOP)/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 will probaly be necessary. + architecture and/or OS will probaly be necessary. If your system uses a different object file format, then you have to write a linker — good luck! @@ -2902,9 +2922,8 @@ The best way around it is to say export TMPDIR=<dir> -in your build.mk file. -Then GHC and the other fptools programs will use the appropriate directory -in all cases. +in your build.mk file. Then GHC and the other +tools will use the appropriate directory in all cases. @@ -3570,7 +3589,7 @@ you do that, ssh uses the $HOME environment variable instead. You have to install the following other things to build GHC, listed below. On Windows you often install executables in directories with spaces, such as -"Program Files". However, the make system for fptools doesn't +"Program Files". However, the make system doesn't deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised to put binaries for all tools in places with no spaces in their path. On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places, @@ -3635,10 +3654,10 @@ but you must have them; hence needing the Cygwin binutils package. We use emacs a lot, so we install that too. -When you are in fptools/ghc/compiler, you can use +When you are in $(GHC_TOP)/compiler, you can use "make tags" to make a TAGS file for emacs. That uses the utility -fptools/ghc/utils/hasktags/hasktags, so you need to make that first. -The most convenient way to do this is by going make boot in fptools/ghc. +$(GHC_TOP)/ghc/utils/hasktags/hasktags, so you need to make that first. +The most convenient way to do this is by going make boot in $(GHC_TOP)/ghc. The make tags command also uses etags, which comes with emacs, so you will need to add emacs/bin to your PATH. @@ -3690,7 +3709,7 @@ Solution: delete configure first. After autoreconf run ./configure in - fptools/ thus: + $(GHC_TOP)/ thus: $ ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc This is the point at which you specify that you are building GHC-mingw @@ -3708,7 +3727,7 @@ say --with-gcc=/mingw/bin/gcc, it'll be interpreted as time it tries to invoke it. Worse, the failure comes with no error message whatsoever. GHC simply fails silently when first invoked, typically leaving you with this: -make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp' +make[4]: Leaving directory `/cygdrive/e/ghc-stage1/ghc/rts/gmp' ../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return @@ -3718,7 +3737,7 @@ typically leaving you with this: -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o make[2]: *** [Adjustor.o] Error 1 make[1]: *** [all] Error 1 -make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc' +make[1]: Leaving directory `/cygdrive/e/ghc-stage1/ghc' make: *** [all] Error 1 Be warned! @@ -3797,7 +3816,7 @@ choices, but it gives a single path that works. ; also, subscribe to cvs-all@haskell.org, or follow the mailing list ; archive, in case you checkout a version with problems ; http://www.haskell.org//pipermail/cvs-all/ - - mkdir c:/fptools; cd c:/fptools + - mkdir c:/ghc-build; cd c:/ghc-build ; (or whereever you want your darcs tree to be) - darcs get http://darcs.haskell.org/ghc - cd ghc @@ -3809,7 +3828,7 @@ choices, but it gives a single path that works. ; for haddock, alex, happy (*) - export PATH=/cygdrive/c/mingw/bin:$PATH ; without, we pick up some cygwin tools at best! - - cd c:/fptools/fptools + - cd c:/ghc-build ; (if you aren't there already) - autoreconf - ./configure --host=i386-unknown-mingw32 --with-gcc=C:/Mingw/bin/gcc.exe