X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=c0167bfe09d924eb726d3183a3afe14b954854b2;hb=d4050431de1adddedb240e497f77f89301f77070;hp=b5642b127fff061260371412e715055a32050884;hpb=e8982ebc45244da2f414eb920dfa798dbdc8cebc;p=ghc-hetmet.git
diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index b5642b1..c0167bf 100644
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -14,11 +14,13 @@
, then you'll be right at home with GHCi. However, GHCi
also has support for interactively loading compiled code, as well as
supporting allexcept foreign export, at the moment
- the language extensions that GHC provides.
+ the language extensions that GHC provides.
FFIGHCi support
- Foreign Function InterfaceGHCi support
+ Foreign Function
+ InterfaceGHCi support.
+ GHCi also includes an interactive debugger (see ).
-
+ Introduction to GHCiLet's start with an example GHCi session. You can fire up
@@ -26,61 +28,15 @@
$ ghci
- ___ ___ _
- / _ \ /\ /\/ __(_)
- / /_\// /_/ / / | | GHC Interactive, version 6.6, for Haskell 98.
-/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
-\____/\/ /_/\____/|_| Type :? for help.
-
+GHCi, version 6.8.1: http://www.haskell.org/ghc/ :? for help
Loading package base ... linking ... done.
Prelude>
There may be a short pause while GHCi loads the prelude and
- standard libraries, after which the prompt is shown. If we follow
- the instructions and type :? for help, we
- get:
-
-
- Commands available from the prompt:
-
- <stmt> evaluate/run <stmt>
- :add <filename> ... add module(s) to the current target set
- :browse [*]<module> display the names defined by <module>
- :cd <dir> change directory to <dir>
- :def <cmd> <expr> define a command :<cmd>
- :help, :? display this list of commands
- :info [<name> ...] display information about the given names
- :load <filename> ... load module(s) and their dependents
- :module [+/-] [*]<mod> ... set the context for expression evaluation
- :main [<arguments> ...] run the main function with the given arguments
- :reload reload the current module set
-
- :set <option> ... set options
- :set args <arg> ... set the arguments returned by System.getArgs
- :set prog <progname> set the value returned by System.getProgName
- :set prompt <prompt> set the prompt used in GHCi
-
- :show modules show the currently loaded modules
- :show bindings show the current bindings made at the prompt
-
- :ctags [<file>] create tags file for Vi (default: "tags")
- :etags [<file>] create tags file for Emacs (defauilt: "TAGS")
- :type <expr> show the type of <expr>
- :kind <type> show the kind of <type>
- :undef <cmd> undefine user-defined command :<cmd>
- :unset <option> ... unset options
- :quit exit GHCi
- :!<command> run the shell command <command>
-
- Options for ':set' and ':unset':
-
- +r revert top-level expressions after each evaluation
- +s print timing/memory stats after each evaluation
- +t print type after evaluation
- -<flags> most GHC command line flags can also be set here
- (eg. -v2, -fglasgow-exts, etc.)
-
+ standard libraries, after which the prompt is shown. As the banner
+ says, you can type :? to see the list of commands
+ available, and a half line description of each of them.We'll explain most of these commands as we go along. For
Hugs users: many things work the same as in Hugs, so you should be
@@ -103,7 +59,7 @@ Prelude>
enter, GHCi will attempt to evaluate it.
-
+ Loading source filesSuppose we have the following Haskell source code, which we
@@ -263,19 +219,17 @@ Ok, modules loaded: Main.
Prelude> :! ghc -c D.hs
Prelude> :load A
-Skipping D ( D.hs, D.o )
-Compiling C ( C.hs, interpreted )
Compiling B ( B.hs, interpreted )
+Compiling C ( C.hs, interpreted )
Compiling A ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
*Main>
- In the messages from the compiler, we see that it skipped D,
- and used the object file D.o. The message
- Skippingmodule
- indicates that compilation for module
- isn't necessary, because the source and everything it depends on
+ In the messages from the compiler, we see that there is no line
+ for D. This is because
+ it isn't necessary to compile D,
+ because the source and everything it depends on
is unchanged since the last compilation.At any time you can use the command
@@ -291,7 +245,7 @@ B ( B.hs, interpreted )
A ( A.hs, interpreted )
*Main>
- If we now modify the source of D (or pretend to: using Unix
+ If we now modify the source of D (or pretend to: using the Unix
command touch on the source file is handy for
this), the compiler will no longer be able to use the object file,
because it might be out of date:
@@ -300,9 +254,6 @@ A ( A.hs, interpreted )
*Main> :! touch D.hs
*Main> :reload
Compiling D ( D.hs, interpreted )
-Skipping C ( C.hs, interpreted )
-Skipping B ( B.hs, interpreted )
-Skipping A ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
*Main>
@@ -318,8 +269,8 @@ Ok, modules loaded: A, B, C, D.
*Main> :! ghc -c C.hs
*Main> :load A
Compiling D ( D.hs, interpreted )
-Compiling C ( C.hs, interpreted )
Compiling B ( B.hs, interpreted )
+Compiling C ( C.hs, interpreted )
Compiling A ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
@@ -342,8 +293,6 @@ Ok, modules loaded: A, B, C, D.
*Main> :load A
-Skipping D ( D.hs, D.o )
-Skipping C ( C.hs, C.o )
Compiling B ( B.hs, interpreted )
Compiling A ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
@@ -354,13 +303,13 @@ Ok, modules loaded: A, B, C, D.
when working on a large program is to occasionally run
ghc ––make to compile the whole project (say
before you go for lunch :-), then continue working in the
- interpreter. As you modify code, the new modules will be
+ interpreter. As you modify code, the changed modules will be
interpreted, but the rest of the project will remain
compiled.
-
+ Interactive evaluation at the promptWhen you type an expression at the prompt, GHCi immediately
@@ -402,7 +351,7 @@ hello
-
+ Using do-notation at the promptdo-notationin GHCistatementsin GHCi
@@ -444,7 +393,13 @@ Prelude>
Show
-
+ The automatic printing of binding results can be supressed with
+ (this does not
+ supress printing the result of non-binding statements).
+ .
+ You might want to do this to prevent the result of binding
+ statements from being fully evaluated by the act of printing
+ them, for example.
Of course, you can also bind normal non-IO expressions
using the let-statement:
@@ -566,7 +521,9 @@ hello
Prelude IO>
- (Note: :module can be shortened to
+ (Note: you can use import M as an
+ alternative to :module +M, and
+ :module can also be shortened to
:m). The full syntax of the
:module command is:
@@ -604,6 +561,12 @@ Prelude IO>
behaves in the same way for expressions typed at the
prompt.
+
+ Hint: GHCi will tab-complete names that are in scope; for
+ example, if you run GHCi and type J<tab>
+ then GHCi will expand it to “Just ”.
+
+
Qualified names
@@ -612,6 +575,34 @@ Prelude IO>
qualified declaration for every module in every
package, and every module currently loaded into GHCi.
+
+
+ The :main command
+
+
+ When a program is compiled and executed, it can use the
+ getArgs function to access the
+ command-line arguments.
+ However, we cannot simply pass the arguments to the
+ main function while we are testing in ghci,
+ as the main function doesn't take its
+ directly.
+
+
+
+ Instead, we can use the :main command.
+ This runs whatever main is in scope, with
+ any arguments being treated the same as command-line arguments,
+ e.g.:
+
+
+
+Prelude> let main = System.Environment.getArgs >>= print
+Prelude> :main foo bar
+["foo","bar"]
+
+
+
@@ -633,9 +624,9 @@ Prelude> it * 2
expression, and if it doesn't have an IO type,
then it transforms it as follows: an expression
e turns into
-
- let it = e;
- print it
+
+let it = e;
+print it
which is then run as an IO-action.
@@ -644,10 +635,14 @@ Prelude> it * 2
complain:
-Prelude> id
-No instance for `Show (a -> a)'
-arising from use of `print'
-in a `do' expression pattern binding: print it
+Prelude> id
+
+<interactive>:1:0:
+ No instance for (Show (a -> a))
+ arising from use of `print' at <interactive>:1:0-1
+ Possible fix: add an instance declaration for (Show (a -> a))
+ In the expression: print it
+ In a 'do' expression: print it
The error message contains some clues as to the
@@ -659,14 +654,15 @@ in a `do' expression pattern binding: print it
which is of type a. eg.:
Prelude> Time.getClockTime
+Wed Mar 14 12:23:13 GMT 2001
Prelude> print it
Wed Mar 14 12:23:13 GMT 2001
The corresponding translation for an IO-typed
e is
-
- it <- e
+
+it <- e
@@ -699,25 +695,803 @@ Wed Mar 14 12:23:13 GMT 2001
standard rules take each group of constraints (C1 a, C2 a, ..., Cn
a) for each type variable a, and defaults the
type variable if
-
- The type variable a
- appears in no other constraints
- All the classes Ci are standard.
- At least one of the classes Ci is
- numeric.
+
+
+
+ The type variable a appears in no
+ other constraints
+
+
+
+
+ All the classes Ci are standard.
+
+
+
+
+ At least one of the classes Ci is
+ numeric.
+
+
+
+ At the GHCi prompt, or with GHC if the
+ -XExtendedDefaultRules flag is given,
+ the following additional differences apply:
+
+
+
+ Rule 2 above is relaxed thus:
+ All of the classes
+ Ci are single-parameter type classes.
+
+
+
+
+ Rule 3 above is relaxed this:
+ At least one of the classes Ci is
+ numeric, or is Show,
+ Eq, or
+ Ord.
+
+
+
+
+ The unit type () is added to the
+ start of the standard list of types which are tried when
+ doing type defaulting.
+
+
+
+ The last point means that, for example, this program:
+
+main :: IO ()
+main = print def
+
+instance Num ()
+
+def :: (Num a, Enum a) => a
+def = toEnum 0
+
+ prints () rather than 0 as the
+ type is defaulted to () rather than
+ Integer.
+
+
+ The motivation for the change is that it means IO a
+ actions default to IO (), which in turn means that
+ ghci won't try to print a result when running them. This is
+ particularly important for printf, which has an
+ instance that returns IO a.
+ However, it is only able to return
+ undefined
+ (the reason for the instance having this type is so that printf
+ doesn't require extensions to the class system), so if the type defaults to
+ Integer then ghci gives an error when running a
+ printf.
+
+
+
+
+
+ The GHCi Debugger
+ debuggerin GHCi
+
+
+ GHCi contains a simple imperative-style debugger in which you can
+ stop a running computation in order to examine the values of
+ variables. The debugger is integrated into GHCi, and is turned on by
+ default: no flags are required to enable the debugging facilities. There
+ is one major restriction: breakpoints and single-stepping are only
+ available in interpreted modules; compiled code is
+ invisible to the debugger.
+
+ The debugger provides the following:
+
+
+ The ability to set a breakpoint on a
+ function definition or expression in the program. When the function
+ is called, or the expression evaluated, GHCi suspends
+ execution and returns to the prompt, where you can inspect the
+ values of local variables before continuing with the
+ execution.
+
+
+ Execution can be single-stepped: the
+ evaluator will suspend execution approximately after every
+ reduction, allowing local variables to be inspected. This is
+ equivalent to setting a breakpoint at every point in the
+ program.
+
+
+ Execution can take place in tracing
+ mode, in which the evaluator remembers each
+ evaluation step as it happens, but doesn't suspend execution until
+ an actual breakpoint is reached. When this happens, the history of
+ evaluation steps can be inspected.
+
+
+ Exceptions (e.g. pattern matching failure and
+ error) can be treated as breakpoints, to help
+ locate the source of an exception in the program.
+
- At the GHCi prompt, the second and third rules are relaxed as follows
- (differences italicised):
-
- All of the classes
- Ci are single-parameter type classes.
- At least one of the classes Ci is
- numeric, or is Show,
- Eq, or Ord.
+
+
+ There is currently no support for obtaining a “stack
+ trace”, but the tracing and history features provide a useful
+ second-best, which will often be enough to establish the context of an
+ error.
+
+
+ Breakpoints and inspecting variables
+
+ Let's use quicksort as a running example. Here's the code:
+
+
+qsort [] = []
+qsort (a:as) = qsort left ++ [a] ++ qsort right
+ where (left,right) = (filter (<=a) as, filter (>a) as)
+
+main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
+
+
+ First, load the module into GHCi:
+
+
+Prelude> :l qsort.hs
+[1 of 1] Compiling Main ( qsort.hs, interpreted )
+Ok, modules loaded: Main.
+*Main>
+
+
+ Now, let's set a breakpoint on the right-hand-side of the second
+ equation of qsort:
+
+
+*Main> :break 2
+Breakpoint 0 activated at qsort.hs:2:15-46
+*Main>
+
+
+ The command :break 2 sets a breakpoint on line
+ 2 of the most recently-loaded module, in this case
+ qsort.hs. Specifically, it picks the
+ leftmost complete subexpression on that line on which to set the
+ breakpoint, which in this case is the expression
+ (qsort left ++ [a] ++ qsort right).
+
+ Now, we run the program:
+
+
+*Main> main
+Stopped at qsort.hs:2:15-46
+_result :: [a]
+a :: a
+left :: [a]
+right :: [a]
+[qsort.hs:2:15-46] *Main>
+
+
+ Execution has stopped at the breakpoint. The prompt has changed to
+ indicate that we are currently stopped at a breakpoint, and the location:
+ [qsort.hs:2:15-46]. To further clarify the
+ location, we can use the :list command:
+
+
+[qsort.hs:2:15-46] *Main> :list
+1 qsort [] = []
+2 qsort (a:as) = qsort left ++ [a] ++ qsort right
+3 where (left,right) = (filter (<=a) as, filter (>a) as)
+
+
+ The :list command lists the source code around
+ the current breakpoint. If your output device supports it, then GHCi
+ will highlight the active subexpression in bold.
+
+ GHCi has provided bindings for the free variablesWe
+ originally provided bindings for all variables in scope, rather
+ than just
+ the free variables of the expression, but found that this affected
+ performance considerably, hence the current restriction to just the
+ free variables.
+ of the expression
+ on which the
+ breakpoint was placed (a, left,
+ right), and additionally a binding for the result of
+ the expression (_result). These variables are just
+ like other variables that you might define in GHCi; you
+ can use them in expressions that you type at the prompt, you can ask
+ for their types with :type, and so on. There is one
+ important difference though: these variables may only have partial
+ types. For example, if we try to display the value of
+ left:
+
+
+[qsort.hs:2:15-46] *Main> left
+
+<interactive>:1:0:
+ Ambiguous type variable `a' in the constraint:
+ `Show a' arising from a use of `print' at <interactive>:1:0-3
+ Cannot resolve unknown runtime types: a
+ Use :print or :force to determine these types
+
+
+ This is because qsort is a polymorphic function,
+ and because GHCi does not carry type information at runtime, it cannot
+ determine the runtime types of free variables that involve type
+ variables. Hence, when you ask to display left at
+ the prompt, GHCi can't figure out which instance of
+ Show to use, so it emits the type error above.
+
+ Fortunately, the debugger includes a generic printing command,
+ :print, which can inspect the actual runtime value of a
+ variable and attempt to reconstruct its type. If we try it on
+ left:
+
+
+[qsort.hs:2:15-46] *Main> :print left
+left = (_t1::[a])
+
+
+ This isn't particularly enlightening. What happened is that
+ left is bound to an unevaluated computation (a
+ suspension, or thunk), and
+ :print does not force any evaluation. The idea is
+ that :print can be used to inspect values at a
+ breakpoint without any unfortunate side effects. It won't force any
+ evaluation, which could cause the program to give a different answer
+ than it would normally, and hence it won't cause any exceptions to be
+ raised, infinite loops, or further breakpoints to be triggered (see
+ ).
+ Rather than forcing thunks, :print
+ binds each thunk to a fresh variable beginning with an
+ underscore, in this case
+ _t1.
+
+ If we aren't concerned about preserving the evaluatedness of a
+ variable, we can use :force instead of
+ :print. The :force command
+ behaves exactly like :print, except that it forces
+ the evaluation of any thunks it encounters:
+
+
+[qsort.hs:2:15-46] *Main> :force left
+left = [4,0,3,1]
+
+
+ Now, since :force has inspected the runtime
+ value of left, it has reconstructed its type. We
+ can see the results of this type reconstruction:
+
+
+[qsort.hs:2:15-46] *Main> :show bindings
+_result :: [Integer]
+a :: Integer
+left :: [Integer]
+right :: [Integer]
+_t1 :: [Integer]
+
+
+ Not only do we now know the type of left, but
+ all the other partial types have also been resolved. So we can ask
+ for the value of a, for example:
+
+
+[qsort.hs:2:15-46] *Main> a
+8
+
+
+ You might find it useful to use Haskell's
+ seq function to evaluate individual thunks rather
+ than evaluating the whole expression with :force.
+ For example:
+
+
+[qsort.hs:2:15-46] *Main> :print right
+right = (_t1::[Integer])
+[qsort.hs:2:15-46] *Main> seq _t1 ()
+()
+[qsort.hs:2:15-46] *Main> :print right
+right = 23 : (_t2::[Integer])
+
+
+ We evaluated only the _t1 thunk, revealing the
+ head of the list, and the tail is another thunk now bound to
+ _t2. The seq function is a
+ little inconvenient to use here, so you might want to use
+ :def to make a nicer interface (left as an exercise
+ for the reader!).
+
+ Finally, we can continue the current execution:
+
+
+[qsort.hs:2:15-46] *Main> :continue
+Stopped at qsort.hs:2:15-46
+_result :: [a]
+a :: a
+left :: [a]
+right :: [a]
+[qsort.hs:2:15-46] *Main>
+
+
+ The execution continued at the point it previously stopped, and has
+ now stopped at the breakpoint for a second time.
+
+
+ Setting breakpoints
+
+ Breakpoints can be set in various ways. Perhaps the easiest way to
+ set a breakpoint is to name a top-level function:
+
+
+ :break identifier
+
+
+ Where identifier names any top-level
+ function in an interpreted module currently loaded into GHCi (qualified
+ names may be used). The breakpoint will be set on the body of the
+ function, when it is fully applied but before any pattern matching has
+ taken place.
+
+ Breakpoints can also be set by line (and optionally column)
+ number:
+
+
+ :break line
+ :break linecolumn
+ :break moduleline
+ :break modulelinecolumn
+
+
+ When a breakpoint is set on a particular line, GHCi sets the
+ breakpoint on the
+ leftmost subexpression that begins and ends on that line. If two
+ complete subexpressions start at the same
+ column, the longest one is picked. If there is no complete
+ subexpression on the line, then the leftmost expression starting on
+ the line is picked, and failing that the rightmost expression that
+ partially or completely covers the line.
+
+ When a breakpoint is set on a particular line and column, GHCi
+ picks the smallest subexpression that encloses that location on which
+ to set the breakpoint. Note: GHC considers the TAB character to have a
+ width of 1, wherever it occurs; in other words it counts
+ characters, rather than columns. This matches what some editors do,
+ and doesn't match others. The best advice is to avoid tab
+ characters in your source code altogether (see
+ in ).
+
+ If the module is omitted, then the most recently-loaded module is
+ used.
+
+ Not all subexpressions are potential breakpoint locations. Single
+ variables are typically not considered to be breakpoint locations
+ (unless the variable is the right-hand-side of a function definition,
+ lambda, or case alternative). The rule of thumb is that all redexes
+ are breakpoint locations, together with the bodies of functions,
+ lambdas, case alternatives and binding statements. There is normally
+ no breakpoint on a let expression, but there will always be a
+ breakpoint on its body, because we are usually interested in inspecting
+ the values of the variables bound by the let.
+
+
+
+ Listing and deleting breakpoints
+
+ The list of breakpoints currently enabled can be displayed using
+ :show breaks:
+
+*Main> :show breaks
+[0] Main qsort.hs:1:11-12
+[1] Main qsort.hs:2:15-46
+
+
+ To delete a breakpoint, use the :delete
+ command with the number given in the output from :show breaks:
+
+
+*Main> :delete 0
+*Main> :show breaks
+[1] Main qsort.hs:2:15-46
+
+
+ To delete all breakpoints at once, use :delete *.
+
+
+
+
+
+ Single-stepping
+
+ Single-stepping is a great way to visualise the execution of your
+ program, and it is also a useful tool for identifying the source of a
+ bug. The concept is simple: single-stepping enables all the
+ breakpoints in the program and executes until the next breakpoint is
+ reached, at which point you can single-step again, or continue
+ normally. For example:
+
+
+*Main> :step main
+Stopped at qsort.hs:5:7-47
+_result :: IO ()
+
+
+ The command :step
+ expr begins the evaluation of
+ expr in single-stepping mode. If
+ expr is ommitted, then it single-steps from
+ the current breakpoint.
+
+ The :list command is particularly useful when
+ single-stepping, to see where you currently are:
+
+
+[qsort.hs:5:7-47] *Main> :list
+4
+5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
+6
+[qsort.hs:5:7-47] *Main>
+
+
+ In fact, GHCi provides a way to run a command when a breakpoint is
+ hit, so we can make it automatically do
+ :list:
+
+
+[qsort.hs:5:7-47] *Main> :set stop :list
+[qsort.hs:5:7-47] *Main> :step
+Stopped at qsort.hs:5:14-46
+_result :: [Integer]
+4
+5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
+6
+[qsort.hs:5:14-46] *Main>
+
+
+
+
+ Nested breakpoints
+ When GHCi is stopped at a breakpoint, and an expression entered at
+ the prompt triggers a
+ second breakpoint, the new breakpoint becomes the “current”
+ one, and the old one is saved on a stack. An arbitrary number of
+ breakpoint contexts can be built up in this way. For example:
+
+
+[qsort.hs:2:15-46] *Main> :st qsort [1,3]
+Stopped at qsort.hs:(1,0)-(3,55)
+_result :: [a]
+... [qsort.hs:(1,0)-(3,55)] *Main>
+
+
+ While stopped at the breakpoint on line 2 that we set earlier, we
+ started a new evaluation with :step qsort [1,3].
+ This new evaluation stopped after one step (at the definition of
+ qsort). The prompt has changed, now prefixed with
+ ..., to indicate that there are saved breakpoints
+ beyond the current one. To see the stack of contexts, use
+ :show context:
+
+
+... [qsort.hs:(1,0)-(3,55)] *Main> :show context
+--> main
+ Stopped at qsort.hs:2:15-46
+--> qsort [1,3]
+ Stopped at qsort.hs:(1,0)-(3,55)
+... [qsort.hs:(1,0)-(3,55)] *Main>
+
+
+ To abandon the current evaluation, use
+ :abandon:
+
+
+... [qsort.hs:(1,0)-(3,55)] *Main> :abandon
+[qsort.hs:2:15-46] *Main> :abandon
+*Main>
+
+
+
+
+ The _result variable
+ When stopped at a breakpoint or single-step, GHCi binds the
+ variable _result to the value of the currently
+ active expression. The value of _result is
+ presumably not available yet, because we stopped its evaluation, but it
+ can be forced: if the type is known and showable, then just entering
+ _result at the prompt will show it. However,
+ there's one caveat to doing this: evaluating _result
+ will be likely to trigger further breakpoints, starting with the
+ breakpoint we are currently stopped at (if we stopped at a real
+ breakpoint, rather than due to :step). So it will
+ probably be necessary to issue a :continue
+ immediately when evaluating _result. Alternatively,
+ you can use :force which ignores breakpoints.
+
+
+
+ Tracing and history
+
+ A question that we often want to ask when debugging a program is
+ “how did I get here?”. Traditional imperative debuggers
+ usually provide some kind of stack-tracing feature that lets you see
+ the stack of active function calls (sometimes called the “lexical
+ call stack”), describing a path through the code
+ to the current location. Unfortunately this is hard to provide in
+ Haskell, because execution proceeds on a demand-driven basis, rather
+ than a depth-first basis as in strict languages. The
+ “stack“ in GHC's execution engine bears little
+ resemblance to the lexical call stack. Ideally GHCi would maintain a
+ separate lexical call stack in addition to the dynamic call stack, and
+ in fact this is exactly
+ what our profiling system does (), and what
+ some other Haskell debuggers do. For the time being, however, GHCi
+ doesn't maintain a lexical call stack (there are some technical
+ challenges to be overcome). Instead, we provide a way to backtrack from a
+ breakpoint to previous evaluation steps: essentially this is like
+ single-stepping backwards, and should in many cases provide enough
+ information to answer the “how did I get here?”
+ question.
+
+ To use tracing, evaluate an expression with the
+ :trace command. For example, if we set a breakpoint
+ on the base case of qsort:
+
+
+*Main> :list qsort
+1 qsort [] = []
+2 qsort (a:as) = qsort left ++ [a] ++ qsort right
+3 where (left,right) = (filter (<=a) as, filter (>a) as)
+4
+*Main> :b 1
+Breakpoint 1 activated at qsort.hs:1:11-12
+*Main>
+
+
+ and then run a small qsort with
+ tracing:
+
+
+*Main> :trace qsort [3,2,1]
+Stopped at qsort.hs:1:11-12
+_result :: [a]
+[qsort.hs:1:11-12] *Main>
+
+
+ We can now inspect the history of evaluation steps:
+
+
+[qsort.hs:1:11-12] *Main> :hist
+-1 : qsort.hs:3:24-38
+-2 : qsort.hs:3:23-55
+-3 : qsort.hs:(1,0)-(3,55)
+-4 : qsort.hs:2:15-24
+-5 : qsort.hs:2:15-46
+-6 : qsort.hs:3:24-38
+-7 : qsort.hs:3:23-55
+-8 : qsort.hs:(1,0)-(3,55)
+-9 : qsort.hs:2:15-24
+-10 : qsort.hs:2:15-46
+-11 : qsort.hs:3:24-38
+-12 : qsort.hs:3:23-55
+-13 : qsort.hs:(1,0)-(3,55)
+-14 : qsort.hs:2:15-24
+-15 : qsort.hs:2:15-46
+-16 : qsort.hs:(1,0)-(3,55)
+<end of history>
+
+
+ To examine one of the steps in the history, use
+ :back:
+
+
+[qsort.hs:1:11-12] *Main> :back
+Logged breakpoint at qsort.hs:3:24-38
+_result :: [a]
+as :: [a]
+a :: a
+[-1: qsort.hs:3:24-38] *Main>
+
+
+ Note that the local variables at each step in the history have been
+ preserved, and can be examined as usual. Also note that the prompt has
+ changed to indicate that we're currently examining the first step in
+ the history: -1. The command
+ :forward can be used to traverse forward in the
+ history.
+
+ The :trace command can be used with or without
+ an expression. When used without an expression, tracing begins from
+ the current breakpoint, just like :step.
+
+ The history is only available when
+ using :trace; the reason for this is we found that
+ logging each breakpoint in the history cuts performance by a factor of
+ 2 or more. GHCi remembers the last 50 steps in the history (perhaps in
+ the future we'll make this configurable).
+
+
+
+ Debugging exceptions
+ Another common question that comes up when debugging is
+ “where did this exception come from?”. Exceptions such as
+ those raised by error or head []
+ have no context information attached to them. Finding which
+ particular call to head in your program resulted in
+ the error can be a painstaking process, usually involving
+ Debug.Trace.trace, or compiling with
+ profiling and using +RTS -xc (see ).
+
+ The GHCi debugger offers a way to hopefully shed some light on
+ these errors quickly and without modifying or recompiling the source
+ code. One way would be to set a breakpoint on the location in the
+ source code that throws the exception, and then use
+ :trace and :history to establish
+ the context. However, head is in a library and
+ we can't set a breakpoint on it directly. For this reason, GHCi
+ provides the flag -fbreak-on-exception which causes
+ the evaluator to stop when an exception is thrown, just as it does when
+ a breakpoint is hit. This is only really useful in conjunction with
+ :trace, in order to log the steps leading up to the
+ exception. For example:
+
+
+*Main> :set -fbreak-on-exception
+*Main> :trace qsort ("abc" ++ undefined)
+"Stopped at <exception thrown>
+_exception :: e
+[<exception thrown>] *Main> :hist
+-1 : qsort.hs:3:24-38
+-2 : qsort.hs:3:23-55
+-3 : qsort.hs:(1,0)-(3,55)
+-4 : qsort.hs:2:15-24
+-5 : qsort.hs:2:15-46
+-6 : qsort.hs:(1,0)-(3,55)
+<end of history>
+[<exception thrown>] *Main> :back
+Logged breakpoint at qsort.hs:3:24-38
+_result :: [a]
+as :: [a]
+a :: a
+[-1: qsort.hs:3:24-38] *Main> :force as
+*** Exception: Prelude.undefined
+[-1: qsort.hs:3:24-38] *Main> :print as
+as = 'b' : 'c' : (_t1::[Char])
+
+
+ The exception itself is bound to a new variable,
+ _exception.
+
+ Breaking on exceptions is particularly useful for finding out what
+ your program was doing when it was in an infinite loop. Just hit
+ Control-C, and examine the history to find out what was going
+ on.
+
+
+ Example: inspecting functions
+
+ It is possible to use the debugger to examine function values.
+ When we are at a breakpoint and a function is in scope, the debugger
+ cannot show
+ you the source code for 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 show the process by means of an example.
+ To keep things simple, we will use the well known map function:
+
+import Prelude hiding (map)
+
+map :: (a->b) -> a -> b
+map f [] = []
+map f (x:xs) = f x : map f xs
+
+
+
+
+ We set a breakpoint on map, and call it.
+
+*Main> :break 5
+Breakpoint 0 activated at map.hs:5:15-28
+*Main> map Just [1..5]
+Stopped at map.hs:(4,0)-(5,12)
+_result :: [b]
+x :: a
+f :: a -> b
+xs :: [a]
+
+ GHCi tells us that, among other bindings, f is in scope.
+ However, its type is not fully known yet,
+ and thus it is not possible to apply it to any
+ arguments. Nevertheless, observe that the type of its first argument is the
+ same as the type of x, and its result type is shared
+ with _result.
+
+
+
+ As we demonstrated earlier (), the
+ debugger has some intelligence built-in to update the type of
+ f whenever the types of x or
+ _result are discovered. So what we do in this
+ scenario is
+ force x a bit, in order to recover both its type
+ and the argument part of f.
+
+*Main> seq x ()
+*Main> :print x
+x = 1
+
+
+
+ We can check now that as expected, the type of x
+ has been reconstructed, and with it the
+ type of f has been too:
+
+*Main> :t x
+x :: Integer
+*Main> :t f
+f :: Integer -> b
+
+
+ From here, we can apply f to any argument of type Integer and observe
+ the results.
+ let b = f 10
+*Main> :t b
+b :: b
+*Main> b
+:1:0:
+ Ambiguous type variable `b' in the constraint:
+ `Show b' arising from a use of `print' at :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]
+]]>
+ In the first application of f, we had to do
+ some more type reconstruction
+ in order to recover the result type of f.
+ But after that, we are free to use
+ f normally.
+
+
+
+ Limitations
+
+
+ When stopped at a breakpoint, if you try to evaluate a variable
+ that is already under evaluation, the second evaluation will hang.
+ The reason is
+ that GHC knows the variable is under evaluation, so the new
+ evaluation just waits for the result before continuing, but of
+ course this isn't going to happen because the first evaluation is
+ stopped at a breakpoint. Control-C can interrupt the hung
+ evaluation and return to the prompt.
+ The most common way this can happen is when you're evaluating a
+ CAF (e.g. main), stop at a breakpoint, and ask for the value of the
+ CAF at the prompt again.
+
+
+ Implicit parameters (see ) are only available
+ at the scope of a breakpoint if there is an explicit type signature.
+
+
- The same type-default behaviour can be enabled in an ordinary Haskell
- module, using the flag -fextended-default-rules.
-
@@ -732,7 +1506,7 @@ Wed Mar 14 12:23:13 GMT 2001
instructs GHCi to load the specified modules or filenames (and all
the modules they depend on), just as if you had said
:load modules at the
- GHCi prompt (see ). For example, to
+ GHCi prompt (see ). For example, to
start GHCi and load the program whose topmost module is in the
file Main.hs, we could say:
@@ -742,9 +1516,7 @@ $ ghci Main.hs
Most of the command-line options accepted by GHC (see ) also make sense in interactive mode. The ones
- that don't make sense are mostly obvious; for example, GHCi
- doesn't generate interface files, so options related to interface
- file generation won't have any effect.
+ that don't make sense are mostly obvious.
Packages
@@ -755,26 +1527,14 @@ $ ghci Main.hs
they will be automatically loaded the first time they are
needed.
- For non-auto packages, however, you need to request the
+ For hidden packages, however, you need to request the
package be loaded by using the -package flag:
-$ ghci -package data
- ___ ___ _
- / _ \ /\ /\/ __(_)
- / /_\// /_/ / / | | GHC Interactive, version 5.05, for Haskell 98.
-/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
-\____/\/ /_/\____/|_| Type :? for help.
-
+$ ghci -package readline
+GHCi, version 6.8.1: http://www.haskell.org/ghc/ :? for help
Loading package base ... linking ... done.
-Loading package haskell98 ... linking ... done.
-Loading package lang ... linking ... done.
-Loading package concurrent ... linking ... done.
-Loading package readline ... linking ... done.
-Loading package unix ... linking ... done.
-Loading package posix ... linking ... done.
-Loading package util ... linking ... done.
-Loading package data ... linking ... done.
+Loading package readline-1.0 ... linking ... done.
Prelude>
@@ -847,14 +1607,23 @@ $ ghci -lm
GHCi commands all begin with
‘:’ and consist of a single command
name followed by zero or more parameters. The command name may be
- abbreviated, as long as the abbreviation is not ambiguous. All of
- the builtin commands, with the exception of
- :unset and :undef, may be
- abbreviated to a single letter.
+ abbreviated, with ambiguities being resolved in favour of the more
+ commonly used commands.
+ :abandon
+ :abandon
+
+
+ Abandons the current evaluation (only available when stopped at
+ a breakpoint).
+
+
+
+
+ :addmodule ...
:add
@@ -867,6 +1636,32 @@ $ ghci -lm
+ :back
+ :back
+
+
+ Travel back one step in the history. See . See also:
+ :trace, :history,
+ :forward.
+
+
+
+
+
+ :break [identifier |
+ [module] line
+ [column]]
+
+ :break
+
+ Set a breakpoint on the specified function or line and
+ column. See .
+
+
+
+
+ :browse*module ...
:browse
@@ -909,6 +1704,52 @@ $ ghci -lm
+ :cmdexpr
+ :cmd
+
+
+ Executes expr as a computation of
+ type IO String, and then executes the resulting
+ string as a list of GHCi commands. Multiple commands are separated
+ by newlines. The :cmd command is useful with
+ :def and :set stop.
+
+
+
+
+
+ :continue
+ :continue
+
+ Continue the current evaluation, when stopped at a
+ breakpoint.
+
+
+
+
+
+ :ctagsfilename
+ :etagsfilename
+ :etags
+
+ :etags
+
+
+
+ Generates a “tags” file for Vi-style editors
+ (:ctags) or
+ Emacs-style editors (:etags). If
+ no filename is specified, the defaulit tags or
+ TAGS is
+ used, respectively. Tags for all the functions, constructors and
+ types in the currently loaded modules are created. All modules must
+ be interpreted for these commands to work.
+ See also .
+
+
+
+
+ :defnameexpr:def
@@ -977,6 +1818,71 @@ Prelude> :. cmds.ghci
+ :delete * | num ...
+ :delete
+
+
+ Delete one or more breakpoints by number (use :show
+ breaks to see the number of each breakpoint). The
+ * form deletes all the breakpoints.
+
+
+
+
+
+ :edit file
+ :edit
+
+
+ Opens an editor to edit the file
+ file, or the most recently loaded
+ module if file is omitted. The
+ editor to invoke is taken from the EDITOR
+ environment variable, or a default editor on your system if
+ EDITOR is not set. You can change the
+ editor using :set editor.
+
+
+
+
+
+ :etags
+
+
+ See :ctags.
+
+
+
+
+
+ :force identifier ...
+ :force
+
+
+ Prints the value of identifier in
+ the same way as :print. Unlike
+ :print, :force evaluates each
+ thunk that it encounters while traversing the value. This may
+ cause exceptions or infinite loops, or further breakpoints (which
+ are ignored, but displayed).
+
+
+
+
+
+ :forward
+ :forward
+
+
+ Move forward in the history. See . See also:
+ :trace, :history,
+ :back.
+
+
+
+
+ :help:help
@@ -991,6 +1897,19 @@ Prelude> :. cmds.ghci
+ :history [num]
+ :history
+
+
+ Display the history of evaluation steps. With a number,
+ displays that many steps (default: 20). For use with
+ :trace; see .
+
+
+
+
+ :infoname ...
:info
@@ -1009,6 +1928,19 @@ Prelude> :. cmds.ghci
+ :kindtype
+ :kind
+
+
+ Infers and prints the kind of
+ type. The latter can be an arbitrary
+ type expression, including a partial application of a type constructor,
+ such as Either Int.
+
+
+
+
+ :loadmodule ...
:load
@@ -1048,23 +1980,83 @@ Prelude> :. cmds.ghci
+ :main arg1 ... argn
+ :main
+
+
+
+ When a program is compiled and executed, it can use the
+ getArgs function to access the
+ command-line arguments.
+ However, we cannot simply pass the arguments to the
+ main function while we are testing in ghci,
+ as the main function doesn't take its
+ arguments directly.
+
+
+
+ Instead, we can use the :main command.
+ This runs whatever main is in scope, with
+ any arguments being treated the same as command-line arguments,
+ e.g.:
+
+
+
+Prelude> let main = System.Environment.getArgs >>= print
+Prelude> :main foo bar
+["foo","bar"]
+
+
+
+
+
+
+ :module +|-*mod1 ... *modn:module
+
+ import mod
+ Sets or modifies the current context for statements
- typed at the prompt. See for
+ typed at the prompt. The form import
+ mod is equivalent to
+ :module +mod.
+ See for
more details.
+ :print names ...
+ :print
+
+
+ Prints a value without forcing its evaluation.
+ :print may be used on values whose types are
+ unknown or partially known, which might be the case for local
+ variables with polymorphic types at a breakpoint. While inspecting
+ the runtime value, :print attempts to
+ reconstruct the type of the value, and will elaborate the type in
+ GHCi's environment if possible. If any unevaluated components
+ (thunks) are encountered, then :print binds
+ a fresh variable with a name beginning with _t
+ to each thunk. See for more
+ information. See also the :sprint command,
+ which works like :print but does not bind new
+ variables.
+
+
+
+
+ :quit:quit
- Quits GHCi. You can also quit by typing a control-D
+ Quits GHCi. You can also quit by typing control-D
at the prompt.
@@ -1110,6 +2102,16 @@ Prelude> :. cmds.ghci
+ :seteditorcmd
+
+
+ Sets the command used by :edit to
+ cmd.
+
+
+
+
+ :setprogprog:set prog
@@ -1135,6 +2137,35 @@ Prelude> :. cmds.ghci
+ :setstop
+ [num] cmd
+
+
+ Set a command to be executed when a breakpoint is hit, or a new
+ item in the history is selected. The most common use of
+ :set stop is to display the source code at the
+ current location, e.g. :set stop :list.
+
+ If a number is given before the command, then the commands are
+ run when the specified breakpoint (only) is hit. This can be quite
+ useful: for example, :set stop 1 :continue
+ effectively disables breakpoint 1, by running
+ :continue whenever it is hit (although GHCi will
+ still emit a message to say the breakpoint was hit). What's more,
+ with cunning use of :def and
+ :cmd you can use :set stop to
+ implement conditional breakpoints:
+
+*Main> :def cond \expr -> return (":cmd if (" ++ expr ++ ") then return \"\" else return \":continue\"")
+*Main> :set stop 0 :cond (x < 3)
+
+ Ignoring breakpoints for a specified number of iterations is
+ also possible using similar techniques.
+
+
+
+
+ :show bindings:show bindings
@@ -1146,59 +2177,94 @@ Prelude> :. cmds.ghci
+ :show breaks
+ :show breaks
+
+
+ List the active breakpoints.
+
+
+
+
+
+ :show context
+ :show context
+
+
+ List the active evaluations that are stopped at breakpoints.
+
+
+
+
+ :show modules:show modules
- Show the list of modules currently load.
+ Show the list of modules currently loaded.
- :ctagsfilename
- :etagsfilename
- :etags
-
- :etags
-
-
+ :show [args|prog|prompt|editor|stop]
+ :show
+
- Generates a “tags” file for Vi-style editors
- (:ctags) or Emacs-style editors (etags). If
- no filename is specified, the defaulit tags or
- TAGS is
- used, respectively. Tags for all the functions, constructors and
- types in the currently loaded modules are created. All modules must
- be interpreted for these commands to work.
- See also .
+ Displays the specified setting (see
+ :set).
- :typeexpression
- :type
+ :sprint
+ :sprint
- Infers and prints the type of
- expression, including explicit
- forall quantifiers for polymorphic types. The monomorphism
- restriction is not applied to the
- expression during type inference.
+ Prints a value without forcing its evaluation.
+ :sprint is similar to :print,
+ with the difference that unevaluated subterms are not bound to new
+ variables, they are simply denoted by ‘_’.
- :kindtype
- :kind
+ :step [expr]
+ :step
- Infers and prints the kind of
- type. The latter can be an arbitrary
- type expression, including a partial application of a type constructor,
- such as Either Int.
+ Single-step from the last breakpoint. With an expression
+ argument, begins evaluation of the expression with a
+ single-step.
+
+
+
+
+
+ :trace [expr]
+ :trace
+
+
+ Evaluates the given expression (or from the last breakpoint if
+ no expression is given), and additionally logs the evaluation
+ steps for later inspection using :history. See
+ .
+
+
+
+
+
+ :typeexpression
+ :type
+
+
+ Infers and prints the type of
+ expression, including explicit
+ forall quantifiers for polymorphic types. The monomorphism
+ restriction is not applied to the
+ expression during type inference.
@@ -1246,7 +2312,7 @@ Prelude> :. cmds.ghci
The :set command sets two types of
options: GHCi options, which begin with
- ‘+” and “command-line”
+ ‘+’, and “command-line”
options, which begin with ‘-’. NOTE: at the moment, the :set command
@@ -1351,7 +2417,6 @@ Prelude> :set -fno-glasgow-exts
staticoptions
-
The .ghci file.ghcifile
@@ -1359,9 +2424,10 @@ Prelude> :set -fno-glasgow-exts
startupfiles, GHCi
- When it starts, GHCi always reads and executes commands from
- $HOME/.ghci, followed by
- ./.ghci.
+ When it starts, unless the -ignore-dot-ghci
+ flag is given, GHCi reads and executes commands from
+ ./.ghci, followed by
+ $HOME/.ghci.The .ghci in your home directory is
most useful for turning on favourite options (eg. :set
@@ -1370,7 +2436,7 @@ Prelude> :set -fno-glasgow-exts
project is a useful way to set certain project-wide options so you
don't have to type them everytime you start GHCi: eg. if your
project uses GHC extensions and CPP, and has source files in three
- subdirectories A B and C, you might put the following lines in
+ subdirectories A, B and C, you might put the following lines in
.ghci:
@@ -1414,7 +2480,33 @@ Prelude> :set -fno-glasgow-exts
-
+
+ Compiling to object code inside GHCi
+
+ 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
+ flag either on the command line or
+ with :set (the 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.
+
+ Compiling to object code inside GHCi is particularly useful
+ if you are developing a compiled application, because the
+ :reload command typically runs much faster than
+ restarting GHC with from the command-line,
+ because all the interface files are already cached in
+ memory.
+
+ 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.
+
+
+ FAQ and Things To Watch Out For
@@ -1459,10 +2551,9 @@ Prelude> :set -fno-glasgow-exts
Concurrent threads don't carry on running when GHCi is
waiting for input.
- No, they don't. This is because the Haskell binding
- to the GNU readline library doesn't support reading from the
- terminal in a non-blocking way, which is required to work
- properly with GHC's concurrency model.
+ This should work, as long as your GHCi was built with
+ the switch, which is the default.
+ Consult whoever supplied your GHCi installation.
@@ -1489,6 +2580,13 @@ Prelude> :set -fno-glasgow-exts
+
+ I can't use Control-C to interrupt computations in
+ GHCi on Windows.
+
+ See .
+
+