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>
+<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>
<variablelist>
<varlistentry>
- <term>RedHat Linux/x86</term>
+ <term>RedHat or SuSE Linux/x86</term>
<listitem>
- <para>RPM source & binary packages for RedHat Linux (x86
- only) are available for most major releases.</para>
+ <para>RPM source & binary packages for RedHat and SuSE
+ Linux (x86 only) are available for most major
+ releases.</para>
</listitem>
</varlistentry>
</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>
sub-directory per project).
</Para>
</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>man/</Literal></Term>
-<ListItem>
-<Para>
-contains Unix manual pages.
-</Para>
-</ListItem></VarListEntry>
</VariableList>
</Para>
<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>
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>
<Sect1 id="sec-install-windows"><Title>Installing on Windows</Title>
-<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.
-</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, and if you're trying to
-build rather than just use GHC, you need many more, so you might as well
-install the lot). 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.
-</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>
-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
-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, make sure you add the location of the
-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.
-</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>
+<para>
+Getting the Glasgow Haskell Compiler (post 5.02) to run on Windows platforms is
+a snap: the Installshield does everything you need.
+</para>
-</VariableList>
+<Sect2><Title>Installing GHC on Windows</Title>
-<Para>
-Make sure that you set all the environment variables described above
-under Cygwin installation, including <Constant>TMPDIR</Constant>.
-</Para>
+<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:
bash$ ./main
Hello, world!
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>
-<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>
-
-</Sect2>
-
+<Sect2><title>Moving GHC around</title>
+<Para>
+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 id="winfaq"><title>Installing ghc-win32 FAQ</title>
<Question>
<Para>
-I'm getting “permission denied” messages from <Command>rm</Command> or
+I'm getting “permission denied” messages from the <Command>rm</Command> or
<Command>mv</Command>.
</Para>
</Question>
</QandAEntry>
-<QandAEntry>
-
-<Question>
-<Para>
-I get errors when trying to build GHC 4.08 with GHC 4.05.
-</Para>
-</Question>
-
-<Answer> <Para> This seems to work better if you don't use
-<Option>-O</Option> in <Constant>GhcHcOpts</Constant>. It's a bug in 4.05,
-unfortunately. Anyway, better to install 4.08 binaries and use those.
-</Para> </Answer>
-
-</QandAEntry>
-
</QandASet>
-</Sect2>
-
-</Sect1>
-
-
-<Sect1 id="building-docs">
-<Title>Building the documentation</Title>
-
+<!-- doesn't add much value any longer; leave out [sof 7/2002].
<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.
-</Para>
-
-<Para>
-Instructions on installing and configuring the DocBook tools follow.
-</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
-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.
-<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> 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 from binaries on Windows</Title>
-
-<Para>
-It's a good idea to use Norman Walsh's <ULink
-URL="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
-notes</ULink> as a guide. You should get version 3.1 of DocBook, and note
-that his file <Filename>test.sgm</Filename> won't work, as it needs version
-3.0. You should unpack Jade into <Filename>\Jade</Filename>, along with the
-entities, DocBook into <Filename>\docbook</Filename>, and the DocBook
-stylesheets into <Filename>\docbook\stylesheets</Filename> (so they actually
-end up in <Filename>\docbook\stylesheets\docbook</Filename>).
+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>
-
+-->
</Sect2>
+</Sect1>
-<Sect2>
-<Title>Installing the DocBook tools from source</Title>
-
-<Sect3>
-<Title>Jade</Title>
-
-<Para>
-Install <ULink URL="http://openjade.sourceforge.net/">OpenJade</ULink> (Windows binaries are available as well as sources). If you want DVI, PS, or PDF then install JadeTeX from the <Filename>dsssl</Filename>
-subdirectory. (If you get the error:
-
-<Screen>
-! LaTeX Error: Unknown option implicit=false' for package hyperref'.
-</Screen>
-
-your version of <Command>hyperref</Command> is out of date; download it from
-CTAN (<Filename>macros/latex/contrib/supported/hyperref</Filename>), 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
-<Command>hyperref</Command>, you can abort at that point and proceed
-straight to <Command>make install</Command>, or enter them as
-<Filename>../</Filename><Emphasis>filename</Emphasis>.)
-</Para>
-
-<Para>
-Make links from <Filename>virtex</Filename> to <Filename>jadetex</Filename>
-and <Filename>pdfvirtex</Filename> to <Filename>pdfjadetex</Filename>
-(otherwise DVI, PostScript and PDF output will not work). Copy
-<Filename>dsssl/*.{dtd,dsl}</Filename> and <Filename>catalog</Filename> to <Filename>/usr/[local/]lib/sgml</Filename>.
-</Para>
-
-</Sect3>
-
-<Sect3>
-<Title>DocBook and the DocBook stylesheets</Title>
-
-<Para>
-Get a Zip of <ULink
-URL="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ULink>
-and install the contents in <Filename>/usr/[local/]/lib/sgml</Filename>.
-</Para>
-
-<Para>
-Get the <ULink URL="http://nwalsh.com/docbook/dsssl/">DocBook
-stylesheets</ULink> and install in
-<Filename>/usr/[local/]lib/sgml/stylesheets</Filename> (thereby creating a
-subdirectory docbook). For indexing, copy or link <Filename>collateindex.pl</Filename> from the DocBook stylesheets archive in <Filename>bin</Filename> into a directory on your <Constant>PATH</Constant>.
-</Para>
-
-<Para>
-Download the <ULink
-URL="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
-entities</ULink> into <Filename>/usr/[local/]lib/sgml</Filename>.
-</Para>
-</Sect3>
+<Sect1 id="sec-install-files"><Title>The layout of installed files</Title>
-</Sect2>
+<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>
-<Sect2>
-<Title>Configuring the DocBook tools</Title>
+<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>
-<Para>
-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.
-</Para>
+<sect2> <title>The binary directory</title>
-</Sect2>
+<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>
-<Sect2>
-<Title>Remaining problems</Title>
+<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>
-If you install from source, you'll get a pile of warnings of the form
+<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>
-<Screen>DTDDECL catalog entries are not supported</Screen>
-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 <Constant>DTDDECL</Constant> entries from <Filename>docbook.cat</Filename>.
-</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>
+</sect2>
-</Sect1>
+</sect1>
</Chapter>
projects / ghc-hetmet.git / blobdiff