[project @ 2002-05-29 13:06:02 by simonpj]

Document GHC-mingw vs GHC-cygwin

diff --git a/docs/building/building.sgml b/docs/building/building.sgml
index ffd2c5c..978cd09 100644 (file)
--- a/docs/building/building.sgml
+++ b/docs/building/building.sgml
@@ -3730,9 +3730,82 @@ guide) before continuing to read these notes.
 </para>
 
 
+<sect2><Title>Cygwin and MinGW</Title>
+
+<para> The Windows situation for building GHC is rather confusing.  This section
+tries to clarify, and to establish terminology.</para>
+
+<sect3 id="ghc-mingw"><title>GHC-mingw</title>
+
+<para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink> 
+is a collection of header
+files and import libraries that allow one to use <command>gcc</command> and produce
+native Win32 programs that do not rely on any third-party DLLs. The
+current set of tools include GNU Compiler Collection (<command>gcc</command>), GNU Binary
+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>
+<para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
+
+<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 
+library; they have to do
+their input output using standard Haskell I/O libraries, or native Win32 bindings.
+</para>
+</sect3>
+
+<sect3 id="ghc-cygwin"><title>GHC-cygwin</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>
+<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>
+<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>
+</sect3>
+
+<sect3><title>Summary</title>
+
+<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>
+
+<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>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>
+</sect3>
+</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>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>.
@@ -3925,9 +3998,18 @@ option <option>--with-ghc=c:/ghc/ghc-some-version/bin/ghc</option>.
 <Screen>
   ./configure --host=i386-unknown-mingw32 --with-gcc=/mingw/bin/gcc
 </Screen>
+This is the point at which you specify that you are building GHC-mingw
+(see <xref linkend="ghc-mingw">).  
 
 Both these options are important! It's possible to get into
-trouble using the wrong C compiler!
+trouble using the wrong C compiler!</para>
+
+<para>
+If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)
+you'll have to do something more like:
+<Screen>
+  ./configure --with-gcc=...the Cygwin gcc...
+</Screen>
 </para>
 </listitem>