X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;ds=inline;f=docs%2Fbuilding%2Fbuilding.sgml;h=9765ba32c27cc3e3e2fb4189b557b75a1800e0e3;hb=21bc88b56b77ef9160b415917245b2e69e2fd84c;hp=071f4c94fdbc54ef5ca3fea7ec7bbc77f07bcc84;hpb=711a6e963883e2a84ccfd878806651144dae353a;p=ghc-hetmet.git diff --git a/docs/building/building.sgml b/docs/building/building.sgml index 071f4c9..9765ba3 100644 --- a/docs/building/building.sgml +++ b/docs/building/building.sgml @@ -240,24 +240,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! @@ -446,6 +432,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 installed, you need to check it out + as well. @@ -481,7 +471,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: @@ -564,17 +561,25 @@ $ 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 -$ cvs update -Pd 2>&1 | tee log +$ cvs update -P 2>&1 | tee log Look at the log file, and fix any conflicts (denoted by a - C in the first column). If you're using multiple - build trees, then for every build tree you have pointing at this - source tree, you need to update the links in case any new files - have appeared: + C in the first column). New directories may have + appeared in the repository; CVS doesn't check these out by + default, so to get new directories you have to explicitly do + +$ cvs update -d + in each project subdirectory. Don't do this at the top level, + because then all the projects will be + checked out. + + If you're using multiple build trees, then for every build + tree you have pointing at this source tree, you need to update + the links in case any new files have appeared: $ cd build-tree @@ -1142,6 +1147,23 @@ $ cvs checkout nofib/spectral + GHC + pre-supposed: GHC + GHC, pre-supposed + + GHC is required to build many of the tools, including + GHC itself. If you need to port GHC to your platform + because there isn't a binary distribution of GHC available, + then see . + + 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. + + + + Perl pre-supposed: Perl Perl, pre-supposed @@ -1178,6 +1200,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. + + 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 @@ -1209,7 +1237,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. @@ -1225,6 +1253,10 @@ $ 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 aclocal.m4. If you modify either of @@ -1266,7 +1298,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 @@ -1342,6 +1374,26 @@ $ cvs checkout nofib/spectral software, and lay hands on them gently when they don't work. + + Quick Start + + If you are starting from a source distribution, and just + want a completely standard build, then the following should + work: + +$ ./configure +$ make +$ make install + + + For GHC, this will do a 2-stage bootstrap build of the + compiler, with profiling libraries, and install the + results. + + If you want to do anything at all non-standard, or you + want to do some development, read on... + + Your source tree @@ -1495,6 +1547,9 @@ $ cvs checkout nofib/spectral Step 1: get ready for configuration. + NOTE: if you're starting from a source distribution, + rather than CVS sources, you can skip this step. + Change directory to $(FPTOOLS_TOP) and issue the command @@ -1517,12 +1572,6 @@ $ cvs checkout nofib/spectral be short, although the resulting shell script, configure, and mk/config.h.in, are long. - - In case you don't have autoconf - we distribute the results, configure, - and mk/config.h.in, with the source - distribution. They aren't kept in the repository, - though. @@ -1677,6 +1726,9 @@ $ cvs checkout nofib/spectral includes build.mk after config.mk.) + For your convenience, there's a file called build.mk.sample + that can serve as a starting point for your build.mk. + For example, config.mk.in contains the definition: @@ -1865,7 +1917,92 @@ $ emacs mk/build.mk the top of your fptools tree and type gmake. This will prepare the tree and build the various projects in the correct order. + + + + Bootstrapping GHC + + GHC requires a 2-stage bootstrap in order to provide + full functionality, including GHCi. By a 2-stage bootstrap, we + mean that the compiler is built once using the installed GHC, + and then again using the compiler built in the first stage. You + can also build a stage 3 compiler, but this normally isn't + necessary except to verify that the stage 2 compiler is working + properly. + + Note that when doing a bootstrap, the stage 1 compiler + must be built, followed by the runtime system and libraries, and + then the stage 2 compiler. The correct ordering is implemented + by the top-level fptools Makefile, so if + you want everything to work automatically it's best to start + make from the top of the tree. When building + GHC, the top-level fptools Makefile is set + up to do a 2-stage bootstrap by default (when you say + make). Some other targets it supports + are: + + + + stage1 + + Build everything as normal, including the stage 1 + compiler. + + + + + stage2 + + Build the stage 2 compiler only. + + + + + stage3 + + Build the stage 3 compiler only. + + + + + bootstrap bootstrap2 + + Build stage 1 followed by stage 2. + + + + + bootstrap3 + + Build stages 1, 2 and 3. + + + + + install + + Install everything, including the compiler built in + stage 2. To override the stage, say make install + stage=n where + n is the stage to install. + + + + + The top-level Makefile also arranges + to do the appropriate make boot steps (see + below) before actually building anything. + + The stage1, stage2 + and stage3 targets also work in the + ghc/compiler directory, but don't forget that + each stage requires its own make boot step: + for example, you must do + $ make boot stage=2 + + before make stage2 in + ghc/compiler. @@ -2078,7 +2215,7 @@ Foo.o : Baz.hi Do NOT use ghc/compiler/ghc, or - ghc/compiler/ghc-5.xx, as these are the + ghc/compiler/ghc-6.xx, as these are the scripts intended for installation, and contain hard-wired paths to the installed libraries, rather than the libraries in the build tree. @@ -3464,10 +3601,10 @@ $ make install-docs target machine, and compiling them using gcc to get a working GHC. - NOTE: GHC version 5.xx is significantly harder - to bootstrap from C than previous versions. We recommend - starting from version 4.08.2 if you need to bootstrap in this - way. + 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. HC files are architecture-dependent (but not OS-dependent), so you have to get a set that were generated on @@ -3589,11 +3726,11 @@ GhcWithRegisterised=NO -# build.mk for GHC 5.xx +# build.mk for GHC 5.xx and 6.x GhcUnregisterised=YES - Version 5.xx only: use the option + Versions 5.xx and 6.x only: use the option instead of when running ./configure. @@ -3955,7 +4092,7 @@ guide) before continuing to read these notes. -Cygwin and MinGW +Cygwin and MinGW The Windows situation for building GHC is rather confusing. This section tries to clarify, and to establish terminology. @@ -4010,6 +4147,37 @@ that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix libr +HOST_OS vs TARGET_OS + + +In the source code you'll find various ifdefs looking like: + + #ifdef mingw32_HOST_OS + ...blah blah... + #endif + +and + + #ifdef mingw32_TARGET_OS + ...blah blah... + #endif + +These macros are set by the configure script (via the file config.h). +Which is which? The criterion is this. In the ifdefs in GHC's source code: + + + The "host" system is the one on which GHC itself will be run. + + + The "target" system is the one for which the program compiled by GHC will be run. + + +For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same. +So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros. + + + + Summary Notice that "GHC-mingw" means "GHC that targets MinGW". It says nothing about @@ -4047,9 +4215,13 @@ 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. -Both cvs and ssh -come with Cygwin, but you'll need them, so make sure you select them when running -the Cygwin installer. +During the installation dialogue, make sure that you select: +cvs, openssh, +autoconf, +binutils (includes ld and (I think) ar), +gcc, +flex, +make. Now set the following user environment variables: @@ -4087,8 +4259,24 @@ There are a few other things to do: +By default, cygwin provides the command shell ash +as sh.exe. We have often seen build-system problems that +turn out to be due to bugs in ash +(to do with quoting +and length of command lines). On the other hand bash seems +to be rock solid. +So, in cygwin/bin +remove the supplied sh.exe (or rename it as ash.exe), +and copy bash.exe to sh.exe. +You'll need to do this in Windows Explorer or the Windows cmd shell, because +you can't rename a running program! + + + + + Some script files used in the make system start with "#!/bin/perl", -(and similarly for bash). Notice the hardwired path! +(and similarly for sh). Notice the hardwired path! So you need to ensure that your /bin directory has the following binaries in it: @@ -4100,21 +4288,10 @@ All these come in Cygwin's bin directory, which you probabl installed as c:/cygwin/bin. By default Cygwin mounts "/" as c:/cygwin, so if you just take the defaults it'll all work ok. (You can discover where your Cygwin -root directory / is by typing mount). +root directory / is by typing mount.) Provided /bin points to the Cygwin bin -directory, there's no need to copy anything. - - - - - -By default, cygwin provides the command shell ash -as sh.exe. It has a couple of 'issues' (to do with quoting -and length of command lines), so -in your /bin directory, make sure that -bash.exe is also provided as sh.exe -(i.e. overwrite the old sh.exe with a copy of -bash.exe). +directory, there's no need to copy anything. If not, copy these binaries from the cygwin/bin +directory (after fixing the sh.exe stuff mentioned in the previous bullet). @@ -4147,6 +4324,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: @@ -4171,7 +4415,8 @@ Happy is a parser generator used to compile the Haskell grammar. Add it in your GHC uses the mingw C compiler to -generate code, so you have to install that. Just pick up a mingw bundle at +generate code, so you have to install that (see ). +Just pick up a mingw bundle at http://www.mingw.org/. We install it in c:/mingw. @@ -4184,6 +4429,18 @@ you are likely to get into a mess because their names overlap with Cygwin binari +We use emacs a lot, so we install that too. +When you are in fptools/ghc/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. +The make tags command also uses etags, which comes with emacs, +so you will need to add emacs/bin to your PATH. + + + + + Finally, check out a copy of GHC sources from the CVS repository, following the instructions above (). @@ -4247,13 +4504,39 @@ can be really confusing. fptools/ thus: - ./configure --host=i386-unknown-mingw32 --with-gcc=/mingw/bin/gcc + ./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 -(see ). +(see ). -Both these options are important! It's possible to get into + Both these options are important! It's possible to get into trouble using the wrong C compiler! + +Furthermore, it's very important that you specify a +full MinGW path for gcc, not a Cygwin path, because GHC (which +uses this path to invoke gcc) is a MinGW program and won't +understand a Cygwin path. For example, if you +say --with-gcc=/mingw/bin/gcc, it'll be interpreted as +/cygdrive/c/mingw/bin/gcc, and GHC will fail the first +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' +../../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 + -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes + -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS + -optc-fomit-frame-pointer -O2 -static + -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: *** [all] Error 1 + +Be warned! + If you want to build GHC-cygwin () @@ -4264,6 +4547,17 @@ you'll have to do something more like: + You almost certainly want to set + + SplitObjs = NO + +in your build.mk configuration file (see ). +This tells the build system not to split each library into a myriad of little object files, one +for each function. Doing so reduces binary sizes for statically-linked binaries, but on Windows +it dramatically increases the time taken to build the libraries in the first place. + + + Do not attempt to build the documentation. It needs all kinds of wierd Jade stuff that we haven't worked out for Win32.