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