X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fbuilding%2Fbuilding.sgml;h=1bb92d5e9636090f3a3711a34616275a117395e2;hb=1b75cf971b425aefb3d9dd4d2dcde8739d4f6879;hp=bcf3cf4f756ed5c272e9d682d6b3cb13157ef984;hpb=11f88ccab7c566d7f4d709edb387ee4bc7d52aa7;p=ghc-hetmet.git diff --git a/docs/building/building.sgml b/docs/building/building.sgml index bcf3cf4..1bb92d5 100644 --- a/docs/building/building.sgml +++ b/docs/building/building.sgml @@ -137,6 +137,12 @@ Set your $CVSROOT environment variable to :pserver:anoncvs@glass.cse.ogi.edu:/cvs + If you set $CVSROOT in a shell script, be sure not to + have any trailing spaces on that line, otherwise CVS will respond with + a perplexing message like + + /cvs : no such repository + Run the command @@ -240,34 +246,10 @@ - [Windows users.] The programs ssh-keygen1, ssh1, and cvs, - seem to lock up bash entirely if they try to get user input (e.g. if - they ask for a password). To solve this, start up cmd.exe - and run it as follows: - - c:\tmp> set CYGWIN32=tty - c:\tmp> c:/user/local/bin/ssh-keygen1 - + Windows users: see the notes in about ssh wrinkles! + + - [Windows users.] To protect your - .ssh from access by anyone else, - right-click your .ssh directory, and - select Properties. If you are not on - the access control list, add yourself, and give yourself - full permissions (the second panel). Remove everyone else - from the access control list. Don't leave them there but - deny them access, because 'they' may be a list that - includes you! - [March 2003] In fact ssh 3.6.1 now seems to require - you to have Unix permissions 600 (read/write for owner only) - on the .ssh/identity file, else it - bombs out. For your local C drive, it seems that chmod 600 identity works, - but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure). - The solution seems to be to set the CYGWIN environment - variable to "ntsec neta". The CYGWIN environment variable is discussed - in the Cygwin User's Guide, - and there are more details in the Cygwin FAQ. - @@ -456,6 +438,10 @@ setsockopt IPTOS_THROUGHPUT: Invalid argument hslibs and libraries modules (for a full list of the projects available, see ). + + Remember that if you do not have + happy and/or Alex + installed, you need to check them out as well. @@ -491,7 +477,14 @@ $ cvs diff you the results. - + + If you changed something in the + fptools/libraries subdirectories, also run + make html to check if the documentation can + be generated successfully, too. + + + Before checking in a change, you need to update your source tree: @@ -574,7 +567,7 @@ $ cvs commit -F commit-message directory major cause of headaches. So, to avoid a lot of hassle, follow this recipe for - updating your tree: + updating your tree: $ cd fptools @@ -733,6 +726,17 @@ $ cvs checkout nofib/spectral + alex + alex + project + + The Alex lexical + analyser generator for Haskell. + + + + ghc ghc project @@ -754,11 +758,11 @@ $ cvs checkout nofib/spectral - green-card - green-cardproject + greencard + greencardproject The Green Card + url="http://www.haskell.org/greencard/">GreenCard system for generating Haskell foreign function interfaces. @@ -1002,12 +1006,21 @@ $ cvs checkout nofib/spectral sparc-sun-solaris2 sparc-sun-solaris2 - Fully supported (at least for Solaris 2.7), + Fully supported (at least for Solaris 2.7 and 2.6), including native-code generator. + sparc-unknown-openbsd + sparc-unknown-openbsd + + Supported, including native-code generator. The + same should also be true of NetBSD + + + + hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x) hppa1.1-hp-hpux @@ -1082,6 +1095,15 @@ $ cvs checkout nofib/spectral ia64-unknown-linux ia64-unknown-linux + Supported, except there is no native code + generator. + + + + + x86_64-unknown-linux + x86_64-unknown-linux + GHC currently works unregisterised. A registerised port is in progress. @@ -1100,6 +1122,14 @@ $ cvs checkout nofib/spectral + mips64-sgi-irix6 + mips-sgi-irix6 + + GHC currently works unregisterised. + + + + powerpc-ibm-aix powerpc-ibm-aix @@ -1114,8 +1144,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. @@ -1213,9 +1243,12 @@ $ cvs checkout nofib/spectral egcs) have varying degrees of stability depending on the platform. + GCC 3.2 is currently known to have problems building + GHC on Sparc, but is stable on x86. + 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) @@ -1244,7 +1277,7 @@ $ cvs checkout nofib/spectral (fptools/happy). It can be built from source, but bear in mind that you'll need GHC installed in order to build it. To avoid the chicken/egg problem, - install a binary distribtion of either Happy or GHC to get + install a binary distribution of either Happy or GHC to get started. Happy distributions are available from Happy's Web Page. @@ -1252,6 +1285,19 @@ $ cvs checkout nofib/spectral + Alex + Alex + + Alex is a lexical-analyser generator for Haskell, + which GHC uses to generate its lexer. Like Happy, Alex is + written in Haskell and is a project in the CVS repository. + Alex distributions are available from Alex's Web + Page. + + + + Autoconf pre-supposed: Autoconf Autoconf, pre-supposed @@ -1260,8 +1306,12 @@ $ cvs checkout nofib/spectral CVS sources, it is not needed if you just intend to build a standard source distribution. + Version 2.52 or later of autoconf is required. + NB. vesrion 2.13 will no longer work, as of GHC version + 6.1. + Autoconf builds the configure - script from configure.in and + script from configure.ac and aclocal.m4. If you modify either of these files, you'll need autoconf to rebuild configure. @@ -1301,7 +1351,7 @@ $ cvs checkout nofib/spectral PVM is the Parallel Virtual Machine on which Parallel Haskell programs run. (You only need this if you - plan to run Parallel Haskell. Concurent Haskell, which + plan to run Parallel Haskell. Concurrent Haskell, which runs concurrent threads on a uniprocessor doesn't need it.) Underneath PVM, you can have (for example) a network of workstations (slow) or a multiprocessor box @@ -1418,7 +1468,7 @@ $ make install - configure.in, + configure.ac, config.sub, config.guess: these files support the configuration process. @@ -1441,7 +1491,7 @@ $ make install only one project (happy, say), you must have a source tree whose root directory contains Makefile, mk/, - configure.in, and the project(s) you want + configure.ac, and the project(s) you want (happy/ in this case). You cannot get by with just the happy/ directory. @@ -1558,20 +1608,20 @@ $ make install issue the command autoconfautoconf (with no arguments). This GNU program converts - $(FPTOOLS_TOP)/configure.in + $(FPTOOLS_TOP)/configure.ac to a shell script called $(FPTOOLS_TOP)/configure. Some projects, including GHC, have their own configure script. If there's an - $(FPTOOLS_TOP)/<project>/configure.in, + $(FPTOOLS_TOP)/<project>/configure.ac, then you need to run autoconf in that directory too. Both these steps are completely platform-independent; they just mean that the - human-written file (configure.in) can + human-written file (configure.ac) can be short, although the resulting shell script, configure, and mk/config.h.in, are long. @@ -1592,7 +1642,7 @@ $ make install round your computer working out what architecture it has, what operating system, whether it has the vfork system call, where - yacc is kept, whether + tar is kept, whether gcc is available, where various obscure #include files are, whether it's a leap year, and what the systems manager had for lunch. It @@ -1772,17 +1822,17 @@ GhcHcOpts=-DDEBUG -Rghc-timing For example, there's a line that says: -YACC = @YaccCmd@ +TAR = @TarCmd@ - This defines the Make variables YACC - to the pathname for a yacc that + This defines the Make variables TAR + to the pathname for a tar that configure finds somewhere. If you have your - own pet yacc you want to use instead, that's + own pet tar you want to use instead, that's fine. Just add this line to mk/build.mk: -YACC = myyacc +TAR = mytar You do not have to have a @@ -2224,7 +2274,8 @@ Foo.o : Baz.hi build tree. Happy can similarly be run from the build tree, using - happy/src/happy-inplace. + happy/src/happy-inplace, and similarly for + Alex and Haddock. @@ -3604,17 +3655,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: @@ -3698,65 +3748,239 @@ foo% make install since unregisterised compilation is usually just a step on the way to a full registerised port, we don't mind too much. - - Building an unregisterised port + 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 + experience most systems differ from the standards in one way or + another. Deal with any problems as they arise - if you get + stuck, ask the experts on + glasgow-haskell-users@haskell.org. - 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: + Lots of useful information about the innards of GHC is + available in the GHC + Commentary, which might be helpful if you run into some + code which needs tweaking for your system. - -# build.mk for GHC 4.08.x -GhcWithRegisterised=NO - + + 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. + + + + +$ cd 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 5.xx and 6.x -GhcUnregisterised=YES +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 + - Versions 5.xx and 6.x only: use the option - instead of - when running - ./configure. - - The build may not go through cleanly. We've tried to - stick to writing portable code in most parts of the compiler, - so it should compile on any POSIXish system with gcc, but in - our experience most systems differ from the standards in one - way or another. Deal with any problems as they arise - if you - get stuck, ask the experts on - glasgow-haskell-users@haskell.org. - - Once you have the unregisterised compiler up and - running, you can use it to start a registerised port. The - following sections describe the various parts of the system - that will need architecture-specific tweaks in order to get a - registerised build going. - - Lots of useful information about the innards of GHC is - available in the GHC - Commentary, which might be helpful if you run into - some code which needs tweaking for your system. + + Edit + H/mk/config.mk: + + + change TARGETPLATFORM + appropriately, and set the variables involving + TARGET to the correct values for + the target platform. This step is necessary because + currently configure doesn't cope + with specifying different values for the + --host and + --target flags. + + + copy LeadingUnderscore + setting from target. + + + + + + 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. + + + + + Touch config.h, just to make + sure it doesn't get replaced during the build: + +$ touch H/ghc/includes/config.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/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. The + process of bootstrapping from C files is automated by the + script in distrib/hc-build, and is + described in . + + +$ ./distrib/hc-build --enable-hc-boot-unregisterised + + + 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. + + Don't bother with running + make install in the newly + bootstrapped tree; just use the compiler in that tree to + build a fresh compiler from scratch, this time without + booting from C files. Before doing this, you might want + to check that the bootstrapped compiler is generating + working binaries: + + +$ cat >hello.hs +main = putStrLn "Hello World!\n" +^D +$ T/ghc/compiler/ghc-inplace hello.hs -o hello +$ ./hello +Hello World! + + + Once you have the unregisterised compiler up and + running, you can use it to start a registerised port. The + following sections describe the various parts of the + system that will need architecture-specific tweaks in + order to get a registerised build going. + + + @@ -3883,10 +4107,13 @@ GhcUnregisterised=YES 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 you probably don't have - to do anything except fiddle with the - #ifdefs at the top of - Linker.c to tell it about your OS. + 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. If your system uses a different object file format, then you have to write a linker — good luck! @@ -4218,14 +4445,37 @@ but you do need it to build GHC. Install Cygwin from http://www.cygwin.com/. The installation process is straightforward; we install it in c:/cygwin. -During the installation dialogue, make sure that you select: -cvs, openssh, -autoconf, -binutils (includes ld and (I think) ar), -gcc, -flex, -make. - +During the installation dialogue, make sure that you select all of the following: + + + cvs, + + + openssh, + + + autoconf, + + + automake, + + + binutils (includes ld and (I think) ar), + + + gcc, + + + flex, + + + make. + + +If you miss out any of these, strange things will happen to you. To see thse packages, +click on the "View" button in the "Select Packages" +stage of Cygwin's installation dialogue, until the view says "Full". The default view, which is +"Category" isn't very helpful, and the "View" button is rather unobtrousive. Now set the following user environment variables: @@ -4245,7 +4495,7 @@ don't do this you get very weird messages when you type Set SHELL to -c:/cygwin/bin/sh. When you invoke a shell in Emacs, this +c:/cygwin/bin/bash. When you invoke a shell in Emacs, this SHELL is what you get. @@ -4327,6 +4577,73 @@ variable. You can always invoke find with an absolute path, +Configuring SSH + +ssh comes with Cygwin, provided you remember to ask for it when +you install Cygwin. (If not, the installer lets you update easily.) Look for openssh +(not ssh) in the Cygwin list of applications! + +There are several strange things about ssh on Windows that you need to know. + + + + The programs ssh-keygen1, ssh1, and cvs, + seem to lock up bash entirely if they try to get user input (e.g. if + they ask for a password). To solve this, start up cmd.exe + and run it as follows: + + c:\tmp> set CYGWIN32=tty + c:\tmp> c:/user/local/bin/ssh-keygen1 + + + + +ssh needs to access your directory .ssh, in your home directory. +To determine your home directory ssh first looks in +c:/cygwin/etc/passwd (or wherever you have Cygwin installed). If there's an entry +there with your userid, it'll use that entry to determine your home directory, ignoring +the setting of the environment variable $HOME. If the home directory is +bogus, ssh fails horribly. The best way to see what is going on is to say + + ssh -v cvs.haskell.org + +which makes ssh print out information about its activity. + + You can fix this problem, either by correcting the home-directory field in +c:/cygwin/etc/passwd, or by simply deleting the entire entry for your userid. If +you do that, ssh uses the $HOME environment variable instead. + + + + + + To protect your + .ssh from access by anyone else, + right-click your .ssh directory, and + select Properties. If you are not on + the access control list, add yourself, and give yourself + full permissions (the second panel). Remove everyone else + from the access control list. Don't leave them there but + deny them access, because 'they' may be a list that + includes you! + + + + In fact ssh 3.6.1 now seems to require + you to have Unix permissions 600 (read/write for owner only) + on the .ssh/identity file, else it + bombs out. For your local C drive, it seems that chmod 600 identity works, + but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure). + The solution seems to be to set the $CYGWIN environment + variable to "ntsec neta". The $CYGWIN environment variable is discussed + in the Cygwin User's Guide, + and there are more details in the Cygwin FAQ. + + + + + + Other things you need to install You have to install the following other things to build GHC: @@ -4348,6 +4665,12 @@ Happy is a parser generator used to compile the Haskell grammar. Add it in your + + Install Alex. This can be done by building from the + source distribution in the usual way. Sources are + available from http://www.haskell.org/alex. + GHC uses the mingw C compiler to