<Chapter id="sec-installing-bin-distrib">
-<Title>Installing from binary distributions</Title>
+ <Title>Installing GHC</Title>
<IndexTerm><Primary>binary installations</Primary></IndexTerm>
<IndexTerm><Primary>installation, of binaries</Primary></IndexTerm>
<Para>
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 <Literal>fptools</Literal> programs, many are written in Haskell,
-so binary distributions allow you to install them without having a Haskell compiler.)
-</Para>
-
-<Para>This guide is in two parts: installing on Unix-a-likes, and installing on Windows.</Para>
-
-
-<Sect1><Title>Installing on Unix-a-likes</Title>
+(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 <Literal>fptools</Literal> programs, many are written in
+Haskell, so binary distributions allow you to install them without
+having a Haskell compiler.)
+</Para>
+
+<Para>This guide is in several parts:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para> Installing on Unix-a-likes (<Xref
+ LinkEnd="sec-unix-a-likes">). </para>
+ </listitem>
+ <listitem>
+ <para> Installing on Windows (<Xref
+ LinkEnd="sec-install-windows">). </para>
+ </listitem>
+ <listitem>
+ <para> The layout of installed files (<Xref
+ LinkEnd="sec-install-files">). You don't need to know this to
+ install GHC, but it's useful if you are changing the
+ implementation.</para>
+ </listitem>
+ </itemizedlist>
+
+ <Sect1 id="sec-unix-a-likes"><Title>Installing on Unix-a-likes</Title>
+
+ <sect2>
+ <title>When a platform-specific package is available</title>
+
+ <para>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.</para>
+
+ <para>We generally provide the following packages:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>RedHat or SuSE Linux/x86</term>
+ <listitem>
+ <para>RPM source & binary packages for RedHat and SuSE
+ Linux (x86 only) are available for most major
+ releases.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Debian Linux/x86</term>
+ <listitem>
+ <para>Debian packages for Linux (x86 only), also for most
+ major releases.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FreeBSD/x86</term>
+ <listitem>
+ <para>On FreeBSD/x86, GHC can be installed using either
+ the ports tree (<literal>cd /usr/ports/lang/ghc && make
+ install</literal>) or from a pre-compiled package
+ available from your local FreeBSD mirror.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Other platform-specific packages may be available, check
+ the GHC download page for details.</para>
+ </sect2>
<Sect2>
-<Title>Bundle structure</Title>
+<Title>GHC binary distributions</Title>
<Para>
<IndexTerm><Primary>bundles of binary stuff</Primary></IndexTerm>
</Para>
<Para>
-Binary distributions come in ``bundles,'' one bundle per file called
-<Literal><bundle>-<platform>.tar.gz</Literal>. (See the building guide for the definition of a platform.) Suppose that you untar a binary-distribution bundle, thus:
+Binary distributions come in “bundles,” one bundle per file called
+<literal><replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</Literal>. (See the building guide for the definition of a platform.) Suppose that you untar a binary-distribution bundle, thus:
</Para>
<Para>
<Screen>
% cd /your/scratch/space
-% gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
-</Screen>
+% gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -</Screen>
</Para>
<Para>
-Then you should find a single directory, <Literal>fptools</Literal>, with the following
-structure:
+Then you should find a single directory,
+<Literal>ghc-<replaceable>version</replaceable></Literal>, with the
+following structure:
</Para>
<Para>
</Para>
</ListItem></VarListEntry>
<VarListEntry>
-<Term><Literal>bin/<platform></Literal></Term>
+ <Term><Literal>bin/<replaceable>platform</replaceable></Literal></Term>
<ListItem>
<Para>
contains platform-specific executable
</Para>
</ListItem></VarListEntry>
<VarListEntry>
-<Term><Literal>lib/<platform>/</Literal></Term>
+<Term><Literal>lib/<replaceable>platform</replaceable>/</Literal></Term>
<ListItem>
<Para>
contains platform-specific support
<VariableList>
<VarListEntry>
-<Term><Literal>libHS.a</Literal> etc:</Term>
+<Term><Literal>libHSstd.a</Literal> etc:</Term>
<ListItem>
<Para>
supporting library archives.
</Para>
</ListItem></VarListEntry>
<VarListEntry>
-<Term><Literal>info/</Literal></Term>
-<ListItem>
-<Para>
-contains Emacs info documentation files (one
-sub-directory per project).
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
<Term><Literal>html/</Literal></Term>
<ListItem>
<Para>
sub-directory per project).
</Para>
</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>man/</Literal></Term>
-<ListItem>
-<Para>
-contains Unix manual pages.
-</Para>
-</ListItem></VarListEntry>
</VariableList>
</Para>
-<Para>
-This structure is designed so that you can unpack multiple bundles
-(including ones from different releases or platforms) into a single
-<Literal>fptools</Literal> directory
-<FOOTNOTE>
-
-<Para>
-this doesn't work at the
-moment
-</Para>
-
-</FOOTNOTE>
-:
-</Para>
-
-<Para>
-
-<Screen>
-% 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 -
-</Screen>
-
-</Para>
-
-<Para>
-When you do multiple unpacks like this, the top level <Literal>Makefile</Literal>,
-<Literal>README</Literal>, and <Literal>INSTALL</Literal> get overwritten each time.
-That's fine—they should be the same. Likewise, the
-<Literal>ANNOUNCE-<bundle></Literal> and <Literal>NEWS-<bundle></Literal>
-files will be duplicated across multiple platforms, so they will be
-harmlessly overwritten when you do multiple unpacks. Finally, the
-<Literal>share/</Literal> stuff will get harmlessly overwritten when you do
-multiple unpacks for one bundle on different platforms.
-</Para>
-
<Sect3 id="sec-install">
<Title>Installing</Title>
<Para>
-OK, so let's assume that you have unpacked your chosen bundles into a
-scratch directory <Literal>fptools</Literal>. What next? Well, you will at least need
-to run the <Literal>configure</Literal><IndexTerm><Primary>configure</Primary></IndexTerm> script by changing your
-directory to <Literal>fptools</Literal> and typing <Literal>./configure</Literal>. 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
+<Literal>configure</Literal><IndexTerm><Primary>configure</Primary></IndexTerm>
+script by changing directory into the top-level directory for the
+bundle and typing <Literal>./configure</Literal>. That should convert
<Literal>Makefile.in</Literal> to <Literal>Makefile</Literal>.
</Para>
<Para>
<IndexTerm><Primary>installing in-place</Primary></IndexTerm>
<IndexTerm><Primary>in-place installation</Primary></IndexTerm>
-</Para>
-
-<Para>
You can now either start using the tools <Emphasis>in-situ</Emphasis> without going
through any installation process, just type <Literal>make in-place</Literal> to set the
tools up for this. You'll also want to add the path which <Literal>make</Literal> will
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.
</Para>
<Para>
-To install an <Literal>fptools</Literal> package, you'll have to do the following:
+To install a package, you'll have to do the following:
</Para>
<Para>
</VariableList>
The values for these variables can be set through invocation of the
-<Command>configure</Command><IndexTerm><Primary>configure</Primary></IndexTerm> script that comes with the distribution,
-but doing an optical diff to see if the values match your expectations
-is always a Good Idea.
-
-<Emphasis>Instead of running <Command>configure</Command>, it is perfectly OK to copy
-<Filename>Makefile.in</Filename> to <Filename>Makefile</Filename> and set all these variables
-directly yourself. But do it right!</Emphasis>
+<Command>configure</Command><IndexTerm><Primary>configure</Primary></IndexTerm>
+script that comes with the distribution, but doing an optical diff to
+see if the values match your expectations is always a Good Idea.
+</para>
+<para>
+<Emphasis>Instead of running <Command>configure</Command>, it is
+perfectly OK to copy <Filename>Makefile.in</Filename> to
+<Filename>Makefile</Filename> and set all these variables directly
+yourself. But do it right!</Emphasis>
</Para>
+
</ListItem>
<ListItem>
<Para>
-Run <Literal>make install</Literal>. This <Emphasis> should</Emphasis> work with ordinary Unix
-<Literal>make</Literal>—no need for fancy stuff like GNU <Literal>make</Literal>.
+Run <Literal>make install</Literal>. This <Emphasis>
+should</Emphasis> work with ordinary Unix
+<Literal>make</Literal>—no need for fancy stuff like GNU
+<Literal>make</Literal>.
</Para>
</ListItem>
<ListItem>
<Para>
- Once done, test your ``installation'' as suggested in
+ Once done, test your “installation” as suggested in
<XRef LinkEnd="sec-GHC-test">. Be sure to use a <Literal>-v</Literal>
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.
</Para>
</ListItem>
procedure will install GHC as <Literal>ghc-x.xx</Literal> where <Literal>x.xx</Literal> is the version
number of GHC. It will also make a link (in the binary installation
directory) from <Literal>ghc</Literal> to <Literal>ghc-x.xx</Literal>. If you install multiple versions
-of GHC then the last one ``wins'', and ``<Literal>ghc</Literal>'' will invoke the last
+of GHC then the last one “wins”, and “<Literal>ghc</Literal>” will invoke the last
one installed. You can change this manually if you want. But
regardless, <Literal>ghc-x.xx</Literal> should always invoke GHC version <Literal>x.xx</Literal>.
</Para>
<Title>What bundles there are</Title>
<Para>
-<IndexTerm><Primary>bundles, binary</Primary></IndexTerm>
-There are plenty of ``non-basic'' GHC bundles. The files for them are
-called <Literal>ghc-x.xx-<bundle>-<platform>.tar.gz</Literal>, where
-the <Literal><platform></Literal> is as above, and <Literal><bundle></Literal> is one
-of these:
+<IndexTerm><Primary>bundles, binary</Primary></IndexTerm> There are
+plenty of “non-basic” GHC bundles. The files for them are
+called
+<Literal>ghc-x.xx-<replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</Literal>,
+where the <replaceable>platform</replaceable> is as above, and
+<replaceable>bundle</replaceable> is one of these:
</Para>
<Para>
</Para>
</ListItem></VarListEntry>
<VarListEntry>
-<Term><Literal>conc</Literal>:</Term>
-<ListItem>
-<Para>
-Concurrent Haskell features. You may want this.
-<IndexTerm><Primary>concurrent bundles</Primary></IndexTerm>
-<IndexTerm><Primary>bundles, concurrent</Primary></IndexTerm>
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
<Term><Literal>par</Literal>:</Term>
<ListItem>
<Para>
<Term><Literal>gran</Literal>:</Term>
<ListItem>
<Para>
-The ``GranSim'' parallel-Haskell simulator
+The “GranSim” parallel-Haskell simulator
(hmm… mainly for implementors).
<IndexTerm><Primary>bundles, gransim</Primary></IndexTerm>
<IndexTerm><Primary>gransim bundles</Primary></IndexTerm>
<Term><Literal>ticky</Literal>:</Term>
<ListItem>
<Para>
-``Ticky-ticky'' profiling; very detailed
-information about ``what happened when I ran this program''—really
+“Ticky-ticky” profiling; very detailed
+information about “what happened when I ran this program”—really
for implementors.
<IndexTerm><Primary>bundles, ticky-ticky</Primary></IndexTerm>
<IndexTerm><Primary>ticky-ticky bundles</Primary></IndexTerm>
</Para>
</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>prof-conc</Literal>:</Term>
-<ListItem>
-<Para>
-Cost-centre profiling for Concurrent Haskell.
-<IndexTerm><Primary>bundles, profiled-concurrent</Primary></IndexTerm>
-<IndexTerm><Primary>profiled-concurrent bundles</Primary></IndexTerm>
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>prof-ticky</Literal>:</Term>
-<ListItem>
-<Para>
-Ticky-ticky profiling for Concurrent Haskell.
-<IndexTerm><Primary>bundles, profiled-ticky</Primary></IndexTerm>
-<IndexTerm><Primary>ticky-concurrent bundles</Primary></IndexTerm>
-</Para>
-</ListItem></VarListEntry>
</VariableList>
</Para>
<Para>
-One likely scenario is that you will grab <Emphasis>three</Emphasis> binary
-bundles—basic, profiling, and concurrent. We don't usually make the
+One likely scenario is that you will grab <Emphasis>two</Emphasis>
+binary bundles—basic, and profiling. We don't usually make the
rest, although you can build them yourself from a source distribution.
</Para>
+<para>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 <emphasis>must</emphasis>
+at least have the basic GHC binary distribution bundle, these extra
+bundles won't install on their own.</para>
+
</Sect3>
<Sect3 id="sec-GHC-test">
libraries, etc., are being found properly:
<Screen>
-% ghc -v -o hello Main.hs
-</Screen>
+% ghc -v -o hello Main.hs</Screen>
</Para>
<Screen>
% ./hello
-Hello, world!
-</Screen>
+Hello, world!</Screen>
</Para>
distributed in <Literal>ghc/misc/examples/nfib/</Literal> in a source distribution.
</Para>
-<Para>
-For more information on how to ``drive'' GHC, either do <Literal>ghc -help</Literal> or
-consult the User's Guide (distributed in several pre-compiled formats
-with a binary distribution, or in source form in
-<Literal>ghc/docs/users_guide</Literal> in a source distribution).
-</Para>
+<para>For more information on how to “drive” GHC, read
+on...</para>
</Sect3>
</Sect1>
-<Sect1><Title>Installing on Windows</Title>
-
-<Para>
-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 ;-)
-</Para>
-
-<Sect2><Title>System requirements</Title>
-
-<Para>
-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.
-</Para>
-
-<Para>
-To run GHC comfortably, your machine should have at least 32M of memory.
-</Para>
-
-</Sect2>
-
-
-<Sect2><Title>Your environment variables</Title>
-
-<Para>
-Much of the Unixy stuff below involves setting environment variables. For example, on WinNT/Win2k, to edit your <Constant>PATH</Constant> variable,
-do the following:
-</Para>
-
-<ItemizedList>
-<ListItem><Para>Press Start/Settings/Control Panels</Para></ListItem>
-<ListItem><Para>Double-click System</Para></ListItem>
-<ListItem><Para>Press Advanced</Para></ListItem>
-<ListItem><Para>Press Environment Variables</Para></ListItem>
-<ListItem><Para>Under System Variables, select PATH</Para></ListItem>
-<ListItem><Para>Press Edit</Para></ListItem>
-<ListItem><Para>Add "<Filename>;C:/whatever/</Filename>" to the end of the string (for example)</Para></ListItem>
-<ListItem><Para>Press OK</Para></ListItem>
-</ItemizedList>
-
-<Para>
-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.
-</Para>
-
-<Para>
-In addition, when running a Cygwin (see <XRef LinkEnd="sec-required">) shell
-you can set environment variables in your <Filename>.bashrc</Filename> 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 <Filename>cvs.exe</Filename> without going via bash.
-</Para>
-
-<Para>
-On a Win9x machine you need to edit <Filename>autoexec.bat</Filename> using
-<Filename>Windows/system/Sysedit</Filename>. You need to reboot to make
-the new settings take effect.
-</Para>
-
-</Sect2>
-
-
-<Sect2 id="sec-required"><Title>Software required</Title>
-
-<VariableList>
-<VarListEntry>
-<Term>The cygwin toolchain (beta20.1)</Term>
-<ListItem>
-<Para>
-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 <Command>gcc</Command>, <Command>as</Command> and <Command>ld</Command>),
-so you'll need to install these tools first. You also need
-Cygwin to use CVS.
-</Para>
-
-<Para>
-Important grungy information about Cygwin:
-</Para>
-
-<ItemizedList>
-
-<ListItem>
-<Para>
-Cygwin doesn't deal well with filenames that include
-spaces. "<Filename>Program Files</Filename>" and "<Filename>Local files</Filename>" are
-common gotchas.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-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.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-<Para>
-Here's how to install Cygwin.
-</Para>
-
-<ItemizedList>
-
-<ListItem>
-<Para>
-Download cygwin, beta20.1 (<filename>full.exe</filename>) from
-<ULink URL="http://sourceware.cygnus.com/cygwin/">sourceware.cygnus.com</ULink>
-Install this somewhere locally.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Create the following directories (if they aren't already there):
-</Para>
-
-<ItemizedList>
-<ListItem><Para><Filename>c:/etc</Filename></Para></ListItem>
-<ListItem><Para><Filename>c:/bin</Filename></Para></ListItem>
-<ListItem><Para><Filename>c:/usr/local/bin</Filename></Para></ListItem>
-</ItemizedList>
-
-<Para>
-(using <Command>mkdir -p /bin</Command>, etc.)
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Add the two <Filename>bin</Filename> directories to your <Constant>PATH</Constant>.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Copy <Filename>bash.exe</Filename> from the <Filename>bin</Filename> directory of the cygwin tree (<Filename>cygwin-b20/H-i586-cygwin32/bin/bash.exe</Filename>) to
-<Filename>/bin</Filename> as <Filename>sh.exe</Filename>. This is where Emacs looks for a shell (I think).
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-You might think that it was easier to use bash directly from it original
-Cygwin directory, but (a) some UNIX utils have got <FIlename>/bin/sh</FIlename> hardwired in, and (b) the path following <Literal>#!</Literal> is limited to 32 characters.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Add <Filename>C:\cygnus\cygwin-b20\H-i586-cygwin32\bin</Filename> to your <Constant>PATH</Constant>.
-<Command>bash</Command> needs this, and when it is invoked from <Filename>/bin</Filename> it can't
-find it.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Set your <Constant>SHELL</Constant> user environment variable to <Filename>c:/bin/sh</Filename>.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Set your <Filename>HOME</Filename> user environment variable to point to your
-home directory. This is where, for example,
-<Command>bash</Command> will look for your <Filename>.bashrc</Filename>
-file.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Set your <Constant>MAKE_MODE</Constant> user environment variable to <Literal>UNIX</Literal>. If you don't do
-this you get very weird messages when you type `<Command>make</Command>', such as:
-</Para>
-
-<Screen>
-/c: /c: No such file or directory
-</Screen>
-</ListItem>
-
-<ListItem>
-<Para>
-Set the <Constant>TMPDIR</Constant> user environment variable to <Filename>/tmp</Filename>. 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 <Constant>TMPDIR</Constant> variable set, it tries to use it for temporary files, but
-Cygwin doesn't grok filenames with spaces, so disaster results.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-If you're an Emacs user and want to be able to run <Command>bash</Command>
-from within a shell buffer, see the <ULink URL="http://www.cs.washington.edu/homes/voelker/ntemacs.html">NT Emacs home page</ULink> for
-instructions on how to set this up.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term>Perl5</Term>
-<ListItem><Para>
-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 <Emphasis>not</Emphasis>
-work with the ActiveState port of perl.
-</Para>
-</ListItem>
-</VarListEntry>
-
-</VariableList>
-
-</Sect2>
-
-
-<Sect2><Title>Installing the supporting software</Title>
-
-<ItemizedList>
-<ListItem>
-<Para>
-Download <ULink URL="http://sourceware.cygnus.com/cygwin/">cygwin beta20.1</ULink> (<Filename>full.exe</Filename>). Install this somewhere locally.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-After having successfully installed this, make sure you do the following:
-</Para>
-
-<ItemizedList>
-<ListItem>
-<Para>
-Create a <Filename>/bin</Filename> directory (using <Command>mkdir -p /bin</Command>).
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Copy <Filename>bash.exe</Filename> from the <Filename>bin</Filename> directory of the cygwin tree (<Filename>cygwin-b20/H-i586-cygwin32/bin/bash.exe</Filename>) to
-<Filename>/bin</Filename> as <Filename>sh.exe</Filename>.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-If you haven't already got one, create a <Filename>/tmp</Filename> directory.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-If you're an Emacs user and want to be able to run <Command>bash</Command>
-from within a shell buffer, see the <ULink URL="http://www.cs.washington.edu/homes/voelker/ntemacs.html">NT Emacs home page</ULink> for
-instructions on how to set this up.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</ListItem>
-
-</ItemizedList>
-
-<Para>
-With the supporting software in place, we can finally get on to installing GHC itself.
-</Para>
-
-</Sect2>
-
-
-<Sect2><Title>Installing GHC</Title>
-
-<Para>
-Download a GHC distribution:
-</Para>
-
-<VariableList>
-
-<VarListEntry>
-<Term>ghc-4.045—InstallShield installer, 10M: <ULink URL="http://www.dcs.gla.ac.uk/~sof/ghc-4.045-win32-IS.zip">http</ULink> or <ULink URL="ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow/4.04/ghc-4.045-win32-IS.zip">ftp</ULink>
-</Term>
-
-<ListItem>
-<Para>
-(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 <Filename>setup.exe</Filename>.
-</Para>
-
-<Para>
-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 <Filename>/Program Files/</Filename>!)
-</Para>
-
-<Para>
-When the installer has completed its job, you may delete the
-<Filename>ghcInstall</Filename> directory.
-</Para>
-
-<Para>
-When the installer has completed, make sure you add the location of the
-ghc <Filename>bin/</Filename> directory to your path (i.e. <Filename>/path/to/wherever/ghc-4.05/bin </Filename>).
-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).
-</Para>
-
-<Para>
-Note: In case you haven't got perl already installed,
-you will have to manually copy the <Filename>perl.exe</Filename> binary from the
-ghc <Filename>bin/</Filename> into your <Filename>/bin</Filename> directory before continuing—the installer will not currently do this.
-</Para>
-</ListItem>
-
-</VarListEntry>
-
-<VarListEntry>
-<Term>
-ghc-4.045 - gzip'ed tarfile, 7.5M: <ULink URL="http://www.dcs.gla.ac.uk/~sof/ghc-4.045-win32.tar.gz">
-http</ULink> or <ULink URL="ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow/4.04/ghc-4.045-win32.tar.gz">ftp</ULink>
-</Term>
-
-<ListItem>
-<Para>
-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.
-</Para>
-
-<Para>
-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.
-</Para>
-</ListItem>
-
-</VarListEntry>
-</VariableList>
-
+<Sect1 id="sec-install-windows"><Title>Installing on Windows</Title>
+
+<para>
+Getting the Glasgow Haskell Compiler (post 5.02) to run on Windows platforms is
+a snap: the Installshield does everything you need.
+</para>
+
+<Sect2><Title>Installing GHC on Windows</Title>
+
+<para>
+To install GHC, use the following steps:
+</para>
+<itemizedlist>
+<listitem><para>Download the Installshield <Filename>setup.exe</Filename>
+from the GHC download page
+<ULink
+URL="http://www.haskell.org/ghc">haskell.org</ULink>.
+</para></listitem>
+
+<listitem><para>Run <Filename>setup.exe</Filename>.
+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 <filename>c:/ghc/<replaceable>ghc-version</replaceable></filename>.
+The executable binary for GHC will be installed in the <filename>bin/</filename> sub-directory
+of the installation directory you choose.
+</para>
+<para>(If you have already installed the same version of GHC, Installshield will offer to "modify",
+or "remove" GHC. Choose "remove"; then run <Filename>setup.exe</Filename> a
+second time. This time it should offer to install.)
+</para>
+<para>
+When installation is complete, you should find GHCi and the GHC documentation are
+available in your Start menu under "Start/Programs/Glasgow Haskell Compiler".
+</para>
+</listitem>
+
+<listitem><para>
+The final dialogue box from the install process reminds you where the GHC binary
+has been installed (usually <filename>c:/ghc/<replaceable>ghc-version</replaceable>/bin/</filename>.
+If you want to invoke GHC from a command line, add this
+to your PATH environment variable.
+</para></listitem>
+
+<listitem><para>
+GHC needs a directory in which to create, and later delete, temporary files.
+It uses the standard Windows procedure <literal>GetTempPath()</literal> to
+find a suitable directory. This procedure returns:
+<itemizedlist>
+<listitem><para>The path in environment variable TMP,
+if TMP is set.</para></listitem>
+<listitem><para>Otherwise, the path in environment variable TEMP,
+if TEMP is set.</para></listitem>
+<listitem><para>Otherwise, there is a per-user default which varies
+between versions of Windows. On NT and XP-ish versions, it might
+be:
+<Filename>c:\Documents and Settings\<username>\Local Settings\Temp</filename>
+</para></listitem>
+</itemizedlist>
+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.
+</para></listitem>
+
+<listitem>
<Para>
To test the fruits of your labour, try now to compile a simple
Haskell program:
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!
-bash$
-</Screen>
+bash$ </Screen>
+</listitem>
+</itemizedlist>
+<para>
+You do <emphasis>not</emphasis> need the Cygwin toolchain, or anything
+else, to install and run GHC.
+</para>
<Para>
-OK, assuming that worked, you're all set. Go forth and write useful
-Haskell programs :-) If not, consult the installation FAQ (<XRef LinkEnd="winfaq">); if that still doesn't help then please report the problems you're experiencing (see <Xref LinkEnd="wrong">).
+An installation of GHC requires about 140M of disk space.
+To run GHC comfortably, your machine should have at least
+64M of memory.
</Para>
+</sect2>
+<Sect2><title>Moving GHC around</title>
<Para>
-Further information on using GHC under Windows can be found in <ULink URL="http://www.dcs.gla.ac.uk/~sof/ghc-win32.html">Sigbjørn Finne's pages</ULink>.
+At the moment, GHC installs in a fixed place (<Filename>c:/ghc/ghc-x.yy</Filename>,
+but once it is installed, you can freely move the entire GHC tree just by copying
+the <Filename>ghc-x.yy</Filename> directory. (You may need to fix up
+the links in "Start/Programs/Glasgow Haskell Compiler" if you do this.)
+</para>
+<para>
+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.
</Para>
+</sect2>
-</Sect2>
-
-</Sect1>
-
-
-<Sect1 id="winfaq"><title>Installing ghc-win32 FAQ</title>
+<Sect2 id="winfaq"><title>Installing ghc-win32 FAQ</title>
<QandASet>
<Question>
<Para>
-Invoking ghc doesn't seem to do anything, it immediately returns without having compiled the input file.
+I'm having trouble with symlinks.
</Para>
</Question>
<Answer>
<Para>
-One cause of this is that <Filename>/bin/sh</Filename> is missing. To verify, open up a
-bash session and type <Command>ls -l /bin/sh.exe</Command>. If <Filename>sh.exe</Filename> is
-reported as not being there, copy <Filename>bash.exe</Filename> (which you'll find
-inside the cygwin installation tree as <Filename>H-i586-cygwin32/bin/bash.exe</Filename>)
-to <Filename>/bin/sh.exe</Filename>.
-</Para>
-
-<Para>
-All being well, ghc should then start to function.
+Symlinks only work under Cygwin (<Xref LinkEnd="sec-install">), so binaries
+not linked to the Cygwin DLL, in particular those built for Mingwin, will not
+work with symlinks.
</Para>
</Answer>
<Question>
<Para>
-When compiling up the <Literal>Hello World</Literal> example, the following happens:
-</Para>
-
-<Screen>
-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$
-</Screen>
-
-<Para>
-or
+I'm getting “permission denied” messages from the <Command>rm</Command> or
+<Command>mv</Command>.
</Para>
-
-<Screen>
-bash$ /ghc/ghc-4.05/bin/ghc-4.05 main.hs
-Program too big fit into memory under NT
-bash$
-</Screen>
</Question>
<Answer>
<Para>
-The cause of this is that you're using a version of <Command>perl</Command> that employs the Microsoft <Command>cmd</Command>/<Command>command</Command> shell when launching sub-processes to execute <Function>system()</Function> calls.
-</Para>
-
-<Para>
-The GHC driver really needs a <Command>perl</Command> which uses a `UNIX'y shell instead, so
-make sure that the version you're using is of an compatible ilk. In particular,
-if <Command>perl -v</Command> reports that you've got a copy of the (otherwise fine) port
-of perl done by ActiveState, you're in trouble.
-</Para>
-
-<Para>
-If you're stuck with an incompatible <Command>perl</Command>, the GHC installation comes with a very basic <Command>perl</Command> binary for you to use. Simply copy it into the <Command>/bin</Command> directory.
-</Para>
-
-<Para>
-Notice that copying <Filename>perl.exe</Filename> into <Filename>/bin</Filename> 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:
-</Para>
-
-<Screen>
-bin/ghc-4.xx -- where xx is the minor release number
-bin/stat2resid
-bin/hstags
-lib/mkdependHS
-</Screen>
-
-<Para>
-For each of these files, you need to edit the first line from instead
-saying <Command>#!/path/to/your/other/perl/install</Command> to <Command>#!/bin/perl</Command>.
-Once that is done, try compiling up the Hello, World example again.
-</Para>
-
-<Para>
-Should you want to pick up a complete installation of a ghc-friendly port
-of perl instead, a <ULink URL="http://cygutils.netpedia.net/">cygwin port</ULink> is available.
+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.
</Para>
</Answer>
</QandAEntry>
-<QAndAEntry>
-
-<Question>
-<Para>
-<Function>System.getArgs</Function> always return the empty list, i.e. the following program always prints <Screen>"[]"</Screen>:
-</Para>
-
-<ProgramListing>
-module Main(main) where
-import qualified System
-main = System.getArgs >>= print
-</ProgramListing>
-
-</Question>
+</QandASet>
-<Answer>
+<!-- doesn't add much value any longer; leave out [sof 7/2002].
<Para>
-This is a bug with the RTS DLL that comes with ghc-4.03. To fix, upgrade to
-ghc-4.05.
+Further information on using GHC under Windows can be found in <ULink
+URL="http://www.dcs.gla.ac.uk/~sof/ghc-win32.html">Sigbjørn Finne's
+pages</ULink>. Note: ignore the installation instructions, which are rather
+out of date; the <Emphasis>Miscellaneous</Emphasis> section at the bottom of
+the page is of most interest, covering topics beyond the scope of this
+manual.
</Para>
-</Answer>
+-->
+</Sect2>
-</QAndAEntry>
+</Sect1>
-</QandASet>
-</Sect1>
+<Sect1 id="sec-install-files"><Title>The layout of installed files</Title>
+
+<para>
+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.
+</para>
+<para> GHC is installed in two directory trees:</para>
+<variablelist>
+<varlistentry>
+<term>Library directory,</term>
+<listitem> <para> known as <Filename>$(libdir)</Filename>, holds all the
+support files needed to run GHC. On Unix, this
+directory is usually something like <Filename>/usr/lib/ghc/ghc-5.02</Filename>. </para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Binary directory</term>
+<listitem> <para> known as <Filename>$(bindir)</Filename>, holds executables that
+the user is expected to invoke.
+Notably, it contains
+<Filename>ghc</Filename> and <Filename>ghci</FileName>. On Unix, this directory
+can be anywhere, but is typically something like <Filename>/usr/local/bin</Filename>. On Windows,
+however, this directory <emphasis>must be</emphasis> <Filename>$(libdir)/bin</Filename>.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>
+When GHC runs, it must know where its library directory is.
+It finds this out in one of two ways:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<Filename>$(libdir)</Filename> is passed to GHC using the <option>-B</option> flag.
+On Unix (but not Windows), the installed <filename>ghc</filename> is just a one-line
+shell script that invokes the real GHC, passing a suitable <option>-B</option> flag.
+[All the user-supplied flags
+follow, and a later <option>-B</option> flag overrides an earlier one, so a user-supplied
+one wins.]
+</para>
+</listitem>
+<listitem>
+<para> On Windows (but not Unix), if no <option>-B</option> flag is given, GHC uses a system
+call to find the directory in which the running GHC executable lives, and derives
+<Filename>$(libdir)</Filename> from that. [Unix lacks such a system call.]
+That is why <Filename>$(bindir)</Filename> must be <Filename>$(libdir)/bin</Filename>.
+</para>
+</listitem>
+</itemizedlist>
+
+<sect2> <title>The binary directory</title>
+
+<para>The binary directory, <Filename>$(bindir)</Filename> contains user-visible
+executables, notably <filename>ghc</filename> and <filename>ghci</filename>.
+You should add it to your <literal>$PATH</literal>
+</para>
+
+<para>On Unix, the user-invokable <filename>ghc</filename> invokes <filename>$(libdir)/ghc-<replaceable>version</replaceable></filename>,
+passing a suitable <option>-B</option> flag to tell <filename>ghc-<replaceable>version</replaceable></filename> where
+<Filename>$(libdir)</Filename> is.
+Similarly <filename>ghci</filename>, except the extra flag <literal>--interactive</literal> is passed.
+</para>
+
+<para>On Win32, the user-invokable <filename>ghc</filename> binary
+is the Real Thing (no intervening
+shell scripts or <filename>.bat</filename> files).
+Reason: we sometimes invoke GHC with very long command lines,
+and <filename>cmd.exe</filename> (which executes <filename>.bat</filename> files)
+truncates them. Similarly <filename>ghci</filename> is a C wrapper program that invokes <filename>ghc --interactive</filename>
+(passing on all other arguments), not a <filename>.bat</filename> file.
+</para>
+
+
+</sect2>
+
+<sect2> <title>The library directory</title>
+
+<para>The layout of the library directory, <filename>$(libdir)</filename> is almost identical on
+Windows and Unix, as follows. Differences between Windows and Unix
+are noted thus <literal>[Win32 only]</literal> and are commented below.</para>
+
+<programlisting>
+ $(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)
+</programlisting>
+
+<para>Note that:
+<itemizedlist>
+
+ <listitem>
+ <para><filename>$(libdir)</filename> also contains support
+ binaries. These are <emphasis>not</emphasis> expected to be
+ on the user's <filename>PATH</filename>, but and are invoked
+ directly by GHC. In the Makefile system, this directory is
+ also called <filename>$(libexecdir)</filename>, but
+ <emphasis>you are not free to change it</emphasis>. It must
+ be the same as <filename>$(libdir)</filename>.</para>
+ </listitem>
+
+<listitem>
+<para>We distribute <filename>gcc</filename> with the Win32 distribution of GHC, so that users
+don't need to install <filename>gcc</filename>, nor need to care about which version it is.
+All <filename>gcc</filename>'s support files are kept in <filename>$(libdir)/gcc-lib/</filename>.
+</para>
+</listitem>
+
+<listitem>
+<para>Similarly, we distribute <filename>perl</filename> and a <filename>touch</filename>
+replacement (<filename>touchy.exe</filename>)
+with the Win32 distribution of GHC. </para>
+</listitem>
+
+ <listitem>
+ <para>The support programs <filename>ghc-split</filename>
+ and <filename>ghc-asm</filename> are Perl scripts. The
+ first line says <literal>#!/bin/perl</literal>; on Unix, the
+ script is indeed invoked as a shell script, which invokes
+ Perl; on Windows, GHC invokes
+ <filename>$(libdir)/perl.exe</filename> directly, which
+ treats the <literal>#!/bin/perl</literal> as a comment.
+ Reason: on Windows we want to invoke the Perl distributed
+ with GHC, rather than assume some installed one. </para>
+ </listitem>
+</itemizedlist>
+</para>
+
+</sect2>
+
+</sect1>
</Chapter>
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: sgml ***
+ ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
+ ;;; End: ***
+ -->
projects / ghc-hetmet.git / blobdiff