[project @ 2000-01-14 19:14:26 by rrt]

SPJ's Windows installation notes added in.

diff --git a/ghc/docs/users_guide/installing.sgml b/ghc/docs/users_guide/installing.sgml
index a7181a3..16914d3 100644 (file)
--- a/ghc/docs/users_guide/installing.sgml
+++ b/ghc/docs/users_guide/installing.sgml
@@ -564,7 +564,50 @@ To run GHC comfortably, your machine should have at least 32M of memory.
 </Sect2>
 
 
-<Sect2><Title>Software required</Title>
+<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>
@@ -574,9 +617,139 @@ To run GHC comfortably, your machine should have at least 32M of memory.
 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.
+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>
@@ -665,8 +838,7 @@ Download a GHC distribution:
 
 <ListItem>
 <Para>
-Packaged up using an installer that should be familiar-looking to
-Windows users. Unpack and double click on <Filename>setup.exe</Filename>.
+(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>