+++ /dev/null
-<?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 — 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
-“stack trace” 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 “failed to load interface file for
- Prelude”.</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 &- 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><<loop>></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><<loop>></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>-#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: ***
- -->