[project @ 2004-05-05 14:10:07 by simonpj]

[ghc-hetmet.git] / docs / building / building.sgml
diff --git a/docs/building/building.sgml b/docs/building/building.sgml

index 3df0893..0e2b254 100644 (file)
--- a/docs/building/building.sgml
+++ b/docs/building/building.sgml
@@ -58,7 +58,7 @@
            the parser specifications.  If you don't want to alter the
            parser then this saves you having to find and install
            <command>happy</command>. You will still need a working
            the parser specifications.  If you don't want to alter the
            parser then this saves you having to find and install
            <command>happy</command>. You will still need a working
-          version of GHC (preferably version 4.08+) on your machine in
+          version of GHC (version 5.x or later) on your machine in
            order to compile (most of) the sources, however.</para>
         </listitem>
        </varlistentry>
            order to compile (most of) the sources, however.</para>
         </listitem>
        </varlistentry>
@@ -107,7 +107,7 @@
      remember is that most mistakes can be undone, but if there's
      anything you're not sure about feel free to bug the local CVS
      meister (namely Jeff Lewis
      remember is that most mistakes can be undone, but if there's
      anything you're not sure about feel free to bug the local CVS
      meister (namely Jeff Lewis
-    <email>jlewis@galconn.com</email>). </para>
+    <email>jlewis@galois.com</email>). </para>
  
      <sect2 id="cvs-access">
        <title>Getting access to the CVS Repository</title>
  
      <sect2 id="cvs-access">
        <title>Getting access to the CVS Repository</title>
@@ -137,6 +137,12 @@
           <listitem>
             <para>Set your <literal>$CVSROOT</literal> environment variable to
              <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
           <listitem>
             <para>Set your <literal>$CVSROOT</literal> environment variable to
              <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
+           <para>If you set <literal>$CVSROOT</literal> in a shell script, be sure not to
+             have any trailing spaces on that line, otherwise CVS will respond with 
+             a perplexing message like
+             <programlisting>
+               /cvs : no such repository
+         </programlisting></para>
           </listitem>
           <listitem>
              <para>Run the command</para>
           </listitem>
           <listitem>
              <para>Run the command</para>
@@ -240,30 +246,16 @@
  
  
         <para>
  
  
         <para>
-       [Windows users.] The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
-       seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
-       they ask for a password).  To solve this, start up <filename>cmd.exe</filename> 
-       and run it as follows:
-       <Screen>
-       c:\tmp> set CYGWIN32=tty
-       c:\tmp> c:/user/local/bin/ssh-keygen1
-       </Screen> </para>
+       <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"> about <command>ssh</command> wrinkles!</emphasis>
+         </para>
+
  
  
-           <para>[Windows users.] To protect your
-            <literal>.ssh</literal> from access by anyone else,
-            right-click your <literal>.ssh</literal> directory, and
-            select <literal>Properties</literal>.  If you are not on
-            the access control list, add yourself, and give yourself
-            full permissions (the second panel).  Remove everyone else
-            from the access control list.  Don't leave them there but
-            deny them access, because 'they' may be a list that
-            includes you!</para>
           </listitem>
  
           <listitem>
             <para>Send a message to to the CVS repository
              administrator (currently Jeff Lewis
           </listitem>
  
           <listitem>
             <para>Send a message to to the CVS repository
              administrator (currently Jeff Lewis
-            <email>jeff@galconn.com</email>), containing:</para>
+            <email>jeff@galois.com</email>), containing:</para>
             <itemizedlist>
               <listitem>
                 <para>Your desired user-name.</para>
             <itemizedlist>
               <listitem>
                 <para>Your desired user-name.</para>
@@ -446,6 +438,10 @@ setsockopt IPTOS_THROUGHPUT: Invalid argument
            <literal>hslibs</literal> and <literal>libraries</literal>
            modules (for a full list of the projects available, see
            <xref linkend="projects">).</para>
            <literal>hslibs</literal> and <literal>libraries</literal>
            modules (for a full list of the projects available, see
            <xref linkend="projects">).</para>
+
+         <para>Remember that if you do not have
+          <literal>happy</literal> and/or <literal>Alex</literal>
+          installed, you need to check them out as well.</para>
         </listitem>
        </itemizedlist>
      </sect2>
         </listitem>
        </itemizedlist>
      </sect2>
@@ -481,7 +477,14 @@ $ cvs diff
            you the results.</para>
         </listitem>
  
            you the results.</para>
         </listitem>
  
-      <listitem>
+       <listitem>
+         <para>If you changed something in the 
+          <literal>fptools/libraries</literal> subdirectories, also run
+          <literal>make html</literal> to check if the documentation can
+          be generated successfully, too.</para>
+       </listitem>
+
+       <listitem>
           <para>Before checking in a change, you need to update your
            source tree:</para>
  
           <para>Before checking in a change, you need to update your
            source tree:</para>
  
@@ -564,17 +567,25 @@ $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory
        major cause of headaches. </para>
  
        <para>So, to avoid a lot of hassle, follow this recipe for
        major cause of headaches. </para>
  
        <para>So, to avoid a lot of hassle, follow this recipe for
-      updating your tree: </para>
+      updating your tree:</para>
  
  <screen>
  $ cd fptools
  
  <screen>
  $ cd fptools
-$ cvs update -Pd 2&gt;&amp;1 | tee log</screen>
+$ cvs update -P 2&gt;&amp;1 | tee log</screen>
  
        <para>Look at the log file, and fix any conflicts (denoted by a
  
        <para>Look at the log file, and fix any conflicts (denoted by a
-      <quote>C</quote> in the first column). If you're using multiple
-      build trees, then for every build tree you have pointing at this
-      source tree, you need to update the links in case any new files
-      have appeared: </para>
+      <quote>C</quote> in the first column).  New directories may have
+      appeared in the repository; CVS doesn't check these out by
+      default, so to get new directories you have to explicitly do
+<screen>
+$ cvs update -d</screen>
+      in each project subdirectory.  Don't do this at the top level,
+      because then <emphasis>all</emphasis> the projects will be
+      checked out.</para>
+
+      <para>If you're using multiple build trees, then for every build
+      tree you have pointing at this source tree, you need to update
+      the links in case any new files have appeared: </para>
  
  <screen>
  $ cd <replaceable>build-tree</replaceable>
  
  <screen>
  $ cd <replaceable>build-tree</replaceable>
@@ -715,6 +726,17 @@ $ cvs checkout nofib/spectral
  
      <variablelist>
        <varlistentry>
  
      <variablelist>
        <varlistentry>
+       <term><literal>alex</literal></term>
+       <indexterm><primary><literal>alex</literal></primary>
+       <secondary>project</secondary></indexterm>
+       <listitem>
+         <para>The <ulink
+         url="http://www.haskell.org/alex/">Alex</ulink> lexical
+         analyser generator for Haskell.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><literal>ghc</literal></term>
         <indexterm><primary><literal>ghc</literal></primary>
         <secondary>project</secondary></indexterm>
         <term><literal>ghc</literal></term>
         <indexterm><primary><literal>ghc</literal></primary>
         <secondary>project</secondary></indexterm>
@@ -736,11 +758,11 @@ $ cvs checkout nofib/spectral
        </varlistentry>
  
        <varlistentry>
        </varlistentry>
  
        <varlistentry>
-       <term><literal>green-card</literal></term>
-       <indexterm><primary><literal>green-card</literal></primary><secondary>project</secondary></indexterm>
+       <term><literal>greencard</literal></term>
+       <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
         <listitem>
           <para>The <ulink
         <listitem>
           <para>The <ulink
-         url="http://www.haskell.org/greencard/">Green Card</ulink>
+         url="http://www.haskell.org/greencard/">GreenCard</ulink>
           system for generating Haskell foreign function
           interfaces.</para>
         </listitem>
           system for generating Haskell foreign function
           interfaces.</para>
         </listitem>
@@ -984,12 +1006,21 @@ $ cvs checkout nofib/spectral
           <term>sparc-sun-solaris2</term>
           <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
           <listitem>
           <term>sparc-sun-solaris2</term>
           <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
           <listitem>
-           <para>Fully supported (at least for Solaris 2.7),
+           <para>Fully supported (at least for Solaris 2.7 and 2.6),
             including native-code generator.</para>
           </listitem>
         </varlistentry>
  
         <varlistentry>
             including native-code generator.</para>
           </listitem>
         </varlistentry>
  
         <varlistentry>
