X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Finstalling.sgml;h=fdfb0782aaaae791573d73a73c52cce769b27b48;hb=3087014ae03067cf0f9c9e0d8d49fb885e2cd0a8;hp=0415c4d366402aceb65904ebe901c88180ff8b45;hpb=c7f8f1e62b555462f98c3f813440559116033a99;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/installing.sgml b/ghc/docs/users_guide/installing.sgml index 0415c4d..fdfb078 100644 --- a/ghc/docs/users_guide/installing.sgml +++ b/ghc/docs/users_guide/installing.sgml @@ -1,1979 +1,887 @@ - -
- -Building and Installing the Glasgow Functional Programming Tools Suite -Version 4.04 -<author>The GHC Team, -Department of Computing Science, -University of Glasgow, -Glasgow, Scotland, -G12 8QQ. - -Email: <tt>glasgow-haskell-{users,bugs}@dcs.gla.ac.uk</tt> -<date>April 1998</date> - -<abstract> - -This guide is intended for people who want to install or modify -programs from the Glasgow <tt>fptools</tt> suite (as distinct from those -who merely want to <em/run/ them). - -</abstract> - -<toc> - -<sect>Getting the Glasgow <tt>fptools</tt> suite -<label id="sec:getting"> -<p> - -Building the Glasgow tools <em/can/ be complicated, mostly because -there are so many permutations of what/why/how, e.g., ``Build Happy -with HBC, everything else with GHC, leave out profiling, and test it -all on the `real' NoFib programs.'' Yeeps! - -Happily, such complications don't apply to most people. A few common -``strategies'' serve most purposes. Pick one and proceed -as suggested: - -<descrip> - -<tag><idx>Binary distribution</idx>.</tag> - If your only purpose is to install some of the <tt>fptools</tt> suite -then the easiest thing to do is to get a binary distribution. In the -binary distribution everything is pre-compiled for your particular -machine architecture and operating system, so all you should have to -do is install the binaries and libraries in suitable places. Section -<ref id="sec:installing-bin-distrib" name="Installing a Binary -Distribution"> describes how to do this. - -A binary distribution may not work for you for two reasons. First, we -may not have built the suite for the particular architecture/OS -platform you want. That may be due to lack of time and energy (in -which case you can get a source distribution and build from it; see -below). Alternatively, it may be because we haven't yet ported the -suite to your architecture, in which case you are considerably worse -off. - -The second reason a binary distribution may not be what you want is -if you want to read or modify the souce code. - -<tag><idx>Source distribution</idx>.</tag> You have a supported -platform, but (a)~you like the warm fuzzy feeling of compiling things -yourself; (b)~you want to build something ``extra''---e.g., a set of -libraries with strictness-analysis turned off; or (c)~you want to hack -on GHC yourself. - -A source distribution contains complete sources for one or more -projects in the <tt>fptools</tt> suite. Not only that, but the more awkward -machine-independent steps are done for you. For example, if you don't -have <tt>flex</tt><ncdx/flex/ you'll find it convenient that the source -distribution contains the result of running <tt>flex</tt> on the lexical -analyser specification. If you don't want to alter the lexical -analyser then this saves you having to find and install <tt>flex</tt>. You -will still need a working version of GHC on your machine in order to -compile (most of) the sources, however. - -We make source distributions more frequently than binary -distributions; a release that comes with pre-compiled binaries -is considered a major release, i.e., a release that we have some -confidence will work well by having tested it (more) thoroughly. - -Source-only distributions are either bugfix releases or snapshots of -current state of development. The release has undergone some testing. -Source releases of 4.xx can be compiled up using 2.10 or later. - -<tag/Build GHC from intermediate C <tt>.hc</tt> files<nidx/hc files/:/ You -need a working GHC to use a source distribution. What if you don't -have a working GHC? Then you have no choice but to ``bootstrap'' up -from the intermediate C (<tt>.hc</tt>) files that we provide. Building GHC -on an unsupported platform falls into this category. Please see -Section <ref id="sec:booting-from-C" name="Booting From C">. - -Once you have built GHC, you can build the other Glasgow tools with -it. - -In theory, you can (could?) build GHC with another Haskell compiler -(e.g., HBC). We haven't tried to do this for ages and it almost -certainly doesn't work any more (for tedious reasons). - -<tag/The CVS repository./ - -We make source distributions slightly more often than binary -distributions; but still infrequently. If you want more up-to-the -minute (but less tested) source code then you need to get access to -our CVS repository. - -All the <tt>fptools</tt> source code is held in a CVS repository. CVS is a -pretty good source-code control system, and best of all it works over -the network. - -The repository holds source code only. It holds no mechanically -generated files at all. So if you check out a source tree from CVS -you will need to install every utility so that you can build all the -derived files from scratch. - -More information about our CVS repository is available at <url -name="The Fptools CVS Cheat Sheet" -url="http://www.dcs.gla.ac.uk/fp/software/ghc/cvs-cheat-sheet.html">. -</descrip> - -If you are going to do any building from sources (either from a source -distribution or the CVS repository) then you need to read all of this -manual in detail. - -<sect>Things to check before you start typing -<p> - -Here's a list of things to check before you get started. -<enum> -<item> -<idx>Disk space needed</idx>: About 30MB (five hamburgers' worth) of disk space -for the most basic binary distribution of GHC; more for some -platforms, e.g., Alphas. An extra ``bundle'' (e.g., concurrent -Haskell libraries) might take you to 8--10 hamburgers. - -You'll need over 100MB (say, 20 hamburgers' worth) if you need to -build the basic stuff from scratch. - - -All of the above are <em/estimates/ of disk-space needs.(I don't yet -know the disk requirements for the non-GHC tools). - -<item> -Use an appropriate machine, compilers, and things. - -SPARC boxes, DEC Alphas running OSF/1, and PCs running Linux, FreeBSD, -or Solaris are all fully supported. MIPS, AIX, Win32 and HP boxes are -in pretty good shape. Section <ref id="sec:port-info" name="Port Info"> -gives the full run-down on ports or lack thereof. - -NOTE: as of version 4.00, we lost a few ports. All of the x86 ports -are working, as is the Sparc/Solaris port, but the rest will need a -little work. Please contact us if you can provide hardware cycles -and/or porting expertise. - -<item> Be sure that the ``pre-supposed'' utilities are installed. -Section <ref id="sec:pre-supposed" name="Installing Pre-Supposed -Utilities"> elaborates. - -<item> If you have any problem when building or installing the Glasgow -tools, please check the ``known pitfalls'' (Section <ref -id="sec:build-pitfalls" name="Building Pitfalls">). Also check the -known bugs page: <url -url="http://www.dcs.gla.ac.uk/fp/software/ghc/ghc-bugs.html">. -<nidx/known bugs/ -<nidx/bugs, known/ - -If you feel there is still some shortcoming in our procedure or -instructions, please report it. - -For GHC, please see the bug-reporting section of the User's guide -(separate document), to maximise the usefulness of your report. -<nidx/bugs, reporting/ - -If in doubt, please send a message to <tt>glasgow-haskell-bugs@dcs.gla.ac.uk</tt>. -<nidx/bugs, mailing list/ -</enum> - - -<sect>What machines the Glasgow tools run on -<label id="sec:port-info"> -<p> -<nidx>ports, GHC</nidx> -<nidx>GHC ports</nidx> -<nidx>supported platforms</nidx> -<nidx>platforms, supported</nidx> - -The main question is whether or not the Haskell compiler (GHC) runs on -your platform. - -A ``platform'' is a architecture/manufacturer/operating-system -combination, such as <tt>sparc-sun-solaris2</tt>. Other common ones are -<tt>alpha-dec-osf2</tt>, <tt>hppa1.1-hp-hpux9</tt>, <tt>i386-unknown-linux</tt>, -<tt>i386-unknown-solaris2</tt>, <tt>i386-unknown-freebsd</tt>, -<tt>i386-unknown-cygwin32</tt>, <tt>m68k-sun-sunos4</tt>, <tt>mips-sgi-irix5</tt>, -<tt>sparc-sun-sunos4</tt>, <tt>sparc-sun-solaris2</tt>, <tt>powerpc-ibm-aix</tt>. - -Bear in mind that certain ``bundles'', e.g. parallel Haskell, may not -work on all machines for which basic Haskell compiling is supported. - -Some libraries may only work on a limited number of platforms; for -example, a sockets library is of no use unless the operating system -supports the underlying BSDisms. - -<sect1>What platforms the Haskell compiler (GHC) runs on -<p> -<nidx>fully-supported platforms</nidx> -<nidx>native-code generator</nidx> -<nidx>registerised ports</nidx> -<nidx>unregisterised ports</nidx> - -The GHC hierarchy of Porting Goodness: (a)~Best is a native-code -generator; (b)~next best is a ``registerised'' -port; (c)~the bare minimum is an ``unregisterised'' port. -(``Unregisterised'' is so terrible that we won't say more about it). - -We use Sparcs running Solaris 2.5, x86 boxes running FreeBSD and -Linux, and DEC~Alphas running OSF/1~V2.0, so those are the -``fully-supported'' platforms, unsurprisingly. All have native-code -generators, for quicker compilations. The native-code generator for -iX86 platforms (e.g., Linux ELF) is <em/nearly/ working; but is not -turned on by default. - -Here's everything that's known about GHC ports. We identify platforms -by their ``canonical'' CPU/Manufacturer/OS triple. - -Note that some ports are fussy about which GCC version you use; or -require GAS; or… - -<descrip> -<tag/alpha-dec-osf1:/ -<nidx>alpha-dec-osf1: fully supported</nidx> - -(We have OSF/1 V3.0.) Fully supported, including native-code -generator. We recommend GCC 2.6.x or later. - -<tag/sparc-sun-sunos4:/ -<nidx>sparc-sun-sunos4: fully supported</nidx> - -Fully supported, including native-code generator. - -<tag/sparc-sun-solaris2:/ -<nidx>sparc-sun-solaris2: fully supported</nidx> - -Fully supported, including native-code generator. A couple of quirks, -though: (a)~the profiling libraries are bizarrely huge when compiled -with object splitting; (b)~the default <tt>xargs</tt><ncdx/xargs/ program is -atrociously bad for building GHC libraries (see Section <ref -id="sec:pre-supposed" name="Installing Pre-Supposed Utilities"> for -details). - -<tag/HP-PA box running HP/UX 9.x:/ -<nidx>hppa1.1-hp-hpux: registerised port</nidx> - -Works registerised. No native-code generator. For GCC, you're best -off with one of the Utah releases of GCC~2.6.3 (`u3' or later), from -<tt>jaguar.cs.utah.edu</tt>. We think a straight GCC 2.7.x works, -too. - -Concurrent/Parallel Haskell probably don't work (yet). -<nidx>hppa1.1-hp-hpux: concurrent---no</nidx> -<nidx>hppa1.1-hp-hpux: parallel---no</nidx> - -<tag/i386-*-linux (PCs running Linux---ELF format):/ -<nidx>i386-*-linux: registerised port</nidx> - -GHC works registerised. You <em/must/ have GCC 2.7.x or later. The -iX86 native-code generator is <em/nearly/ there, but it isn't turned -on by default. - -Profiling works, and Concurrent Haskell works. -<nidx>i386-*-linux: profiling---yes</nidx> -<nidx>i386-*-linux: concurrent---yes</nidx> -Parallel Haskell probably works. -<nidx>i386-*-linux: parallel---maybe</nidx> - -On old Linux a.out systems: should be the same. -<nidx>i386-*-linuxaout: registerised port</nidx> - -<tag>i386-*-freebsd (PCs running FreeBSD 2.2 or higher, and -NetBSD/OpenBSD using FreeBSD emulation):</tag> -<nidx>i386-*-freebsd:registerised port</nidx> - -GHC works registerised. Supports same set of bundles as the above. - -<nidx>i386-*-freebsd: profiling---yes</nidx> -<nidx>i386-*-freebsd: concurrent---yes</nidx> -<nidx>i386-*-freebsd: parallel---maybe</nidx> - -<tag/i386-unknown-cygwin32:/ -<nidx>i386-unknown-cygwin32: fully supported</nidx> - -Fully supported under Win95/NT, including a native code -generator. Requires the <tt>cygwin32</tt> compatibility library and a -healthy collection of GNU tools (i.e., gcc, GNU ld, bash etc.) -Profiling works, so does Concurrent Haskell. - -<nidx>i386-*-cygwin32: profiling---yes</nidx> -<nidx>i386-*-cygwin32: concurrent---yes</nidx> - -<tag/mips-sgi-irix5:/ -<nidx>mips-sgi-irix5: registerised port</nidx> - -GHC works registerised (no native-code generator). I suspect any -GCC~2.6.x (or later) is OK. The GCC that I used was built with -<tt>--with-gnu-as</tt>; turns out that is important! - -Concurrent/Parallel Haskell probably don't work (yet). -Profiling might work, but it is untested. -<nidx>mips-sgi-irix5: concurrent---no</nidx> -<nidx>mips-sgi-irix5: parallel---no</nidx> -<nidx>mips-sgi-irix5: profiling---maybe</nidx> - -<tag/mips-sgi-irix6:/ -<nidx>mips-sgi-irix6: registerised port</nidx> - -Thanks to the fine efforts of Tomasz Cholewo <htmlurl -url="mailto:tjchol01@mecca.spd.louisville.edu" -name="tjchol01@mecca.spd.louisville.edu">, GHC works registerised (no -native code generator) under IRIX 6.2 and 6.3. Depends on having -specially tweaked version of gcc-2.7.2 around, which can be downloaded -from <url url="http://mecca.spd.louisville.edu/~tjchol01/software/">. - -Profiling works, Concurrent/Parallel Haskell might work (AFAIK, untested). -<nidx>mips-sgi-irix6: concurrent---maybe</nidx> -<nidx>mips-sgi-irix6: parallel---maybe</nidx> -<nidx>mips-sgi-irix6: profiling---yes</nidx> - -<tag/powerpc-ibm-aix:/ -<nidx>powerpc-ibm-aix: registerised port</nidx> -GHC works registerised (no native-code generator..yet). -I suspect 2.7.x is what you need together with this. - -Concurrent/Parallel Haskell probably don't work (yet). -Profiling might work, but it is untested. -<nidx>mips-sgi-irix5: concurrent---no</nidx> -<nidx>mips-sgi-irix5: parallel---no</nidx> -<nidx>mips-sgi-irix5: profiling---maybe</nidx> - -<tag/m68k-apple-macos7 (Mac, using MPW):/ -<nidx>m68k-apple-macos7: historically ported</nidx> -Once upon a time, David Wright in Tasmania has actually -gotten GHC to run on a Macintosh. Ditto James Thomson here at Glasgow. -You may be able to get Thomson's from here. (Not sure that it will -excite you to death, but…) - -No particularly recent GHC is known to work on a Mac. - -<tag/m68k-next-nextstep3:/ -<nidx>m68k-next-nextstep3: historically ported</nidx> -Carsten Schultz succeeded with a ``registerised'' port of GHC~0.29. -There's probably a little bit-rot since then, but otherwise it should -still be fine. - -Concurrent/Parallel Haskell probably won't work (yet). -<nidx>m68k-next-nextstep3: concurrent---no</nidx> -<nidx>m68k-next-nextstep3: parallel---no</nidx> - -<tag/m68k-sun-sunos4 (Sun3):/ <nidx>m68k-sun-sunos4: registerised -port</nidx> GHC 2.0x and 3.0x haven't been tried on a Sun3. GHC~0.26 -worked registerised. No native-code generator. - -Concurrent/Parallel Haskell probably don't work (yet). -<nidx>m68k-sun-sunos4: concurrent---no</nidx> -<nidx>m68k-sun-sunos4: parallel---no</nidx> -</descrip> - -<sect1>What machines the other tools run on -<p> - -Unless you hear otherwise, the other tools work if GHC works. - -Haggis requires Concurrent Haskell to work. -<nidx>Haggis, Concurrent Haskell</nidx> - - -<sect>Installing from binary distributions -<p> -<label id="sec:installing-bin-distrib"> -<nidx>binary installations</nidx> -<nidx>installation, of binaries</nidx> +<Chapter id="sec-installing-bin-distrib"> + <Title>Installing GHC +binary installations +installation, of binaries + Installing from binary distributions is easiest, and recommended! -(Why binaries? Because GHC is a Haskell compiler written in Haskell, -so you've got to ``bootstrap'' it, somehow. We provide -machine-generated C-files-from-Haskell for this purpose, but it's -really quite a pain to use them. If you must build GHC from its -sources, using a binary-distributed GHC to do so is a sensible way to -proceed. For the other fptools programs, many are written in Haskell, -so binary distributions allow you to install them without having a Haskell compiler.) - - -Bundle structure

