+ <sect1 id="ghci-debugger">
+ <title>The GHCi debugger</title>
+ <indexterm><primary>debugger</primary></indexterm>
+ <para>GHCi embeds an utility debugger with a very basic set of operations. The debugger
+ is always available in ghci, you do not need to do anything to activate it. </para>
+ <para>The following conditions must hold before the debugger can be used with a module:
+ <itemizedlist>
+ <listitem>
+ <para>The module must have been loaded interpreted, i.e. not loaded from an <filename>.o</filename> file compiled by ghc </para>
+ </listitem>
+ <listitem>
+ <para>The module must have been loaded with the <literal>-fdebugging</literal> flag
+ </para></listitem>
+ </itemizedlist></para>
+ <sect2><title>Using the debugger</title>
+ <para>The debugger allows the insertion of breakpoints at specific locations in the source code. These locations are goberned by event type, and not by line as in traditional debuggers for imperative languages.
+ Once a breakpointed event is hit, the debugger stops the execution and you can examine the local variables in scope
+ in the context of the event, and evaluate arbitrary Haskell expressions in
+ a special interactive environment prompt.No matter what you do at the
+ breakpoint context, you cannot change the value assigned to the bindings of
+ your program. When you are done you issue the <literal>:quit</literal>
+ command and the execution goes on. All the other GHCi commands are supported
+ too, but the commands <literal>:load</literal> and <literal>:reload</literal>,
+ will cause a breakpoint session to stop.
+
+ </para>
+ <sidebar><title>Events</title><?dbfo float-type="left"?>
+ <para> Events are the places in source code where you can set a breakpoint.
+<programlisting>
+qsort [] = <co id="name-binding-co"/> []
+qsort (x:xs) =
+ <coref linkend="name-binding-co"/> let left = <coref linkend="name-binding-co"/> filter (\y -> <co id="lambda-co"/> y < x) xs
+ right = <coref linkend="name-binding-co"/> case filter (\y -> <coref linkend="lambda-co"/> y > x) xs of
+ right_val -> <co id="case-co"/> right_val
+ in <co id="let-co"/> qsort left ++ [x] ++ qsort right
+main = <coref linkend="name-binding-co"/> do {
+ arg <- <coref linkend="name-binding-co"/> getLine ;
+ let num = <coref linkend="name-binding-co"/> read arg :: [Int] ;
+ <co id="stmts-co"/> print (qsort num) ;
+ <coref linkend="stmts-co"/> putStrLn "GoodBye!" }
+</programlisting>
+ The GHCi debugger recognizes the following event types:
+ <calloutlist>
+ <callout arearefs="name-binding-co" id="name-binding">
+ <para>Function definition and local bindings in let/where</para>
+ </callout>
+ <callout arearefs="lambda-co" id="lambda">
+ <para>Lambda expression entry point</para>
+ </callout>
+ <callout arearefs="let-co" id="let">
+ <para>Let expression body</para>
+ </callout>
+ <callout arearefs="case-co" id="case">
+ <para>Case alternative body</para>
+ </callout>
+ <callout arearefs="stmts-co" id="stmts">
+ <para>do notation statements</para>
+ </callout>
+ </calloutlist></para>
+ <para>In reality however, we eliminate some redundant event sites.
+ For instance, sites with two co-located breakpoint events are coalesced into a single one,
+ and sites with no bindings in scope are assumed to be uninteresting and eliminated
+ too.</para>
+ </sidebar>
+
+<para>
+ You don't need to do anything special in order to start the debugging session.
+ Simply use ghci to evaluate your Haskell expressions and whenever a breakpoint
+ is hit, the debugger will enter the stage:
+<programlisting>
+*main:Main> :break add Main 2
+Breakpoint set at (2,15)
+*main:Main> qsort [10,9..1]
+Local bindings in scope:
+ x :: a, xs :: [a], left :: [a], right :: [a]
+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.
+ 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
+ these bindings may be unevaluated, and that exploring their contents may
+ trigger a computation. </para><para>
+ Second: look at the types of the things in scope.
+ GHCi has left its types parameterised by a variable!
+ This is due to the type of the <code>qsort</code> function, 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.
+ 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.
+ </para><para>
+ So, what can we do with a value without concrete type? Very few interesting
+ things. The <literal>:print</literal> command in ghci allows you to
+ explore its contents and see if it is evaluated or not.
+ This is useful because you cannot just type <literal>x</literal> in the
+ prompt and expect GHCi to return you the value of a. 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
+ type of <literal>x</literal> to do its work. </para>
+ <para> Let's go on with the debugging session of the <code>qsort</code>
+ example:
+<programlisting>
+qsort2.hs:2:15-46> x
+This is an untyped, unevaluated computation. You can use seq to
+force its evaluation and then :print to recover its type <co id="seq1"/>
+qsort2.hs:2:15-46> seq x () <co id="seq2"/>
+()
+qsort2.hs:2:15-46> x <co id="seq3"/>
+This is an untyped, unevaluated computation. You can use seq to
+force its evaluation and then :print to recover its type
+qsort2.hs:2:15-46> :t x
+x :: GHC.Base.Unknown
+qsort2.hs:2:15-46> :p x <co id="seq4"/>
+x - 10
+</programlisting>