faq.xml 18.9 KB
Newer Older
1
<?xml version="1.0" encoding="iso-8859-1"?>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<chapter id="faq">
  <title>GHC FAQ</title>

  <para>This section has the answers to questions that get asked
  regularly on the GHC mailing lists, in no particular order.  Please
  let us know if you think there's a question/answer that should be
  added here.</para>
    
  <variablelist>
    <varlistentry>
      <term>How do I port GHC to platform X?</term>
      <listitem>
	<para>There are two distinct possibilities: either</para>
	<itemizedlist>
	  <listitem>
	    <para>The hardware architecture for your system is already
	    supported by GHC, but you're running an OS that isn't
	    supported (or perhaps has been supported in the past, but
	    currently isn't).  This is the easiest type of porting
	    job, but it still requires some careful
	    bootstrapping.</para>
	  </listitem>

	  <listitem>
	    <para>Your system's hardware architecture isn't supported
	    by GHC.  This will be a more difficult port (though by
	    comparison perhaps not as difficult as porting
	    gcc).</para>
	  </listitem>
	</itemizedlist>

ross's avatar
ross committed
33
	<para>Both ways require you to bootstrap from intermediate
34
35
36
37
38
39
	<literal>HC</literal> files: these are the stylised C files
	generated by GHC when it compiles Haskell source.  Basically
	the idea is to take the HC files for GHC itself to the target
	machine and compile them with <literal>gcc</literal> to get a
	working GHC, and go from there.</para>

40
	<para>The <ulink url="http://www.haskell.org/ghc/latest/building/building-guide.html">Building
41
42
43
44
45
46
	Guide</ulink> has all the details on how to bootstrap GHC on a
	new platform.</para>

      </listitem>
    </varlistentry>
    
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
    <varlistentry>
      <term>Do I have to recompile all my code if I upgrade
      GHC?</term>
      <listitem>
	<para>Yes.  There are two reasons for this:</para>
	<itemizedlist>
	  <listitem>
	    <para>GHC does a lot of cross-module optimisation, so
	    compiled code will include parts of the libraries it was
	    compiled against (including the Prelude), so will be
	    deeply tied to the actual version of those libraries it
	    was compiled against.  When you upgrade GHC, the libraries
	    may change; even if the external interface of the
	    libraries doesn't change, sometimes internal details may
	    change because GHC optimised the code in the library
	    differently.</para>
	  </listitem>
	  <listitem>
	    <para>We sometimes change the ABI (application binary
	    interface) between versions of GHC.  Code compiled with
	    one version of GHC is not necessarily compatible with code
	    compiled by a different version, even if you arrange to
	    keep the same libraries.</para>
	  </listitem>
	</itemizedlist>
      </listitem>
    </varlistentry>

75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
    <varlistentry>
      <term>Why doesn't GHC use shared libraries?</term>
      <listitem>
	<para>The subject of shared libraries has come up several
        times in the past &mdash; take a look through the mailing-list
        archives for some of the previous discussions. The upshot is
        that shared libraries wouldn't really buy much unless you
        really need to save the disk space: in all other
        considerations, static linking comes out better.</para>
	  
        <para>Unfortunately GHC-compiled libraries are very tightly
        coupled, which means it's unlikely you'd be able to swap out a
        shared library for a newer version unless it was compiled with
        <emphasis>exactly</emphasis> the same compiler and set of
        libraries as the old version.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>I can't get string gaps to work</term>
      <listitem>
	<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
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>GHCi complains about missing symbols like
      <literal>CC_LIST</literal> when loading a previously compiled .o
      file.</term>
      <listitem>
	<para> This probably means the .o files in question were
        compiled for profiling (with <option>-prof</option>).  Workaround:
        recompile them without profiling.  We really ought to detect
        this situation and give a proper error message.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Linking a program causes the following error on Linux:
      <literal>/usr/bin/ld: cannot open -lgmp: No such file or
      directory</literal></term>
      <listitem>
	<para>The problem is that your system doesn't have the GMP
        library installed.  If this is a RedHat distribution, install
        the RedHat-supplied <literal>gmp-devel</literal> package, and
        the <literal>gmp</literal> package if you don't already have
        it.  There have been reports that installing the RedHat
        packages also works for SuSE (SuSE don't supply a shared gmp
        library).</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>I Can't run GHCi on Linux, because it complains about a
      missing <literal>libreadline.so.3</literal>.</term>
      <listitem>
	<para>The "correct" fix for this problem is to install the
        correct RPM for the particular flavour of Linux on your
        machine.  If this isn't an option, however, there is a hack
        that might work: make a symbolic link from
        <filename>libreadline.so.4</filename> to
        <filename>libreadline.so.3</filename> in
        <literal>/usr/lib</literal>.  We tried this on a SuSE 7.1 box
        and it seemed to work, but YMMV.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Solaris users may sometimes get link errors due to
      libraries needed by GNU Readline.</term>
      <listitem>
	<para>We suggest you try linking in some combination of the
        <literal>termcap</literal>, <literal>curses</literal> and
        <literal>ncurses</literal> libraries, by giving
        <literal>-ltermcap</literal>, <literal>-lcurses</literal> and
        <literal>-lncurses</literal> respectively.  If you encounter
        this problem, we would appreciate feedback on it, since we
        don't fully understand what's going on here.</para>
      </listitem>
    </varlistentry>
    
157
158
159
160
161
162
163
164
165
166
167
    <varlistentry>
      <term>The build fails in readline.</term>
      <listitem>
	<para>It has been reported that if you have multiple versions
	of the readline library installed on Linux, then this may
	cause the build to fail.  If you have multiple versions of
	readline, try uninstalling all except the most recent
	version.</para>
      </listitem>
    </varlistentry>

168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
    <varlistentry>
      <term>When I try to start ghci (probably one I compiled myself)
      it says <literal>ghc-5.02: not built for interactive
      use</literal></term>
      <listitem>
	<para>To build a working ghci, you need to build GHC 5.02 with
        itself; the above message appears if you build it with 4.08.X,
        for example.  It'll still work fine for batch-mode
        compilation, though.  Note that you really must build with
        exactly the same version of the compiler.  Building 5.02 with
        5.00.2, for example, may or may not give a working interactive
        system; it probably won't, and certainly isn't supported.
        Note also that you can build 5.02 with any older compiler,
        back to 4.08.1, if you don't want a working interactive
        system; that's OK, and supported.</para>
      </listitem>
    </varlistentry>
   
    <varlistentry>
      <term>When I use a foreign function that takes or returns a
      float, it gives the wrong answer, or crashes.</term>
      <listitem>
	<para>You should use the <option>-#include</option> option to
	bring the correct prototype into scope (see <xref
192
	linkend="options-C-compiler"/>).</para>
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>My program that uses a really large heap crashes on
      Windows.</term>
      <listitem>
	<para>For utterly horrible reasons, programs that use more
        than 128Mb of heap won't work when compiled dynamically on
        Windows (they should be fine statically compiled).</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>GHC doesn't like filenames containing
      <literal>+</literal>.</term>
      <listitem>
	<para>Indeed not. You could change <literal>+</literal> to
	<literal>p</literal> or <literal>plus</literal>.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>When I open a FIFO (named pipe) and try to read from it, I
      get EOF immediately.</term>
      <listitem>
	<para>This is a consequence of the fact that GHC opens the
        FIFO in non-blocking mode.  The behaviour varies from OS to
        OS: on Linux and Solaris you can wait for a writer by doing an
        explicit <literal>threadWaitRead</literal> on the file
        descriptor (gotten from <literal>Posix.handleToFd</literal>)
        before the first read, but this doesn't work on FreeBSD
        (although rumour has it that recent versions of FreeBSD
ross's avatar
ross committed
226
        changed the behaviour to match other OSs).  A workaround for
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
        all systems is to open the FIFO for writing yourself, before
        (or at the same time as) opening it for reading.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>When I <literal>foreign import</literal> a function that
      returns <literal>char</literal> or <literal>short</literal>, I
      get garbage back.</term>
      <listitem>
	<para>This is a known bug in GHC versions prior to 5.02.2.
        GHC doesn't mask out the more significant bits of the result.
        It doesn't manifest with gcc 2.95, but apparently shows up
        with g++ and gcc 3.0.</para>
      </listitem>
    </varlistentry>
243
244
245
246
247
248
249
250
251
252
253

    <varlistentry>
      <term>My program is failing with <literal>head []</literal>, or
      an array bounds error, or some other random error, and I have no
      idea how to find the bug.  Can you help?</term>

      <listitem>
	<para>Compile your program with <literal>-prof
-auto-all</literal> (make sure you have the profiling libraries
installed), and run it with <literal>+RTS -xc -RTS</literal> to get a
&ldquo;stack trace&rdquo; at the point at which the exception was
254
raised.  See <xref linkend="rts-options-debugging"/> for more
255
256
257
258
259
260
261
262
details.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>How do I increase the heap size permanently for a given
      binary?</term>
      <listitem>
263
	<para>See <xref linkend="rts-hooks"/>.</para>
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>I'm trying to compile my program for parallel execution
      with the <option>-parallel</option>, and GHC complains with an
      error like &ldquo;failed to load interface file for
      Prelude&rdquo;.</term>
      <listitem>
	<para>GHC doesn't ship with support for parallel execution,
	that support is provided separately by the <ulink
							  url="http://www.macs.hw.ac.uk/~dsg/gph/">GPH</ulink> project.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>When is it safe to use
      <literal>unsafePerformIO</literal>?</term>
      <listitem>
	<para>We'll give two answers to this question, each of which
	may be helpful.  These criteria are not rigorous in any real
	sense (you'd need a formal semantics for Haskell in order to
	give a proper answer to this question), but should give you a
	feel for the kind of things you can and cannot do with
	<literal>unsafePerformIO</literal>.</para>
	
	<itemizedlist>
	  <listitem>
	    <para>It is safe to implement a function or API using
	    <literal>unsafePerformIO</literal> if you could imagine
	    also implementing the same function or API in Haskell
	    without using <literal>unsafePerformIO</literal> (forget
	    about efficiency, just consider the semantics).</para>
	  </listitem>

	  <listitem>
	    <para>In pure Haskell, the value of a function depends
	    only on the values of its arguments (and free variables,
	    if it has any).  If you can implement the function using
	    <literal>unsafePerformIO</literal> and still retain this
	    invariant, then you're probably using
	    <literal>unsafePerformIO</literal> in a safe way.  Note
	    that you need only consider the
	    <emphasis>observable</emphasis> values of the arguments
	    and result.</para>
	  </listitem>
	</itemizedlist>
	
	<para>For more information, see <ulink
	url="http://www.haskell.org/pipermail/glasgow-haskell-users/2002-July/003681.html">this
	thread</ulink>.</para>
      </listitem>
    </varlistentry>

318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
    <varlistentry>
      <term>Why does linking take so long?</term>
      <listitem>
	<para>Linking a small program should take no more than a few
	seconds.  Larger programs can take longer, but even linking
	GHC itself only takes 3-4 seconds on our development
	machines.</para>
	
	<para>Long link times have been attributed to using Sun's
	linker on Solaris, as compared to GNU <command>ld</command>
	which appears to be much faster.  So if you're on a Sun box,
	try switching to GNU <command>ld</command>.  <ulink
	url="http://www.haskell.org/pipermail/glasgow-haskell-users/2002-November/004477.html">This
	article</ulink> from the mailing list has more
	information.</para>
      </listitem>
    </varlistentry>

336
    <varlistentry> 
ross's avatar
ross committed
337
      <term>If I explicitly set the buffering on a Handle to
338
      "NoBuffering" I'm not able to enter EOF by typing
339
340
341
342
343
344
345
346
347
348
349
350
351
      "Ctrl-D".</term>

      <listitem>
	<para>This is a consequence of Unixy terminal semantics.  Unix
        does line buffering on terminals in the kernel as part of the
        terminal processing, unless you turn it off.  However, the
        Ctrl-D processing is also part of the terminal processing
        which gets turned off when the kernel line buffering is
        disabled.  So GHC tries its best to get NoBuffering semantics
        by turning off the kernel line buffering, but as a result you
        lose Ctrl-D.  C'est la vie.</para>
      </listitem>
    </varlistentry>
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371

    <varlistentry>
      <term>If I print out a string using <literal>putStr</literal>,
      and then attempt to read some input using
      <literal>hGetLine</literal>, I don't see the output from the
      <literal>putStr</literal>.</term>

      <listitem>
	<para>The <literal>stdout</literal> handle is line-buffered by
	default, which means that output sent to the handle is only
	flushed when a newline (<literal>/n</literal>) is output, the
	buffer is full, or <literal>hFlush</literal> is called on the
	Handle.  The right way to make the text appear without sending
	a newline is to use <literal>hFlush</literal>:</para>

<programlisting>
  import System.IO
  main = do
    putStr "how are you today? "
    hFlush stdout
372
    input &amp;- hGetLine
373
374
375
376
377
378
379
380
381
382
383
    ...</programlisting>

	<para>You'll probably find that the behaviour differs when
	using GHCi: the <literal>hFlush</literal> isn't necessary to
	make the text appear.  This is because in GHCi we turn off the
	buffering on <literal>stdout</literal>, because this is
	normally what you want in an interpreter: output appears as it
	is generated.</para>
      </listitem>
    </varlistentry>

384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
    <varlistentry>
      <term>I can't get finalizers to work properly.  My program
      sometimes just prints
      <literal>&lt;&lt;loop&gt;&gt;</literal>.</term>
      
      <listitem>
	<para>Chances are that your program is trying to write a
	message to <literal>stdout</literal> or
	<literal>stderr</literal> in the finalizer.  Handles have
	finalizers themselves, and since finalizers don't keep other
	finalized values alive, the <literal>stdout</literal> and
	<literal>stderr</literal> Handles may be finalized before your
	finalizer runs.  If this happens, your finalizer will block on
	the handle, and probably end up receiving a
	<literal>NonTermination</literal> exception (which is printed
	as <literal>&lt;&lt;loop&gt;&gt;</literal>).</para>
      </listitem>
    </varlistentry>
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416

    
    <varlistentry>
      <term>Does GHC implement any kind of extensible records?</term>

      <listitem>
	<para>No, extensible records are not implemented in GHC.
	<ulink url="http://www.haskell.org/hugs/">Hugs</ulink>
	implements TRex, one extensible record variant.  The problem
	is that the record design space is large, and seems to lack
	local optima.  And all reasonable variants break backward
	compatibility.  As a result, nothing much happens.</para>
      </listitem>
    </varlistentry>

417
418
419
420
421
422
423
424
425
426
427
    <varlistentry>
      <term>Why do I get errors about missing include files when
      compiling with <option>-O</option> or
      <option>-prof</option>?</term>

      <listitem>
	<para>Certain options, such as <option>-O</option>, turn on
	via-C compilation, instead of using the native code generator.
	Include files named by <option>-&num;include</option> options
	or in <literal>foreign import</literal> declarations are only
	used in via-C compilation mode.  See <xref
428
	linkend="finding-header-files"/> for more details.</para>
429
430
431
      </listitem>
    </varlistentry>

432
433
434
435
436
437
438
439
440
441
442
443
    <varlistentry>
      <term>How do I compile my program for profiling without
      overwriting the object files and <literal>hi</literal> files
      I've already built?</term>
      <listitem>
	<para>You can select alternative suffixes for object files and
	interface files, so you can have several builds of the same
	code coexisting in the same directory.  For example, to
	compile with profiling, you might do this:</para>
	
	<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
446
447
448
449
	the <option>-osuf</option> and <option>-hisuf</option>
	options.</para>
      </listitem>
    </varlistentry>

450
451
452
453
454
455
456
457
    <varlistentry>
      <term>I can't use readline under GHCi on Windows</term>
      <listitem>
	<para>In order to load the readline package under GHCi on Windows, you
	  need to make a version of the readline library that GHCi can load.
	  Instructions for GHC 6.2.2. are <ulink url="http://www.haskell.org/pipermail/glasgow-haskell-users/2004-November/007370.html">here</ulink>.</para>
      </listitem>
    </varlistentry>
458
459
460
461
462
463
464

    <varlistentry>
      <term>Ctrl-C doesn't work on Windows</term>
      <listitem>
	<para>When running GHC under a Cygwin shell on Windows, Ctrl-C
	  sometimes doesn't work.  The workaround is to use Ctrl-Break
	  instead.</para>
465
466
      </listitem>
    </varlistentry>
467

468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
    <varlistentry>
      <term>I get an error message from GHCi about a "duplicate definition for
	symbol __module_registered"</term>
      <listitem>
	<para>An error message like this:

<screen>
GHCi runtime linker: fatal error: I found a duplicate definition for symbol
       __module_registered
    whilst processing object file
       /usr/local/lib/ghc-6.2/HSfgl.o</screen>

	  probably indicates that when building a library for GHCi
	  (<filename>HSfgl.o</filename> in the above example), you should use
	  the <option>-x</option> option to <literal>ld</literal>.</para>
      </listitem>
    </varlistentry>
485
  </variablelist>
486

487
488
489
490
491
492
</chapter>



<!-- Emacs stuff:
     ;;; Local Variables: ***
493
494
     ;;; mode: xml ***
     ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
495
496
     ;;; End: ***
 -->