--- /dev/null
+<chapter id="faq">
+ <title>GHC FAQ</title>
+
+ <para>This section has the answers to questions that get asked
+ regularly on the GHC mailing lists, in no particular order. Please
+ let us know if you think there's a question/answer that should be
+ added here.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>How do I port GHC to platform X?</term>
+ <listitem>
+ <para>There are two distinct possibilities: either</para>
+ <itemizedlist>
+ <listitem>
+ <para>The hardware architecture for your system is already
+ supported by GHC, but you're running an OS that isn't
+ supported (or perhaps has been supported in the past, but
+ currently isn't). This is the easiest type of porting
+ job, but it still requires some careful
+ bootstrapping.</para>
+ </listitem>
+
+ <listitem>
+ <para>Your system's hardware architecture isn't supported
+ by GHC. This will be a more difficult port (though by
+ comparison perhaps not as difficult as porting
+ gcc).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Both ways require you to bootrap from intermediate
+ <literal>HC</literal> files: these are the stylised C files
+ generated by GHC when it compiles Haskell source. Basically
+ the idea is to take the HC files for GHC itself to the target
+ machine and compile them with <literal>gcc</literal> to get a
+ working GHC, and go from there.</para>
+
+ <para>The <ulink
+ url="http://www.haskell.org/ghc/latest/building/building-guide.html">Building
+ Guide</ulink> has all the details on how to bootstrap GHC on a
+ new platform.</para>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Why doesn't GHC use shared libraries?</term>
+ <listitem>
+ <para>The subject of shared libraries has come up several
+ times in the past — take a look through the mailing-list
+ archives for some of the previous discussions. The upshot is
+ that shared libraries wouldn't really buy much unless you
+ really need to save the disk space: in all other
+ considerations, static linking comes out better.</para>
+
+ <para>Unfortunately GHC-compiled libraries are very tightly
+ coupled, which means it's unlikely you'd be able to swap out a
+ shared library for a newer version unless it was compiled with
+ <emphasis>exactly</emphasis> the same compiler and set of
+ libraries as the old version.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>I can't get string gaps to work</term>
+ <listitem>
+ <para>If you're also using CPP, beware of the known pitfall
+ with string gaps mentioned in <xref
+ linkend="cpp-string-gaps">.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>GHCi complains about missing symbols like
+ <literal>CC_LIST</literal> when loading a previously compiled .o
+ file.</term>
+ <listitem>
+ <para> This probably means the .o files in question were
+ compiled for profiling (with <option>-prof</option>). Workaround:
+ recompile them without profiling. We really ought to detect
+ this situation and give a proper error message.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Linking a program causes the following error on Linux:
+ <literal>/usr/bin/ld: cannot open -lgmp: No such file or
+ directory</literal></term>
+ <listitem>
+ <para>The problem is that your system doesn't have the GMP
+ library installed. If this is a RedHat distribution, install
+ the RedHat-supplied <literal>gmp-devel</literal> package, and
+ the <literal>gmp</literal> package if you don't already have
+ it. There have been reports that installing the RedHat
+ packages also works for SuSE (SuSE don't supply a shared gmp
+ library).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>I Can't run GHCi on Linux, because it complains about a
+ missing <literal>libreadline.so.3</literal>.</term>
+ <listitem>
+ <para>The "correct" fix for this problem is to install the
+ correct RPM for the particular flavour of Linux on your
+ machine. If this isn't an option, however, there is a hack
+ that might work: make a symbolic link from
+ <filename>libreadline.so.4</filename> to
+ <filename>libreadline.so.3</filename> in
+ <literal>/usr/lib</literal>. We tried this on a SuSE 7.1 box
+ and it seemed to work, but YMMV.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Solaris users may sometimes get link errors due to
+ libraries needed by GNU Readline.</term>
+ <listitem>
+ <para>We suggest you try linking in some combination of the
+ <literal>termcap</literal>, <literal>curses</literal> and
+ <literal>ncurses</literal> libraries, by giving
+ <literal>-ltermcap</literal>, <literal>-lcurses</literal> and
+ <literal>-lncurses</literal> respectively. If you encounter
+ this problem, we would appreciate feedback on it, since we
+ don't fully understand what's going on here.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>When I try to start ghci (probably one I compiled myself)
+ it says <literal>ghc-5.02: not built for interactive
+ use</literal></term>
+ <listitem>
+ <para>To build a working ghci, you need to build GHC 5.02 with
+ itself; the above message appears if you build it with 4.08.X,
+ for example. It'll still work fine for batch-mode
+ compilation, though. Note that you really must build with
+ exactly the same version of the compiler. Building 5.02 with
+ 5.00.2, for example, may or may not give a working interactive
+ system; it probably won't, and certainly isn't supported.
+ Note also that you can build 5.02 with any older compiler,
+ back to 4.08.1, if you don't want a working interactive
+ system; that's OK, and supported.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>When I use a foreign function that takes or returns a
+ float, it gives the wrong answer, or crashes.</term>
+ <listitem>
+ <para>You should use the <option>-#include</option> option to
+ bring the correct prototype into scope (see <xref
+ linkend="options-C-compiler">).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>My program that uses a really large heap crashes on
+ Windows.</term>
+ <listitem>
+ <para>For utterly horrible reasons, programs that use more
+ than 128Mb of heap won't work when compiled dynamically on
+ Windows (they should be fine statically compiled).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>GHC doesn't like filenames containing
+ <literal>+</literal>.</term>
+ <listitem>
+ <para>Indeed not. You could change <literal>+</literal> to
+ <literal>p</literal> or <literal>plus</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>When I open a FIFO (named pipe) and try to read from it, I
+ get EOF immediately.</term>
+ <listitem>
+ <para>This is a consequence of the fact that GHC opens the
+ FIFO in non-blocking mode. The behaviour varies from OS to
+ OS: on Linux and Solaris you can wait for a writer by doing an
+ explicit <literal>threadWaitRead</literal> on the file
+ descriptor (gotten from <literal>Posix.handleToFd</literal>)
+ before the first read, but this doesn't work on FreeBSD
+ (although rumour has it that recent versions of FreeBSD
+ changed the behavour to match other OSs). A workaround for
+ all systems is to open the FIFO for writing yourself, before
+ (or at the same time as) opening it for reading.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>When I <literal>foreign import</literal> a function that
+ returns <literal>char</literal> or <literal>short</literal>, I
+ get garbage back.</term>
+ <listitem>
+ <para>This is a known bug in GHC versions prior to 5.02.2.
+ GHC doesn't mask out the more significant bits of the result.
+ It doesn't manifest with gcc 2.95, but apparently shows up
+ with g++ and gcc 3.0.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</chapter>
+
+
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: sgml ***
+ ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
+ ;;; End: ***
+ -->