X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Finstalling.sgml;h=2d15aff91bc998b4d038e33034a92645aae8ba61;hb=d3229889fb50daec12a9f73af9124ed958e89266;hp=d668f21f109acb63d095e126472ea33070403597;hpb=7db602a0d8f840362c455650cbddc1ecc04ec43d;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/installing.sgml b/ghc/docs/users_guide/installing.sgml index d668f21..2d15aff 100644 --- a/ghc/docs/users_guide/installing.sgml +++ b/ghc/docs/users_guide/installing.sgml @@ -1,26 +1,81 @@ -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 or building the documentation (). + + + + + 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 Linux/x86 + + RPM source & binary packages for RedHat 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 +83,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: @@ -96,7 +151,7 @@ Guide and this file isn't present. -bin/<platform> + bin/platform contains platform-specific executable @@ -105,7 +160,7 @@ must end up in your path. -lib/<platform>/ +lib/platform/ contains platform-specific support @@ -123,7 +178,7 @@ These sub-directories have the following general structure: -libHS.a etc: +libHSstd.a etc: supporting library archives. @@ -163,14 +218,6 @@ for the installation. Again, there is a sub-directory for each -info/ - - -contains Emacs info documentation files (one -sub-directory per project). - - - html/ @@ -188,41 +235,6 @@ 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 @@ -245,7 +257,7 @@ 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. @@ -323,21 +335,26 @@ 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! +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. +Run make install. This +should work with ordinary Unix +make—no need for fancy stuff like GNU +make. @@ -356,7 +373,7 @@ stuff in your bin directory. . 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 know pitfalls in +If things don't work as expected, check the list of known pitfalls in the building guide. @@ -383,11 +400,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: @@ -442,6 +460,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. + @@ -491,12 +515,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... @@ -505,343 +525,46 @@ with a binary distribution, or in source form in -Installing on Windows - - -Getting the Glasgow Haskell Compiler(GHC) to run on Windows95/98 or -Windows NT4 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. - - - - - -Your environment variables - - -Much of the Unixy stuff below involves setting environment variables. -This section summarises how to set these variables on a Windows machine, in -case you don't know alread.y -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 a Cygwin (see ) shell -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 need to reboot to make -the new settings take effect. - - - - - -Software required +Installing on Windows -You need two chunks of software other than GHC itself: the Cygwin toolchain, and Perl. Here's how to get and install them. +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 use GHC is included in +the InstallShield. -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. - - - -Important grungy information about Cygwin: - - - - - -Cygwin doesn't deal well with filenames that include -spaces. "Program Files" and "Local files" are -common gotchas. +An installation of GHC requires about 140M of disk space. +To run GHC comfortably, your machine should have at least +64M of memory. - - - - -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. - - - - - - -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. - - - - - - - - - - - -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.045—InstallShield installer, 10M: http or ftp - - - - -(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. +Download the latest GHC distribution (ghc-5.02 InstallShield installer, 27M) +from haskell.org. 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.05/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. +ghc bin/ directory to your path, as directed in the +final dialog of the installer. You need to do this in order to bring the +various GHC binaries into scope. - - - - - -ghc-4.045 - gzip'ed tarfile, 7.5M: -http or ftp - - - -A `normal' GHC binary distribution packaged up as a compressed tar file. -If you're already accustomed to installing and using GHC distributions -on other platforms, the setup should be familiar to you, I -hope. Unpack and read the INSTALL file contained in the -distribution for instructions on how to set it up. +You can freely move the GHC tree once you've installed it just by copying +the ghc-x.yy directory. You might want to do this in +order to use GHC with tools that don't like spaces in paths (GHC is +installed in \Program Files\Glasgow Haskell +Compiler by default. -Notice that the top directory of the distribution contains -(rather clumsily) a perl binary (version 5.005_02). If you -haven't already got a working perl, install this somewhere -along your path too. - - - - - - - -Make sure that you set all the environment variables described above -under Cygwin installation, including TMPDIR - - To test the fruits of your labour, try now to compile a simple Haskell program: @@ -851,7 +574,7 @@ bash$ cat main.hs module Main(main) where main = putStrLn "Hello, world!" -bash$ /path/to/the/ghc/bin/directory/ghc-4.05 -o main main.hs +bash$ ghc -o main main.hs .. bash$ ./main Hello, world! @@ -863,15 +586,18 @@ Haskell programs :-) If not, consult the installation FAQ (Sigbjørn Finne's pages. +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. - - -Installing ghc-win32 FAQ +Installing ghc-win32 FAQ @@ -879,21 +605,15 @@ Further information on using GHC under Windows can be found in ), so binaries +not linked to the Cygwin DLL, in particular those built for Mingwin, will not +work with symlinks. @@ -903,94 +623,347 @@ All being well, ghc should then start to function. -When compiling up the Hello World example, the following happens: - - - -bash$ /ghc/ghc-4.05/bin/ghc-4.05 main.hs -<stdin>:0:25: Character literal '{-# LINE 1 "main.hs" -}' too long -<stdin>:0:25: on input: "'" -bash$ - - -or +I'm getting “permission denied” messages from the rm or +mv. - - -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. +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 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. + + + + + + + +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: + + +Binary directory + known as $(bindir), holds executables that +the user is expected to invoke. Notably, +ghc and ghci. On Unix, this directory +is typically something like /usr/local/bin. On Windows, +however, this directory is always $(libdir)/bin. + + + + +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. + + + + + +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.] + + + + + Layout of the library directory + +The layout of the library directory is almost identical on +Windows and Unix, as follows: layout: + + + $(libdir)/ + package.conf GHC package configuration + ghc-usage.txt Message displayed by ghc --help + + bin/ [Win32 only] User-visible binaries + ghc.exe + ghci.bat + + 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: + + +On Win32, the $(libdir)/bin directory contains user-visible binaries; +add it to your PATH. The ghci executable is a .bat +file which invokes ghc. + +The GHC executable 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. [We assume people won't invoke ghci with very long +command lines.] + +On Unix, the user-invokable ghc invokes $(libdir)/ghc-version, +passing a suitable flag. + + + + + $(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. + + + + + + + + + +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. - -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: + +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 in RedHat 6.2 (7.0 and later +should be OK), but they are easy to fix: just make a symlink from +/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl +to /usr/lib/sgml/lib/dblib.dsl. + + + + + Installing DocBook on FreeBSD + + On FreeBSD systems, the easiest way to get DocBook up and + running is to install it from the ports tree or a pre-compiled + package (packages are available from your local FreeBSD mirror + site). + + To use the ports tree, do this: + + $ cd /usr/ports/textproc/docproj + $ make install + + This installs the FreeBSD documentation project tools, which + includes everything needed to format the GHC + documentation. + + + +Installing from binaries on Windows + +It's a good idea to use Norman Walsh's installation +notes as a guide. You should get version 3.1 of DocBook, and note +that his file test.sgm won't work, as it needs version +3.0. You should unpack Jade into \Jade, along with the +entities, DocBook into \docbook, and the DocBook +stylesheets into \docbook\stylesheets (so they actually +end up in \docbook\stylesheets\docbook). + + + + +Installing the DocBook tools from source + + +Jade + +Install OpenJade (Windows binaries are available as well as sources). If you want DVI, PS, or PDF then install JadeTeX from the dsssl +subdirectory. (If you get the error: + -bin/ghc-4.xx -- where xx is the minor release number -bin/stat2resid -bin/hstags -lib/mkdependHS +! LaTeX Error: Unknown option implicit=false' for package hyperref'. + - -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. +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.) - -Should you want to pick up a complete installation of a ghc-friendly port -of perl instead, a cygwin port is available. +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 - - -System.getArgs always return the empty list, i.e. the following program always prints “[]”: +Get a Zip of DocBook +and install the contents in /usr/[local/]/lib/sgml. - -module Main(main) where -import qualified System -main = System.getArgs >>= print - +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. + - - -This is a bug with the RTS DLL that comes with ghc-4.03. To fix, upgrade to -ghc-4.05. + + + + + +Configuring the DocBook tools + +Once the DocBook tools are installed, the configure script will detect them and set up the build system accordingly. If you have a system that isn't supported, let us know, and we'll try to help. - - + - + +Remaining problems + +If you install from source, you'll get a pile of warnings of the form + +DTDDECL catalog entries are not supported + +every time you build anything. These can safely be ignored, but if you find them tedious you can get rid of them by removing all the DTDDECL entries from docbook.cat. + + + + +