[project @ 2004-07-12 08:47:19 by simonmar]

[ghc-hetmet.git] / ghc / docs / users_guide / faq.sgml

diff --git a/ghc/docs/users_guide/faq.sgml b/ghc/docs/users_guide/faq.sgml
index 0c274d7..beda1cb 100644 (file)
--- a/ghc/docs/users_guide/faq.sgml
+++ b/ghc/docs/users_guide/faq.sgml
@@ -156,6 +156,17 @@
     </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>
@@ -323,7 +334,122 @@ details.</para>
       </listitem>
     </varlistentry>
 
+    <varlistentry> 
+      <term>If I explicitely 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>&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>
+
   </variablelist>
+
 </chapter>