-bundles of binary stuff - -Binary distributions come in ``bundles,'' one bundle per file called -<bundle>-<platform>.tar.gz. (See Section for what a platform -is.) Suppose that you untar a binary-distribution bundle, thus: - - - % cd /your/scratch/space - % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf - - - -Then you should find a single directory, fptools, with the following -structure: - -binary distribution, layout -directory layout (binary distributions) - - -Makefile.in the raw material from which the Makefile -will be made (Section ). - -configure the configuration script (Section ). - -README Contains this file summary. - -INSTALL Contains this description of how to install +(Why binaries? Because GHC is a Haskell compiler written in Haskell, +so you've got to bootstrap it somehow. We provide machine-generated +C-files-from-Haskell for this purpose, but it's really quite a pain to +use them. If you must build GHC from its sources, using a +binary-distributed GHC to do so is a sensible way to proceed. For the +other fptools programs, many are written in +Haskell, so binary distributions allow you to install them without +having a Haskell compiler.) + + +This guide is in several parts: + + + + Installing on Unix-a-likes (). + + + Installing on Windows (). + + + The layout of installed files (). You don't need to know this to + install GHC, but it's useful if you are changing the + implementation. + + + + Installing on Unix-a-likes + + + When a platform-specific package is available + + For certain platforms, we provide GHC binaries packaged + using the native package format for the platform. This is + likely to be by far the best way to install GHC for your + platform if one of these packages is available, since + dependencies will automatically be handled and the package + system normally provides a way to uninstall the package at a + later date. + + We generally provide the following packages: + + + + RedHat or SuSE Linux/x86 + + RPM source & binary packages for RedHat and SuSE + Linux (x86 only) are available for most major + releases. + + + + + Debian Linux/x86 + + Debian packages for Linux (x86 only), also for most + major releases. + + + + + FreeBSD/x86 + + On FreeBSD/x86, GHC can be installed using either + the ports tree (cd /usr/ports/lang/ghc && make + install) or from a pre-compiled package + available from your local FreeBSD mirror. + + + + + Other platform-specific packages may be available, check + the GHC download page for details. + + + +GHC binary distributions + + +bundles of binary stuff + + + +Binary distributions come in “bundles,” one bundle per file called +bundle-platform.tar.gz. (See the building guide for the definition of a platform.) Suppose that you untar a binary-distribution bundle, thus: + + + + + +% cd /your/scratch/space +% gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf - + + + + +Then you should find a single directory, +ghc-version, with the +following structure: + + + +binary distribution, layout +directory layout (binary distributions) + + + +Makefile.in + + +the raw material from which the Makefile +will be made (). + + + +configure + + +the configuration script (). + + + +README + + +Contains this file summary. + + + +INSTALL + + +Contains this description of how to install the bundle. - -ANNOUNCE The announcement message for the bundle. - -NEWS release notes for the bundle -- a longer version -of ANNOUNCE. For GHC, the release notes are contained in the User + + + +ANNOUNCE + + +The announcement message for the bundle. + + + +NEWS + + +release notes for the bundle—a longer version +of ANNOUNCE. For GHC, the release notes are contained in the User Guide and this file isn't present. - -bin/<platform> contains platform-specific executable + + + + bin/platform + + +contains platform-specific executable files to be invoked directly by the user. These are the files that must end up in your path. - -lib/<platform>/ contains platform-specific support + + + +lib/platform/ + + +contains platform-specific support files for the installation. Typically there is a subdirectory for -each fptools project, whose name is the name of the project with its +each fptools project, whose name is the name of the project with its version number. For example, for GHC there would be a sub-directory -ghc-x.xx/ where x.xx is the version number of GHC in the bundle. +ghc-x.xx/ where x.xx is the version number of GHC in the bundle. + + These sub-directories have the following general structure: - - -libHS.a etc: supporting library archives. -ghc-iface.prl etc: support scripts. -import/ Interface files (.hi) for the prelude. -include/ A few C #include files. - - -share/ contains platform-independent support files + + + + + + +libHSstd.a etc: + + +supporting library archives. + + + +ghc-iface.prl etc: + + +support scripts. + + + +import/ + + +Interface files (.hi) for the prelude. + + + +include/ + + +A few C #include files. + + + + + + +share/ + + +contains platform-independent support files for the installation. Again, there is a sub-directory for each -fptools project. - -info/ contains Emacs info documentation files (one -sub-directory per project). - -html/ contains HTML documentation files (one +fptools project. + + + +html/ + + +contains HTML documentation files (one sub-directory per project). - -man/ contains Unix manual pages. - - - -This structure is designed so that you can unpack multiple bundles -(including ones from different releases or platforms) into a single -fptools directorythis doesn't work at the -moment: - - - % cd /your/scratch/space - % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf - - % gunzip < happy-x.xx-sun-sparc-sunos4.tar.gz | tar xvf - - - -When you do multiple unpacks like this, the top level Makefile, -README, and INSTALL get overwritten each time. -That's fine -- they should be the same. Likewise, the -ANNOUNCE-<bundle> and NEWS-<bundle> -files will be duplicated across multiple platforms, so they will be -harmlessly overwritten when you do multiple unpacks. Finally, the -share/ stuff will get harmlessly overwritten when you do -multiple unpacks for one bundle on different platforms. - -Installing

