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>
<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>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>
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>
-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>
(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
-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>
</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>