+         <term>sparc-unknown-openbsd</term>
+         <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
+         <listitem>
+           <para>Supported, including native-code generator. The
+           same should also be true of NetBSD</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
           <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
           <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
           <listitem>
           <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
           <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
           <listitem>
@@ -1039,8 +1070,7 @@ $ cvs checkout nofib/spectral
         </varlistentry>
  
         <varlistentry>
         </varlistentry>
  
         <varlistentry>
-         <term>i386-unknown-netbsd (PCs running NetBSD and
-           OpenBSD)</term>
+         <term>i386-unknown-netbsd (PCs running NetBSD)</term>
             <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
           <listitem>
             <para>Will require some minor porting effort, but should
             <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
           <listitem>
             <para>Will require some minor porting effort, but should
@@ -1064,12 +1094,31 @@ $ cvs checkout nofib/spectral
           <term>ia64-unknown-linux</term>
           <indexterm><primary>ia64-unknown-linux</primary></indexterm>
           <listitem>
           <term>ia64-unknown-linux</term>
           <indexterm><primary>ia64-unknown-linux</primary></indexterm>
           <listitem>
+           <para>Supported, except there is no native code
+           generator.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term>x86_64-unknown-linux</term>
+         <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
+         <listitem>
             <para>GHC currently works unregisterised.  A registerised
             port is in progress.</para>
           </listitem>
         </varlistentry>
  
         <varlistentry>
             <para>GHC currently works unregisterised.  A registerised
             port is in progress.</para>
           </listitem>
         </varlistentry>
  
         <varlistentry>
+         <term>amd64-unknown-openbsd</term>
+         <indexterm><primary>amd64-unknown-linux</primary></indexterm>
+         <listitem>
+            <para>(This is the same as x86_64-unknown-openbsd). GHC
+                currently works unregisterised.  A registerised port is in
+                progress.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
           <term>mips-sgi-irix5</term>
           <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
           <listitem>
           <term>mips-sgi-irix5</term>
           <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
           <listitem>
@@ -1082,6 +1131,14 @@ $ cvs checkout nofib/spectral
         </varlistentry>
  
         <varlistentry>
         </varlistentry>
  
         <varlistentry>
+         <term>mips64-sgi-irix6</term>
+         <indexterm><primary>mips-sgi-irix6</primary></indexterm>
+         <listitem>
+           <para>GHC currently works unregisterised.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
           <term>powerpc-ibm-aix</term>
           <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
           <listitem>
           <term>powerpc-ibm-aix</term>
           <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
           <listitem>
@@ -1096,8 +1153,8 @@ $ cvs checkout nofib/spectral
           <term>powerpc-apple-darwin</term>
           <indexterm><primary>powerpc-apple-darwin</primary></indexterm> 
           <listitem>
           <term>powerpc-apple-darwin</term>
           <indexterm><primary>powerpc-apple-darwin</primary></indexterm> 
           <listitem>
-           <para>Supported registerised.  No native code
-           generator.</para>
+           <para>Supported registerised.  Native code generator is
+           almost working.</para>
           </listitem>
         </varlistentry>
  
           </listitem>
         </varlistentry>
  
@@ -1195,9 +1252,12 @@ $ cvs checkout nofib/spectral
            <command>egcs</command>) have varying degrees of stability
            depending on the platform.</para>
  
            <command>egcs</command>) have varying degrees of stability
            depending on the platform.</para>
  
+         <para>GCC 3.2 is currently known to have problems building
+         GHC on Sparc, but is stable on x86.</para>
+         
           <para>If your GCC dies with &ldquo;internal error&rdquo; on
            some GHC source file, please let us know, so we can report
           <para>If your GCC dies with &ldquo;internal error&rdquo; on
            some GHC source file, please let us know, so we can report
-          it and get things improved.  (Exception: on iX86
+          it and get things improved.  (Exception: on x86
            boxes&mdash;you may need to fiddle with GHC's
            <option>-monly-N-regs</option> option; see the User's
            Guide)</para>
            boxes&mdash;you may need to fiddle with GHC's
            <option>-monly-N-regs</option> option; see the User's
            Guide)</para>
@@ -1226,7 +1286,7 @@ $ cvs checkout nofib/spectral
            (<literal>fptools/happy</literal>).  It can be built from
            source, but bear in mind that you'll need GHC installed in
            order to build it.  To avoid the chicken/egg problem,
            (<literal>fptools/happy</literal>).  It can be built from
            source, but bear in mind that you'll need GHC installed in
            order to build it.  To avoid the chicken/egg problem,
-          install a binary distribtion of either Happy or GHC to get
+          install a binary distribution of either Happy or GHC to get
            started.  Happy distributions are available from <ulink
            url="http://www.haskell.org/happy/">Happy's Web
            Page</ulink>.</para>
            started.  Happy distributions are available from <ulink
            url="http://www.haskell.org/happy/">Happy's Web
            Page</ulink>.</para>
@@ -1234,19 +1294,37 @@ $ cvs checkout nofib/spectral
        </varlistentry>
  
        <varlistentry>
        </varlistentry>
  
        <varlistentry>
-       <term>Autoconf</term>
-       <indexterm><primary>pre-supposed: Autoconf</primary></indexterm>
-       <indexterm><primary>Autoconf, pre-supposed</primary></indexterm>
+       <term>Alex</term>
+       <indexterm><primary>Alex</primary></indexterm>
+       <listitem>
+         <para>Alex is a lexical-analyser generator for Haskell,
+         which GHC uses to generate its lexer.  Like Happy, Alex is
+         written in Haskell and is a project in the CVS repository.
+         Alex distributions are available from <ulink
+         url="http://www.haskell.org/alex/">Alex's Web
+         Page</ulink>.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>autoconf</term>
+       <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
+       <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
         <listitem>
         <listitem>
-         <para>GNU Autoconf is needed if you intend to build from the
+         <para>GNU autoconf is needed if you intend to build from the
            CVS sources, it is <emphasis>not</emphasis> needed if you
            just intend to build a standard source distribution.</para>
  
            CVS sources, it is <emphasis>not</emphasis> needed if you
            just intend to build a standard source distribution.</para>
  
-         <para>Autoconf builds the <command>configure</command>
-          script from <filename>configure.in</filename> and
-          <filename>aclocal.m4</filename>.  If you modify either of
-          these files, you'll need <command>autoconf</command> to
-          rebuild <filename>configure</filename>.</para>
+         <para>Version 2.52 or later of the autoconf package is required.
+         NB. version 2.13 will no longer work, as of GHC version
+         6.1.</para>
+
+         <para><command>autoreconf</command> (from the autoconf package)
+          recursively builds <command>configure</command> scripts from
+          the corresponding <filename>configure.ac</filename> and
+          <filename>aclocal.m4</filename> files.  If you modify one of
+          the latter files, you'll need <command>autoreconf</command> to
+          rebuild the corresponding <filename>configure</filename>.</para>
         </listitem>
        </varlistentry>
  
         </listitem>
        </varlistentry>
  
@@ -1283,7 +1361,7 @@ $ cvs checkout nofib/spectral
           <listitem>
             <para>PVM is the Parallel Virtual Machine on which
              Parallel Haskell programs run.  (You only need this if you
           <listitem>
             <para>PVM is the Parallel Virtual Machine on which
              Parallel Haskell programs run.  (You only need this if you
-            plan to run Parallel Haskell.  Concurent Haskell, which
+            plan to run Parallel Haskell.  Concurrent Haskell, which
              runs concurrent threads on a uniprocessor doesn't need
              it.)  Underneath PVM, you can have (for example) a network
              of workstations (slow) or a multiprocessor box
              runs concurrent threads on a uniprocessor doesn't need
              it.)  Underneath PVM, you can have (for example) a network
              of workstations (slow) or a multiprocessor box
@@ -1366,7 +1444,8 @@ $ cvs checkout nofib/spectral
        want a completely standard build, then the following should
        work:</para>
  
        want a completely standard build, then the following should
        work:</para>
  
-<screen>$ ./configure
+<screen>$ autoreconf
+$ ./configure
  $ make
  $ make install
  </screen>
  $ make
  $ make install
  </screen>
@@ -1400,7 +1479,7 @@ $ make install
         </listitem>
  
         <listitem>
         </listitem>
  
         <listitem>
