Commit b4c60e5b authored by simonmar's avatar simonmar
Browse files

[project @ 2005-12-13 12:45:08 by simonmar]

the FAQ is now in the Wiki
parent 0a1d2631
<?xml version="1.0" encoding="iso-8859-1"?>
<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>
<para>Both ways require you to bootstrap from intermediate
<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>
<para>The <ulink url="http://www.haskell.org/ghc/latest/building/building-guide.html">Building
Guide</ulink> has all the details on how to bootstrap GHC on a
new platform.</para>
</listitem>
</varlistentry>
<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>
<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
with string gaps mentioned in <xref linkend="cpp-string-gaps" />.</para>
</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>
<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>
<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
linkend="options-C-compiler"/>).</para>
</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
changed the behaviour to match other OSs). A workaround for
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>
<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
raised. See <xref linkend="rts-options-debugging"/> for more
details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>How do I increase the heap size permanently for a given
binary?</term>
<listitem>
<para>See <xref linkend="rts-hooks"/>.</para>
</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>
<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>
<varlistentry>
<term>If I explicitly set the buffering on a Handle to
"NoBuffering" I'm not able to enter EOF by typing
"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>
<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
input &amp;- hGetLine
...</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>
<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>
<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>
<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
linkend="finding-header-files"/> for more details.</para>
</listitem>
</varlistentry>
<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>
<para>See <xref linkend="options-output"/> for more details on
the <option>-osuf</option> and <option>-hisuf</option>
options.</para>
</listitem>
</varlistentry>
<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>
<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>
</listitem>
</varlistentry>
<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>
<varlistentry>
<term>GHC puts <literal>stdin</literal> and <literal>stdout</literal> in
non-blocking mode, which causes problems when I try to invoke a text
editor (for example) using <literal>System.Cmd.system</literal> or
<literal>System.Cmd.rawSystem</literal>.</term>
<listitem>
<para>The real problem is that Unix shares the non-blocking flag
between all processes accessing a file or stream. It's impossible to
set this flag locally to a single process. GHC's I/O library needs
non-blocking mode to properly support multithreaded I/O.</para>
<para>Here's one possible fix, if you know that your program isn't
going to be accessing <literal>stdin</literal> from another thread
while the sub-process is running:</para>
<programlisting>
> main = do stdin `seq` return ()
> bracket (setFdOption stdInput NonBlockingRead False)
> (\_ -> setFdOption stdInput NonBlockingRead True)
> (\_ -> rawSystem "nvi" [])</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>Why doesn't GHC have a .NET back end?</term>
<listitem>
<para>See <ulink
url="http://www.haskell.org/pipermail/glasgow-haskell-users/2005-January/007594.html">this message</ulink> for a detailed answer to this question.</para>
</listitem>
</varlistentry>
</variablelist>
</chapter>
<!-- Emacs stuff:
;;; Local Variables: ***
;;; mode: xml ***
;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
;;; End: ***
-->
......@@ -20,7 +20,6 @@
&utils;
&win32-dll;
&bugs;
&faq;
<index/>
<!-- Emacs stuff:
......
<!ENTITY ghci SYSTEM "ghci.xml">
<!ENTITY faq SYSTEM "faq.xml">
<!ENTITY flags SYSTEM "flags.xml">
<!ENTITY license SYSTEM "license.xml">
<!ENTITY intro SYSTEM "intro.xml" >
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment