1 <?xml version="1.0" encoding="iso-8859-1"?>
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
12 <term>How do I port GHC to platform X?</term>
14 <para>There are two distinct possibilities: either</para>
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
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
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>
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
48 <term>Do I have to recompile all my code if I upgrade
51 <para>Yes. There are two reasons for this:</para>
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
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>
76 <term>Why doesn't GHC use shared libraries?</term>
78 <para>The subject of shared libraries has come up several
79 times in the past — 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>
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>
94 <term>I can't get string gaps to work</term>
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>
102 <term>GHCi complains about missing symbols like
103 <literal>CC_LIST</literal> when loading a previously compiled .o
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>
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>
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
129 <term>I Can't run GHCi on Linux, because it complains about a
130 missing <literal>libreadline.so.3</literal>.</term>
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>
144 <term>Solaris users may sometimes get link errors due to
145 libraries needed by GNU Readline.</term>
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>
158 <term>The build fails in readline.</term>
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
169 <term>When I try to start ghci (probably one I compiled myself)
170 it says <literal>ghc-5.02: not built for interactive
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>
187 <term>When I use a foreign function that takes or returns a
188 float, it gives the wrong answer, or crashes.</term>
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>
197 <term>My program that uses a really large heap crashes on
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>
207 <term>GHC doesn't like filenames containing
208 <literal>+</literal>.</term>
210 <para>Indeed not. You could change <literal>+</literal> to
211 <literal>p</literal> or <literal>plus</literal>.</para>
216 <term>When I open a FIFO (named pipe) and try to read from it, I
217 get EOF immediately.</term>
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>
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>
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>
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>
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 “stack trace” at the point at which the exception was
254 raised. See <xref linkend="rts-options-debugging"/> for more
260 <term>How do I increase the heap size permanently for a given
263 <para>See <xref linkend="rts-hooks"/>.</para>
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 “failed to load interface file for
271 Prelude”.</term>
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>
280 <term>When is it safe to use
281 <literal>unsafePerformIO</literal>?</term>
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>
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>
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
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>
319 <term>Why does linking take so long?</term>
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
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
337 <term>If I explicitly set the buffering on a Handle to
338 "NoBuffering" I'm not able to enter EOF by typing
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>
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>
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>
370 putStr "how are you today? "
372 input &- hGetLine
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
385 <term>I can't get finalizers to work properly. My program
386 sometimes just prints
387 <literal><<loop>></literal>.</term>
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><<loop>></literal>).</para>
405 <term>Does GHC implement any kind of extensible records?</term>
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>
418 <term>Why do I get errors about missing include files when
419 compiling with <option>-O</option> or
420 <option>-prof</option>?</term>
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>-#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>
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>
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>
442 <screen>ghc --make -prof -o foo-prof -osuf p.o -hisuf p.hi Main</screen>
444 <para>See <xref linkend="options-output"/> for more details on
445 the <option>-osuf</option> and <option>-hisuf</option>
451 <term>I can't use readline under GHCi on Windows</term>
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>
460 <term>Ctrl-C doesn't work on Windows</term>
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
469 <term>I get an error message from GHCi about a "duplicate definition for
470 symbol __module_registered"</term>
472 <para>An error message like this:
475 GHCi runtime linker: fatal error: I found a duplicate definition for symbol
477 whilst processing object file
478 /usr/local/lib/ghc-6.2/HSfgl.o</screen>
480 probably indicates that when building a library for GHCi
481 (<filename>HSfgl.o</filename> in the above example), you should use
482 the <option>-x</option> option to <literal>ld</literal>.</para>
487 <term>GHC puts <literal>stdin</literal> and <literal>stdout</literal> in
488 non-blocking mode, which causes problems when I try to invoke a text
489 editor (for example) using <literal>System.Cmd.system</literal> or
490 <literal>System.Cmd.rawSystem</literal>.</term>
493 <para>The real problem is that Unix shares the non-blocking flag
494 between all processes accessing a file or stream. It's impossible to
495 set this flag locally to a single process. GHC's I/O library needs
496 non-blocking mode to properly support multithreaded I/O.</para>
498 <para>Here's one possible fix, if you know that your program isn't
499 going to be accessing <literal>stdin</literal> from another thread
500 while the sub-process is running:</para>
503 > main = do stdin `seq` return ()
504 > bracket (setFdOption stdInput NonBlockingRead False)
505 > (\_ -> setFdOption stdInput NonBlockingRead True)
506 > (\_ -> rawSystem "nvi" [])</programlisting>
511 <term>Why doesn't GHC have a .NET back end?</term>
515 url="http://www.haskell.org/pipermail/glasgow-haskell-users/2005-January/007594.html">this message</ulink> for a detailed answer to this question.</para>
526 ;;; Local Variables: ***
528 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***