-         <para><filename>configure.in</filename>,
+         <para><filename>configure.ac</filename>,
            <filename>config.sub</filename>,
            <filename>config.guess</filename>: these files support the
            configuration process.</para>
            <filename>config.sub</filename>,
            <filename>config.guess</filename>: these files support the
            configuration process.</para>
@@ -1423,7 +1502,7 @@ $ make install
        only one project (<literal>happy</literal>, say), you must have
        a source tree whose root directory contains
        <filename>Makefile</filename>, <filename>mk/</filename>,
        only one project (<literal>happy</literal>, say), you must have
        a source tree whose root directory contains
        <filename>Makefile</filename>, <filename>mk/</filename>,
-      <filename>configure.in</filename>, and the project(s) you want
+      <filename>configure.ac</filename>, and the project(s) you want
        (<filename>happy/</filename> in this case).  You cannot get by
        with just the <filename>happy/</filename> directory.</para>
      </sect2>
        (<filename>happy/</filename> in this case).  You cannot get by
        with just the <filename>happy/</filename> directory.</para>
      </sect2>
@@ -1537,26 +1616,32 @@ $ make install
  
             <para>Change directory to
              <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant> and
  
             <para>Change directory to
              <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant> and
-            issue the command
-            <command>autoconf</command><indexterm><primary>autoconf</primary></indexterm>
-            (with no arguments). This GNU program converts
-            <filename><constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>/configure.in</filename>
+            issue the command</para>
+<ProgramListing>
+autoreconf
+</ProgramListing>
+            <indexterm><primary>autoreconf</primary></indexterm>
+            <para>(with no arguments). This GNU program (recursively) converts
+            <filename><constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>/configure.ac</filename> and
+            <filename><constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>/aclocal.m4</filename>
              to a shell script called
              <filename><constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>/configure</filename>.
              to a shell script called
              <filename><constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>/configure</filename>.
+             If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
+             then delete the latter and try again.  Note that you must use <command>autoreconf</command>,
+             and not the old <command>autoconf</command>!  If you erroneously use the latter, you'll get 
+             a message like "No rule to make target 'mk/config.h.in'".
              </para>
  
              </para>
  
-           <para>Some projects, including GHC, have their own
-            configure script.  If there's an
-            <constant>&dollar;(FPTOOLS&lowbar;TOP)/&lt;project&gt;/configure.in</constant>,
-            then you need to run <command>autoconf</command> in that
-            directory too.</para>
-
-           <para>Both these steps are completely
-            platform-independent; they just mean that the
-            human-written file (<filename>configure.in</filename>) can
-            be short, although the resulting shell script,
-            <command>configure</command>, and
-            <filename>mk/config.h.in</filename>, are long.</para>
+           <para>Some projects, including GHC, have their own configure script.
+            <command>autoreconf</command> takes care of that, too, so all you have
+             to do is calling <command>autoreconf</command> in the top-level directory
+            <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>.</para>
+
+           <para>These steps are completely platform-independent; they just mean
+            that the human-written files (<filename>configure.ac</filename> and
+            <filename>aclocal.m4</filename>) can be short, although the resulting
+            files (the <command>configure</command> shell scripts and the C header
+            template <filename>mk/config.h.in</filename>) are long.</para>
           </listitem>
         </varlistentry>
  
           </listitem>
         </varlistentry>
  
@@ -1574,7 +1659,7 @@ $ make install
              round your computer working out what architecture it has,
              what operating system, whether it has the
              <Function>vfork</Function> system call, where
              round your computer working out what architecture it has,
              what operating system, whether it has the
              <Function>vfork</Function> system call, where
-            <command>yacc</command> is kept, whether
+            <command>tar</command> is kept, whether
              <command>gcc</command> is available, where various obscure
              <literal>&num;include</literal> files are, whether it's a
              leap year, and what the systems manager had for lunch.  It
              <command>gcc</command> is available, where various obscure
              <literal>&num;include</literal> files are, whether it's a
              leap year, and what the systems manager had for lunch.  It
@@ -1660,13 +1745,6 @@ $ make install
                 </listitem>
               </varlistentry>
             </variablelist>
                 </listitem>
               </varlistentry>
             </variablelist>
-           
-           <para><command>configure</command> caches the results of
-            its run in <filename>config.cache</filename>.  Quite often
-            you don't want that; you're running
-            <command>configure</command> a second time because
-            something has changed.  In that case, simply delete
-            <filename>config.cache</filename>.</para>
           </listitem>
         </varlistentry>
         
           </listitem>
         </varlistentry>
         
@@ -1711,6 +1789,9 @@ $ make install
        includes <filename>build.mk</filename> after
        <filename>config.mk</filename>.)</para>
  
        includes <filename>build.mk</filename> after
        <filename>config.mk</filename>.)</para>
  
+     <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
+     that can serve as a starting point for your <filename>build.mk</filename>.</para>
+
        <para>For example, <filename>config.mk.in</filename> contains
        the definition:</para>
  
        <para>For example, <filename>config.mk.in</filename> contains
        the definition:</para>
  
@@ -1751,17 +1832,17 @@ GhcHcOpts=-DDEBUG -Rghc-timing
        For example, there's a line that says:</para>
  
  <ProgramListing>
        For example, there's a line that says:</para>
  
  <ProgramListing>
-YACC = @YaccCmd@
+TAR = @TarCmd@
  </ProgramListing>
  
  </ProgramListing>
  
-      <para>This defines the Make variables <constant>YACC</constant>
-      to the pathname for a <command>yacc</command> that
+      <para>This defines the Make variables <constant>TAR</constant>
+      to the pathname for a <command>tar</command> that
        <command>configure</command> finds somewhere.  If you have your
        <command>configure</command> finds somewhere.  If you have your
-      own pet <command>yacc</command> you want to use instead, that's
+      own pet <command>tar</command> you want to use instead, that's
        fine. Just add this line to <filename>mk/build.mk</filename>:</para>
  
  <ProgramListing>
        fine. Just add this line to <filename>mk/build.mk</filename>:</para>
  
  <ProgramListing>
-YACC = myyacc
+TAR = mytar
  </ProgramListing>
  
        <para>You do not <emphasis>have</emphasis> to have a
  </ProgramListing>
  
        <para>You do not <emphasis>have</emphasis> to have a
@@ -1828,21 +1909,13 @@ $ cd /scratch/joe-bloggs/myfptools-sun4
           <para>Prepare for system configuration:</para>
  
  <programlisting>
           <para>Prepare for system configuration:</para>
  
  <programlisting>
-$ autoconf
+$ autoreconf
  </programlisting>
  
           <para>(You can skip this step if you are starting from a
            source distribution, and you already have
            <filename>configure</filename> and
            <filename>mk/config.h.in</filename>.)</para>
  </programlisting>
  
           <para>(You can skip this step if you are starting from a
            source distribution, and you already have
            <filename>configure</filename> and
            <filename>mk/config.h.in</filename>.)</para>
-
-         <para>Some projects, including GHC itself, have their own
-         configure scripts, so it is necessary to run autoconf again
-         in the appropriate subdirectories. eg:</para>
-
-<programlisting>
-$ (cd ghc; autoconf)
-</programlisting>
         </listitem>
  
         <listitem>
         </listitem>
  
         <listitem>
@@ -2197,13 +2270,14 @@ Foo.o : Baz.hi
  
        <para> Do <emphasis>NOT</emphasis> use
        <filename>ghc/compiler/ghc</filename>, or
  
        <para> Do <emphasis>NOT</emphasis> use
        <filename>ghc/compiler/ghc</filename>, or
-      <filename>ghc/compiler/ghc-5.xx</filename>, as these are the
+      <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
        scripts intended for installation, and contain hard-wired paths
        to the installed libraries, rather than the libraries in the
        build tree.</para>
  
        <para>Happy can similarly be run from the build tree, using
        scripts intended for installation, and contain hard-wired paths
        to the installed libraries, rather than the libraries in the
        build tree.</para>
  
        <para>Happy can similarly be run from the build tree, using
-      <filename>happy/src/happy-inplace</filename>.</para>
+      <filename>happy/src/happy-inplace</filename>, and similarly for
+      Alex and Haddock.</para>
      </sect2>
  
      <sect2>
      </sect2>
  
      <sect2>
@@ -3583,17 +3657,16 @@ $ make install-docs
        target machine, and compiling them using gcc to get a working
        GHC.</para>
  
        target machine, and compiling them using gcc to get a working
        GHC.</para>
  
