X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Finstalling.sgml;h=fdfb0782aaaae791573d73a73c52cce769b27b48;hb=90af5e7b48c2f0ec74891c1399d46781d078484a;hp=ae44c3389c03d3a171b59fb071e2c0d21b0377ec;hpb=ff0d9475f7681a60f41280d8791dbd69b272ec55;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/installing.sgml b/ghc/docs/users_guide/installing.sgml index ae44c33..fdfb078 100644 --- a/ghc/docs/users_guide/installing.sgml +++ b/ghc/docs/users_guide/installing.sgml @@ -15,10 +15,26 @@ Haskell, so binary distributions allow you to install them without having a Haskell compiler.) -This guide is in two parts: installing on Unix-a-likes, and installing on Windows. - - - Installing on Unix-a-likes +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 @@ -35,10 +51,11 @@ having a Haskell compiler.) - RedHat Linux/x86 + RedHat or SuSE Linux/x86 - RPM source & binary packages for RedHat Linux (x86 - only) are available for most major releases. + RPM source & binary packages for RedHat and SuSE + Linux (x86 only) are available for most major + releases. @@ -86,8 +103,9 @@ Binary distributions come in “bundles,” one bundle per file called -Then you should find a single directory, fptools, with the following -structure: +Then you should find a single directory, +ghc-version, with the +following structure: @@ -216,13 +234,6 @@ contains HTML documentation files (one sub-directory per project). - -man/ - - -contains Unix manual pages. - - @@ -230,10 +241,11 @@ contains Unix manual pages. Installing -OK, so let's assume that you have unpacked your chosen bundles into a -scratch directory fptools. What next? Well, you will at least need -to run the configureconfigure script by changing your -directory to fptools and typing ./configure. That should convert +OK, so let's assume that you have unpacked your chosen bundles. What +next? Well, you will at least need to run the +configureconfigure +script by changing directory into the top-level directory for the +bundle and typing ./configure. That should convert Makefile.in to Makefile. @@ -248,11 +260,11 @@ you simply want to try out the package and/or you don't have the necessary privileges (or inclination) to properly install the tools locally. Note that if you do decide to install the package `properly' at a later date, you have to go through the installation steps that -follows. +follow. -To install an fptools package, you'll have to do the following: +To install a package, you'll have to do the following: @@ -518,47 +530,64 @@ on... Installing on Windows - -Getting the Glasgow Haskell Compiler (GHC) to run on Windows platforms can -be a bit of a trying experience. It should be much easier now than in the -past, since all the software required to build and use GHC is included in -the InstallShield. - - - -An installation of GHC requires about 70M of disk space (which can be -reduced by choosing a “compact” installation). -To run GHC comfortably, your machine should have at least -64M of memory. - - - -Installing GHC - - -Download the latest GHC distribution (ghc-4.08 InstallShield installer, 19M) -from haskell.org -It is packaged up using an installer that should be familiar-looking to -Windows users. - - - -Note: The Cygwin support for long file names containing -spaces is not 100%, so make sure that you install ghc in a directory -that has no embedded spaces (i.e., resist the temptation to put it -in /Program Files/!) - + +Getting the Glasgow Haskell Compiler (post 5.02) to run on Windows platforms is +a snap: the Installshield does everything you need. + - -When the installer has completed, make sure you add the location of the -ghc bin/ directory to your path (e.g. -/ghc/ghc-4.08/bin ). -You need to do this in order to bring the various GHC binaries into scope. -Also, if the directory C:/TEMP doesn't already exist, -you should create it. - +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: @@ -574,23 +603,36 @@ 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. + -OK, assuming that worked, you're all set. Go forth and write useful -Haskell programs :-) If not, consult the installation FAQ (); if that still doesn't help then please report the problems you're experiencing (see ). +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 -Further information on using GHC under Windows can be found in Sigbjørn Finne's -pages. Note: ignore the installation instructions, which are rather -out of date; the Miscellaneous section at the bottom of -the page is of most interest, covering topics beyond the scope of this -manual. +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 @@ -618,7 +660,7 @@ work with symlinks. -I'm getting “permission denied” messages from rm or +I'm getting “permission denied” messages from the rm or mv. @@ -634,178 +676,206 @@ on or rebooting may be the quickest cure. - - - - -I get errors when trying to build GHC 4.08 with GHC 4.05. - - - - This seems to work better if you don't use - in GhcHcOpts. It's a bug in 4.05, -unfortunately. Anyway, better to install 4.08 binaries and use those. - - - - - - - - - - -Building the documentation - - -We use the DocBook DTD, which is widely used. Most shrink-wrapped -distributions seem to be broken in one way or another; thanks to -heroic efforts by Sven Panne and Manuel Chakravarty, we now support -most of them, plus properly installed versions. - - + + - -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. - +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. + + + + - -Configuring the DocBook tools + +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. + + + - -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. - + The binary directory - +The binary directory, $(bindir) contains user-visible +executables, notably ghc and ghci. +You should add it to your $PATH + - -Remaining problems +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. + - -If you install from source, you'll get a pile of warnings of the form +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. + -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. - + + + 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. + + + - + - +