-

- -ghc-x.xx-<bundle>-<platform>.tar.gz, where -the <platform> is as above, and <bundle> is one -of these: - - - -prof: Profiling with cost-centres. You probably want this. -conc: Concurrent Haskell features. You may want this. -par: Parallel Haskell features (sits on top of PVM). +regardless, ghc-x.xx should always invoke GHC version x.xx. + + + + + + +What bundles there are + + +bundles, binary There are +plenty of “non-basic” GHC bundles. The files for them are +called +ghc-x.xx-bundle-platform.tar.gz, +where the platform is as above, and +bundle is one of these: + + + + + + +prof: + + +Profiling with cost-centres. You probably want this. +profiling bundles +bundles, profiling + + + +par: + + +Parallel Haskell features (sits on top of PVM). You'll want this if you're into that kind of thing. -gran: The ``GranSim'' parallel-Haskell simulator +parallel bundles +bundles, parallel + + + +gran: + + +The “GranSim” parallel-Haskell simulator (hmm… mainly for implementors). -ticky: ``Ticky-ticky'' profiling; very detailed -information about ``what happened when I ran this program''---really +bundles, gransim +gransim bundles + + + +ticky: + + +“Ticky-ticky” profiling; very detailed +information about “what happened when I ran this program”—really for implementors. -prof-conc: Cost-centre profiling for Concurrent Haskell. -prof-ticky: Ticky-ticky profiling for Concurrent Haskell. - - -One likely scenario is that you will grab bundles, ticky-ticky +ticky-ticky bundles + + + + + + +One likely scenario is that you will grab two +binary bundles—basic, and profiling. We don't usually make the rest, although you can build them yourself from a source distribution. + -Testing that GHC seems to be working -