-      <para><emphasis>NOTE: GHC version 5.xx is significantly harder
-      to bootstrap from C than previous versions.  We recommend
-      starting from version 4.08.2 if you need to bootstrap in this
-      way.</emphasis></para>
+      <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
+      from C.  We recommend using GHC 6.0.1 or
+      later.</emphasis></para>
  
  
-      <para>HC files are architecture-dependent (but not
-      OS-dependent), so you have to get a set that were generated on
-      similar hardware.  There may be some supplied on the GHC
-      download page, otherwise you'll have to compile some up
-      yourself, or start from <emphasis>unregisterised</emphasis> HC
-      files - see <xref linkend="unregisterised-porting">.</para>
+      <para>HC files are platform-dependent, so you have to get a set
+      that were generated on similar hardware.  There may be some
+      supplied on the GHC download page, otherwise you'll have to
+      compile some up yourself, or start from
+      <emphasis>unregisterised</emphasis> HC files - see <xref
+      linkend="unregisterised-porting">.</para>
  
        <para>The following steps should result in a working GHC build
        with full libraries:</para>
  
        <para>The following steps should result in a working GHC build
        with full libraries:</para>
@@ -3677,65 +3750,239 @@ foo% make install
        since unregisterised compilation is usually just a step on the
        way to a full registerised port, we don't mind too much.</para>
  
        since unregisterised compilation is usually just a step on the
        way to a full registerised port, we don't mind too much.</para>
  
-      <sect3>
-       <title>Building an unregisterised port</title>
+      <para>Notes on GHC portability in general: we've tried to stick
+      to writing portable code in most parts of the system, so it
+      should compile on any POSIXish system with gcc, but in our
+      experience most systems differ from the standards in one way or
+      another.  Deal with any problems as they arise - if you get
+      stuck, ask the experts on
+      <email>glasgow-haskell-users@haskell.org</email>.</para>
         
         
-       <para>The first step is to get some unregisterised HC files.
-       Either (a)&nbsp;download them from the GHC site (if there are
-       some available for the right version of GHC), or
-       (b)&nbsp;build them yourself on any machine with a working
-       GHC.  If at all possible this should be a machine with the
-       same word size as the target.</para>
-
-       <para>There is a script available which should automate the
-       process of doing the 2-stage bootstrap necessary to get the
-       unregisterised HC files - it's available in <ulink
-       url="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/distrib/cross-port"><filename>fptools/distrib/cross-port</filename></ulink>
-       in CVS.</para>
-
-       <para>Now take these unregisterised HC files to the target
-       platform and bootstrap a compiler from them as per the
-       instructions in <xref linkend="sec-booting-from-hc">.  In
-       <filename>build.mk</filename>, you need to tell the build
-       system that the compiler you're building is
-       (a)&nbsp;unregisterised itself, and (b)&nbsp;builds
-       unregisterised binaries.  This varies depending on the GHC
-       version you're bootstraping:</para>
+      <para>Lots of useful information about the innards of GHC is
+      available in the <ulink
+      url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
+      Commentary</ulink>, which might be helpful if you run into some
+      code which needs tweaking for your system.</para>
  
  
-<programlisting>
-# build.mk for GHC 4.08.x
-GhcWithRegisterised=NO
-</programlisting>
+      <sect3>
+       <title>Cross-compiling to produce an unregisterised GHC</title>
+
+       <para>In this section, we explain how to bootstrap GHC on a
+       new platform, using unregisterised intermediate C files.  We
+       haven't put a great deal of effort into automating this
+       process, for two reasons: it is done very rarely, and the
+       process usually requires human intervention to cope with minor
+       porting issues anyway.</para>
+
+       <para>The following step-by-step instructions should result in
+       a fully working, albeit unregisterised, GHC.  Firstly, you
+       need a machine that already has a working GHC (we'll call this
+       the <firstterm>host</firstterm> machine), in order to
+       cross-compile the intermediate C files that we will use to
+       bootstrap the compiler on the <firstterm>target</firstterm>
+       machine.</para>
+
+       <itemizedlist>
+         <listitem>
+           <para>On the target machine:</para>
+
+         <itemizedlist>
+           <listitem>
+             <para>Unpack a source tree (preferably a released
+             version).  We will call the path to the root of this
+             tree <replaceable>T</replaceable>.</para>
+           </listitem>
+
+           <listitem>
+<screen>
+$ cd <replaceable>T</replaceable>
+$ ./configure --enable-hc-boot --enable-hc-boot-unregisterised
+</screen>
+
+             <para>You might need to update
+              <filename>configure.in</filename> to recognise the new
+              architecture, and re-generate
+              <filename>configure</filename> with
+              <literal>autoreconf</literal>.</para>
+           </listitem>
+  
+           <listitem>
+<screen>
+$ cd <replaceable>T</replaceable>/ghc/includes
+$ make config.h
+</screen>
+           </listitem>
+         </itemizedlist>
+         </listitem>
+
+         <listitem>
+           <para>On the host machine:</para>
+             
+         <itemizedlist>
+           <listitem>
+             <para>Unpack a source tree (same released version).  Call
+              this directory <replaceable>H</replaceable>.</para>
+           </listitem>
+ 
+           <listitem>
+<screen>
+$ cd <replaceable>H</replaceable>
+$ ./configure
+</screen>
+           </listitem>
+
+           <listitem>
+             <para>Create
+             <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
+             with the following contents:</para>
  
  <programlisting>
  
  <programlisting>
-# build.mk for GHC 5.xx
-GhcUnregisterised=YES
+GhcUnregisterised = YES
+GhcLibHcOpts = -O -H32m -keep-hc-files
+GhcLibWays =
+SplitObjs = NO
+GhcWithNativeCodeGen = NO
+GhcWithInterpreter = NO
+GhcStage1HcOpts = -O -H32m -fasm
+GhcStage2HcOpts = -O -fvia-C -keep-hc-files
  </programlisting>
  </programlisting>
