X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Finstalling.sgml;h=fdfb0782aaaae791573d73a73c52cce769b27b48;hb=57d3c7c8a8523e375d49d2ac036210b6dcf7ec9c;hp=27f42ae2a1bff38e3741b1e353760573647511bd;hpb=6873ca831100617add303f4ce545a5aea34255ca;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/installing.sgml b/ghc/docs/users_guide/installing.sgml index 27f42ae..fdfb078 100644 --- a/ghc/docs/users_guide/installing.sgml +++ b/ghc/docs/users_guide/installing.sgml @@ -1,26 +1,89 @@ -Installing from binary distributions + 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.) - - -This guide is in two parts: installing on Unix-a-likes, and installing on Windows. - - -Installing on Unix-a-likes +(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. + -Bundle structure +GHC binary distributions bundles of binary stuff @@ -28,7 +91,7 @@ so binary distributions allow you to install them without having a Haskell compi 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: +bundle-platform.tar.gz. (See the building guide for the definition of a platform.) Suppose that you untar a binary-distribution bundle, thus: @@ -40,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: @@ -96,7 +160,7 @@ Guide and this file isn't present. -bin/<platform> + bin/platform contains platform-specific executable @@ -105,7 +169,7 @@ must end up in your path. -lib/<platform>/ +lib/platform/ contains platform-specific support @@ -170,59 +234,18 @@ 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 directory - - - -this 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 -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. @@ -237,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: @@ -380,11 +403,12 @@ regardless, ghc-x.xx should always invoke GHC version 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: +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: @@ -439,6 +463,12 @@ binary bundles—basic, and profiling. We don't usually make the rest, although you can build them yourself from a source distribution. +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. + @@ -488,12 +518,8 @@ Some simple-but-profitable tests are to compile and run the notorious 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). - +For more information on how to “drive” GHC, read +on... @@ -504,324 +530,64 @@ with a binary distribution, or in source form in Installing on Windows - -Getting the Glasgow Haskell Compiler (GHC) to run on Windows platforms can -be a bit of a trying experience. This document tries to simplify the task by -enumerating the steps you need to follow in order to set up and configure -your machine to run GHC (at least that's the intention ;-) - - -System requirements - - -An installation of GHC requires ca. 70M of disk space. The size of the -installed GHC distribution is just(!) 17M, the rest is needed by -supporting software. - - - -To run GHC comfortably, your machine should have at least 32M of memory. - - - - - -Software required - - -You need two chunks of software other than GHC itself: the Cygwin toolchain, and Perl. Here's how to get and install them. - - -The cygwin toolchain (beta20.1) - - -GHC depends at the moment on the cygwin tools to operate, which -dresses up the Win32 environment into something more UNIX-like. -(notably, it provides gcc, as and ld), -so you'll need to install these tools first. You also need -Cygwin to use CVS. (We don't yet support later versions of Cygwin.) - - - -Important grungy information about 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 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. - - - - - - -Here's how to install Cygwin. - - - - - - -Download cygwin, beta20.1 (full.exe) from -sourceware.cygnus.com -Install this somewhere locally. - - - - - -Create the following directories (if they aren't already there): - - - -c:/etc -c:/bin -c:/usr/local/bin - - - -(using mkdir -p /bin, etc.) - - - - - -Copy bash.exe from the bin -directory of the cygwin tree -(cygwin-b20/H-i586-cygwin32/bin/bash.exe) to -/bin as sh.exe. You might -think that it was easier to use bash directly from it original Cygwin -directory, but (a) some UNIX utils have got -/bin/sh hardwired in, and (b) the path following -#! is limited to 32 characters. - - - - - -If you're an Emacs user and want to be able to run bash -from within a shell buffer, see the NT Emacs home page for -instructions on how to set this up. - - - - - - - - -Environment variables - - -In case you don't already know how to set environment variables on a Windows -machine, here's how. On WinNT/Win2k, to edit your PATH -variable (for example), do the following: - - - -Press Start/Settings/Control Panels -Double-click System -Press Advanced -Press Environment Variables -Under System Variables, select PATH -Press Edit -Add ";C:/whatever/" to the end of the string (for example) -Press OK - - - -Some environment variables are “user variables” and -some are “system variables”. I'm not sure of the difference -but both are changed though the same dialogue. - - - -In addition, when running bash -you can set environment variables in your .bashrc file. -But it is better to set your environment variables from the -control panel (they get inherited by bash) because then they are visible -to applications that aren't started by bash. For example, -when you're invoking CVS (and ssh) via Emacs keybindings; -it invokes cvs.exe without going via bash. - - - -On a Win9x machine you need to edit autoexec.bat using -Windows/system/Sysedit. You must reboot to make -the new settings take effect. - - - -The following environment variables must be set: - - - - - - - - - - -PATH -System - -Add C:/cygnus/cygwin-b20/H-i586-cygwin32/bin. -bash needs this, and when it is invoked from /bin it can't -find it. c:/bin and c:/usr/local/bin should also be added. - - - - -SHELL -User - -c:/bin/sh. - - - - -HOME -User - -Set to point to your home directory. This is where, for example, -bash will look for your .bashrc -file. - - - - -MAKE_MODE -User - -Set 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 - - - -TMPDIR -User - -Set to c:/tmp. For some reason, Win2k invisibly sets -this variable to point to a temporary directory in your profile, that -contains embedded spaces. If GHC sees the TMPDIR -variable set, it tries to use it for temporary files, but Cygwin -doesn't grok filenames with spaces, so disaster results. - -Furthermore, it seems that TMPDIR must be set to a directory -in the same file system in which you invoke GHC. Otherwise you get very werid messages -when you invoke GHC, such as: - -does not exist -Action: openFile -Reason: file does not exist /tmp/ghc11068.cpp -We think this is due to a bug in Cygwin. - - - - - - - - - -In addition, we've had problems in the past with certain environment -variables being set that seem to have bad effects on GHC. If you have -installed other systems ported from Unix, you might too. If you get weird -inexplicable failures to build GHC, then it might be worth weeding out unused -environment variables. Known culprits from the past include -GCC_EXEC_PREFIX and INCLUDE. - - - - - -Perl5 - - -The driver script is written in Perl, so you'll need to have this -installed too. However, the ghc binary distribution includes a -perl binary for you to make use of, should you not already have a -cygwin compatible one. Note: GHC does not -work with the ActiveState port of perl. - - - - - - - -Installing GHC - - -Download a GHC distribution: - - - - - -ghc-4.08—InstallShield installer, 20M: http - - - - -(The version number may change.) It is packaged up using an installer that should be familiar-looking to Windows users. Unpack and double click on setup.exe. - - - -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/!) - - - -When the installer has completed its job, you may delete the -ghcInstall directory. - - - -When the installer has completed, make sure you add the location of the -ghc bin/ directory to your path (i.e. -/path/to/wherever/ghc-4.08/bin ). -You need to do this in order to bring the various GHC DLLs into scope; -if not, then you need to copy the DLLs into a directory that is (the -system directory, for example). - - - -Note: In case you haven't got perl already installed, -you will have to manually copy the perl.exe binary from the -ghc bin/ into your /bin directory before continuing—the installer will not currently do this. - - + +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 - - - -Make sure that you set all the environment variables described above -under Cygwin installation, including TMPDIR - + +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: @@ -832,23 +598,41 @@ bash$ cat main.hs module Main(main) where main = putStrLn "Hello, world!" -bash$ /path/to/the/ghc/bin/directory/ghc-4.08 -o main main.hs +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. +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 @@ -858,30 +642,6 @@ Further information on using GHC under Windows can be found in - - -or - - - -bash$ /ghc/ghc-4.05/bin/ghc-4.05 main.hs -Program too big fit into memory under NT -bash$ - - - - -The cause of this is that you're using a version of perl that employs the Microsoft cmd/command shell when launching sub-processes to execute system() calls. - - - -The GHC driver really needs a perl which uses a `UNIX'y shell instead, so -make sure that the version you're using is of an compatible ilk. In particular, -if perl -v reports that you've got a copy of the (otherwise fine) port -of perl done by ActiveState, you're in trouble. - - - -If you're stuck with an incompatible perl, the GHC installation comes with a very basic perl binary for you to use. Simply copy it into the /bin directory. - - - -Notice that copying perl.exe into /bin will not cause -the GHC install to suddenly start functioning. If you don't want to -re-run the InstallShield installer again, you need to edit the following -files within the directory tree that the installer created: - - - -bin/ghc-4.xx where xx is the minor release number -bin/stat2resid -bin/hstags -lib/mkdependHS - - -For each of these files, you need to edit the first line from instead -saying #!/path/to/your/other/perl/install to #!/bin/perl. -Once that is done, try compiling up the Hello, World example again. - + + - - - - -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. - - - -Instructions on installing and configuring the DocBook tools follow. - - - -Installing the DocBook tools from RPMs - - -If you're 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 at the moment. - - - - - - -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. - - - +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. + + + - + - +