+
+<sect3><title> File names </title>
+
+<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> 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>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
+</para></listitem>
+</itemizedlist>
+</para>
+</sect3>
+
+<sect3><title>HOST_OS vs TARGET_OS</title>
+
+<para>
+In the source code you'll find various ifdefs looking like:
+<programlisting>
+ #ifdef mingw32_HOST_OS
+ ...blah blah...
+ #endif
+</programlisting>
+and
+<programlisting>
+ #ifdef mingw32_TARGET_OS
+ ...blah blah...
+ #endif
+</programlisting>
+These macros are set by the configure script (via the file config.h).
+Which is which? The criterion is this. In the ifdefs in GHC's source code:
+<itemizedlist>
+ <listitem> <para>
+ The "host" system is the one on which GHC itself will be run.
+ </para> </listitem>
+ <listitem> <para>
+ The "target" system is the one for which the program compiled by GHC will be run.
+ </para> </listitem>
+</itemizedlist>
+For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
+So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
+
+</para>
+</sect3>
+
+</sect2>
+
+<sect2><title>Wrapper scripts</title>
+
+<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>
+
+ <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>
+
+</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.
+</para>
+
+
+<Sect2><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>