+           </listitem>
  
  
-       <para>Version 5.xx only: use the option
-       <option>--enable-hc-boot-unregisterised</option> instead of
-       <option>--enable-hc-boot</option> when running
-       <filename>./configure</filename>.</para>
-
-       <para>The build may not go through cleanly.  We've tried to
-       stick to writing portable code in most parts of the compiler,
-       so it should compile on any POSIXish system with gcc, but in
-       our experience most systems differ from the standards in one
-       way or another.  Deal with any problems as they arise - if you
-       get stuck, ask the experts on
-       <email>glasgow-haskell-users@haskell.org</email>.</para>
-       
-       <para>Once you have the unregisterised compiler up and
-       running, you can use it to start a registerised port.  The
-       following sections describe the various parts of the system
-       that will need architecture-specific tweaks in order to get a
-       registerised build going.</para>
-
-       <para>Lots of useful information about the innards of GHC is
-       available in the <ulink
-       url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
-       Commentary</ulink>, which might be helpful if you run into
-       some code which needs tweaking for your system.</para>
+           <listitem>
+             <para>Edit
+             <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
+             <itemizedlist>
+               <listitem>
+                 <para>change <literal>TARGETPLATFORM</literal>
+                  appropriately, and set the variables involving
+                  <literal>TARGET</literal> to the correct values for
+                  the target platform.  This step is necessary because
+                  currently <literal>configure</literal> doesn't cope
+                  with specifying different values for the
+                  <literal>--host</literal> and
+                  <literal>--target</literal> flags.</para>
+               </listitem>
+               <listitem>
+                 <para>copy <literal>LeadingUnderscore</literal>
+                 setting from target.</para>
+               </listitem>
+             </itemizedlist>
+           </listitem>
+
+           <listitem>
+             <para>Copy
+             <filename><replaceable>T</replaceable>/ghc/includes/config.h</filename>
+             to
+             <filename><replaceable>H</replaceable>/ghc/includes</filename>.
+             Note that we are building on the host machine, using the
+             target machine's <literal>config.h</literal> file.  This
+             is so that the intermediate C files generated here will
+             be suitable for compiling on the target system.</para>
+
+           </listitem>
+
+             <listitem>
+               <para>Touch <literal>config.h</literal>, just to make
+               sure it doesn't get replaced during the build:</para>
+<screen>
+$ touch <replaceable>H</replaceable>/ghc/includes/config.h</screen>
+             </listitem>
+
+           <listitem>
+               <para>Now build the compiler:</para>
+<screen>
+$ cd <replaceable>H</replaceable>/glafp-utils && make boot && make
+$ cd <replaceable>H</replaceable>/ghc && make boot && make
+</screen>
+             <para>Don't worry if the build falls over in the RTS, we
+              don't need the RTS yet.</para>
+           </listitem>
+
+           <listitem>
+<screen>
+$ cd <replaceable>H</replaceable>/libraries
+$& make boot && make
+</screen>
+           </listitem>
+
+           <listitem>
+<screen>
+$ cd <replaceable>H</replaceable>/ghc
+$ make boot stage=2 && make stage=2
+</screen>
+           </listitem>
+           
+           <listitem>
+             <screen>
+$ cd <replaceable>H</replaceable>/ghc/utils
+$ make clean
+$ make -k HC=<replaceable>H</replaceable>/ghc/compiler/stage1/ghc-inplace \
+               EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
+</screen>
+           </listitem>
+           
+           <listitem>
+<screen>
+$ cd <replaceable>H</replaceable>
+$ make hc-file-bundle Project=Ghc
+</screen>
+           </listitem>
+
+           <listitem>
+             <para>copy
+             <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
+             to <filename><replaceable>T</replaceable>/..</filename>.</para>
+           </listitem>
+         </itemizedlist>
+         </listitem>
+
+         <listitem>
+           <para>On the target machine:</para>
+
+           <para>At this stage we simply need to bootstrap a compiler
+           from the intermediate C files we generated above.  The
+           process of bootstrapping from C files is automated by the
+           script in <literal>distrib/hc-build</literal>, and is
+           described in <xref linkend="sec-booting-from-hc">.</para>
+
+<screen>
+$ ./distrib/hc-build --enable-hc-boot-unregisterised
+</screen>
+
+           <para>However, since this is a bootstrap on a new machine,
+           the automated process might not run to completion the
+           first time.  For that reason, you might want to treat the
+           <literal>hc-build</literal> script as a list of
+           instructions to follow, rather than as a fully automated
+           script.  This way you'll be able to restart the process
+           part-way through if you need to fix anything on the
+           way.</para>
+
+           <para>Don't bother with running
+           <literal>make&nbsp;install</literal> in the newly
+           bootstrapped tree; just use the compiler in that tree to
+           build a fresh compiler from scratch, this time without
+           booting from C files.  Before doing this, you might want
+           to check that the bootstrapped compiler is generating
+           working binaries:</para>
+
+<screen>
+$ cat >hello.hs
+main = putStrLn "Hello World!\n"
+^D
+$ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
+$ ./hello
+Hello World!
+</screen>
+
+           <para>Once you have the unregisterised compiler up and
+           running, you can use it to start a registerised port.  The
+           following sections describe the various parts of the
+           system that will need architecture-specific tweaks in
+           order to get a registerised build going.</para>
+
+         </listitem>
+       </itemizedlist>
        </sect3>
  
        <sect3>
        </sect3>
  
        <sect3>
@@ -3862,10 +4109,13 @@ GhcUnregisterised=YES
         <para>To support GHCi, you need to port the dynamic linker
         (<filename>fptools/ghc/rts/Linker.c</filename>).  The linker
         currently supports the ELF and PEi386 object file formats - if
         <para>To support GHCi, you need to port the dynamic linker
         (<filename>fptools/ghc/rts/Linker.c</filename>).  The linker
         currently supports the ELF and PEi386 object file formats - if
-       your platform uses one of these then you probably don't have
-       to do anything except fiddle with the
-       <literal>#ifdef</literal>s at the top of
-       <filename>Linker.c</filename> to tell it about your OS.</para>
+       your platform uses one of these then things will be
+       significantly easier.  The majority of Unix platforms use the
+       ELF format these days.  Even so, there are some
+       machine-specific parts of the ELF linker: for example, the
+       code for resolving particular relocation types is
+       machine-specific, so some porting of this code to your
+       architecture will probaly be necessary.</para>
         
         <para>If your system uses a different object file format, then
         you have to write a linker &mdash; good luck!</para>
         
         <para>If your system uses a different object file format, then
         you have to write a linker &mdash; good luck!</para>
@@ -4062,24 +4312,19 @@ Workaround: don't put weird things in string args to <command>cpp</command> macr
  </sect1>
  
  
  </sect1>
  
  
-<Sect1 id="winbuild"><Title>Notes for building under Windows</Title>
-
+<Sect1 id="platforms"><Title>Platforms, scripts, and file names</Title>
  <para>
  <para>
-This section summarises how to get the utilities you need on your
-Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for
-installing and running GHC may be found in the user guide. In general,
-Win95/Win98 behave the same, and WinNT/Win2k behave the same.
-You should read the GHC installation guide sections on Windows (in the user
-guide) before continuing to read these notes.
+GHC is designed both to be built, and to run, on both Unix and Windows.  This flexibility
+gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
  </para>
  
  </para>
  
+<sect2 id="cygwin-and-mingw"><Title>Windows platforms: Cygwin, MSYS, and MinGW</Title>
  
  
-<sect2><Title>Cygwin and MinGW</Title>
-
-<para> The Windows situation for building GHC is rather confusing.  This section
+<para> The build system is built around Unix-y makefiles.  Because it's not native,
+the Windows situation for building GHC is particularly confusing.  This section
  tries to clarify, and to establish terminology.</para>
  
  tries to clarify, and to establish terminology.</para>
  
-<sect3 id="ghc-mingw"><title>GHC-mingw</title>
+<sect3 id="ghc-mingw"><title>MinGW</title>
  
  <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink> 
  is a collection of header
  
  <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink> 
  is a collection of header
@@ -4089,43 +4334,121 @@ current set of tools include GNU Compiler Collection (<command>gcc</command>), G
  Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
  other utilities. 
  </para>
  Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
  other utilities. 
  </para>
-<para>The GHC that we distribute includes, inside the distribution itself, the MinGW <command>gcc</command>,
-<command>as</command>, <command>ld</command>, and a bunch of input/output libraries.  
-GHC compiles Haskell to C (or to 
-assembly code), and then invokes these MinGW tools to generate an executable binary.
-The resulting binaries can run on any Win32 system.
+
+<para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
+Posix interface.  
  </para>
  </para>
-<para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
+</sect3>
+
+<sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>
+
+<para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
+or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
+<command>ls</command>, nor build-system stuff such as <command>make</command> and <command>cvs</command>.
+For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink> 
+and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:
+
+<itemizedlist>
+<listitem><para>
+Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
+compile code that has access to all of Posix.  The price is that the executables must be 
+dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
+that doesn't have Cygwin</emphasis>.  Worse, Cygwin is a moving target.  The name of the main DLL, <literal>cygwin1.dll</literal>
+does not change, but the implementation certainly does.  Even the interfaces to functions
+it exports seem to change occasionally. </para>
+</listitem>
+
+<listitem><para>
+MSYS is a fork of the Cygwin tree, so they
+are fundamentally similar.  However, MSYS is by design much smaller and simpler.  Access to the file system goes
+through fewer layers, so MSYS is quite a bit faster too.
+</para>
+
+<para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
+compile binaries that run with no DLL support, on any Win32 system.
+However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>, 
+<command>cvs</command>, <command>ssh</command> etc.  To get these, you have to download the 
+MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
+</para>
+<para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>, 
+<command>ssh</command> and so on),
+not by programs compiled under MSYS.
+</para></listitem>
+
+</itemizedlist>
+
+</para>
+</sect3>
+
+<sect3><title>Targeting MinGW</title>
  
  
-<para> The down-side of GHC-mingw is that the MinGW libraries do not support anything like the full
-Posix interface.  So programs compiled with GHC-mingw cannot import the (Haskell) Posix 
+<para>We want GHC to compile programs that work on any Win32 system.  Hence:
+<itemizedlist>
+<listitem><para>
+GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
+invokes the MinGW tools, not the Cygwin ones.  That means that the programs GHC compiles
+will work on any system, but it also means that the programs GHC compiles do not have access
+to all of Posix.  In particular, they cannot import the (Haskell) Posix 
  library; they have to do
  library; they have to do