-testing a new GHC +The various GHC bundles are designed to be unpacked into the +same directory; then installing as per the directions above will +install the whole lot in one go. Note: you must +at least have the basic GHC binary distribution bundle, these extra +bundles won't install on their own. -The way to do this is, of course, to compile and run Main.hs): - - -main = putStr "Hello, world!\n" - + -Compile the program, using the -v (verbose) flag to verify that -libraries, etc., are being found properly: - -% ghc -v -o hello Main.hs - + +Testing that GHC seems to be working + -Now run it: - -% ./hello -Hello, world! - + +testing a new GHC + -Some simple-but-profitable tests are to compile and run the notorious -nfibnfib :: Int -> Int, and then try Integer, Float, Double, -Rational and perhaps the overloaded version. Code for this is -distributed in ghc/misc/examples/nfib/ in a source distribution. - -For more information on how to ``drive'' GHC, either do ghc -help or -consult the User's Guide (distributed in several pre-compiled formats -with a binary distribution, or in source form in -ghc/docs/users_guide in a source distribution). - -Installing pre-supposed utilities -

- -Here are the gory details about some utility programs you may need; -perl and gcc are the only important ones. ( -script will tell you if you are missing something. - - -Perl: -pre-supposed: Perl -Perl, pre-supposed -cygwin32, as the common Hip/ActiveWare port -of Perl is not Cool Enough for our purposes. - -Perl should be put somewhere so that it can be invoked by the #! -script-invoking mechanism. (I believe /usr/bin/perl is preferred; -we use /usr/local/bin/perl at Glasgow.) The full pathname should -be less than 32 characters long. - -GNU C (gcc): -pre-supposed: GCC (GNU C compiler) -GCC (GNU C compiler), pre-supposed - -Versions 2.7.2.x, 2.8.1 and egcs 1.1.2 are known to work. Use other -versions at your own risk! - -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 boxes---you may need to fiddle with GHC's --monly-N-regs option; see the User's Guide) - -xargs on Solaris2: -xargs, presupposed (Solaris only) -Solaris: alternative xargs -The GHC libraries are put together with something like: - -find bunch-of-dirs -name '*.o' -print | xargs ar q ... - -Unfortunately the Solaris xargs (the shell-script equivalent -of map) only ``bites off'' the .o files a few at a -time---with near-infinite rebuilding of the symbol table in -the .a file. - -The best solution is to install a sane xargs from the GNU -findutils distribution. You can unpack, build, and install the GNU -version in the time the Solaris xargs mangles just one GHC -library. - -Autoconf: -pre-supposed: Autoconf -Autoconf, pre-supposed - -GNU Autoconf is needed if you intend to build from the CVS sources, it -is configure script from configure.in and -aclocal.m4. If you modify either of these files, you'll need -Autoconf to rebuild configure. - -sed -pre-supposed: sed -sed, pre-supposed - -You need a working sed if you are going to build from sources. The -build-configuration stuff needs it. GNU sed version 2.0.4 is no good! -It has a bug in it that is tickled by the build-configuration. 2.0.5 -is ok. Others are probably ok too (assuming we don't create too -elaborate configure scripts..) - - -One fptools project is worth a quick note at this point, because it -is useful for all the others: glafp-utils contains several utilities -which aren't particularly Glasgow-ish, but Occasionally Indispensable. -Like lndir for creating symbolic link trees. - - Tools for building parallel GHC (GPH) -

- - -PVM version 3: -pre-supposed: PVM3 (Parallel Virtual Machine) -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 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 (faster). - -The current version of PVM is 3.3.11; we use 3.3.7. It is readily -available on the net; I think I got it from research.att.com, in -netlib. - -A PVM installation is slightly quirky, but easy to do. Just follow -the Readme instructions. - -bash: -bash, presupposed (Parallel Haskell only) -Sadly, the gr2ps script, used to convert ``parallelism profiles'' -to PostScript, is written in Bash (GNU's Bourne Again shell). -This bug will be fixed (someday). - - - Tools for building the Documentation -

- -The following additional tools are required if you want to format the -documentation that comes with the fptools projects: - - -SGML-Tools: -pre-supposed: SGML-Tools -SGML-Tools, pre-supposed - -All our documentation is written in SGML, using the LinuxDoc DTD that -comes with the SGML-Tools, which is the most shrink-wrapped SGML suite -that we could find. Should unpack and build painlessly on most -architectures, and you can use it to generate HTML, Info, LaTeX (and -hence DVI and Postscript), Groff, and plain text output from any -LinuxDoc source file (including this manual). Sources are available -from - -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. - - - Other useful tools -

- - -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 glafp-utils. Depending on your operating system, -the supplied lex may or may not work; you should get the GNU -version. - - -Building from source -

- -You've been rash enough to want to build some of -the Glasgow Functional Programming tools (GHC, Happy, -nofib, etc) from source. You've slurped the source, -from the CVS repository or from a source distribution, and -now you're sitting looking at a huge mound of bits, wondering -what to do next. - -Gingerly, you type make. Wrong already! - -This rest of this guide is intended for duffers like me, who aren't -really interested in Makefiles and systems configurations, but who -need a mental model of the interlocking pieces so that they can make -them work, extend them consistently when adding new software, and lay -hands on them gently when they don't work. - -Your source tree -

- -The source code is held in your - Makefile: the root Makefile. - mk/: the directory that contains the -main Makefile code, shared by all the -fptools software. - configure.in, config.sub, config.guess: -these files support the configuration process. - install-sh. - - -All the other directories are individual fptools system --- for example, the Glasgow Haskell Compiler -(ghc), the Happy parser generator (happy), the nofib benchmark -suite, and so on. You can have zero or more of these. Needless to -say, some of them are needed to build others. - -The important thing to remember is that even if you want 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 (happy/ in this case). You cannot get by with -just the happy/ directory. - -Build trees - - -While you can build a system in the source tree, we don't recommend it. -We often want to build multiple versions of our software -for different architectures, or with different options (e.g. profiling). -It's very desirable to share a single copy of the source code among -all these builds. - -So for every source tree we have zero or more lndirmkshadowdirX11 lndir --- check out fptools/glafp-utils/lndir ). - -The build tree does not need to be anywhere near the source tree in -the file system. Indeed, one advantage of separating the build tree -from the source is that the build tree 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 -- Section~ Foo.o, as well.) You -can fptools suite. Inside -Makefiles, the root of your build tree is called -$(FPTOOLS_TOP)$(FPTOOLS_TOP) unless otherwise stated. For -example, the file ghc/mk/target.mk is actually -$(FPTOOLS_TOP)/ghc/mk/target.mk. - - -Getting the build you want -

