[project @ 2005-10-26 15:22:08 by simonmar]
[ghc-hetmet.git] / docs / building / building.xml
index e0608bc..6ea21e6 100644 (file)
@@ -1,27 +1,23 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+  <!ENTITY hacking SYSTEM "../../ghc/HACKING">
+]>
 
 <article id="building-guide">
 
 <articleinfo>
 
-<title>Building the Glasgow Functional Programming Tools Suite</title>
+<title>Building and developing GHC</title>
 <author><othername>The GHC Team</othername></author>
 <address><email>glasgow-haskell-&lcub;users,bugs&rcub;@haskell.org</email></address>
 
     <abstract>
-      <para>The Glasgow fptools suite is a collection of Functional
-      Programming related tools, including the Glasgow Haskell
-      Compiler (GHC).  The source code for the whole suite is kept in
-      a single CVS repository and shares a common build and
-      installation system.</para>
-
-      <para>This guide is intended for people who want to build or
-      modify programs from the Glasgow <literal>fptools</literal>
-      suite (as distinct from those who merely want to
-      <emphasis>run</emphasis> them). Installation instructions are
-      now provided in the user guide.</para>
+      <para>This Guide is primarily aimed at those who want to build and/or
+       hack on GHC.  It describes how to get started with building GHC on your
+       machine, and how to tweak the settings to get the kind of build you
+       want.  It also describes the inner workings of the build system, so you
+       can extend it, modify it, and use it to build your code.</para>
 
       <para>The bulk of this guide applies to building on Unix
       systems; see <xref linkend="winbuild"/> for Windows notes.</para>
@@ -33,8 +29,7 @@
   <sect1 id="sec-getting">
     <title>Getting the sources</title>
     
-    <para>You can get your hands on the <literal>fptools</literal>
-    in two ways:</para>
+    <para>You can get your hands on the GHC sources in two ways:</para>
 
     <variablelist>
 
@@ -49,8 +44,7 @@
           (c)&nbsp;you want to hack on GHC yourself.</para>
 
          <para>A source distribution contains complete sources for
-          one or more projects in the <literal>fptools</literal>
-          suite.  Not only that, but the more awkward
+          GHC.  Not only that, but the more awkward
           machine-independent steps are done for you.  For example, if
           you don't have
           <command>happy</command><indexterm><primary>happy</primary></indexterm>
@@ -71,7 +65,7 @@
           up-to-the minute (but less tested) source code then you need
           to get access to our CVS repository.</para>
 
-         <para>All the <literal>fptools</literal> source code is held
+         <para>All the GHC source code is held
           in a CVS repository. CVS is a pretty good source-code
           control system, and best of all it works over the
           network.</para>
        </listitem>
       </varlistentry>
     </variablelist>
-
-    <para>If you are going to do any building from sources (either
-    from a source distribution or the CVS repository) then you need to
-    read all of this manual in detail.</para>
   </sect1>
 
   <sect1 id="sec-cvs">
          </listitem>
          <listitem>
            <para>Set your <literal>$CVSROOT</literal> environment variable to
-            <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
+            <literal>:pserver:anoncvs@cvs.haskell.org:/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
@@ -407,12 +397,12 @@ setsockopt IPTOS_THROUGHPUT: Invalid argument</screen>
           result in checking out the entire repository instead of just
           the <literal>fpconfig</literal> bit.</para>
 <screen>$ cd <replaceable>directory</replaceable>
-$ cvs checkout ghc hslibs libraries</screen>
+$ cvs checkout ghc libraries</screen>
 
          <para>The second command here checks out the relevant
           modules you want to work on. For a GHC build, for instance,
           you need at least the <literal>ghc</literal>,
-          <literal>hslibs</literal> and <literal>libraries</literal>
+          and <literal>libraries</literal>
           modules (for a full list of the projects available, see
           <xref linkend="projects"/>).</para>
 
@@ -605,7 +595,7 @@ $ lndir <replaceable>source-tree</replaceable></screen>
 
 <screen>$ cvs co -r ghc-4-06 fpconfig
 $ cd fptools
