[project @ 2003-03-24 14:46:53 by simonmar]

[ghc-hetmet.git] / docs / building / building.sgml

diff --git a/docs/building/building.sgml b/docs/building/building.sgml
index f32c420..3df0893 100644 (file)
--- a/docs/building/building.sgml
+++ b/docs/building/building.sgml
@@ -1142,6 +1142,23 @@ $ cvs checkout nofib/spectral
     <variablelist>
 
       <varlistentry>
+       <term>GHC</term>
+       <indexterm><primary>pre-supposed: GHC</primary></indexterm>
+       <indexterm><primary>GHC, pre-supposed</primary></indexterm>
+       <listitem>
+         <para>GHC is required to build many of the tools, including
+         GHC itself.  If you need to port GHC to your platform
+         because there isn't a binary distribution of GHC available,
+         then see <xref linkend="sec-porting-ghc">.</para>
+
+         <para>Which version of GHC you need will depend on the
+         packages you intend to build.  GHC itself will normally
+         build using one of several older versions of itself - check
+         the announcement or release notes for details.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
        <term>Perl</term>
        <indexterm><primary>pre-supposed: Perl</primary></indexterm>
        <indexterm><primary>Perl, pre-supposed</primary></indexterm>
@@ -4112,6 +4129,37 @@ that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix libr
 </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>
+
 <sect3><title>Summary</title>
 
 <para>Notice that "GHC-mingw" means "GHC that <emphasis>targets</emphasis> MinGW".  It says nothing about 
@@ -4349,13 +4397,22 @@ can be really confusing.
     <filename>fptools/</filename> thus:
 
 <Screen>
-  ./configure --host=i386-unknown-mingw32 --with-gcc=/mingw/bin/gcc
+  ./configure --host=i386-unknown-mingw32 --with-gcc=c:/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!</para>
+(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 
+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.)
+</para>
 
 <para>
 If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)