-their input output using standard Haskell I/O libraries, or native Win32 bindings.
+their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
+<para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
+</listitem>
+
+<listitem><para>
+To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
+<command>as</command>, <command>ld</command>, and a bunch of input/output libraries.  
+</para></listitem>
+</itemizedlist>
+So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
+It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>, 
+that targets Cygwin instead.  The up-side of GHC-cygwin is
+that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
+<emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
+</para>
+
+<para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about 
+how GHC is <emphasis>built</emphasis>.  We use both MSYS and Cygwin as build environments for
+GHC; both work fine, though MSYS is rather lighter weight.</para>
+
+<para>In your build tree, you build a compiler called <Command>ghc-inplace</Command>.  It
+uses the <Command>gcc</Command> that you specify using the
+<option>--with-gcc</option> flag when you run
+<Command>configure</Command> (see below).
+The makefiles are careful to use <Command>ghc-inplace</Command> (not <Command>gcc</Command>)
+to compile any C files, so that it will in turn invoke the correct <Command>gcc</Command> rather that
+whatever one happens to be in your path.  However, the makefiles do use whatever <Command>ld</Command> 
+and <Command>ar</Command> happen to be in your path. This is a bit naughty, but (a) they are only
+used to glom together .o files into a bigger .o file, or a .a file, 
+so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
+Cygwin and MinGW use the same .o file format.  So its ok.
  </para>
  </sect3>
  
  </para>
  </sect3>
  
-<sect3 id="ghc-cygwin"><title>GHC-cygwin</title>
+<sect3><title> File names </title>
  
  
-<para>There <emphasis>is</emphasis> a way to get the full Posix interface, which is to use Cygwin.  
-<ulink url="http://www.cygwin.com">Cygwin</ulink> is a complete Unix simulation that runs on Win32.
-Cygwin comes with a shell, and all the usual Unix commands: <command>mv</command>, <command>rm</command>,
-<command>ls</command>, plus of course <command>gcc</command>, <command>ld</command> and so on.
-A C program compiled with the Cygwin <command>gcc</command> certainly can use all of Posix.
+<para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
+However:
+<itemizedlist>
+<listitem><para>
+MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
+<filename>/c/tmp/foo</filename> etc.  The exact mount table is given in the doc subdirectory of the MSYS distribution.
  </para>
  </para>
-<para>So why doesn't GHC use the Cygwin <command>gcc</command> and libraries?  Because
-Cygwin comes with a DLL <emphasis>that must be linked with every runnable Cygwin-compiled program</emphasis>.
-A program compiled by the Cygwin tools cannot run at all unless Cygwin is installed. 
-If GHC targeted Cygwin, users would have to install Cygwin just to run the Haskell programs
-that GHC compiled; and the Cygwin DLL would have to be in the DLL load path.
-Worse, Cygwin is a moving target.  The name of the main DLL, <literal>cygwin1.dll</literal>
-does not change, but the implementation certainly does.  Even the interfaces to functions
-it exports seem to change occasionally. So programs compiled by GHC might only run with
-particular versions of Cygwin.  All of this seems very undesirable.
+<para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
+directory.  If so, it just invokes it.  If not, it assumes the program is no an MSYS program, and walks over the command-line
+arguments changing MSYS paths into native-compatible paths.  It does this inside sub-arguments and inside quotes. For example,
+if you invoke
+<programlisting>
+   foogle -B/c/tmp/baz
+</programlisting>
+the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
+</para></listitem>
+
+<listitem><para>
+Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
  </para>
  </para>
-<para>
-Nevertheless, it is certainly possible to build a version of GHC that targets Cygwin;
-we will call that <emphasis>GHC-cygwin</emphasis>.  The up-side of GHC-cygwin is
-that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
+<para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
+</para></listitem>
+</itemizedlist>
  </para>
  </sect3>
  
  </para>
  </sect3>
  
@@ -4160,47 +4483,160 @@ So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp ma
  </para>
  </sect3>
  
  </para>
  </sect3>
  
-<sect3><title>Summary</title>
+</sect2>
  
  
-<para>Notice that "GHC-mingw" means "GHC that <emphasis>targets</emphasis> MinGW".  It says nothing about 
-how that GHC was <emphasis>built</emphasis>.  It is entirely possible to have a GHC-mingw that was built
-by compiling GHC's Haskell sources with a GHC-cygwin, or vice versa.</para>
+<sect2><title>Wrapper scripts</title>
  
  
-<para>We distribute only a GHC-mingw built by a GHC-mingw; supporting
-GHC-cygwin too is beyond our resources.  The GHC we distribute
-therefore does not require Cygwin to run, nor do the programs it
-compiles require Cygwin.</para>
+<para>
+Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
+For <emphasis>installed</emphasis> programs, the strategy depends on the platform.  We'll use
+GHC itself as an example:
+<itemizedlist>
+  <listitem> <para>
+  On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
+  paths to the front of the source file <filename>ghc.sh</filename>, 
+  that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
+  where to find its supporting files. 
+  </para> </listitem>
  
  
-<para>The instructions that follow describe how to build GHC-mingw. It is
-possible to build GHC-cygwin, but it's not a supported route, and the build system might
-be flaky.</para>
+  <listitem> <para>
+  On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
+  native Windows shell <command>cmd</command> (e.g. limits on the length
+   of the command line).  So instead we invoke the GHC binary directly, with no -B flag.
+  GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
+  and from that figures out where the supporting files are.
+  </para> </listitem>
+</itemizedlist>
+(You can find the layout of GHC's supporting files in the
+  section "Layout of installed files" of Section 2 of the GHC user guide.)
+</para>
+<para>
+Things work differently for <emphasis>in-place</emphasis> execution, where you want to
+execute a program that has just been built in a build tree. The difference is that the
+layout of the supporting files is different.
+In this case, whether on Windows or Unix, we always use a shell script. This works OK
+on Windows because the script is executed by MSYS or Cygwin, which don't have the
+shortcomings of the native Windows <command>cmd</command> shell.
+</para>
  
  
-<para>In your build tree, you build a compiler called <Command>ghc-inplace</Command>.  It
-uses the <Command>gcc</Command> that you specify using the
-<option>--with-gcc</option> flag when you run
-<Command>configure</Command> (see below).
-The makefiles are careful to use <Command>ghc-inplace</Command> (not <Command>gcc</Command>)
-to compile any C files, so that it will in turn invoke the right <Command>gcc</Command> rather that
-whatever one happens to be in your path.  However, the makefiles do use whatever <Command>ld</Command> 
-and <Command>ar</Command> happen to be in your path. This is a bit naughty, but (a) they are only
-used to glom together .o files into a bigger .o file, or a .a file, 
-so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
-Cygwin and Mingw use the same .o file format.  So its ok.
+</sect2>
+
+</sect1>
+
+<Sect1 id="winbuild"><Title>Instructions for building under Windows</Title>
+
+<para>
+This section gives detailed instructions for how to build 
+GHC from source on your Windows machine. Similar instructions for
+installing and running GHC may be found in the user guide. In general,
+Win95/Win98 behave the same, and WinNT/Win2k behave the same.
+</para>
+<para>
+Make sure you read the preceding section on platforms (<xref linkend="platforms">)
+before reading section.
+You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC, 
+but you do need one or the other to <emphasis>build</emphasis> GHC.</para>
+
+
+<Sect2 id=msys-install><Title>Installing and configuring MSYS</Title>
+
+<para>
+MSYS is a lightweight alternative to Cygwin.  
+You don't need MSYS to <emphasis>use</emphasis> GHC, 
+but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
+Here's how to install MSYS.
+<itemizedlist>
+<listitem><para>
+Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and 
+download the following (of course, the version numbers will differ):
+<itemizedlist>
+  <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
+  </para></listitem>
+  <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
+                   This provides <command>make</command>, <command>autoconf</command>, 
+                   <command>ssh</command>, <command>cvs</command> and probably more besides.
+  </para></listitem>
+</itemizedlist>
+Run both executables (in the order given above) to install them.  I put them in <literal>c:/msys</literal>
+</para></listitem>
+
+<listitem><para>
+Set the following environment variables
+<itemizedlist>
+  <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> to your path.  (Of course, the version number may differ.)
+  </para></listitem>
+
+  <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
+  This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
+  </para></listitem>  
+
+  <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
+  </para></listitem>
+
+  <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>.  Only necessary if
+             you are using CVS.
+  </para></listitem>
+
+  <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>.  (I'm not certain this is necessary for MSYS.)
+  </para></listitem>
+
+</itemizedlist>
+</para></listitem>
+
+<listitem><para>
+Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set.  It's a bad bug
+that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
+causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
+file has too-liberal permissinos.
+</para></listitem>
+
+</itemizedlist>
+</para>
+<para>Here are some points to bear in mind when using MSYS:
+<itemizedlist>
+<listitem> <para> MSYS does some kind of special magic to binaries stored in 
+<filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped
+to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>).
+Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories: 
+they fail in mysterious ways.  However, it's fine to put other binaries in <filename>/usr/local/bin</filename>,
+which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem>
+
+<listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost.
+</para></listitem>
+
+<listitem> <para>
+Win32 has a <command>find</command> command which is not the same as MSYS's find.
+You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
+before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant> 
+environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant> 
+variable.  You can always invoke <command>find</command> with an absolute path, or rename it.
+</para></listitem>
+
+<listitem> <para>
+MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal> 
+will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>).  Useful when you get a
+bzip'd dump.</para></listitem>
+
+</itemizedlist>
  </para>
  </para>
