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
11 <term>How do I port GHC to platform X?</term>
13 <para>There are two distinct possibilities: either</para>
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
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
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>
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
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
98 linkend="cpp-string-gaps">.</para>
103 <term>GHCi complains about missing symbols like
104 <literal>CC_LIST</literal> when loading a previously compiled .o
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>
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>
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
130 <term>I Can't run GHCi on Linux, because it complains about a
131 missing <literal>libreadline.so.3</literal>.</term>
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>
145 <term>Solaris users may sometimes get link errors due to
146 libraries needed by GNU Readline.</term>
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>
159 <term>When I try to start ghci (probably one I compiled myself)
160 it says <literal>ghc-5.02: not built for interactive
163 <para>To build a working ghci, you need to build GHC 5.02 with
164 itself; the above message appears if you build it with 4.08.X,
165 for example. It'll still work fine for batch-mode
166 compilation, though. Note that you really must build with
167 exactly the same version of the compiler. Building 5.02 with
168 5.00.2, for example, may or may not give a working interactive
169 system; it probably won't, and certainly isn't supported.
170 Note also that you can build 5.02 with any older compiler,
171 back to 4.08.1, if you don't want a working interactive
172 system; that's OK, and supported.</para>
177 <term>When I use a foreign function that takes or returns a
178 float, it gives the wrong answer, or crashes.</term>
180 <para>You should use the <option>-#include</option> option to
181 bring the correct prototype into scope (see <xref
182 linkend="options-C-compiler">).</para>
187 <term>My program that uses a really large heap crashes on
190 <para>For utterly horrible reasons, programs that use more
191 than 128Mb of heap won't work when compiled dynamically on
192 Windows (they should be fine statically compiled).</para>
197 <term>GHC doesn't like filenames containing
198 <literal>+</literal>.</term>
200 <para>Indeed not. You could change <literal>+</literal> to
201 <literal>p</literal> or <literal>plus</literal>.</para>
206 <term>When I open a FIFO (named pipe) and try to read from it, I
207 get EOF immediately.</term>
209 <para>This is a consequence of the fact that GHC opens the
210 FIFO in non-blocking mode. The behaviour varies from OS to
211 OS: on Linux and Solaris you can wait for a writer by doing an
212 explicit <literal>threadWaitRead</literal> on the file
213 descriptor (gotten from <literal>Posix.handleToFd</literal>)
214 before the first read, but this doesn't work on FreeBSD
215 (although rumour has it that recent versions of FreeBSD
216 changed the behavour to match other OSs). A workaround for
217 all systems is to open the FIFO for writing yourself, before
218 (or at the same time as) opening it for reading.</para>
223 <term>When I <literal>foreign import</literal> a function that
224 returns <literal>char</literal> or <literal>short</literal>, I
225 get garbage back.</term>
227 <para>This is a known bug in GHC versions prior to 5.02.2.
228 GHC doesn't mask out the more significant bits of the result.
229 It doesn't manifest with gcc 2.95, but apparently shows up
230 with g++ and gcc 3.0.</para>
235 <term>My program is failing with <literal>head []</literal>, or
236 an array bounds error, or some other random error, and I have no
237 idea how to find the bug. Can you help?</term>
240 <para>Compile your program with <literal>-prof
241 -auto-all</literal> (make sure you have the profiling libraries
242 installed), and run it with <literal>+RTS -xc -RTS</literal> to get a
243 “stack trace” at the point at which the exception was
244 raised. See <xref linkend="rts-options-debugging"> for more
250 <term>How do I increase the heap size permanently for a given
253 <para>See <xref linkend="rts-hooks">.</para>
258 <term>I'm trying to compile my program for parallel execution
259 with the <option>-parallel</option>, and GHC complains with an
260 error like “failed to load interface file for
261 Prelude”.</term>
263 <para>GHC doesn't ship with support for parallel execution,
264 that support is provided separately by the <ulink
265 url="http://www.macs.hw.ac.uk/~dsg/gph/">GPH</ulink> project.</para>
270 <term>When is it safe to use
271 <literal>unsafePerformIO</literal>?</term>
273 <para>We'll give two answers to this question, each of which
274 may be helpful. These criteria are not rigorous in any real
275 sense (you'd need a formal semantics for Haskell in order to
276 give a proper answer to this question), but should give you a
277 feel for the kind of things you can and cannot do with
278 <literal>unsafePerformIO</literal>.</para>
282 <para>It is safe to implement a function or API using
283 <literal>unsafePerformIO</literal> if you could imagine
284 also implementing the same function or API in Haskell
285 without using <literal>unsafePerformIO</literal> (forget
286 about efficiency, just consider the semantics).</para>
290 <para>In pure Haskell, the value of a function depends
291 only on the values of its arguments (and free variables,
292 if it has any). If you can implement the function using
293 <literal>unsafePerformIO</literal> and still retain this
294 invariant, then you're probably using
295 <literal>unsafePerformIO</literal> in a safe way. Note
296 that you need only consider the
297 <emphasis>observable</emphasis> values of the arguments
302 <para>For more information, see <ulink
303 url="http://www.haskell.org/pipermail/glasgow-haskell-users/2002-July/003681.html">this
304 thread</ulink>.</para>
309 <term>Why does linking take so long?</term>
311 <para>Linking a small program should take no more than a few
312 seconds. Larger programs can take longer, but even linking
313 GHC itself only takes 3-4 seconds on our development
316 <para>Long link times have been attributed to using Sun's
317 linker on Solaris, as compared to GNU <command>ld</command>
318 which appears to be much faster. So if you're on a Sun box,
319 try switching to GNU <command>ld</command>. <ulink
320 url="http://www.haskell.org/pipermail/glasgow-haskell-users/2002-November/004477.html">This
321 article</ulink> from the mailing list has more
332 ;;; Local Variables: ***
334 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***