X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Finstalling.xml;fp=docs%2Fusers_guide%2Finstalling.xml;h=9f8e4c9eb80b788aaaaae7b72b316e0c7d46a661;hb=0065d5ab628975892cea1ec7303f968c3338cbe1;hp=0000000000000000000000000000000000000000;hpb=28a464a75e14cece5db40f2765a29348273ff2d2;p=ghc-hetmet.git diff --git a/docs/users_guide/installing.xml b/docs/users_guide/installing.xml new file mode 100644 index 0000000..9f8e4c9 --- /dev/null +++ b/docs/users_guide/installing.xml @@ -0,0 +1,875 @@ + + + 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 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 +Guide and this file isn't present. + + + + 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 +files for the installation. Typically there is a subdirectory for +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. + + + +These sub-directories have the following general structure: + + + + + + +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. + + + +html/ + + +contains HTML documentation files (one +sub-directory per project). + + + + + + +Installing + + +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. + + + +installing in-place +in-place installation +You can now either start using the tools in-situ without going +through any installation process, just type make in-place to set the +tools up for this. You'll also want to add the path which make will +now echo to your PATH environment variable. This option is useful if +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 +follow. + + + +To install a package, you'll have to do the following: + + + + + + + + + Edit the Makefile and check the settings of the following variables: + +directories, installation +installation directories + + + + +platform + + +the platform you are going to install for. + + + +bindir + + +the directory in which to install user-invokable +binaries. + + + +libdir + + +the directory in which to install +platform-dependent support files. + + + +datadir + + +the directory in which to install +platform-independent support files. + + + +infodir + + +the directory in which to install Emacs info +files. + + + +htmldir + + +the directory in which to install HTML +documentation. + + + +dvidir + + +the directory in which to install DVI +documentation. + + + + +The values for these variables can be set through invocation of the +configureconfigure +script that comes with the distribution, but doing an optical diff to +see if the values match your expectations is always a Good Idea. + + + +Instead of running configure, it is +perfectly OK to copy Makefile.in to +Makefile and set all these variables directly +yourself. But do it right! + + + + + + +Run make install. This +should work with ordinary Unix +make—no need for fancy stuff like GNU +make. + + + + + + +rehash (t?csh or zsh users), so your shell will see the new +stuff in your bin directory. + + + + + + + Once done, test your “installation” as suggested in +. Be sure to use a -v +option, so you can see exactly what pathnames it's using. + +If things don't work as expected, check the list of known pitfalls in +the building guide. + + + + + + + + +link, installed as ghc +When installing the user-invokable binaries, this installation +procedure will install GHC as ghc-x.xx where x.xx is the version +number of GHC. It will also make a link (in the binary installation +directory) from ghc to ghc-x.xx. If you install multiple versions +of GHC then the last one “wins”, and “ghc” will invoke the last +one installed. You can change this manually if you want. But +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. +parallel bundles +bundles, parallel + + + +gran: + + +The “GranSim” parallel-Haskell simulator +(hmm… mainly for implementors). +bundles, gransim +gransim bundles + + + +ticky: + + +“Ticky-ticky” profiling; very detailed +information about “what happened when I ran this program”—really +for implementors. +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. + + +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. + + + + +Testing that GHC seems to be working + + + +testing a new GHC + + + +The way to do this is, of course, to compile and run this program +(in a file 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 + + + + +Now run it: + + +% ./hello +Hello, world! + + + + +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. +On Windows, all of GHC's files are installed in a single directory. +If you choose ``Custom'' from the list of install options, you will be given a +choice about where this directory is; otherwise it will be installed +in c:/ghc/ghc-version. +The executable binary for GHC will be installed in the bin/ sub-directory +of the installation directory you choose. + +(If you have already installed the same 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.) + + +When installation is complete, 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 reminds you where the GHC binary +has been installed (usually c:/ghc/ghc-version/bin/. +If you want to invoke GHC from a command line, add this +to your PATH environment variable. + + + +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 happens. +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. + + + + + + + + + + +