-$ cvs co -r ghc-4-06 ghc hslibs</screen>
+$ cvs co -r ghc-4-06 ghc libraries</screen>
     </sect2>
 
     <sect2 id="cvs-hints">
@@ -793,8 +783,7 @@ $ cvs checkout nofib/spectral</screen>
           <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
         </term>
        <listitem>
-         <para>Supplemental libraries for GHC
-         (<emphasis>required</emphasis> for building GHC).</para>
+         <para>Old, now deprecated, libraries.  Everything in here is in <literal>libraries</literal>.</para>
        </listitem>
       </varlistentry>
 
@@ -843,8 +832,8 @@ $ cvs checkout nofib/spectral</screen>
     </variablelist>
 
     <para>So, to build GHC you need at least the
-    <literal>ghc</literal>, <literal>libraries</literal> and
-    <literal>hslibs</literal> projects (a GHC source distribution will
+    <literal>ghc</literal> and <literal>libraries</literal>
+    projects (a GHC source distribution will
     already include the bits you need).</para>
   </sect1>
 
@@ -904,7 +893,7 @@ $ cvs checkout nofib/spectral</screen>
   </sect1>
 
   <sect1 id="sec-port-info">
-    <title>What machines the Glasgow tools run on</title>
+    <title>What machines GHC runs on</title>
 
 <indexterm><primary>ports</primary><secondary>GHC</secondary></indexterm>
 <indexterm><primary>GHC</primary><secondary>ports</secondary></indexterm>
@@ -1091,20 +1080,11 @@ $ cvs checkout nofib/spectral</screen>
          <term>x86_64-unknown-linux
             <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
           </term>
-         <listitem>
-           <para>GHC currently works unregisterised.  A registerised
-           port is in progress.</para>
-         </listitem>
-       </varlistentry>
-
-       <varlistentry>
-         <term>amd64-unknown-openbsd
+<term>amd64-unknown-openbsd
             <indexterm><primary>amd64-unknown-linux</primary></indexterm>
           </term>
          <listitem>
-            <para>(This is the same as x86_64-unknown-openbsd). GHC
-                currently works unregisterised.  A registerised port is in
-                progress.</para>
+           <para>Fully supported, with a native code generator and GHCi.</para>
          </listitem>
        </varlistentry>
 
@@ -1167,16 +1147,8 @@ $ cvs checkout nofib/spectral</screen>
       support still remains, but porting to one of these systems will
       certainly be a non-trivial task.</para>
     </sect2>
-
-    <sect2>
-      <title>What machines the other tools run on</title>
-
-      <para>Unless you hear otherwise, the other tools work if GHC
-      works.</para>
-    </sect2>
   </sect1>
 
-
   <sect1 id="sec-pre-supposed">
     <title>Installing pre-supposed utilities</title>
 
@@ -1221,8 +1193,9 @@ $ cvs checkout nofib/spectral</screen>
           Perl version 5 at least is required.  GHC has been known to
           tickle bugs in Perl, so if you find that Perl crashes when
           running GHC try updating (or downgrading) your Perl
-          installation.  Versions of Perl that we use and are known to
-          be fairly stable are 5.005 and 5.6.1.</para>
+          installation.  Versions of Perl before 5.6 have been known to have
+          various bugs tickled by GHC, so the configure script
+          will look for version 5.6 or later.</para>
 
          <para>For Win32 platforms, you should use the binary
           supplied in the InstallShield (copy it to
@@ -1242,16 +1215,12 @@ $ cvs checkout nofib/spectral</screen>
           <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
         </term>
        <listitem>
-         <para>We recommend using GCC version 2.95.2 on all
-          platforms.  Failing that, version 2.7.2 is stable on most
-          platforms.  Earlier versions of GCC can be assumed not to
-          work, and versions in between 2.7.2 and 2.95.2 (including
-          <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>Most GCC versions should work with the most recent GHC
+           sources.  Expect trouble if you use a recent GCC with
+           an older GHC, though (trouble in the form of mis-compiled code,
+           link errors, and errors from the <literal>ghc-asm</literal>
+           script).</para>
+
          <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 x86
@@ -1279,14 +1248,23 @@ $ cvs checkout nofib/spectral</screen>
         </term>
        <listitem>
          <para>Happy is a parser generator tool for Haskell, and is
-          used to generate GHC's parsers.  Happy is written in
+          used to generate GHC's parsers.</para>
+
+         <para>If you start from a source tarball of GHC (i.e. not a CVS
+           checkout), then you don't need Happy, because we supply the
+           pre-processed versions of the Happy parsers.  If you intend to
+           modify the compiler and/or you're using a CVS checkout, then you
+           need Happy.</para>
+
+         <para>Happy version 1.15 is currently required to build GHC.</para>
+
+         <para>Happy is written in
           Haskell, and is a project in the CVS repository
           (<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 distribution of either Happy or GHC to get
-          started.  Happy distributions are available from <ulink
-          url="http://www.haskell.org/happy/">Happy's Web
+          started.  Happy distributions are available from <ulink url="http://www.haskell.org/happy/">Happy's Web
           Page</ulink>.</para>
        </listitem>
       </varlistentry>
@@ -1297,10 +1275,15 @@ $ cvs checkout nofib/spectral</screen>
         </term>
        <listitem>
          <para>Alex is a lexical-analyser generator for Haskell,
-         which GHC uses to generate its lexer.  Like Happy, Alex is
+         which GHC uses to generate its lexer.</para>
+
+         <para>Like Happy, you don't need Alex if you're building GHC from a
+           source tarball, but you do need it if you're modifying GHC and/or
+           building a CVS checkout.</para>
+
+         <para>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
+         Alex distributions are available from <ulink url="http://www.haskell.org/alex/">Alex's Web
          Page</ulink>.</para>
        </listitem>
       </varlistentry>
@@ -1425,41 +1408,54 @@ $ cvs checkout nofib/spectral</screen>
     <indexterm><primary>Building from source</primary></indexterm>
     <indexterm><primary>Source, building from</primary></indexterm>
 
-    <para>You've been rash enough to want to build some of the Glasgow
-    Functional Programming tools (GHC, Happy, nofib, etc.) from
-    source.  You've slurped the source, from the CVS repository or
-    from a source distribution, and now you're sitting looking at a
-    huge mound of bits, wondering what to do next.</para>
-
-    <para>Gingerly, you type <command>make</command>.  Wrong
-    already!</para>
-
-    <para>This rest of this guide is intended for duffers like me, who
-    aren't really interested in Makefiles and systems configurations,
-    but who need a mental model of the interlocking pieces so that
-    they can make them work, extend them consistently when adding new
-    software, and lay hands on them gently when they don't
-    work.</para>
-
-    <sect2 id="quick-start">
-      <title>Quick Start</title>
+    <para>&ldquo;I just want to build it!&rdquo;</para>
 
-      <para>If you are starting from a source distribution, and just
-      want a completely standard build, then the following procedure should 
-      work (unless you're on Windows, in which case go to <xref linkend="winbuild" />).</para>
+    <para>No problem.  This recipe should build and install a working GHC with
+      all the default settings.  (unless you're
+      on Windows, in which case go to <xref linkend="winbuild" />).</para>
 
-<screen>$ autoreconf
+<screen>$ autoreconf<footnote><para>not necessary if you started from a source tarball</para>
+      </footnote>
 $ ./configure
 $ make
 $ make install</screen>
 
       <para>For GHC, this will do a 2-stage bootstrap build of the
       compiler, with profiling libraries, and install the
-      results.</para>
+      results in the default location (under <filename>/usr/local</filename> on
+      Unix, for example).</para>
+
+    <para>The <literal>configure</literal> script is a standard GNU
+      <literal>autoconf</literal> script, and accepts the usual options for
+      changing install locations and the like.  Run
+      <literal>./configure&nbsp;--help</literal> for a list of options.</para>
 
       <para>If you want to do anything at all non-standard, or you
       want to do some development, read on...</para>
-    </sect2>
+    </sect1>
+    
+    <sect1 id="quick-start">
+      <title>Quick start for GHC developers</title>
+      
+      <para>This section is a copy of the file
+       <literal>ghc/HACKING</literal> from the GHC source tree.  It describes
+       how to get started with setting up your build tree for developing GHC
+       or its libraries, and how to start building.</para>
+
+<screen>     
+&hacking;
+      </screen>
+    </sect1>
+
+  <sect1 id="sec-working-with-the-build-system">
+    <title>Working with the build system</title>
+    
+    <para>This rest of this guide is intended for duffers like me, who
+    aren't really interested in Makefiles and systems configurations,
+    but who need a mental model of the interlocking pieces so that
+    they can make them work, extend them consistently when adding new
+    software, and lay hands on them gently when they don't
+    work.</para>
 
     <sect2 id="sec-source-tree">
       <title>Your source tree</title>
@@ -3618,7 +3614,7 @@ $ make install</screen>
           corresponding Haskell source (<filename>.hs</filename> or
           <filename>.lhs</filename>) in the compiler subdirectory
           <filename>ghc/compiler</filename> and in the libraries
-          (subdirectories of <filename>hslibs</filename> and
+          (subdirectories of 
           <literal>libraries</literal>).</para>
        </listitem>
 
@@ -3778,7 +3774,7 @@ GhcLibWays =
 SplitObjs = NO
 GhcWithNativeCodeGen = NO
 GhcWithInterpreter = NO
-GhcStage1HcOpts = -O -fasm
+GhcStage1HcOpts = -O
 GhcStage2HcOpts = -O -fvia-C -keep-hc-files
 SRC_HC_OPTS += -H32m
 GhcBootLibs = YES</programlisting>
@@ -3819,7 +3815,19 @@ GhcBootLibs = YES</programlisting>
              <listitem>
                <para>Touch the generated configuration files, just to make
                sure they don't get replaced during the build:</para>
-<screen>$ touch <filename><replaceable>H</replaceable></filename>/ghc/includes/{ghcautoconf.h,DerivedConstants.h.GHCConstants.h.mkDerivedConstants.c,mkDerivedConstantsHdr,mkDerivedConstants.o,mkGHCConstants,mkGHCConstants.o}
+<screen>$ cd <filename><replaceable>H</replaceable></filename>/ghc/includes
+$ touch ghcautoconf.h DerivedConstants.h GHCConstants.h mkDerivedConstants.c
+$ touch mkDerivedConstantsHdr mkDerivedConstants.o mkGHCConstants mkGHCConstants.o</screen>
+
+               <para>Note: it has been reported that these files still get
+                 overwritten during the next stage.  We have installed a fix
+                 for this in GHC 6.4.2, but if you are building a version
+                 before that you need to watch out for these files getting
+                 overwritte by the <literal>Makefile</literal> in
+                 <literal>ghc/includes</literal>.  If your system supports
+                 it, you might be able to prevent it by making them
+                 immutable:</para>
+<screen>$ chflags uchg  ghc/includes/{ghcautoconf.h,DerivedConstants.h,GHCConstants.h}</screen>
              </listitem>
 
            <listitem>
@@ -3841,8 +3849,10 @@ $ make boot stage=2 &amp;&amp; make stage=2</screen>
            </listitem>
 
            <listitem>
-<screen>$ cd <replaceable>H</replaceable>/ghc/lib
+<screen>$ cd <replaceable>H</replaceable>/ghc/lib/compat
 $ make clean
+$ rm .depend
+$ make boot UseStage1=YES
 $ make -k UseStage1=YES EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
 $ cd <replaceable>H</replaceable>/ghc/utils
 $ make clean
@@ -4566,11 +4576,17 @@ bzip'd dump.</para></listitem>
 </para>
 </sect2>
 
-<sect2><title>Installing and configuring Cygwin</title>
+<sect2 id="install-cygwin"><title>Installing and configuring Cygwin</title>
 
 <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>.
-During the installation dialogue, make sure that you select all of the following:
+The installation process is straightforward; we install it in
+<filename>c:/cygwin</filename>.</para>
+<para>
+You must install enough Cygwin <emphasis>packages</emphasis> to support
+building GHC.  If you miss out any of these, strange things will happen to you.   There are two ways to do this:
+<itemizedlist>
+<listitem><para>The direct, but laborious way is to 
+select all of the following packages in the installation dialogue:
              <command>cvs</command>, 
              <command>openssh</command>,
              <command>autoconf</command>,
@@ -4578,11 +4594,32 @@ During the installation dialogue, make sure that you select all of the following
              <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, 
+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>
+</listitem>
+
+<listitem><para>The clever way is to point the Cygwin installer at the
+<command>ghc-depends</command> package, which is kept at <ulink
+url="http://haskell.org/ghc/cygwin">http://haskell.org/ghc/cygwin</ulink>.
+When the Cygwin installer asks you to "Choose a Download Site", choose one of
+the
+offered mirror sites; and then type "http://haskell.org/ghc/cygwin" into the
+"User URL" box and click "Add"; now two sites are selected. (The Cygwin
+installer remembers this for next time.)
+Click "Next".</para>
+<para>In the "Select Packages" dialogue box that follows, click the "+" sign by
+"Devel", scroll down to the end of the "Devel" packages, and choose
+<command>ghc-depends</command>.
+The package <command>ghc-depends</command> will not actually install anything itself, 
+but forces additional packages to be added by the Cygwin installer.
+</para>
+</listitem>
+</itemizedlist>
+</para>
+
 <para> Now set the following user environment variables:
 <itemizedlist>
 
@@ -4611,50 +4648,7 @@ file.  Ditto <command>emacs</command> looking for <filename>.emacsrc</filename>
 </itemizedlist>
 </para>
 
-<para>
-There are a few other things to do:
-<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>",
-(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>
-<listitem> <para><command>sh</command></para></listitem>
-<listitem> <para><command>perl</command></para></listitem>
-<listitem> <para><command>cat</command></para></listitem>
-</itemizedlist>
-All these come in Cygwin's <filename>bin</filename> directory, which you probably have
-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>.)
-Provided <filename>/bin</filename> points to the Cygwin <filename>bin</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>
-
-<para>Finally, here are some things to be aware of when using Cygwin:
+<para>Here are some things to be aware of when using Cygwin:
 <itemizedlist>
 <listitem> <para>Cygwin doesn't deal well with filenames that include
 spaces. "<filename>Program Files</filename>" and "<filename>Local files</filename>" are
@@ -4673,6 +4667,38 @@ they don't recognise symlinks.
 See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>,
 which apply to Cygwin too.
 </para></listitem>
+
+<listitem>
+<para>
+Some script files used in the make system start with "<command>#!/bin/perl</command>",
+(and similarly for <command>sh</command>).  Notice the hardwired path!
+So you need to ensure that your <filename>/bin</filename> directory has at least
+<command>sh</command>, <command>perl</command>, and <command>cat</command> in it.
+All these come in Cygwin's <filename>bin</filename> directory, which you probably have
+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>.)
+Provided <filename>/bin</filename> points to the Cygwin <filename>bin</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>
+
+<listitem>
+<para>
+By default, cygwin provides the command shell <filename>ash</filename>
+as <filename>sh.exe</filename>.   It seems to be fine now, but in the past we
+saw build-system problems that turned 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.
+If this happens to you (which it shouldn't), 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>
 </itemizedlist>
 </para>
 
@@ -4681,9 +4707,10 @@ which apply to Cygwin too.
 
 <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><command>ssh</command> comes with both Cygwin and MSYS. 
+(Cygwin note: you need to ask for package <command>openssh</command> (not ssh)
+in the Cygwin list of packages; or use the <command>ghc-depends</command>
+package -- see <xref linkend="install-cygwin"/>.)</para>
 
 <para>There are several strange things about <command>ssh</command> on Windows that you need to know.
 <itemizedlist>
@@ -4801,7 +4828,11 @@ in your path.
 <para><emphasis>On Cygwin, do not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your  path.
 They are only going to get used by explicit access (via the --with-gcc flag you
 give to <command>configure</command> later).  If you do add them to your path
-you are likely to get into a mess because their names overlap with Cygwin binaries.
+you are likely to get into a mess because their names overlap with Cygwin
+binaries.
+On the other hand, you <emphasis>do</emphasis> need <command>ld</command>, <command>ar</command>
+(and perhaps one or two other things) in your path.  The Cygwin ones are fine,
+but you must have them; hence needing the  Cygwin binutils package.
 </para>
 </listitem>
 
@@ -4927,6 +4958,88 @@ Win32.</para></listitem>
 </sect2>
 
 
+<sect2><title>A Windows build log using Cygwin</title>
+
+<para>Here is a complete, from-scratch, log of all you need to build GHC using
+Cygwin, kindly provided by Claus Reinke.  It does not discuss alternative
+choices, but it gives a single path that works.</para>
+<programlisting>- Install some editor (vim, emacs, whatever)
+
+- Install cygwin (http://www.cygwin.com)
+    ; i used 1.5.16-1, installed in c:\cygwin
+  - run 'setup.exe'
+    Choose a Download Source:
+       select 'download from internet';
+    Select Root Install Directory:
+       root dir: c:\cygwin; 
+       install for: all users;
+       default file type: unix
+    Select Local Package Directory
+       choose a spare temporary home
+    Select Your Internet Connection
+       Use IE5 settings
+    Choose a Download Site
+       Choose your preferred main mirror and
+        Add 'http://www.haskell.org/ghc/cygwin'
+    Select Packages
+       In addition to 'Base' (default install), 
+       select 'Devel->ghc-depends'
+
+- Install mingw (http://www.mingw.org/)
+    ; i used MinGW-3.1.0-1.exe
+    ; installed in c:\mingw
+  - you probably want to add GLUT 
+    ; (http://www.xmission.com/~nate/glut.html)
+    ; i used glut-3.7.3-mingw32.tar
+
+- Get recent binary snapshot of ghc-6.4.1 for mingw 
+    ; (http://www.haskell.org/ghc/dist/stable/dist/)
+  - unpack in c:/ghc
+  - add C:\ghc\ghc-6.4.1\bin to %PATH%
+    (Start->Control Panel->System->Advanced->Environment Variables)
+
+- Get cvs version of ghc
+    ; also, subscribe to cvs-all@haskell.org, or follow the mailing list
+    ; archive, in case you checkout a version with problems
+    ; http://www.haskell.org//pipermail/cvs-all/
+  - mkdir c:/fptools; cd c:/fptools 
+    ; (or whereever you want your cvs tree to be)
+  - export CVSROOT=:pserver:anoncvs@cvs.haskell.org:/cvs
+  - cvs login
+    ; pw: cvs
+  - cvs checkout fpconfig
+  - cd fptools
+  - cvs checkout ghc hslibs libraries
+
+- Build ghc, using cygwin and mingw, targetting mingw
+  - export PATH=/cygdrive/c/ghc/ghc-6.4.1:$PATH
+    ; for haddock, alex, happy (*)
+  - export PATH=/cygdrive/c/mingw/bin:$PATH
+    ; without, we pick up some cygwin tools at best!
+  - cd c:/fptools/fptools
+    ; (if you aren't there already)
+  - autoreconf
+  - ./configure --host=i386-unknown-mingw32 --with-gcc=C:/Mingw/bin/gcc.exe
+    ; we use cygwin, but build for windows
+  - cp mk/build.mk.sample mk/build.mk
+  - in mk/build.mk:
+    add line:       SplitObjs = NO
+       (MSYS seems slow when there are zillions of object files)
+    uncomment line: BuildFlavour = perf
+       (or BuildFlavour = devel, if you are doing development)
+    add line:       BIN_DIST=1
+  - make 2>&amp;1 | tee make.log
+    ; always useful to have a log around
+
+- Package up binary distribution
+  - make binary-dist Project=Ghc 2>&amp;1 | tee make-bin-dist.log
+    ; always useful to have a log around
+  - cd ghc-6.5
+  - chmod +x ../distrib/prep-bin-dist-mingw
+    ; if you're happy with the script's contents (*)
+  - ../distrib/prep-bin-dist-mingw
+    ; then tar up, unpack where wanted, and enjoy</programlisting>
+</sect2>
 </sect1>
 
 <index/>