ghc/docs/users_guide/faq.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <chapter id="faq">
   3   <title>GHC FAQ</title>
   4
   5   <para>This section has the answers to questions that get asked
   6   regularly on the GHC mailing lists, in no particular order.  Please
   7   let us know if you think there's a question/answer that should be
   8   added here.</para>
   9
  10   <variablelist>
  11     <varlistentry>
  12       <term>How do I port GHC to platform X?</term>
  13       <listitem>
  14         <para>There are two distinct possibilities: either</para>
  15         <itemizedlist>
  16           <listitem>
  17             <para>The hardware architecture for your system is already
  18             supported by GHC, but you're running an OS that isn't
  19             supported (or perhaps has been supported in the past, but
  20             currently isn't).  This is the easiest type of porting
  21             job, but it still requires some careful
  22             bootstrapping.</para>
  23           </listitem>
  24
  25           <listitem>
  26             <para>Your system's hardware architecture isn't supported
  27             by GHC.  This will be a more difficult port (though by
  28             comparison perhaps not as difficult as porting
  29             gcc).</para>
  30           </listitem>
  31         </itemizedlist>
  32
  33         <para>Both ways require you to bootstrap from intermediate
  34         <literal>HC</literal> files: these are the stylised C files
  35         generated by GHC when it compiles Haskell source.  Basically
  36         the idea is to take the HC files for GHC itself to the target
  37         machine and compile them with <literal>gcc</literal> to get a
  38         working GHC, and go from there.</para>
  39
  40         <para>The <ulink
  41         url="http://www.haskell.org/ghc/latest/building/building-guide.html">Building
  42         Guide</ulink> has all the details on how to bootstrap GHC on a
  43         new platform.</para>
  44
  45       </listitem>
  46     </varlistentry>
  47
  48     <varlistentry>
  49       <term>Do I have to recompile all my code if I upgrade
  50       GHC?</term>
  51       <listitem>
  52         <para>Yes.  There are two reasons for this:</para>
  53         <itemizedlist>
  54           <listitem>
  55             <para>GHC does a lot of cross-module optimisation, so
  56             compiled code will include parts of the libraries it was
  57             compiled against (including the Prelude), so will be
  58             deeply tied to the actual version of those libraries it
  59             was compiled against.  When you upgrade GHC, the libraries
  60             may change; even if the external interface of the
  61             libraries doesn't change, sometimes internal details may
  62             change because GHC optimised the code in the library
  63             differently.</para>
  64           </listitem>
  65           <listitem>
  66             <para>We sometimes change the ABI (application binary
  67             interface) between versions of GHC.  Code compiled with
  68             one version of GHC is not necessarily compatible with code
  69             compiled by a different version, even if you arrange to
  70             keep the same libraries.</para>
  71           </listitem>
  72         </itemizedlist>
  73       </listitem>
  74     </varlistentry>
  75
  76     <varlistentry>
  77       <term>Why doesn't GHC use shared libraries?</term>
  78       <listitem>
  79         <para>The subject of shared libraries has come up several
  80         times in the past &mdash; take a look through the mailing-list
  81         archives for some of the previous discussions. The upshot is
  82         that shared libraries wouldn't really buy much unless you
  83         really need to save the disk space: in all other
  84         considerations, static linking comes out better.</para>
  85
  86         <para>Unfortunately GHC-compiled libraries are very tightly
  87         coupled, which means it's unlikely you'd be able to swap out a
  88         shared library for a newer version unless it was compiled with
  89         <emphasis>exactly</emphasis> the same compiler and set of
  90         libraries as the old version.</para>
  91       </listitem>
  92     </varlistentry>
  93
  94     <varlistentry>
  95       <term>I can't get string gaps to work</term>
  96       <listitem>
  97         <para>If you're also using CPP, beware of the known pitfall
  98         with string gaps mentioned in <xref
  99         linkend="cpp-string-gaps"/>.</para>
 100       </listitem>
 101     </varlistentry>
 102
 103     <varlistentry>
 104       <term>GHCi complains about missing symbols like
 105       <literal>CC_LIST</literal> when loading a previously compiled .o
 106       file.</term>
 107       <listitem>
 108         <para> This probably means the .o files in question were
 109         compiled for profiling (with <option>-prof</option>).  Workaround:
 110         recompile them without profiling.  We really ought to detect
 111         this situation and give a proper error message.</para>
 112       </listitem>
 113     </varlistentry>
 114
 115     <varlistentry>
 116       <term>Linking a program causes the following error on Linux:
 117       <literal>/usr/bin/ld: cannot open -lgmp: No such file or
 118       directory</literal></term>
 119       <listitem>
 120         <para>The problem is that your system doesn't have the GMP
 121         library installed.  If this is a RedHat distribution, install
 122         the RedHat-supplied <literal>gmp-devel</literal> package, and
 123         the <literal>gmp</literal> package if you don't already have
 124         it.  There have been reports that installing the RedHat
 125         packages also works for SuSE (SuSE don't supply a shared gmp
 126         library).</para>
 127       </listitem>
 128     </varlistentry>
 129
 130     <varlistentry>
 131       <term>I Can't run GHCi on Linux, because it complains about a
 132       missing <literal>libreadline.so.3</literal>.</term>
 133       <listitem>
 134         <para>The "correct" fix for this problem is to install the
 135         correct RPM for the particular flavour of Linux on your
 136         machine.  If this isn't an option, however, there is a hack
 137         that might work: make a symbolic link from
 138         <filename>libreadline.so.4</filename> to
 139         <filename>libreadline.so.3</filename> in
 140         <literal>/usr/lib</literal>.  We tried this on a SuSE 7.1 box
 141         and it seemed to work, but YMMV.</para>
 142       </listitem>
 143     </varlistentry>
 144
 145     <varlistentry>
 146       <term>Solaris users may sometimes get link errors due to
 147       libraries needed by GNU Readline.</term>
 148       <listitem>
 149         <para>We suggest you try linking in some combination of the
 150         <literal>termcap</literal>, <literal>curses</literal> and
 151         <literal>ncurses</literal> libraries, by giving
 152         <literal>-ltermcap</literal>, <literal>-lcurses</literal> and
 153         <literal>-lncurses</literal> respectively.  If you encounter
 154         this problem, we would appreciate feedback on it, since we
 155         don't fully understand what's going on here.</para>
 156       </listitem>
 157     </varlistentry>
 158
 159     <varlistentry>
 160       <term>The build fails in readline.</term>
 161       <listitem>
 162         <para>It has been reported that if you have multiple versions
 163         of the readline library installed on Linux, then this may
 164         cause the build to fail.  If you have multiple versions of
 165         readline, try uninstalling all except the most recent
 166         version.</para>
 167       </listitem>
 168     </varlistentry>
 169
 170     <varlistentry>
 171       <term>When I try to start ghci (probably one I compiled myself)
 172       it says <literal>ghc-5.02: not built for interactive
 173       use</literal></term>
 174       <listitem>
 175         <para>To build a working ghci, you need to build GHC 5.02 with
 176         itself; the above message appears if you build it with 4.08.X,
 177         for example.  It'll still work fine for batch-mode
 178         compilation, though.  Note that you really must build with
 179         exactly the same version of the compiler.  Building 5.02 with
 180         5.00.2, for example, may or may not give a working interactive
 181         system; it probably won't, and certainly isn't supported.
 182         Note also that you can build 5.02 with any older compiler,
 183         back to 4.08.1, if you don't want a working interactive
 184         system; that's OK, and supported.</para>
 185       </listitem>
 186     </varlistentry>
 187
 188     <varlistentry>
 189       <term>When I use a foreign function that takes or returns a
 190       float, it gives the wrong answer, or crashes.</term>
 191       <listitem>
 192         <para>You should use the <option>-#include</option> option to
 193         bring the correct prototype into scope (see <xref
 194         linkend="options-C-compiler"/>).</para>
 195       </listitem>
 196     </varlistentry>
 197
 198     <varlistentry>
 199       <term>My program that uses a really large heap crashes on
 200       Windows.</term>
 201       <listitem>
 202         <para>For utterly horrible reasons, programs that use more
 203         than 128Mb of heap won't work when compiled dynamically on
 204         Windows (they should be fine statically compiled).</para>
 205       </listitem>
 206     </varlistentry>
 207
 208     <varlistentry>
 209       <term>GHC doesn't like filenames containing
 210       <literal>+</literal>.</term>
 211       <listitem>
 212         <para>Indeed not. You could change <literal>+</literal> to
 213         <literal>p</literal> or <literal>plus</literal>.</para>
 214       </listitem>
 215     </varlistentry>
 216
 217     <varlistentry>
 218       <term>When I open a FIFO (named pipe) and try to read from it, I
 219       get EOF immediately.</term>
 220       <listitem>
 221         <para>This is a consequence of the fact that GHC opens the
 222         FIFO in non-blocking mode.  The behaviour varies from OS to
 223         OS: on Linux and Solaris you can wait for a writer by doing an
 224         explicit <literal>threadWaitRead</literal> on the file
 225         descriptor (gotten from <literal>Posix.handleToFd</literal>)
 226         before the first read, but this doesn't work on FreeBSD
 227         (although rumour has it that recent versions of FreeBSD
 228         changed the behaviour to match other OSs).  A workaround for
 229         all systems is to open the FIFO for writing yourself, before
 230         (or at the same time as) opening it for reading.</para>
 231       </listitem>
 232     </varlistentry>
 233
 234     <varlistentry>
 235       <term>When I <literal>foreign import</literal> a function that
 236       returns <literal>char</literal> or <literal>short</literal>, I
 237       get garbage back.</term>
 238       <listitem>
 239         <para>This is a known bug in GHC versions prior to 5.02.2.
 240         GHC doesn't mask out the more significant bits of the result.
 241         It doesn't manifest with gcc 2.95, but apparently shows up
 242         with g++ and gcc 3.0.</para>
 243       </listitem>
 244     </varlistentry>
 245
 246     <varlistentry>
 247       <term>My program is failing with <literal>head []</literal>, or
 248       an array bounds error, or some other random error, and I have no
 249       idea how to find the bug.  Can you help?</term>
 250
 251       <listitem>
 252         <para>Compile your program with <literal>-prof
 253 -auto-all</literal> (make sure you have the profiling libraries
 254 installed), and run it with <literal>+RTS -xc -RTS</literal> to get a
 255 &ldquo;stack trace&rdquo; at the point at which the exception was
 256 raised.  See <xref linkend="rts-options-debugging"/> for more
 257 details.</para>
 258       </listitem>
 259     </varlistentry>
 260
 261     <varlistentry>
 262       <term>How do I increase the heap size permanently for a given
 263       binary?</term>
 264       <listitem>
 265         <para>See <xref linkend="rts-hooks"/>.</para>
 266       </listitem>
 267     </varlistentry>
 268
 269     <varlistentry>
 270       <term>I'm trying to compile my program for parallel execution
 271       with the <option>-parallel</option>, and GHC complains with an
 272       error like &ldquo;failed to load interface file for
 273       Prelude&rdquo;.</term>
 274       <listitem>
 275         <para>GHC doesn't ship with support for parallel execution,
 276         that support is provided separately by the <ulink
 277                                                           url="http://www.macs.hw.ac.uk/~dsg/gph/">GPH</ulink> project.</para>
 278       </listitem>
 279     </varlistentry>
 280
 281     <varlistentry>
 282       <term>When is it safe to use
 283       <literal>unsafePerformIO</literal>?</term>
 284       <listitem>
 285         <para>We'll give two answers to this question, each of which
 286         may be helpful.  These criteria are not rigorous in any real
 287         sense (you'd need a formal semantics for Haskell in order to
 288         give a proper answer to this question), but should give you a
 289         feel for the kind of things you can and cannot do with
 290         <literal>unsafePerformIO</literal>.</para>
 291
 292         <itemizedlist>
 293           <listitem>
 294             <para>It is safe to implement a function or API using
 295             <literal>unsafePerformIO</literal> if you could imagine
 296             also implementing the same function or API in Haskell
 297             without using <literal>unsafePerformIO</literal> (forget
 298             about efficiency, just consider the semantics).</para>
 299           </listitem>
 300
 301           <listitem>
 302             <para>In pure Haskell, the value of a function depends
 303             only on the values of its arguments (and free variables,
 304             if it has any).  If you can implement the function using
 305             <literal>unsafePerformIO</literal> and still retain this
 306             invariant, then you're probably using
 307             <literal>unsafePerformIO</literal> in a safe way.  Note
 308             that you need only consider the
 309             <emphasis>observable</emphasis> values of the arguments
 310             and result.</para>
 311           </listitem>
 312         </itemizedlist>
 313
 314         <para>For more information, see <ulink
 315         url="http://www.haskell.org/pipermail/glasgow-haskell-users/2002-July/003681.html">this
 316         thread</ulink>.</para>
 317       </listitem>
 318     </varlistentry>
 319
 320     <varlistentry>
 321       <term>Why does linking take so long?</term>
 322       <listitem>
 323         <para>Linking a small program should take no more than a few
 324         seconds.  Larger programs can take longer, but even linking
 325         GHC itself only takes 3-4 seconds on our development
 326         machines.</para>
 327
 328         <para>Long link times have been attributed to using Sun's
 329         linker on Solaris, as compared to GNU <command>ld</command>
 330         which appears to be much faster.  So if you're on a Sun box,
 331         try switching to GNU <command>ld</command>.  <ulink
 332         url="http://www.haskell.org/pipermail/glasgow-haskell-users/2002-November/004477.html">This
 333         article</ulink> from the mailing list has more
 334         information.</para>
 335       </listitem>
 336     </varlistentry>
 337
 338     <varlistentry>
 339       <term>If I explicitly set the buffering on a Handle to
 340       "NoBuffering" I'm not able to enter EOF by typing
 341       "Ctrl-D".</term>
 342
 343       <listitem>
 344         <para>This is a consequence of Unixy terminal semantics.  Unix
 345         does line buffering on terminals in the kernel as part of the
 346         terminal processing, unless you turn it off.  However, the
 347         Ctrl-D processing is also part of the terminal processing
 348         which gets turned off when the kernel line buffering is
 349         disabled.  So GHC tries its best to get NoBuffering semantics
 350         by turning off the kernel line buffering, but as a result you
 351         lose Ctrl-D.  C'est la vie.</para>
 352       </listitem>
 353     </varlistentry>
 354
 355     <varlistentry>
 356       <term>If I print out a string using <literal>putStr</literal>,
 357       and then attempt to read some input using
 358       <literal>hGetLine</literal>, I don't see the output from the
 359       <literal>putStr</literal>.</term>
 360
 361       <listitem>
 362         <para>The <literal>stdout</literal> handle is line-buffered by
 363         default, which means that output sent to the handle is only
 364         flushed when a newline (<literal>/n</literal>) is output, the
 365         buffer is full, or <literal>hFlush</literal> is called on the
 366         Handle.  The right way to make the text appear without sending
 367         a newline is to use <literal>hFlush</literal>:</para>
 368
 369 <programlisting>
 370   import System.IO
 371   main = do
 372     putStr "how are you today? "
 373     hFlush stdout
 374     input &amp;- hGetLine
 375     ...</programlisting>
 376
 377         <para>You'll probably find that the behaviour differs when
 378         using GHCi: the <literal>hFlush</literal> isn't necessary to
 379         make the text appear.  This is because in GHCi we turn off the
 380         buffering on <literal>stdout</literal>, because this is
 381         normally what you want in an interpreter: output appears as it
 382         is generated.</para>
 383       </listitem>
 384     </varlistentry>
 385
 386     <varlistentry>
 387       <term>I can't get finalizers to work properly.  My program
 388       sometimes just prints
 389       <literal>&lt;&lt;loop&gt;&gt;</literal>.</term>
 390
 391       <listitem>
 392         <para>Chances are that your program is trying to write a
 393         message to <literal>stdout</literal> or
 394         <literal>stderr</literal> in the finalizer.  Handles have
 395         finalizers themselves, and since finalizers don't keep other
 396         finalized values alive, the <literal>stdout</literal> and
 397         <literal>stderr</literal> Handles may be finalized before your
 398         finalizer runs.  If this happens, your finalizer will block on
 399         the handle, and probably end up receiving a
 400         <literal>NonTermination</literal> exception (which is printed
 401         as <literal>&lt;&lt;loop&gt;&gt;</literal>).</para>
 402       </listitem>
 403     </varlistentry>
 404
 405
 406     <varlistentry>
 407       <term>Does GHC implement any kind of extensible records?</term>
 408
 409       <listitem>
 410         <para>No, extensible records are not implemented in GHC.
 411         <ulink url="http://www.haskell.org/hugs/">Hugs</ulink>
 412         implements TRex, one extensible record variant.  The problem
 413         is that the record design space is large, and seems to lack
 414         local optima.  And all reasonable variants break backward
 415         compatibility.  As a result, nothing much happens.</para>
 416       </listitem>
 417     </varlistentry>
 418
 419     <varlistentry>
 420       <term>Why do I get errors about missing include files when
 421       compiling with <option>-O</option> or
 422       <option>-prof</option>?</term>
 423
 424       <listitem>
 425         <para>Certain options, such as <option>-O</option>, turn on
 426         via-C compilation, instead of using the native code generator.
 427         Include files named by <option>-&num;include</option> options
 428         or in <literal>foreign import</literal> declarations are only
 429         used in via-C compilation mode.  See <xref
 430         linkend="finding-header-files"/> for more details.</para>
 431       </listitem>
 432     </varlistentry>
 433
 434     <varlistentry>
 435       <term>How do I compile my program for profiling without
 436       overwriting the object files and <literal>hi</literal> files
 437       I've already built?</term>
 438       <listitem>
 439         <para>You can select alternative suffixes for object files and
 440         interface files, so you can have several builds of the same
 441         code coexisting in the same directory.  For example, to
 442         compile with profiling, you might do this:</para>
 443
 444         <screen>ghc --make -prof -o foo-prof -osuf p.o -hisuf p.hi Main</screen>
 445
 446         <para>See <xref linkend="options-output"/> for more details on
 447         the <option>-osuf</option> and <option>-hisuf</option>
 448         options.</para>
 449       </listitem>
 450     </varlistentry>
 451
 452   </variablelist>
 453
 454 </chapter>
 455
 456
 457
 458 <!-- Emacs stuff:
 459      ;;; Local Variables: ***
 460      ;;; mode: xml ***
 461      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
 462      ;;; End: ***
 463  -->