<Para>
Getting the Glasgow Haskell Compiler (GHC) to run on Windows platforms can
-be a bit of a trying experience. This document tries to simplify the task by
-enumerating the steps you need to follow in order to set up and configure
-your machine to run GHC.
+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.
</Para>
-<Sect2><Title>System requirements</Title>
-
-<Para>
-An installation of GHC requires about 50M of disk space (which can be lowered by choosing a “compact” installation). The Cygwin support tools take another 200M or so (though if you really need to this can be halved by installing only the following packages: bash, binutils, cygwin, diff, fileutils, findutils, gcc, grep, make, perl, mingw, sed, textutils, w32api; however, it's fiddly and not recommended). To run GHC
-comfortably, your machine should have at least 64M of memory.
-</Para>
-
-</Sect2>
-
-
-<Sect2 id="sec-required"><Title>Software required</Title>
-
-<Para>
-You need two chunks of software other than GHC itself: the Cygwin toolchain, and Perl. Here's how to get and install them.
-</Para>
-
-<Sect3><Title>The Cygwin toolchain (1.1.x)</Title>
-
-<Para>
-At the moment you'll need Cygwin to use GHC. Cygwin dresses up the Win32
-environment into something more UNIX-like; (notably, it provides
-<Command>gcc</Command>, <Command>as</Command> and <Command>ld</Command>).
-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.
+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.
</Para>
-<ItemizedList>
-
-<ListItem>
-<Para>
-Install the latest Cygwin 1.1.x from <ULink
-URL="http://sources.redhat.com/cygwin/">sources.redhat.com/cygwin</ULink>.
-If you have a pre-1.1 version, you should deinstall this first. Choose DOS
-text mode. After installation, start up a Cygwin shell and issue the
-following command:
-
-<Screen>
-mount -f c: /</Screen>
-
-assuming you installed Cygwin at <Filename>C:\cygwin</Filename>; otherwise
-change the drive and directory as appropriate.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Create <Filename>C:/Temp</Filename> if it doesn't already exist; substitute
-the drive you installed Cygwin on for <Filename>C:</Filename>).
-</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>
-
-</Sect3>
-
-
-<Sect3><Title>Environment variables</Title>
-
-<Para>
-In case you don't already know how to set environment variables on a Windows
-machine, here's how. On WinNT/Win2k, to edit your <Constant>PATH</Constant>
-variable (for example), 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 <Constant>PATH</Constant></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 <Command>bash</Command>
-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 must reboot to make
-the new settings take effect.
-</Para>
-
-<Para>
-The following environment variables must be set:
-</Para>
-
-<Para>
-<InformalTable>
-<TGroup cols="2">
-<ColSpec Align="Left" Colsep="0">
-<ColSpec Align="Left" Colsep="0">
-<TBody>
-
-<Row>
-<Entry><Constant>PATH</Constant></Entry>
-<Entry>System</Entry>
-<Entry><Para>
-Add <Filename>C:\usr\bin</Filename>.
-This should come <Emphasis>before</Emphasis> the Windows system directories
-(e.g. <Filename>\WINNT\system32</Filename>).
-</Para></Entry>
-</Row>
-
-<Row>
-<Entry><Constant>SHELL</Constant></Entry>
-<Entry>User</Entry>
-<Entry><Para>
-<Filename>C:/usr/bin/bash</Filename>.
-</Para></Entry>
-</Row>
-
-<Row>
-<Entry><Constant>HOME</Constant></Entry>
-<Entry>User</Entry>
-<Entry><Para>
-Set to point to your home directory (normally under
-<Filename>C:/WINNT/Profiles</Filename> on Win2k). This is where, for example,
-<Command>bash</Command> will look for your <Filename>.bashrc</Filename>
-file.
-</Para></Entry>
-</Row>
-
-<Row>
-<Entry><Constant>MAKE_MODE</Constant></Entry>
-<Entry>User</Entry>
-<Entry><Para>
-Set 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></Entry>
-</Row>
-
-<Row>
-<Entry><Constant>TMPDIR</Constant></Entry>
-<Entry>User</Entry>
-<Entry><Para>
-Set to <Filename>C:/Temp</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><Para>
-Furthermore, it seems that <Constant>TMPDIR</Constant> must be set to a directory in the same file system in which you invoke GHC. Otherwise you get very weird messages when you invoke GHC, such as:
-<Screen>
-does not exist
-Action: openFile
-Reason: file does not exist /Temp/ghc11068.cpp</Screen>
-We think this is due to a bug in Cygwin.
-</Para></Entry>
-</Row>
-</TBody>
-
-</TGroup>
-</InformalTable>
-</Para>
-
-<Para>
-In addition, we've had problems in the past with certain environment
-variables being set that seem to have bad effects on GHC. If you have
-installed other systems ported from Unix, you might too. If you get weird
-inexplicable failures to build GHC, then it might be worth weeding out unused
-environment variables. Known culprits from the past include
-<Constant>GCC_EXEC_PREFIX</Constant> and <Constant>INCLUDE</Constant>.
-</Para>
-
-</Sect3>
-
-</Sect2> <!-- Reqd software -->
-
<Sect2><Title>Installing GHC</Title>
<Para>
-Download the latest GHC distribution:
-</Para>
-
-<VariableList>
-
-<VarListEntry>
-<Term>ghc-4.08 InstallShield installer, 15M: <ULink
-URL="http://www.haskell.org/ghc/download.html">http</ULink>
-</Term>
-
-<ListItem>
-<Para>
+Download the latest GHC distribution (ghc-4.08 InstallShield installer, 19M)
+from <ULink
+URL="http://www.haskell.org/ghc/download.html">haskell.org</ULink>
It is packaged up using an installer that should be familiar-looking to
Windows users.
</Para>
<Para>
-Note: The cygwin support for long file names containing
+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>!)
ghc <Filename>bin/</Filename> directory to your path (e.g.
<Filename>/ghc/ghc-4.08/bin </Filename>).
You need to do this in order to bring the various GHC binaries into scope.
+Also, if the directory <Filename>C:/TEMP</Filename> doesn't already exist,
+you should create it.
</Para>
<Para>
-Note: If 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>
-
-</VariableList>
-
-<Para>
-Make sure that you set all the environment variables described above
-under Cygwin installation, including <Constant>TMPDIR</Constant>.
-</Para>
-<Para>
To test the fruits of your labour, try now to compile a simple
Haskell program:
</Para>
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">).
</Para>
-<Para> Further information on using GHC under Windows can be found in <ULink
+<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>. 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>
+manual.
+</Para>
</Sect2>
</QandAEntry>
-<QandAEntry>
-
-<Question>
-<Para>
-My programs compile fine but do nothing when run.
-</Para>
-</Question>
-
-<Answer> <Para>Some recent versions of the mingw package in Cygwin seem to
-cause this. mingwin version 20001111-1 works fine; you should be able to
-select it by clicking on the version number of the mingw package in the list
-presented by the Cygwin setup program.</Para>
-</Answer>
-
-</QAndAEntry>
-
</QandASet>
</Sect2>
<Title>Building the documentation</Title>
<Para>
-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.
+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.
</Para>
<Para>
<Sect2>
<Title>Installing the DocBook tools from RPMs</Title>
-<Para> If you're using a system that can handle RedHat RPM packages, you can
-probably use the <ULink
+<Para> If you're using a system that can handle RedHat RPM packages,
+you can probably use the <ULink
URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus DocBook
-tools</ULink>, which is the most shrink-wrapped SGML suite that we could
-find. You need all the RPMs except for psgml (i.e.
+tools</ULink>, which is the most shrink-wrapped SGML suite that we
+could find. You need all the RPMs except for psgml (i.e.
<Filename>docbook</Filename>, <Filename>jade</Filename>,
<Filename>jadetex</Filename>, <Filename>sgmlcommon</Filename> and
<Filename>stylesheets</Filename>). Note that most of these RPMs are
architecture neutral, so are likely to be found in a
-<Filename>noarch</Filename> directory. The SuSE RPMs also work; the RedHat
-ones <Emphasis>don't</Emphasis> as of version 6.2, but they are easy to fix:
-just make a symlink from
-<Filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</Filename> to
-<Filename>/usr/lib/sgml/lib/dblib.dsl</Filename>. </Para>
+<Filename>noarch</Filename> directory. The SuSE RPMs also work; the
+RedHat ones <Emphasis>don't</Emphasis> in RedHat 6.2 (7.0 and later
+should be OK), but they are easy to fix: just make a symlink from
+<Filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</Filename>
+to <Filename>/usr/lib/sgml/lib/dblib.dsl</Filename>. </Para>
</Sect2>
+ <sect2>
+ <title>Installing DocBook on FreeBSD</title>
+
+ <para>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).</para>
+
+ <para>To use the ports tree, do this:
+<screen>
+ $ cd /usr/ports/textproc/docproj
+ $ make install
+</screen>
+ This installs the FreeBSD documentation project tools, which
+ includes everything needed to format the GHC
+ documentation.</para>
+ </sect2>
<Sect2>
<Title>Installing from binaries on Windows</Title>