<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
+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
</Para>
<Para>
-Binary distributions come in ``bundles,'' one bundle per file called
+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:
</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>
<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>
<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>
+% gunzip < happy-x.xx-sun-sparc-sunos4.tar.gz | tar xvf -</Screen>
</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
</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.
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>
<Para>
<IndexTerm><Primary>bundles, binary</Primary></IndexTerm>
-There are plenty of ``non-basic'' GHC bundles. The files for them are
+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:
<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>
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>
</Para>
<Para>
-For more information on how to ``drive'' GHC, either do <Literal>ghc -help</Literal> or
+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).
<Sect1><Title>Installing on Windows</Title>
<Para>
-Getting the Glasgow Haskell Compiler(GHC) to run on Windows95/98 or
+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
<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,
+Much of the Unixy stuff below involves setting environment variables.
+This section summarises how to set these variables on a Windows machine, in
+case you don't know alread.y
+On WinNT/Win2k, to edit your <Constant>PATH</Constant> variable (for example),
do the following:
</Para>
</ItemizedList>
<Para>
-Some environment variables are ``user variables'' and
-some are ``system variables''. I'm not sure of the difference
+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>
<Sect2 id="sec-required"><Title>Software required</Title>
-<VariableList>
-<VarListEntry>
-<Term>The cygwin toolchain (beta20.1)</Term>
-<ListItem>
+<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 (beta20.1)</Title>
+
<Para>
GHC depends at the moment on the cygwin tools to operate, which
dresses up the Win32 environment into something more UNIX-like.
<ListItem>
<Para>
-Add the two <Filename>bin</Filename> directories to your <Constant>PATH</Constant>.
+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>. 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>
-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).
+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>
-<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>
+</ItemizedList>
-<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.
+The following environment variables must be set:
</Para>
-</ListItem>
-<ListItem>
<Para>
-Set your <Constant>SHELL</Constant> user environment variable to <Filename>c:/bin/sh</Filename>.
-</Para>
-</ListItem>
+<InformalTable>
+<TGroup cols="2">
+<ColSpec Align="Left" Colsep="0">
+<ColSpec Align="Left" Colsep="0">
+<TBody>
-<ListItem>
-<Para>
-Set your <Filename>HOME</Filename> user environment variable to point to your
-home directory. This is where, for example,
+<Row>
+<Entry><Constant>PATH</Constant></Entry>
+<Entry>System</Entry>
+<Entry><Para>
+Add <Filename>C:\cygnus\cygwin-b20\H-i586-cygwin32\bin</Filename>.
+<Command>bash</Command> needs this, and when it is invoked from <Filename>/bin</Filename> it can't
+find it. <Filename>c:/bin</Filename> and <Filename>c:/usr/local/bin</Filename> should also be added.
+</Para></Entry>
+</Row>
+
+<Row>
+<Entry><Constant>SHELL</Constant></Entry>
+<Entry>User</Entry>
+<Entry><Para>
+<Filename>c:/bin/sh</Filename>.
+</Para></Entry>
+</Row>
+
+<Row>
+<Entry><Constant>HOME</Constant></Entry>
+<Entry>User</Entry>
+<Entry><Para>
+Set 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
+</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>
-
+</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:/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><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 werid messages
+when you invoke GHC, such as:
<Screen>
-/c: /c: No such file or directory
-</Screen>
-</ListItem>
+does not exist
+Action: openFile
+Reason: file does not exist /tmp/ghc11068.cpp</Screen>
+We think this is due to a bug in Cygwin.
+</Para></Entry>
+</Row>
+</TBody>
-<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.
+</TGroup>
+</InformalTable>
</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>
+</Sect3>
-</ItemizedList>
-</ListItem>
-</VarListEntry>
+<Sect3><Title>Perl5</Title>
-<VarListEntry>
-<Term>Perl5</Term>
-<ListItem><Para>
+<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>
+</Sect3> <!-- Perl -->
-<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> <!-- Reqd software -->
<Sect2><Title>Installing GHC</Title>
</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>
..
bash$ ./main
Hello, world!
-bash$
-</Screen>
+bash$ </Screen>
<Para>
OK, assuming that worked, you're all set. Go forth and write useful
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>
+bash$ </Screen>
<Para>
or
<Screen>
bash$ /ghc/ghc-4.05/bin/ghc-4.05 main.hs
Program too big fit into memory under NT
-bash$
-</Screen>
+bash$ </Screen>
</Question>
<Answer>
bin/ghc-4.xx -- where xx is the minor release number
bin/stat2resid
bin/hstags
-lib/mkdependHS
-</Screen>
+lib/mkdependHS</Screen>
<Para>
For each of these files, you need to edit the first line from instead
<Question>
<Para>
-<Function>System.getArgs</Function> always return the empty list, i.e. the following program always prints <Screen>"[]"</Screen>:
+<Function>System.getArgs</Function> always return the empty list, i.e. the following program always prints “<Literal>[]</Literal>”:
</Para>
<ProgramListing>
</Sect1>
+
+<Sect1>
+<Title>Building the documentation</Title>
+
+<Para>
+This is a slightly sore point at the moment, because the GHC team has been unable to strike a good balance between having a documentation system that is easy to maintain and one that is widely available. We use the DocBook DTD, which is widely used; however, shrink-wrapped distributions of DocBook are few and far between, and getting it to work out of the box is a nightmare. We settled on the Cygnus DocBook tools; however, these are only available as Red Hat RPMs, and hence at the moment the documentation can only be built on systems which can use RPMs (i.e. most versions of Linux). Sorry about that. We will probably add pre-built documentation to future source distributions (it's already in binary distributions, of course) until the situation is sorted out (either we bite the bullet and have our own version of the DocBook tools, or a more portable distribution is made available).
+</Para>
+
+<Para>
+See the Building Guide for details of what to install to get the DocBook tools and how to build the documentation (it's done by the build system, but just isn't part of a normal build).
+</Para>
+
+</Sect1>
+
</Chapter>
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: sgml ***
+ ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
+ ;;; End: ***
+ -->
projects / ghc-hetmet.git / blobdiff