-</sect3>
  </sect2>
  
  <Sect2><Title>Installing and configuring Cygwin</Title>
  
  </sect2>
  
  <Sect2><Title>Installing and configuring Cygwin</Title>
  
-<para>You don't need Cygwin to <emphasis>use</emphasis> GHC, 
-but you do need it to <emphasis>build</emphasis> GHC.</para>
-
  <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
  The installation process is straightforward; we install it in <Filename>c:/cygwin</Filename>.
  <para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
  The installation process is straightforward; we install it in <Filename>c:/cygwin</Filename>.
-Both <command>cvs</command> and <command>ssh</command>
-come with Cygwin, but you'll need them, so make sure you select them when running
-the Cygwin installer.
-
+During the installation dialogue, make sure that you select all of the following:
+             <command>cvs</command>, 
+             <command>openssh</command>,
+             <command>autoconf</command>,
+             <command>binutils</command> (includes ld and (I think) ar),
+             <command>gcc</command>,
+             <command>flex</command>,
+             <command>make</command>.
+If you miss out any of these, strange things will happen to you.   To see thse packages, 
+click on the "View" button in the "Select Packages" 
+stage of Cygwin's installation dialogue, until the view says "Full".  The default view, which is
+"Category" isn't very helpful, and the "View" button is rather unobtrousive.
  </para>
  <para> Now set the following user environment variables:
  <itemizedlist>
  </para>
  <para> Now set the following user environment variables:
  <itemizedlist>
@@ -4220,7 +4656,7 @@ don't do this you get very weird messages when you type
  </listitem>
  
  <listitem><para> Set <constant>SHELL</constant> to
  </listitem>
  
  <listitem><para> Set <constant>SHELL</constant> to
-<Filename>c:/cygwin/bin/sh</Filename>. When you invoke a shell in Emacs, this
+<Filename>c:/cygwin/bin/bash</Filename>. When you invoke a shell in Emacs, this
  <constant>SHELL</constant> is what you get.
  </para></listitem>
  
  <constant>SHELL</constant> is what you get.
  </para></listitem>
  
@@ -4237,8 +4673,24 @@ There are a few other things to do:
  <itemizedlist>
  <listitem>
  <para>
  <itemizedlist>
  <listitem>
  <para>
+By default, cygwin provides the command shell <filename>ash</filename>
+as <filename>sh.exe</filename>. We have often seen build-system problems that 
+turn out to be due to bugs in <filename>ash</filename>
+(to do with quoting
+and length of command lines).  On the other hand <filename>bash</filename> seems
+to be rock solid.
+So, in <filename>cygwin/bin</filename>
+remove the supplied <filename>sh.exe</filename> (or rename it as <filename>ash.exe</filename>),
+and copy <filename>bash.exe</filename> to  <filename>sh.exe</filename>.
+You'll need to do this in Windows Explorer or the Windows <command>cmd</command> shell, because
+you can't rename a running program!
+</para>
+</listitem>
+
+<listitem>
+<para>
  Some script files used in the make system start with "<Command>#!/bin/perl</Command>",
  Some script files used in the make system start with "<Command>#!/bin/perl</Command>",
-(and similarly for <Command>bash</Command>).  Notice the hardwired path!
+(and similarly for <Command>sh</Command>).  Notice the hardwired path!
  So you need to ensure that your <Filename>/bin</Filename> directory has the following
  binaries in it:
  <itemizedlist>
  So you need to ensure that your <Filename>/bin</Filename> directory has the following
  binaries in it:
  <itemizedlist>
@@ -4250,21 +4702,10 @@ All these come in Cygwin's <Filename>bin</Filename> directory, which you probabl
  installed as <Filename>c:/cygwin/bin</Filename>.  By default Cygwin mounts "<Filename>/</Filename>" as
  <Filename>c:/cygwin</Filename>, so if you just take the defaults it'll all work ok.
  (You can discover where your Cygwin
  installed as <Filename>c:/cygwin/bin</Filename>.  By default Cygwin mounts "<Filename>/</Filename>" as
  <Filename>c:/cygwin</Filename>, so if you just take the defaults it'll all work ok.
  (You can discover where your Cygwin
-root directory <Filename>/</Filename> is by typing <Command>mount</Command>).
+root directory <Filename>/</Filename> is by typing <Command>mount</Command>.)
  Provided <Filename>/bin</Filename> points to the Cygwin <Filename>bin</Filename>
  Provided <Filename>/bin</Filename> points to the Cygwin <Filename>bin</Filename>
-directory, there's no need to copy anything.
-</para>
-</listitem>
-
-<listitem>
-<para>
-By default, cygwin provides the command shell <filename>ash</filename>
-as <filename>sh.exe</filename>. It has a couple of 'issues' (to do with quoting
-and length of command lines), so
-in your <filename>/bin</filename> directory, make sure that <filename>
-bash.exe</filename> is also provided as <filename>sh.exe</filename>
-(i.e. overwrite the old <filename>sh.exe</filename> with a copy of
-<filename>bash.exe</filename>).
+directory, there's no need to copy anything.  If not, copy these binaries from the <filename>cygwin/bin</filename>
+directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
  </para>
  </listitem>
  </itemizedlist>
  </para>
  </listitem>
  </itemizedlist>
@@ -4286,20 +4727,93 @@ they don't recognise symlinks.
  </para></listitem>
  
  <listitem> <para>
  </para></listitem>
  
  <listitem> <para>
-Win32 has a <command>find</command> command which is not the same as Cygwin's find.
-You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
-before the Cygwin one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant> 
-environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant> 
-variable.  You can always invoke <command>find</command> with an absolute path, or rename it.
+See the notes in <xref linkend="msys-install"> about <command>find</command> and <command>bzip</command>,
+which apply to Cygwin too.
  </para></listitem>
  </itemizedlist>
  </para>
  
  </Sect2>
  
  </para></listitem>
  </itemizedlist>
  </para>
  
  </Sect2>
  
+
+<Sect2 id="configure-ssh"><Title>Configuring SSH</Title>
+
+<para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when
+you install Cygwin.  (If not, the installer lets you update easily.)  Look for <command>openssh</command> 
+(not ssh) in the Cygwin list of applications!</para>
+
+<para>There are several strange things about <command>ssh</command> on Windows that you need to know.
+<itemizedlist>
+<listitem>
+<para>
+       The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
+       seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
+       they ask for a password).  To solve this, start up <filename>cmd.exe</filename> 
+       and run it as follows:
+       <Screen>
+       c:\tmp> set CYGWIN32=tty
+       c:\tmp> c:/user/local/bin/ssh-keygen1
+       </Screen> </para>
+</listitem>
+
+<listitem><para> (Cygwin-only problem, I think.)
+<command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.  
+To determine your home directory <command>ssh</command> first looks in 
+<filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed).  If there's an entry
+there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
+the setting of the environment variable $HOME</emphasis>.  If the home directory is
+bogus, <command>ssh</command> fails horribly.   The best way to see what is going on is to say
+<programlisting>
+  ssh -v cvs.haskell.org
+</programlisting>
+which makes <command>ssh</command> print out information about its activity.
+</para>
+<para> You can fix this problem, either by correcting the home-directory field in 
+<filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
+you do that, <command>ssh</command> uses the $HOME environment variable instead.
+</para>
+
+</listitem>
+
+<listitem>
+           <para>To protect your
+            <literal>.ssh</literal> from access by anyone else,
+            right-click your <literal>.ssh</literal> directory, and
+            select <literal>Properties</literal>.  If you are not on
+            the access control list, add yourself, and give yourself
+            full permissions (the second panel).  Remove everyone else
+            from the access control list.  Don't leave them there but
+            deny them access, because 'they' may be a list that
+            includes you!</para>
+</listitem>
+
+<listitem>
+           <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
+             you to have Unix permissions 600 (read/write for owner only) 
+             on the <literal>.ssh/identity</literal> file, else it 
+             bombs out.  For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
+             but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).  
+             The solution seems to be to set the $CYGWIN environment
+             variable to "<literal>ntsec neta</literal>".  The $CYGWIN environment variable is discussed
+             in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
+             and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
+             </para>
+</listitem>
+</itemizedlist>
+</para>
+</sect2>
+
  <Sect2><Title>Other things you need to install</Title>
  
  <Sect2><Title>Other things you need to install</Title>
  
