ghc/docs/users_guide/faq.sgml

   1 <chapter id="faq">
   2   <title>GHC FAQ</title>
   3
   4   <para>This section has the answers to questions that get asked
   5   regularly on the GHC mailing lists, in no particular order.  Please
   6   let us know if you think there's a question/answer that should be
   7   added here.</para>
   8
   9   <variablelist>
  10     <varlistentry>
  11       <term>How do I port GHC to platform X?</term>
  12       <listitem>
  13         <para>There are two distinct possibilities: either</para>
  14         <itemizedlist>
  15           <listitem>
  16             <para>The hardware architecture for your system is already
  17             supported by GHC, but you're running an OS that isn't
  18             supported (or perhaps has been supported in the past, but
  19             currently isn't).  This is the easiest type of porting
  20             job, but it still requires some careful
  21             bootstrapping.</para>
  22           </listitem>
  23
  24           <listitem>
  25             <para>Your system's hardware architecture isn't supported
  26             by GHC.  This will be a more difficult port (though by
  27             comparison perhaps not as difficult as porting
  28             gcc).</para>
  29           </listitem>
  30         </itemizedlist>
  31
  32         <para>Both ways require you to bootrap from intermediate
  33         <literal>HC</literal> files: these are the stylised C files
  34         generated by GHC when it compiles Haskell source.  Basically
  35         the idea is to take the HC files for GHC itself to the target
  36         machine and compile them with <literal>gcc</literal> to get a
  37         working GHC, and go from there.</para>
  38
  39         <para>The <ulink
  40         url="http://www.haskell.org/ghc/latest/building/building-guide.html">Building
  41         Guide</ulink> has all the details on how to bootstrap GHC on a
  42         new platform.</para>
  43
  44       </listitem>
  45     </varlistentry>
  46
  47     <varlistentry>
  48       <term>Why doesn't GHC use shared libraries?</term>
  49       <listitem>
  50         <para>The subject of shared libraries has come up several
  51         times in the past &mdash; take a look through the mailing-list
  52         archives for some of the previous discussions. The upshot is
  53         that shared libraries wouldn't really buy much unless you
  54         really need to save the disk space: in all other
  55         considerations, static linking comes out better.</para>
  56
  57         <para>Unfortunately GHC-compiled libraries are very tightly
  58         coupled, which means it's unlikely you'd be able to swap out a
  59         shared library for a newer version unless it was compiled with
  60         <emphasis>exactly</emphasis> the same compiler and set of
  61         libraries as the old version.</para>
  62       </listitem>
  63     </varlistentry>
  64
  65     <varlistentry>
  66       <term>I can't get string gaps to work</term>
  67       <listitem>
  68         <para>If you're also using CPP, beware of the known pitfall
  69         with string gaps mentioned in <xref
  70         linkend="cpp-string-gaps">.</para>
  71       </listitem>
  72     </varlistentry>
  73
  74     <varlistentry>
  75       <term>GHCi complains about missing symbols like
  76       <literal>CC_LIST</literal> when loading a previously compiled .o
  77       file.</term>
  78       <listitem>
  79         <para> This probably means the .o files in question were
  80         compiled for profiling (with <option>-prof</option>).  Workaround:
  81         recompile them without profiling.  We really ought to detect
  82         this situation and give a proper error message.</para>
  83       </listitem>
  84     </varlistentry>
  85
  86     <varlistentry>
  87       <term>Linking a program causes the following error on Linux:
  88       <literal>/usr/bin/ld: cannot open -lgmp: No such file or
  89       directory</literal></term>
  90       <listitem>
  91         <para>The problem is that your system doesn't have the GMP
  92         library installed.  If this is a RedHat distribution, install
  93         the RedHat-supplied <literal>gmp-devel</literal> package, and
  94         the <literal>gmp</literal> package if you don't already have
  95         it.  There have been reports that installing the RedHat
  96         packages also works for SuSE (SuSE don't supply a shared gmp
  97         library).</para>
  98       </listitem>
  99     </varlistentry>
 100
 101     <varlistentry>
 102       <term>I Can't run GHCi on Linux, because it complains about a
 103       missing <literal>libreadline.so.3</literal>.</term>
 104       <listitem>
 105         <para>The "correct" fix for this problem is to install the
 106         correct RPM for the particular flavour of Linux on your
 107         machine.  If this isn't an option, however, there is a hack
 108         that might work: make a symbolic link from
 109         <filename>libreadline.so.4</filename> to
 110         <filename>libreadline.so.3</filename> in
 111         <literal>/usr/lib</literal>.  We tried this on a SuSE 7.1 box
 112         and it seemed to work, but YMMV.</para>
 113       </listitem>
 114     </varlistentry>
 115
 116     <varlistentry>
 117       <term>Solaris users may sometimes get link errors due to
 118       libraries needed by GNU Readline.</term>
 119       <listitem>
 120         <para>We suggest you try linking in some combination of the
 121         <literal>termcap</literal>, <literal>curses</literal> and
 122         <literal>ncurses</literal> libraries, by giving
 123         <literal>-ltermcap</literal>, <literal>-lcurses</literal> and
 124         <literal>-lncurses</literal> respectively.  If you encounter
 125         this problem, we would appreciate feedback on it, since we
 126         don't fully understand what's going on here.</para>
 127       </listitem>
 128     </varlistentry>
 129
 130     <varlistentry>
 131       <term>When I try to start ghci (probably one I compiled myself)
 132       it says <literal>ghc-5.02: not built for interactive
 133       use</literal></term>
 134       <listitem>
 135         <para>To build a working ghci, you need to build GHC 5.02 with
 136         itself; the above message appears if you build it with 4.08.X,
 137         for example.  It'll still work fine for batch-mode
 138         compilation, though.  Note that you really must build with
 139         exactly the same version of the compiler.  Building 5.02 with
 140         5.00.2, for example, may or may not give a working interactive
 141         system; it probably won't, and certainly isn't supported.
 142         Note also that you can build 5.02 with any older compiler,
 143         back to 4.08.1, if you don't want a working interactive
 144         system; that's OK, and supported.</para>
 145       </listitem>
 146     </varlistentry>
 147
 148     <varlistentry>
 149       <term>When I use a foreign function that takes or returns a
 150       float, it gives the wrong answer, or crashes.</term>
 151       <listitem>
 152         <para>You should use the <option>-#include</option> option to
 153         bring the correct prototype into scope (see <xref
 154         linkend="options-C-compiler">).</para>
 155       </listitem>
 156     </varlistentry>
 157
 158     <varlistentry>
 159       <term>My program that uses a really large heap crashes on
 160       Windows.</term>
 161       <listitem>
 162         <para>For utterly horrible reasons, programs that use more
 163         than 128Mb of heap won't work when compiled dynamically on
 164         Windows (they should be fine statically compiled).</para>
 165       </listitem>
 166     </varlistentry>
 167
 168     <varlistentry>
 169       <term>GHC doesn't like filenames containing
 170       <literal>+</literal>.</term>
 171       <listitem>
 172         <para>Indeed not. You could change <literal>+</literal> to
 173         <literal>p</literal> or <literal>plus</literal>.</para>
 174       </listitem>
 175     </varlistentry>
 176
 177     <varlistentry>
 178       <term>When I open a FIFO (named pipe) and try to read from it, I
 179       get EOF immediately.</term>
 180       <listitem>
 181         <para>This is a consequence of the fact that GHC opens the
 182         FIFO in non-blocking mode.  The behaviour varies from OS to
 183         OS: on Linux and Solaris you can wait for a writer by doing an
 184         explicit <literal>threadWaitRead</literal> on the file
 185         descriptor (gotten from <literal>Posix.handleToFd</literal>)
 186         before the first read, but this doesn't work on FreeBSD
 187         (although rumour has it that recent versions of FreeBSD
 188         changed the behavour to match other OSs).  A workaround for
 189         all systems is to open the FIFO for writing yourself, before
 190         (or at the same time as) opening it for reading.</para>
 191       </listitem>
 192     </varlistentry>
 193
 194     <varlistentry>
 195       <term>When I <literal>foreign import</literal> a function that
 196       returns <literal>char</literal> or <literal>short</literal>, I
 197       get garbage back.</term>
 198       <listitem>
 199         <para>This is a known bug in GHC versions prior to 5.02.2.
 200         GHC doesn't mask out the more significant bits of the result.
 201         It doesn't manifest with gcc 2.95, but apparently shows up
 202         with g++ and gcc 3.0.</para>
 203       </listitem>
 204     </varlistentry>
 205   </variablelist>
 206 </chapter>
 207
 208
 209
 210 <!-- Emacs stuff:
 211      ;;; Local Variables: ***
 212      ;;; mode: sgml ***
 213      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 214      ;;; End: ***
 215  -->