- -When you build fptools you will be compiling code on a particular -platform. The -difficulty is that there are minor differences between different -platforms; minor, but enough that the code needs to be a bit different -for each. There are some big differences too: for a different -architecture we need to build GHC with a different native-code -generator. - -There are also knobs you can turn to control how the fptools -software is built. For example, you might want to build GHC optimised -(so that it runs fast) or unoptimised (so that you can compile it fast -after you've modified it. Or, you might want to compile it with -debugging on (so that extra consistency-checking code gets included) -or off. And so on. - -All of this stuff is called the - -Step 1: get ready for configuration. Change directory to -$(FPTOOLS_TOP) and issue the command autoconf$(FPTOOLS_TOP)/configure.in -to a shell script called $(FPTOOLS_TOP)/configure. - -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. - -Step 2: system configuration. -Runs the newly-created configure script, thus: - - ./configure - -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 gcc is available, -where various obscure #include files are, whether it's a leap year, -and what the systems manager had for lunch. It communicates these -snippets of information in two ways: - - - - It translates mk/config.mk.inmk/config.mkYES'' or ``NO'' depending on what configure finds. -mk/config.mk is included by every Makefile (directly or indirectly), -so the configuration information is thereby communicated to all -Makefiles. - - It translates mk/config.h.inmk/config.h#included by various C -programs, which can thereby make use of configuration information. - - - -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. - -Step 3: build configuration. - - Next, you say how this build of fptools is to differ from the -standard defaults by creating a new file mk/build.mkbuild.mk files, and use a -symbolic link in each build tree to point to the appropriate one.) So -mk/build.mk never exists in the source tree --- you create one in -each build tree from the template. We'll discuss what to put in it -shortly. - - - -And that's it for configuration. Simple, eh? - -What do you put in your build-specific configuration file -mk/build.mk? mk/config.mk.in. -The whole point of mk/config.mk.in --- and its derived counterpart -mk/config.mk --- is to define the build configuration. It is heavily -commented, as you will see if you look at it. So generally, what you -do is look at mk/config.mk.in, and add definitions in mk/build.mk -that override any of the config.mk definitions that you want to -change. (The override occurs because the main boilerplate file, -mk/boilerplate.mkbuild.mk after -config.mk.) - -For example, config.mk.in contains the definition: - - - ProjectsToBuild = glafp-utils ghc - - -The accompanying comment explains that this is the list of enabled -projects; that is, if (after configuring) you type gmake all in -FPTOOLS_TOP four specified projects will be made. If you want to -add green-card, you can add this line to build.mk: - - - ProjectsToBuild += green-card - - -or, if you prefer, - - - ProjectsToBuild = glafp-utils ghc green-card - - -(GNU make allows existing definitions to have new text appended -using the ``+='' operator, which is quite a convenient feature.) - -When reading config.mk.in, remember that anything between -``@...@'' signs is going to be substituted by configure -later. You - YACC = @YaccCmd@ - - -This defines the Make variables YACC to the pathname for a Yacc that -configure finds somewhere. If you have your own pet Yacc you want -to use instead, that's fine. Just add this line to mk/build.mk: - - - YACC = myyacc - - -You do not mk/build.mk file at all; if you -don't, you'll get all the default settings from mk/config.mk.in. - -You can also use build.mk to override anything that configure got -wrong. One place where this happens often is with the definition of -FPTOOLS_TOP_ABS: this variable is supposed to be the canonical path -to the top of your source tree, but if your system uses an automounter -then the correct directory is hard to find automatically. If you find -that configure has got it wrong, just put the correct definition in -build.mk. - -The story so far -

- -Let's summarise the steps you need to carry to get yourself -a fully-configured build tree from scratch. - - - - Get your source tree from somewhere (CVS repository 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 Section~). - - Use lndir or mkshadowdir to create a build tree. - - cd myfptools - mkshadowdir . /scratch/joe-bloggs/myfptools-sun4 - -You probably want to give the build tree a name that -suggests its main defining characteristic (in your mind at least), -in case you later add others. - - Change directory to the build tree. Everything is going -to happen there now. - - cd /scratch/joe-bloggs/myfptools-sun4 - - Prepare for system configuration: - - autoconf - -(You can skip this step if you are starting from a source distribution, -and you already have configure and mk/config.h.in.) - - Do system configuration: - - ./configure - - - Create the file mk/build.mk, -adding definitions for your desired configuration options. - - emacs mk/build.mk - - -You can make subsequent changes to mk/build.mk as often -as you like. You do not have to run any further configuration -programs to make these changes take effect. -In theory you should, however, say gmake clean, gmake all, -because configuration option changes could affect anything --- but in practice you are likely to know what's affected. - -Making things -

- -At this point you have made yourself a fully-configured build tree, -so you are ready to start building real things. - -The first thing you need to know is that -make, usually called gmake, not standard Unix make/. -If you use standard Unix make you will get all sorts of error messages -(but no damage) because the fptools Makefiles use GNU make's facilities -extensively. - -Standard Targets -

- -To get started, let us look at the Makefile for an imaginary small -fptools project, small. Each project in fptools has its own -directory in FPTOOLS_TOP, so the small project will have its own -directory FPOOLS_TOP/small/. Inside the small/ directory there -will be a Makefile, looking something like this: - - - # Makefile for fptools project "small" - - TOP = .. - include $(TOP)/mk/boilerplate.mk - - SRCS = $(wildcard *.lhs) $(wildcard *.c) - HS_PROG = small - - include $(TOP)/target.mk - - -This Makefile has three sections: - - - - The first section includesOne of the most important -features of GNU make that we use is the ability for a Makefile to -include another named file, very like cpp's #include -directive. a file of ``boilerplate'' code from the level -above (which in this case will be -FPTOOLS_TOP/mk/boilerplate.mkboilerplate.mk consists of a large quantity of standard -Makefile code. We discuss this boilerplate in more detail in -Section~. -include statement, you must define the make variable -TOPmk directory in -which the boilerplate.mk file is. It is - include ../mk/boilerplate.mk # NO NO NO - - -Why? Because the boilerplate.mk file needs to know where it is, so -that it can, in turn, include other files. (Unfortunately, when an -included file does an include, the filename is treated relative to -the directory in which gmake is being run, not the directory in -which the included sits.) In general, every file foo.mk -assumes that $(TOP)/mk/foo.mk refers to itself. It is up to the -Makefile doing the include to ensure this is the case. - -Files intended for inclusion in other Makefiles are written to have -the following property: foo.mk is included, it leaves -TOP containing the same value as it had just before the include -statement/. In our example, this invariant guarantees that the -include for target.mk will look in the same directory as that for -boilerplate.mk. - - The second section defines the following standard make -variables: SRCSHS_PROG. - -The definition for SRCS uses the useful GNU make construct -$(wildcard~$pat$)pat in the current directory. In -this example, SRCS is set to the list of all the .lhs and .c -files in the directory. (Let's suppose there is one of each, -Foo.lhs and Baz.c.) - - The last section includes a second file of standard code, -called target.mkgmake how to make the standard targets (Section~). Why, you ask, -can't this standard code be part of boilerplate.mk? Good question. -We discuss the reason later, in Section~. - -You do not include the target.mk file. Instead, you -can write rules of your own for all the standard targets. Usually, -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 (Section~. - - - -In our example Makefile, most of the work is done by the two -included files. When you say gmake all, the following things -happen: - - - - gmake figures out that the object files are Foo.o and -Baz.o. - - It uses a boilerplate pattern rule to compile Foo.lhs to -Foo.o using a Haskell compiler. (Which one? That is set in the -build configuration.) - - It uses another standard pattern rule to compile Baz.c to -Baz.o, using a C compiler. (Ditto.) - - It links the resulting .o files together to make small, -using the Haskell compiler to do the link step. (Why not use ld? -Because the Haskell compiler knows what standard librarise to link in. -How did gmake know to use the Haskell compiler to do the link, -rather than the C compiler? Because we set the variable HS_PROG -rather than C_PROG.) - - - -All Makefiles should follow the above three-section format. - -A larger project -

- -Larger projects are usually structured into a nummber of sub-directories, -each of which has its own Makefile. (In very large projects, this -sub-structure might be iterated recursively, though that is rare.) -To give you the idea, here's part of the directory structure for -the (rather large) ghc project: - - - $(FPTOOLS_TOP)/ghc/ - Makefile - - mk/ - boilerplate.mk - rules.mk - - docs/ - Makefile - ...source files for documentation... - - driver/ - Makefile - ...source files for driver... - - compiler/ - Makefile - parser/...source files for parser... - renamer/...source files for renamer... - ...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. It does most -of its work by recursively invoking gmake on the Makefiles in the -sub-directories. We say that ghc/Makefile is a Makefile/, because it does little except organise its children, -while the Makefiles in the sub-directories are all Makefiles/. (In principle the sub-directories might themselves -contain a non-leaf Makefile and several sub-sub-directories, but -that does not happen in ghc.) - -The Makefile in ghc/compiler is considered a leaf Makefile even -though the ghc/compiler has sub-directories, because these sub-directories -do not themselves have Makefiles in them. They are just used to structure -the collection of modules that make up ghc, but all are managed by the -single Makefile in ghc/compiler. - -You will notice that ghc/ also contains a directory ghc/mk/. It -contains ghc-specific Makefile boilerplate code. More precisely: - - - - ghc/mk/boilerplate.mk is included at the top of -ghc/Makefile, and of all the leaf Makefiles in the -sub-directories. It in turn includes the main boilerplate file -mk/boilerplate.mk. - - - ghc/mk/target.mk is included at the bottom of -ghc/Makefile, and of all the leaf Makefiles in the -sub-directories. It in turn includes the file mk/target.mk. - - - -So these two files are the place to look for ghc-wide customisation -of the standard boilerplate. - -Boilerplate architecture - -

- -Every Makefile includes a boilerplate.mktarget.mk - - boilerplate.mk consists of: - - make variables/ that -collectively specify the build configuration. Examples: -, the options to feed to the Haskell compiler; -, the sub-directories to enable within the -nofib project; , the name of the Haskell -compiler to use when compiling GHC in the ghc project. -gmake how to construct one -file from another. - - -boilerplate.mk needs to be included at the Makefile, so that the user can replace the -boilerplate definitions or pattern rules by simply giving a new -definition or pattern rule in the Makefile. gmake -simply takes the last definition as the definitive one. - -Instead of Makefile might say: - - - SRC_HC_OPTS += -O - - -thereby adding ``-O'' to the end of . - - target.mk contains make rules for the standard -targets described in Section~. These rules are selectively included, -depending on the setting of certain make variables. These -variables are usually set in the middle section of the -Makefile between the two includes. - -target.mk must be included at the end (rather than being part of -boilerplate.mk) for several tiresome reasons: - - - gmake commits target and dependency lists earlier than -it should. For example, target.mk has a rule that looks like -this: - - - $(HS_PROG) : $(OBJS) - $(HC) $(LD_OPTS) $< -o $@ - - -If this rule was in boilerplate.mk then $(HS_PROG)$(OBJS)gmake encountered the rule. Alas, gmake takes a snapshot -of their current values, and wires that snapshot into the rule. (In -contrast, the commands executed when the rule ``fires'' are only -substituted at the moment of firing.) So, the rule must follow the -definitions given in the Makefile itself. - - Unlike pattern rules, ordinary rules cannot be overriden or -replaced by subsequent rules for the same target (at least not without an -error message). Including ordinary rules in boilerplate.mk would -prevent the user from writing rules for specific targets in specific cases. - - There are a couple of other reasons I've forgotten, but it doesn't -matter too much. - - - -The main mk/boilerplate.mk file -

- -Sometimes the canned rule just doesn't do the right thing. For -example, in the nofib suite we want the link step to print out -timing information. The thing to do here is HS_PROG or C_PROG, and instead define a special purpose rule in -your own Makefile. By using different variable names you will avoid -the canned rules being included, and conflicting with yours. - - -Booting/porting from C (.hc) files -

- -This section is for people trying to get GHC going by using the -supplied intermediate C (.hc) files. This would probably be because -no binaries have been provided, or because the machine is not ``fully -supported.'' - -The intermediate C files are normally made available together with a -source release, please check the announce message for exact directions -of where to find them. If we've haven't made them available or you -can't find them, please ask. - -Assuming you've got them, unpack them on top of a fresh source tree. -Then follow the `normal' instructions in Section~ for setting -up a build tree. When you invoke the configure script, you'll have -to tell the script about your intentions: - - -foo% ./configure --enable-hc-boot - -mk/build.mk -for any other purposes, the next step is to proceed with a make boot -followed by make all. At the successful completion of make all, -you should end up with a binary of the compiler proper, -ghc/compiler/hsc, plus archives (but no .hi files!) of the prelude -libraries. To generate the Prelude interface files (and test drive the -bootstrapped compiler), re-run the configure script, but this time -witout the --enable-hc-boot option. After that re-create the -contents of ghc/lib: - - -foo% ./configure - .... -foo% cd ghc/lib -foo% make clean -foo% make boot -foo% make all - - - -That's the mechanics of the boot process, but, of course, if you're -trying to boot on a platform that is not supported and significantly -`different' from any of the supported ones, this is only the start of -the adventure…(ToDo: porting tips - stuff to look out for, etc.) - - -Known pitfalls in building Glasgow Haskell -

- -WARNINGS about pitfalls and known ``problems'': - - - - -One difficulty that comes up from time to time is running out of space -in /tmp. (It is impossible for the configuration stuff to -compensate for the vagaries of different sysadmin approaches re temp -space.) -setenv TMPDIR /usr/tmpsetenv TMPDIR . (or the equivalent incantation with the shell -of your choice). - -The best way around it is to say - -export TMPDIR=

- -in your build.mk file. -Then GHC and the other fptools programs will use the appropriate directory -in all cases. - - - -In compiling some support-code bits, e.g., in ghc/rts/gmp and even -in ghc/lib, you may get a few C-compiler warnings. We think these -are OK. - - -When compiling via C, you'll sometimes get ``warning: assignment from -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__2_2s.o truncated to GlaIOMonad_ -... - - - In compiling the compiler proper (in compiler/), you - - If you're compiling with GHC 4.00 or above, then the --optCrts-M&lt;size&gt; flag (add this flag to -<module>_HC_OPTS make variable in the appropriate Makefile). - - For GHC < 4.00, add a suitable -H flag to the Makefile, as -above. - - - -and try again: gmake. (see Section~ for information about -<module>_HC_OPTS.) - -Alternatively, just cut to the chase scene: - -% cd ghc/compiler -% make EXTRA_HC_OPTS=-optCrts-M128M - - - -If you try to compile some Haskell, and you get errors from GCC about -lots of things from /usr/include/math.h, then your GCC was -mis-installed. fixincludes wasn't run when it should've been. + +The way to do this is, of course, to compile and run this program +(in a file Main.hs): + -As fixincludes is now automagically run as part of GCC installation, -this bug also suggests that you have an old GCC. + + +main = putStr "Hello, world!\n" + - -You ranlib -% 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 - - -We'd be interested to know if this is still necessary. - + - -GHC's sources go through cpp before being compiled, and cpp varies -a bit from one Unix to another. One particular gotcha is macro calls -like this: + +Compile the program, using the -v (verbose) flag to verify that +libraries, etc., are being found properly: - - SLIT("Hello, world") - + +% ghc -v -o hello Main.hs -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 - + +Now run it: -Alas, cpp doesn't tell you the offending file! + +% ./hello +Hello, world! -Workaround: don't put wierd things in string args to cpp macros. - + -
+ +Some simple-but-profitable tests are to compile and run the notorious +nfibnfib program, using different numeric types. Start with +nfib :: Int -> Int, and then try Integer, Float, Double, +Rational and perhaps the overloaded version. Code for this is +distributed in ghc/misc/examples/nfib/ in a source distribution. + + +For more information on how to “drive” GHC, read +on... + + + + + + + + +Installing on Windows + + +Getting the Glasgow Haskell Compiler (post 5.02) to run on Windows platforms is +a snap: the Installshield does everything you need. + + +Installing GHC on Windows + + +To install GHC, use the following steps: + + +Download the Installshield setup.exe +from the GHC download page +haskell.org. + + +Run setup.exe. +(If you have a previous version of GHC, Installshield will offer to "modify", +or "remove" GHC. Choose "remove"; then run setup.exe a +second time. This time it should offer to install.) + + +At this point you should find GHCi and the GHC documentation are +available in your Start menu under "Start/Programs/Glasgow Haskell Compiler". + + + + +The final dialogue box from the install process tells you where GHC has +been installed. If you want to invoke GHC from a command line, add this +to your PATH environment variable. Usually, GHC installs into +c:/ghc/ghc-5.02, though the last part of this path +depends on which version of GHC you are installing, of course. +You need to add c:/ghc/ghc-5.02/bin to your path if yo + + + +GHC needs a directory in which to create, and later delete, temporary files. +It uses the standard Windows procedure GetTempPath() to +find a suitable directory. This procedure returns: + +The path in environment variable TMP, +if TMP is set. +Otherwise, the path in environment variable TEMP, +if TEMP is set. +Otherwise, there is a per-user default which varies +between versions of Windows. On NT and XP-ish versions, it might +be: +c:\Documents and Settings\<username>\Local Settings\Temp + + +The main point is that if you don't do anything GHC will work fine; +but if you want to control where the directory is, you can do so by +setting TMP or TEMP. + + + + +To test the fruits of your labour, try now to compile a simple +Haskell program: + + + +bash$ cat main.hs +module Main(main) where + +main = putStrLn "Hello, world!" +bash$ ghc -o main main.hs +.. +bash$ ./main +Hello, world! +bash$ + + + + +You do not need the Cygwin toolchain, or anything +else, to install and run GHC. + + +An installation of GHC requires about 140M of disk space. +To run GHC comfortably, your machine should have at least +64M of memory. + + + +Moving GHC around + +At the moment, GHC installs in a fixed place (c:/ghc/ghc-x.yy, +but once it is installed, you can freely move the entire GHC tree just by copying +the ghc-x.yy directory. (You may need to fix up +the links in "Start/Programs/Glasgow Haskell Compiler" if you do this.) + + +It is OK to put GHC tree in a directory whose path involves spaces. However, +don't do this if you use want to use GHC with the Cygwin tools, +because Cygwin can get confused when this happpens. +We havn't quite got to the bottom of this, but so far as we know it's not +a problem with GHC itself. Nevertheless, just to keep life simple we usually +put GHC in a place with a space-free path. + + + +Installing ghc-win32 FAQ + + + + + + + +I'm having trouble with symlinks. + + + + + +Symlinks only work under Cygwin (), so binaries +not linked to the Cygwin DLL, in particular those built for Mingwin, will not +work with symlinks. + + + + + + + + + +I'm getting “permission denied” messages from the rm or +mv. + + + + + +This can have various causes: trying to rename a directory when an Explorer +window is open on it tends to fail. Closing the window generally cures the +problem, but sometimes its cause is more mysterious, and logging off and back +on or rebooting may be the quickest cure. + + + + + + + + + + + + + +The layout of installed files + + +This section describes what files get installed where. You don't need to know it +if you are simply installing GHC, but it is vital information if you are changing +the implementation. + + GHC is installed in two directory trees: + + +Library directory, + known as $(libdir), holds all the +support files needed to run GHC. On Unix, this +directory is usually something like /usr/lib/ghc/ghc-5.02. + + + +Binary directory + known as $(bindir), holds executables that +the user is expected to invoke. +Notably, it contains +ghc and ghci. On Unix, this directory +can be anywhere, but is typically something like /usr/local/bin. On Windows, +however, this directory must be $(libdir)/bin. + + + + + + +When GHC runs, it must know where its library directory is. +It finds this out in one of two ways: + + + + +$(libdir) is passed to GHC using the flag. +On Unix (but not Windows), the installed ghc is just a one-line +shell script that invokes the real GHC, passing a suitable flag. +[All the user-supplied flags +follow, and a later flag overrides an earlier one, so a user-supplied +one wins.] + + + + On Windows (but not Unix), if no flag is given, GHC uses a system +call to find the directory in which the running GHC executable lives, and derives +$(libdir) from that. [Unix lacks such a system call.] +That is why $(bindir) must be $(libdir)/bin. + + + + + The binary directory + +The binary directory, $(bindir) contains user-visible +executables, notably ghc and ghci. +You should add it to your $PATH + + +On Unix, the user-invokable ghc invokes $(libdir)/ghc-version, +passing a suitable flag to tell ghc-version where +$(libdir) is. +Similarly ghci, except the extra flag --interactive is passed. + + +On Win32, the user-invokable ghc binary +is the Real Thing (no intervening +shell scripts or .bat files). +Reason: we sometimes invoke GHC with very long command lines, +and cmd.exe (which executes .bat files) +truncates them. Similarly ghci is a C wrapper program that invokes ghc --interactive +(passing on all other arguments), not a .bat file. + + + + + + The library directory + +The layout of the library directory, $(libdir) is almost identical on +Windows and Unix, as follows. Differences between Windows and Unix +are noted thus [Win32 only] and are commented below. + + + $(libdir)/ + package.conf GHC package configuration + ghc-usage.txt Message displayed by ghc ––help + + bin/ [Win32 only] User-visible binaries + ghc.exe + ghci.exe + + unlit Remove literate markup + + touchy.exe [Win32 only] + perl.exe [Win32 only] + gcc.exe [Win32 only] + + ghc-x.xx GHC executable [Unix only] + + ghc-split Asm code splitter + ghc-asm Asm code mangler + + gcc-lib/ [Win32 only] Support files for gcc + specs gcc configuration + + cpp0.exe gcc support binaries + as.exe + ld.exe + + crt0.o Standard + ..etc.. binaries + + libmingw32.a Standard + ..etc.. libraries + + *.h Include files + + imports/ GHC interface files + std/*.hi 'std' library + lang/*.hi 'lang' library + ..etc.. + + include/ C header files + StgMacros.h GHC-specific + ..etc... header files + + mingw/*.h [Win32 only] Mingwin header files + + libHSrts.a GHC library archives + libHSstd.a + libHSlang.a + ..etc.. + + HSstd1.o GHC library linkables + HSstd2.o (used by ghci, which does + HSlang.o not grok .a files yet) + + +Note that: + + + + $(libdir) also contains support + binaries. These are not expected to be + on the user's PATH, but and are invoked + directly by GHC. In the Makefile system, this directory is + also called $(libexecdir), but + you are not free to change it. It must + be the same as $(libdir). + + + +We distribute gcc with the Win32 distribution of GHC, so that users +don't need to install gcc, nor need to care about which version it is. +All gcc's support files are kept in $(libdir)/gcc-lib/. + + + + +Similarly, we distribute perl and a touch +replacement (touchy.exe) +with the Win32 distribution of GHC. + + + + The support programs ghc-split + and ghc-asm are Perl scripts. The + first line says #!/bin/perl; on Unix, the + script is indeed invoked as a shell script, which invokes + Perl; on Windows, GHC invokes + $(libdir)/perl.exe directly, which + treats the #!/bin/perl as a comment. + Reason: on Windows we want to invoke the Perl distributed + with GHC, rather than assume some installed one. + + + + + + + + + + +