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