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-likesWhen 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.
+
+
+
-
+
-
+