-<para>You have to install the following other things to build GHC:
+<para>You have to install the following other things to build GHC, listed below.</para>
+
+<para>On Windows you often install executables in directories with spaces, such as 
+"<filename>Program Files</filename>". However, the <literal>make</literal> system for fptools doesn't 
+deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised
+to put binaries for all tools in places with no spaces in their path.
+On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places,
+<filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>.  But it doesn't matter,
+provided they are in your path.
  <itemizedlist>
  <listitem>
  <para>
  <itemizedlist>
  <listitem>
  <para>
@@ -4313,15 +4827,31 @@ you need to add upon completion.
  <listitem>
  <para>
  Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
  <listitem>
  <para>
  Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
-Happy is a parser generator used to compile the Haskell grammar.  Add it in your
+Happy is a parser generator used to compile the Haskell grammar.  Under MSYS or Cygwin you can easily
+build it from the source distribution using
+<programlisting>
+  ./configure
+  make
+  make install
+</programlisting>
+This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename>
+on MSYS).
+Make sure the installation directory is in your
  <constant>PATH</constant>.
  </para>
  </listitem>
  
  <constant>PATH</constant>.
  </para>
  </listitem>
  
+         <listitem>
+           <para>Install Alex.  This can be done by building from the
+           source distribution in the same way as Happy.  Sources are
+           available from <ulink
+           url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
+         </listitem>
  
  <listitem>
  <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
  
  <listitem>
  <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
-generate code, so you have to install that. Just pick up a mingw bundle at
+generate code, so you have to install that (see <xref linkend="cygwin-and-mingw">). 
+Just pick up a mingw bundle at
  <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
  We install it in <filename>c:/mingw</filename>.
  </para>
  <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
  We install it in <filename>c:/mingw</filename>.
  </para>
@@ -4334,6 +4864,18 @@ you are likely to get into a mess because their names overlap with Cygwin binari
  
  
  <listitem>
  
  
  <listitem>
+<para>We use <command>emacs</command> a lot, so we install that too.
+When you are in <filename>fptools/ghc/compiler</filename>, you can use
+"<literal>make tags</literal>" to make a TAGS file for emacs.  That uses the utility
+<filename>fptools/ghc/utils/hasktags/hasktags</filename>, so you need to make that first.
+The most convenient way to do this is by going <literal>make boot</literal> in <filename>fptools/ghc</filename>.
+The <literal>make tags</literal> command also uses <command>etags</command>, which comes with <command>emacs</command>,
+so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</literal>.
+</para>
+</listitem>
+
+
+<listitem>
  <para> Finally, check out a copy of GHC sources from
  the CVS repository, following the instructions above (<xref linkend="cvs-access">).
  </para>
  <para> Finally, check out a copy of GHC sources from
  the CVS repository, following the instructions above (<xref linkend="cvs-access">).
  </para>
@@ -4351,9 +4893,8 @@ you about Windows-specific wrinkles.</para>
  <ItemizedList>
  <listitem>
  <para>
  <ItemizedList>
  <listitem>
  <para>
-Run <Command>autoconf</Command> both in <filename>fptools</filename>
-and in <filename>fptools/ghc</filename>.  If you omit the latter step you'll
-get an error when you run <filename>./configure</filename>:
+If you used <Command>autoconf</Command> instead of <Command>autoreconf</Command>,
+you'll get an error when you run <filename>./configure</filename>:
  <Screen>
  ...lots of stuff...
  creating mk/config.h
  <Screen>
  ...lots of stuff...
  creating mk/config.h
@@ -4366,8 +4907,8 @@ configure: error: ./configure failed for ghc
  </para>
  </listitem>
  
  </para>
  </listitem>
  
-<listitem> <para><command>autoconf</command> seems to create the file <filename>configure</filename>
-read-only.  So if you need to run autoconf again (which I sometimes do for safety's sake),
+<listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
+read-only.  So if you need to run autoreconf again (which I sometimes do for safety's sake),
  you get
  <screen>
  /usr/bin/autoconf: cannot create configure: permission denied
  you get
  <screen>
  /usr/bin/autoconf: cannot create configure: permission denied
@@ -4376,24 +4917,8 @@ Solution: delete <filename>configure</filename> first.
  </para></listitem>
  
  <listitem>
  </para></listitem>
  
  <listitem>
-<para>
-You either need to add <filename>ghc</filename> to your
-<constant>PATH</constant> before you invoke
-<Command>configure</Command>, or use the <Command>configure</Command>
-option <option>--with-ghc=c:/ghc/ghc-some-version/bin/ghc</option>.
-</para>
-</listitem>
-
-<listitem><para>
-If you are paranoid, delete <filename>config.cache</filename> if it exists.
-This file occasionally remembers out-of-date configuration information, which 
-can be really confusing.
-</para>
-</listitem>
-
-<listitem>
    <para> 
    <para> 
-    After <command>autoconf</command> run <command>./configure</command> in
+    After <command>autoreconf</command> run <command>./configure</command> in
      <filename>fptools/</filename> thus:
  
  <Screen>
      <filename>fptools/</filename> thus:
  
  <Screen>
@@ -4403,15 +4928,32 @@ This is the point at which you specify that you are building GHC-mingw
  (see <xref linkend="ghc-mingw">). </para>
  
  <para> Both these options are important! It's possible to get into
  (see <xref linkend="ghc-mingw">). </para>
  
  <para> Both these options are important! It's possible to get into
-trouble using the wrong C compiler!
-Furthermore, it's very important that you specify a 
-full mingw path for <command>gcc</command>, not a cygwin path, because GHC (which
-uses this path to invoke <command>gcc</command>) is a Mingw program and won't
-understand a cygwin path..  For example, if you 
+trouble using the wrong C compiler!</para>
+<para>
+Furthermore, it's <emphasis>very important</emphasis> that you specify a 
+full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
+uses this path to invoke <command>gcc</command>) is a MinGW program and won't
+understand a Cygwin path.  For example, if you 
  say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
  <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
  say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
  <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
-time it tries to invoke it.   (Worse, the failure does not come with
-a helpful error message, unfortunately.)
+time it tries to invoke it.   Worse, the failure comes with
+no error message whatsoever.  GHC simply fails silently when first invoked, 
+typically leaving you with this:
+<programlisting>
+make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
+../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O 
+  -optc-Wall -optc-W  -optc-Wstrict-prototypes -optc-Wmissing-prototypes 
+  -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return 
+  -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes 
+  -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS 
+  -optc-fomit-frame-pointer -O2 -static 
+  -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
+make[2]: *** [Adjustor.o] Error 1
+make[1]: *** [all] Error 1
+make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
+make: *** [all] Error 1
+</programlisting>
+Be warned!
  </para>
  
  <para>
  </para>
  
  <para>
@@ -4423,6 +4965,24 @@ you'll have to do something more like:
  </para>
  </listitem>
  
  </para>
  </listitem>
  
+<listitem><para>
+If you are paranoid, delete <filename>config.cache</filename> if it exists.
+This file occasionally remembers out-of-date configuration information, which 
+can be really confusing.
+</para>
+</listitem>
+
+<listitem><para> You almost certainly want to set
+<programlisting>
+  SplitObjs = NO
+</programlisting>
+in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config">).
+This tells the build system not to split each library into a myriad of little object files, one
+for each function.  Doing so reduces binary sizes for statically-linked binaries, but on Windows
+it dramatically increases the time taken to build the libraries in the first place.
+</para>
+</listitem>
+
  <listitem><para> Do not attempt to build the documentation.
  It needs all kinds of wierd Jade stuff that we haven't worked out for
  Win32.</para></listitem>
  <listitem><para> Do not attempt to build the documentation.
  It needs all kinds of wierd Jade stuff that we haven't worked out for
  Win32.</para></listitem>