<indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm>
<indexterm><primary>Foreign Function Interface</primary><secondary>GHCi support</secondary></indexterm>
- <sect1>
+ <sect1 id="ghci-introduction">
<title>Introduction to GHCi</title>
<para>Let's start with an example GHCi session. You can fire up
enter, GHCi will attempt to evaluate it.</para>
</sect1>
- <sect1>
+ <sect1 id="loading-source-files">
<title>Loading source files</title>
<para>Suppose we have the following Haskell source code, which we
</sect1>
- <sect1>
+ <sect1 id="interactive-evaluation">
<title>Interactive evaluation at the prompt</title>
<para>When you type an expression at the prompt, GHCi immediately
standard rules take each group of constraints <literal>(C1 a, C2 a, ..., Cn
a)</literal> for each type variable <literal>a</literal>, and defaults the
type variable if
- <itemizedlist>
- <listitem><para> The type variable <literal>a</literal>
- appears in no other constraints </para></listitem>
- <listitem><para> All the classes <literal>Ci</literal> are standard.</para></listitem>
- <listitem><para> At least one of the classes <literal>Ci</literal> is
- numeric.</para></listitem>
- </itemizedlist>
- At the GHCi prompt, the second and third rules are relaxed as follows
- (differences italicised):
- <itemizedlist>
- <listitem><para> <emphasis>All</emphasis> of the classes
- <literal>Ci</literal> are single-parameter type classes.</para></listitem>
- <listitem><para> At least one of the classes <literal>Ci</literal> is
- numeric, <emphasis>or is <literal>Show</literal>,
- <literal>Eq</literal>, or <literal>Ord</literal></emphasis>.</para></listitem>
- </itemizedlist>
- The same type-default behaviour can be enabled in an ordinary Haskell
- module, using the flag <literal>-fextended-default-rules</literal>.
+ <orderedlist>
+ <listitem>
+ <para>
+ The type variable <literal>a</literal> appears in no
+ other constraints
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All the classes <literal>Ci</literal> are standard.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ At least one of the classes <literal>Ci</literal> is
+ numeric.
+ </para>
+ </listitem>
+ </orderedlist>
+ At the GHCi prompt, or with GHC if the
+ <literal>-fextended-default-rules</literal> flag is given,
+ the following additional differences apply:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Rule 2 above is relaxed thus:
+ <emphasis>All</emphasis> of the classes
+ <literal>Ci</literal> are single-parameter type classes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Rule 3 above is relaxed this:
+ At least one of the classes <literal>Ci</literal> is
+ numeric, <emphasis>or is <literal>Show</literal>,
+ <literal>Eq</literal>, or
+ <literal>Ord</literal></emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The unit type <literal>()</literal> is added to the
+ start of the standard list of types which are tried when
+ doing type defaulting.
+ </para>
+ </listitem>
+ </itemizedlist>
+ The last point means that, for example, this program:
+<programlisting>
+main :: IO ()
+main = print def
+
+instance Num ()
+
+def :: (Num a, Enum a) => a
+def = toEnum 0
+</programlisting>
+ prints <literal>()</literal> rather than <literal>0</literal> as the
+ type is defaulted to <literal>()</literal> rather than
+ <literal>Integer</literal>.
+ </para>
+ <para>
+ The motivation for the change is that it means <literal>IO a</literal>
+ actions default to <literal>IO ()</literal>, which in turn means that
+ ghci won't try to print a result when running them. This is
+ particularly important for <literal>printf</literal>, which has an
+ instance that returns <literal>IO a</literal>.
+ However, it is only able to return
+ <literal>undefined</literal>
+ (the reason for the instance having this type is to not require
+ extensions to the class system), so if the type defaults to
+ <literal>Integer</literal> then ghci gives an error when running a
+ printf.
</para>
</sect2>
</sect1>
<literal>:continue</literal>
<indexterm><primary><literal>:continue</literal></primary></indexterm>
</term>
- <listitem> Shortcut to <literal>:breakpoint continue </literal>
+ <listitem><para>Shortcut to <literal>:breakpoint continue</literal></para>
</listitem>
</varlistentry>
Prelude> head li
Just 1
Prelude> :sp li
-li - [Just 1 | _]
+li - Just 1 : _
Prelude> :p li
-li - [Just 1 | (_t2::[Maybe Integer])]
+li - Just 1 : (_t2::[Maybe Integer])
Prelude> last li
Just 5
Prelude> :sp li
The example uses <literal>:print</literal> and <literal>:sprint</literal>
to help us observe how the <literal>li</literal> variable is evaluated progressively as we operate
with it. Note for instance how <quote>last</quote> traverses all the elements of
- the list to compute its result, but without evaluating the individual elements.</para>
- <para>Finally note that the Prolog convention of [head | tail] is used by
- <literal>:sprint</literal> to display unevaluated lists.
+ the list to compute its result, but without evaluating the individual elements.
</para>
</listitem>
</varlistentry>
Prelude> head li
Just 1
Prelude> :sp li
-li - [Just 1 | _]
+li - Just 1 : _
Prelude> last li
Just 5
Prelude> :sp li
</screen>
The example uses <literal>:sprint</literal> to help us observe how the <literal>li</literal> variable is evaluated progressively as we operate
with it. Note for instance how <quote>last</quote> traverses all the elements of
- the list to compute its result, but without evaluating the individual elements.</para>
- <para>Finally note that the Prolog convention of [head | tail] is used by
- <literal>:sprint</literal> to display unevaluated lists.
+ the list to compute its result, but without evaluating the individual elements.
</para>
</listitem>
</varlistentry>
qsort2.hs:2:15-46>
</programlisting>
What is happening here is that GHCi has interrupted the evaluation of
- <code>qsort</code> at the breakpoint set in line 2, as the prompt indicates.
+ <literal>qsort</literal> at the breakpoint set in line 2, as the prompt indicates.
At this point you can freely explore the contents of the bindings in scope,
but with two catches. </para><para>
First, take into account that due to the lazy nature of Haskell, some of
trigger a computation. </para><para>
Second: look at the types of the things in scope.
GHCi has left its types parameterised by a variable!
- Look at the type of <code>qsort</code>, which is
+ Look at the type of <literal>qsort</literal>, which is
polymorphic on the type of its argument. It does not
- tell us really what the types of <code>x</code> and <code>xs</code> can be.
+ tell us really what the types of <literal>x</literal> and <literal>xs</literal> can be.
In general, polymorphic programs deal with polymorphic values,
and this means that some of the bindings available in a breakpoint site
will be parametrically typed.
This is useful because you cannot just type <literal>x</literal> in the
prompt and expect GHCi to return you its value. Perhaps you know for
sure that
- <literal>x</literal> is of type <code>Int</code>, which is an instance of
- <code>Show</code>, but GHCi does not have this information.
- <code>:print</code> however is fine, because it does not need to know the
+ <literal>x</literal> is of type <literal>Int</literal>, which is an instance of
+ <literal>Show</literal>, but GHCi does not have this information.
+ <literal>:print</literal> however is fine, because it does not need to know the
type to do its work. </para>
- <para> Let's go on with the debugging session of the <code>qsort</code>
+ <para> Let's go on with the debugging session of the <literal>qsort</literal>
example:
<example id="debuggingEx"><title>A short debugging session</title>
<programlisting>
<para>GHCi reminds us that this value is untyped, and instructs us to force its evaluation </para>
</callout>
<callout arearefs="seq2">
- <para>This line forces the evaluation of <code>x</code> </para>
+ <para>This line forces the evaluation of <literal>x</literal> </para>
</callout>
<callout arearefs="seq3">
<para>Even though x has been evaluated, we cannot simply use its name to see its value!
This is a bit counterintuitive, but currently in GHCi the type of a binding
- cannot be a type variable <code>a</code>.
- Thus, the binding <code>x</code> gets assigned the concrete type Unknown.</para>
+ cannot be a type variable <literal>a</literal>.
+ Thus, the binding <literal>x</literal> gets assigned the concrete type Unknown.</para>
</callout>
<callout arearefs="seq4">
- <para>We can explore <code>x</code> using the <literal>:print</literal>
- command, which does find out that <code>x</code> is of type Int and prints
+ <para>We can explore <literal>x</literal> using the <literal>:print</literal>
+ command, which does find out that <literal>x</literal> is of type Int and prints
its value accordingly.</para>
</callout>
<callout arearefs="seq5">
- <literal>:print</literal> also updates the type of <code>x</code> with
- the most concrete type information available.
+ <para><literal>:print</literal> also updates the type of <literal>x</literal> with
+ the most concrete type information available.</para>
</callout>
</calloutlist>
The example shows the standard way to proceeed with polymorphic values in a breakpoint.
</varlistentry>
</variablelist></para>
</sect2>
- <sect2><title>Limitations</title>
- <para>
- <itemizedlist>
- <listitem><para>
- <xref linkend="implicit-parameters" xrefstyle="select: title"/> are only available
- at the scope of a breakpoint if there is a explicit type signature.
- </para></listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem><para>
- Modules compiled by GHCi under the <literal>-fdebugging
- </literal> flag will perform slower: the debugging mode introduces some overhead.
- Modules compiled to object code by ghc are not affected.
- </para></listitem>
- </itemizedlist>
- </para>
+ <sect2><title>Debugging Higher-Order functions</title>
+ It is possible to use the debugger to examine lambdas.
+ When we are at a breakpoint and a lambda is in scope, the debugger cannot show
+ you the source code that constitutes it; however, it is possible to get some
+ information by applying it to some arguments and observing the result.
+
+ The process is slightly complicated when the binding is polymorphic.
+ We will use a example to show the process.
+ To keep it simple, we will use the well known <literal>map</literal> function:
+ <programlisting>
+import Prelude hiding (map)
+
+map :: (a->b) -> a -> b
+map f [] = []
+map f (x:xs) = f x : map f xs
+ </programlisting>
+ We set a breakpoint on <literal>map</literal>, and call it.
+ <programlisting>
+*Main> :break map
+Breakpoint 0 activated at map.hs:(4,0)-(5,12)
+*Main> map Just [1..5]
+Stopped at map.hs:(4,0)-(5,12)
+_result :: [b]
+x :: a
+f :: a -> b
+xs :: [a]
+ </programlisting>
+ GHCi tells us that, among other bindings, <literal>f</literal> is in scope.
+ However, its type is not fully known yet,
+ and thus it is not possible to apply it yet to any
+ arguments. Nevertheless, observe that the type of its first argument is the
+ same as the type of <literal>x</literal>, and its result type is the
+ same as the type of <literal>_result</literal>.
+ The debugger has some intelligence built-in to update the type of
+ <literal>f</literal> whenever the types of <literal>x</literal> or
+ <literal>_result</literal> are reconstructed. So what we do in this scenario is
+ force <literal>x</literal> a bit, in order to recover both its type
+ and the argument part of <literal>f</literal>.
+ <programlisting>
+*Main> seq x ()
+*Main> :print x
+x = 1
+ </programlisting>
+ We can check now that as expected, the type of <literal>x</literal>
+ has been reconstructed, and with it the
+ type of <literal>f</literal> has been too:
+ <programlisting>
+*Main> :t x
+x :: Integer
+*Main> :t f
+f :: Integer -> b
+ </programlisting>
+ From here, we can apply f to any argument of type Integer and observe the
+ results.
+ <programlisting><![CDATA[
+*Main> let b = f 10
+*Main> :t b
+b :: b
+*Main> b
+<interactive>:1:0:
+ Ambiguous type variable `b' in the constraint:
+ `Show b' arising from a use of `print' at <interactive>:1:0
+*Main> :p b
+b = (_t2::a)
+*Main> seq b ()
+()
+*Main> :t b
+b :: a
+*Main> :p b
+b = Just 10
+*Main> :t b
+b :: Maybe Integer
+*Main> :t f
+f :: Integer -> Maybe Integer
+*Main> f 20
+Just 20
+*Main> map f [1..5]
+[Just 1, Just 2, Just 3, Just 4, Just 5]
+ ]]></programlisting>
+ In the first application of <literal>f</literal>, we had to do
+ some more type reconstruction
+ in order to recover the result type of <literal>f</literal>.
+ But after that, we are free to use
+ <literal>f</literal> normally.
</sect2>
<sect2><title>Tips</title>
<variablelist>
<programlisting>{-# OPTIONS_GHC -fdebugging #-}</programlisting>
</listitem>
</varlistentry>
- <varlistentry> <term>* Repeated use of <code>seq</code> and
+ <varlistentry> <term>* Repeated use of <literal>seq</literal> and
<literal>:print</literal> may be necessary to observe unevaluated
untyped bindings</term>
<listitem><para>see <xref linkend="debuggingEx"/>
</para></listitem>
</varlistentry>
- <varlistentry> <term> * <code>GHC.Exts.unsafeCoerce</code> can help if you are positive about the type of a binding</term>
+ <varlistentry> <term> * <literal>GHC.Exts.unsafeCoerce</literal> can help if you are positive about the type of a binding</term>
<listitem><para><programlisting>
type MyLongType a = [Maybe [Maybe a]]
-main:Main> :m +GHC.Exts
-main:Main> main
+*Main> :m +GHC.Exts
+*Main> main
Local bindings in scope:
x :: a
Main.hs:15> let x' = unsafeCoerce x :: MyLongType Bool
Note that a wrong coercion will likely result in your debugging session being interrupted by a segmentation fault
</para></listitem>
</varlistentry>
- <varlistentry> <term> * The undocumented (and unsupported) :force command </term>
+ <varlistentry> <term> * The <literal>:force</literal> command </term>
<listitem><para>
equivalent to <literal> :print</literal> with automatic
- <code>seq</code> forcing,
- may prove useful to replace sequences of <code>seq</code> and
+ <literal>seq</literal> forcing,
+ may prove useful to replace sequences of <literal>seq</literal> and
<literal>:print</literal> in some situations.
</para></listitem>
</varlistentry>
</variablelist>
- </sect2></sect1>
+ </sect2>
+ <sect2><title>Limitations</title>
+ <para>
+ <itemizedlist>
+ <listitem><para>
+ Implicit parameters (see <xref linkend="implicit-parameters"/>) are only available
+ at the scope of a breakpoint if there is a explicit type signature.
+ </para></listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem><para>
+ Modules compiled by GHCi under the <literal>-fdebugging
+ </literal> flag will perform slower: the debugging mode introduces some overhead.
+ Modules compiled to object code by ghc are not affected.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ </sect1>
<sect1 id="ghci-dot-files">
<title>The <filename>.ghci</filename> file</title>
<indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary>
</sect1>
+ <sect1 id="ghci-obj">
+ <title>Compiling to object code inside GHCi</title>
+
+ <para>By default, GHCi compiles Haskell source code into byte-code
+ that is interpreted by the runtime system. GHCi can also compile
+ Haskell code to object code: to turn on this feature, use the
+ <option>-fobject-code</option> flag either on the command line or
+ with <literal>:set</literal> (the option
+ <option>-fbyte-code</option> restores byte-code compilation
+ again). Compiling to object code takes longer, but typically the
+ code will execute 10-20 times faster than byte-code.</para>
+
+ <para>Compiling to object code inside GHCi is particularly useful
+ if you are developing a compiled application, because the
+ <literal>:reload</literal> command typically runs much faster than
+ restarting GHC with <option>--make</option> from the command-line,
+ because all the interface files are already cached in
+ memory.</para>
+
+ <para>There are disadvantages to compiling to object-code: you
+ can't set breakpoints in object-code modules, for example. Only
+ the exports of an object-code module will be visible in GHCi,
+ rather than all top-level bindings as in interpreted
+ modules.</para>
+ </sect1>
+
<sect1 id="ghci-faq">
<title>FAQ and Things To Watch Out For</title>
<term>I can't use Control-C to interrupt computations in
GHCi on Windows.</term>
<listitem>
- <para>See <xref linkend="ghci-windows">.</xref></para>
+ <para>See <xref linkend="ghci-windows"/></para>
</listitem>
</varlistentry>
</variablelist>
projects / ghc-hetmet.git / blobdiff