X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fbuilding%2Fbuilding.sgml;h=3f47334517fdf6d9180dd79df45bf21a5e6995c5;hb=224f25a6ab4e15e8b4743996e065dc7f1ebc5410;hp=80398f303d9c34d3b5e067c173f0fef2be335124;hpb=cccb6444f80ceb5adb36dbba2f1844b333a0e3f3;p=ghc-hetmet.git diff --git a/docs/building/building.sgml b/docs/building/building.sgml index 80398f3..3f47334 100644 --- a/docs/building/building.sgml +++ b/docs/building/building.sgml @@ -1,13 +1,12 @@ -
+
- + -Building the Glasgow Functional Programming Tools Suite -The GHC Team -
glasgow-haskell-{users,bugs}@haskell.org
-November 2001 +Building the Glasgow Functional Programming Tools Suite +The GHC Team +
glasgow-haskell-{users,bugs}@haskell.org
The Glasgow fptools suite is a collection of Functional @@ -17,16 +16,16 @@ installation system. This guide is intended for people who want to build or - modify programs from the Glasgow fptools + modify programs from the Glasgow fptools suite (as distinct from those who merely want to - run them). Installation instructions are + run them). Installation instructions are now provided in the user guide. The bulk of this guide applies to building on Unix - systems; see for Windows notes. + systems; see for Windows notes. - + @@ -58,15 +57,13 @@ the parser specifications. If you don't want to alter the parser then this saves you having to find and install happy. You will still need a working - version of GHC (preferably version 4.08+) on your machine in + version of GHC (version 5.x or later) on your machine in order to compile (most of) the sources, however. - The CVS repository. - CVS repository - + The CVS repository.CVS repository We make releases infrequently. If you want more up-to-the minute (but less tested) source code then you need @@ -107,7 +104,7 @@ remember is that most mistakes can be undone, but if there's anything you're not sure about feel free to bug the local CVS meister (namely Jeff Lewis - jlewis@galconn.com). + jlewis@galois.com). Getting access to the CVS Repository @@ -137,12 +134,14 @@ 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 - - $ cvs login - +$ cvs login The password is simply cvs. This sets up a file in your home directory called .cvspass, which squirrels away the @@ -180,9 +179,7 @@ Generate a DSA private-key/public-key pair, thus: - - $ ssh-keygen -d - +$ ssh-keygen -d (ssh-keygen comes with ssh.) Running ssh-keygen -d creates the private and public keys in @@ -194,9 +191,7 @@ you have Version 2 ssh installed; it will fail harmlessly otherwise. If you only have Version 1 you can instead generate an RSA key pair using plain - - $ ssh-keygen - +$ ssh-keygen Doing so creates the private and public RSA keys in $HOME/.ssh/identity and @@ -207,12 +202,10 @@ 2 ssh to use the Version 1 protocol by creating $HOME/config with the following in it: - - BatchMode Yes +BatchMode Yes - Host cvs.haskell.org - Protocol 1 - +Host cvs.haskell.org +Protocol 1 In both cases, ssh-keygen will ask for a passphrase. The @@ -240,30 +233,16 @@ - [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! Send a message to to the CVS repository administrator (currently Jeff Lewis - jeff@galconn.com), containing: + jeff@galois.com), containing: Your desired user-name. @@ -278,7 +257,7 @@ Set the following environment variables: - + $HOME: points to your home directory. This is where CVS @@ -326,7 +305,7 @@ - + @@ -336,12 +315,10 @@ Put the following in $HOME/.cvsrc: - - checkout -P - release -d - update -P - diff -u - +checkout -P +release -d +update -P +diff -u These are the default options for the specified CVS commands, @@ -401,9 +378,7 @@ methods above. The Approved Way to check out a source tree is as follows: - - $ cvs checkout fpconfig - +$ cvs checkout fpconfig At this point you have a new directory called fptools which contains the basic stuff @@ -411,40 +386,37 @@ some other junk. [Windows users.] The following messages appear to be harmless: - -setsockopt IPTOS_LOWDELAY: Invalid argument -setsockopt IPTOS_THROUGHPUT: Invalid argument - +setsockopt IPTOS_LOWDELAY: Invalid argument +setsockopt IPTOS_THROUGHPUT: Invalid argument You can call the fptools directory whatever you like, CVS won't mind: - - $ mv fptools directory - +$ mv fptools directory NB: after you've read the CVS manual you might be tempted to try - - $ cvs checkout -d directory fpconfig - +$ cvs checkout -d directory fpconfig instead of checking out fpconfig and then renaming it. But this doesn't work, and will result in checking out the entire repository instead of just the fpconfig bit. - - $ cd directory - $ cvs checkout ghc hslibs - +$ cd directory +$ cvs checkout ghc hslibs libraries The second command here checks out the relevant modules you want to work on. For a GHC build, for instance, - you need at least the ghc and - hslibs modules (for a full list of the - projects available, see ). + you need at least the ghc, + 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. @@ -470,9 +442,7 @@ setsockopt IPTOS_THROUGHPUT: Invalid argument Test them. You can see exactly what changes you've made by using the cvs diff command: - -$ cvs diff - +$ cvs diff lists all the changes (using the diff command) in and below the current directory. In emacs, C-c C-v = runs @@ -480,14 +450,19 @@ $ 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: - -$ cd fptools -$ cvs update - +$ cd fptools +$ cvs update This pulls in any changes that other people have made, and merges them with yours. If there are any conflicts, CVS will tell you, and you'll have to resolve them before you @@ -507,9 +482,7 @@ $ cvs update When you're happy that your change isn't going to break anything, check it in. For a one-file change: - -$ cvs commit filename - +$ cvs commit filename CVS will then pop up an editor for you to enter a "commit message", this is just a short description @@ -526,16 +499,12 @@ $ cvs commit filename way I find easiest. First type the commit message into a temporary file. Then either - -$ cvs commit -F commit-message file_1 .... file_n - +$ cvs commit -F commit-message file_1 .... file_n or, if nothing else has changed in this part of the source tree, - -$ cvs commit -F commit-message directory - +$ cvs commit -F commit-message directory where directory is a common parent directory for all your changes, and @@ -563,29 +532,31 @@ $ 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 +$ cd fptools +$ 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. - -$ cd build-tree -$ lndir source-tree - + 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 +$ lndir source-tree Some files might have been removed, so you need to remove the links pointing to these non-existent files: - -$ find . -xtype l -exec rm '{}' \; - +$ find . -xtype l -exec rm '{}' \; To be really safe, you should do @@ -630,11 +601,9 @@ $ find . -xtype l -exec rm '{}' \; So, to check out a fresh GHC 4.06 tree you would do: - - $ cvs co -r ghc-4-06 fpconfig - $ cd fptools - $ cvs co -r ghc-4-06 ghc hslibs - +$ cvs co -r ghc-4-06 fpconfig +$ cd fptools +$ cvs co -r ghc-4-06 ghc hslibs @@ -668,26 +637,20 @@ $ find . -xtype l -exec rm '{}' \; checked-out fptools tree containing just ghc, and you want to add nofib to it: - -$ cd fptools -$ cvs checkout nofib - +$ cd fptools +$ cvs checkout nofib or: - -$ cd fptools -$ cvs update -d nofib - +$ cd fptools +$ cvs update -d nofib (the -d flag tells update to create a new directory). If you just want part of the nofib suite, you can do - -$ cd fptools -$ cvs checkout nofib/spectral - +$ cd fptools +$ cvs checkout nofib/spectral This works because nofib is a module in its own right, and spectral is a subdirectory of @@ -714,9 +677,23 @@ $ cvs checkout nofib/spectral - ghc - ghc - project + + alex + alexproject + + + The Alex lexical + analyser generator for Haskell. + + + + + + ghc + ghc + project + The Glasgow Haskell Compiler (minus libraries). Absolutely @@ -725,8 +702,10 @@ $ cvs checkout nofib/spectral - glafp-utils - glafp-utilsproject + + glafp-utils + glafp-utilsproject + Utility programs, some of which are used by the build/installation system. Required for pretty much @@ -735,19 +714,23 @@ $ 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. - haggis - haggisproject + + haggis + haggisproject + The Haggis @@ -756,8 +739,10 @@ $ cvs checkout nofib/spectral - haddock - haddockproject + + haddock + haddockproject + The Haddock @@ -766,8 +751,10 @@ $ cvs checkout nofib/spectral - happy - happyproject + + happy + happyproject + The Happy Parser @@ -776,8 +763,10 @@ $ cvs checkout nofib/spectral - hdirect - hdirectproject + + hdirect + hdirectproject + The H/Direct @@ -786,8 +775,10 @@ $ cvs checkout nofib/spectral - hood - hoodproject + + hood + hoodproject + The Haskell Object Observation Debugger. @@ -795,8 +786,10 @@ $ cvs checkout nofib/spectral - hslibs - hslibsproject + + hslibs + hslibsproject + Supplemental libraries for GHC (required for building GHC). @@ -804,8 +797,10 @@ $ cvs checkout nofib/spectral - libraries - project + + libraries + project + Hierarchical Haskell library suite (required for building GHC). @@ -813,16 +808,20 @@ $ cvs checkout nofib/spectral - mhms - project + + mhms + project + The Modular Haskell Metric System. - nofib - nofibproject + + nofib + nofibproject + The NoFib suite: A collection of Haskell programs used primarily for benchmarking. @@ -830,8 +829,10 @@ $ cvs checkout nofib/spectral - testsuite - testsuiteproject + + testsuite + testsuiteproject + A testing framework, including GHC's regression test suite. @@ -853,9 +854,8 @@ $ cvs checkout nofib/spectral - - Disk space needed - Disk space needed: from about 100Mb for a basic GHC + Disk space neededDisk + space needed: from about 100Mb for a basic GHC build, up to probably 500Mb for a GHC build with everything included (libraries built several different ways, etc.). @@ -870,16 +870,16 @@ $ cvs checkout nofib/spectral Be sure that the “pre-supposed” utilities are - installed. + installed. elaborates. If you have any problem when building or installing the - Glasgow tools, please check the “known pitfalls” (). Also check the FAQ for the + Glasgow tools, please check the “known pitfalls” (). Also check the FAQ for the version you're building, which is part of the User's Guide and - available on the GHC web + available on the GHC web site. bugsknown @@ -955,13 +955,13 @@ $ cvs checkout nofib/spectral - alpha-dec-{osf,linux,freebsd,openbsd,netbsd}: + alpha-dec-{osf,linux,freebsd,openbsd,netbsd}: alpha-dec-osf alpha-dec-linux alpha-dec-freebsd alpha-dec-openbsd alpha-dec-netbsd - + The OSF port is currently working (as of GHC version 5.02.1) and well supported. The native code generator is @@ -971,8 +971,9 @@ $ cvs checkout nofib/spectral - sparc-sun-sunos4 - sparc-sun-sunos4 + sparc-sun-sunos4 + sparc-sun-sunos4 + Probably works with minor tweaks, hasn't been tested for a while. @@ -980,17 +981,29 @@ $ cvs checkout nofib/spectral - sparc-sun-solaris2 - sparc-sun-solaris2 + 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. - hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x) - hppa1.1-hp-hpux + 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 + A registerised port is available for version 4.08, but GHC hasn't been built on that platform since (as far @@ -999,11 +1012,12 @@ $ cvs checkout nofib/spectral - i386-unknown-linux (PCs running Linux, ELF binary format) - i386-*-linux + i386-unknown-linux (PCs running Linux, ELF binary format) + i386-*-linux + GHC works registerised and has a native code - generator. You must have GCC 2.7.x + generator. You must have GCC 2.7.x or later. NOTE about glibc versions: GHC binaries built on a system running glibc 2.0 won't work on a system running @@ -1015,9 +1029,9 @@ $ cvs checkout nofib/spectral - i386-unknown-freebsd (PCs running FreeBSD 2.2 or - higher) - i386-unknown-freebsd + i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher) + i386-unknown-freebsd + GHC works registerised. Pre-built packages are available in the native package format, so if you just @@ -1028,8 +1042,9 @@ $ cvs checkout nofib/spectral - i386-unknown-openbsd (PCs running OpenBSD) - i386-unknown-openbsd + i386-unknown-openbsd (PCs running OpenBSD) + i386-unknown-openbsd + Supported, with native code generator. Packages are available through the ports system in the native package @@ -1038,9 +1053,9 @@ $ cvs checkout nofib/spectral - i386-unknown-netbsd (PCs running NetBSD and - OpenBSD) - i386-unknown-netbsd + i386-unknown-netbsd (PCs running NetBSD) + i386-unknown-netbsd + Will require some minor porting effort, but should work registerised. @@ -1048,8 +1063,9 @@ $ cvs checkout nofib/spectral - i386-unknown-mingw32 (PCs running Windows) - i386-unknown-mingw32 + i386-unknown-mingw32 (PCs running Windows) + i386-unknown-mingw32 + Fully supported under Win9x, WinNT, Win2k, and WinXP. Includes a native code generator. Building from @@ -1060,8 +1076,19 @@ $ cvs checkout nofib/spectral - ia64-unknown-linux - ia64-unknown-linux + 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. @@ -1069,8 +1096,20 @@ $ cvs checkout nofib/spectral - mips-sgi-irix5 - mips-sgi-irix[5-6] + amd64-unknown-openbsd + amd64-unknown-linux + + + (This is the same as x86_64-unknown-openbsd). GHC + currently works unregisterised. A registerised port is in + progress. + + + + + mips-sgi-irix5 + mips-sgi-irix[5-6] + Port has worked in the past, but hasn't been tested for some time (and will certainly have rotted in various @@ -1081,8 +1120,18 @@ $ cvs checkout nofib/spectral - powerpc-ibm-aix - powerpc-ibm-aix + mips64-sgi-irix6 + mips-sgi-irix6 + + + GHC currently works unregisterised. + + + + + powerpc-ibm-aix + powerpc-ibm-aix + Port currently doesn't work, needs some minimal porting effort. As usual, we don't have access to @@ -1092,17 +1141,19 @@ $ cvs checkout nofib/spectral - powerpc-apple-darwin - powerpc-apple-darwin + powerpc-apple-darwin + powerpc-apple-darwin + - Supported registerised. No native code - generator. + Supported registerised. Native code generator is + almost working. - powerpc-apple-linux - powerpc-apple-linux + powerpc-apple-linux + powerpc-apple-linux + Not supported (yet). @@ -1141,9 +1192,28 @@ $ cvs checkout nofib/spectral - Perl - pre-supposed: Perl - Perl, pre-supposed + 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 + You have to have Perl to proceed! Perl version 5 at least is required. GHC has been known to @@ -1165,10 +1235,10 @@ $ cvs checkout nofib/spectral - GNU C (gcc) - pre-supposed: GCC (GNU C - compiler) GCC (GNU C - compiler), pre-supposed + GNU C (gcc) + pre-supposed: GCC (GNU C compiler) + GCC (GNU C compiler), pre-supposed + We recommend using GCC version 2.95.2 on all platforms. Failing that, version 2.7.2 is stable on most @@ -1177,9 +1247,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) @@ -1187,9 +1260,9 @@ $ cvs checkout nofib/spectral - GNU Make - makeGNU - + GNU Make + makeGNU + The fptools build system makes heavy use of features specific to GNU make, so you must have @@ -1199,8 +1272,9 @@ $ cvs checkout nofib/spectral - Happy - Happy + Happy + Happy + Happy is a parser generator tool for Haskell, and is used to generate GHC's parsers. Happy is written in @@ -1208,7 +1282,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. @@ -1216,26 +1290,47 @@ $ cvs checkout nofib/spectral - Autoconf - pre-supposed: Autoconf - Autoconf, pre-supposed + Alex + Alex + - GNU Autoconf is needed if you intend to build from the + 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 + + + GNU autoconf is needed if you intend to build from the CVS sources, it is not needed if you just intend to build a standard source distribution. - Autoconf builds the configure - script from configure.in and - aclocal.m4. If you modify either of - these files, you'll need autoconf to - rebuild configure. + Version 2.52 or later of the autoconf package is required. + NB. version 2.13 will no longer work, as of GHC version + 6.1. + + autoreconf (from the autoconf package) + recursively builds configure scripts from + the corresponding configure.ac and + aclocal.m4 files. If you modify one of + the latter files, you'll need autoreconf to + rebuild the corresponding configure. - sed - pre-supposed: sed - sed, pre-supposed + sed + pre-supposed: sed + sed, pre-supposed + You need a working sed if you are going to build from sources. The build-configuration stuff @@ -1259,13 +1354,14 @@ $ cvs checkout nofib/spectral - PVM version 3: + PVM version 3: pre-supposed: PVM3 (Parallel Virtual Machine) - PVM3 (Parallel Virtual Machine), pre-supposed + PVM3 (Parallel Virtual Machine), pre-supposed + 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 @@ -1283,8 +1379,9 @@ $ cvs checkout nofib/spectral - bash: - bash, presupposed (Parallel Haskell only) + bash: + bash, presupposed (Parallel Haskell only) + Sadly, the gr2ps script, used to convert “parallelism profiles” to PostScript, @@ -1295,54 +1392,15 @@ $ cvs checkout nofib/spectral - - Tools for building the Documentation - - The following additional tools are required if you want to - format the documentation that comes with the - fptools projects: - - - - DocBook - pre-supposed: DocBook - DocBook, pre-supposed - - All our documentation is written in SGML, using the - DocBook DTD. Instructions on installing and configuring - the DocBook tools are in the installation guide (in the - GHC user guide). - - - - - TeX - pre-supposed: TeX - TeX, pre-supposed - - A decent TeX distribution is required if you want to - produce printable documentation. We recomment teTeX, - which includes just about everything you need. - - - - - In order to actually build any documentation, you need to - set SGMLDocWays in your - build.mk. Valid values to add to this list - are: dvi, ps, - pdf, html, and - rtf. - - Other useful tools - Flex - pre-supposed: flex - flex, pre-supposed + Flex + pre-supposed: flex + flex, pre-supposed + This is a quite-a-bit-better-than-Lex lexer. Used to build a couple of utilities in @@ -1352,6 +1410,10 @@ $ cvs checkout nofib/spectral + + More tools are required if you want to format the documentation + that comes with GHC and other fptools projects. See . @@ -1377,6 +1439,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: + +$ autoreconf +$ ./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 @@ -1398,7 +1480,7 @@ $ cvs checkout nofib/spectral - configure.in, + configure.ac, config.sub, config.guess: these files support the configuration process. @@ -1421,7 +1503,7 @@ $ cvs checkout nofib/spectral 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. @@ -1452,8 +1534,8 @@ $ cvs checkout nofib/spectral are two (If you don't have either, the source distribution includes sources for the X11 lndir—check out - fptools/glafp-utils/lndir). See for a typical invocation. + fptools/glafp-utils/lndir). See for a typical invocation. The build tree does not need to be anywhere near the source tree in the file system. Indeed, one advantage of @@ -1461,8 +1543,8 @@ $ cvs checkout nofib/spectral can be placed in a non-backed-up partition, saving your systems support people from backing up untold megabytes of easily-regenerated, and rapidly-changing, gubbins. The golden - rule is that (with a single exception—) absolutely everything in + rule is that (with a single exception—) absolutely everything in the build tree is either a symbolic link to the source tree, or else is mechanically generated. It should be perfectly OK for your build tree to vanish overnight; an hour or @@ -1497,7 +1579,7 @@ $ cvs checkout nofib/spectral $(FPTOOLS_TOP) unless otherwise stated. For example, the file ghc/mk/target.mk is actually - $(FPTOOLS_TOP)/ghc/mk/target.mk. + $(FPTOOLS_TOP)/ghc/mk/target.mk. @@ -1530,34 +1612,35 @@ $ 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 - autoconfautoconf - (with no arguments). This GNU program converts - $(FPTOOLS_TOP)/configure.in + issue the command +autoreconf + autoreconf + (with no arguments). This GNU program (recursively) converts + $(FPTOOLS_TOP)/configure.ac and + $(FPTOOLS_TOP)/aclocal.m4 to a shell script called - $(FPTOOLS_TOP)/configure. + $(FPTOOLS_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 + a message like "No rule to make target 'mk/config.h.in'". - Some projects, including GHC, have their own - configure script. If there's an - $(FPTOOLS_TOP)/<project>/configure.in, - 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 - 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. + Some projects, including GHC, 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). + + These steps are completely platform-independent; they just mean + that the human-written files (configure.ac and + aclocal.m4) can be short, although the resulting + files (the configure shell scripts and the C header + template mk/config.h.in) are long. @@ -1567,15 +1650,13 @@ $ cvs checkout nofib/spectral Runs the newly-created configure script, thus: - -./configure args - +./configure args configure's mission is to scurry round your computer working out what architecture it has, what operating system, whether it has the - vfork system call, where - yacc is kept, whether + vfork system call, where + 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 @@ -1619,9 +1700,9 @@ $ cvs checkout nofib/spectral - --with-ghc=path - --with-ghc - + --with-ghc=path + --with-ghc + Specifies the path to an installed GHC which you would like to use. This compiler will be used @@ -1636,9 +1717,9 @@ $ cvs checkout nofib/spectral - --with-hc=path - --with-hc - + --with-hc=path + --with-hc + Specifies the path to any installed Haskell compiler. This compiler will be used for compiling @@ -1648,9 +1729,9 @@ $ cvs checkout nofib/spectral - --with-gcc=path - --with-gcc - + --with-gcc=path + --with-gcc + Specifies the path to the installed GCC. This compiler will be used to compile all C files, @@ -1661,13 +1742,6 @@ $ cvs checkout nofib/spectral - - configure caches the results of - its run in config.cache. Quite often - you don't want that; you're running - configure a second time because - something has changed. In that case, simply delete - config.cache. @@ -1712,12 +1786,13 @@ $ 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: - -GhcHcOpts=-O -Rghc-timing - +GhcHcOpts=-O -Rghc-timing The accompanying comment explains that this is the list of flags passed to GHC when building GHC itself. For doing @@ -1727,9 +1802,7 @@ GhcHcOpts=-O -Rghc-timing or, if you prefer, - -GhcHcOpts += -DDEBUG - +GhcHcOpts += -DDEBUG GNU make allows existing definitions to have new text appended using the “+=” @@ -1740,9 +1813,7 @@ GhcHcOpts += -DDEBUG lot quicker), you can just override GhcLibHcOpts altogether: - -GhcHcOpts=-DDEBUG -Rghc-timing - +GhcHcOpts=-DDEBUG -Rghc-timing When reading config.mk.in, remember that anything between “@...@” signs is going to be substituted @@ -1751,19 +1822,15 @@ GhcHcOpts=-DDEBUG -Rghc-timing you want, but you need to be a bit surer what you are doing. 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 mk/build.mk file at all; if you don't, @@ -1794,8 +1861,8 @@ YACC = myyacc or source distribution). Say you call the root directory myfptools (it does not have to be called fptools). Make sure that you - have the essential files (see ). + have the essential files (see ). @@ -1803,10 +1870,8 @@ YACC = myyacc (Optional) Use lndir or mkshadowdir to create a build tree. - -$ cd myfptools -$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 - +$ cd myfptools +$ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 (N.B. mkshadowdir's first argument is taken relative to its second.) You probably want to give @@ -1819,39 +1884,25 @@ $ mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 Change directory to the build tree. Everything is going to happen there now. - -$ cd /scratch/joe-bloggs/myfptools-sun4 - +$ cd /scratch/joe-bloggs/myfptools-sun4 Prepare for system configuration: - -$ autoconf - +$ autoreconf (You can skip this step if you are starting from a source distribution, and you already have configure and mk/config.h.in.) - - Some projects, including GHC itself, have their own - configure scripts, so it is necessary to run autoconf again - in the appropriate subdirectories. eg: - - -$ (cd ghc; autoconf) - Do system configuration: - -$ ./configure - +$ ./configure Don't forget to check whether you need to add any arguments to configure; for example, a @@ -1864,9 +1915,7 @@ $ ./configure adding definitions for your desired configuration options. - -$ emacs mk/build.mk - +$ emacs mk/build.mk @@ -1900,7 +1949,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. @@ -2050,8 +2184,8 @@ $ emacs mk/build.mk is only available in the root directory $(FPTOOLS_TOP); it has - been discussed in . + been discussed in . @@ -2067,9 +2201,7 @@ $ emacs mk/build.mk generated .depend file will contain the dependency: - -Foo.o : Baz.hi - +Foo.o : Baz.hi which says that the object file Foo.o depends on the interface file @@ -2113,13 +2245,14 @@ 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. Happy can similarly be run from the build tree, using - happy/src/happy-inplace. + happy/src/happy-inplace, and similarly for + Alex and Haddock. @@ -2135,9 +2268,7 @@ Foo.o : Baz.hi make is going to rebuild everything anyway, the following hack may be useful: - -gmake FAST=YES - +gmake FAST=YES This tells the make system to ignore dependencies and just build what you tell it to. In other words, it's equivalent to @@ -2178,7 +2309,7 @@ gmake FAST=YES the contents of any make variable in the context of the current Makefile: -$ make show VALUE=HS_SRCS +$ make show VALUE=HS_SRCS where you can replace HS_SRCS with the name of any variable you wish to see the value of. @@ -2206,8 +2337,7 @@ gmake FAST=YES Makefile, minimal - -# Makefile for fptools project "small" +# Makefile for fptools project "small" TOP = .. include $(TOP)/mk/boilerplate.mk @@ -2215,8 +2345,7 @@ include $(TOP)/mk/boilerplate.mk SRCS = $(wildcard *.lhs) $(wildcard *.c) HS_PROG = small -include $(TOP)/target.mk - +include $(TOP)/target.mk this Makefile has three sections: @@ -2235,11 +2364,11 @@ directive. a file of “boilerplate” code from the level above (which in this case will be - FPTOOLS_TOP/mk/boilerplate.mkboilerplate.mk). + FPTOOLS_TOP/mk/boilerplate.mkboilerplate.mk). As its name suggests, boilerplate.mk consists of a large quantity of standard Makefile code. We discuss this - boilerplate in more detail in . + boilerplate in more detail in . include, directive in Makefiles Makefile inclusion @@ -2251,9 +2380,7 @@ directive. directory in which the boilerplate.mk file is. It is not OK to simply say - -include ../mk/boilerplate.mk # NO NO NO - +include ../mk/boilerplate.mk # NO NO NO Why? Because the boilerplate.mk @@ -2266,7 +2393,7 @@ include ../mk/boilerplate.mk # NO NO NO included sits.) In general, every file foo.mk assumes that - $(TOP)/mk/foo.mk + $(TOP)/mk/foo.mk refers to itself. It is up to the Makefile doing the include to ensure this is the case. @@ -2291,8 +2418,8 @@ include ../mk/boilerplate.mk # NO NO NO HS_PROGHS_PROG (the executable binary to be built). We will discuss in more detail what the “standard variables” are, - and how they affect what happens, in . + and how they affect what happens, in . The definition for SRCS uses the useful GNU make construct @@ -2311,12 +2438,12 @@ include ../mk/boilerplate.mk # NO NO NO code, called target.mktarget.mk. It contains the rules that tell gmake how - to make the standard targets (). Why, you ask, can't this + to make the standard targets (). Why, you ask, can't this standard code be part of boilerplate.mk? Good question. We - discuss the reason later, in . + discuss the reason later, in . You do not have to include the @@ -2325,8 +2452,8 @@ include ../mk/boilerplate.mk # NO NO NO though, you will find quite a big payoff from using the canned rules in target.mk; the price tag is that you have to understand what canned rules get - enabled, and what they do (). + enabled, and what they do (). @@ -2382,8 +2509,7 @@ include ../mk/boilerplate.mk # NO NO NO rare.) To give you the idea, here's part of the directory structure for the (rather large) GHC project: - -$(FPTOOLS_TOP)/ghc/ +$(FPTOOLS_TOP)/ghc/ Makefile mk/ boilerplate.mk @@ -2398,15 +2524,14 @@ $(FPTOOLS_TOP)/ghc/ Makefile parser/...source files for parser... renamer/...source files for renamer... - ...etc... - + ...etc... The sub-directories docs, driver, compiler, and so on, each contains a sub-component of GHC, and each has its own Makefile. There must also be a Makefile in - $(FPTOOLS_TOP)/ghc. + $(FPTOOLS_TOP)/ghc. It does most of its work by recursively invoking gmake on the Makefiles in the sub-directories. We say that @@ -2508,9 +2633,7 @@ $(FPTOOLS_TOP)/ghc/ augment them. For example, a Makefile might say: - -SRC_HC_OPTS += -O - +SRC_HC_OPTS += -O thereby adding “” to the end of @@ -2520,7 +2643,7 @@ SRC_HC_OPTS += -O target.mk contains make rules for the standard targets - described in . These + described in . These rules are selectively included, depending on the setting of certain make variables. These variables are usually set in the middle section of the @@ -2537,13 +2660,11 @@ SRC_HC_OPTS += -O gmake commits target and dependency lists earlier than it should. For example, - target.mk has a rule that looks + target.mk has a rule that looks like this: - -$(HS_PROG) : $(OBJS) - $(HC) $(LD_OPTS) $< -o $@ - +$(HS_PROG) : $(OBJS) + $(HC) $(LD_OPTS) $< -o $@ If this rule was in boilerplate.mk then @@ -2584,23 +2705,25 @@ $(HS_PROG) : $(OBJS) boilerplate.mk If you look at - $(FPTOOLS_TOP)/mk/boilerplate.mk + $(FPTOOLS_TOP)/mk/boilerplate.mk you will find that it consists of the following sections, each held in a separate file: - config.mk - config.mk + config.mk + config.mk + is the build configuration file we discussed at - length in . + length in . - paths.mk - paths.mk + paths.mk + paths.mk + defines make variables for pathnames and file lists. This file contains code for @@ -2616,9 +2739,9 @@ $(HS_PROG) : $(OBJS) - ALL_DIRS - ALL_DIRS - + ALL_DIRS + ALL_DIRS + Set to a list of directories to search in addition to the current directory for source @@ -2627,9 +2750,9 @@ $(HS_PROG) : $(OBJS) - EXCLUDE_SRCS - EXCLUDE_SRCS - + EXCLUDE_SRCS + EXCLUDE_SRCS + Set to a list of source files (relative to the current directory) to omit from the automatic @@ -2645,9 +2768,9 @@ $(HS_PROG) : $(OBJS) - EXTRA_SRCS - EXCLUDE_SRCS - + EXTRA_SRCS + EXCLUDE_SRCS + Set to a list of extra source files (perhaps in directories not listed in @@ -2662,8 +2785,9 @@ $(HS_PROG) : $(OBJS) - SRCS - SRCS + SRCS + SRCS + All source files found, sorted and without duplicates, including those which might not exist @@ -2675,8 +2799,9 @@ $(HS_PROG) : $(OBJS) - HS_SRCS - HS_SRCS + HS_SRCS + HS_SRCS + all Haskell source files in the current directory, including those derived from other source @@ -2686,8 +2811,9 @@ $(HS_PROG) : $(OBJS) - HS_OBJS - HS_OBJS + HS_OBJS + HS_OBJS + Object files derived from HS_SRCS. @@ -2695,8 +2821,9 @@ $(HS_PROG) : $(OBJS) - HS_IFACES - HS_IFACES + HS_IFACES + HS_IFACES + Interface files (.hi files) derived from HS_SRCS. @@ -2704,16 +2831,18 @@ $(HS_PROG) : $(OBJS) - C_SRCS + C_SRCS C_SRCS + All C source files found. - C_OBJS + C_OBJS C_OBJS + Object files derived from C_SRCS. @@ -2721,8 +2850,9 @@ $(HS_PROG) : $(OBJS) - SCRIPT_SRCS + SCRIPT_SRCS SCRIPT_SRCS + All script source files found (.lprl files). @@ -2730,8 +2860,9 @@ $(HS_PROG) : $(OBJS) - SCRIPT_OBJS + SCRIPT_OBJS SCRIPT_OBJS + object files derived from SCRIPT_SRCS @@ -2740,8 +2871,9 @@ $(HS_PROG) : $(OBJS) - HSC_SRCS + HSC_SRCS HSC_SRCS + All hsc2hs source files (.hsc files). @@ -2749,8 +2881,9 @@ $(HS_PROG) : $(OBJS) - HAPPY_SRCS + HAPPY_SRCS HAPPY_SRCS + All happy source files (.y or .hy files). @@ -2758,8 +2891,9 @@ $(HS_PROG) : $(OBJS) - OBJS + OBJS OBJS + the concatenation of $(HS_OBJS), @@ -2785,23 +2919,25 @@ $(HS_PROG) : $(OBJS) - opts.mk - opts.mk + opts.mk + opts.mk + defines make variables for option strings to pass to each program. For example, it defines HC_OPTSHC_OPTS, the option strings to pass to the Haskell compiler. See - . + . - suffix.mk - suffix.mk + suffix.mk + suffix.mk + - defines standard pattern rules—see . + defines standard pattern rules—see . @@ -2830,11 +2966,9 @@ $(HS_PROG) : $(OBJS) Almost all the rules look something like this: - -%.o : %.c +%.o : %.c $(RM) $@ - $(CC) $(CC_OPTS) -c $< -o $@ - + $(CC) $(CC_OPTS) -c $< -o $@ Here's how to understand the rule. It says that something.o (say @@ -2862,9 +2996,8 @@ $(HS_PROG) : $(OBJS) defined in mk/opts.mk. Almost all of them are defined like this: - -CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) - +CC_OPTS = \ + $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) The four variables from which CC_OPTS is built have the following @@ -2888,7 +3021,7 @@ CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) mp. The variable WAY_CC_OPTS holds options to pass to the C compiler when compiling the - standard way. ( dicusses + standard way. ( dicusses multi-way compilation.) @@ -2910,9 +3043,7 @@ CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS) extra options to pass to all C compilations. This is intended for command line use, thus: - -gmake libHS.a EXTRA_CC_OPTS="-v" - +gmake libHS.a EXTRA_CC_OPTS="-v" @@ -2923,8 +3054,8 @@ gmake libHS.a EXTRA_CC_OPTS="-v" target.mk target.mk contains canned rules for - all the standard targets described in . It is complicated by the fact + all the standard targets described in . It is complicated by the fact that you don't want all of these rules to be active in every Makefile. Rather than have a plethora of tiny files which you can include selectively, there is a single @@ -3018,10 +3149,8 @@ gmake libHS.a EXTRA_CC_OPTS="-v" All of these rules are “double-colon” rules, thus - -install :: $(HS_PROG) - ...how to install it... - +install :: $(HS_PROG) + ...how to install it... GNU make treats double-colon rules as separate entities. If there are several double-colon rules for @@ -3052,7 +3181,7 @@ install :: $(HS_PROG) When SUBDIRS is defined, target.mk includes a rather neat rule for - the standard targets ( that + the standard targets ( that simply invokes make recursively in each of the sub-directories. @@ -3141,8 +3270,8 @@ install :: $(HS_PROG) Makefile to the list of way tags you want these targets built for. The mechanism here is very much like the recursive invocation of - make in sub-directories (). It is up to you to set + make in sub-directories (). It is up to you to set WAYS in your Makefile; this is how you control what ways will get built. @@ -3162,10 +3291,8 @@ install :: $(HS_PROG) file will match. The key pattern rules (in suffix.mk) look like this: - -%.$(way_)o : %.lhs - $(HC) $(HC_OPTS) $< -o $@ - +%.$(way_)o : %.lhs + $(HC) $(HC_OPTS) $< -o $@ Neat, eh? @@ -3176,9 +3303,7 @@ install :: $(HS_PROG) to build files related to a particular way in the current directory. eg. - -$ make way=p - +$ make way=p will build files for the profiling way only in the current directory. @@ -3201,6 +3326,258 @@ $ make way=p + + Building the documentation + + + Tools for building the Documentation + + The following additional tools are required if you want to + format the documentation that comes with the + fptools projects: + + + + DocBook + pre-supposed: DocBook + DocBook, pre-supposed + + + Much of our documentation is written in SGML, using + the DocBook DTD. Instructions on installing and + configuring the DocBook tools are below. + + + + + TeX + pre-supposed: TeX + TeX, pre-supposed + + + A decent TeX distribution is required if you want to + produce printable documentation. We recomment teTeX, + which includes just about everything you need. + + + + + Haddock + Haddock + + + 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 + to build. + + + + + + + Installing the DocBook tools + + + Installing the DocBook tools on Linux + + If you're on a recent RedHat system (7.0+), you probably + have working DocBook tools already installed. The configure + script should detect your setup and you're away. + + If you don't have DocBook tools installed, and you are + using a system that can handle RedHat RPM packages, you can + probably use the Cygnus + DocBook tools, which is the most shrink-wrapped SGML + suite that we could find. You need all the RPMs except for + psgml (i.e. docbook, + jade, jadetex, + sgmlcommon and + stylesheets). Note that most of these + RPMs are architecture neutral, so are likely to be found in a + noarch directory. The SuSE RPMs also + work; the RedHat ones don't in RedHat 6.2 + (7.0 and later should be OK), but they are easy to fix: just + make a symlink from + /usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl + to /usr/lib/sgml/lib/dblib.dsl. + + + + Installing DocBook on FreeBSD + + On FreeBSD systems, the easiest way to get DocBook up + and running is to install it from the ports tree or a + pre-compiled package (packages are available from your local + FreeBSD mirror site). + + To use the ports tree, do this: +$ cd /usr/ports/textproc/docproj +$ make install + This installs the FreeBSD documentation project tools, which + includes everything needed to format the GHC + documentation. + + + + Installing from binaries on Windows + + It's a good idea to use Norman Walsh's installation + notes as a guide. You should get version 3.1 of + DocBook, and note that his file test.sgm + won't work, as it needs version 3.0. You should unpack Jade + into \Jade, along with the entities, + DocBook into \docbook, and the DocBook + stylesheets into \docbook\stylesheets (so + they actually end up in + \docbook\stylesheets\docbook). + + + + + Installing the DocBook tools from source + + + Jade + + Install OpenJade + (Windows binaries are available as well as sources). If you + want DVI, PS, or PDF then install JadeTeX from the + dsssl subdirectory. (If you get the + error: + +! LaTeX Error: Unknown option implicit=false' for package hyperref'. + + your version of hyperref is out of date; + download it from CTAN + (macros/latex/contrib/supported/hyperref), + and make it, ensuring that you have first removed or renamed + your old copy. If you start getting file not found errors + when making the test for hyperref, you + can abort at that point and proceed straight to + make install, or enter them as + ../filename.) + + Make links from virtex to + jadetex and + pdfvirtex to + pdfjadetex (otherwise DVI, PostScript + and PDF output will not work). Copy + dsssl/*.{dtd,dsl} and + catalog to + /usr/[local/]lib/sgml. + + + + DocBook and the DocBook stylesheets + + Get a Zip of DocBook + and install the contents in + /usr/[local/]/lib/sgml. + + Get the DocBook + stylesheets and install in + /usr/[local/]lib/sgml/stylesheets + (thereby creating a subdirectory docbook). For indexing, + copy or link collateindex.pl from the + DocBook stylesheets archive in bin into + a directory on your PATH. + + Download the ISO + entities into + /usr/[local/]lib/sgml. + + + + + + Configuring the DocBook tools + + Once the DocBook tools are installed, the configure script + will detect them and set up the build system accordingly. If you + have a system that isn't supported, let us know, and we'll try + to help. + + + + Remaining problems + + If you install from source, you'll get a pile of warnings + of the form + +DTDDECL catalog entries are not supported + + every time you build anything. These can safely be ignored, but + if you find them tedious you can get rid of them by removing all + the DTDDECL entries from + docbook.cat. + + + + Building the documentation + + To build documentation in a certain format, you can + say, for example, + +$ make html + + to build HTML documentation below the current directory. + The available formats are: dvi, + ps, pdf, + html, and rtf. Note that + not all documentation can be built in all of these formats: HTML + documentation is generally supported everywhere, and DocBook + documentation might support the other formats (depending on what + other tools you have installed). + + All of these targets are recursive; that is, saying + make html will make HTML docs for all the + documents recursively below the current directory. + + Because there are many different formats that the DocBook + documentation can be generated in, you have to select which ones + you want by setting the SGMLDocWays variable + to a list of them. For example, in + build.mk you might have a line: + +SGMLDocWays = html ps + + This will cause the documentation to be built in the requested + formats as part of the main build (the default is not to build + any documentation at all). + + + + Installing the documentation + + To install the documentation, use: + +$ make install-docs + + This will install the documentation into + $(datadir) (which defaults to + $(prefix)/share). The exception is HTML + documentation, which goes into + $(datadir)/html, to keep things tidy. + + Note that unless you set $(SGMLDocWays) + to a list of formats, the install-docs target + won't do anything for SGML documentation. + + + + + Porting GHC @@ -3239,17 +3616,16 @@ $ make way=p 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 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: @@ -3263,8 +3639,8 @@ $ make way=p corresponding Haskell source (.hs or .lhs) in the compiler subdirectory ghc/compiler and in the libraries - (ghc/lib, and subdirectories of - hslibs). + (subdirectories of hslibs and + libraries). @@ -3276,9 +3652,7 @@ $ make way=p command will execute the whole build process (it won't install yet): - -foo% distrib/hc-build --prefix=dir - +foo% distrib/hc-build --prefix=dir --hc-build By default, the installation directory is @@ -3291,9 +3665,7 @@ foo% distrib/hc-build --prefix=dir build process, you can install the resulting system, as normal, with - -foo% make install - +foo% make install @@ -3333,65 +3705,216 @@ 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: - - -# build.mk for GHC 4.08.x -GhcWithRegisterised=NO - - - -# build.mk for GHC 5.xx -GhcUnregisterised=YES - - - Version 5.xx 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. + 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. + + + 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: + +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 + + + + 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. + + + @@ -3402,9 +3925,9 @@ GhcUnregisterised=YES - ghc/includes/MachRegs.h - MachRegs.h - + ghc/includes/MachRegs.h + MachRegs.h + Defines the STG-register to machine-register mapping. You need to know your platform's C calling @@ -3414,9 +3937,9 @@ GhcUnregisterised=YES - ghc/includes/TailCalls.h - TailCalls.h - + ghc/includes/TailCalls.h + TailCalls.h + Macros that cooperate with the mangler (see ) to make proper tail-calls @@ -3424,9 +3947,9 @@ GhcUnregisterised=YES - ghc/rts/Adjustor.c - Adjustor.c - + ghc/rts/Adjustor.c + Adjustor.c + Support for foreign import "wrapper" @@ -3437,9 +3960,9 @@ GhcUnregisterised=YES - ghc/rts/StgCRun.c - StgCRun.c - + ghc/rts/StgCRun.c + StgCRun.c + The little assembly layer between the C world and the Haskell world. See the comments and code for the @@ -3447,12 +3970,12 @@ GhcUnregisterised=YES - ghc/rts/MBlock.h - ghc/rts/MBlock.c - MBlock.h - - MBlock.c - + ghc/rts/MBlock.h + MBlock.h + + ghc/rts/MBlock.c + MBlock.c + These files are really OS-specific rather than architecture-specific. In MBlock.h @@ -3470,8 +3993,10 @@ GhcUnregisterised=YES The mangler - The mangler is an evil Perl-script that rearranges the - assembly code output from gcc to do two main things: + The mangler is an evil Perl-script + (ghc/driver/mangler/ghc-asm.lprl) that + rearranges the assembly code output from gcc to do two main + things: @@ -3502,6 +4027,23 @@ GhcUnregisterised=YES + The splitter + + The splitter is another evil Perl script + (ghc/driver/split/ghc-split.lprl). It + cooperates with the mangler to support object splitting. + Object splitting is what happens when the + option is passed to GHC: the + object file is split into many smaller objects. This feature + is used when building libraries, so that a program statically + linked against the library will pull in less of the + library. + + The splitter has some platform-specific stuff; take a + look and tweak it for your system. + + + The native code generator The native code generator isn't essential to getting a @@ -3518,10 +4060,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! @@ -3543,7 +4088,7 @@ WARNINGS about pitfalls and known “problems”: - + @@ -3559,9 +4104,7 @@ of choice). The best way around it is to say - -export TMPDIR=<dir> - +export TMPDIR=<dir> in your build.mk file. Then GHC and the other fptools programs will use the appropriate directory @@ -3593,11 +4136,9 @@ incompatible pointer type” out of GCC. Harmless. Similarly, archiving warning messages like the following are not a problem: - -ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_ +ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_ ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_ -... - +... @@ -3637,15 +4178,13 @@ above. -and try again: gmake. (see for information about +and try again: gmake. (see for information about <module>_HC_OPTS.) Alternatively, just cut to the chase: - -% cd ghc/compiler -% make EXTRA_HC_OPTS=-optCrts-M128M - +% cd ghc/compiler +% make EXTRA_HC_OPTS=-optCrts-M128M @@ -3669,13 +4208,11 @@ this bug also suggests that you have an old GCC. You may need to re-ranlibranlib your libraries (on Sun4s). - -% cd $(libdir)/ghc-x.xx/sparc-sun-sunos4 +% cd $(libdir)/ghc-x.xx/sparc-sun-sunos4 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv... ? ranlib $i ? # or, on some machines: ar s $i -? end - +? end We'd be interested to know if this is still necessary. @@ -3691,18 +4228,14 @@ a bit from one Unix to another. One particular gotcha is macro calls like this: - -SLIT("Hello, world") - +SLIT("Hello, world") Some cpps treat the comma inside the string as separating two macro arguments, so you get - -:731: macro `SLIT' used with too many (2) args - +:731: macro `SLIT' used with too many (2) args Alas, cpp doesn't tell you the offending file! @@ -3711,58 +4244,666 @@ Workaround: don't put weird things in string args to cpp macr - + -Notes for building under Windows +Platforms, scripts, and file names + +GHC is designed both to be built, and to run, on both Unix and Windows. This flexibility +gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter. + + +Windows platforms: Cygwin, MSYS, and MinGW + + The build system is built around Unix-y makefiles. Because it's not native, +the Windows situation for building GHC is particularly confusing. This section +tries to clarify, and to establish terminology. + +MinGW + MinGW (Minimalist GNU for Windows) +is a collection of header +files and import libraries that allow one to use gcc and produce +native Win32 programs that do not rely on any third-party DLLs. The +current set of tools include GNU Compiler Collection (gcc), GNU Binary +Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted +other utilities. + + + The down-side of MinGW is that the MinGW libraries do not support anything like the full +Posix interface. + + + +Cygwin and MSYS + +You can't use the MinGW to build GHC, because MinGW doesn't have a shell, +or the standard Unix commands such as mv, rm, +ls, nor build-system stuff such as make and cvs. +For that, there are two choices: Cygwin +and MSYS: + + + +Cygwin comes with compilation tools (gcc, ld and so on), which +compile code that has access to all of Posix. The price is that the executables must be +dynamically linked with the Cygwin DLL, so that you cannot run a Cywin-compiled program on a machine +that doesn't have Cygwin. Worse, Cygwin is a moving target. The name of the main DLL, cygwin1.dll +does not change, but the implementation certainly does. Even the interfaces to functions +it exports seem to change occasionally. + + + +MSYS is a fork of the Cygwin tree, so they +are fundamentally similar. However, MSYS is by design much smaller and simpler. Access to the file system goes +through fewer layers, so MSYS is quite a bit faster too. + + +Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These +compile binaries that run with no DLL support, on any Win32 system. +However, MSYS does come with all the make-system tools, such as make, autoconf, +cvs, ssh etc. To get these, you have to download the +MsysDTK (Developer Tool Kit) package, as well as the base MSYS package. + +MSYS does have a DLL, but it's only used by MSYS commands (sh, rm, +ssh and so on), +not by programs compiled under MSYS. + + + + + + + +Targeting MinGW + +We want GHC to compile programs that work on any Win32 system. Hence: + + +GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only +invokes the MinGW tools, not the Cygwin ones. That means that the programs GHC compiles +will work on any system, but it also means that the programs GHC compiles do not have access +to all of Posix. In particular, they cannot import the (Haskell) Posix +library; they have to do +their input output using standard Haskell I/O libraries, or native Win32 bindings. + We will call a GHC that targets MinGW in this way GHC-mingw. + + + +To make the GHC distribution self-contained, the GHC distribution includes the MinGW gcc, +as, ld, and a bunch of input/output libraries. + + +So GHC targets MinGW, not Cygwin. +It is in principle possible to build a version of GHC, GHC-cygwin, +that targets Cygwin instead. The up-side of GHC-cygwin is +that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library. +We do not support GHC-cygwin, however; it is beyond our resources. + + +While GHC targets MinGW, that says nothing about +how GHC is built. We use both MSYS and Cygwin as build environments for +GHC; both work fine, though MSYS is rather lighter weight. + +In your build tree, you build a compiler called ghc-inplace. It +uses the gcc that you specify using the + flag when you run +configure (see below). +The makefiles are careful to use ghc-inplace (not gcc) +to compile any C files, so that it will in turn invoke the correct gcc rather that +whatever one happens to be in your path. However, the makefiles do use whatever ld +and ar happen to be in your path. This is a bit naughty, but (a) they are only +used to glom together .o files into a bigger .o file, or a .a file, +so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b) +Cygwin and MinGW use the same .o file format. So its ok. + + + + File names + +Cygwin, MSYS, and the underlying Windows file system all understand file paths of form c:/tmp/foo. +However: + + +MSYS programs understand /bin, /usr/bin, and map Windows's lettered drives as +/c/tmp/foo etc. The exact mount table is given in the doc subdirectory of the MSYS distribution. + + When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS /bin +directory. If so, it just invokes it. If not, it assumes the program is no an MSYS program, and walks over the command-line +arguments changing MSYS paths into native-compatible paths. It does this inside sub-arguments and inside quotes. For example, +if you invoke +foogle -B/c/tmp/baz +the MSYS shell will actually call foogle with argument -Bc:/tmp/baz. + + + +Cygwin programs have a more complicated mount table, and map the lettered drives as /cygdrive/c/tmp/foo. + +The Cygwin shell does no argument processing when invoking non-Cygwin programs. + + + + + +Host System vs Target System + + +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. + + + + + + +Wrapper scripts + + +Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries. +For installed programs, the strategy depends on the platform. We'll use +GHC itself as an example: + + + On Unix, the command ghc is a shell script, generated by adding installation + paths to the front of the source file ghc.sh, + that invokes the real binary, passing "-Bpath" as an argument to tell ghc + where to find its supporting files. + + + + On vanilla Windows, it turns out to be much harder to make reliable script to be run by the + native Windows shell cmd (e.g. limits on the length + of the command line). So instead we invoke the GHC binary directly, with no -B flag. + GHC uses the Windows getExecDir function to find where the executable is, + and from that figures out where the supporting files are. + + +(You can find the layout of GHC's supporting files in the + section "Layout of installed files" of Section 2 of the GHC user guide.) + -This section summarises how to get the utilities you need on your -Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for +Things work differently for in-place execution, where you want to +execute a program that has just been built in a build tree. The difference is that the +layout of the supporting files is different. +In this case, whether on Windows or Unix, we always use a shell script. This works OK +on Windows because the script is executed by MSYS or Cygwin, which don't have the +shortcomings of the native Windows cmd shell. + + + + + + +Instructions for building under Windows + + +This section gives detailed instructions for how to build +GHC from source on your Windows machine. Similar instructions for installing and running GHC may be found in the user guide. In general, Win95/Win98 behave the same, and WinNT/Win2k behave the same. -You should read the GHC installation guide sections on Windows (in the user -guide) before continuing to read these notes. + +Make sure you read the preceding section on platforms () +before reading section. +You don't need Cygwin or MSYS to use GHC, +but you do need one or the other to build GHC. -Before you start +Installing and configuring MSYS + +MSYS is a lightweight alternative to Cygwin. +You don't need MSYS to use GHC, +but you do need it or Cygwin to build GHC. +Here's how to install MSYS. + + +Go to http://www.mingw.org/download.shtml and +download the following (of course, the version numbers will differ): + The main MSYS package (binary is sufficient): MSYS-1.0.9.exe + + The MSYS developer's toolkit (binary is sufficient): msysDTK-1.0.1.exe. + This provides make, autoconf, + ssh, cvs and probably more besides. + + +Run both executables (in the order given above) to install them. I put them in c:/msys + + + +Set the following environment variables + + PATH: add c:/msys/1.0/bin to your path. (Of course, the version number may differ.) + + + HOME: set to your home directory (e.g. c:/userid). + This is where, among other things, ssh will look for your .ssh directory. + + + SHELL: set to c:/msys/1.0/bin/sh.exe + + + CVS_RSH: set to c:/msys/1.0/bin/ssh.exe. Only necessary if + you are using CVS. + + + MAKE_MODE: set to UNIX. (I'm not certain this is necessary for MSYS.) + + + + + + +Check that the CYGWIN environment variable is not set. It's a bad bug +that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it +causes the MSYS ssh to bogusly fail complaining that your .ssh/identity +file has too-liberal permissinos. + + + + +Here are some points to bear in mind when using MSYS: + + MSYS does some kind of special magic to binaries stored in +/bin and /usr/bin, which are by default both mapped +to c:/msys/1.0/bin (assuming you installed MSYS in c:/msys). +Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories: +they fail in mysterious ways. However, it's fine to put other binaries in /usr/local/bin, +which maps to c:/msys/1.0/local/bin. + + MSYS seems to implement symbolic links by copying, so sharing is lost. + + + +Win32 has a find command which is not the same as MSYS's find. +You will probably discover that the Win32 find appears in your PATH +before the MSYS one, because it's in the system PATH +environment variable, whereas you have probably modified the user PATH +variable. You can always invoke find with an absolute path, or rename it. + + + +MSYS comes with bzip, and MSYS's tar's -j +will bunzip an archive (e.g. tar xvjf foo.tar.bz2). Useful when you get a +bzip'd dump. + + + + + +Installing and configuring Cygwin + + 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 all of the following: + cvs, + openssh, + autoconf, + 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: + + + Add c:/cygwin/bin and c:/cygwin/usr/bin to your +PATH + -Make sure that the user environment variable -MAKE_MODE is set to UNIX. If you +Set MAKE_MODE to UNIX. If you don't do this you get very weird messages when you type make, such as: - -/c: /c: No such file or directory - +/c: /c: No such file or directory + + + + Set SHELL to +c:/cygwin/bin/bash. When you invoke a shell in Emacs, this +SHELL is what you get. + + + Set HOME to point to your +home directory. This is where, for example, +bash will look for your .bashrc +file. Ditto emacs looking for .emacsrc + + + + + +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 sh). Notice the hardwired path! +So you need to ensure that your /bin directory has the following +binaries in it: + + sh + perl + cat + +All these come in Cygwin's bin directory, which you probably have +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.) +Provided /bin points to the Cygwin bin +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). + + + + + +Finally, here are some things to be aware of when using Cygwin: + + Cygwin doesn't deal well with filenames that include +spaces. "Program Files" and "Local files" are +common gotchas. + + + Cygwin implements a symbolic link as a text file with some +magical text in it. So other programs that don't use Cygwin's +I/O libraries won't recognise such files as symlinks. +In particular, programs compiled by GHC are meant to be runnable +without having Cygwin, so they don't use the Cygwin library, so +they don't recognise symlinks. + + + +See the notes in about find and bzip, +which apply to Cygwin too. + + + + + + + +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 + + + (Cygwin-only problem, I think.) +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, listed below. + +On Windows you often install executables in directories with spaces, such as +"Program Files". However, the make system for fptools 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, +/usr/local/bin and /usr/local/lib. But it doesn't matter, +provided they are in your path. + + + +Install an executable GHC, from http://www.haskell.org/ghc. +This is what you will use to compile GHC. Add it in your +PATH: the installer tells you the path element +you need to add upon completion. + + + + + +Install an executable Happy, from http://www.haskell.org/happy. +Happy is a parser generator used to compile the Haskell grammar. Under MSYS or Cygwin you can easily +build it from the source distribution using +./configure +make +make install +This should install it in /usr/local/bin (which maps to c:/msys/1.0/local/bin +on MSYS). +Make sure the installation directory is in your +PATH. + + + + + Install Alex. This can be done by building from the + source distribution in the same way as Happy. Sources are + available from http://www.haskell.org/alex. + + + 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. +Do not add any of the mingw binaries to your path. +They are only going to get used by explicit access (via the --with-gcc flag you +give to configure later). If you do add them to your path +you are likely to get into a mess because their names overlap with Cygwin binaries. + + + + + +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 (). + + + + +Building GHC + +OK! +Now go read the documentation above on building from source (); +the bullets below only tell +you about Windows-specific wrinkles. + -Install a version of GHC, and put it in your -PATH (the installer tells you the path element -you need to add upon completion.) +If you used autoconf instead of autoreconf, +you'll get an error when you run ./configure: + +...lots of stuff... +creating mk/config.h +mk/config.h is unchanged +configuring in ghc +running /bin/sh ./configure --cache-file=.././config.cache --srcdir=. +./configure: ./configure: No such file or directory +configure: error: ./configure failed for ghc - - + + autoreconf seems to create the file configure +read-only. So if you need to run autoreconf again (which I sometimes do for safety's sake), +you get +/usr/bin/autoconf: cannot create configure: permission denied +Solution: delete configure first. + + + + + After autoreconf run ./configure in + fptools/ 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 +(see ). + + 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 () +you'll have to do something more like: +./configure --with-gcc=...the Cygwin gcc... + + + + +If you are paranoid, delete config.cache if it exists. +This file occasionally remembers out-of-date configuration information, which +can be really confusing. + + + + 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. + + + -
+